Coze Docker部署教程｜附配置文件

Coze 是一套用于构建 AI Agent、智能体应用和工作流应用的平台。对于希望在本地服务器、云服务器或内网环境中部署 Coze 的团队来说，使用 Docker 进行部署是相对稳定、可维护且便于迁移的方式。本文将以一台 Linux 服务器为例，完整介绍 Coze 的 Docker 部署流程，并附上常用配置文件示例，方便你快速搭建一套可运行的 Coze 环境。

说明：不同版本的 Coze 开源项目在目录结构、服务名称、环境变量上可能略有差异。本文提供的是通用 Docker 部署思路和配置模板，实际部署时建议结合官方仓库中的 README、.env.example、docker-compose.yml 等文件进行调整。

一、部署前准备

在正式部署 Coze 之前，需要准备一台服务器，并确保服务器可以正常访问 Docker 镜像仓库、GitHub 或项目代码仓库。

1. 服务器配置建议

如果只是用于学习、测试或个人使用，可以选择较低配置；如果用于团队生产环境，则建议配置更高。

操作系统建议使用：

• Ubuntu 20.04 / 22.04
• Debian 11 / 12
• CentOS Stream / Rocky Linux / AlmaLinux

本文以 Ubuntu 22.04 为例进行说明。

二、安装 Docker 和 Docker Compose

如果你的服务器已经安装了 Docker，可以跳过本章节。

1. 更新系统软件包

sudo apt update
sudo apt upgrade -y

2. 安装必要依赖

sudo apt install -y ca-certificates curl gnupg lsb-release

3. 安装 Docker

可以直接使用官方安装脚本：

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

安装完成后，查看 Docker 版本：

docker version

启动 Docker 并设置开机自启：

sudo systemctl enable docker
sudo systemctl start docker

4. 安装 Docker Compose

新版 Docker 通常自带 Compose 插件，可以通过以下命令确认：

docker compose version

如果能够正常输出版本号，说明 Docker Compose 已安装成功。

三、创建 Coze 部署目录

建议将 Coze 部署文件统一放在 /opt/coze 目录下，方便后续维护。

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

目录结构建议如下：

/opt/coze
├── docker-compose.yml
├── .env
├── nginx
│   └── coze.conf
├── data
│   ├── mysql
│   ├── redis
│   ├── minio
│   └── coze
└── logs

创建相关目录：

mkdir -p nginx data/mysql data/redis data/minio data/coze logs

四、准备环境变量配置文件

在 Docker 部署中，.env 文件非常重要。它通常用于配置数据库账号、Redis 密码、访问域名、对象存储参数、模型 API Key 等信息。

在 /opt/coze 目录下创建 .env 文件：

vim .env

参考配置如下：

# ===============================
# Coze 基础配置
# ===============================

# 服务运行环境，可选：development / production
APP_ENV=production

# Coze Web 访问地址
# 如果使用域名，请改成你的域名，例如：https://coze.example.com
COZE_WEB_URL=http://127.0.0.1:8080

# 后端 API 地址
COZE_API_URL=http://127.0.0.1:8080

# JWT 密钥，生产环境请务必改成复杂随机字符串
JWT_SECRET=please_change_this_jwt_secret

# 会话加密密钥，生产环境请务必修改
SESSION_SECRET=please_change_this_session_secret


# ===============================
# MySQL 数据库配置
# ===============================

MYSQL_ROOT_PASSWORD=coze_root_password
MYSQL_DATABASE=coze
MYSQL_USER=coze
MYSQL_PASSWORD=coze_password

# 数据库连接地址，容器内访问使用服务名 mysql
DB_HOST=mysql
DB_PORT=3306
DB_NAME=coze
DB_USER=coze
DB_PASSWORD=coze_password


# ===============================
# Redis 配置
# ===============================

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=coze_redis_password


# ===============================
# MinIO 对象存储配置
# ===============================

MINIO_ROOT_USER=coze_minio
MINIO_ROOT_PASSWORD=coze_minio_password
MINIO_BUCKET=coze
MINIO_ENDPOINT=http://minio:9000
MINIO_PUBLIC_ENDPOINT=http://127.0.0.1:9000


# ===============================
# 大模型 API 配置
# ===============================

# OpenAI 兼容接口地址
OPENAI_BASE_URL=https://api.openai.com/v1

# OpenAI API Key
OPENAI_API_KEY=sk-your-api-key

# 默认模型名称，可按实际情况修改
DEFAULT_MODEL=gpt-4o-mini


# ===============================
# 服务端口配置
# ===============================

# Coze 对外访问端口
COZE_PORT=8080

# MinIO 控制台端口
MINIO_CONSOLE_PORT=9001

配置说明

其中几个参数尤其需要注意：

1. COZE_WEB_URL
   用于配置 Coze 前端访问地址。如果你使用 IP 访问，可以填写 http://服务器IP:8080；如果使用域名和 HTTPS，则填写类似 https://coze.example.com。

2. JWT_SECRET 和 SESSION_SECRET
   这两个参数一定要修改，不能使用示例值。可以使用以下命令生成随机字符串：

   openssl rand -hex 32

3. OPENAI_BASE_URL 和 OPENAI_API_KEY
   如果你使用 OpenAI 官方接口，就填写官方地址和 Key；如果使用兼容 OpenAI 格式的第三方模型服务，也可以将地址改为对应服务商的接口地址。

4. MINIO_PUBLIC_ENDPOINT
   如果 Coze 需要从浏览器访问上传文件或图片资源，该地址需要配置成外部可访问地址。

五、编写 Docker Compose 配置文件

接下来在 /opt/coze 目录下创建 docker-compose.yml 文件。

vim docker-compose.yml

以下是一个完整的参考配置：

version: "3.9"

services:
  mysql:
    image: mysql:8.0
    container_name: coze-mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      TZ: Asia/Shanghai
    command:
      [
        "--default-authentication-plugin=mysql_native_password",
        "--character-set-server=utf8mb4",
        "--collation-server=utf8mb4_unicode_ci"
      ]
    ports:
      - "3306:3306"
    volumes:
      - ./data/mysql:/var/lib/mysql
    networks:
      - coze-net

  redis:
    image: redis:7.2
    container_name: coze-redis
    restart: always
    command: redis-server --requirepass ${REDIS_PASSWORD}
    ports:
      - "6379:6379"
    volumes:
      - ./data/redis:/data
    networks:
      - coze-net

  minio:
    image: minio/minio:latest
    container_name: coze-minio
    restart: always
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
      TZ: Asia/Shanghai
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "${MINIO_CONSOLE_PORT}:9001"
    volumes:
      - ./data/minio:/data
    networks:
      - coze-net

  coze:
    image: coze/coze:latest
    container_name: coze-app
    restart: always
    depends_on:
      - mysql
      - redis
      - minio
    environment:
      APP_ENV: ${APP_ENV}
      COZE_WEB_URL: ${COZE_WEB_URL}
      COZE_API_URL: ${COZE_API_URL}

      JWT_SECRET: ${JWT_SECRET}
      SESSION_SECRET: ${SESSION_SECRET}

      DB_HOST: ${DB_HOST}
      DB_PORT: ${DB_PORT}
      DB_NAME: ${DB_NAME}
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}

      REDIS_HOST: ${REDIS_HOST}
      REDIS_PORT: ${REDIS_PORT}
      REDIS_PASSWORD: ${REDIS_PASSWORD}

      MINIO_BUCKET: ${MINIO_BUCKET}
      MINIO_ENDPOINT: ${MINIO_ENDPOINT}
      MINIO_PUBLIC_ENDPOINT: ${MINIO_PUBLIC_ENDPOINT}
      MINIO_ACCESS_KEY: ${MINIO_ROOT_USER}
      MINIO_SECRET_KEY: ${MINIO_ROOT_PASSWORD}

      OPENAI_BASE_URL: ${OPENAI_BASE_URL}
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      DEFAULT_MODEL: ${DEFAULT_MODEL}

      TZ: Asia/Shanghai
    ports:
      - "${COZE_PORT}:8080"
    volumes:
      - ./data/coze:/app/data
      - ./logs:/app/logs
    networks:
      - coze-net

networks:
  coze-net:
    driver: bridge

注意：coze/coze:latest 仅作为示例镜像名称。如果你使用的是官方开源仓库提供的镜像，请替换为官方实际镜像地址。如果官方要求从源码构建镜像，则需要先执行 docker build 或使用官方提供的 Compose 文件。

六、初始化 MinIO 存储桶

MinIO 用于存放 Coze 运行过程中产生的文件、图片、素材、插件资源等。启动服务后，需要创建一个 bucket。

先启动 MySQL、Redis 和 MinIO：

docker compose up -d mysql redis minio

查看容器运行状态：

docker compose ps

如果状态均为 running，说明基础组件启动成功。

浏览器访问 MinIO 控制台：

http://服务器IP:9001

登录账号密码对应 .env 中的：

MINIO_ROOT_USER=coze_minio
MINIO_ROOT_PASSWORD=coze_minio_password

登录后创建一个名为 coze 的 bucket。如果你在 .env 中修改了 MINIO_BUCKET，则 bucket 名称要与配置保持一致。

也可以通过 MinIO 客户端自动创建：

docker run --rm --network coze_coze-net \
  minio/mc:latest \
  sh -c "mc alias set local http://minio:9000 coze_minio coze_minio_password && mc mb -p local/coze"

如果你的 Compose 项目网络名称不是 coze_coze-net，可以通过以下命令查看：

docker network ls

七、启动 Coze 服务

基础服务准备完成后，可以启动 Coze 主服务：

docker compose up -d

查看所有容器：

docker compose ps

查看 Coze 日志：

docker compose logs -f coze

如果日志中没有明显报错，并且显示服务已启动，可以在浏览器访问：

http://服务器IP:8080

如果你在 .env 中将 COZE_PORT 改成了其他端口，则访问对应端口即可。

八、配置 Nginx 反向代理

在生产环境中，不建议直接使用 服务器IP:8080 访问 Coze。更推荐使用域名，并通过 Nginx 做反向代理。如果需要 HTTPS，可以配合 Certbot 申请免费 SSL 证书。

1. 安装 Nginx

sudo apt install -y nginx

2. 创建 Nginx 配置文件

假设你的域名是：

coze.example.com

创建配置文件：

sudo vim /etc/nginx/conf.d/coze.conf

写入以下内容：

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

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:8080;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Real-IP $remote_addr;
        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";

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

检查 Nginx 配置：

sudo nginx -t

重载 Nginx：

sudo systemctl reload nginx

然后修改 .env 中的访问地址：

COZE_WEB_URL=http://coze.example.com
COZE_API_URL=http://coze.example.com
MINIO_PUBLIC_ENDPOINT=http://coze.example.com

修改完成后重启 Coze：

docker compose restart coze

九、配置 HTTPS 证书

如果你希望通过 HTTPS 访问 Coze，可以使用 Certbot 自动申请 Let’s Encrypt 免费证书。

1. 安装 Certbot

sudo apt install -y certbot python3-certbot-nginx

2. 申请证书

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

按照提示选择是否自动跳转 HTTPS。完成后，访问：

https://coze.example.com

同时建议将 .env 修改为 HTTPS 地址：

COZE_WEB_URL=https://coze.example.com
COZE_API_URL=https://coze.example.com
MINIO_PUBLIC_ENDPOINT=https://coze.example.com

重启服务：

docker compose restart coze

十、模型接口配置

Coze 的核心能力依赖大模型接口。你可以选择 OpenAI、Azure OpenAI、国内大模型厂商，或者任何兼容 OpenAI API 格式的服务。

如果使用 OpenAI 官方接口，配置示例：

OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
DEFAULT_MODEL=gpt-4o-mini

如果使用兼容接口，例如某些网关或代理服务：

OPENAI_BASE_URL=https://your-llm-gateway.example.com/v1
OPENAI_API_KEY=your-api-key
DEFAULT_MODEL=your-model-name

修改 .env 后重启服务：

docker compose restart coze

如果页面中仍无法调用模型，可以查看日志：

docker compose logs -f coze

重点检查以下问题：

• API Key 是否正确；
• 模型名称是否存在；
• 服务器是否可以访问模型接口；
• 接口地址是否需要 /v1；
• 是否存在网络代理、防火墙或 DNS 问题。

十一、常用运维命令

1. 启动服务

docker compose up -d

2. 停止服务

docker compose down

3. 重启服务

docker compose restart

4. 查看服务状态

docker compose ps

5. 查看日志

查看全部日志：

docker compose logs -f

查看单个服务日志：

docker compose logs -f coze
docker compose logs -f mysql
docker compose logs -f redis
docker compose logs -f minio

6. 进入容器

docker exec -it coze-app bash

如果容器内没有 bash，可以使用：

docker exec -it coze-app sh

十二、数据备份与恢复

在 Docker 部署中，最重要的数据通常包括：

• MySQL 数据；
• MinIO 文件数据；
• Redis 缓存数据；
• Coze 应用数据与日志。

1. 备份 MySQL

docker exec coze-mysql mysqldump \
  -uroot \
  -p${MYSQL_ROOT_PASSWORD} \
  coze > backup-coze.sql

如果命令中无法读取环境变量，可以直接写密码：

docker exec coze-mysql mysqldump \
  -uroot \
  -pcoze_root_password \
  coze > backup-coze.sql

2. 恢复 MySQL

cat backup-coze.sql | docker exec -i coze-mysql mysql \
  -uroot \
  -pcoze_root_password \
  coze

3. 备份数据目录

tar czvf coze-data-backup.tar.gz /opt/coze/data /opt/coze/.env /opt/coze/docker-compose.yml

4. 恢复数据目录

停止服务：

docker compose down

解压备份：

tar xzvf coze-data-backup.tar.gz -C /

重新启动：

cd /opt/coze
docker compose up -d

生产环境建议每天备份数据库，并定期将备份文件同步到其他服务器或对象存储中，避免单点故障导致数据丢失。

十三、升级 Coze

如果你使用的是镜像部署，可以通过以下方式升级：

cd /opt/coze
docker compose pull
docker compose up -d

升级前建议先备份：

tar czvf coze-before-upgrade.tar.gz /opt/coze

如果项目涉及数据库迁移，升级后需要关注容器日志，确认迁移是否成功：

docker compose logs -f coze

如果升级后出现异常，可以回滚到之前的镜像版本。为了方便回滚，生产环境不建议长期使用 latest 标签，建议指定明确版本，例如：

image: coze/coze:v1.0.0

这样可以避免镜像自动更新导致不可预期的问题。

十四、常见问题排查

1. 页面打不开

可以按以下顺序排查：

docker compose ps
docker compose logs -f coze
sudo ss -tunlp | grep 8080

确认：

• Coze 容器是否运行；
• 端口是否正确映射；
• 服务器防火墙是否放行端口；
• 云服务器安全组是否放行端口；
• Nginx 反向代理地址是否正确。

2. 数据库连接失败

查看 MySQL 是否正常：

docker compose logs -f mysql

进入 MySQL 容器测试：

docker exec -it coze-mysql mysql -uroot -p

重点检查 .env 中的数据库用户名、密码、数据库名称是否与 docker-compose.yml 保持一致。

3. Redis 连接失败

查看 Redis 日志：

docker compose logs -f redis

测试 Redis：

docker exec -it coze-redis redis-cli -a coze_redis_password ping

如果返回：

PONG

说明 Redis 正常。

4. 文件上传失败

文件上传失败通常与 MinIO 配置有关。需要检查：

• bucket 是否已创建；
• MINIO_ENDPOINT 是否为容器内可访问地址；
• MINIO_PUBLIC_ENDPOINT 是否为浏览器可访问地址；
• Access Key 和 Secret Key 是否正确；
• Nginx 是否限制了上传文件大小。

如果上传大文件失败，可以在 Nginx 中增加：

client_max_body_size 100m;

5. 模型调用失败

模型调用失败可能由以下原因造成：

• API Key 错误；
• 模型名称错误；
• 服务商接口地址错误；
• 服务器无法访问外部接口；
• 账号余额不足；
• 接口限流；
• 请求格式不兼容。

可以进入容器中使用 curl 测试接口连通性：

docker exec -it coze-app sh
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

十五、安全加固建议

如果你准备将 Coze 部署到公网环境，建议至少完成以下安全配置：

1. 修改所有默认密码
   包括 MySQL、Redis、MinIO、JWT、Session 等配置。

2. 不要暴露数据库端口
   生产环境中，MySQL 的 3306、Redis 的 6379 不建议直接暴露到公网。可以将 Compose 中的端口映射删除，仅允许容器内部访问。

   例如删除：

   ports:
     - "3306:3306"

3. 启用 HTTPS
   所有登录、Token、API 调用都建议通过 HTTPS 传输。

4. 限制 MinIO 控制台访问
   MinIO 控制台端口 9001 不建议长期暴露到公网，可以通过防火墙限制来源 IP。

5. 定期备份数据
   尤其是数据库和对象存储数据。

6. 固定镜像版本
   不建议生产环境使用 latest，避免版本变化带来的兼容性问题。

7. 配置防火墙
   Ubuntu 可以使用 UFW：

   sudo ufw allow 22
   sudo ufw allow 80
   sudo ufw allow 443
   sudo ufw enable

十六、推荐的生产环境 Compose 调整

生产环境中，可以不将 MySQL、Redis、MinIO 直接暴露到公网，仅暴露 Coze 服务端口。

示例：

mysql:
  image: mysql:8.0
  container_name: coze-mysql
  restart: always
  environment:
    MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
    MYSQL_DATABASE: ${MYSQL_DATABASE}
    MYSQL_USER: ${MYSQL_USER}
    MYSQL_PASSWORD: ${MYSQL_PASSWORD}
  volumes:
    - ./data/mysql:/var/lib/mysql
  networks:
    - coze-net

redis:
  image: redis:7.2
  container_name: coze-redis
  restart: always
  command: redis-server --requirepass ${REDIS_PASSWORD}
  volumes:
    - ./data/redis:/data
  networks:
    - coze-net

这样数据库和 Redis 只能被同一个 Docker 网络中的服务访问，安全性更高。

十七、总结

通过 Docker 部署 Coze 的核心流程可以概括为以下几步：

1. 准备 Linux 服务器；
2. 安装 Docker 和 Docker Compose；
3. 创建 Coze 部署目录；
4. 编写 .env 环境变量文件；
5. 编写 docker-compose.yml；
6. 启动 MySQL、Redis、MinIO 等基础服务；
7. 初始化对象存储 bucket；
8. 启动 Coze 主服务；
9. 配置 Nginx 和 HTTPS；
10. 完成模型接口配置并进行测试。

Docker 部署的优势在于环境隔离、配置清晰、迁移方便。后续如果需要迁移服务器，只需要备份 /opt/coze 目录和数据库数据，在新服务器上重新安装 Docker 后恢复即可。

如果是测试环境，可以直接使用示例配置快速启动；如果是生产环境，则务必修改默认密码、启用 HTTPS、关闭不必要的端口暴露，并做好定期备份。这样才能保证 Coze 平台稳定、安全地运行。