开源版扣子（Coze Studio 本地版）部署指南

https://youtu.be/SuGMO5bHFxo

一、简介

Coze（扣子） 是字节跳动开源的智能体平台，包含 Coze Studio（开发平台） 和 Coze Loop（运维平台），支持本地化部署。
本地版主要特点：

• 支持 Docker Compose 一键部署
• 提供 智能体开发、插件、知识库 管理功能
• 默认不自带大模型，需要用户配置 云端或本地模型 API

二、环境准备

• 操作系统：Linux / macOS / Windows (WSL2 推荐)
• 依赖：
  • Docker ≥ 20.10
  • Docker Compose ≥ v2.20
  • Git

三、部署步骤

1. 获取源码

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

2. 配置环境变量

复制 .env.example 为 .env，根据需要修改：

cp .env.example .env

常见配置：

# 服务端口
APP_PORT=8888

# 数据库账号
POSTGRES_USER=coze
POSTGRES_PASSWORD=coze123
POSTGRES_DB=coze_local

# Redis 设置
REDIS_PASSWORD=coze123

3. 启动服务

docker compose --profile '*' up -d

等待容器启动完成后，访问：

http://localhost:8888

即可进入 Coze Studio 管理平台。

四、接入大模型

1. 云端大模型（OpenAI 示例）

在 Coze Studio → 设置 → 大模型 中填写：

• Base URL: https://api.openai.com/v1
• API Key: sk-xxxxxx

2. 本地大模型（推荐 Ollama / FastChat）

方案 A：Ollama

安装 Ollama 并运行：

ollama run qwen:7b

Ollama 默认提供：

http://127.0.0.1:11434/v1

在扣子中配置：

• Base URL: http://127.0.0.1:11434/v1
• API Key: 任意字符串

方案 B：FastChat

部署 FastChat（支持 Qwen、LLaMA、ChatGLM 等）：

docker run -it -p 8000:8000 \
  -v ./models:/models lmsys/fastchat \
  bash -c "python3 -m fastchat.serve.controller & \
           python3 -m fastchat.serve.model_worker --model-path /models/qwen-7b & \
           python3 -m fastchat.serve.openai_api_server --host 0.0.0.0 --port 8000"

在扣子中配置：

• Base URL: http://127.0.0.1:8000/v1
• API Key: 任意字符串

五、验证是否连通

1. 直接测试 API

用 curl 检查大模型接口是否正常：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test" \
  -d '{
    "model": "qwen-7b",
    "messages": [{"role":"user","content":"你好"}]
  }'

✅ 返回 choices → message → API 正常
❌ 404 / 拒绝连接 → 模型服务未启动或 URL 配错

2. 查看扣子日志

docker compose logs -f app

常见报错：

• ECONNREFUSED → 模型服务没运行
• 404 Not Found → URL 填错（缺少 /v1）
• invalid_request_error → 返回格式不符，需要翻译器

六、常见问题与注意事项

1. 默认不带大模型
   扣子本地版只是智能体平台，需要你手动配置大模型 API。
2. API 格式要求
   必须是 OpenAI Chat Completions 格式：{ "model": "xxx", "messages": [{ "role": "user", "content": "你好"}] }如果本地模型 API 不兼容，必须用 翻译器（proxy） 封装。
3. API Key 必填
   即使是本地模型（不校验 key），也要随便填一个字符串，否则请求会报错。
4. 性能与延迟
   • 云端模型 → 网络延迟较高
   • 本地模型 → 依赖显卡性能（建议 16GB 显存起步）
5. 离线环境部署
   • 在外网机器 docker pull 镜像 → docker save → 内网 docker load
   • 避免网络限制导致镜像下载失败

七、总结

• 扣子本地版能让你在内网安全地运行智能体平台，但 大模型要自己配置。
• 如果要接入 本地 LLM，推荐 Ollama（轻量）或 FastChat（兼容性强）。
• 遇到问题时，先用 curl 验证大模型 API，再检查扣子配置和日志。

Coze Studio 本地版下载地址 ：https://github.com/coze-dev/coze-studio

油管：https://youtu.be/SuGMO5bHFxo