Docker Compose 手动部署：完全掌控每一步

如果你需要「每一步都自己掌控」——指定端口、外接数据库、把前端挂到 CDN、只重启某一个服务 —— 那就走手动编排这条路。交付包里的 docker-compose.yml 就是完整拓扑，没有隐藏步骤。

一、四个容器各干什么

服务	作用	备注
postgres	唯一的数据来源（业务表 + 系统表）	命名卷 pg-data，默认 512M 内存上限
new-api	原生网关底座（官方镜像，零代码改动）	不对外暴露端口，只在内网被调用
yaka-ext	扩展层：计费、订阅、支付、发票、素材、站点设置等业务 API	健康检查依赖数据库
nginx	统一入口：静态资源 + API 反代 + TLS	只暴露 HTTP_PORT / HTTPS_PORT

二、拉包并准备 .env

sudo mkdir -p /opt/yaka && cd /opt/yaka
sudo curl -fsSLO https://yaka-dist.tos-cn-beijing.volces.com/releases/latest/yaka-instance.tar.gz
sudo tar -xzf yaka-instance.tar.gz && cd yaka-instance-*

cp .env.example .env
vi .env

必改项（其余保持默认即可）：

变量	怎么填
PUBLIC_BASE_URL	对外地址，带协议，例如 https://ai.example.com。支付回调、邮件链接都按它拼
PG_PASSWORD	强随机口令，别用默认的「请改成强口令」
DB_DSN	必须与 PG_PASSWORD 同步改，否则扩展层连不上库
SESSION_SECRET	随机会话密钥，泄露等于会话可伪造
NATIVE_ADMIN_PASSWORD	原生底座管理员口令，装完立刻改
HTTP_PORT	80 被占用时改（如 8088）
DEPLOY_EDITION	standard 或 premium；高级版必须同时把 BOOT_GRANT_REQUIRED 设为 1

generate 一个强口令： openssl rand -base64 24。不要在多个环境复用同一个。

三、启动

docker compose up -d
docker compose ps          # 等 postgres / yaka-ext 变 healthy

启动顺序由 compose 的 depends_on + 健康检查保证：数据库先就绪，扩展层再起，最后网关接入。 如果 yaka-ext 反复重启，先看它的日志，不要盲改配置：

docker compose logs -n 100 yaka-ext

四、改配置的正确姿势

这是最容易翻车的地方：改完 .env 必须重建容器。

# ✗ 错：restart 不会重新注入环境变量
docker compose restart yaka-ext

# ✓ 对：只重建这一个服务，不动数据库
docker compose up -d --no-deps --force-recreate yaka-ext

--no-deps 很关键：不加它，compose 会把依赖链上的容器一并重建， 在跑着的业务会被顺带重启一遍。

五、升级与回滚

# 升级前先备份
./backup.sh

# 替换 build/ 下的二进制 / 前端 / 迁移脚本后，只重建扩展层
docker compose up -d --no-deps --force-recreate yaka-ext

前端是挂载目录而不是打进镜像的，所以换前端产物不用重建镜像，清空目录再解包即可。 回滚 = 把备份里的 build/ 放回去再重建一次容器。

六、踩坑清单

现象	原因与处置
yaka-ext 一直 unhealthy，日志报连接数据库失败	DB_DSN 里的口令与 PG_PASSWORD 不一致。两处必须同步改。
口令里带 @ : / # % 导致连库失败	DSN 是 URL 结构，特殊字符必须百分号编码（如 @ → %40）。 拿不准就生成一个只含字母数字的口令。
改 .env 没生效	用了 restart。必须 --force-recreate。
反代到容器名后偶发 502	后端容器重启换了 IP，而反代缓存了旧 IP。给容器固定 ipv4_address， 或干脆反代到 127.0.0.1:HTTP_PORT 走网关。
2G 内存机器上 OOM	把 PG_MEM_LIMIT 调到 512m、EXT_MEM_LIMIT 调到 384m； 同时确认机器有 swap。
数据没了	执行过 down -v。命名卷被删，只能从备份恢复。