Coze Docker部署教程｜生产环境实测

本文面向希望在服务器上使用 Docker / Docker Compose 部署 Coze 开源项目的开发者、运维人员和团队管理员。内容会尽量按照生产环境思路来写，包括服务器准备、Docker 安装、项目部署、环境变量配置、反向代理、HTTPS、数据持久化、备份、升级以及常见问题排查。

一、前言

Coze 是一个用于构建 AI Agent / 智能体应用的平台，适合用来搭建对话机器人、知识库问答系统、工作流自动化应用等。对于企业或团队来说，如果只是体验，可以使用官方提供的在线服务；但如果有以下需求，自建部署会更加合适：

• 希望数据部署在自己的服务器中；
• 希望接入内部系统、私有知识库或内网 API；
• 希望进行二次开发或深度定制；
• 希望掌控运行环境、日志、资源和安全策略；
• 希望在生产环境长期稳定运行。

本文将以 Docker 方式部署 Coze，并结合生产环境中的常见配置进行说明。相比直接源码运行，Docker 部署的优势是环境隔离好、迁移方便、服务管理简单，也更适合后期升级和运维。

二、部署前准备

1. 服务器配置建议

如果只是测试，2 核 4G 的云服务器也能跑起来。但如果用于生产环境，尤其涉及知识库、工作流、多用户访问，建议至少准备以下配置：

操作系统推荐：

• Ubuntu 22.04 LTS
• Ubuntu 24.04 LTS
• Debian 12
• CentOS Stream / Rocky Linux 也可以，但命令略有差异

本文示例以 Ubuntu 22.04 为主。

2. 域名与端口准备

生产环境建议使用域名访问，例如：

coze.example.com

需要开放的端口：

如果使用云服务器，需要在安全组中放行 80 和 443 端口。

3. 安装基础工具

登录服务器后，先更新系统：

sudo apt update && sudo apt upgrade -y

安装常用工具：

sudo apt install -y curl wget git vim unzip ca-certificates gnupg lsb-release

三、安装 Docker 与 Docker Compose

1. 安装 Docker

使用官方安装脚本是比较简单的方式：

curl -fsSL https://get.docker.com | bash

安装完成后查看版本：

docker -v

示例输出：

Docker version 27.x.x, build xxxxxxx

启动并设置开机自启：

sudo systemctl enable docker
sudo systemctl start docker

如果希望当前用户无需每次使用 sudo 执行 Docker 命令，可以执行：

sudo usermod -aG docker $USER

然后重新登录服务器。

2. 安装 Docker Compose

新版本 Docker 通常已经自带 Compose 插件，可以检查：

docker compose version

如果能看到类似输出，说明已经安装：

Docker Compose version v2.x.x

如果没有，可以手动安装 Docker Compose 插件：

sudo apt install -y docker-compose-plugin

四、获取 Coze 项目代码

进入推荐的应用目录：

sudo mkdir -p /opt/apps
sudo chown -R $USER:$USER /opt/apps
cd /opt/apps

克隆 Coze 项目代码：

git clone https://github.com/coze-dev/coze-studio.git
cd coze-studio

说明：实际部署时请以官方仓库最新文档为准。开源项目可能会调整目录结构、环境变量名称或 Compose 配置。

查看项目目录：

ls -la

一般来说，项目中会包含 Docker 相关配置，例如：

docker-compose.yml
.env.example
backend/
frontend/
...

如果项目提供了专门的 Docker 部署目录，也可以进入对应目录，例如：

cd docker

具体以仓库实际结构为准。

五、配置环境变量

生产环境部署前，最重要的一步就是修改环境变量。不要直接使用默认配置上线。

通常项目会提供 .env.example 文件，可以复制一份：

cp .env.example .env

然后编辑：

vim .env

常见需要关注的配置包括：

1. 基础访问地址

例如：

APP_URL=https://coze.example.com
WEB_URL=https://coze.example.com
API_URL=https://coze.example.com/api

如果项目区分前端地址、后端地址、回调地址，必须保持和最终访问域名一致，否则可能出现登录失败、接口跨域、回调错误等问题。

2. 数据库配置

如果使用 Docker Compose 内置数据库，通常会有类似配置：

MYSQL_DATABASE=coze
MYSQL_USER=coze
MYSQL_PASSWORD=请改成强密码
MYSQL_ROOT_PASSWORD=请改成更强的密码

生产环境建议：

• 密码长度不少于 16 位；
• 包含大小写字母、数字和特殊字符；
• 不要使用 123456、password、admin 等弱密码；
• 不要把 .env 文件提交到公开仓库。

如果使用外部数据库，例如独立 MySQL 或 PostgreSQL，需要修改主机、端口、用户名和密码：

DB_HOST=10.0.0.10
DB_PORT=3306
DB_USER=coze
DB_PASSWORD=StrongPassword
DB_NAME=coze

3. Redis 配置

多数 AI 应用都会使用 Redis 缓存、会话或队列。示例：

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=StrongRedisPassword

生产环境中，如果 Redis 暴露到公网是非常危险的。建议：

• Redis 仅监听内网；
• 使用强密码；
• 不直接映射 6379 到公网；
• 必要时使用云厂商托管 Redis。

4. 对象存储配置

如果 Coze 需要上传文件、知识库文档、图片或插件资源，通常会用到对象存储。生产环境不建议把所有上传文件直接放容器里，因为容器重建后可能丢失。

可以使用：

• MinIO 自建对象存储；
• 阿里云 OSS；
• 腾讯云 COS；
• AWS S3；
• 其他兼容 S3 协议的存储。

示例配置：

STORAGE_TYPE=s3
S3_ENDPOINT=https://oss.example.com
S3_BUCKET=coze
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=auto

如果 Compose 中自带 MinIO，也要修改默认账号密码：

MINIO_ROOT_USER=cozeadmin
MINIO_ROOT_PASSWORD=StrongMinioPassword

5. 大模型 API 配置

Coze 的核心功能离不开大模型服务。根据你使用的模型提供商，配置方式不同。常见有：

OPENAI_API_KEY=sk-xxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1

如果使用国内模型服务商，可能需要配置对应的 API 地址和密钥，例如：

MODEL_PROVIDER=custom
MODEL_API_KEY=your-api-key
MODEL_BASE_URL=https://your-model-provider/v1

生产环境建议：

• 不要把 API Key 写进前端代码；
• 限制 Key 的额度和权限；
• 定期轮换密钥；
• 对异常调用进行监控。

六、启动 Coze 服务

环境变量配置完成后，使用 Docker Compose 启动：

docker compose up -d

第一次启动需要拉取镜像或构建镜像，时间会比较久。可以查看容器状态：

docker compose ps

查看日志：

docker compose logs -f

如果只想看某个服务日志，例如后端：

docker compose logs -f backend

如果看到类似以下状态，说明容器基本启动成功：

STATUS
Up
healthy

七、初始化数据库与管理员账号

部分项目第一次启动后会自动初始化数据库；也有项目需要手动执行迁移命令。具体命令以项目文档为准，常见形式如下：

docker compose exec backend sh

进入容器后执行：

npm run migrate

或：

pnpm run db:migrate

也可能是 Go / Python 项目命令，例如：

./bin/migrate

初始化管理员账号通常有三种方式：

1. 通过 Web 页面首次注册；
2. 通过环境变量预设管理员；
3. 通过命令行创建管理员。

如果支持环境变量，可能类似：

ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=StrongAdminPassword

生产环境中，管理员密码一定要足够强，并建议开启多因素认证或至少限制后台访问来源。

八、配置 Nginx 反向代理

为了让用户通过域名访问，并使用 HTTPS，生产环境建议在服务器上部署 Nginx 作为反向代理。

安装 Nginx：

sudo apt install -y nginx

假设 Coze 前端服务在本机 3000 端口，后端服务在 8080 端口。实际端口请以 docker-compose.yml 中映射为准。

创建站点配置：

sudo vim /etc/nginx/sites-available/coze.conf

写入以下内容：

server {
    listen 80;
    server_name coze.example.com;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/coze.conf /etc/nginx/sites-enabled/coze.conf

检查配置：

sudo nginx -t

重载 Nginx：

sudo systemctl reload nginx

此时可以先通过 HTTP 访问：

http://coze.example.com

九、配置 HTTPS 证书

推荐使用 Certbot 申请 Let’s Encrypt 免费证书。

安装 Certbot：

sudo apt install -y certbot python3-certbot-nginx

申请证书：

sudo certbot --nginx -d coze.example.com

按提示选择是否自动跳转 HTTPS。建议开启 HTTP 到 HTTPS 的强制跳转。

申请成功后测试续期：

sudo certbot renew --dry-run

如果成功，说明自动续期没有问题。

十、生产环境安全建议

1. 不要暴露内部端口

Docker Compose 中经常会看到端口映射，例如：

ports:
  - "3000:3000"
  - "8080:8080"
  - "3306:3306"
  - "6379:6379"

生产环境中，数据库和 Redis 不应该暴露公网。建议只暴露前端或网关端口，其他服务仅在 Docker 网络中通信。

例如数据库服务可以只保留：

expose:
  - "3306"

而不是：

ports:
  - "3306:3306"

2. 配置防火墙

Ubuntu 可以使用 UFW：

sudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable

查看状态：

sudo ufw status

如果你的 Docker 容器映射了额外端口，需要确认是否真的要对外开放。

3. 定期更新系统和镜像

生产环境不能长期不更新。建议定期执行：

sudo apt update && sudo apt upgrade -y

更新 Coze 代码：

cd /opt/apps/coze-studio
git pull

重新拉取镜像并启动：

docker compose pull
docker compose up -d

如果项目是本地构建镜像：

docker compose build
docker compose up -d

升级前务必备份数据库和文件。

4. 日志管理

Docker 日志如果不限制，可能会占满磁盘。建议配置 Docker 日志大小限制。

编辑：

sudo vim /etc/docker/daemon.json

写入：

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "200m",
    "max-file": "5"
  }
}

重启 Docker：

sudo systemctl restart docker

然后重新启动项目：

cd /opt/apps/coze-studio
docker compose up -d

十一、数据备份方案

生产环境中，备份比部署更重要。至少需要备份以下内容：

1. 数据库；
2. 对象存储或上传文件；
3. .env 配置文件；
4. Nginx 配置；
5. Docker Compose 配置；
6. 自定义插件或二次开发代码。

1. MySQL 备份示例

如果数据库容器名是 coze-mysql，可以执行：

docker exec coze-mysql mysqldump -uroot -p coze > coze_$(date +%F).sql

如果需要自动备份，可以创建脚本：

mkdir -p /opt/backup/coze
vim /opt/backup/coze/backup.sh

写入：

#!/bin/bash

BACKUP_DIR="/opt/backup/coze"
DATE=$(date +%F_%H-%M-%S)

docker exec coze-mysql mysqldump -uroot -p'你的数据库密码' coze > $BACKUP_DIR/coze_$DATE.sql

find $BACKUP_DIR -name "*.sql" -mtime +14 -delete

赋予执行权限：

chmod +x /opt/backup/coze/backup.sh

加入定时任务：

crontab -e

每天凌晨 2 点备份：

0 2 * * * /opt/backup/coze/backup.sh

2. 文件备份

如果你使用的是本地挂载目录，例如：

/opt/apps/coze-studio/data

可以用 tar 打包：

tar -czf /opt/backup/coze/coze_data_$(date +%F).tar.gz /opt/apps/coze-studio/data

如果使用对象存储，则建议开启对象存储自身的版本控制、生命周期管理和跨区域备份。

十二、升级与回滚

生产环境升级前建议执行以下流程：

1. 查看官方 Release Note；
2. 确认是否有数据库变更；
3. 备份数据库和文件；
4. 拉取新代码或新镜像；
5. 在测试环境先跑一遍；
6. 生产环境低峰期升级；
7. 升级后观察日志和核心功能。

升级命令通常如下：

cd /opt/apps/coze-studio
git pull
docker compose pull
docker compose up -d

如果升级后出现问题，可以尝试回滚代码版本：

git log --oneline
git checkout <旧版本commit>
docker compose up -d

如果数据库已经迁移，回滚会更复杂，因此升级前数据库备份非常关键。

十三、常见问题排查

1. 容器启动失败

查看容器状态：

docker compose ps

查看日志：

docker compose logs -f

常见原因：

• 环境变量缺失；
• 数据库密码错误；
• 端口被占用；
• 镜像拉取失败；
• 磁盘空间不足；
• 服务启动顺序问题。

检查端口占用：

sudo lsof -i :3000
sudo lsof -i :8080

2. 页面能打开，但接口报错

这种情况通常是前后端地址配置不一致，或者 Nginx 代理路径写错。

重点检查：

• .env 中的 API_URL；
• Nginx 的 /api/ 转发规则；
• 后端容器是否正常；
• 浏览器控制台 Network 请求地址；
• 是否存在跨域问题。

3. 登录失败或回调异常

如果登录依赖 OAuth、SSO 或第三方授权，需要确认回调地址和公网域名完全一致。

例如系统访问地址是：

https://coze.example.com

那么回调地址也应使用 HTTPS 域名，而不是：

http://127.0.0.1:3000

4. 上传文件失败

可能原因包括：

• Nginx 限制上传大小；
• 对象存储配置错误；
• 容器没有写入权限；
• 磁盘空间不足；
• MinIO Access Key / Secret Key 错误。

Nginx 中可以设置：

client_max_body_size 100m;

如果上传知识库文件较大，可以适当调高。

5. 服务运行一段时间变慢

建议检查：

docker stats

查看 CPU、内存占用。

检查磁盘：

df -h

检查 Docker 占用：

docker system df

清理无用镜像和缓存：

docker system prune -a

注意：清理前确认不会删除仍需使用的镜像或缓存。

十四、生产环境实测经验总结

结合实际部署经验，Coze 这类 AI 应用在生产环境中最容易遇到的问题，不是“能不能启动”，而是“能不能稳定运行”。

以下几点尤其重要：

1. 数据库和对象存储要认真规划

测试环境中，把所有服务都放在一个 Docker Compose 里很方便。但生产环境建议至少将数据库数据卷、上传文件、对象存储单独规划，并做好备份。否则服务器一旦磁盘损坏或误操作，恢复成本会非常高。

2. 模型 API 的稳定性直接影响体验

如果大模型 API 延迟高、限流严重或经常超时，用户会认为是 Coze 系统不稳定。因此建议配置可用性较高的模型服务，并为关键应用设置超时、重试和监控策略。

3. 日志一定要限制大小

Docker 默认日志很容易在长时间运行后占满磁盘。生产环境必须配置日志滚动，否则某一天系统突然无法登录、容器无法启动，很多时候就是磁盘满了。

4. HTTPS 和回调地址要一次配对

AI Agent 平台经常涉及插件、OAuth、Webhook、API 调用等能力。如果公网地址、系统地址、回调地址不一致，后期会出现各种看似复杂的问题。建议部署之初就统一使用 HTTPS 域名。

5. 升级前必须备份

开源项目迭代速度快，升级可能涉及数据库结构变化。不要在没有备份的情况下直接 git pull 然后重启。生产环境一定要遵循“先备份、再升级、可回滚”的原则。

十五、结语

通过 Docker 部署 Coze 并不复杂，核心流程可以概括为：

准备服务器 → 安装 Docker → 获取项目代码 → 配置环境变量 → 启动服务 → 配置 Nginx → 启用 HTTPS → 做好备份和监控

如果只是体验，按照官方 Docker Compose 启动即可；但如果用于生产环境，就必须重点关注安全、持久化、备份、日志、升级和外部依赖稳定性。

本文提供的是一套较完整的生产环境部署思路。实际操作时，建议始终结合 Coze 官方文档、项目 Release Note 以及自身业务规模进行调整。对于小团队来说，单机 Docker Compose 已经足够支撑早期使用；对于企业级场景，则可以进一步拆分数据库、Redis、对象存储、模型网关和应用服务，逐步演进到更高可用的架构。