此为预览文档，正式版本尚未发布。
准备
安装 Docker Engine 或 Docker Desktop、Compose v2 和 OpenSSL，确认docker info 与 docker compose version 正常。模型任务需要你自己的模型凭据。先保证磁盘能保存数据库与工作文件；实际 CPU/内存需求取决于并发和工具负载。
从 Release 下载页选择版本，下载 agentscope-service-VERSION-compose.tar.gz 和 SHA256SUMS。比较压缩包的 SHA-256 与清单中的对应条目：Linux 使用 sha256sum，macOS 使用 shasum -a 256。下面的 VERSION 与 REGISTRY/NAMESPACE 使用该 Release 公布的准确值，镜像仓库路径不包含 https://。
1. 启动
600 的 .env，保存数据库密码、JWT 密钥、内部令牌、Vault 密钥和初始管理员密码。重复运行脚本保留原文件，不更新版本或重置密码。
2. 登录
http://localhost:18080，用 admin 与 .env 中的 AISTIO_BOOTSTRAP_PASSWORD 登录，在 Profile 修改密码。初始管理员只在空用户库中创建，重启不重置已有账号。
3. 配置执行能力
可信本地体验可以编辑.env：
docker compose up -d --wait --wait-timeout 600。Local 工具运行在 Dataplane 容器内，主机文件并不自动挂载。随后按快速开始创建 Managed Agent。
已有 Coding Agent 时，也可走 Hosted Agent 路径。需要隔离工具时保持 Local 关闭，配置相应 Environment。
入口与网络
同机反向代理可以转发到
127.0.0.1:18080。代理运行在另一个容器时，localhost 指代理容器自身，需要配置共享网络或可达的宿主地址。只向用户暴露 Gateway，内部组件和数据库保留在私网。
启用远程访问
需要从其他设备访问本地服务，或联调 OAuth/Channel 公网回调时，再配置这一部分。准备域名和 TLS 证书，将 HTTPS 代理指向 Gateway。在.env 设置 BUILDER_OAUTH_PUBLIC_URL=https://agentscope.example.com，如需监听其他地址再设置 BIND_ADDRESS 和 GATEWAY_PORT，之后重建容器。
代理必须支持 SSE：及时转发事件、不缓存事件流，并设置足够长的读取超时。验证登录、长回复、刷新重连及 OAuth/Channel 回调，不能只验证首页可打开。
数据持久化
三个命名卷分别保存 PostgreSQL、共享 Workspace 和 Artifact。使用docker volume ls 找到 Compose 项目卷，按存储策略备份。.env 中的 Vault master key 必须和加密数据一起保存。
需要接入宿主目录时显式配置挂载，并保证容器用户 65532:65532 有必要访问权限。不要把本地路径写入 Agent 指令后就假定容器能够读取。业务资料的访问应与所选 Environment 保持一致。
更新配置和版本
编辑.env 后：
init-env.sh 不覆盖已有配置，因此修改版本应编辑 SERVICE_VERSION。密钥变更需要协调组件；Vault master key 不是可随意替换的普通密码。
完整 Compose 运行 standalone HTTP。需要 ASDP 的 External SDK 请使用对应接入部署。生产环境安装见生产安装。升级前完成备份恢复演练。
停止、继续与排错
docker compose down 停止服务，数据卷仍保留；重新运行启动命令即可继续。不要在日常停止时加 -v，它会删除数据卷。
启动失败先运行 docker compose ps -a 和 docker compose logs --tail=100，检查镜像拉取、数据库和组件错误。端口冲突可修改 .env 的 GATEWAY_PORT，并同步修改 BUILDER_OAUTH_PUBLIC_URL 后重建容器。
下一步：快速开始 · 生产安装。