Coze Docker部署教程｜零基础可学

本文面向零基础用户，手把手讲解如何使用 Docker 部署 Coze。无论你是刚接触 Linux、Docker，还是第一次部署 AI 应用平台，都可以按照本文步骤完成基础安装、启动、访问与常见问题排查。

一、什么是 Coze？

Coze 是一个用于构建 AI 智能体、工作流和 AI 应用的平台。通过 Coze，用户可以创建聊天机器人、知识库问答助手、自动化流程助手等应用，并将其用于客服、运营、内容生产、数据分析等场景。

如果你使用过在线版 Coze，可能已经体验过它的智能体搭建能力。而通过 Docker 部署 Coze，则可以将相关服务运行在自己的服务器或本地电脑上，便于测试、学习、二次开发或私有化使用。

二、为什么推荐使用 Docker 部署？

对于零基础用户来说，直接在服务器上安装各种依赖通常比较复杂，例如：

• Node.js 版本不匹配
• Go / Python 环境冲突
• 数据库安装失败
• 端口被占用
• 系统依赖缺失
• 不同操作系统配置差异较大

Docker 的优势在于：它可以把应用运行所需的环境打包成镜像，再通过容器运行。你不需要手动安装大量依赖，只需要安装 Docker，然后执行几条命令即可启动服务。

简单理解：

Docker 就像一个“应用集装箱”，Coze 的运行环境已经放进集装箱里，你只需要把它启动起来。

三、部署前准备

在开始之前，你需要准备以下内容。

1. 一台服务器或本地电脑

推荐使用 Linux 服务器，例如：

• Ubuntu 20.04 / 22.04
• Debian 11 / 12
• CentOS 7 / Rocky Linux / AlmaLinux
• 云服务器：阿里云、腾讯云、华为云、AWS、Vultr 等

如果你只是学习，也可以在本地电脑上部署：

• Windows：建议安装 Docker Desktop
• macOS：安装 Docker Desktop
• Linux：直接安装 Docker Engine

2. 推荐服务器配置

如果只是体验和学习，建议配置如下：

如果你要长期使用或多人访问，建议：

• CPU：4 核以上
• 内存：8GB 或 16GB 以上
• 硬盘：100GB 以上
• 使用独立数据库和对象存储

四、安装 Docker

下面以 Ubuntu 系统为例进行说明。如果你使用的是其他系统，命令可能略有不同，但整体思路一致。

1. 更新系统软件包

登录服务器后，执行：

sudo apt update
sudo apt upgrade -y

2. 安装必要工具

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

3. 安装 Docker

你可以使用官方脚本快速安装 Docker：

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

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

docker version

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

4. 设置 Docker 开机自启

sudo systemctl enable docker
sudo systemctl start docker

5. 验证 Docker 是否可用

执行：

sudo docker run hello-world

如果输出中看到类似以下内容：

Hello from Docker!

说明 Docker 已经可以正常运行。

五、安装 Docker Compose

很多现代项目都会使用 docker compose 来同时管理多个容器，例如前端、后端、数据库、Redis 等。Coze 这类平台通常也会涉及多个服务，因此 Docker Compose 非常重要。

1. 查看是否已经安装

docker compose version

如果能看到版本号，例如：

Docker Compose version v2.x.x

说明已经安装。

2. 如果没有安装

新版 Docker 通常已经自带 Compose 插件。如果没有，可以参考 Docker 官方文档安装，或使用系统包管理器安装：

sudo apt install -y docker-compose-plugin

再次验证：

docker compose version

六、获取 Coze 项目代码

接下来需要获取 Coze 的部署文件。通常可以从官方 GitHub 仓库获取。

注意：不同版本的 Coze 项目目录结构可能会调整，请以官方仓库 README 为准。本文以常见 Docker Compose 部署流程为例讲解。

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

cd /opt

克隆项目：

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

进入项目目录：

cd coze-studio

如果你使用的是其他官方仓库地址，请替换为实际地址。

七、查看项目目录

进入项目后，可以先查看目录结构：

ls

你可能会看到类似文件：

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

常见重要文件说明如下：

如果项目中没有根目录下的 docker-compose.yml，请查看 deploy 或 docker 目录，很多项目会将部署文件放在这些目录下。

八、配置环境变量

多数 Docker 项目都会提供 .env.example 文件，我们需要复制一份作为实际配置文件。

cp .env.example .env

然后编辑 .env：

nano .env

如果你不熟悉 nano：

• 使用方向键移动光标
• 修改内容后按 Ctrl + O 保存
• 按回车确认
• 按 Ctrl + X 退出

常见需要关注的配置

不同版本配置项可能不同，但通常会包含以下内容：

# 服务端口
PORT=8888

# 数据库配置
MYSQL_HOST=mysql
MYSQL_PORT=3306
MYSQL_USER=coze
MYSQL_PASSWORD=coze_password
MYSQL_DATABASE=coze

# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379

# 服务访问地址
PUBLIC_URL=http://你的服务器IP:8888

请重点检查：

1. 端口是否被占用
2. 数据库密码是否安全
3. 访问地址是否填写正确
4. 是否需要配置模型服务 API Key

如果你要使用大语言模型能力，通常还需要配置模型供应商，例如 OpenAI、豆包、通义千问、智谱、DeepSeek 等。不同版本支持的配置方式不一样，常见形式如下：

OPENAI_API_KEY=你的APIKey
OPENAI_BASE_URL=https://api.openai.com/v1

如果你使用兼容 OpenAI 格式的模型服务，也可以填写对应服务商的 Base URL。

九、启动 Coze 服务

配置完成后，就可以使用 Docker Compose 启动。

如果 docker-compose.yml 在当前目录，执行：

sudo docker compose up -d

参数说明：

• docker compose：使用 Compose 管理多个容器
• up：启动服务
• -d：后台运行

首次启动时，Docker 会拉取镜像或构建镜像，因此需要等待一段时间。根据网络环境不同，可能需要几分钟到几十分钟。

十、查看容器运行状态

启动后执行：

sudo docker compose ps

你会看到类似结果：

NAME              IMAGE              STATUS
coze-web          xxx                Up
coze-server       xxx                Up
coze-mysql        mysql              Up
coze-redis        redis              Up

只要主要服务状态是 Up，说明容器已经启动。

如果某个容器显示 Exited，说明启动失败，需要查看日志。

十一、查看运行日志

查看所有服务日志：

sudo docker compose logs -f

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

sudo docker compose logs -f server

查看前端服务：

sudo docker compose logs -f web

日志中常见错误包括：

• 数据库连接失败
• Redis 连接失败
• 环境变量缺失
• 端口被占用
• 镜像拉取失败
• API Key 配置错误

遇到问题不要慌，先看日志，日志通常会告诉你失败原因。

十二、访问 Coze

假设你配置的端口是 8888，服务器 IP 是 1.2.3.4，那么可以在浏览器访问：

http://1.2.3.4:8888

如果你是在本地电脑部署，可以访问：

http://localhost:8888

如果页面正常打开，说明部署成功。

十三、开放服务器防火墙端口

如果容器已经启动，但浏览器无法访问，可能是服务器安全组或防火墙没有放行端口。

1. 云服务器安全组

如果你使用阿里云、腾讯云、华为云等，需要进入云服务器控制台，找到安全组规则，放行对应端口，例如：

TCP 8888

来源可以先设置为：

0.0.0.0/0

但生产环境建议限制访问来源，避免暴露风险。

2. Ubuntu 防火墙

如果启用了 UFW，可以执行：

sudo ufw allow 8888/tcp
sudo ufw reload

查看状态：

sudo ufw status

十四、常用 Docker 管理命令

部署完成后，你需要掌握一些常用命令，方便后续维护。

1. 停止服务

sudo docker compose stop

2. 启动服务

sudo docker compose start

3. 重启服务

sudo docker compose restart

4. 停止并删除容器

sudo docker compose down

注意：down 会删除容器和网络，但通常不会删除数据卷。若添加 -v，则会删除数据卷，可能导致数据丢失。

sudo docker compose down -v

新手不建议随意执行 down -v。

5. 查看镜像

sudo docker images

6. 查看容器

sudo docker ps

查看所有容器，包括已停止的：

sudo docker ps -a

十五、配置域名访问

如果你不想用 IP:端口 的方式访问，可以配置域名，例如：

https://coze.example.com

常见做法是使用 Nginx 反向代理。

1. 安装 Nginx

sudo apt install -y nginx

2. 新建站点配置

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

写入示例配置：

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

    location / {
        proxy_pass http://127.0.0.1:8888;
        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/
sudo nginx -t
sudo systemctl reload nginx

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

十六、配置 HTTPS 证书

生产环境建议使用 HTTPS。可以通过 Certbot 免费申请 Let’s Encrypt 证书。

1. 安装 Certbot

sudo apt install -y certbot python3-certbot-nginx

2. 申请证书

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

根据提示输入邮箱并确认即可。

完成后访问：

https://coze.example.com

十七、更新 Coze

项目后续可能会更新版本。如果你是通过 Git 获取代码，可以按照以下方式更新。

1. 进入项目目录

cd /opt/coze-studio

2. 拉取最新代码

sudo git pull

3. 重新拉取镜像并启动

sudo docker compose pull
sudo docker compose up -d

如果项目需要重新构建镜像，可以执行：

sudo docker compose up -d --build

更新前建议先备份数据库和 .env 文件，避免配置丢失。

十八、数据备份建议

如果你只是测试，可以暂时不考虑备份。但如果你已经在 Coze 中创建了智能体、工作流、知识库等内容，就必须重视数据备份。

1. 备份 .env

cp .env .env.backup

2. 备份 Docker 数据卷

查看数据卷：

sudo docker volume ls

如果数据库使用 Docker volume 存储，可以通过打包数据目录或数据库导出方式备份。

3. 备份 MySQL 数据库

假设 MySQL 容器名为 coze-mysql，可以执行：

sudo docker exec coze-mysql mysqldump -u root -p coze > coze_backup.sql

执行后会提示输入密码。

恢复时可以使用：

sudo docker exec -i coze-mysql mysql -u root -p coze < coze_backup.sql

实际容器名、数据库名、用户名请根据你的配置调整。

十九、常见问题排查

1. 访问页面打不开

可能原因：

• 容器未启动
• 端口未开放
• 云服务器安全组未放行
• Nginx 配置错误
• 服务启动中，还未完全就绪

排查命令：

sudo docker compose ps
sudo docker compose logs -f

同时检查端口：

sudo ss -tunlp | grep 8888

2. Docker 镜像拉取失败

可能原因：

• 服务器无法访问镜像仓库
• 网络不稳定
• 镜像地址变更

解决思路：

• 多尝试几次
• 更换网络环境
• 配置 Docker 镜像加速
• 查看官方文档是否更换镜像地址

3. 提示端口被占用

如果启动时报错类似：

bind: address already in use

说明端口被其他程序占用。

查看占用端口的程序：

sudo lsof -i:8888

或：

sudo ss -tunlp | grep 8888

解决方式：

• 修改 .env 或 docker-compose.yml 中的端口
• 停止占用该端口的服务

例如将：

ports:
  - "8888:8888"

改为：

ports:
  - "8899:8888"

然后访问：

http://服务器IP:8899

4. 数据库连接失败

常见原因：

• 数据库容器未启动
• 数据库密码配置错误
• 后端服务启动过快，数据库还未初始化完成
• .env 中数据库地址填写错误

可以先查看数据库容器状态：

sudo docker compose ps

再查看数据库日志：

sudo docker compose logs -f mysql

如果是首次启动，数据库初始化可能需要一点时间，可以等待后重启后端服务：

sudo docker compose restart

5. 配置了 API Key 但模型不可用

可能原因：

• API Key 填错
• Base URL 填错
• 模型名称不匹配
• 服务商账户余额不足
• 当前服务器无法访问模型服务商接口

建议你先在服务器上测试网络：

curl https://api.openai.com/v1/models

如果使用其他兼容服务商，请替换为对应地址。

二十、安全建议

如果你准备将 Coze 暴露到公网，请务必注意安全。

1. 不要使用弱密码

数据库、后台账号、API Key 等都应使用复杂密码。

2. 不要公开 .env 文件

.env 中可能包含数据库密码、模型 API Key 等敏感信息，不能上传到公开仓库。

3. 使用 HTTPS

公网服务建议配置 SSL 证书，避免明文传输。

4. 限制端口暴露

生产环境尽量只暴露 80 和 443 端口，内部服务如 MySQL、Redis 不要直接暴露到公网。

5. 定期更新

定期更新系统、Docker 镜像和 Coze 项目代码，修复潜在安全风险。

二十一、适合新手的部署流程总结

如果你觉得上面内容较多，可以先记住最核心的流程：

# 1. 安装 Docker
curl -fsSL https://get.docker.com | bash

# 2. 克隆项目
cd /opt
git clone https://github.com/coze-dev/coze-studio.git
cd coze-studio

# 3. 配置环境变量
cp .env.example .env
nano .env

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

# 5. 查看状态
docker compose ps

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

最后在浏览器访问：

http://服务器IP:端口

如果你能打开 Coze 页面，就说明基础部署已经完成。

二十二、结语

通过 Docker 部署 Coze，其实并没有想象中复杂。对于零基础用户来说，最重要的是理解几个概念：Docker 用来运行容器，Docker Compose 用来同时管理多个服务，.env 用来配置环境变量，日志用来排查问题。

部署过程中如果遇到问题，不要盲目重装系统，也不要频繁删除数据。正确的排查顺序应该是：

1. 查看容器是否启动
2. 查看服务日志
3. 检查端口是否开放
4. 检查环境变量是否正确
5. 检查服务器网络是否正常

只要掌握这些基本方法，你不仅可以部署 Coze，也可以部署大多数基于 Docker 的开源项目。对于想学习 AI 应用开发、智能体搭建和工作流自动化的用户来说，Coze 是一个非常值得上手的平台，而 Docker 部署则是最适合新手入门的一种方式。