每个人都可以，
拥有SSL证书

最近用 Docker Compose 部署 Coze，连着踩了几个坑，有些是老问题，但隔段时间不碰又绕进去了。顺便把 Compose 配置修改之后怎么让它生效也理一遍，下次不用再去翻文档猜。

先记 Coze 部署时碰到的两个典型状况，这两个问题在群里也经常看到有人问。

注册/登录点了没反应

部署完访问页面，注册按钮点下去啥也不发生，Chrome 控制台开始报错。这类问题多半不是代码的锅，得从网络、依赖和前端资源三块去查。

我习惯先确认后端服务能不能正常访问。在服务器上 curl 一下健康检查接口：

curl -v http://<服务器IP>:<端口>/api/health

如果不通，先看端口在不在监听，再看防火墙。服务器上如果装了宝塔，它的防火墙跟系统防火墙是两套，端口需要在面板里单独放行。同时系统层面也要确认，比如 ufw：

ufw allow 8080/tcp

网络没问题之后，看一眼容器状态。docker compose ps 看所有 service 是不是都在 running，状态异常的用 logs 查：

docker compose -f docker-compose.yml ps
docker logs coze-web | grep -i "error"

这里很多人会忽略前端资源加载失败。按钮没响应，有时是因为前端引用的 js 文件直接 404 了。打开浏览器 Network 面板，刷新页面，看有没有红色的请求。如果静态资源路径错，大概率是 nginx 的代理没写对。类似这样一段要确认：

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
}

代理目标的端口要和前端容器实际监听的端口一致，否则请求就打到了错误的地方。

启动就 panic，报 config.yaml 不存在

错误长得像这样：

panic: InitializeInfra failed, err=open /app/resources/conf/workflow/config.yaml: no such file

这个一看就是容器里没挂载到配置文件。先去检查 docker-compose.yml 里该服务的 volumes 段落，类似：

volumes:
  - /path/to/host/config:/app/resources/conf

到宿主机上 ls 一下 /path/to/host/config 下面是不是真的有 workflow/config.yaml。没有的话就对照项目文档补上去。文件存在还报错，就检查权限，给成 644 一般够用：

chmod 644 /path/to/host/config/workflow/config.yaml

改完权限或补完文件之后，不能只 restart，得把旧的匿名卷清掉再重建，否则容器可能还在用之前没挂载成功时的空白卷：

docker compose -f docker-compose.yml down --volumes
docker compose -f docker-compose.yml up -d --build

--volumes 会把 compose 创建的卷一并删掉，注意别误删了有数据的命名卷，使用前先确认一下自己 compose 文件里的卷定义。

再回过头说 Docker Compose 配置修改之后怎么让它生效，这个跟上面排查的问题经常连着。改了配置但发现没反应，就是没搞对生效方式。

只是动了一下环境变量或者非关键配置

这种情况下，理论上直接重启容器就行，不需要重建镜像。操作就是：

docker compose -f docker-compose.yml restart web

或者重启全部服务：

docker compose -f docker-compose.yml restart

restart 只会重启容器里的主进程，不拉新镜像，也不重建容器，所以很快。

但有个细节要注意——如果改的是 .env 文件里的变量，restart 很多时候不会更新容器里已经注入的环境变量，因为容器创建时变量就已经写死了。这时候得用 down/up 或者 up -d --force-recreate，不然变量还是旧的。线上跑起来问题就出来了，我一开始也以为 restart 能搞定，后来发现不是。

改了镜像版本、端口映射或者 Dockerfile

这些就必须要重建了。可以用 up 带 --build 参数，让它根据当前 Dockerfile 重新构建镜像然后启动：

docker compose -f docker-compose.yml up -d --build web

如果是大改，更稳的做法是先 down 掉再重新 up：

docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml up -d --build

down 会停容器并删除网络等资源，加 --volumes 会连卷一起删（刚才提过，谨慎使用）。这个组合相当于全新部署一次，一些奇奇怪怪的状态会被清干净。

.env 文件和 docker-compose.yml 的配合也顺带记一下，经常有人把两个文件的关系弄混。

docker-compose.yml 定义的是服务、网络、卷这些“架构”层面的东西，而 .env 是用来集中放环境变量，特别是数据库密码、API 密钥这种不能提交到代码仓库里的配置。

所以 .env 一定要写到 .gitignore 里，否则把密码传上去再改就麻烦了。

变量引用方式很简单，compose 文件里用 ${VAR} 就行：

services:
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}

.env 里配：

DB_PASSWORD=secure123

启动时 docker compose up -d 会自动加载同目录下的 .env 文件。要是怀疑变量没被替换，可以进容器打印一下环境变量确认：

docker exec -it db_container env | grep MYSQL_ROOT_PASSWORD

如果输出是 MYSQL_ROOT_PASSWORD=secure123，那就没问题。

这些配置改完之后，也别忘了顺手备份一下 docker-compose.yml 和挂载出来的配置文件目录。很多时候服务挂了不是代码的问题，而是配置文件被误删或者回滚时丢掉了，定期备一份能省很多事。