Docker Compose 部署

约 617 字大约 2 分钟

生产环境建议先在开发机或 CI 生成发布包，再上传服务器部署。不要在生产服务器上直接修改源码或临时编译服务。

服务器准备

Ubuntu 22.04/24.04 或兼容 Linux，建议从 4 核、8 GB 内存、80 GB SSD 起步；生产工作负载建议按生成并发提升规格。
Docker Engine 和 Docker Compose 插件，外部中间件模式要求 Compose 2.24.4 或更高版本。
一个 MySQL 8.x 实例；需要上传与生成结果时，准备对象存储 Bucket 和访问域名。
已解析的用户端与管理端域名，以及覆盖二者的 TLS 证书。
安全组仅开放 SSH、80 与 443；禁止将数据库、Redis、Gateway 和业务服务端口暴露公网。

构建发布包

在仓库根目录执行：

powershell -ExecutionPolicy Bypass -File deploy/scripts/package-local.ps1

依赖已安装时可追加 -SkipInstall。构建成功后，检查 release/ 中的压缩包，确认包含 docker-compose.yml、.env.example、应用产物、Nginx 和脚本目录。

首次部署

mkdir -p /mnt/frameai
cd /mnt/frameai
tar --strip-components=1 -xzf /path/to/ad-canvas-<time>.tar.gz
cp .env.example .env

编辑 .env，至少替换数据库密码、所有 change-this-* 密钥、域名、公共访问地址以及对象存储配置。不要将真实 .env 提交到代码仓库或发送到不可信位置。

验证与启动：

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
docker compose --env-file .env logs --tail=200 db-migrate

外部 MySQL 模式

若 MySQL/Redis 由外部维护，使用 docker-compose.external-middleware.yml：

cp .env.external-middleware.example .env
export COMPOSE_FILE=docker-compose.yml:docker-compose.external-middleware.yml
docker compose --env-file .env config --quiet
docker compose --env-file .env run --rm db-migrate -command version
docker compose --env-file .env run --rm db-migrate
docker compose --env-file .env up -d --build

确认合并后的服务列表不包含 mysql 或 redis。外部数据库必须限制来源，只允许 FrameAI Docker 主机或指定私网访问。

上线验证

所有业务服务状态为运行，db-migrate 已成功完成。
用户端、管理端和 /health 检查可访问。
完成登录、素材上传、最小生成任务和后台渠道检查。
查看 Gateway、生成服务、媒体服务和 Nginx 日志中是否存在配置或认证错误。

详细的新服务器流程见仓库根目录的 deploy/新服务器完整部署文档.md。