目标

避免“本地开发服务器已更新，但云端仍在服务旧代码或旧前端构建产物”的版本漂移。部署命令应把构建、同步、重启和公网验证串成一个可重复执行的发布单元。

适用条件

  • 生产目录不是 Git 工作树，或不能以提交号可靠地描述当前版本；
  • 前端生产产物（如 dist/）被 .gitignore 忽略，必须显式构建并上传；
  • 服务由 systemd、PM2 等进程管理器运行，并经 Nginx 等反向代理公开；
  • 生产环境有不能被源码同步覆盖的密钥、依赖、反馈数据或用户上传内容。

推荐流程

  1. 在本地使用生产构建命令生成前端产物。
  2. 运行与发布内容相关的自动化测试；测试失败时不连接服务器。
  3. 计算关键文件的 SHA-256，例如前端入口 HTML 和一个后端核心模块。哈希是本次发布的可验证身份，而不是仅依赖时间戳。
  4. 在远端创建带时间戳的部署快照，再同步源码和构建产物。
  5. 同步时显式排除 .env、虚拟环境、依赖目录、反馈/埋点文件、媒体上传、日志、备份和本地数据集备份。
  6. 用远端运行时解释器做语法编译检查，重启服务并等待本地端口恢复。

  7. 分层验证：

    • 进程管理器显示服务为 active；
    • 远端 127.0.0.1 服务首页哈希等于本地构建哈希；
    • 公网域名首页哈希也相同，确认反向代理实际服务的是新版本；
    • 公网 API 返回最小业务正确结果，而非仅检查 HTTP 200。
  8. 任一同步后验证失败时，自动从快照恢复应用文件并重启旧服务；输出快照路径供人工复核。

Windows 开发环境的实现选择

优先使用 rsync --archive --delete 配合排除清单。Windows Git Bash 可能没有 rsync，此时可用 Python 标准库 tarfile 打包经过同一排除规则过滤的文件，再用 scp 上传，远端清理可替换文件后解压。两条路径必须共享同一份“保留/排除”语义，否则不同机器会产生不同的发布结果。

验证边界

  • 前端构建警告（例如 bundle 大于建议体积）不等于发布失败，但应单独记录性能优化项。
  • curl 在刚重启服务时可能暂时无法连接；轮询检查应抑制这类预期重试噪声，最终检查必须严格失败。
  • 反向代理、TLS 和路径规则如果没有变化，不应由业务发布脚本顺带修改；它们应走独立的 Nginx 变更流程。

相关概念

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/Network