coze 开源版本地部署及踩过的坑【喂饭级教程】

• • Coze Studio：用于AI Agent开发，提供可视化设计与编排工具，支持零代码或低代码方式快速打造智能体、应用和工作流，适合构建低代码AI产品。
• • Coze Loop：用于运维管理（类似罗盘）。
• • 许可证：采用Apache‑2.0许可证，允许自由使用、修改及商用，限制极少。
• • 技术架构：后端基于Golang开发，前端使用React + TypeScript，整体为微服务架构，遵循领域驱动设计（DDD）原则，具备高性能、高扩展性，便于二次开发。

Coze Studio的开源旨在降低AI Agent开发与应用门槛，鼓励社区共建。本文主要讲一下 Coze Studio 本地部署过程及踩过的坑。

一、安装docker

网址：https://www.docker.com/

image-20250128134319075

image-20250128134319075

一路点击下一步安装即可，因为docker会用到hyper-v，如果电脑没开启hyper-v，可能会需要重启一次。

二、下载开源项目

开源地址：https://github.com/coze-dev/coze-studio

获取源码有两种方式，通过git克隆，或者直接下载源码包

本地没安装git的同学可以使用第二种方式：直接下载源码包

一）git克隆源码

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

二）直接下载源码包

三、开始部署

一）进入项目

cd coze-studio

二）打开命令行

三）拷贝大模型配置文件（关键）

这一步是为了配置项目大模型的，是核心步骤，coze的大模型配置是一个大模型一个专门配置文件，目前支持的大模型相较于dify是不够丰富的，不过相信未来coze会支持的更多，现在支持市面上主流的大模型，也够用了，Coze Studio 支持的模型服务如下：

• • Ark（火山方舟）
• • OpenAI
• • DeepSeek
• • Claude
• • Ollama
• • Qwen
• • Gemini

在 Coze Studio 开源版中，模型配置统一放在backend/conf/model 目录中，目录下存在多个 yaml 文件，每个文件对应一个可访问的模型。 为方便开发者快速配置，Coze Studio 在 backend/conf/model/template 目录下提供了一些模板文件，覆盖了常见的模型类型，例如火山方舟、OpenAI 等。开发者可以找到对应厂商的模型模板，复制到backend/conf/model 目录，根据模板注释设置各个参数。

下面以 deepseek 模型为例：

1、获取deepseek的api key

地址：https://platform.deepseek.com/

注册账号并获取自己的api key

2、复制模型配置模版

# 复制模型配置模版
cp backend/conf/model/template/model_template_ark_volc_deepseek-r1.yaml backend/conf/model/ark_volc_deepseek-r1.yaml

3、配置大模型

不要被模型配置的一大堆参数吓住了，我们只需要配置核心的几个参数即可：

base_url: "https://api.deepseek.com/v1"
api_key: "你的api key"
model: "deepseek-reasoner"

四）复制项目配置文件

1、进入docker目录

2、复制项目env配置文件

五）启动

执行如下命令启动服务：

docker compose --profile '*' up -d

六）浏览器打开

在浏览器打开地址：http://localhost:8888

七）测试一下模型配置是否正确

1、创建一个工作流

2、设置好节点并测试

四、遇到的坑

一）端口冲突：Ports are not available

问题原因：

我之前本地安装过Mysql服务，所以占用了3306端口了，有两个解决方案：

1、关闭本地mysql服务

win+r 快捷键调出运行窗口，输入services.msc 即可调出服务运行窗口，找到 mysql 服务 ，停止服务即可

2、改配置文件内的mysql端口

修改 docker 目录下的env文件，将mysql端口配置改为其他端口数字即可，只要不和其他服务端口冲突就行

image-20250727120504246

image-20250727120504246

二）error during connect: Get xxx

刚拿到coze源码比较激动，急着想看看开源coze长啥样，到底有没有和官方版是否一模一样，直接启动，没想到报错了，原来是忘记启动docker服务了，这点大家可别学我哈[捂脸哭]

三）mysql启动失败：dependency failed to start: container coze-mysql exited

好不容易镜像拉完了，到了启动服务的激动时刻，没想到mysql服务启动失败

于是，我进入docker容器内部查看报错原因：

[ERROR] [Entrypoint]: MYSQL_USER="root", MYSQL_USER and MYSQL_PASSWORD are for configuring a regular user and cannot be used for the root user

明明配置文件中MYSQL_USER是coze，这里为什么是oot呢？忽然想起，我之前给win全局配置过环境变量：

MYSQL相关的全局变量删掉就好了！

四）elasticsearch-setup" didn't complete successfully: exit 127

启动发现 coze-elasticsearch-setup 容器又启动失败：

我们根据报错去容器内查看提示 coze-studio\docker\volumes\elasticsearch\setup_es.sh 文件找不到，但其实这个文件是存在的：

这是为什么呢？答案是：LF和CRLF表示的换行方式不同导致；解决方案：

打开IDE（我这里以vscode举例），切换CRLF为LF即可