外观
案例 9：生产部署与升级
约 1245 字大约 4 分钟
本案例以 Ubuntu 服务器上的 Docker Compose 部署为例，覆盖首次生产上线与后续版本升级。每一次操作都以“可验证、可回滚、不在生产临时改源码”为原则。
成功标准
- 服务器仅对公网开放必要端口，内部服务与数据库不暴露。
- 发布包在开发机/CI 构建，生产机只解压、配置、迁移和启动。
db-migrate在业务服务之前成功完成。- 用户端、管理端、登录、上传、生成任务和后台渠道均完成业务验收。
- 旧发布包、数据库备份与配置快照可用于紧急回退。
阶段一：上线前准备
资源清单
| 项目 | 必须确认 |
|---|---|
| 服务器 | Ubuntu 22.04/24.04、Docker、Docker Compose、时间同步。 |
| 网络 | 80/443 对公网，3306/6379/9999/20000-20009 不对公网。 |
| 数据库 | MySQL 8.x、utf8mb4、备份和恢复流程已验证。 |
| 对象存储 | 上传 Bucket、公开/上游访问域名、服务端凭证。 |
| 域名证书 | 用户端和管理端域名均解析且 TLS 证书已放置。 |
| 密钥 | 各 JWT、内部 Token、对象存储、支付与渠道密钥均为独立随机值。 |
阶段二：构建并检查发布包
在开发机仓库根目录执行：
powershell -ExecutionPolicy Bypass -File deploy/scripts/package-local.ps1已有依赖时可使用 -SkipInstall。构建后检查：
tar -tzf release/ad-canvas-<time>.tar.gz | head -n 50确认包内含 docker-compose.yml、环境变量示例、应用产物、Nginx 配置和运维脚本。发布包中不得包含真实 .env、证书或私钥。
阶段三：配置服务器
sudo mkdir -p /mnt/frameai
sudo chown -R "$USER":"$USER" /mnt/frameai
cd /mnt/frameai
tar --strip-components=1 -xzf /path/to/ad-canvas-<time>.tar.gz
cp .env.example .env编辑 .env 时按组替换：
APP_DOMAIN、ADMIN_DOMAIN、PUBLIC_BASE_URL。- MySQL 用户、密码、库名，或外部模式下的
MYSQL_DSN。 - 所有
change-this-*内部认证令牌与 JWT 密钥。 - 七牛对象存储开关、Bucket、访问域名和凭证；将
QINIU_PUBLIC_DOMAIN配置为浏览器使用的 CDN 域名，将QINIU_UPSTREAM_DOMAIN配置为服务端/AI 上游源站。 - 生成 Worker 并发、超时、回调基础地址。
- 需要上线真实支付时才开启相关
BILLING_*配置。
阶段四：预检、迁移与启动
docker compose --env-file .env config --quiet
docker compose --env-file .env config --services
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
docker compose --env-file .env logs --tail=200 db-migrate检查顺序：
config --quiet必须通过，才能证明变量与 Compose 语法可解析。db-migrate必须成功；不可让应用服务自行执行数据库 DDL。ps中服务应运行或健康，迁移服务可显示已完成。- 读取 Gateway、user-service、generation-service、media-service 日志，确认没有内部 Token、数据库或对象存储认证错误。
阶段五：业务验收脚本
按下列顺序实际操作并记录结果：
| 序号 | 操作 | 通过标准 |
|---|---|---|
| 1 | 访问用户端 HTTPS 域名 | 页面、静态资源和登录页可加载。 |
| 2 | 访问管理端 HTTPS 域名 | 管理员可登录且无跨域/路由错误。 |
| 3 | 创建测试用户/登录 | Gateway 与 user-service 认证正常。 |
| 4 | 上传一张测试图片 | 媒体服务写入对象存储且可读取。 |
| 5 | 提交最小图片或视频任务 | 任务创建、轮询、结果回填完整。 |
| 6 | 后台检查渠道与任务 | 任务、渠道、成本/计费信息可追溯。 |
| 7 | 查看健康与日志 | 无持续重启、迁移错误或高频 5xx。 |
阶段六：版本升级与回滚
升级
- 记录当前镜像/发布包版本与
docker compose ps状态。 - 备份 MySQL，保存当前
.env和证书的受控副本。 - 上传新发布包，不删除旧发布包。
- 先检查新包配置差异，再按预检、迁移、启动、业务验收顺序执行。
- 观察任务队列、失败率、上游成本和数据库连接。
回滚决策
- 仅前端或服务配置异常：使用旧发布包/镜像和已验证配置回退受影响服务。
- 已执行兼容性迁移：回退应用版本前先评估新旧 schema 兼容性；不要在生产直接执行
down、drop或force。 - 数据写入异常：暂停写入入口，保留日志和任务 ID；依据恢复预案处理，不手工改表结构。
运行中常用命令
docker compose --env-file .env ps
docker compose --env-file .env logs -f --tail=200 gateway user-service generation-service
docker compose --env-file .env logs -f --tail=200 media-service workspace-service billing-service
docker compose --env-file .env run --rm db-migrate -command version发生故障时，先阅读 故障排查 的分层诊断路径，再进行单服务重启或渠道降级。不要把“重启全部容器”当成默认修复方式。