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

本文面向希望在服务器上部署 Coze / Coze Studio，并将其用于真实业务环境的开发者、运维人员和 AI 应用搭建者。文章会从环境准备、服务部署、配置说明、生产环境优化、常见问题排查等角度，完整梳理一套可落地的 Coze 部署流程。

一、Coze 是什么？

Coze 是一个用于构建 AI Agent、智能体工作流、插件工具和知识库应用的平台。对于企业或开发团队来说，Coze 的价值主要体现在以下几个方面：

1. 低代码搭建 AI 应用
   可以通过可视化方式编排智能体能力，例如调用大模型、接入插件、使用知识库、执行工作流等。

2. 支持复杂工作流编排
   相比单纯的 ChatBot，Coze 更适合做多步骤、多工具、多条件判断的业务流程。

3. 适合企业内部 AI 助手场景
   例如客服助手、文档问答、数据分析助手、运营工具、研发辅助工具等。

4. 便于统一管理模型和应用能力
   企业可以将不同模型、插件、知识库、业务接口统一封装到平台中，降低后续维护成本。

如果只是个人测试，使用官方在线版本即可；但如果希望在企业内部署、接入私有模型、使用私有数据、避免数据外传，那么自部署就是更稳妥的选择。

二、部署前的准备工作

在正式部署之前，需要先准备服务器、系统环境、域名和基础软件。生产环境不建议直接使用个人电脑或临时云主机进行长期运行。

1. 服务器配置建议

根据实际测试，如果只是小规模测试，最低配置可以较低；但如果要在生产环境运行，建议至少满足以下配置：

注意：如果你还要在同一台机器上部署大模型推理服务，例如 Ollama、vLLM、Xinference 等，那么配置需要进一步提升，尤其是显存资源。

2. 操作系统建议

推荐使用以下系统：

• Ubuntu 22.04 LTS
• Ubuntu 20.04 LTS
• Debian 12
• CentOS Stream 9

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

3. 域名准备

生产环境建议准备一个域名，例如：

coze.example.com

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

如果只是在内网环境使用，也可以使用内网域名或直接使用服务器 IP，但生产环境强烈建议启用 HTTPS。

三、安装基础环境

1. 更新系统软件包

登录服务器后，先执行：

sudo apt update
sudo apt upgrade -y

安装常用工具：

sudo apt install -y curl wget git vim unzip lsof net-tools ca-certificates gnupg

2. 安装 Docker

Coze 这类平台通常包含多个服务组件，使用 Docker Compose 部署会更方便，也更适合后续维护。

执行以下命令安装 Docker：

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

安装完成后，启动 Docker：

sudo systemctl enable docker
sudo systemctl start docker

查看版本：

docker version

如果希望当前用户可以直接执行 Docker 命令，可以执行：

sudo usermod -aG docker $USER

然后重新登录服务器。

3. 安装 Docker Compose

部分系统已经内置 Docker Compose 插件，可以先检查：

docker compose version

如果没有安装，可以执行：

sudo apt install -y docker-compose-plugin

再次验证：

docker compose version

四、获取 Coze 部署项目

进入准备部署的目录，例如：

cd /opt

拉取项目代码：

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

进入项目目录：

cd coze-studio

如果你的服务器无法访问 GitHub，可以先在本地下载源码压缩包，再上传到服务器。

查看目录结构：

ls -lah

通常你会看到类似以下内容：

docker-compose.yml
backend
frontend
scripts
README.md
.env.example

不同版本的项目结构可能略有差异，以实际仓库为准。

五、配置环境变量

部署前最重要的一步就是配置 .env 文件。通常项目会提供示例配置文件，例如：

cp .env.example .env

然后编辑：

vim .env

1. 基础访问地址配置

你需要重点检查类似以下配置：

WEB_BASE_URL=https://coze.example.com
API_BASE_URL=https://coze.example.com/api

如果你暂时没有域名，只是测试，可以使用：

WEB_BASE_URL=http://服务器IP
API_BASE_URL=http://服务器IP/api

但生产环境建议使用 HTTPS。

2. 数据库配置

如果使用 Docker Compose 自带数据库，通常会在 .env 中看到：

POSTGRES_USER=coze
POSTGRES_PASSWORD=请修改为强密码
POSTGRES_DB=coze
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

生产环境一定要修改默认密码，例如：

POSTGRES_PASSWORD=Coze_Prod_DB_2025_StrongPwd

如果你使用外部 PostgreSQL，则需要将 POSTGRES_HOST 改为外部数据库地址。

3. Redis 配置

一般会有如下配置：

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

生产环境建议设置 Redis 密码：

REDIS_PASSWORD=Redis_Prod_StrongPwd

同时需要确保 Docker Compose 或 Redis 配置中启用了认证。

4. 模型服务配置

Coze 的核心能力依赖大模型，因此你需要配置模型提供方。常见选择包括：

• OpenAI API
• Azure OpenAI
• 火山方舟
• 通义千问
• 智谱 AI
• DeepSeek
• Ollama 本地模型
• vLLM 私有推理服务

例如使用兼容 OpenAI 格式的模型网关，可以配置类似：

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

如果使用 DeepSeek 这类兼容 OpenAI 接口的模型，也可以配置为：

OPENAI_API_KEY=你的API_KEY
OPENAI_BASE_URL=https://api.deepseek.com/v1
DEFAULT_MODEL=deepseek-chat

实际变量名需要以当前 Coze 项目版本说明为准。不同版本可能会将模型配置放到后台管理界面中，而不是完全依赖 .env。

六、启动 Coze 服务

配置完成后，可以使用 Docker Compose 启动服务：

docker compose up -d

首次启动会拉取镜像，耗时取决于网络环境。启动完成后查看容器状态：

docker compose ps

如果所有服务状态都是 running 或 healthy，说明基础启动成功。

查看日志：

docker compose logs -f

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

docker compose logs -f backend

七、初始化数据库

有些版本在首次启动时会自动初始化数据库；有些版本则需要手动执行迁移命令。你可以查看项目 README 或部署说明。

常见命令类似：

docker compose exec backend npm run migrate

或：

docker compose exec backend ./scripts/migrate.sh

如果是 Go 后端，也可能类似：

docker compose exec backend ./coze migrate

初始化完成后，建议重启服务：

docker compose restart

八、配置反向代理与 HTTPS

生产环境中，不建议直接暴露容器端口，而是通过 Nginx 进行反向代理，并启用 HTTPS。

1. 安装 Nginx

sudo apt install -y nginx

启动并设置开机自启：

sudo systemctl enable nginx
sudo systemctl start nginx

2. 配置 Nginx

创建配置文件：

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:8888;
        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";

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

其中 8888 需要替换成你实际暴露的前端或网关端口。可以通过以下命令查看端口：

docker compose ps

启用配置：

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

3. 申请 HTTPS 证书

安装 Certbot：

sudo apt install -y certbot python3-certbot-nginx

申请证书：

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

根据提示选择自动跳转 HTTPS。

申请完成后访问：

https://coze.example.com

如果页面可以正常打开，说明反向代理和 HTTPS 配置成功。

九、创建管理员账号

不同版本的 Coze 初始化管理员方式可能不同。常见方式有三种：

方式一：页面注册首个账号

首次访问系统时，页面会提示创建管理员账号。填写邮箱、用户名和密码即可。

方式二：命令行创建管理员

进入后端容器执行：

docker compose exec backend ./scripts/create-admin.sh

然后按照提示输入邮箱和密码。

方式三：修改数据库用户角色

如果已经注册了普通账号，可以通过数据库将其提升为管理员。进入数据库：

docker compose exec postgres psql -U coze -d coze

查看用户表：

SELECT id, email, role FROM users;

更新角色：

UPDATE users SET role='admin' WHERE email='admin@example.com';

实际表名和字段名需要以当前版本为准，不建议在不了解数据结构的情况下直接修改生产数据库。

十、生产环境实测重点配置

部署成功只是第一步，真正用于生产环境时，还需要做一系列稳定性和安全性优化。

1. 修改所有默认密码

包括但不限于：

• 数据库密码
• Redis 密码
• 管理员密码
• 模型 API Key
• 对象存储密钥
• JWT Secret
• Session Secret

.env 中如果存在如下配置，一定要修改：

JWT_SECRET=change_me
SESSION_SECRET=change_me
ENCRYPTION_KEY=change_me

建议使用随机强密码：

openssl rand -base64 32

2. 限制数据库端口暴露

生产环境中，PostgreSQL、Redis 等服务不应暴露到公网。如果使用 Docker Compose，应确保它们只在内部网络通信。

检查 docker-compose.yml 中是否存在类似：

ports:
  - "5432:5432"

如果不需要外部访问数据库，建议删除该端口映射，只保留内部服务访问。

Redis 同理，不建议暴露：

ports:
  - "6379:6379"

3. 配置防火墙

使用 UFW：

sudo apt install -y ufw

放行 SSH、HTTP、HTTPS：

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

启用防火墙：

sudo ufw enable

查看状态：

sudo ufw status

如果 SSH 端口不是 22，请务必放行实际端口，否则可能导致无法远程登录。

4. 配置日志管理

Docker 容器日志如果不限制，长期运行可能占满磁盘。可以创建 Docker daemon 配置：

sudo vim /etc/docker/daemon.json

写入：

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

重启 Docker：

sudo systemctl restart docker

然后重新启动 Coze：

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

5. 配置数据备份

生产环境最重要的是数据安全。至少需要备份以下内容：

• PostgreSQL 数据库
• 上传文件
• 知识库文件
• 对象存储数据
• .env 配置文件
• Nginx 配置
• Docker Compose 文件

PostgreSQL 备份示例

创建备份目录：

mkdir -p /opt/backups/coze

执行备份：

docker compose exec postgres pg_dump -U coze coze > /opt/backups/coze/coze_$(date +%F).sql

如果需要自动备份，可以添加定时任务：

crontab -e

加入：

0 3 * * * cd /opt/coze-studio && docker compose exec -T postgres pg_dump -U coze coze > /opt/backups/coze/coze_$(date +\%F).sql

建议定期将备份同步到另一台服务器或对象存储，避免单机故障导致数据丢失。

6. 监控服务状态

生产环境中，需要监控以下指标：

• CPU 使用率
• 内存使用率
• 磁盘空间
• Docker 容器状态
• 数据库连接数
• Redis 内存占用
• 接口响应时间
• 大模型调用失败率
• Token 消耗情况

简单查看容器资源：

docker stats

查看磁盘：

df -h

查看内存：

free -h

如果团队规模较大，建议接入 Prometheus + Grafana，或者使用云厂商自带监控服务。

十一、接入大模型服务

部署 Coze 后，最关键的是让平台能够正常调用模型。

1. 使用云端模型 API

这是最简单的方式，只需要配置 API Key 和 Base URL。例如：

模型名称：deepseek-chat
接口地址：https://api.deepseek.com/v1
API Key：你的 Key

优点：

• 部署简单
• 不需要 GPU
• 稳定性较好
• 模型能力持续更新

缺点：

• 长期调用有成本
• 数据可能经过第三方服务
• 受接口限流影响

2. 使用本地私有模型

如果你希望数据完全留在内网，可以使用 Ollama 或 vLLM 部署私有模型。

以 Ollama 为例：

curl -fsSL https://ollama.com/install.sh | sh

下载模型：

ollama pull qwen2.5:7b

启动后，Ollama 默认监听：

http://127.0.0.1:11434

如果 Coze 在 Docker 容器中访问宿主机 Ollama，可以使用：

http://host.docker.internal:11434

Linux 下如果不可用，可以在 docker-compose.yml 中增加：

extra_hosts:
  - "host.docker.internal:host-gateway"

然后在 Coze 的模型配置中填写对应接口。

十二、知识库与文件存储配置

Coze 通常会涉及知识库、文件上传、插件结果缓存等功能。生产环境中，文件存储不建议只依赖容器内部目录。

1. 使用本地挂载目录

可以在 docker-compose.yml 中挂载目录：

volumes:
  - /data/coze/uploads:/app/uploads

确保目录权限正确：

sudo mkdir -p /data/coze/uploads
sudo chown -R 1000:1000 /data/coze/uploads

2. 使用对象存储

更推荐使用对象存储，例如：

• AWS S3
• 阿里云 OSS
• 腾讯云 COS
• MinIO
• 火山 TOS

如果是内网环境，可以部署 MinIO：

docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD=StrongMinioPassword \
  -v /data/minio:/data \
  minio/minio server /data --console-address ":9001"

然后在 Coze 中配置对象存储 Endpoint、Bucket、AccessKey 和 SecretKey。

十三、升级与回滚

生产环境升级前，一定要先备份。

1. 备份当前环境

cd /opt/coze-studio
docker compose ps
docker compose logs > /opt/backups/coze/logs_before_upgrade_$(date +%F).txt

备份数据库：

docker compose exec -T postgres pg_dump -U coze coze > /opt/backups/coze/coze_before_upgrade_$(date +%F).sql

备份配置：

cp .env /opt/backups/coze/env_before_upgrade_$(date +%F)
cp docker-compose.yml /opt/backups/coze/docker-compose_before_upgrade_$(date +%F).yml

2. 拉取新版本

git pull

更新镜像：

docker compose pull

重新启动：

docker compose up -d

观察日志：

docker compose logs -f

3. 回滚思路

如果升级后出现异常，可以：

1. 切回旧版本代码；
2. 恢复旧的 .env 和 docker-compose.yml；
3. 恢复数据库备份；
4. 重新启动服务。

回滚数据库示例：

cat /opt/backups/coze/coze_before_upgrade_2025-01-01.sql | docker compose exec -T postgres psql -U coze -d coze

十四、常见问题排查

1. 页面无法打开

检查 Nginx 状态：

sudo systemctl status nginx

检查端口监听：

sudo lsof -i:80
sudo lsof -i:443

检查容器：

docker compose ps

如果容器未启动，查看日志：

docker compose logs -f

2. 接口请求 502

502 通常是 Nginx 无法连接后端。重点检查：

• proxy_pass 端口是否正确；
• 后端容器是否正常运行；
• 防火墙是否拦截；
• 服务是否只监听了容器内部地址；
• Docker 网络是否异常。

3. 模型调用失败

常见原因包括：

• API Key 错误；
• Base URL 填写错误；
• 模型名称不正确；
• 模型服务限流；
• 服务器无法访问外网；
• 请求超时；
• 本地模型没有启动。

可以进入容器内测试网络：

docker compose exec backend curl https://api.deepseek.com/v1/models

4. 知识库上传失败

重点检查：

• 文件大小限制；
• Nginx client_max_body_size；
• 后端上传限制；
• 存储目录权限；
• 对象存储配置；
• 磁盘空间是否充足。

查看磁盘：

df -h

5. 容器频繁重启

查看具体日志：

docker compose logs -f 服务名

常见原因：

• .env 配置错误；
• 数据库连接失败；
• Redis 连接失败；
• 端口冲突；
• 内存不足；
• 镜像版本不兼容。

十五、生产环境部署建议总结

经过生产环境实测，部署 Coze 时最容易被忽视的不是启动命令，而是后续维护能力。建议你至少完成以下事项：

• 使用域名和 HTTPS；
• 修改所有默认密钥和密码；
• 不暴露数据库、Redis 到公网；
• 配置防火墙；
• 配置 Docker 日志限制；
• 定期备份数据库和文件；
• 使用对象存储保存上传文件；
• 对大模型接口设置限流和预算；
• 建立监控和告警；
• 升级前必须备份；
• 重要业务上线前先做压测。

如果只是个人体验，Docker Compose 一键启动基本足够；但如果是企业内部生产环境，就必须把 Coze 当作一个正式业务系统来部署和维护。

十六、最终访问验证

完成部署后，可以按以下流程验证：

1. 访问：

https://coze.example.com

2. 注册或登录管理员账号；
3. 配置模型供应商；
4. 创建一个测试智能体；
5. 输入一句测试问题；
6. 查看是否能正常返回；
7. 上传一份文档到知识库；
8. 测试知识库问答；
9. 检查日志是否有异常；
10. 重启服务器后确认服务是否自动恢复。

如果以上流程全部正常，说明 Coze 已经具备基本生产可用条件。

结语

Coze 的部署并不复杂，真正的难点在于生产环境的稳定性、安全性和可维护性。对于个人开发者而言，只要 Docker Compose 能跑起来，就可以快速体验智能体搭建能力；但对于企业场景而言，需要重点关注数据库安全、文件存储、模型调用稳定性、日志管理、备份恢复和权限控制。

从生产实测角度来看，推荐的最终架构是：

用户
  ↓
HTTPS / Nginx
  ↓
Coze Web / API 服务
  ↓
PostgreSQL + Redis + 对象存储
  ↓
云端模型 API 或私有模型推理服务

只要按照本文步骤完成环境准备、服务启动、反向代理、模型配置和生产优化，就可以搭建出一套相对稳定、可持续维护的 Coze 部署环境。