gongxiangp2/docs/部署规范.md

部署规范

更新时间：2026-05-07 当前默认部署方式：scripts/git-incremental-deploy.ps1

1. 当前标准部署方式

本项目当前以 Git 增量部署 作为默认发布链路。源码先推送到 Git 仓库，构建机只从 Git 拉取增量代码并构建镜像，生产服务器只拉取镜像并替换应用容器。

本机提交并推送源码到 Git
  -> 构建机 git fetch / reset 到指定提交
  -> 构建机 docker build，复用 Docker / Next 缓存
  -> 构建机推送 production-<commit> 和 production-latest 镜像
  -> 生产机拉取指定提交镜像
  -> 停旧应用容器，启动新应用容器
  -> 检查 /api/health，失败时默认尝试回滚旧镜像

脚本路径：

.\scripts\git-incremental-deploy.ps1

Mac 维护机使用原生调度入口。该入口直接读取上面的主脚本远端模板，构建机与生产机门禁仍只有一套，不在 Mac 构建生产镜像：

./scripts/git-incremental-deploy-macos.sh --dry-run
./scripts/git-incremental-deploy-macos.sh --commit '<40位小写提交SHA>'

默认使用 ~/.ssh/gongxiangp2_build_machine 连接构建机，并从本机 ~/.ssh/known_hosts 提取已信任的构建机 ED25519 主机密钥。构建机到生产机继续使用其固定的 /root/.ssh/gongxiangp2-production-known_hosts。脚本不读取、保存或传递 SSH 密码。

默认参数：

• Git 仓库：http://git.1080p.hk/WuYongJie/gongxiangp2.git（现场 Gitea 仅提供 HTTP；脚本只允许这一条精确地址）
• 分支：main
• 构建机：192.168.40.206
• 生产机：192.168.58.20
• 正式容器：youyidian-3d-material
• 正式端口：4320
• 影子发布：当前通用脚本已 fail-closed 禁用；必须使用 uploads/runtime/Redis 完全隔离的专用入口后才能恢复。

WuYongJie/gongxiangp2 是当前唯一权威仓库。lunanting/gongxiangp2 仅作为历史仓库识别，不得再用于构建或发布。

正式部署由维护人员执行，不要求普通用户手动运行。

2. 常用命令

2.1 运行前准备

维护机需要具备：

• PowerShell 5.1+。
• PuTTY 工具：plink.exe、pscp.exe。
• 构建机 SSH 凭据，通过 BUILD_SERVER_PASSWORD 或 -BuildServerPassword 提供。
• 构建机、生产机的固定 SSH SHA256 主机指纹；OpenSSH 模式还要提供受控 known_hosts 文件。
• 维护机和构建机已配置只读 Git credential helper。部署脚本禁止把 Git 密码/Header 写入参数、临时脚本或进程命令行。

Mac 入口需要具备：

• macOS 自带的 bash、ssh、scp、ssh-keygen，以及 Node.js 18+ 和 Git。
• 已授权到构建机的独立私钥，默认路径为 ~/.ssh/gongxiangp2_build_machine，权限必须为 0600 或更严格。
• 本机 known_hosts 已通过人工核验保存构建机 ED25519 主机密钥；不使用运行时 ssh-keyscan 自动接受主机。

不要把 Git 密码写进仓库 URL，也不要把临时部署密码写入文档或提交到仓库。Gitea 的 HTTP 通道不具备传输加密与证书身份保证，因此只能使用只读、最小权限 credential helper；正式构建/部署必须显式指定维护机已核对的完整 40 位小写提交 SHA，并继续核对 SSH 主机指纹、镜像 ID 与 manifest digest。

脚本对维护机和构建机的 Git HTTP 读取设置 30 秒低速超时。Gitea 无响应时本次发布失败关闭，不允许无限挂起后由人工跳过源码身份校验。

2.2 部署命令

正式部署前先做 DryRun：

.\scripts\git-incremental-deploy.ps1 -DryRun

部署正式环境：

.\scripts\git-incremental-deploy.ps1 -Commit '<40位小写提交SHA>'

影子环境（当前禁止通过通用脚本执行；下面命令会明确失败）：

.\scripts\git-incremental-deploy.ps1 -Target shadow

部署指定提交：

.\scripts\git-incremental-deploy.ps1 -Commit '<40位小写提交SHA>'

必要时彻底重新构建：

.\scripts\git-incremental-deploy.ps1 -Commit '<40位小写提交SHA>' -NoCache

3. 参数说明

• -Target：当前只允许 production；shadow 会在任何 Git/远程操作前 fail-closed。
• -RepoUrl：Git 仓库地址，默认使用 WuYongJie/gongxiangp2。
• -Branch：部署分支，默认 main。
• -Commit：正式构建/部署必填，必须是维护机已核对的 40 位小写提交 SHA；仅 -DryRun 可不填。
• -DryRun：只做连通性与依赖预检，不构建、不推镜像、不重启容器。
• -NoCache：Docker 构建不使用缓存。
• -KeepOldImages：跳过自动 Docker 镜像清理。
• -AggressiveBuildCacheCleanup：额外清理较旧构建缓存；默认不启用。
• -SkipBuild / -SkipPush：只允许同时配合 -SkipDeploy 做本地排障；真实生产发布禁止跳过构建或推送。
• -SkipDeploy：只构建/验证，不触碰生产流量。

4. 安全边界

• 不从本机上传源码压缩包。
• 不在生产机上执行 npm install 或 next build。
• 不修改生产机 .env 文件。
• 不删除、不移动、不覆盖生产机 uploads 目录内容。
• 不直接操作 PostgreSQL、Redis 或 MinIO 容器。
• 生产机只替换应用容器，并保留 /mnt/PoolOne/youyidian-uploads:/app/uploads 独立 ZFS 数据集挂载。
• 新容器健康检查失败时，脚本默认用旧镜像回滚应用容器。

详细安全说明见：部署脚本安全说明。

5. 镜像标签

每次部署生成确定提交标签和移动标签：

production-<commit>     # 正式环境确定版本
production-latest       # 正式环境最新版本
shadow-*                # 历史命名；通用发布入口当前不再生成

Registry UI：

http://192.168.40.206:5001

6. 清理策略

脚本默认只清理 Docker 虚拟资源，不清理业务文件目录。

构建机：

• 清理悬空镜像。
• 默认保留 Docker build cache，保证增量构建速度。
• 只有传入 -AggressiveBuildCacheCleanup 时，才额外清理较旧构建缓存。

生产服务器：

• 清理 6 小时前的旧镜像。
• 清理 6 小时前的未使用容器。
• 保留当前运行的应用容器、uploads 挂载目录、数据库和 MinIO 数据。

7. 历史脚本口径

本地历史脚本名

deploy-remote-build.ps1、deploy-local-build.ps1、deploy-public-build.ps1 这类 deploy-*.ps1 属于本地历史脚本名，受 .gitignore 保护，不作为仓库交付入口。

它们对应的是旧的“本机打包代码并上传到构建机”或“本地 / 公网穿透构建”链路，只能用于识别历史资料，不再是当前默认方式。

旧链路：

本地电脑打包源码
  -> SSH 上传源码压缩包到构建机
  -> 构建机构建镜像
  -> 推送 Registry
  -> 生产机拉取镜像并替换容器

deploy-git-build.ps1

历史 Git 部署脚本已被 scripts/git-incremental-deploy.ps1 替代。后续涉及 Git 增量部署时，只看新脚本和 Git 增量部署方案。

8. 故障排查顺序

DryRun 失败

优先检查：

• 构建机 SSH 是否可达。
• 构建机能否读取 Git 仓库。
• 构建机能否 SSH 到生产服务器。
• 构建机本地 Registry 是否可用。

Git 同步失败

优先检查：

• Git 仓库地址是否正确。
• Git 凭据是否正确。
• main 分支是否已经推送最新代码。

生产容器启动失败

优先检查：

ssh root@192.168.58.20 'docker logs --tail 120 youyidian-3d-material'
ssh root@192.168.58.20 'curl -fsS http://127.0.0.1:4320/api/health'

uploads 目录检查

ssh root@192.168.58.20 'ls -la /mnt/PoolOne/youyidian-uploads | head -20'

9. 版本历史

• v2.0 (2026-05-07): 默认部署方式切换为 scripts/git-incremental-deploy.ps1。
• v1.0 (2026-01-26): 旧版远程构建机脚本规范，现已降级为应急回退资料。