如何调试coze-studio

coze-studio的源码下了好几天了，看看怎么调试

docker compose启动

官方文档

https://github.com/coze-dev/coze-studio/wiki/2.-Quickstart

复制配置文件

bash 复制代码

cd coze-studio
# Copy model configuration template
cp backend/conf/model/template/model_template_ark_doubao-seed-1.6.yaml backend/conf/model/ark_doubao-seed-1.6.yaml

创建环境变量文件并启动

复制代码

cd docker
cp .env.example .env
docker compose --profile '*' up -d

只是下载镜像要久一点，镜像好了直接启动就可以了，下面是需要的镜像列表，其中coze-server默认用的latest标签，为了版本清晰一些，我修改了docker-compose.yml的版本号

复制代码

"mysql:8.4.5",  
"bitnami/redis:8.0",  
"bitnami/elasticsearch:8.18.0",  
"minio/minio:RELEASE.2025-06-13T11-33-47Z-cpuv1",  
"bitnami/etcd:3.5",  
"milvusdb/milvus:v2.5.10",  
"nsqio/nsq:v1.2.1",  
"alpine/curl:8.12.1",  
"minio/mc:RELEASE.2025-05-21T01-59-54Z-cpuv1",  
"arigaio/atlas:0.35.0-community-alpine"
"opencoze/opencoze:0.3.1"

镜像下载方法可以看我另一篇文章《GithubAction同步镜像到阿里云仓库》

https://mp.weixin.qq.com/s/g8mugs21Y7yfGeoRMwVvkA

启动成功如下

登录web

访问ip:8888端口

编译源码

官方文档如下

https://github.com/coze-dev/coze-studio/wiki/7.-Development-Standards#code-development-and-testing

执行命令make server即可

coze-server的编译命令得看Makefile中的server规则

调用的scripts/setup/server.sh脚本编译和启动coze-server, 代码入口是backend/main.go

编译前需要

docker compose成功启动了coze
安装go、nodejs

在编译的过程中，可能还需要设置git邮箱

编译server的前会先编译前端代码，在安装依赖或运行打包脚本时，可能会执行 Git 相关命令（如验证作者身份），如果你的 Git 没有设置 user.email，就会失败。

bash 复制代码

git config --global user.name "xxxxx"
git config --global user.email "you@example.com"

调试coze-server

在docker-compose.yml中可以看到，各个服务都做了端口映射，所以只需要通过docker compose启动好应用后，停止掉coze-server ,然后本地启动coze-server进行调试即可。

修改编译命令

修改scripts/setup/server.sh如下

删除当前正在运行的coze server镜像

docker目录下执行下面的命令，停止coze-server

bash 复制代码

docker compose --profile "*" rm -s -f coze-server

编译coze-server源码

项目根目录下，执行make server，就会编译前端、编译server。编译完成后，二进制文件会输出到项目根目录下的bin目录中，然后会调用 xxxx/coze-studio/bin/open -start命令启动server

调试server代码

退出前面启动的server，在项目根目录下创建调试脚本debug.sh

bash 复制代码

#!/bin/bash

BASE_DIR=$(pwd)
BACKEND_DIR="$BASE_DIR/backend"
BIN_DIR="$BASE_DIR/bin"
CONFIG_DIR="$BIN_DIR/resources/conf"
RESOURCES_DIR="$BIN_DIR/resources/"
DOCKER_DIR="$BASE_DIR/docker"
source "$DOCKER_DIR/.env"

echo "📑 Copying environment file..."
if [ -f "$DOCKER_DIR/.env" ]; then
    cp "$DOCKER_DIR/.env" "$BIN_DIR/.env"
else
    echo "error: .env file not found in $DOCKER_DIR"
    exit 1
fi

if [ -f "$DOCKER_DIR/cert.pem" ]; then
    cp "$DOCKER_DIR/cert.pem" "$BIN_DIR/cert.pem"
fi

if [ -f "$DOCKER_DIR/key.pem" ]; then
    cp "$DOCKER_DIR/key.pem" "$BIN_DIR/key.pem"
fi

echo "Cleaning configuration files..."
rm -rf "$CONFIG_DIR"
mkdir -p "$CONFIG_DIR"

cp -r "$BACKEND_DIR/conf" "$RESOURCES_DIR"
cp -r "$BACKEND_DIR/static" "$RESOURCES_DIR"

cd $BIN_DIR && dlv --headless --listen=:7000 --api-version=2 --accept-multiclient --log exec -- /root/coze-studio/bin/opencoze -start

因为server启动的时候，需要复制一下配置文件，参考源码的server.sh脚本的逻辑，编写了debug.sh脚本。不使用debug.sh脚本就要手动复制配置文件了。

脚本编写好后，赋予脚本执行权限chmod +x debug.sh

执行脚本,输出如下内容

vscode debug

配置项如下

可以开始调试了

如果调试太卡可以把dlv的日志选项去掉会快一些