第 19 课：用 Git 版本发布、升级和回滚

第五阶段 · 正式生产环境 · 面向 Docker 初学者

本课完成标准

你能够用 Git 标签固定发布版本；在 ECS 拉取指定版本；备份数据库后执行 Alembic 迁移；分步骤升级 Docker 服务；出现问题时回滚应用镜像或代码，并知道数据库迁移为什么需要谨慎。

1. 发布的核心思想

不要直接把“当前最新代码”当成生产版本。一次发布应该有明确版本号、变更说明、数据库迁移和回滚方案：Git 版本 → 备份 → 拉取指定版本 → 构建镜像 → 迁移 → 重启 → 验收。

2. 在本地固定版本

在 macOS 或 Windows 的项目目录执行：

git status; git add .; git commit -m "release: prepare production v1.1.0"; git tag v1.1.0; git push origin main --tags

不要把 .env、私钥、真实密码和生产数据库导出文件提交 GitHub。标签 v1.1.0 是以后回滚时定位代码的依据。

3. 在 ECS 发布指定版本

cd /www/wwwroot/student-management-api; git fetch --tags origin; git checkout v1.1.0; git log -1 --oneline; docker compose build api; docker compose up -d api

生产发布尽量切换到已经在本地验证过的标签，不要自动合并未知分支。

4. Alembic 迁移和备份

数据库结构变更前先用宝塔面板或命令行备份。备份文件要放在受保护目录，不要放进 Nginx 静态目录。

docker compose run --rm api alembic upgrade head; docker compose ps; docker compose logs --tail=100 api

迁移成功后再验收 API。不要在生产环境随意执行 alembic downgrade；降级可能造成数据丢失，应该先设计可逆迁移和恢复方案。

5. 分阶段验收

curl -I https://api.example.com/login; curl -I https://api.example.com/docs; docker compose ps; docker compose logs --tail=200 api

依次确认容器、登录页、静态资源、认证接口、核心查询和数据库读写。发现错误就停止继续发布。

6. 回滚应用版本

新版本启动失败时先保留日志，再切回上一标签：

git checkout v1.0.0; docker compose build api; docker compose up -d api; docker compose ps

回滚代码和镜像不等于数据库自动回到旧结构。若新迁移已经执行，必须根据迁移设计和备份方案处理数据库，不能盲目降级。

7. 发布记录模板

发布版本：v1.1.0；上一个版本：v1.0.0；Git 提交：；变更内容：；数据库迁移：；备份位置与时间：；验收结果：；回滚命令：；发布人和时间：

8. 一分钟自测

为什么回滚代码后不能直接认为数据库也回滚了？

• A. 数据库迁移可能已改变表结构或数据，必须单独处理
• B. Docker 会自动删除数据库
• C. Git 标签会保存数据库内容

答案：A。

本课通关证据

git log -1 --oneline; git describe --tags --always; docker compose ps; docker compose logs --tail=100 api

保存版本标签、迁移结果、备份记录和验收结果。后续可继续学习第 20 课：日志、备份与恢复（该课程文件未包含在本次导入中）。