fan-video-dl-build

命令

fan-video-dl 完整开发-发布-部署教程

补充说明

本教程介绍 fan-video-dl 从源码提交、打 tag 触发 GitHub Actions 发布流水线到目标服务器一键安装、卸载、升级的完整流程，适用于个人视频下载工具自建发布链路。

项目：fan-video-dl｜Web 视频下载工具（基于 yt-dlp）仓库：https://github.com/meimolihan/fan-video-dl 编译发布主机：fnOS（Debian，git/gh/curl 环境齐全）部署目标主机：Debian Linux（amd64/arm64）

重要规则

GitHub 不允许直接覆盖已发布 Release，正式环境版本号单向递增；内测可删除重建同名 tag。

不在本地编译任何二进制：发布全部由 GitHub Actions 的 release.yml 流水线完成，本地只更新版本号、写发版备注、打 tag 推送。

install.sh 不依赖 GitHub Release 附件（源码经 main 分支或源码压缩包拉取），脚本无需硬编码版本号。

Docker 镜像构建于流水线（Docker Hub + GHCR 双推），systemd 直接安装运行时为 Python venv + gunicorn。

一、编译发布机（fnOS）环境准备

1.1 安装依赖

apt update
apt install git curl

Python3（本机 python3 --version 需 >= 3.9），ffmpeg（视频合并/转码必需）。GitHub Actions 侧负责镜像构建，本机无需 Docker。

1.2 安装 gh 命令行工具并授权 GitHub

gh auth login

选择 GitHub.com → SSH → 网页授权登录，务必勾选 repo 权限。

校验授权结果

gh auth status

输出必须包含：Token scopes: admin:public_key, gist, read:org, repo

1.3 拉取源码

git clone git@github.com:meimolihan/fan-video-dl.git
cd fan-video-dl

项目目录结构

fan-video-dl/
├── app.py                     # Flask 后端（含浏览器可播放性转码 ensure_browser_playable）
├── cli.py                     # 内置 CLI 命令（status/credentials/start|stop|restart/uninstall/version/help）
├── douyin_downloader.py       # 抖音无水印下载器
├── templates/index.html       # 前端页面（原生 HTML/JS）
├── Dockerfile                 # 编译机流水线构建用
├── docker-compose.yml         # 生产 Compose 部署样例
├── requirements.txt           # Python 依赖
├── version.txt                # 版本号文件（build-and-push.sh 自动写入）
├── scripts/
│   ├── install.sh             # 远程一键安装脚本
│   ├── uninstall.sh           # 卸载脚本
│   ├── fan-video-dl_backup.sh # 备份脚本
│   ├── fan-video-dl_recover.sh# 恢复脚本
│   └── build-and-push.sh      # 发版脚本（打 tag 触发流水线）
└── .github/workflows/release.yml  # 发布流水线

二、配置一键安装脚本

确认 scripts/install.sh 头部常量（无需改动，默认已正确定义）：

APP_NAME="fan-video-dl"
DEFAULT_PORT=5200
APP_DIR="/var/lib/fan-video-dl"

提交推送至 main 分支

git add scripts/install.sh
git commit -m "chore: update install script"
git push origin main

三、构建与发布

3.1 一键发布（推荐）

./scripts/build-and-push.sh v1.1.9 --yes -m "本次更新：xxx"

内部流程：校验版本号（形如 v1.1.9）→ 自动清理同名 Release/tag（内测重建用）→ version.txt 写入版本号 → 生成 RELEASE_NOTES.md → git commit + git tag v1.1.9 → git push origin main + git push origin v1.1.9 → 轮询展示 GitHub Actions 流水线运行信息。

3.2 触发流水线后自动完成（GitHub Actions）

推送 tag v* 后由 .github/workflows/release.yml 自动执行：

构建并推送 Docker 镜像：mobufan/fan-video-dl（Docker Hub）+ ghcr.io/meimolihan/fan-video-dl（GHCR），latest 与 v1.1.9 双 tag，amd64/arm64 multi-arch
创建 GitHub Release：附带 RELEASE_NOTES.md
同步到 CNB 镜像仓库（失败不影响整体结果，continue-on-error: true）

3.3 手动触发（可选）

仓库 Actions → 选择 Release Pipeline → Run workflow（需指定版本号）。

校验 Release

访问：https://github.com/meimolihan/fan-video-dl/releases/tag/v1.1.9

状态：Published，不是 Draft 草稿
Actions 中对应 run 全部成功（CNB 步骤失败除外）
镜像可拉取验证：

docker pull mobufan/fan-video-dl:v1.1.9
docker pull ghcr.io/meimolihan/fan-video-dl:v1.1.9

四、目标服务器远程一键安装

目标服务器需要 root 权限，已安装 curl。

4.1 预检查国内网络

curl -sSL https://raw.githubusercontent.com/meimolihan/fan-video-dl/main/scripts/install.sh

输出 shell 脚本内容 = 网络正常；卡住超时需要网络代理（可用 FAN_VIDEO_DL_REPO 镜像仓库）。

4.2 执行一键安装

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-video-dl/main/scripts/install.sh)"

交互步骤：

请输入监听端口 [默认: 5200]: 回车使用默认，或填写自定义端口
请输入数据目录 [默认: /var/lib/fan-video-dl/data]: 回车使用默认路径
脚本自动检查 Python3/venv/ffmpeg（缺失自动安装）、拉取源码或从 GitHub 下载源码压缩包、创建 venv 安装依赖、写入 /etc/fan-video-dl.conf、安装内置 CLI、创建 systemd 服务并启动
输出 Web 访问地址、账号 admin、密码 admin888、数据目录与程序目录

静默安装

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-video-dl/main/scripts/install.sh)" -p 5200 -d /var/lib/fan-video-dl -y

部署后运维命令

systemctl status fan-video-dl
journalctl -u fan-video-dl -f
systemctl restart fan-video-dl
fan-video-dl status
fan-video-dl credentials
fan-video-dl version

访问示例：http://10.10.10.251:5200

账号：admin
密码：admin888（登录后必须修改密码，改密后初始密码不再显示）

五、一键卸载

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-video-dl/main/scripts/uninstall.sh)" -y

--purge 同时删除数据目录（含下载文件）；默认保留数据目录。

六、新版本发布模式

模式 1：递增新版本（正式环境，推荐）

不要复用旧 tag，版本号向上迭代，例如 v1.1.9 → v1.2.0

cd /vol1/1000/GitHub/fan-video-dl
./scripts/build-and-push.sh v1.2.0 --yes -m "本次更新说明"

目标服务器升级，直接重跑安装脚本，自动拉取最新源码，覆盖程序，systemd 自动重启，数据保留：

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-video-dl/main/scripts/install.sh)" -y
fan-video-dl version

Docker 部署升级：

docker pull mobufan/fan-video-dl:latest
docker compose up -d

模式 2：删除重建同名 Release（仅限内测，无线上用户）

⚠️ 已有服务器依赖该版本绝对禁止执行；build-and-push.sh 已内置自动清理，也可手动执行。

cd /vol1/1000/GitHub/fan-video-dl
# 删除github release 并清理本地与远端tag
gh release delete v1.1.9 --yes --cleanup-tag
git tag -d v1.1.9
git push origin --delete v1.1.9

# 重新打 tag 触发流水线重建
./scripts/build-and-push.sh v1.1.9 --yes -m "内测重建"

七、故障排查表

现象	排查方案
gh release create 返回 401 Unauthorized	执行 `gh auth login` 重新授权，确保 token 具备 repo 权限
Actions 流水线失败	`gh run view <run_id> --log-failed` 查看失败日志
CNB 同步失败	属已知项，`continue-on-error` 不影响整体结果，可忽略
raw.githubusercontent.com 卡住超时	国内网络限制，配置代理，或使用 `FAN_VIDEO_DL_REPO` 镜像仓库
服务启动失败	`journalctl -u fan-video-dl -n 100` 查看日志；检查端口占用、目录权限
安装脚本获取源码失败	确认 git 可用，或 `-s` 指定本地源码目录（含 app.py 与 requirements.txt）
镜像拉取 404	检查 Release tag 是否已生成、流水线 Docker build 是否成功

八、前端/后端修改流程

fan-video-dl 前端为 templates/index.html（原生 HTML/JS），后端为 app.py（Flask）：

修改 app.py / templates/index.html 等源码
本地测试：pip install -r requirements.txt && python app.py，浏览器访问 http://127.0.0.1:5200
提交代码：git add . && git commit -m "xxx" && git push origin main
走发布流程：./scripts/build-and-push.sh vX.Y.Z --yes -m "备注"
目标服务器重跑一键安装脚本升级生效（Docker 部署 docker pull + docker compose up -d）。

九、极简速查复制块

发布新版本速记

cd /vol1/1000/GitHub/fan-video-dl
./scripts/build-and-push.sh v1.1.9 --yes -m "本次更新说明"
# 或分步：
# echo 'v1.1.9' > version.txt
# git add . && git commit -m "chore: bump version to 1.1.9"
# git push origin main && git tag v1.1.9 && git push origin v1.1.9
gh run list --workflow=release.yml --branch v1.1.9
gh release view v1.1.9

Docker 快速部署

docker run -d --name fan-video-dl --restart unless-stopped -p 5200:5200 \
  -e PORT=5200 -e AUTH_USERNAME=admin -e AUTH_PASSWORD=admin888 \
  -v ./data:/app/data -v ./downloads:/app/downloads \
  --tmpfs /tmp:size=2G mobufan/fan-video-dl:latest