AgentScope Studio Docker部署完全指南:从一键启动到数据持久化与端口配置详解
AgentScope Studio Docker部署完全指南:从一键启动到数据持久化与端口配置详解
AgentScope Studio 是一款面向 Agent 开发者的本地可视化开发工具包,提供项目管理、运行时对话、OpenTelemetry Tracing 追踪与 Agent 评估能力。本指南带你通过 Docker 一键部署 AgentScope Studio,涵盖镜像构建、容器启动、端口配置、数据持久化与常见问题排查,帮助新手快速搭建稳定的可视化调试环境。
为什么选择 Docker 部署 🐳
如果你不想在本机安装 Node.js >= 20 和 Python 环境,Docker 是最省心的选择:
- 环境完全隔离:镜像内置 Node.js、Python 3.10 及全部依赖,
docker build一次即可运行; - 跨平台一致:无论 Windows、macOS 还是 Linux,行为完全一致;
- 数据可持久化:用户数据统一挂载到宿主机目录,容器随时可重建;
- 管理脚本开箱即用:项目提供了 docker/docker.sh 管理脚本,一个命令即可完成构建、启停、看日志等操作。
AgentScope Studio 部署后的项目列表界面如下,连接 AgentScope 应用后即可看到项目与运行记录:
相关说明可参考官方文档 docker/README.md 与 docs/tutorial/zh_CN/tutorial/quick_start.md。
环境准备:安装 Docker 与获取项目
前置要求:安装 Docker 与 Docker Compose。
验证环境:
docker --version
docker compose version
克隆项目源码(所有命令均在项目根目录执行):
git clone https://gitcode.com/gh_mirrors/ag/agentscope-studio
cd agentscope-studio
Docker 相关配置文件位于 docker/ 目录:
| 文件 | 作用 |
|---|---|
| docker/Dockerfile | 镜像定义(多阶段构建) |
| docker/docker-compose.yml | Compose 编排(端口、卷、环境变量) |
| docker/docker.sh | 一键管理脚本 |
| docker/entrypoint.sh | 容器启动入口脚本 |
一键启动:使用 docker.sh 管理脚本(推荐)⭐
赋予脚本执行权限,然后依次执行构建与启动:
# 添加执行权限
chmod +x docker/docker.sh
# 构建镜像(首次部署必须执行)
./docker/docker.sh build
# 启动容器,并自动打印最近 40 行启动日志
./docker/docker.sh start
build 命令会基于 docker/Dockerfile 做多阶段构建:先用 node:22-slim 编译前端与后端代码,再复制到 python:3.10-slim 运行时中安装 Python 依赖(供内置 Copilot Friday 使用),最终镜像只保留生产依赖,体积更小。
常用管理命令速查
| 命令 | 说明 |
|---|---|
./docker/docker.sh build |
构建 Docker 镜像 |
./docker/docker.sh start |
启动容器并显示启动日志 |
./docker/docker.sh stop |
停止并移除容器 |
./docker/docker.sh restart |
重启容器 |
./docker/docker.sh logs |
实时跟踪日志(Ctrl+C 退出) |
./docker/docker.sh exec |
进入容器 shell |
./docker/docker.sh status |
查看容器与镜像状态 |
./docker/docker.sh clean |
清理容器、镜像、卷等资源 |
./docker/docker.sh help |
显示帮助 |
手动部署:直接执行 docker / docker-compose 命令
如果想了解底层细节,也可以不使用脚本,手动执行两条核心命令:
# 构建镜像
docker build -f docker/Dockerfile -t agentscope/studio:latest .
# 启动(-d 后台运行)
docker compose -f docker/docker-compose.yml up -d
# 停止
docker compose -f docker/docker-compose.yml down
核心编排逻辑见 docker/docker-compose.yml:
services:
agentscope-studio:
image: agentscope/studio
ports:
- '3000:3000'
- '4317:4317'
volumes:
- ../data:/app/data
environment:
- LOG_LEVEL=warn
- PORT=3000
- HOME=/app/data
restart: unless-stopped
healthcheck:
test: ['CMD', 'curl', '-f', 'http://localhost:3000/trpc']
几个值得注意的设计:
restart: unless-stopped:Docker 重启后服务自动拉起,适合长期作为调试后端;healthcheck:每 30 秒请求/trpc接口探测健康状态,docker compose ps中健康检查通过后说明服务真正就绪。
启动成功后,浏览器访问 http://localhost:3000 即可打开 AgentScope Studio。
端口配置详解:3000 与 4317 各是干什么的 🔌
AgentScope Studio 对外暴露两个端口:
| 端口 | 用途 | 说明 |
|---|---|---|
3000 |
HTTP 服务端口 | 前端页面、REST/WS 接口,浏览器访问入口 |
4317 |
OpenTelemetry gRPC 端口 | 接收 Agent 应用上报的 Trace 数据 |
4317 是 OpenTelemetry 官方约定的 OTLP/gRPC 端口。AgentScope 应用通过该端口把 LLM 调用、工具执行等 Span 数据上报到 Studio,最终呈现为 Tracing 页面中的调用链与 Token 统计:
修改端口的方法
方法一:只改宿主机端口(最常用)
如果本机 3000 端口被占用,只需修改 docker/docker-compose.yml 中冒号左侧的宿主机端口:
ports:
- '8080:3000' # 宿主机 8080 → 容器内 3000
- '4318:4317' # 宿主机 4318 → 容器内 4317
修改后执行 ./docker/docker.sh start 生效。此时浏览器访问 http://localhost:8080,AgentScope 应用连接 http://localhost:4318 上报 Trace。
方法二:改容器内端口
容器内端口由环境变量 PORT 与 OTEL_GRPC_PORT 决定(见 docker/Dockerfile 的默认值 PORT=3000、OTEL_GRPC_PORT=4317)。这两个端口在服务端通过 packages/shared/src/config/server.ts 读取,也可以在启动位置用 .env 文件覆盖,详见 docs/tutorial/zh_CN/tutorial/quick_start.md。
⚠️ 小贴士:修改容器内端口时,请同时更新 compose 中的
environment、ports以及 healthcheck 地址,保持一致。
LOG_LEVEL 环境变量(默认 warn)可设为 debug、log、warn、error、silent,排查问题时可临时调高日志级别。
数据持久化详解:让数据不怕容器重建 💾
AgentScope Studio 的所有用户数据都存放在容器内的 /app/data 目录,compose 已将其映射到宿主机的 ./data(相对于 docker/ 目录,即项目根目录下的 data/):
volumes:
- ../data:/app/data
容器内通过 HOME=/app/data 环境变量让服务以标准 Linux 路径约定读写数据(见 packages/shared/src/config/server.ts),实际结构如下:
data/ # 宿主机目录(项目根目录下)
└── AgentScope-Studio/
├── database.sqlite # SQLite 数据库:项目、运行、消息、Trace
├── config.json # 用户配置
├── logs/ # 运行日志
└── Friday/
├── config.json # Friday 配置
└── session.json # Friday 会话历史
两个值得了解的细节:
- 首次启动自动生成 Friday 配置:docker/entrypoint.sh 会在
/app/data/AgentScope-Studio/Friday/config.json不存在时写入默认配置,然后启动node dist/server/src/index.js; - 备份与迁移零成本:只需拷贝宿主机的
data/目录即可完整迁移所有数据。
Friday 是 AgentScope Studio 内置的 Copilot,其模型提供方等配置界面如下,配置保存后写入上述 Friday/config.json:
连接 AgentScope 应用:部署成功的最后一步 ✅
在 AgentScope 项目中把 studio_url 指向 Studio 地址(HTTP 端口 3000):
import agentscope
agentscope.init(
...
studio_url="http://localhost:3000",
)
如果 Studio 部署在远程服务器上,替换为对应 IP 即可(记得让 3000 与 4317 端口可达)。运行 Agent 后,你可以在 Run 页面实时查看对话与工具调用过程:
常见问题排查 Troubleshooting 🛠️
| 现象 | 排查方法 |
|---|---|
| 服务启动慢 / 不确定是否就绪 | ./docker/docker.sh status 查看 healthcheck 状态 |
| 接口报错、页面空白 | ./docker/docker.sh logs 实时跟踪容器日志 |
| 端口冲突 | 按上文「修改端口的方法」调整 ports 映射 |
| 数据异常想从零开始 | ./docker/docker.sh stop 后删除宿主机 data/ 目录再 start |
| 镜像构建失败 | ./docker/docker.sh clean 清理后重新 build 并 start |
总结
- 一键启动:
./docker/docker.sh build+./docker/docker.sh start即可完成 AgentScope Studio 的 Docker 部署; - 两个端口:3000 用于 Web 访问,4317 用于 OpenTelemetry Trace 上报,按需修改 compose 的
ports映射即可; - 数据持久化:所有数据集中在宿主机
data/目录(挂载到容器/app/data),备份、迁移、重建容器互不影响; - 更多官方细节请阅读 docker/README.md。
祝部署顺利,玩得开心!🚀



