Coze 私有化部署实战：Docker 一套命令快速跑起来

发布人：慈云数据-客服中心发布时间：22小时前阅读量：4

Coze Docker部署教程｜附完整命令

Coze 是一款面向 AI 应用开发的智能体/工作流平台，适合用来搭建企业内部的 AI 助手、知识库问答、自动化工作流、多 Agent 协作应用等。如果你希望在自己的服务器上私有化部署 Coze，使用 Docker 是目前相对简单、稳定、可维护的方式之一。

本文将从服务器准备、Docker 安装、项目拉取、环境变量配置、容器启动、访问验证、常用运维命令、升级与排错等方面，完整介绍 Coze 的 Docker 部署流程，并附上可直接复制执行的命令。

一、部署前准备

在开始部署之前，建议准备一台 Linux 服务器。本文以 Ubuntu 22.04 / Debian 系统为例，CentOS、Rocky Linux、AlmaLinux 也可以参考，只是部分包管理命令略有差异。

1. 服务器配置建议

如果只是测试体验，最低配置可以较低；如果用于团队或生产环境，建议适当提高配置。

场景	CPU	内存	磁盘
测试体验	2 核	4GB	40GB
小团队使用	4 核	8GB	80GB
生产环境	8 核及以上	16GB 及以上	200GB 及以上

注意：Coze 本身可能依赖数据库、缓存、对象存储、搜索/向量组件等服务，实际资源占用会根据启用的功能、访问量、模型调用量而变化。

2. 系统要求

建议系统环境：

Ubuntu 20.04+
Debian 11+
CentOS 7+
Rocky Linux 8+

本文命令主要以 Ubuntu / Debian 为例。

3. 域名与端口

如果只是内网测试，可以直接使用服务器 IP 访问。

如果用于正式环境，建议准备一个域名，例如：

coze.example.com

同时确保服务器安全组或防火墙放行必要端口：

端口	用途
80	HTTP 访问
443	HTTPS 访问
8888 / 8080 等	根据 Docker Compose 暴露端口而定

二、安装 Docker 和 Docker Compose

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

1. 更新系统软件包

sudo apt update
sudo apt upgrade -y

2. 安装基础依赖

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

3. 添加 Docker 官方 GPG Key

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

4. 添加 Docker 软件源

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. 安装 Docker Engine

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

6. 启动 Docker 并设置开机自启

sudo systemctl enable docker
sudo systemctl start docker

7. 验证 Docker 是否安装成功

docker version
docker compose version

如果能够看到 Docker 和 Docker Compose 的版本信息，说明安装成功。

三、拉取 Coze 项目代码

Coze 开源版本通常以源码仓库的形式发布，Docker 部署一般会使用仓库内提供的 docker-compose.yml 或部署脚本。

进入你希望存放项目的目录，例如 /opt：

cd /opt

拉取 Coze 项目：

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

进入项目目录：

cd coze-studio

如果你希望普通用户也可以操作该目录，可以修改目录权限：

sudo chown -R $USER:$USER /opt/coze-studio

查看项目文件：

ls -la

一般情况下，你应该能看到类似以下文件或目录：

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

不同版本的项目结构可能会有所变化，请以实际仓库为准。

四、配置环境变量

Docker Compose 部署通常需要 .env 文件保存环境变量，例如数据库账号、Redis 密码、访问地址、模型 API Key 等。

1. 复制环境变量模板

如果项目中提供了 .env.example，可以复制一份：

cp .env.example .env

如果模板文件名称不同，可以先查找：

find . -maxdepth 2 -name "*env*"

2. 编辑 `.env` 文件

使用 nano 编辑：

nano .env

或者使用 vim：

vim .env

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

# 服务访问地址
WEB_URL=http://你的服务器IP:端口
API_BASE_URL=http://你的服务器IP:端口

# 数据库配置
MYSQL_ROOT_PASSWORD=请修改为强密码
MYSQL_DATABASE=coze
MYSQL_USER=coze
MYSQL_PASSWORD=请修改为强密码

# Redis 配置
REDIS_PASSWORD=请修改为强密码

# 对象存储配置
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=请修改为强密码

# 模型服务配置，按需填写
OPENAI_API_KEY=你的模型APIKey
OPENAI_BASE_URL=https://api.openai.com/v1

注意：上面的变量名是常见示例，实际项目中的变量名请以 .env.example 或官方文档为准。不要机械复制不匹配的变量名。

3. 生成随机强密码

你可以使用下面的命令生成随机密码：

openssl rand -base64 32

例如分别生成数据库密码、Redis 密码、对象存储密码：

MYSQL_PASSWORD=$(openssl rand -base64 32)
REDIS_PASSWORD=$(openssl rand -base64 32)
MINIO_PASSWORD=$(openssl rand -base64 32)

echo "MYSQL_PASSWORD=$MYSQL_PASSWORD"
echo "REDIS_PASSWORD=$REDIS_PASSWORD"
echo "MINIO_PASSWORD=$MINIO_PASSWORD"

然后将生成的值写入 .env 文件。

五、使用 Docker Compose 启动 Coze

1. 查看 Compose 文件

在项目目录下执行：

ls docker-compose*

可能会看到：

docker-compose.yml
docker-compose.dev.yml
docker-compose.prod.yml

如果官方提供了生产环境配置，建议使用生产配置。如果只有 docker-compose.yml，直接使用即可。

查看服务列表：

docker compose config --services

该命令可以检查 Compose 配置是否正确，并列出将要启动的服务。

2. 拉取镜像

docker compose pull

如果镜像较多，首次拉取可能需要几分钟到十几分钟，具体取决于服务器网络环境。

3. 构建镜像

如果 Compose 文件中包含 build 字段，需要构建镜像：

docker compose build

如果你希望不使用缓存重新构建：

docker compose build --no-cache

4. 启动服务

后台启动：

docker compose up -d

如果你想在前台查看启动过程，可以使用：

docker compose up

后台启动后，查看容器状态：

docker compose ps

正常情况下，相关服务状态应该是 running 或 healthy。

六、初始化数据库或执行迁移

部分项目首次启动后，需要执行数据库迁移、初始化管理员账号、初始化数据表等操作。

你可以先查看容器名称：

docker compose ps

假设后端服务名称为 api 或 backend，可以查看日志：

docker compose logs -f backend

如果官方文档要求执行迁移命令，通常类似：

docker compose exec backend ./migrate

或者：

docker compose exec backend npm run migrate

也可能是：

docker compose exec backend pnpm migrate

由于不同版本命令可能不同，建议以项目 README 或部署文档中的初始化命令为准。

如果你不确定服务名称，可以执行：

docker compose config --services

然后根据列出的服务名称执行对应命令。

七、访问 Coze 控制台

服务启动完成后，查看端口映射：

docker compose ps

你会看到类似输出：

NAME                 SERVICE       PORTS
coze-frontend        frontend      0.0.0.0:8888->80/tcp
coze-backend         backend       0.0.0.0:8080->8080/tcp

如果前端端口是 8888，可以在浏览器访问：

http://服务器IP:8888

例如：

http://192.168.1.100:8888

如果你配置了域名和反向代理，可以访问：

https://coze.example.com

八、配置 Nginx 反向代理

生产环境不建议直接暴露容器端口给外部访问，推荐使用 Nginx 做反向代理，并配置 HTTPS。

1. 安装 Nginx

sudo apt install -y nginx

启动并设置开机自启：

sudo systemctl enable nginx
sudo systemctl start nginx

2. 新建站点配置

假设 Coze 前端映射到宿主机 8888 端口，创建配置文件：

sudo nano /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";
    }
}

启用站点：

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

检查配置：

sudo nginx -t

重载 Nginx：

sudo systemctl reload nginx

此时可以访问：

http://coze.example.com

九、配置 HTTPS 证书

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

1. 安装 Certbot

sudo apt install -y certbot python3-certbot-nginx

2. 申请证书

将 coze.example.com 替换为你的真实域名：

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

按照提示输入邮箱、同意协议即可。

3. 验证自动续期

sudo certbot renew --dry-run

如果没有报错，说明证书自动续期配置正常。

十、常用运维命令

1. 查看容器状态

docker compose ps

2. 查看全部日志

docker compose logs -f

3. 查看指定服务日志

例如查看后端日志：

docker compose logs -f backend

查看前端日志：

docker compose logs -f frontend

查看数据库日志：

docker compose logs -f mysql

4. 重启所有服务

docker compose restart

5. 重启指定服务

docker compose restart backend

6. 停止服务

docker compose stop

7. 启动已停止的服务

docker compose start

8. 停止并删除容器

docker compose down

注意：该命令默认不会删除数据卷，但会删除容器和网络。

9. 停止并删除容器、网络和数据卷

docker compose down -v

警告：-v 会删除数据卷，可能导致数据库、文件、索引等数据丢失，生产环境慎用。

10. 查看资源占用

docker stats

11. 进入容器

docker compose exec backend sh

如果容器内使用 bash：

docker compose exec backend bash

十一、升级 Coze

升级前务必备份数据，尤其是数据库、对象存储目录、挂载目录和 .env 文件。

1. 备份当前配置

cd /opt/coze-studio

mkdir -p /opt/backup/coze

cp .env /opt/backup/coze/.env.$(date +%F-%H%M%S)
cp docker-compose.yml /opt/backup/coze/docker-compose.yml.$(date +%F-%H%M%S)

2. 备份数据库

如果 MySQL 服务名为 mysql，数据库名为 coze，可以执行：

docker compose exec mysql mysqldump -uroot -p coze > /opt/backup/coze/coze-$(date +%F-%H%M%S).sql

执行后会提示输入 MySQL root 密码。

如果想直接从 .env 中读取密码，需要根据实际变量名调整命令。

3. 拉取最新代码

git pull

4. 拉取最新镜像

docker compose pull

5. 重新构建并启动

docker compose up -d --build

6. 查看启动状态

docker compose ps
docker compose logs -f

十二、数据备份建议

生产环境建议至少备份以下内容：

.env 配置文件；
docker-compose.yml 及相关 Compose 文件；
数据库数据；
对象存储数据，例如 MinIO；
上传文件目录；
向量库或搜索索引数据；
自定义插件、工作流、知识库配置。

可以创建一个简单备份目录：

sudo mkdir -p /data/backup/coze

备份项目配置：

cd /opt/coze-studio

sudo tar -czf /data/backup/coze/coze-config-$(date +%F-%H%M%S).tar.gz .env docker-compose.yml

如果数据目录挂载在 /data/coze，可以备份：

sudo tar -czf /data/backup/coze/coze-data-$(date +%F-%H%M%S).tar.gz /data/coze

建议将备份文件同步到其他服务器或对象存储，避免单点故障。

十三、常见问题排查

1. 容器启动失败

查看容器状态：

docker compose ps

查看日志：

docker compose logs -f

如果某个服务一直重启，可以单独查看：

docker compose logs -f 服务名

常见原因包括：

.env 配置错误；
数据库密码不一致；
端口被占用；
镜像拉取失败；
内存不足；
数据目录权限不足。

2. 端口被占用

查看端口占用：

sudo ss -tulnp

例如查看 8888 端口：

sudo ss -tulnp | grep 8888

如果端口已被占用，可以修改 docker-compose.yml 中的端口映射，例如：

ports:
  - "8899:80"

修改后重启：

docker compose up -d

3. 页面打不开

首先确认容器是否正常：

docker compose ps

确认端口是否监听：

sudo ss -tulnp | grep 8888

确认防火墙是否放行：

sudo ufw status

放行端口：

sudo ufw allow 8888/tcp

如果使用云服务器，还需要在云厂商安全组中放行对应端口。

4. Nginx 反向代理后接口报错

常见原因是后端 API 地址、跨域配置或 WebSocket 代理配置不正确。

可以检查 .env 中的访问地址，例如：

WEB_URL=https://coze.example.com
API_BASE_URL=https://coze.example.com

修改后重启服务：

docker compose up -d

同时确认 Nginx 中包含 WebSocket 相关配置：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

5. 容器无法连接数据库

查看数据库服务日志：

docker compose logs -f mysql

查看后端日志：

docker compose logs -f backend

常见原因：

数据库服务尚未完全启动；
数据库账号密码配置不一致；
数据库名不存在；
后端服务使用了错误的数据库主机名。

在 Docker Compose 内部，服务之间通常使用服务名通信，例如：

MYSQL_HOST=mysql
MYSQL_PORT=3306

不要在容器内使用 127.0.0.1 连接另一个容器，因为 127.0.0.1 指向的是当前容器自身。

十四、安全加固建议

如果 Coze 用于生产环境，建议做以下安全配置：

修改所有默认密码
包括数据库、Redis、MinIO、后台管理员等。
不要直接暴露数据库端口
MySQL、Redis、MinIO 管理端等不建议开放到公网。
使用 HTTPS
通过 Nginx + Certbot 配置 SSL 证书。
限制服务器 SSH 登录
禁止 root 密码登录，改用 SSH Key。
定期备份数据
至少每天备份一次核心数据。
定期升级镜像和依赖
修复安全漏洞。
配置防火墙
只开放必要端口，例如 80、443、SSH。

Ubuntu 可以使用 UFW：

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

十五、一键部署命令汇总

下面整理一份从零开始部署的命令，适合快速测试。正式环境仍建议逐步检查配置。

# 1. 更新系统
sudo apt update && sudo apt upgrade -y

# 2. 安装依赖
sudo apt install -y ca-certificates curl gnupg lsb-release git openssl

# 3. 添加 Docker GPG Key
sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 4. 添加 Docker 软件源
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 6. 启动 Docker
sudo systemctl enable docker
sudo systemctl start docker

# 7. 拉取 Coze 源码
cd /opt
sudo git clone https://github.com/coze-dev/coze-studio.git
sudo chown -R $USER:$USER /opt/coze-studio
cd /opt/coze-studio

# 8. 复制环境变量
cp .env.example .env

# 9. 编辑环境变量
nano .env

# 10. 拉取镜像
docker compose pull

# 11. 构建镜像
docker compose build

# 12. 启动服务
docker compose up -d

# 13. 查看状态
docker compose ps

# 14. 查看日志
docker compose logs -f

十六、总结

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

准备 Linux 服务器；
安装 Docker 和 Docker Compose；
拉取 Coze 项目源码；
根据 .env.example 配置环境变量；
使用 docker compose up -d 启动服务；
通过 IP、端口或域名访问 Coze；
使用 Nginx 和 HTTPS 提升生产可用性；
定期备份、升级和监控服务状态。

如果你只是本地或测试环境体验，按照本文命令基本可以快速跑起来；如果是生产环境，建议额外关注安全、备份、日志、监控、HTTPS、模型服务限流和服务器资源规划。部署完成后，你就可以在 Coze 中创建智能体、配置知识库、编排工作流，并将 AI 能力接入到业务系统中。

文章标签： Coze Docker部署 DockerCompose Nginx反向代理

上一篇：跨境电商团队自建 Coze：Docker 部署与实战配置指南

下一篇：Coze 本地化部署实战：Docker 一键搭建与配置文件详解

更多栏目

新闻动态

文档中心

下载中心

目录结构

全文

产品与服务

新闻帮助

生态合作

了解我们