AgentScope Studio Docker部署完全指南:从一键启动到数据持久化与端口配置详解

原创2026-11-04 18:37:442,170 阅读
文章标签:人工智能AI 应用可观测性链路追踪数据可视化AI 评测前端后端

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 应用后即可看到项目与运行记录:

AgentScope Studio Docker部署后的项目列表界面

相关说明可参考官方文档 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 统计:

AgentScope Studio Tracing追踪总览界面

修改端口的方法

方法一:只改宿主机端口(最常用)

如果本机 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 会话历史

两个值得了解的细节:

  1. 首次启动自动生成 Friday 配置:docker/entrypoint.sh 会在 /app/data/AgentScope-Studio/Friday/config.json 不存在时写入默认配置,然后启动 node dist/server/src/index.js;
  2. 备份与迁移零成本:只需拷贝宿主机的 data/ 目录即可完整迁移所有数据。

Friday 是 AgentScope Studio 内置的 Copilot,其模型提供方等配置界面如下,配置保存后写入上述 Friday/config.json:

AgentScope Studio Friday Copilot配置界面

连接 AgentScope 应用:部署成功的最后一步 ✅

在 AgentScope 项目中把 studio_url 指向 Studio 地址(HTTP 端口 3000):

import agentscope

agentscope.init(
    ...
    studio_url="http://localhost:3000",
)

如果 Studio 部署在远程服务器上,替换为对应 IP 即可(记得让 3000 与 4317 端口可达)。运行 Agent 后,你可以在 Run 页面实时查看对话与工具调用过程:

AgentScope Studio ReActAgent运行时对话与Token统计界面

常见问题排查 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。

祝部署顺利,玩得开心!🚀

登录后查看全文
agentscope-studio