Coze 生产环境部署指南｜一键部署

随着大模型应用进入企业级落地阶段，越来越多团队开始使用 Coze 构建智能体、工作流、插件和知识库应用。相比本地体验或测试环境，生产环境部署更关注稳定性、安全性、可扩展性、可观测性和运维成本。本文将围绕 Coze 在生产环境中的一键部署思路，系统介绍部署前准备、服务器规划、环境变量配置、Docker Compose 部署、反向代理、HTTPS、数据持久化、备份恢复、监控告警以及上线后的运维建议，帮助你快速搭建一个可长期运行的 Coze 生产环境。

说明：不同版本的 Coze 或 Coze Studio 在目录结构、环境变量名称、依赖组件上可能存在差异。本文以通用生产部署方法为主，实际落地时请结合官方仓库中的 README、docker-compose.yml、.env.example 等文件进行调整。

一、生产环境部署目标

生产环境部署并不只是“把服务跑起来”，而是要确保服务能够稳定、安全、可维护地运行。一个合格的 Coze 生产环境通常需要满足以下目标：

1. 服务稳定可用
   Coze Web 服务、API 服务、数据库、缓存、对象存储、向量检索等组件应能稳定运行，并具备自动重启能力。

2. 数据持久化
   用户数据、智能体配置、工作流配置、知识库文件、向量数据、日志等必须持久化存储，避免容器重建后数据丢失。

3. HTTPS 访问
   生产环境应通过域名和 HTTPS 提供服务，避免账号、Token、配置等敏感信息明文传输。

4. 安全隔离
   数据库、Redis、对象存储等内部组件不应直接暴露到公网，只允许 Coze 服务或内网访问。

5. 便于升级回滚
   通过 Docker Compose、镜像版本号、备份机制和配置管理，实现可控升级与快速回滚。

6. 具备监控和告警能力
   能够及时发现服务异常、磁盘不足、数据库连接异常、接口响应变慢等问题。

二、部署架构概览

一个典型的 Coze 生产部署架构如下：

用户浏览器
   │
   │ HTTPS
   ▼
Nginx / Caddy / Traefik
   │
   ├── Coze Web
   ├── Coze API / Backend
   ├── Plugin / Workflow Service
   └── Internal Services
          ├── PostgreSQL / MySQL
          ├── Redis
          ├── Object Storage（MinIO / S3）
          ├── Vector DB（Milvus / Elasticsearch / pgvector 等）
          └── Message Queue（如有）

如果是中小团队或内部使用，可以先采用 单机 Docker Compose 部署。这类部署方式上手快、维护成本低，非常适合作为第一阶段生产环境。后续随着用户量增加，可以逐步拆分为多机部署、Kubernetes 部署或云托管服务。

三、服务器配置建议

生产环境的服务器配置需要根据访问量、知识库规模、并发任务数量以及所接入的大模型能力综合评估。以下是一个常见的起步配置建议：

1. 基础生产环境

适合团队内部使用、小规模应用验证。

2. 中等规模生产环境

适合多业务线、多智能体、多知识库场景。

3. 高可用环境

适合正式对外服务或企业核心系统。

四、部署前准备

在正式部署之前，建议完成以下准备工作。

1. 准备域名

例如：

coze.example.com

将域名解析到服务器公网 IP。

如果使用 Cloudflare、阿里云 DNS、腾讯云 DNS 等服务，需要添加一条 A 记录：

主机记录：coze
记录类型：A
记录值：服务器公网 IP

2. 开放必要端口

服务器安全组或防火墙中至少需要开放：

生产环境不建议直接开放数据库、Redis、MinIO 控制台等端口到公网。如果确实需要临时排查，应通过堡垒机、VPN 或 SSH 隧道访问。

3. 安装基础工具

以 Ubuntu 为例：

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

4. 安装 Docker

curl -fsSL https://get.docker.com | bash
sudo systemctl enable docker
sudo systemctl start docker

验证安装：

docker version

5. 安装 Docker Compose

较新版本 Docker 已内置 Compose 插件，可以执行：

docker compose version

如果提示不存在，可以安装：

sudo apt install -y docker-compose-plugin

五、一键部署目录规划

建议将 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
│   └── conf.d
│       └── coze.conf
├── data
│   ├── postgres
│   ├── redis
│   ├── minio
│   └── vector
├── logs
│   ├── nginx
│   └── coze
├── backup
│   ├── db
│   └── files
└── scripts
    ├── deploy.sh
    ├── backup.sh
    └── rollback.sh

这样做的好处是：

• 配置集中，便于管理；
• 数据集中持久化，便于备份；
• 日志路径清晰，便于排查问题；
• 脚本化部署，降低人工失误。

六、环境变量配置

生产环境一定不要直接使用默认密码。建议复制官方示例配置：

cp .env.example .env

如果没有示例文件，可以自行创建 .env：

vim .env

示例配置如下，具体变量名请以实际项目为准：

# 基础配置
COZE_ENV=production
COZE_DOMAIN=https://coze.example.com
TZ=Asia/Shanghai

# 数据库配置
POSTGRES_DB=coze
POSTGRES_USER=coze_user
POSTGRES_PASSWORD=请替换为强密码
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=请替换为强密码

# 对象存储配置
MINIO_ROOT_USER=coze_minio
MINIO_ROOT_PASSWORD=请替换为强密码
MINIO_BUCKET=coze

# JWT / Session / 加密密钥
JWT_SECRET=请替换为至少32位随机字符串
SESSION_SECRET=请替换为至少32位随机字符串
ENCRYPTION_KEY=请替换为至少32位随机字符串

# 模型服务配置
OPENAI_API_KEY=你的模型服务Key
OPENAI_BASE_URL=https://api.openai.com/v1

# 日志级别
LOG_LEVEL=info

生成随机密钥可以使用：

openssl rand -hex 32

生产环境配置时需要注意：

1. 密码不要使用 123456、password、admin 等弱密码；
2. .env 文件不要提交到公开 Git 仓库；
3. API Key 不要写入前端代码；
4. 如果接入多个模型供应商，应分别管理 Key；
5. 更换密钥前要确认是否影响历史数据解密或用户登录状态。

七、Docker Compose 一键部署示例

下面是一个通用的 Docker Compose 示例，用于说明生产环境组件组织方式。实际镜像名称、端口、启动命令请以官方项目为准。

version: "3.9"

services:
  coze-web:
    image: coze/web:latest
    container_name: coze-web
    restart: always
    env_file:
      - .env
    depends_on:
      - coze-api
    networks:
      - coze-net

  coze-api:
    image: coze/api:latest
    container_name: coze-api
    restart: always
    env_file:
      - .env
    depends_on:
      - postgres
      - redis
      - minio
    volumes:
      - ./logs/coze:/app/logs
    networks:
      - coze-net

  postgres:
    image: postgres:16
    container_name: coze-postgres
    restart: always
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      TZ: ${TZ}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    networks:
      - coze-net

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

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

  nginx:
    image: nginx:1.25
    container_name: coze-nginx
    restart: always
    depends_on:
      - coze-web
      - coze-api
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./logs/nginx:/var/log/nginx
      - ./certbot/www:/var/www/certbot
      - ./certbot/conf:/etc/letsencrypt
    networks:
      - coze-net

networks:
  coze-net:
    driver: bridge

部署命令：

docker compose pull
docker compose up -d

查看服务状态：

docker compose ps

查看日志：

docker compose logs -f coze-api
docker compose logs -f coze-web
docker compose logs -f nginx

八、Nginx 反向代理配置

生产环境通常需要通过 Nginx 统一暴露 Web 与 API 服务。示例配置如下：

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

    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name coze.example.com;

    ssl_certificate /etc/letsencrypt/live/coze.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/coze.example.com/privkey.pem;

    client_max_body_size 100m;

    access_log /var/log/nginx/coze.access.log;
    error_log /var/log/nginx/coze.error.log;

    location /api/ {
        proxy_pass http://coze-api: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 https;
        proxy_read_timeout 300s;
    }

    location / {
        proxy_pass http://coze-web: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 https;
    }
}

如果 Coze 使用 WebSocket、SSE 或长连接能力，还需要增加：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_buffering off;

对于大模型流式输出场景，建议关闭代理缓冲，否则用户可能无法实时看到回答内容。

九、申请 HTTPS 证书

可以使用 Certbot 申请免费 Let’s Encrypt 证书。

创建目录：

mkdir -p certbot/www certbot/conf

首次申请证书：

docker run --rm \
  -v /opt/coze/certbot/conf:/etc/letsencrypt \
  -v /opt/coze/certbot/www:/var/www/certbot \
  certbot/certbot certonly \
  --webroot \
  -w /var/www/certbot \
  -d coze.example.com \
  --email admin@example.com \
  --agree-tos \
  --no-eff-email

申请完成后重启 Nginx：

docker compose restart nginx

证书自动续期可以使用定时任务：

crontab -e

加入：

0 3 * * * docker run --rm -v /opt/coze/certbot/conf:/etc/letsencrypt -v /opt/coze/certbot/www:/var/www/certbot certbot/certbot renew --quiet && cd /opt/coze && docker compose restart nginx

十、一键部署脚本

为了降低部署复杂度，可以编写 scripts/deploy.sh：

#!/usr/bin/env bash
set -e

APP_DIR="/opt/coze"

echo "进入部署目录：$APP_DIR"
cd "$APP_DIR"

echo "检查 Docker..."
docker version >/dev/null

echo "检查 Docker Compose..."
docker compose version >/dev/null

echo "拉取最新镜像..."
docker compose pull

echo "启动服务..."
docker compose up -d

echo "等待服务初始化..."
sleep 10

echo "当前服务状态："
docker compose ps

echo "部署完成，请访问：https://coze.example.com"

赋予执行权限：

chmod +x scripts/deploy.sh

执行一键部署：

./scripts/deploy.sh

如果想实现更完整的一键部署，可以在脚本中加入：

• 自动检查 .env 是否存在；
• 自动生成随机密钥；
• 自动检测域名解析；
• 自动申请 HTTPS 证书；
• 自动初始化数据库；
• 自动创建对象存储 Bucket；
• 自动执行健康检查；
• 部署失败自动输出日志。

十一、初始化与健康检查

部署完成后，不要急着对外开放，建议先做基础检查。

1. 查看容器状态

docker compose ps

所有核心服务应处于 Up 状态。

2. 查看 API 日志

docker compose logs -f coze-api

重点关注：

• 数据库连接是否成功；
• Redis 连接是否成功；
• 对象存储初始化是否成功；
• 模型 API Key 是否配置正确；
• 是否存在数据库迁移失败；
• 是否存在端口冲突或权限问题。

3. 浏览器访问

访问：

https://coze.example.com

确认页面可以正常打开、登录、创建智能体、调用模型、上传知识库文件。

4. 接口健康检查

如果服务提供健康检查接口，可以执行：

curl -I https://coze.example.com
curl https://coze.example.com/api/health

返回 200 或类似健康状态即表示基础链路正常。

十二、数据持久化与备份策略

生产环境最重要的资产不是容器，而是数据。Coze 中常见的重要数据包括：

• 用户账号与权限数据；
• 智能体配置；
• 工作流配置；
• 插件配置；
• 知识库文件；
• 向量索引数据；
• 会话记录；
• 系统配置；
• 运行日志。

1. 数据库备份

以 PostgreSQL 为例，可以编写 scripts/backup.sh：

#!/usr/bin/env bash
set -e

BACKUP_DIR="/opt/coze/backup/db"
DATE=$(date +"%Y%m%d_%H%M%S")

mkdir -p "$BACKUP_DIR"

docker exec coze-postgres pg_dump \
  -U coze_user \
  -d coze \
  > "$BACKUP_DIR/coze_$DATE.sql"

gzip "$BACKUP_DIR/coze_$DATE.sql"

echo "数据库备份完成：$BACKUP_DIR/coze_$DATE.sql.gz"

设置权限：

chmod +x scripts/backup.sh

定时备份：

crontab -e

加入：

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

2. 文件备份

如果使用本地 MinIO 或本地文件系统，还需要备份：

/opt/coze/data/minio
/opt/coze/data/vector
/opt/coze/.env
/opt/coze/nginx

可以使用 rsync 同步到另一台服务器：

rsync -avz /opt/coze/backup user@backup-server:/data/backup/coze/

3. 备份注意事项

• 数据库备份和文件备份要尽量保持时间一致；
• 备份文件应存放在异地或云存储中；
• 定期做恢复演练，确保备份真的可用；
• .env 中包含密钥，应加密保存；
• 备份保留周期可以设置为 7 天、30 天或 90 天，视业务要求而定。

十三、升级与回滚

生产环境升级必须谨慎，尤其是涉及数据库迁移、知识库结构变更、向量索引重建时。

1. 升级前准备

升级前建议执行：

./scripts/backup.sh
docker compose ps
docker compose logs --tail=200 coze-api

同时记录当前镜像版本：

docker images | grep coze

生产环境不要长期使用 latest 标签，建议指定明确版本：

image: coze/api:v1.2.3
image: coze/web:v1.2.3

2. 执行升级

docker compose pull
docker compose up -d

3. 升级后验证

验证内容包括：

• 页面是否正常打开；
• 登录是否正常；
• 智能体是否能正常运行；
• 工作流是否能正常执行；
• 知识库是否能正常检索；
• 历史数据是否完整；
• 日志是否存在异常报错。

4. 回滚策略

如果升级后出现严重问题，可以将镜像版本改回旧版本：

image: coze/api:v1.2.2
image: coze/web:v1.2.2

然后执行：

docker compose up -d

如果数据库已被新版本迁移且不兼容旧版本，则需要从备份中恢复。因此，升级前备份是生产环境的底线。

十四、安全加固建议

Coze 通常会涉及模型 Key、企业知识库、用户对话数据等敏感信息，因此安全配置非常重要。

1. 最小化公网暴露

公网只开放：

• 80
• 443
• 必要的 SSH 端口

数据库、Redis、MinIO、向量数据库等均不要暴露公网端口。

2. SSH 安全

建议：

sudo vim /etc/ssh/sshd_config

修改：

PermitRootLogin no
PasswordAuthentication no

使用密钥登录，并重启 SSH：

sudo systemctl restart ssh

3. 防火墙配置

使用 UFW：

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

4. 密钥管理

• 定期轮换模型 API Key；
• 不在日志中输出密钥；
• 不把 .env 上传到 Git；
• 生产和测试环境使用不同 Key；
• 重要密钥建议接入 Vault、云 KMS 或密钥管理服务。

5. 登录与权限

上线后应检查：

• 是否允许公开注册；
• 管理员账号是否使用强密码；
• 是否需要开启企业 SSO；
• 普通用户是否具备过高权限；
• 插件调用是否有权限边界。

十五、监控与日志

生产环境需要及时发现问题。最简单的做法是先关注容器状态和系统资源。

1. 查看资源占用

docker stats

关注 CPU、内存、网络和磁盘 IO。

2. 查看磁盘空间

df -h
du -sh /opt/coze/*

知识库文件、日志、向量索引都可能快速增长，因此磁盘监控非常重要。

3. 日志采集

可以将日志接入：

• Loki + Grafana；
• ELK / OpenSearch；
• 云日志服务；
• Docker logging driver。

Nginx 日志重点关注：

• 4xx、5xx 错误；
• 请求耗时；
• 上传文件大小；
• 高频异常 IP。

Coze API 日志重点关注：

• 模型调用失败；
• 工作流执行失败；
• 数据库连接池耗尽；
• Redis 超时；
• 对象存储上传失败；
• 知识库索引失败。

4. 监控告警

建议监控指标包括：

• 服务是否存活；
• API 响应时间；
• 5xx 错误率；
• CPU 使用率；
• 内存使用率；
• 磁盘使用率；
• 数据库连接数；
• Redis 内存；
• 证书过期时间；
• 模型调用失败率。

对于中小团队，可以先使用 Uptime Kuma 监控 HTTPS 可用性，再逐步接入 Prometheus 和 Grafana。

十六、常见问题排查

1. 页面打不开

排查顺序：

docker compose ps
docker compose logs nginx
docker compose logs coze-web

同时检查：

• 域名是否解析正确；
• 80/443 端口是否开放；
• Nginx 配置是否正确；
• HTTPS 证书路径是否存在。

2. API 请求 502

通常是 Nginx 无法连接后端服务。检查：

docker compose logs coze-api
docker inspect coze-api

常见原因包括：

• API 容器未启动；
• API 端口配置错误；
• Nginx proxy_pass 地址错误；
• 服务不在同一个 Docker 网络中；
• 后端启动失败。

3. 数据库连接失败

检查环境变量：

cat .env
docker compose logs postgres
docker compose logs coze-api

重点确认：

• 数据库用户名和密码一致；
• 数据库服务名是否正确；
• 数据库端口是否正确；
• 数据卷权限是否正常。

4. 上传知识库失败

可能原因：

• MinIO/S3 配置错误；
• Bucket 未创建；
• 文件大小超过 Nginx 限制；
• 后端上传超时；
• 磁盘空间不足。

可以适当调整：

client_max_body_size 100m;
proxy_read_timeout 300s;

5. 大模型调用失败

检查：

• API Key 是否有效；
• Base URL 是否正确；
• 模型名称是否支持；
• 服务器是否能访问模型供应商；
• 是否触发供应商限流；
• 是否存在代理、防火墙或 DNS 问题。

十七、生产环境上线清单

正式上线前，建议逐项确认：

• [ ] 域名已解析到服务器；
• [ ] HTTPS 证书已配置；
• [ ] 80/443 端口正常开放；
• [ ] 数据库、Redis、对象存储未暴露公网；
• [ ] .env 中所有默认密码已修改；
• [ ] JWT、Session、加密密钥已使用随机强密钥；
• [ ] 数据目录已持久化；
• [ ] 已配置数据库备份；
• [ ] 已完成一次备份恢复演练；
• [ ] 已配置日志查看方式；
• [ ] 已配置基础监控；
• [ ] 管理员账号已设置强密码；
• [ ] 模型 API Key 已验证可用；
• [ ] 智能体、工作流、知识库功能测试通过；
• [ ] 升级和回滚流程已确认。

十八、总结

Coze 的生产环境部署可以从单机 Docker Compose 起步，通过“一键部署脚本”快速完成服务启动、镜像更新、配置加载和状态检查。对于大多数团队来说，第一阶段重点不是追求复杂架构，而是把 域名、HTTPS、数据持久化、备份、安全加固和日志监控 做扎实。

当业务规模扩大后，可以再逐步演进到云数据库、独立对象存储、多副本后端服务、负载均衡、Kubernetes、Prometheus 监控和 CI/CD 发布体系。生产部署的核心原则是：配置可管理、数据可恢复、服务可观测、升级可回滚、安全有边界。

只要按照本文的步骤完成服务器准备、环境变量配置、Docker Compose 编排、Nginx 反向代理、证书申请、备份监控和上线检查，你就可以搭建一个相对可靠的 Coze 生产环境，并为后续的企业级智能体应用建设打下坚实基础。