前端独立构建与测试服发布

在前端 game-busAdminSystem 仓库的 kra 分支根目录执行。全部命令只需要前端源码，不需要 Go 仓库或后端配置。

本机需要 Node.js 22.12 及以上、pnpm 10 及以上、Git。生成发布包还需 tar；发布需 OpenSSH 的 ssh / scp。Windows、macOS、Linux 使用相同的 pnpm 命令。Docker 源码构建另需本机 Docker；发布包方式在服务器构建镜像，本机不需要 Docker。

1. 只构建静态文件

pnpm install --frozen-lockfile
pnpm build

产物是 dist/。生产接口使用同域 /api，前端包里不写数据库密码、SDK 密钥或 SSH 密码。

2. 独立打包

先提交前端改动；脚本会检查前端目录的已修改、暂存及未跟踪文件，构建过程中生成的 src/pathInfo.json 也须与提交一致。

pnpm package:test
# 自定义版本；默认版本为当前提交号前 12 位
pnpm package:test --tag web-20261105-01

脚本安装锁定依赖、执行生产构建，生成：

.cache/deploy/sw2-frontend-<版本>.tar.gz
.cache/deploy/sw2-frontend-<版本>.tar.gz.sha256

包内只有 dist/、运行镜像的 Dockerfile、nginx.conf、服务端 deploy.sh 与 release.json。版本清单记录提交号、源码树和构建时间，静态目录中的 build-info.json / version.txt 用于发布核对。已有同名包不会被覆盖；发布时复用该包或指定新版本。

--skip-install 可在已经按锁文件安装依赖后使用；--output <目录> 可指定包输出目录。在 sw-new/web 中开发时也可运行：检查只覆盖前端，后端本地配置不影响打包。若已在本地生成分仓提交，可传 --source-ref codex/publish-web，脚本会验证该提交的根目录与当前前端源码树一致。

3. 构建并推送 Harbor 镜像

pnpm build:docker
pnpm build:docker --tag web-20261105-01
# 构建后推送到 Harbor
docker login harbor.fuhua91.com
pnpm push:docker --tag web-20261105-01

镜像仓库统一为 harbor.fuhua91.com/game/sw2:<版本>，默认版本仍为源码提交号前 12 位。build:docker 只构建，push:docker 构建并推送到 Harbor 的 game/sw2 仓库。使用已有 Docker 登录凭据或机器人账号，本机推送账号需要 game/sw2 的 push 权限，服务器拉取账号需要 pull 权限；密码不写入脚本或发布包。

deploy/Dockerfile 在 Node 容器内完成源码构建，deploy/runtime.Dockerfile 用于发布包的服务器构建。根目录 Dockerfile 与 Windows pnpm pack:docker <版本> 入口也使用上述 Harbor 仓库；pack:docker 构建并推送，传 -SaveArchive 可额外导出离线镜像到忽略的 .cache/docker/。

本机构建检测到 Buildx 时，输出 Linux amd64 的单平台 Docker 镜像并关闭默认证明附件，兼容测试服 Docker 18.06；没有 Buildx 时使用传统构建器。

4. 发布到 sw2 测试服

默认连接 root@192.168.2.226:22，部署根目录 /www/wwwroot/sw2.fuhua91.com。使用本机 SSH 密钥或 SSH agent；首次使用先用 ssh root@192.168.2.226 确认主机指纹和登录权限。脚本使用非交互 SSH，仓库不保存密码。

# 本机打包，服务器构建并推送 Harbor，再拉取部署
pnpm deploy:test

# 已通过 push:docker 推送：测试服直接从 Harbor 拉取，不再上传包或重新构建
pnpm deploy:test --image-tag web-20261105-01

# 复用已经生成的包
pnpm deploy:test --archive .cache/deploy/sw2-frontend-web-20261105-01.tar.gz

# 构建、推送、拉取并预检，保持当前容器运行
pnpm deploy:test --archive .cache/deploy/sw2-frontend-web-20261105-01.tar.gz --build-only
# 也可仅预检 Harbor 中的现有镜像
pnpm deploy:test --image-tag web-20261105-01 --build-only

# 使用其他 SSH 账号、端口或密钥
pnpm deploy:test --archive <发布包.tar.gz> --user deploy --port 22 --identity <私钥路径>

可用 --host 与 --directory 覆盖测试服务器和部署根目录。服务器账号需要该目录写权限及 Docker 权限，并已执行 docker login harbor.fuhua91.com。发布包模式在服务器执行 push，需 push/pull 权限；--image-tag 模式只需 pull 权限。现有的 sw2-net 网络、sw2-backend:8000 服务与宝塔反向代理应已就绪；服务端脚本兼容 Docker 18.06，不依赖 Docker Compose。

若服务器已有其他项目的 Docker 登录，可为本项目前端单独配置。脚本优先读取部署根目录 harbor-docker/config.json，不存在时使用当前账号默认 Docker 配置：

install -d -m 700 /www/wwwroot/sw2.fuhua91.com/harbor-docker
docker --config /www/wwwroot/sw2.fuhua91.com/harbor-docker login harbor.fuhua91.com
chmod 600 /www/wwwroot/sw2.fuhua91.com/harbor-docker/config.json

发布过程：

验证包结构和版本，上传至 frontend-releases/，校验 SHA-256。相同版本只接受同一个发布包。
发布包模式先构建并推送 harbor.fuhua91.com/game/sw2:<版本>；两种模式随后都从 Harbor 拉取，取得镜像摘要，按 harbor.fuhua91.com/game/sw2@sha256:… 运行临时容器并检查 /healthz、/version.txt 和 /api/health。镜像推送或拉取失败时，当前容器继续运行。
预检通过后，只替换 sw2-frontend，仍绑定 127.0.0.1:9601。上一版保留为停止状态的 sw2-frontend-previous。
正式容器使用同一个已验证的镜像摘要；再次检查失败时自动恢复上一版。成功后写入 current-frontend-release，镜像摘要保存在 frontend-images/<版本>.ref。后端容器、数据库、后端配置及联合发布的 current-release 均不修改。

Nginx 使用 Docker DNS 动态解析后端地址，后端独立重建后无需重建前端镜像。对外仍访问 http://sw2.fuhua91.com。

回退与验证

指定 Harbor 中保留的旧版本即可回退，仍只操作前端：

pnpm deploy:test --image-tag <旧版本>

服务端手工执行同样的脚本：

bash /www/wwwroot/sw2.fuhua91.com/frontend-releases/<版本>/deploy.sh <版本>
curl -fsS http://127.0.0.1:9601/version.txt
curl -fsS http://127.0.0.1:9601/api/health
docker inspect --format '{{.Config.Image}}' sw2-frontend

发布脚本通过文件锁阻止并发前端发布。永久回归测试覆盖包路径与版本验证、Harbor 推送/拉取失败、缺失镜像摘要、直接拉取模式、预检失败及发布后回退，以及后端容器保持不变：

pnpm test:release

测试需要 Bash；Windows 可使用 Git for Windows 自带的 Bash，或通过 BASH 环境变量指定。

6.6 KiB Raw Blame History Unescape Escape