fan-nginx-build

补充说明

本教程介绍 fan-nginx 从源码编译、发布 GitHub Release 到目标服务器一键安装、卸载、升级的完整流程，适用于个人自建 Nginx 图形化管理平台发布链路。

项目：fan-nginx｜Nginx 图形化管理平台 仓库：https://github.com/meimolihan/fan-nginx 编译发布主机：fnOS（Debian，本机 Git、curl、Maven、JDK8、gh 环境齐全） 部署测试主机：Debian Linux（amd64/arm64）

重要规则

1. GitHub 不允许直接覆盖已发布 Release，正式环境版本号单向递增；内测可删除重建同名 tag（build-and-push.sh 已内置自动删除重建逻辑）。
2. install.sh 默认使用 releases/latest/download，脚本不需要硬编码版本号；可传 FAN_NGINX_VERSION=vX.Y.Z 锁定指定版本。
3. 编译机器 ≠ 业务运行机器；fnOS 只做编译发布，业务跑在目标主机。
4. 正式发布由 GitHub Actions 流水线完成（Maven jar + GitHub Release + Docker Hub/GHCR 镜像 + CNB 同步），本地 build-and-push.sh 仅负责升版本号、打 tag。

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

1.1 安装依赖

apt update
apt install git curl unzip

Java 8（JDK8）与 Maven（确保 java -version、mvn -version 正常）。

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

项目目录结构

fan-nginx/
├── scripts/install.sh            # 远程一键安装脚本（systemd）
├── scripts/uninstall.sh          # 卸载脚本
├── scripts/fan-nginx_backup.sh   # 备份脚本（在线，不停服）
├── scripts/fan-nginx_recover.sh  # 恢复脚本
├── scripts/fan-nginx-cli.sh      # 内置 CLI 命令（fan-nginx）
├── scripts/build-and-push.sh     # 构建+打tag+推送脚本（触发 GitHub Actions）
├── buildx.sh                     # 本地多架构镜像构建（amd64/arm64）
├── docker-compose.yml            # Docker Compose 部署示例（host 网络）
├── pom.xml                       # Maven 工程（Java 8 / Solon）
└── src/                          # 源码

二、本地编译 jar

mvn clean package

编译产物：target/fan-nginx-<ver>.jar（如 target/fan-nginx-4.4.3.jar）。

需要生产 jar 可直接投递到目标服务器，用 install.sh 的 -j 参数指定安装。

三、构建与发布

3.1 一键发布（推荐，触发 GitHub Actions 全链路）

bash scripts/build-and-push.sh v4.4.3 --yes -m "本次新增 xxx"

内部流程：校验 TAG 格式（vX.Y.Z）→ 检查/自动创建 CNB 仓库 → 删除已存在的同名 Release/tag（可重发）→ 更新 pom.xml 工程版本号（仅 fan-nginx 工程，不动依赖版本）→ 写 RELEASE_NOTES.md → git commit + git push main + git push origin v4.4.3 → 轮询 release.yml 流水线状态并打印快捷命令。

推送后由 GitHub Actions（.github/workflows/release.yml）链式自动完成：

3.2 本地多架构 Docker 镜像构建（备选，不走 Actions）

# 需先 docker login（Docker Hub 与 GHCR）
docker login
bash buildx.sh          # 自动读 pom 版本号，构建并推送 amd64/arm64

3.3 创建 GitHub Release（手动备选）

VERSION=4.4.3
gh release create "v${VERSION}" target/fan-nginx-${VERSION}.jar \
  --title "v${VERSION}" \
  --notes "fan-nginx - Nginx 图形化管理平台"

校验 Release

访问：https://github.com/meimolihan/fan-nginx/releases/tag/v4.4.3

1. 状态：Published，不是 Draft 草稿
2. Assets 内必须存在 fan-nginx-4.4.3.jar，不要只看源码 zip/tar.gz。

测试下载链接有效性

curl -I https://github.com/meimolihan/fan-nginx/releases/download/v4.4.3/fan-nginx-4.4.3.jar

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

四、目标服务器远程一键安装（systemd 裸机部署）

目标服务器需要 root 权限，已安装 curl；脚本会检测并安装 Nginx（未安装时）。

4.1 预检查国内网络

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

输出 shell 脚本内容 = 网络正常；卡住超时需要网络代理或设置 FAN_NGINX_REPO 镜像仓库。

4.2 执行一键安装

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

交互步骤：

1. 输入监听端口（回车默认 8080）
2. 输入数据目录（回车默认 /var/lib/fan-nginx）
3. 可选输入初始管理员账号/密码（-u / -P，仅首次启动生效）
4. 脚本自动下载预编译 jar（或使用本地 -j / 源码 -s）、检测/安装 Nginx、创建 systemd 服务并启动
5. 输出 Web 访问地址与内置 CLI 提示

静默安装（指定端口、数据目录并初始化管理员）

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-nginx/main/scripts/install.sh)" -p 8080 -d /var/lib/fan-nginx -u admin -P 123456

锁定指定版本号

FAN_NGINX_VERSION=v4.4.3 bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-nginx/main/scripts/install.sh)" -y

国内网络镜像仓库加速

FAN_NGINX_REPO=https://ghfast.top/https://github.com/meimolihan/fan-nginx.git bash scripts/install.sh -y

部署后运维命令

systemctl status fan-nginx
journalctl -u fan-nginx -f
systemctl restart fan-nginx
fan-nginx status        # 内置 CLI：运行方式/端口/地址/路径/内存
fan-nginx credentials   # 重置并打印全部管理员账号密码（关闭两步验证）

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

• 首次登录：安装脚本指定了 -u/-P 则用该账号密码；否则使用内置 CLI fan-nginx credentials 查看/重置。

五、一键卸载

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

交互：

• 卸载将停止并移除 fan-nginx 服务与程序，是否继续？[y/N]:
• 是否删除数据目录 /var/lib/fan-nginx？[Y/n]:

免交互卸载

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

卸载完成：systemd 服务移除、进程停止、程序目录/CLI 命令/安装记录删除，可清理防火墙端口。

六、新版本发布两种模式

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

不要复用旧 tag，版本号向上迭代，例如 v4.4.3 → v4.4.4

cd /vol1/1000/GitHub/fan-nginx
bash scripts/build-and-push.sh v4.4.4 --yes -m "本次新增 xxx"

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

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

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

⚠️ 已有服务器依赖该版本绝对禁止执行，会造成旧版本下载 404。build-and-push.sh 已内置该逻辑（检测到同名 Release 自动删除并重建 tag）。

cd /vol1/1000/GitHub/fan-nginx
# 手动删除（等效脚本内置动作）
gh release delete v4.4.3 --yes --cleanup-tag
git tag -d v4.4.3
git push origin --delete v4.4.3

# 重新编译并重建 release 上传附件
mvn clean package
gh release create "v4.4.3" target/fan-nginx-4.4.3.jar \
  --title "v4.4.3" \
  --notes "fan-nginx - Nginx 图形化管理平台"

七、故障排查表

八、前端/业务修改后发布流程

fan-nginx 为 Maven 单体 Java 工程（内置 Web 界面资源），修改 src/ 后重走发布流程即可：

1. 修改 src/ Java / 前端静态资源代码
2. 本地验证：mvn clean package（可先本地 java -jar target/fan-nginx-...jar --server.port=8080 --project.home=/tmp/nh 跑通）
3. 重新走发布流程：bash scripts/build-and-push.sh v4.4.4 --yes -m "新功能"
4. 目标服务器重跑一键安装脚本 / docker compose pull && up -d 升级生效。

九、极简速查复制块

发布新版本速记

cd /vol1/1000/GitHub/fan-nginx
bash scripts/build-and-push.sh v4.4.4 --yes -m "本次新增 xxx"   # 触发 Actions 全链路
# 或分步：
# mvn clean package
# git add . && git commit -m "release v4.4.4"
# git push origin main && git push origin v4.4.4

gh release create "v4.4.4" target/fan-nginx-4.4.4.jar --title "v4.4.4" --notes "更新说明"

目标服务器升级

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-nginx/main/scripts/install.sh)" -y
# Docker 方式：
docker compose pull && docker compose up -d