环境要求
在开始之前,请确保你的设备满足以下条件:
项目 | 要求 |
---|---|
操作系统 | Windows 10/11(建议开启 WSL 2) |
内存 | 至少 4 GB,推荐 8 GB+ |
CPU | 至少双核 |
预装软件 | Docker Desktop、Docker Compose、Git、VS Code(推荐) |
⚠️ Docker Desktop 必须启用 WSL 2 后端
步骤一:克隆项目源码
git clone https://github.com/coze-dev/coze-studio.git
cd coze-studio
步骤二:配置模型(以火山引擎 Ark 的 doubao 模型为例)
1. 复制模型模板
cp backend/conf/model/template/model_template_ark_doubao-seed-1.6.yaml backend/conf/model/ark_doubao-seed-1.6.yaml
2. 修改模型配置
编辑 backend/conf/model/ark_doubao-seed-1.6.yaml
,修改以下字段:
id: 1001 # 自定义唯一模型 ID,必须是非零整数
meta:
conn_config:
api_key: <你的 Volcengine Ark API Key>
model: ep-xxxxxxxxxxxxxxxxxxxxxx # ⚠️ 填写 Endpoint ID,不是模型名!
模型字段说明:
字段 | 说明 |
---|---|
id | 自定义模型 ID,必须唯一 |
api_key | 在火山方舟后台申请的 API 密钥 |
model | Endpoint ID,形如 ep-m-20250319200227-k7zp5 ,不是 doubao-seed-1.6 |
步骤三:配置环境变量
进入 docker
目录,复制 .env
文件:
cd docker
cp .env.example .env
步骤四:启动服务(重点来了!)
正确的 Docker Compose 命令(避免多个项目混在一起)
如果你有多个项目都叫 docker
文件夹,建议指定项目名:
docker compose -p coze-studio --profile "*" up -d
否则默认项目名为 docker
,多个项目的网络、容器可能会冲突。
常见报错 & Windows 特有坑解决
报错:/bin/sh: /setup_es.sh: not found
这是 Windows 用户常见问题!
原因:
- Windows 保存的
.sh
文件换行符是CRLF
,Linux 容器只能识别LF
- 脚本虽然存在,但 shell 认为它无效或无法执行
解决方案一(推荐):修改换行符为 LF
用 VS Code 打开 docker/volumes/elasticsearch/setup_es.sh
:
- 点击右下角的
CRLF
→ 选择LF
- 保存并重新启动容器
或使用 Notepad++ → 菜单:编辑 → EOL转换 → 转换为 UNIX格式
解决方案二:使用 WSL 命令行运行 Compose
cd /mnt/c/Users/你的用户名/Desktop/coze-studio/docker
docker compose --profile "*" up -d
步骤五:访问 Web 页面
启动完成后,打开浏览器输入:
http://localhost:8888
补充说明:服务状态正常与否?
服务启动后,以下几个容器退出(Exited (0)
)是正常现象:
coze-elasticsearch-setup
coze-minio-setup
coze-mysql-setup-init-sql
coze-mysql-setup-schema
只要看到:
Container coze-server Started
就代表你的 Coze Studio 成功跑起来了!
觉得写的不错的话点个关注不迷路