fan-reubah-build

补充说明

本教程介绍 fan-reubah 从源码编译、发布 GitHub Release 到目标服务器一键安装、卸载、升级的完整流程，适用于个人设备本地文件转换/图像处理工具自建发布链路。

项目：fan-reubah｜通用文件转换与图像处理 仓库：https://github.com/meimolihan/fan-reubah 编译发布主机：fnOS（Debian，仅需 gh/git；本地编译验证另需 Go/Node/gcc/Rust） 部署测试主机：Debian Linux（amd64/arm64）

重要规则

1. GitHub 不允许直接覆盖已发布 Release，正式环境版本号单向递增；内测可删除重建同名 tag（build-and-push.sh 已内置自动清理）。
2. install.sh 使用 releases/latest/download，脚本不需要硬编码版本号。
3. 编译机器 ≠ 业务运行机器；fnOS 只负责触发发布流水线，实际编译在 GitHub Actions 完成，业务跑在目标主机。
4. fan-reubah 依赖 CGO（libwebp/libheif），CI 交叉编译使用 CGO_ENABLED=1；无这些库时可用 CGO_ENABLED=0 构建（部分功能受限）。

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

1.1 安装依赖

apt update
apt install git curl build-essential pkg-config libwebp-dev libheif-dev libde265-dev libx265-dev

Go（本机 /usr/local/go/bin/go，首次使用需 export PATH=$PATH:/usr/local/go/bin）、Node.js 18+、Make。如需编译 vtracer 还需安装 Rust（curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh）。

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

项目目录结构

fan-reubah/
├── scripts/install.sh            # 远程一键安装脚本
├── scripts/uninstall.sh          # 卸载脚本
├── scripts/build-and-push.sh     # 升版+打tag+推送+触发CI发布脚本
├── scripts/prepare-embed.sh      # 生成 go:embed 内嵌资源（前端+vtracer，本地构建用）
├── cmd/server/                   # 后端入口（编译为单个自包含二进制）
├── internal/                     # 业务逻辑包 + assets（内嵌 web/engine）
├── templates/                    # 前端（HTML + TailwindCSS + esbuild，npm run build 生成 CSS/JS 到 static/）
├── static/                       # 前端构建产物（css/js），内嵌进二进制
├── vtracer/                      # Rust vendored SVG 矢量化引擎源码
├── .github/workflows/release.yml # 发布流水线（workflow_dispatch 触发）
└── bin/                          # 编译产物（CI/构建后生成）

二、配置一键安装脚本

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

APP_NAME="fan-reubah"
DEFAULT_PORT=8081
DEFAULT_APP_DIR="/var/lib/fan-reubah"
BIN_PATH="/usr/local/bin/fan-reubah"
RECORD_FILE="/etc/fan-reubah.conf"

提交推送至 main 分支

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

三、构建与发布

3.1 一键发布（推荐）

cd /vol1/1000/GitHub/fan-reubah
bash scripts/build-and-push.sh v1.0.0 --yes -m "本次发布的说明文字"

build-and-push.sh 本身不在本地编译，只负责升版并触发 CI：

1. 校验 tag 格式（vX.Y.Z）
2. 清理已存在的同名 Release 与本地/远端 tag（内测场景）
3. 更新 templates/package.json 版本号，写入 RELEASE_NOTES.md
4. git commit + git push origin main，再 git tag + git push origin vX.Y.Z
5. gh workflow run release.yml -f tag=vX.Y.Z --ref vX.Y.Z 触发发布流水线

随后 .github/workflows/release.yml 链式作业自动完成：

• build-binaries：Node 构建前端 → cargo 编译 vtracer（amd64/arm64）→ CGO_ENABLED=1 交叉编译 Go → 两个自包含单文件
• publish-release：下载产物并 gh release create 上传 fan-reubah_linux_amd64、fan-reubah_linux_arm64
• build-docker：buildx 构建并推送 multi-arch 镜像（Docker Hub + GHCR）
• sync-cnb：同步 Git 仓库与标签到 CNB

3.2 产物说明

3.3 校验 Release

访问：https://github.com/meimolihan/fan-reubah/releases/tag/v1.0.0

1. 状态：Published，不是 Draft 草稿
2. Assets 内必须存在 fan-reubah_linux_amd64 和 fan-reubah_linux_arm64。

测试下载链接有效性

curl -I https://github.com/meimolihan/fan-reubah/releases/latest/download/fan-reubah_linux_amd64
curl -I https://github.com/meimolihan/fan-reubah/releases/latest/download/fan-reubah_linux_arm64

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

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

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

4.1 预检查国内网络

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

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

4.2 执行一键安装

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

交互步骤：

1. 请输入监听端口 [默认: 8081]: 回车使用默认，或填写自定义端口
2. 请输入应用部署目录 [默认: /var/lib/fan-reubah]: 回车使用默认路径
3. 脚本自动从 Release 下载自包含单文件二进制（或使用本地构建产物）、安装二进制、创建 systemd 服务、启动程序
4. 输出 Listening on [::]:端口，可直接通过 http://<IP>:端口 访问

静默安装

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

部署后运维命令

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

五、一键卸载

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

卸载完成：systemd 服务移除、二进制删除、应用目录（默认 /var/lib/fan-reubah）删除。

六、新版本发布两种模式

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

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

cd /vol1/1000/GitHub/fan-reubah
bash scripts/build-and-push.sh v1.0.1 --yes

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

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

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

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

cd /vol1/1000/GitHub/fan-reubah
# 删除github release
gh release delete v1.0.0 -y --cleanup-tag
# 重新运行构建发布脚本（自动清理tag、重新编译、重新创建Release）
bash scripts/build-and-push.sh v1.0.0 --yes

七、故障排查表

八、前端 UI 修改流程

前端位于 templates/（HTML + TailwindCSS），构建由 esbuild 完成，产物输出到 static/css、static/js，最终内嵌进自包含单文件二进制：

1. 修改 templates/ 前端代码
2. 本地构建验证：cd templates && npm run build
3. 重新走发布流程：bash scripts/build-and-push.sh v1.0.1 --yes
4. 目标服务器重跑一键安装脚本升级生效。

九、极简速查复制块

发布新版本速记

cd /vol1/1000/GitHub/fan-reubah
bash scripts/build-and-push.sh v1.0.1 --yes

远程一键安装

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

远程一键卸载

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

准备内嵌资源（本地构建可选）

cd /vol1/1000/GitHub/fan-reubah
bash scripts/prepare-embed.sh

相关命令

• fan-reubah-build 👈 当前所在位置
• fan-reubah
• fan-reubah_menu
• dc_inst_fan-reubah
• opencode_menu