配置

默认的 Docker Compose 服务栈无需配置，并且只监听回环地址。compose.env 只用于部署拓扑和引导密钥，然后用 Setup Server 来配置登录、提供方应用和部署选项。

Compose 环境变量复制锚点链接

只有在需要覆盖默认值时才复制模板：

cp compose.env.example compose.env

在每条 Compose 命令中都带上它：

docker compose --env-file compose.env up -d

compose.env 已被 gitignore。不要把它纳入源码管理或未经批准的备份。

镜像版本复制锚点链接

为获得可复现的部署，请固定到某个 AgentConnect 发布版本：

AGENTCONNECT_VERSION=vX.Y.Z

已发布的应用镜像和迁移镜像目前面向 linux/amd64。

本地端口复制锚点链接

AGENTCONNECT_BIND_ADDRESS 对 Web、控制平面和 Relay 默认为 127.0.0.1。在提供的 Compose 文件中，PostgreSQL、连接器网关、Setup Server 和本地 Logto 叠加配置始终只监听回环地址。

网络与公开 URL复制锚点链接

容器之间在内部使用 Docker 服务名。浏览器、Daemon、提供方回调和链接则使用下列公开源地址：

不要添加末尾斜杠。

对于远程 Daemon 或网络部署，请把这些默认值替换为可达的源地址。浏览器和回调源地址使用 HTTPS，面向 Daemon 的 Relay URL 使用 wss://。反向代理必须为控制平面和 Relay 连接保留 WebSocket 升级。

在创建 GitHub 或 Slack 应用之前，先设定最终的公开 URL。Setup 会根据这些值推导出它们的回调清单。如果之后 URL 发生变化，请先用同样的环境变量和 Compose 覆盖文件重新创建 Setup Server，再更新提供方应用。对于基础服务栈：

docker compose --env-file compose.env up -d --force-recreate setup-server

更新提供方应用之后，用同样的环境变量和 Compose 覆盖文件重新创建各运行时服务：

docker compose --env-file compose.env up -d --force-recreate control-plane relay web

不要把无认证的服务栈或其默认密钥发布到网络上。Compose 是单主机拓扑，不是高可用部署。

Setup Server复制锚点链接

Setup Server 在 http://localhost:8091 提供基于浏览器的 AgentConnect Setup 界面。它包含在基础服务栈中，并且始终绑定到回环地址。

用它来：

• 引导 Logto 登录；
• 创建、接管、检查或清除提供方应用；
• 存储提供方凭证，且不会返回已保存的密钥值；以及
• 启用或禁用预设的 agentconnect Agent。

保存的更改会在服务启动时加载。用以下命令使其生效：

docker compose restart control-plane relay web

如果 Compose 运行在另一台主机上，请转发 Setup Server，而不是把它公开暴露：

ssh -L 8091:127.0.0.1:8091 operator@host.example

然后在本地打开 http://localhost:8091。

关于初始管理员以及 Logto Cloud 或外部 Logto OSS 的设置，请继续阅读登录。

预设 Agent复制锚点链接

新组织默认会获得一个内置的 agentconnect Agent。在 Setup 中打开选项，取消勾选启用预设 Agent，然后保存。这会阻止后续的自动创建和回填；它不会删除已经存在的 Agent。

数据库与引导密钥复制锚点链接

PostgreSQL 18 把数据存储在 agentconnect_postgres-data 卷中。docker compose down 会保留它；docker compose down --volumes 会删除它。

在任何网络暴露之前，请替换这些默认值：

为每个密钥分别生成一个值：

openssl rand -hex 32

轮换 AGENTCONNECT_API_KEY_PEPPER 会使现有的 Daemon 和个人 API 密钥失效。在非临时用途之前请先备份 PostgreSQL。

密钥存储复制锚点链接

在 AgentConnect 或 Setup 中显示为只写的密钥仍然需要静态加密。默认的 SECRET_CIPHER=none 会把它们以明文存储在 PostgreSQL 中。对于生产或暴露在网络上的部署，请使用 HashiCorp Vault Transit。

创建一个 Transit 密钥，以及一条可以用它加密和解密的策略：

vault secrets enable transit
vault write -f transit/keys/agentconnect-cp

path "transit/encrypt/agentconnect-cp" {
  capabilities = ["update"]
}

path "transit/decrypt/agentconnect-cp" {
  capabilities = ["update"]
}

把 Vault 设置同时传给控制平面和 Setup Server，让它们使用同一个加密根：

# compose.vault.yaml
services:
  control-plane:
    environment: &vault
      SECRET_CIPHER: vault-transit
      VAULT_ADDR: ${VAULT_ADDR}
      VAULT_TRANSIT_KEY: ${VAULT_TRANSIT_KEY:-agentconnect-cp}
      VAULT_TRANSIT_MOUNT: ${VAULT_TRANSIT_MOUNT:-transit}
      VAULT_TOKEN: ${VAULT_TOKEN}
  setup-server:
    environment: *vault

使用受策略限制的令牌而不是 Vault 根令牌，然后重新创建这两个服务：

docker compose --env-file compose.env -f compose.yaml -f compose.vault.yaml \
  up -d --force-recreate control-plane setup-server

在做好数据库备份之后，加密此前以明文存储的值：

docker compose --env-file compose.env -f compose.yaml -f compose.vault.yaml \
  exec control-plane node dist/secrets/rewrap-cli.js

该命令可以断点续跑，也可以在轮换 Transit 密钥之后重新运行。Vault 工作负载身份可以通过 VAULT_JWT_ROLE、VAULT_JWT_PATH 和 VAULT_AUTH_MOUNT 来使用，以替代 VAULT_TOKEN。

文件传输与对象存储复制锚点链接

控制台的文件传输需要一个兼容 S3 的对象存储。有了它，用户可以在 Playground 消息中附加任意文件，控制台也能下载不超过存储上限的任意大小的工作区文件。文件字节通过短时有效的签名 URL 在浏览器或 Daemon 与存储之间直接传输；控制平面只负责签名，从不接触文件内容。没有对象存储时，只能附加图片，工作区文件经由控制平面下载，每个文件最大 8 MiB。

签名 URL 必须是 https://，并且浏览器和 Daemon 会直接访问存储，因此存储需要一个它们信任的 HTTPS 源地址。

内置存储（HTTPS 叠加配置）复制锚点链接

compose.logto.https.yaml 叠加配置把服务栈和 Logto 登录放在 Caddy HTTPS 之后，同时还会运行一个 RustFS 对象存储。Caddy 在单独的 HTTPS 端口上提供它，一次性的 object-store-setup 服务会在每次启动时创建 agentconnect 存储桶、它的生命周期规则，以及允许控制台源地址的 CORS 规则。在叠加配置的 .env 中加入：

AGENTCONNECT_OBJECT_STORE_HTTPS_PORT=1445
AGENTCONNECT_OBJECT_STORE_ACCESS_KEY=agentconnect-store
AGENTCONNECT_OBJECT_STORE_SECRET_KEY=<random-password>

缺少其中任何一项时，叠加配置会拒绝启动。每条命令都要带上全部三个 Compose 文件：

docker compose --env-file .env \
  -f compose.yaml -f compose.logto.yaml -f compose.logto.https.yaml \
  up -d

通过 Caddy 检查存储：

curl -k https://<host>:1445/health

浏览器和 Daemon 会沿着下载链接访问这个端口，因此除了控制台之外，它们也必须为这个端口信任 Caddy CA。仓库中的 Caddy HTTPS 指南完整介绍了这个叠加配置，包括如何导出并信任 Caddy 根证书。

外部存储桶复制锚点链接

如果要改用你自己的存储桶，请在 compose.env 中把 AC_FILE_TRANSFER 设置为单行 JSON 文档：

AC_FILE_TRANSFER='{"version":1,"endpoint":"https://s3.example.com","region":"us-east-1","bucket":"agentconnect","forcePathStyle":true,"credentials":{"source":"static","dir":"/run/secrets","accessKeyIdKey":"file_transfer_access_key_id","secretAccessKeyKey":"file_transfer_secret_access_key"}}'

用一个覆盖文件把密钥文件挂载到控制平面：

# compose.file-transfer.yaml
services:
  control-plane:
    secrets:
      - file_transfer_access_key_id
      - file_transfer_secret_access_key
secrets:
  file_transfer_access_key_id:
    file: ./secrets/file-transfer-access-key-id
  file_transfer_secret_access_key:
    file: ./secrets/file-transfer-secret-access-key

docker compose --env-file compose.env -f compose.yaml -f compose.file-transfer.yaml \
  up -d --force-recreate control-plane

存储桶还需要：

• 一条生命周期规则：让 <prefix>/src/（没有前缀时为 src/）下标记为 ac-cache=pending 的对象在 2 天后过期。在规则存在之前，控制平面会拒绝传输，并在日志中给出需要添加的规则。规则文档以及 AWS 和 MinIO 的命令见 Chart README。
• 一条 CORS 规则：允许控制台源地址发起 GET 和 PUT，并允许 content-type、x-amz-checksum-sha256 和 x-amz-tagging 请求头。
• 权限：密钥对需要在 <prefix>/src/*/transfer/ 下拥有 s3:PutObject、s3:PutObjectTagging 和 s3:GetObject，并在存储桶上拥有 s3:GetLifecycleConfiguration。

私有证书颁发机构复制锚点链接

如果 GitLab 或 Gitea 实例出示的是由私有证书颁发机构签发的证书，就需要让该机构的证书包在每个进程内部都存在的文件路径上可读，包括 Agent 沙箱。让每个 Runtime 都指向它：

只存在于宿主机上的路径是不够的：Agent 在拥有独立文件系统视图的沙箱中运行，因此证书包也必须挂载到沙箱里，而且这些变量必须传递到沙箱环境中。请在配置沙箱镜像及其环境的地方设置它们，而不是只在宿主机上设置。

Agent 会话发出的 Git 和代码托管平台 API 请求会经过 Daemon 的凭证代理，代理用同样这些颁发机构校验实例，因此即使会话运行在别处，Daemon 进程本身也需要它们。

Relay 从不主动连接该实例——它只接收 Webhook 投递——因此它不需要证书包，也不需要出站访问。

生产环境检查清单复制锚点链接

• 固定发布镜像版本。
• 配置 OIDC 登录和 API Resource。
• 替换所有默认密钥，并启用加密的密钥存储。
• 如果使用连接器，设置连接器加密密钥，并备份其卷。
• 把 Web、控制平面、Relay 和 Logto 放在 HTTPS 之后。
• 为文件传输配置带生命周期规则的 HTTPS 对象存储，或者不启用它。
• 保留 WebSocket 升级。
• 备份 PostgreSQL 并测试恢复。
• 让 Setup Server、PostgreSQL 和连接器网关远离公共网络。