fan-image-tr

补充说明

本教程介绍 fan-image-tr 的部署、升级、卸载、备份、恢复与日常运维，适用于 NAS / 个人工作站上的私有图片批量处理台。

项目：fan-image-tr｜基于 FFmpeg 的图片批量处理 Web 工具 仓库：https://github.com/meimolihan/fan-image-tr 运行依赖：FFmpeg 8+（ffmpeg 与 ffprobe）；编译依赖：Go 1.25+

fan-image-tr 没有账号密码体系，浏览器打开即用。 对外暴露时请自行在前面加反向代理与鉴权。

安装与卸载

方式一：Docker Compose 部署（推荐）

# 一键脚本（拉源码 + 本地构建 + 启动）
bash <(curl -sL gitee.com/meimolihan/cmdbox/raw/master/sh/dc_inst_fan-image-tr.sh) 8791 /vol1/1000/compose/fan-image-tr

• 详见 dc_inst_fan-image-tr

方式二：使用仓库自带的 compose 文件

git clone --depth 1 https://github.com/meimolihan/fan-image-tr.git
cd fan-image-tr

# 启动前把 ./photos 换成你的图片库目录
docker compose up -d --build

# 指定端口与并发
FIT_PORT=8791 FIT_APP_WORKER=2 docker compose up -d --build

方式三：Release 二进制 + systemd 部署

# 1. 安装 FFmpeg（项目运行强依赖，内含 ffprobe）
apt update && apt install -y ffmpeg      # dnf / yum / apk 同理

# 2. 创建服务账号与目录
sudo useradd -r -s /sbin/nologin -d /var/lib/fan-image-tr fit
sudo mkdir -p /var/lib/fan-image-tr /srv/photos

# 3. 下载二进制（按架构二选一，release 里还有 darwin / windows 产物）
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
sudo curl -fsSL -o /usr/local/bin/fan-image-tr \
  "https://github.com/meimolihan/fan-image-tr/releases/latest/download/fan-image-tr-linux-${ARCH}"
sudo chmod +x /usr/local/bin/fan-image-tr
fan-image-tr version

# 4. 写入 systemd 单元
sudo cp scripts/fan-image-tr.service /etc/systemd/system/
# 按需修改 unit 里的 FIT_APP_PORT / FIT_APP_MEDIA_DIR / User / ReadWritePaths
sudo systemctl daemon-reload
sudo systemctl enable --now fan-image-tr

• 静默安装 / 升级（等同于重跑上面的二进制替换 + systemctl restart）

sudo systemctl stop fan-image-tr
sudo curl -fsSL -o /usr/local/bin/fan-image-tr "https://github.com/meimolihan/fan-image-tr/releases/latest/download/fan-image-tr-linux-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
sudo chmod +x /usr/local/bin/fan-image-tr
sudo systemctl start fan-image-tr

卸载命令

# systemd 方式
sudo systemctl disable --now fan-image-tr
sudo rm -f /etc/systemd/system/fan-image-tr.service /usr/local/bin/fan-image-tr
sudo systemctl daemon-reload && sudo systemctl reset-failed fan-image-tr
sudo rm -rf /var/lib/fan-image-tr          # 可选：删数据目录

• Docker 方式

cd /vol1/1000/compose/fan-image-tr && docker-compose down --rmi all && rm -rf /vol1/1000/compose/fan-image-tr

• 菜单内一键安装 / 卸载

bash <(curl -sL gitee.com/meimolihan/cmdbox/raw/master/sh/fan-image-tr_menu.sh)
# 菜单内选 66 安装/升级、99 卸载

备份与恢复

数据目录（默认 /var/lib/fan-image-tr）内含 tasks.json 任务快照、profiles.json 自定义预设、uploads/ 上传文件与 output/ 转换产物，打包备份即可。

备份数据

sudo tar -czf "/vol2/1000/file/backup/fan-image-tr-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C "$(dirname /var/lib/fan-image-tr)" "$(basename /var/lib/fan-image-tr)"

• 将备份脚本添加到系统定时任务

# 1.（推荐）直接用菜单内选项 77 备份；也可以按下面的方式落地为独立脚本
cat > /usr/local/bin/fan-image-tr_backup << 'EOF'
#!/bin/bash
set -uo pipefail
DATA_DIR="/var/lib/fan-image-tr"
BACKUP_DIR="${1:-/vol2/1000/file/backup/fan-image-tr-backup}"
KEEP="${2:-6}"
[ -d "$DATA_DIR" ] || { echo "数据目录不存在: $DATA_DIR"; exit 1; }
mkdir -p "$BACKUP_DIR"
ts=$(date +%Y%m%d-%H%M%S)
tar -czf "$BACKUP_DIR/fan-image-tr-${ts}.tar.gz" -C "$(dirname "$DATA_DIR")" "$(basename "$DATA_DIR")" || exit 1
ls -1t "$BACKUP_DIR"/fan-image-tr-*.tar.gz 2>/dev/null | tail -n +$((KEEP + 1)) | xargs -r rm -f
echo "备份完成: $BACKUP_DIR/fan-image-tr-${ts}.tar.gz"
EOF

# 2.增加执行权限
chmod +x /usr/local/bin/fan-image-tr_backup

# 3.测试运行一次（目录/保留份数：/vol2/1000/file/backup/fan-image-tr-backup 保留6份）
fan-image-tr_backup /vol2/1000/file/backup/fan-image-tr-backup 6

# 4.追加 crontab(root)：每日凌晨2点30分执行，防重复追加
(crontab -l 2>/dev/null | grep -Fq '/usr/local/bin/fan-image-tr_backup /vol2/1000/file/backup/fan-image-tr-backup 6') || (crontab -l 2>/dev/null; echo '30 2 * * * /usr/local/bin/fan-image-tr_backup /vol2/1000/file/backup/fan-image-tr-backup 6 >> /var/log/fan-image-tr_backup.log 2>&1') | crontab -

# 5.验证定时任务是否写入成功
crontab -l

恢复数据

• 恢复 /vol2/1000/file/backup/fan-image-tr-backup 目录最新的备份

sudo systemctl stop fan-image-tr
sudo mv /var/lib/fan-image-tr "/var/lib/fan-image-tr.bak.$(date +%Y%m%d-%H%M%S)"
sudo tar -xzf "$(ls -1t /vol2/1000/file/backup/fan-image-tr-backup/fan-image-tr-*.tar.gz | head -1)" -C /var/lib
sudo chown -R fit:fit /var/lib/fan-image-tr
sudo systemctl start fan-image-tr

• 或使用菜单内选项 88 恢复（交互确认，失败自动回滚）

脚本命令

日常管理命令

配置参数

优先级：命令行参数 > 环境变量（FIT_ 前缀） > 配置文件 > 默认值

配置文件 config.yaml 按 ./ → ./data → /etc/fan-image-tr 顺序查找。

浏览根目录、数据目录、上传目录、输出目录都允许被 API 访问；其余路径一律拒绝（ErrPathNotAllowed / HTTP 403）。

HTTP API 速查

提交任务示例（variants 一次生成缩略图 / 列表图 / 大图）：

curl -X POST http://127.0.0.1:8791/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": ["IMG_0001.jpg", "IMG_0002.png"],
    "output_dir": "output",
    "options": {"format": "webp", "quality": 82, "resize": "long_edge", "size": 1920, "adapt": "fit", "strip_metadata": true},
    "variants": [
      {"name": "thumb", "resize": "long_edge", "size": 320},
      {"name": "list",  "resize": "long_edge", "size": 640, "quality": 75}
    ]
  }'

状态码约定：400 参数非法 / 403 路径越界 / 404 任务或文件不存在 / 409 任务状态不允许该操作 / 503 FFmpeg 探测失败或能力不可用。

数据目录说明

• 默认数据目录：/var/lib/fan-image-tr（systemd）/ ./data（二进制直跑）
• 目录内容：tasks.json 任务快照（重启后未完成任务回到队列）、profiles.json 自定义预设（内置预设不可改）、uploads/ 上传文件、output/ 转换产物
• 版本号注入：internal/version.Version（编译期 ldflags），也可用 FIT_VERSION 覆盖
• 浏览根目录、数据目录、上传目录、输出目录允许被 API 访问，其余路径一律 403
• 硬件加速：/api/capabilities 里的 hw_formats 是逐个格式实际编码一张测试图得出的结果；QSV 的 JPEG 在 yuvj* 像素格式下会自动补 -color_range pc，避免白底发灰