开始部署前，有几个关键点需要明确：如果本地Docker版本过旧、WSL2或Hyper-V未预先启用，后续所有步骤都将无法顺利执行。简单来说，就是必须先确保基础设施就绪，才能进行业务部署。

获取Coze Studio项目后，不要急于启动。先打开终端，运行docker --version和docker-compose --version，确认两者均有输出且版本不低于24.0.0。Windows用户需特别注意：必须手动启用Hyper-V或WSL2，否则容器无法拉取。这是从大量实际部署案例中总结出的经验。

确认本地环境是否达标

您的电脑需要满足最低运行要求，否则项目启动将直接报错退出。在终端中执行 docker --version 和 docker-compose --version，确保两项都有输出且版本不低于24.0.0。如果显示command not found，表明Docker未安装或服务未启用，【此时需先安装Docker Desktop并重启系统】。Windows用户请特别注意：必须启用Hyper-V或WSL2，否则容器根本拉不起来。

拉取Coze Studio源码并校验完整性

进入您常用的项目目录，例如 ~/projects，然后执行以下命令：

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

等待克隆完成。接着进入项目根目录：cd coze-studio。运行 ls -la 检查是否存在 docker-compose.yml 和 backend/conf/model/template/ 这两个关键路径。如果template目录为空，说明git-lfs未安装或未正常启用，会导致模型配置文件缺失——缺了这一步，后续所有部署都会卡在“找不到模型定义”错误上。

配置第一个可用大模型

Coze Studio在启动前必须指定至少一个模型配置文件，否则服务将拒绝加载。当前最便捷的方式是复用官方提供的Ark Doubao模板：

第一步：复制模板文件
cp backend/conf/model/template/model_template_ark_doubao-seed-1.6.yaml backend/conf/model/ark_doubao-seed-1.6.yaml

第二步：编辑该YAML文件
使用VS Code或其他编辑器打开 backend/conf/model/ark_doubao-seed-1.6.yaml，找到 meta.conn_config.api_key 字段，填入您已申请的Ark平台API Key；并确保 id 值为非零整数（例如101），meta.conn_config.model 值为 doubao-pro-2505（这是2026年最新稳定版模型标识）。

⚠️ 注意：id字段若为0，系统会静默跳过该模型注册，在前端创建Bot时将无法选择任何模型。

一键启动完整服务集群

请确保您位于 coze-studio 项目根目录下，直接运行：

docker compose up -d

等待约90秒，在此期间容器会自动拉取镜像、初始化数据库并加载插件。检查服务状态：执行 docker compose ps，所有服务状态应显示为 running。最后验证后端是否就绪：运行 curl http://localhost:8080/health，若返回 {"status":"UP"}，则表明核心服务已成功激活。

登录并验证前端可访问

打开浏览器，访问 http://localhost:3000。首次加载可能需要20～30秒，当页面显示Coze Studio标志与“Create Bot”按钮时，说明部署成功。使用默认账号登录：
【用户名：admin，密码：123456】
登录后点击右上角头像 → Settings → Model Providers，确认列表中已显示您刚配置的 ark_doubao-seed-1.6 条目，且状态为Active。