fan-video-build

补充说明

本教程介绍 fan-video 从源码编译、发布 GitHub Release 到目标服务器一键安装、卸载、升级的完整流程，适用于个人设备本地大屏影视库自建发布链路。

项目：fan-video｜本地视频媒体服务器 仓库：https://github.com/meimolihan/fan-video 编译发布主机：fnOS（Debian，本机 Go/Node/make/ffmpeg 环境齐全） 部署测试主机：Debian Linux（amd64/arm64）

重要规则

1. GitHub 不允许直接覆盖已发布 Release，正式环境版本号单向递增；内测可删除重建同名 tag。
2. install.sh 使用 releases/latest/download，脚本不需要硬编码版本号。
3. 编译机器 ≠ 业务运行机器；fnOS 只做编译发布，业务跑在目标主机。
4. 正式二进制默认 CGO_ENABLED=1（内嵌 ffmpeg/QSV 硬件加速）；跨机静态二进制使用 CGO_ENABLED=0 构建。

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

1.1 安装依赖

apt update
apt install git curl build-essential

Go（本机 /usr/local/go/bin/go，确保 go version 正常），Node.js 18+，Make。ffmpeg 相关静态库需齐全（QSV 硬件加速需要 Intel Media SDK / oneVPL）。

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.git
cd fan-video
go mod download

项目目录结构

fan-video/
├── scripts/install.sh            # 远程一键安装脚本
├── scripts/uninstall.sh          # 卸载脚本
├── scripts/fan-video_backup.sh   # 备份脚本
├── scripts/fan-video_recover.sh  # 恢复脚本
├── scripts/build-and-push.sh     # 构建+打tag+推送脚本
├── bump-version.sh               # 版本号自增脚本
├── web/                          # 前端（React + Vite）
└── cmd/server-lite/              # 后端正式入口（内嵌 PWA 前端）

二、配置一键安装脚本

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

APP_NAME="fan-video"
DEFAULT_PORT=8080
DEFAULT_DATA_DIR="/var/lib/fan-video"

提交推送至 main 分支

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

三、构建与发布

3.1 构建正式二进制

make build-server        # 先 sync-pwa，再 CGO_ENABLED=1 构建 cmd/server-lite → bin/fan-video

构建 Web 前端（修改过 web/ 时）

make build-web

3.2 一键发布（推荐）

./scripts/build-and-push.sh 1.2.3 --yes

内部流程：校验版本号 → bump-version.sh 升版 → make build → git commit + git tag v1.2.3 → git push origin main + git push origin v1.2.3。

3.3 交叉编译 Release 静态二进制（供 install.sh 远程下载）

export VERSION=1.2.3
rm -rf dist && mkdir -p dist
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags "-s -w -X github.com/fan-video/fan-video/internal/version.Version=${VERSION}" -o dist/fan-video_linux_amd64 ./cmd/server-lite
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags "-s -w -X github.com/fan-video/fan-video/internal/version.Version=${VERSION}" -o dist/fan-video_linux_arm64 ./cmd/server-lite
ls dist

静态二进制不含 ffmpeg/QSV 加速，功能完整（软件解码/首帧提取可回退）；正式设备建议用本机 CGO_ENABLED=1 构建产物部署。

3.4 创建 GitHub Release 并上传二进制

VERSION=1.2.3
gh release create "v${VERSION}" \
  dist/fan-video_linux_amd64 \
  dist/fan-video_linux_arm64 \
  --title "v${VERSION}" \
  --notes "fan-video - Local Video Media Server"

校验 Release

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

1. 状态：Published，不是 Draft 草稿
2. Assets 内必须存在两个编译二进制，不要只看源码 zip/tar.gz。

测试下载链接有效性

curl -I https://github.com/meimolihan/fan-video/releases/latest/download/fan-video_linux_amd64

返回 302 Found 正常；返回 404 代表附件缺失。

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

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

4.1 预检查国内网络

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

输出 shell 脚本内容 = 网络正常；卡住超时需要网络代理。

4.2 执行一键安装

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

交互步骤：

1. Enter listen port [default: 8080]: 回车使用默认，或填写自定义端口
2. Enter data directory [default: /var/lib/fan-video]: 回车使用默认路径
3. 脚本自动下载二进制（或使用本地 -b 产物）、创建 systemd 服务、启动程序
4. 输出 Web 访问地址；首次登录默认密码见启动日志，登录页同步展示，改密后清除

静默安装

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

部署后运维命令

systemctl status fan-video
journalctl -u fan-video -f
systemctl restart fan-video
/usr/local/bin/fan-video -version

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

• 账号：admin
• 密码：首次启动日志输出，登录后必须修改密码

五、一键卸载

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

交互：

• Remove data directory /var/lib/fan-video ? [y/N]:

卸载完成：systemd 服务移除、二进制文件删除。

六、新版本发布两种模式

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

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

cd /vol1/1000/compose/opencode/workspace/fan-video
./scripts/build-and-push.sh 1.2.4 --yes

目标服务器升级，直接重跑安装脚本，自动拉取 latest，覆盖二进制，systemd 自动重启

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

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

⚠️ 已有服务器依赖该版本绝对禁止执行，会造成旧版本下载 404。

cd /vol1/1000/compose/opencode/workspace/fan-video
# 删除github release
gh release delete v1.2.3 --yes
# 删除本地与远端git tag
git tag -d v1.2.3
git push origin --delete v1.2.3

# 重新编译并重建release上传附件
export VERSION=1.2.3
rm -rf dist && mkdir -p dist
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags "-s -w -X github.com/fan-video/fan-video/internal/version.Version=${VERSION}" -o dist/fan-video_linux_amd64 ./cmd/server-lite
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags "-s -w -X github.com/fan-video/fan-video/internal/version.Version=${VERSION}" -o dist/fan-video_linux_arm64 ./cmd/server-lite

gh release create "v${VERSION}" \
  dist/fan-video_linux_amd64 \
  dist/fan-video_linux_arm64 \
  --title "v${VERSION}" \
  --notes "fan-video - Local Video Media Server"

七、故障排查表

八、前端 UI 修改流程

前端为 React + Vite（web/），构建产物内嵌进后端二进制（internal/pwa + go:embed）：

1. 修改 web/src/ 前端代码
2. 重新构建：make build-web && make build-server
3. 重新走发布流程：提交代码 → 构建 → 创建 Release
4. 目标服务器重跑一键安装脚本升级生效。

九、极简速查复制块

发布新版本速记

cd /vol1/1000/compose/opencode/workspace/fan-video
./scripts/build-and-push.sh 1.2.4 --yes    # 或分步：
# make build-server
# git add . && git commit -m "release v1.2.4"
# git push origin main && git push origin v1.2.4

export VERSION=1.2.4
rm -rf dist && mkdir -p dist
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags "-s -w -X github.com/fan-video/fan-video/internal/version.Version=${VERSION}" -o dist/fan-video_linux_amd64 ./cmd/server-lite
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags "-s -w -X github.com/fan-video/fan-video/internal/version.Version=${VERSION}" -o dist/fan-video_linux_arm64 ./cmd/server-lite
gh release create "v${VERSION}" dist/fan-video_linux_amd64 dist/fan-video_linux_arm64 --title "v${VERSION}" --notes "更新说明"