AgentScope Java 生产部署指南：AgentScope Service 用 Docker Compose 与 Helm 一键上线
【免费下载链接】agentscope-javaBuild distributed, production-grade, long-running agents.项目地址: https://gitcode.com/gh_mirrors/ag/agentscope-java
AgentScope Java 是用于构建分布式、生产级、长时运行智能体的开源框架，其AgentScope Service提供统一的 Agent 控制面与治理平台。本文将带你用Docker Compose与Kubernetes Helm两条路径，把 AgentScope Service 一键部署到生产环境，从初始化密钥到验证上线，全程约 10 分钟。
认识 AgentScope Service：企业级智能体管控平台
AgentScope Service 构建于 AgentScope Harness 之上，定位为企业统一的 Agent 控制面与编排中心：
- 控制面（Control Plane）：为所有 Agent 提供注册、查询与分布式协调，兼容 AgentScope、LangChain、ADK 等主流运行时；
- Managed Agents：低代码创建与托管运行智能体，推理与工具执行分离；
- Agent Teams：把不同技术栈的 Agent 编排成协作团队，共同完成复杂任务。
整套服务由 4 个组件 + 1 个数据库组成，生产部署架构如下：
| 平面 | 职责 | 端口 |
|---|---|---|
| Gateway | 公共入口、认证与 API 路由 | 18080（对外） |
Control Plane（aistiod） | Agent 状态、Session、Team 管理 | 8081（内部） |
| Dataplane | 托管运行时、事件日志、SSE | 8082（内部） |
| Scheduler | 定时任务、Channel、出站任务 | 8083（内部） |
| PostgreSQL | 产品与运行状态存储（cp/rt/dp三个 schema） | 5432 |
💡 只有 Gateway 对外暴露，其余组件与数据库都保留在私网内，这是两种部署方式共同的安全设计。
部署前准备：5 分钟备齐依赖
两种路径的共同前置条件：
- Docker Engine / Docker Desktop+ Compose v2（Compose 路径必需）；
- Kubernetes 集群 + Helm 3（Helm 路径必需）；
- 模型 API Key（如 DashScope），服务本身不包含模型凭据；
- 从 Release 发布说明中获取版本号与镜像仓库命名空间，下载
agentscope-service-VERSION-compose.tar.gz并校验 SHA-256； - 磁盘空间要能容纳数据库与工作文件，CPU/内存需求取决于并发与工具负载。
⚠️ 特别注意：PostgreSQL需要提前具备cp、rt、dp三个 schema，Compose 包内已附带初始化脚本 postgres-init.sql，容器首次启动时自动执行。
路径一：Docker Compose 一键部署（最快上手）
适合单服务器、团队内部环境或私有化体验，官方部署包见 deploy/README.md，核心编排文件是 compose.yaml。
一键初始化环境
解压部署包后，只需 3 行命令：
./init-env.sh VERSION REGISTRY/NAMESPACE docker compose pull docker compose up -d --wait --wait-timeout 600初始化脚本 init-env.sh 会用openssl随机生成一套完整密钥，写入权限为600的.env文件，包含：
- 数据库密码、JWT 签名密钥、内部调用令牌、Vault 加密主密钥；
- 初始管理员密码（
AISTIO_BOOTSTRAP_PASSWORD）。
🔒 生产要点：.env里没有任何可预测的开发密钥，且脚本绝不覆盖已有.env——重复运行不会重置密码或版本，升级时手动修改SERVICE_VERSION即可。
验证上线并登录
docker compose ps curl -fsS http://localhost:18080/actuator/health确认整栈健康后，打开http://localhost:18080，用admin+.env中的AISTIO_BOOTSTRAP_PASSWORD登录，并立即在 Profile 中修改密码。初始管理员只在空用户库时创建，重启不会重置已有账号，生产环境也没有任何演示账号。
配置模型与执行环境
编辑.env填入模型凭据后重建容器：
DASHSCOPE_API_KEY=你的模型凭据 BUILDER_ALLOW_LOCAL_ENVIRONMENT=false⚠️
BUILDER_ALLOW_LOCAL_ENVIRONMENT生产环境请保持false（默认值）。仅在可信本地评估时才开启，它允许 Local 工具在 Dataplane 容器内直接执行；需要隔离工具执行时，请配置 Sandbox 或自托管 Worker。
数据持久化方面，Compose 包用3 个命名卷分别保存 PostgreSQL 数据、共享 Workspace 与 Artifact，例如 workspaces.png 所示的 Workspace 页面中的文件都落在这些卷里。停止服务用docker compose down，不要加-v，否则会删除全部应用数据。
启用远程访问（可选）
如需从其他设备访问或对接 OAuth/Channel 公网回调：
- 准备域名 + TLS 证书，HTTPS 反向代理指向 Gateway；
- 在
.env设置BUILDER_OAUTH_PUBLIC_URL=https://你的域名，按需调整BIND_ADDRESS与GATEWAY_PORT； - 重建容器后，验证登录、长回复、SSE 重连与回调链路（代理必须支持 SSE，不能只验证首页可打开）。
路径二：Helm Chart 部署到 Kubernetes（规模化生产）
面向集群化生产环境，官方 Helm Chart 一次安装 Gateway、Control、Dataplane、Scheduler 四个 Deployment，PostgreSQL 与存储由你独立管理。Chart 说明见 helm/agentscope-service/README.md，完整文档见 kubernetes.md。
第 1 步：准备数据库与 Secret
- 用应用数据库所有者执行
postgres-init.sql，创建cp、rt、dp三个 schema； - 复制 kubernetes.env.example 到私有文件，替换全部占位值（数据库连接、JWT / internal / Vault 密钥、初始管理员密码、模型凭据）：
kubectl create namespace agentscope kubectl -n agentscope create secret generic agentscope-service \ --from-env-file=/private/path/service.envSecret 是运行配置，切勿把明文密钥提交到代码仓库。
第 2 步：准备 values 并安装
values.yaml 中的关键项：persistence.workspaces需ReadWriteMany共享存储（Workspace 会被多个组件挂载），persistence.artifacts默认 ReadWriteOnce，Ingress 可选开启：
existingSecret: agentscope-service allowLocalEnvironment: false publicURL: https://agentscope.example.com persistence: workspaces: storageClass: shared-rwx size: 20Gi artifacts: storageClass: standard size: 20Gi ingress: enabled: true className: nginx host: agentscope.example.com tls: - hosts: [agentscope.example.com] secretName: agentscope-service-tls使用 Release 提供的 Chart 包安装指定版本：
helm upgrade --install service ./agentscope-service-VERSION.tgz \ --namespace agentscope \ --set imageRepository=REGISTRY/NAMESPACE \ -f production-values.yaml \ --wait --timeout 10m第 3 步：验证用户路径
kubectl -n agentscope get pods,pvc,svc,ingress kubectl -n agentscope port-forward service/service-agentscope-gateway 18080:8080确认 PVC Bound、Pod Ready，用初始管理员登录公开域名并修改密码，再验证模型连接、首次 Chat 与长连接。port-forward只用于排障，不能替代公网回调地址验证。
生产安全与运维要点
- 备份三位一体：数据库（
pg_dump）+ Workspace/Artifact 卷快照 + 密钥（.env/ Secret）。只有三者能共同恢复，备份才算有效，详细流程见 operations.md； - 升级走维护窗口：先阅读迁移说明、在测试库副本演练，再备份后升级。注意组件镜像回退不保证旧版本可读新 schema；
- 卸载保留 PVC：Helm Chart 卸载时不会删除你创建的持久卷；重新安装时显式指定保留的
existingClaim； - 诚实的预期：当前 Chart 每组件单副本 + Recreate 更新，不提供多副本 HA 或无停机迁移，请据此规划容量与发布节奏。
官方文档与延伸阅读
| 资料 | 路径 |
|---|---|
| Compose 部署说明 | deploy/README.md |
| 生产部署包配置 | deploy/compose.yaml |
| Helm Chart 文档 | helm/agentscope-service/README.md |
| 本地快速体验 | quickstart.md |
| 生产安装（K8s） | kubernetes.md |
| 备份与升级手册 | operations.md |
| 服务总览 | agentscope-service/README_zh.md |
现在，打开控制台创建第一个 Managed Agent，发送第一条消息，你的企业级智能体管控平台就正式上线了 🚀
【免费下载链接】agentscope-javaBuild distributed, production-grade, long-running agents.项目地址: https://gitcode.com/gh_mirrors/ag/agentscope-java
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
