fan-shop-build

补充说明

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

项目：fan-shop｜非凡商店（基于 Docker 的容器管理平台） 仓库：https://github.com/meimolihan/fan-shop Docker 镜像：mobufan/fan-shop（latest + 版本标签，Actions 自动构建 multi-arch） 发布方式：本地不编译，build-and-push.sh 仅更新版本号并推送 v* tag，由 GitHub Actions 自动完成打包源码包与镜像

重要规则

1. GitHub 不允许直接覆盖已发布 Release，正式环境版本号单向递增；内测可删除重建同名 tag（build-and-push.sh 已内置自动清理）。
2. install.sh 使用 releases/latest/download 或按传入版本下载源码包，脚本不需要硬编码版本号。
3. 发布动作为：更新版本号 → 提交 → 推 tag → GitHub Actions 自动构建（release.yml 打包自包含源码包+创建 Release，build.yml 构建 Docker 镜像）。
4. 后端为 Python(FastAPI/uvicorn)，无编译依赖；前端为原生静态资源（eslint 校验），由 Actions 直接打包，无需本地构建产物。

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

1.1 安装依赖

apt update
apt install git curl python3 python3-venv

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

项目目录结构

fan-shop/
├── scripts/install.sh            # 远程一键安装脚本（systemd 直装）
├── scripts/uninstall.sh          # 卸载脚本
├── scripts/build-and-push.sh     # 版本号更新+打tag+推送脚本（触发 Actions）
├── backend/                      # Python FastAPI 后端
│   └── app/main.py               # 应用入口（uvicorn app.main:app）
│   └── app/version.py            # 版本号（VERSION = "v2.1.7"）
├── frontend/                     # 前端静态源码（eslint 校验）
├── Dockerfile                    # 镜像构建（python:3.11-slim + uvicorn 8001）
├── docker-compose.yml            # Compose 部署模板（8000:8001）
├── fnOS/                         # 飞牛 fnOS 应用配置
├── .github/workflows/release.yml # tag 触发：打包源码包 + 创建 Release
└── .github/workflows/build.yml   # tag 触发：构建 multi-arch Docker 镜像

二、配置一键安装脚本

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

REPO="meimolihan/fan-shop"
INSTALL_DIR="/opt/fan-shop"
PORT=8001

fan-shop 安装脚本为固定目录 /opt/fan-shop 与固定端口 8001（无 -p/-a 参数），从 Release 下载 fan-shop-<版本>.tar.gz 自包含源码包，创建 venv 并注册 systemd 服务。

提交推送至 main 分支

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

三、构建与发布

3.1 本地验证（可选，仅测试）

cd backend
python3 -m venv ../.venv
../.venv/bin/pip install -r requirements.txt
../.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001

前端无构建步骤（原生静态资源），后端无需编译，本地无需生成发布产物。

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

cd /vol1/1000/GitHub/fan-shop
bash scripts/build-and-push.sh v2.1.7 --yes

内部流程：

1. 清理已存在的同名 Release 与本地/远端 tag（内测场景）
2. 更新版本号：backend/app/version.py（VERSION = "vX.Y.Z"、BUILD_DATE）
3. Git commit + push main
4. 打 v2.1.7 tag 并推送
5. GitHub Actions 自动执行：
   • release.yml：组装源码包（backend + frontend + Dockerfile + compose + scripts）→ 打包 fan-shop-2.1.7.tar.gz + 生成 SHA256SUMS → 创建 GitHub Release
   • build.yml：构建 multi-arch（linux/amd64,arm64）Docker 镜像并推送 mobufan/fan-shop:latest + v2.1.7

3.3 查看发布结果

cd /vol1/1000/GitHub/fan-shop
gh release view v2.1.7
git ls-remote --tags origin | grep v2.1.7
docker pull mobufan/fan-shop:v2.1.7

3.4 校验 Release

访问：https://github.com/meimolihan/fan-shop/releases/tag/v2.1.7

1. 状态：Published，不是 Draft 草稿
2. Assets 内必须存在 fan-shop-2.1.7.tar.gz 和 SHA256SUMS。

测试下载链接有效性

curl -I https://github.com/meimolihan/fan-shop/releases/latest/download/fan-shop-2.1.7.tar.gz
curl -I https://github.com/meimolihan/fan-shop/releases/latest/download/SHA256SUMS

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

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

目标服务器需要 root 权限，已安装 curl、python3；建议已安装 Docker（fan-shop 的容器管理功能依赖）。

4.1 预检查国内网络

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

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

4.2 执行一键安装

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

交互步骤：

1. 请求 GitHub API 解析最新 Release 版本（或传入版本参数 v2.1.7）
2. 下载 fan-shop-<版本>.tar.gz 自包含源码包，解压到 /opt/fan-shop
3. 创建 Python venv 并 pip install backend/requirements.txt
4. 注册 systemd 服务 fan-shop.service，uvicorn app.main:app --port 8001 启动
5. 输出访问地址；首次使用需注册用户

静默安装指定版本

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

部署后运维命令

systemctl status fan-shop
journalctl -u fan-shop -f
systemctl restart fan-shop
cat /opt/fan-shop/backend/app/version.py  # 查看 VERSION

五、一键卸载

bash <(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-shop/main/scripts/uninstall.sh)

• 默认保留数据（/opt/fan-shop 目录与 backend/data），加 --purge 彻底清除。

六、新版本发布两种模式

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

不要复用旧 tag，版本号向上迭代，例如 v2.1.7 → v2.1.8

cd /vol1/1000/GitHub/fan-shop
bash scripts/build-and-push.sh v2.1.8 --yes

目标服务器升级，直接重跑安装脚本，自动拉取 latest 源码包、重建 venv、systemd 自动重启

bash -c "$(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-shop/main/scripts/install.sh)"
grep VERSION /opt/fan-shop/backend/app/version.py   # 查看新版本号

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

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

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

七、故障排查表

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

1. 前端：修改 frontend/ 静态源码，cd frontend && npm run lint 校验
2. 后端：修改 backend/app/（FastAPI），本地 uvicorn 验证
3. 发布新版本：bash scripts/build-and-push.sh v2.1.8 --yes，等待 Actions 完成
4. 目标服务器重跑一键安装脚本升级生效（Docker 用户改为 docker compose pull && docker compose up -d）

九、极简速查复制块

发布新版本速记

cd /vol1/1000/GitHub/fan-shop
bash scripts/build-and-push.sh v2.1.8 --yes
gh release view v2.1.8

远程一键安装

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

远程一键卸载

bash <(curl -sSL https://raw.githubusercontent.com/meimolihan/fan-shop/main/scripts/uninstall.sh) --purge

相关命令

• fan-shop-build 👈 当前所在位置
• fan-shop
• fan-shop_menu
• dc_inst_fan-shop
• opencode_menu