BtrFS Cleaner Web 是一个基于 Web 的 Btrfs 文件系统管理工具，提供：
- 📊 存储区概览（挂载点、容量、使用率）
- 🔧 手动数据清洗（Scrub）
- ⏰ 定时清洗计划（每日/每周/每月）
- 📜 清洗任务历史与实时进度（SSE 流式推送）
- 🔐 基于系统 PAM 用户认证
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux（Debian/Ubuntu, RHEL/CentOS/Rocky, Arch） |
| Python | ≥ 3.8 |
| 工具集 | btrfs-progs, sudo |
| 权限 | root 安装运行（读写 /opt/btrfs-cleaner、管理 systemd 服务） |
| 网络 | 默认监听 0.0.0.0:5100 |
# 把项目上传到目标机器，然后：
cd /path/to/btrfs-cleaner
chmod +x install.sh
sudo ./install.sh脚本会自动完成：安装系统依赖 → 创建 Python 虚拟环境 → 部署应用文件 → 配置 systemd 服务 → 配置 sudoers → 启动服务。
安装完成后访问：
http://<服务器IP>:5100
用系统本地用户（Linux 用户/密码）登录。
# 1. 安装系统依赖
# Debian/Ubuntu
apt update && apt install -y python3 python3-pip python3-venv python3-pam python3-psutil btrfs-progs sudo curl
# 2. 创建目录
mkdir -p /opt/btrfs-cleaner /var/log/btrfs-cleaner
# 3. 复制文件
cp app.py requirements.txt login.html main.html /opt/btrfs-cleaner/
chmod +x /opt/btrfs-cleaner/app.py
# 4. Python 虚拟环境
python3 -m venv /opt/btrfs-cleaner/venv
source /opt/btrfs-cleaner/venv/bin/activate
pip install -r /opt/btrfs-cleaner/requirements.txt
deactivate
# 5. 配置环境变量
cat > /opt/btrfs-cleaner/config.env << 'EOF'
BTRFS_CLEANER_PORT=5100
BTRFS_CLEANER_HOST=0.0.0.0
BTRFS_CLEANER_LOG_DIR=/var/log/btrfs-cleaner
EOF
# 6. 配置 sudoers（允许以 sudo 执行 btrfs 命令）
echo "btrfs-cleaner ALL=(ALL) NOPASSWD: /usr/sbin/btrfs, /usr/bin/btrfs, /sbin/btrfs, /bin/btrfs" > /etc/sudoers.d/btrfs-cleaner
chmod 440 /etc/sudoers.d/btrfs-cleaner
# 7. 配置 systemd 服务
cat > /etc/systemd/system/btrfs-cleaner.service << 'SERVICE'
[Unit]
Description=BtrFS Cleaner Web UI
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=root
ExecStart=/opt/btrfs-cleaner/venv/bin/python /opt/btrfs-cleaner/app.py
EnvironmentFile=/opt/btrfs-cleaner/config.env
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
SERVICE
# 8. 启动
systemctl daemon-reload
systemctl enable --now btrfs-cleaner
# 9. 防火墙放行
ufw allow 5100/tcp
# 或 firewalld: firewall-cmd --add-port=5100/tcp --permanent && firewall-cmd --reload应用启动时会自动检测系统是否支持 IPv6：
- 支持 IPv6 → 绑定
[::]:5100（双栈，同时监听 IPv4 和 IPv6 连接） - 不支持 IPv6 → 绑定
0.0.0.0:5100（仅 IPv4）
无需任何额外配置。如果用 IPv6 地址访问：
http://[::1]:5100 # 本机 IPv6
http://[240e:...]:5100 # 公网/内网 IPv6 地址
⚠️ 注意：hostname -I通常只返回 IPv4 地址，安装脚本输出中的访问链接仅提示 IPv4。如需 IPv6 访问，请替换为实际的 IPv6 地址。
如绑定了 [::] 但仍需限制为仅 IPv4，可将 config.env 中的 BTRFS_CLEANER_HOST 改为 127.0.0.1 或特定内网 IPv4 地址。
# 查看运行状态
systemctl status btrfs-cleaner
# 查看实时日志
journalctl -u btrfs-cleaner -f
# 重启
systemctl restart btrfs-cleaner
# 停止
systemctl stop btrfs-cleaner
# 开机自启（安装时已启用）
systemctl enable btrfs-cleaner
# 禁止开机自启
systemctl disable btrfs-cleaner| 环境变量 | 默认值 | 说明 |
|---|---|---|
APP_PORT |
5100 |
Web 端口（安装时通过环境变量设置） |
BTRFS_CLEANER_PORT |
5100 |
Web 端口（运行时读取） |
BTRFS_CLEANER_HOST |
0.0.0.0 |
监听地址（0.0.0.0 仅 IPv4；实际启动时若检测到 IPv6 则自动改为 :: 双栈） |
BTRFS_CLEANER_LOG_DIR |
/var/log/btrfs-cleaner |
日志目录 |
端口可在安装时通过环境变量覆盖：
sudo APP_PORT=8080 ./install.sh也可安装后修改 /opt/btrfs-cleaner/config.env，然后重启服务：
systemctl restart btrfs-cleaner/opt/btrfs-cleaner/
├── app.py # Flask 应用主程序
├── requirements.txt # Python 依赖
├── login.html # 登录页面模板
├── main.html # 主面板模板
├── config.env # 运行环境配置
├── .secret # Flask session 密钥（自动生成）
└── venv/ # Python 虚拟环境
/var/log/btrfs-cleaner/
├── app.log # 应用日志
# 停止并禁用服务
systemctl stop btrfs-cleaner
systemctl disable btrfs-cleaner
# 删除服务文件
rm -f /etc/systemd/system/btrfs-cleaner.service
systemctl daemon-reload
# 删除 sudoers 配置
rm -f /etc/sudoers.d/btrfs-cleaner
# 删除安装目录
rm -rf /opt/btrfs-cleaner
# 删除日志目录（可选）
rm -rf /var/log/btrfs-cleanerQ: 登录时提示 "Invalid username or password"？ → 使用服务器的本地系统用户登录，非 root 用户也可。确保 PAM 认证正常。
Q: 面板显示 "未检测到 btrfs 文件系统"？
→ 确认已挂载 btrfs 分区，且 sudo btrfs filesystem show 能正常输出。
Q: Scrub 任务一直卡在 "pending"？
→ 检查 sudo btrfs scrub status <mountpoint> 是否能正常执行，可能是 btrfs-progs 版本问题。
Q: 如何修改端口？
→ 修改 /opt/btrfs-cleaner/config.env 中的 BTRFS_CLEANER_PORT，然后 sudo systemctl restart btrfs-cleaner。
Q: 如何启用 HTTPS？ → 建议在前置代理（Nginx/Caddy）上配置 TLS，代理到后端 5100 端口。
Q: 安装脚本提示的 IP 不是 IPv6 地址？
→ 正常。hostname -I 只输出 IPv4 地址。应用实际会自动检测并绑定 IPv6 双栈，直接用 [IPv6地址]:5100 访问即可。