它的后端采用 Golang 开发，前端使用 React + TypeScript，整体基于微服务架构并遵循领域驱动设计（DDD）原则构建。今天，我们就来详细讲讲如何部署 Coze Studio。
一、部署前的准备工作
1. 操作系统
Windows 10/11（建议开启 WSL 2）、macOS 或 Linux 系统均可。
2. 硬件
至少2核CPU、4GB内存，8GB及以上内存可获得更好体验。
3. 预装软件
Docker：创建隔离运行环境。不同系统安装方式如下：
Windows 系统：前往 Docker 官网下载 Docker Desktop 安装包（https://www.docker.com/products/docker - desktop）。安装时记得勾选启用 Hyper - V（安装过程中若提示重启需同意）。国内用户若下载慢，可使用飞书镜像包https://ay6exk7fyt.feishu.cn/drive/folder/IccNf2B4JlJOIvd2kWfcpYnRn4l）。安装完成后打开 Docker Desktop，确认状态栏显示 “Running” 。
Mac 系统：直接从官网下载 Docker Desktop 安装包并拖拽安装，无需特殊设置。安装完成后确保 Docker Desktop 运行正常。
Linux 系统：使用命令行安装 Docker Engine ，如在 Ubuntu 系统中，可执行sudo apt update && sudo apt install docker.io docker - compose ，安装完成后执行docker --version验证是否安装成功，若显示版本号则安装成功。
Git：用于获取Coze Studio 的源码。在Git官网（https://git - scm.com/）下载对应系统的安装包进行安装。例如，Windows 系统下载 “Download for Windows”版本，安装过程中可根据提示进行默认设置，也可自定义安装路径（建议安装在C盘以外的盘符）。
VS Code（可选，但推荐）：方便后续对配置文件等进行编辑，可从VS Code官网（https://code.visualstudio.com/）下载安装。
1. 打开 Docker Desktop 内置终端（右下Terminal），对于没有安装 Docker Desktop 的 Linux 系统用户，直接打开系统自带的终端。
2. 逐行执行以下命令：
克隆官方仓库代码：git clone https://github.com/coze - dev/coze - studio.git。若国内用户下载慢，可使用镜像加速链接，如git clone https://gitee.com/mirrors_coze/coze - studio.git。
进入 docker 配置目录：cd coze - studio/docker。
复制环境配置文件：cp.env.example.env。
若没有安装 Git，也可在 GitHub 直接下载 ZIP 包（https://github.com/coze - dev/coze - studio/archive/refs/heads/main.zip），解压后进入coze - studio/docker目录手动创建.env文件。
二、关键步骤：配置模型服务
模型服务的配置至关重要，未配置模型将无法创建智能体。这里以常见的几种模型配置为例：
1. 复制模型模板
在终端中执行cp backend/conf/model/template/model_template_ark_doubao - seed - 1.6.yaml backend/conf/model/ark_doubao - seed - 1.6.yaml 。
2. 修改模型配置
使用文本编辑器（如 VS Code、记事本等）打开backend/conf/model/ark_doubao - seed - 1.6.yaml，修改以下字段：
id
自定义唯一模型 ID，必须是非零整数，例如id: 1001 。
meta.conn_config.api_key
在火山方舟后台（https://console.volcengine.com/ark）申请的 API 密钥。登录火山方舟后，进入 API Key 的管理界面，创建一个 API Key，填写好名称后点击 “确认”，然后点击查看API并复制。
meta.conn_config.model
填写推理接入点 Endpoint ID （不是模型名），在火山方舟的【在线推理】界面，进入【自定义推理接入点】，点击【创建推理接入点】，填写好接入点名称、描述，选择最新版本的 “Doubao - Seed - 1.6” 大模型，点击 “确定”，最后回到【在线推理】界面，复制接入点下方的 ID 。
(二)使用 DeepSeek 模型
1. 进入模型配置目录（Windows 系统若使用 PowerShell，可用start替换open ）：open../backend/conf/model/ 。
2. 复制 DeepSeek 模板文件：cp../backend/conf/model/template/model_template_ark_volc_deepseek - r1.yaml backend/conf/model/deepseek - r1.yaml 。
3. 用文本编辑器打开deepseek - r1.yaml ，修改以下参数：
base_url: "https://api.deepseek.com/v1" 。
api_key: "sk - xxxxxxxx" ，在 DeepSeek 平台（https://platform.deepseek.com/）申请的 API Key 。
model: "deepseek - reasoner" 。
1.启动本地模型服务（以Ollama的Qwen-7B模型为例）
安装 Ollama ，可从 Ollama 官网（https://ollama.com/download）下载安装包并安装。
运行ollama run qwen:7b，下载并运行Qwen-7B模型。
2.创建模型配置文件
cp backend/conf/model/template/model_template_openai.yaml backend/conf/model/local_qwen.yaml 。
3.编辑local_qwen.yaml
id: 1001 （唯一 ID，不能为 0 ）。
meta:
▪ model: "local - qwen7b" 。
▪ conn_config:
• base_url: "http://host.docker.internal:11434/v1" （Ollama 默认端口）。
• api_key: "null" （无鉴权模型可留空）。
• model: "qwen:7b" （与本地运行的模型名一致）。
三、一键启动服务
在coze - studio/docker目录下，执行以下命令启动服务：docker compose --profile '*' up -d首次运行时，需要下载镜像，这可能需要一些时间，大约5 -10分钟，具体取决于网络情况。当出现Container coze - server Started提示时，即表示启动成功。
服务启动后，打开浏览器，访问http://localhost:8888，首次使用点击注册，输入邮箱和密码，登录后即可进入Coze Studio 操作界面。
四、常见问题解决
报错提示：Ports are not available 。
解决方法：
1. 在 Windows 系统中，执行netstat -ano | findstr :3306 ，查找占用 3306 端口（若冲突的是其他端口，将 3306 替换为对应的端口号）的进程 PID ，然后在任务管理器中结束该进程。
2. 也可修改docker - compose.yml文件中的端口，找到冲突端口对应的配置项，如ports: - "3306:3306" ，将其修改为其他未被占用的端口，如ports: - "3307:3306" ，然后重启服务。
报错提示：MYSQL_USER cannot be "root"等。
解决方法：删除系统环境变量中的MYSQL_USER和MYSQL_PASSWORD ，然后重新启动服务。
报错表现：启动时异常退出。
解决方法：
1. 若使用 Windows 系统，用 VS Code 打开docker/volumes/elasticsearch/setup_es.sh ，点击右下角的CRLF ，选择LF ，保存并重新启动容器。
2. 或者使用 Notepad ++ ，通过菜单：编辑→EOL 转换→转换为 UNIX 格式，然后重新启动容器。
五、进阶：切换不同模型
后续想要切换不同的模型可参考以下步骤：
1.编辑对应模型的 YAML 配置文件（位于backend/conf/model/目录下） 。例如，要切换为 Qwen 模型，复制模板文件到配置目录：cp../backend/conf/model/template/model_template_basic../backend/conf/model/qwen.yaml 。
2.修改qwen.yaml内容：
◦ id: 2 （保持唯一性，不可与其他模型重复）。
◦ name: "qwen3 - 235b" 。
◦ meta.conn_config:
▪ base_url: "https://dashscope.aliyuncs.com/compatible - mode/v1" 。
▪ api_key: "阿里百炼申请的KEY" 。
▪ model: "qwen3 - 235b - a22b - instruct - 2507" 。
3.重启服务使配置生效：docker compose --profile '*' restart coze - server 。
通过以上步骤，你就可以顺利完成 Coze Studio 的部署，并根据自己的需求进行模型配置和使用啦！赶紧动手试试，开启你的 AI Agent 开发之旅吧。
