部署环境变量
面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/environment-variables/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。
本页汇总了控制面及相关组件在进程启动时读取的环境变量,涵盖 PostgreSQL 主库、Pod Base 分片数据库、ankole-function-runtime、部署密钥、对象存储与进程运行参数。WorkerProvider 的详细配置以 YAML 格式保存在 PostgreSQL 中,不在环境变量里声明。
支持在实例运行期间动态调整的设置见 系统配置;请勿将这些运行时设置写入 .env 或 Kubernetes Secret。
引导配置与部署密钥(进程启动)
以下变量必须在控制面启动前准备就绪:使用 Docker Compose 部署时写入 .env,使用 Helm 部署时存入 Chart 读取的 Secret。
| 变量 | 必需 | 含义 |
|---|---|---|
DATABASE_URL |
是(prod) |
控制面(Ankole.Repo)使用的 PostgreSQL 18+ 连接串 |
BASE_DB_URLS |
否 | 可选的分号(;)分隔 PostgreSQL 18+ 连接串列表,用于物理 Pod Base 分片库(Ankole.Pod.BaseRepo),支持查询参数 ankole_sharding、ankole_pool_size、ankole_stock_only;FOSS 单库部署未设置该变量时,默认将 DATABASE_URL 作为 base_default 使用;拒绝携带 sslmode 参数 |
ANKOLE_SECRET_BASE |
是(prod) |
站点级主密钥(Secret Base),用于派生数据加密与签名密钥 |
RELEASE_COOKIE |
是(prod) |
Erlang 分布式节点通信 Cookie;同一部署实例下的所有控制面节点必须使用相同的值 |
ANKOLE_FUNCTION_RUNTIME_TOKEN |
是(prod) |
控制面与 ankole-function-runtime 之间共享的内部 Bearer 认证密钥 |
ANKOLE_FUNCTION_RUNTIME_URL |
是(prod) |
ankole-function-runtime 的内部访问地址(例如 Compose 中的 http://function-runtime:9000 或 Kubernetes Headless Service 地址) |
POSTGRES_PASSWORD |
仅内置 PostgreSQL | PostgreSQL 数据库密码(启用内置 PostgreSQL 时必填;使用外部数据库时则通过 DATABASE_URL 或外部 Secret 提供) |
ANKOLE_HOST |
Compose | 部署实例对外提供服务的公开 DNS 域名 |
ACME_EMAIL |
Compose | Caddy 申请与续期 Let’s Encrypt 证书所用的联系邮箱 |
ANKOLE_DOCKER_GID |
Compose | 宿主机 Docker Socket 所属的用户组 ID;控制面以非特权用户运行,通过该用户组权限访问 Socket |
以上配置包含敏感密钥,应妥善存放在 .env 或 Kubernetes Secret 中,切勿提交到版本控制系统。使用 Docker Compose 部署时,可复制 .env.example 作为配置起点。
无需在 .env 或 Secret 中为 Worker 预先配置认证密钥——控制面在创建每个 Worker 时会自动签发专属凭据。
在 Helm Chart 的 values.yaml 中,对应的配置键路径分别为:secrets.ankoleSecretBase、secrets.releaseCookie、secrets.functionRuntimeToken、secrets.databaseURL、secrets.baseDBURLs、secrets.postgresqlPassword、controlPlane.siteAdminConsolePath 以及 functionRuntime.*。
运行时调优(进程环境)
以下变量在进程启动时读取,用于调整控制面或 ankole-function-runtime 进程的运行参数,本身不包含敏感密钥。
| 变量 | 默认 | 含义 |
|---|---|---|
ANKOLE_ENV |
— | 部署环境标识(如 prod、dev) |
ANKOLE_LOG_LEVEL |
info |
日志输出级别(debug、info、warning、error) |
POOL_SIZE |
10 |
控制面进程直接读取的 Ankole.Repo 数据库连接池大小 |
ANKOLE_DATABASE_POOL_SIZE |
10 |
Docker Compose .env 中的连接池变量,由 compose.yaml 映射为控制面容器内的 POOL_SIZE |
ANKOLE_POSTGRES_MAX_CONNECTIONS |
300 |
内置 PostgreSQL 数据库的 max_connections 上限 |
ANKOLE_SITE_ADMIN_CONSOLE_PATH |
/site-admin-console |
站点管理台(Site Admin Console)的 URL 访问路径 |
ANKOLE_FUNCTION_RUNTIME_IMAGE |
发布默认镜像 | Docker Compose 部署中使用的 ankole-function-runtime 容器镜像 |
ANKOLE_FUNCTION_RUNTIME_MAX_CONCURRENCY |
32 |
单个 ankole-function-runtime 容器允许的最大并发执行数 |
ANKOLE_LIBRARY_ROOT |
Chart 默认值 | 内置 Agent Library 的目录路径(app/library) |
ANKOLE_INTERNAL_SKILLS_ROOT |
— | 内部 Skill 包的目录路径 |
ANKOLE_AI_GATEWAY_BASE_URL |
— | 覆盖 AIGateway 的基础 URL |
文件存储(进程启动)
控制面对象存储(Ankole.ObjectStore)通过 ANKOLE_FILES_STORE 配置,统一承载统一云盘(Unified Drive)不可变文件对象(file_objects,涵盖公共空间、成员私人空间、Agent 云盘及会话文件)、Pod 与 Applet 资产(pod_files,含文档与 Base 附件、已编译的 Applet 产物包及自定义表情)、Skill 随附二进制文件(skill_files),以及冻结的聊天消息与投递附件。Worker 从不持有底层存储凭据,所有文件字节均经由控制面流式传输。完整的 OpenDAL 后端支持列表见控制面云盘与对象存储配置。
| 变量 | 必填 | 含义 |
|---|---|---|
ANKOLE_FILES_STORE |
是 | fs 表示使用控制面持久卷上的本地目录;s3 表示使用 Amazon S3 或 Cloudflare R2 等 S3 兼容存储 |
ANKOLE_FILES_FS_ROOT |
fs |
本地存储目录的绝对路径;Docker Compose 默认使用挂载在 /var/lib/ankole/files 的 files_data 卷 |
ANKOLE_FILES_S3_BUCKET |
s3 |
S3 存储桶名称 |
ANKOLE_FILES_S3_REGION |
s3 |
存储桶所在区域;Cloudflare R2 填写 auto |
ANKOLE_FILES_S3_ENDPOINT |
否 | S3 兼容存储服务的端点地址 |
ANKOLE_FILES_S3_ROOT |
否 | 存储桶内的对象键前缀 |
ANKOLE_FILES_S3_ACCESS_KEY_ID、ANKOLE_FILES_S3_SECRET_ACCESS_KEY |
否 | 静态访问凭据;留空时默认走 AWS 凭据链(包括 EKS Pod Identity) |
使用 fs 本地存储时,控制面仅支持单副本运行;若需运行多个控制面副本,请改用 s3 等远程共享存储。
向 s3 写入大文件时采用分段上传(Multipart Upload)。若控制面在上传中途停止,已上传的分段会残留在存储桶里,因此请为存储桶配置自动中止未完成分段上传的生命周期规则。
Worker Provider 引导配置
以下启动变量用于标识当前部署实例与目标 Worker 镜像。每个 WorkerProvider 的具体参数在 Console → 工作节点 → Providers 中以 YAML 配置,凭据单独加密存储。WorkerProvider 创建后,其类型、运行位置与持久存储设置不可更改;实例规格等运行参数修改后,会在 Agent 空闲时生效。
| 变量 | 含义 |
|---|---|
ANKOLE_AGENT_COMPUTER_IMAGE |
与当前控制面版本配套的目标 Worker 镜像 |
ANKOLE_WORKER_RUNTIME_FABRIC_ENDPOINT |
默认的 RuntimeFabric WebSocket 地址,提供商未配置 endpoints.runtimeFabricUrl 的 Worker 连接这个地址。只要提供商没有配置 endpoints.relayOrigin,Worker 还会通过自己所连 RuntimeFabric 地址对应的 HTTP 源访问 /api/v1/vfs/ 来挂载云盘,因此这个源必须能到达每一个控制面副本 |
ANKOLE_WORKER_INSTALLATION |
部署实例标识,默认为 ankole |
ANKOLE_WORKER_PROVIDERS_FILE |
可选的 WorkerProvider 种子 YAML 文件路径;首次导入时会与存量 Agent 的提供商指派在同一事务内完成 |
本地运行 bun dev 时,源码与内部 Skill 目录挂载由 config/dev.exs 配置,正式发布版本不包含这些开发期挂载。
模型提供商出站代理
当访问模型提供商的流量必须经过出站代理时,可在控制面进程上设置以下标准环境变量(https_proxy 等小写形式同样有效)。
| 变量 | 含义 |
|---|---|
HTTPS_PROXY |
HTTPS 和加密 WebSocket(wss)模型请求使用的代理 |
HTTP_PROXY |
HTTP 和明文 WebSocket(ws)模型请求使用的代理;未设置 HTTPS_PROXY 和 ALL_PROXY 时,加密请求也会回退使用该代理 |
ALL_PROXY |
未设置协议专用代理变量时,模型请求使用的兜底代理 |
NO_PROXY |
必须直连的目标主机或域名后缀,多项之间以英文逗号分隔 |
代理地址支持 http、https、socks5 和 socks5h 协议;若代理要求认证,可直接在 URL 中包含凭据。匹配优先级上,NO_PROXY 最高;加密请求依次读取 HTTPS_PROXY、ALL_PROXY、HTTP_PROXY;明文请求依次读取 HTTP_PROXY、ALL_PROXY。修改代理变量后必须重启控制面。
Worker 专属环境变量(Agent Computer Worker)
以下变量由控制面在创建 Worker 实例时自动注入,无需运维人员手动设置。Worker 启动后根据 WORKER_ID 识别所属 Agent;具体的会话与回合信息随每次 turn_start 消息下发,不通过环境变量传递。
| 变量 | 含义 |
|---|---|
WORKER_ID |
目标 Agent 的 UID;该 Worker 实例仅服务于这一个 Agent |
ANKOLE_RUNTIME_FABRIC_ENDPOINT |
Worker 回连控制面所使用的 ws:// 或 wss:// RuntimeFabric 地址 |
ANKOLE_RUNTIME_FABRIC_WORKER_AUTH_KEY |
当前实例代次(generation)专用的随机认证凭据;控制面仅保存其摘要及加密后的重试值 |
ANKOLE_WORKER_STORAGE |
由所属 WorkerProvider 设定的存储准备模式 |
如需为 Worker 注入通用环境变量,可在 WorkerProvider YAML 的 env 字段或 Kubernetes podTemplate 中设置。其中 ANKOLE_MAX_CONCURRENT_SLOTS 用于限制单个 Worker 并发运行的环境工作区与 Codex 回合数,默认值为 12;普通模型推理回合不占用该槽位。修改实例设置后,控制面会在 Agent 空闲时替换 Worker。
浏览器与内置 Skill 的路径(包括 ANKOLE_BROWSER_* 和 ANKOLE_BUILTIN_SKILLS_ROOT)由 Worker 镜像内置设定,不支持管理员手动调整。
在 Agent 环境变量编辑器中,PATH、HOME、DATABASE_URL 与 ANKOLE_ 前缀均受系统保留保护;这一限制并不影响在 WorkerProvider YAML 中配置受支持的实例参数。详见环境变量。
修改部署环境变量
在 Docker Compose 的 .env 或 Helm 的 values 文件中修改启动变量后,需重启对应进程使其生效。WorkerProvider 的设置请在 Console 中直接修改——已导入过的种子文件不会覆盖现有记录。每当镜像或实例配置发生变化,控制面都会在 Agent 空闲时替换对应的 Worker。