fan-panel-build

补充说明

本教程介绍 fan-panel 从源码开发、触发 GitHub Actions 自动构建、发布 GitHub Release/Docker 镜像，到目标服务器一键安装、卸载、升级的完整流程，适用于个人项目自建发布链路。

项目：fan-panel｜通用服务器管理面板（Vue 3 + Vite 前端 / Go 后端） 仓库：https://github.com/meimolihan/fan-panel Docker 镜像：mobufan/fan-panel（latest + 版本标签，Actions 自动构建 multi-arch） 发布方式：本地不编译，build-and-push.sh 仅更新版本号并推送 v* tag，由 GitHub Actions 自动完成编译与 Release/镜像

重要规则

1. GitHub 不允许直接覆盖已发布 Release，正式环境版本号单向递增；内测可删除重建同名 tag（build-and-push.sh 已内置自动清理）。
2. install.sh 使用 releases/latest/download，脚本不需要硬编码版本号；也支持 -v <tag> 指定历史版本。
3. 发布动作为：更新版本号 → 提交 → 推 tag → GitHub Actions 自动构建（release.yml 生成二进制+web资源包，build.yml 生成 Docker 镜像）。
4. 后端为 Go 1.21 静态编译（CGO_ENABLED=0），跨架构由 Actions 的 ubuntu runner 交叉编译 amd64/arm64，目标服务器无需额外依赖。

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

1.1 安装依赖

apt update
apt install git curl build-essential

前后端开发环境：

• Node.js 18+ 与 pnpm@8（前端 Vue 3 + Vite）
• Go 1.21（后端 service/，本机 /usr/local/go/bin/go，首次使用需 export PATH=$PATH:/usr/local/go/bin）

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-panel.git
cd fan-panel

项目目录结构

fan-panel/
├── scripts/install.sh            # 远程一键安装脚本
├── scripts/uninstall.sh          # 卸载脚本
├── scripts/backup.sh             # 备份脚本
├── scripts/restore.sh            # 恢复脚本
├── scripts/build-and-push.sh     # 版本号自增+打tag+推送脚本（触发 Actions）
├── service/                      # Go 后端（main.go + models/router/api）
├── service/assets/version        # 后端内置版本号（形如 11|1.4.0）
├── src/                          # 前端源码（Vue 3 + Vite + Naive UI）
├── dist/                         # 前端构建产物（Actions 构建并打包进 web 资源包）
├── .github/workflows/release.yml # tag 触发：交叉编译 + 创建 Release
└── .github/workflows/build.yml   # tag 触发：构建 multi-arch Docker 镜像

二、配置一键安装脚本

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

APP_NAME="fan-panel"
REPO="meimolihan/fan-panel"
DEFAULT_PORT=3002
DEFAULT_APP_DIR="/var/lib/fan-panel"

提交推送至 main 分支

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

三、构建与发布

3.1 本地开发编译（可选，仅验证）

前端（Vue 3 + Vite，包管理 pnpm@8）：

pnpm install
pnpm run build          # 产物输出到 dist/

后端（Go 1.21）：

cd service
export PATH=$PATH:/usr/local/go/bin
go mod download
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w -X fan-panel/global.RUNCODE=release" -o ../fan-panel_linux_amd64 ../main.go 2>/dev/null || go build main.go

本地编译仅用于功能验证；正式发布依赖 Actions，无需在本地生成最终产物。

3.2 一键发布（推荐，触发 Actions）

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

内部流程：

1. 清理已存在的同名 Release 与本地/远端 tag（内测场景）
2. 更新版本号：service/assets/version（保留左侧前缀，只替换版本号）与 package.json
3. Git commit + push main
4. 打 v1.4.1 tag 并推送
5. GitHub Actions 自动执行：
   • release.yml：构建前端 → 打包 fan-panel-assets.tar.gz（内含 web/）→ Go 交叉编译 fan-panel_linux_amd64/arm64 → 创建 GitHub Release
   • build.yml：构建 multi-arch Docker 镜像并推送 mobufan/fan-panel:latest + v1.4.1

3.3 查看发布结果

cd /vol1/1000/GitHub/fan-panel
gh release view v1.4.1
git ls-remote --tags origin | grep v1.4.1
docker pull mobufan/fan-panel:v1.4.1

3.4 校验 Release

访问：https://github.com/meimolihan/fan-panel/releases/tag/v1.4.1

1. 状态：Published，不是 Draft 草稿
2. Assets 内必须存在 fan-panel_linux_amd64、fan-panel_linux_arm64、fan-panel-assets.tar.gz。

测试下载链接有效性

curl -I https://github.com/meimolihan/fan-panel/releases/latest/download/fan-panel_linux_amd64
curl -I https://github.com/meimolihan/fan-panel/releases/latest/download/fan-panel-assets.tar.gz

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

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

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

4.1 预检查国内网络

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

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

4.2 执行一键安装

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

交互步骤：

1. 端口 [3002]>: 回车使用默认，或填写自定义端口（写入 conf/conf.ini 的 http_port）
2. 应用目录 [/var/lib/fan-panel]>: 回车使用默认路径
3. 脚本自动下载二进制与 web 资源包、初始化 conf/database/uploads、创建 systemd 服务、启动程序
4. 输出访问地址；默认账号 admin / admin888

静默安装

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

部署后运维命令

systemctl status fan-panel
journalctl -u fan-panel -f
systemctl restart fan-panel
cat /var/lib/fan-panel/conf/conf.ini | grep http_port

五、一键卸载

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

• 默认保留数据（conf/ database/ uploads/），加 --purge 彻底清除。

六、新版本发布两种模式

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

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

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

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

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-panel/main/scripts/install.sh)" -y
cat /etc/fan-panel.conf   # 查看 VERSION

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

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

cd /vol1/1000/GitHub/fan-panel
# 删除github release
gh release delete v1.4.1 -y --cleanup-tag
# 重新运行发布脚本（自动清理tag、重新打tag触发Actions重建Release与镜像）
bash scripts/build-and-push.sh v1.4.1 --yes

七、故障排查表

八、前端/后端代码修改流程

1. 前端：修改 src/ 源码（Vue 3 + Vite + Naive UI），本地 pnpm run build 验证
2. 后端：修改 service/（Go），本地编译验证（见 3.1）
3. 发布新版本：bash scripts/build-and-push.sh v1.4.2 --yes，等待 Actions 完成
4. 目标服务器重跑一键安装脚本升级生效（Docker 用户改为 docker compose pull && docker compose up -d）

九、极简速查复制块

发布新版本速记

cd /vol1/1000/GitHub/fan-panel
bash scripts/build-and-push.sh v1.4.2 --yes
gh release view v1.4.2

远程一键安装

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

备份 / 恢复 / 卸载

bash <(curl -sL https://raw.githubusercontent.com/meimolihan/fan-panel/main/scripts/backup.sh)
bash <(curl -sL https://raw.githubusercontent.com/meimolihan/fan-panel/main/scripts/restore.sh) /path/to/backup.tar.gz
bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-panel/main/scripts/uninstall.sh)" -y --purge

相关命令

• fan-panel-build 👈 当前所在位置
• fan-panel
• fan-panel_menu
• opencode_menu