fan-video-ct-build

补充说明

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

项目：fan-video-ct｜本地视频剪切工具（基于 FFmpeg，仅本地处理不外传） 仓库：https://github.com/meimolihan/fan-video-ct 编译发布主机：fnOS（Debian，本机 Go/make/ffmpeg 环境齐全） 部署测试主机：Debian Linux（amd64/arm64）

重要规则

1. GitHub 不允许直接覆盖已发布 Release，正式环境版本号单向递增；内测可删除重建同名 tag。
2. install.sh 使用 releases/latest/download，脚本不需要硬编码版本号。
3. 编译机器 ≠ 业务运行机器；fnOS 只做编译发布，业务跑在目标主机。
4. 前端为原生 HTML/CSS/JS（internal/embedded/web），已通过 go:embed 内嵌二进制，无 Node/React 构建步骤。

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

1.1 安装依赖

apt update
apt install git curl build-essential

Go（本机 /usr/local/go/bin/go，确保 go version 正常），Make。

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

项目目录结构

fan-video-ct/
├── scripts/install.sh            # 远程一键安装脚本
├── scripts/uninstall.sh          # 卸载脚本
├── scripts/build-and-push.sh     # 升版+打tag+推代码+触发发布流水线
├── scripts/build-release.sh      # 本地交叉编译 dist/（amd64+arm64+sha256）
├── internal/version/version.go   # 版本号（唯一来源）
├── internal/embedded/web/        # 前端（原生 HTML/CSS/JS，go:embed 内嵌）
├── internal/{config,ffmpeg,handler,service}/  # 后端
├── server.go                     # Web 服务入口
├── cli_ui.go                     # CLI 交互界面
├── Makefile                      # vet/build/test/release/install/docker
├── Dockerfile                    # 多阶段构建，运行镜像内置 ffmpeg
└── docker-compose.yml            # 本地一键 Compose 部署

二、配置一键安装脚本

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

APP_NAME="fan-video-ct"
DEFAULT_PORT=8788
DEFAULT_INSTALL_DIR="/var/lib/fan-video-ct"

提交推送至 main 分支

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

三、构建与发布

3.1 构建正式二进制

make vet          # 代码检查
make build        # 版本号自动从 internal/version/version.go 注入 ldflags
make test         # 单元测试
make run          # 本地运行（-data ./data -port 8788）

构建产物：bin/fan-video-ct。

3.2 一键发布（推荐）

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

内部流程：校验版本号 → 更新 internal/version/version.go → 写入 RELEASE_NOTES.md → git commit + 打 tag v1.2.3 → git push origin main + git push origin v1.2.3 → gh workflow run release.yml -f tag=v1.2.3 --ref v1.2.3。

3.3 Release 流水线（GitHub Actions）

release.yml（仅 workflow_dispatch 触发，日常 push 不触发）按顺序执行：

1. build-binaries：GitHub Actions 构建 fan-video-ct_linux_amd64 / fan-video-ct_linux_arm64 + sha256sums.txt
2. publish-release：创建 GitHub Release 并上传上述附件（版本跟随 internal/version/version.go）
3. build-docker：构建并推送 multi-arch 镜像到 Docker Hub mobufan/fan-video-ct + GHCR ghcr.io/meimolihan/fan-video-ct
4. sync-cnb：同步镜像到 CNB（continue-on-error: true，失败不阻塞）

3.4 交叉编译 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/meimolihan/fan-video-ct/internal/version.Version=${VERSION}" -o dist/fan-video-ct_linux_amd64 .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags "-s -w -X github.com/meimolihan/fan-video-ct/internal/version.Version=${VERSION}" -o dist/fan-video-ct_linux_arm64 .
ls dist

3.5 创建 GitHub Release 并上传二进制（离线模式）

VERSION=1.2.3
gh release create "v${VERSION}" \
  dist/fan-video-ct_linux_amd64 \
  dist/fan-video-ct_linux_arm64 \
  --title "v${VERSION}" \
  --notes "fan-video-ct - Local Video Cutting Tool"

校验 Release

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

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

测试下载链接有效性

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

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

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

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

4.1 预检查国内网络

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

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

4.2 执行一键安装

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

交互步骤：

1. 请输入监听端口 [默认: 8788]: 回车使用默认，或填写自定义端口
2. 请输入安装目录 [默认: /var/lib/fan-video-ct]: 回车使用默认路径
3. 请输入视频浏览根目录 [可选，留空浏览全盘]: 可指定媒体目录（如 /vol2/1000/downloads/fan-video-ct）
4. 脚本自动下载二进制（或使用本地 -b 产物）、创建 systemd 服务（--port --data [--media]）、写入安装记录 /etc/fan-video-ct.conf、启动程序
5. 输出 Web 访问地址；无账号密码（内网工具）

静默安装

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

部署后运维命令

systemctl status fan-video-ct
journalctl -u fan-video-ct -f
systemctl restart fan-video-ct
/var/lib/fan-video-ct/fan-video-ct --version

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

五、一键卸载

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

交互：

• 是否清除数据目录 /var/lib/fan-video-ct/data ? 默认保留，-y --purge 可一并清除（不可恢复）

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

六、新版本发布两种模式

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

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

cd /vol1/1000/GitHub/fan-video-ct
./scripts/build-and-push.sh 1.2.4 --yes

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

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

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

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

cd /vol1/1000/GitHub/fan-video-ct
# 删除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/meimolihan/fan-video-ct/internal/version.Version=${VERSION}" -o dist/fan-video-ct_linux_amd64 .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags "-s -w -X github.com/meimolihan/fan-video-ct/internal/version.Version=${VERSION}" -o dist/fan-video-ct_linux_arm64 .

gh release create "v${VERSION}" \
  dist/fan-video-ct_linux_amd64 \
  dist/fan-video-ct_linux_arm64 \
  --title "v${VERSION}" \
  --notes "fan-video-ct - Local Video Cutting Tool"

七、故障排查表

八、前端 UI 修改流程

前端为原生 HTML/CSS/JS（internal/embedded/web/），无 Node 构建，修改后直接重新编译内嵌即可：

1. 修改 internal/embedded/web/ 下的 index.html / css/style.css / js/app.js
2. 重新构建：make build
3. 重新走发布流程：./scripts/build-and-push.sh 1.2.5 --yes 触发流水线
4. 目标服务器重跑一键安装脚本升级生效（或本地 make install）

九、极简速查复制块

发布新版本速记

cd /vol1/1000/GitHub/fan-video-ct
./scripts/build-and-push.sh 1.2.4 --yes    # 自动：升版 version.go → commit → push main → tag → 触发 release.yml

# 或分步（离线模式）：
# make build
# git add . && git commit -m "release v1.2.4"
# git push origin main && git push origin v1.2.4
# gh workflow run release.yml -f tag=v1.2.4 --ref 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/meimolihan/fan-video-ct/internal/version.Version=${VERSION}" -o dist/fan-video-ct_linux_amd64 .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags "-s -w -X github.com/meimolihan/fan-video-ct/internal/version.Version=${VERSION}" -o dist/fan-video-ct_linux_arm64 .
gh release create "v${VERSION}" dist/fan-video-ct_linux_amd64 dist/fan-video-ct_linux_arm64 --title "v${VERSION}" --notes "更新说明"