gongxiangp2/docs/Git增量部署方案.md

Git 增量部署方案

目标

以 Git 仓库作为唯一源码入口，构建机增量拉取源码并构建镜像，生产服务器只拉取镜像并替换容器。

部署链路

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

脚本

脚本路径：

.\scripts\git-incremental-deploy.ps1

默认部署：

• Git 仓库：https://git.1080p.hk/WuYongJie/gongxiangp2.git（证书必须有效，禁止跳过 TLS 校验）
• 分支：main
• 构建机：192.168.40.206
• 生产机：192.168.58.20
• 正式容器：youyidian-3d-material
• 正式端口：4320

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

首次运行前准备

本脚本由维护人员执行，不要求普通用户手动运行。首次在一台新维护机上运行前，需要确认：

• 本机可用 PowerShell 5.1+。
• 本机已安装 PuTTY 工具，plink.exe 和 pscp.exe 可在 PATH 中找到，或位于 C:\Program Files\PuTTY\。
• 本机能访问构建机 192.168.40.206。
• 构建机能访问 Git 仓库和生产机 192.168.58.20。
• 构建机本地 Registry 端口 5000 可用。
• 已通过环境变量或参数提供构建机密码：BUILD_SERVER_PASSWORD 或 -BuildServerPassword。
• 已分别固定构建机和生产机的 SSH SHA256 主机指纹；OpenSSH 模式还必须使用预置、只读的 known_hosts 文件。
• 私有 Git 仓库认证必须预先配置在维护机和构建机的只读 credential helper 中。脚本拒绝 GIT_DEPLOY_PASSWORD、GIT_AUTH_HEADER、明文 HTTP 和 URL 内嵌凭据。

安全边界

• 不从本机上传源码压缩包。
• 不在生产机上执行 npm install 或 next build。
• 不改生产机的 .env 和 uploads 目录。
• 不把 Git 密码写入仓库或远端 URL。
• Git HTTPS 证书失效、SSH 指纹不匹配或仓库地址偏离权威地址时，发布必须停止；不得使用 -k 或关闭主机校验绕过。
• 生产容器启动失败时，默认尝试回滚到旧镜像。
• 清理策略只清理无用镜像/容器，默认保留 Docker build cache。

验证方式

正式部署前先执行 DryRun：

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

DryRun 只验证：

• 构建机可连接
• 构建机能读取 Git 仓库
• 构建机能连接生产机
• 构建机 Registry 可用

DryRun 不会改代码、构建镜像或重启生产容器。

镜像标签

每次部署会生成两个标签：

• production-<commit>：可回滚的确定版本
• production-latest：正式环境最新版本

影子环境的历史标签为：

• shadow-<commit>
• shadow-latest

当前通用发布脚本会在任何 Git 扫描或远程操作前拒绝 Target=shadow，因为影子环境尚未证明 uploads、后台 runtime 和 Redis 与生产完全隔离。不得把这些历史标签说明理解为可执行发布入口。

回滚思路

脚本启动新容器前会记录旧容器镜像。如果新容器健康检查失败，默认会重新用旧镜像启动容器。

如果需要人工指定旧版本，可以通过 Registry 中的 production-<commit> 标签部署指定提交。