跳到正文
Ankole

控制面云盘与对象存储配置

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/drive-storage/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

控制面对象存储(Ankole.ObjectStore)通过 ANKOLE_FILES_STORE 配置,统一承载每个 Agent 的云盘(Worker 停止期间仍可读写)、Pod file 页面、Pod 文档/Base/Chat 与对话附件,以及已编译的 Applet 产物包。其中,路径、权限和内容引用保存在 PostgreSQL 中,按内容寻址的对象字节则存放在 OpenDAL 后端。Ankole 支持 fs、s3、azblob、d1、cos、postgresql、oss、tos、gcs、sftp 和 webdav。

对象存储属于站点级启动配置,同一站点下的所有租户共用同一后端。WorkerProvider 的持久 Home、缓存盘以及 Cloudflare R2 备份需单独配置,详见 WorkerProvider 与缓存盘;面向用户的云盘操作说明见 文件管理。

选择后端

部署 ANKOLE_FILES_STORE 使用方式
单机或一个控制面副本 fs 持久卷或本地文件夹
AWS S3 s3 存储桶、区域(Region)和 AWS 凭据链
Cloudflare R2 s3 S3 API 端点、区域设为 auto、R2 凭据
其他 S3 兼容服务 s3 服务端点地址、签名区域和凭据,上线前需验证实际兼容性

运行多个控制面副本时,各副本必须连接相同的远程共享后端和根路径,并组成 Distributed Erlang cluster。Worker 还须能够直达 Pod IP,不能配置 endpoints.relayOrigin。官方 Helm Chart 会配置集群发现,并在多副本下拒绝 files.store: fs 或提供商的 endpoints.relayOrigin。聊天长连接会跨节点协调归属,Oban 共用任务队列。部署与升级要求见控制面副本说明。

环境变量

变量 适用后端 要求
ANKOLE_FILES_STORE 全部 生产环境必填,用于选择受支持的存储后端
ANKOLE_FILES_FS_ROOT fs 控制面容器或进程内可写的绝对路径
ANKOLE_FILES_S3_BUCKET s3 预先创建好的存储桶名称
ANKOLE_FILES_S3_REGION s3 必填;AWS 填写存储桶所在区域,R2 填写 auto
ANKOLE_FILES_S3_ENDPOINT s3 S3 兼容服务的端点地址;AWS S3 通常留空
ANKOLE_FILES_S3_ROOT s3 可选的对象键前缀,如 /ankole/production/
ANKOLE_FILES_S3_ACCESS_KEY_ID s3 可选静态凭据,须与下一项同时设置
ANKOLE_FILES_S3_SECRET_ACCESS_KEY s3 可选静态凭据,须与上一项同时设置

未配置静态凭据时,控制面默认走 AWS 凭据链(包括已配置的 EKS Pod Identity)。存储凭据和工作负载身份只需提供给控制面;Worker 通过 RuntimeFabric 读写自己的云盘,无需持有存储桶密钥。上述变量均在进程启动时读取,修改后需重启控制面才能生效。请勿将本页未列出的其他 OpenDAL 参数直接拼作 Ankole 环境变量。

其他 OpenDAL 后端

其他后端的环境变量统一采用 ANKOLE_FILES_<SCHEME>_<FIELD> 格式,后端标识与字段名均使用大写字母。例如,连接 Azure Blob 需设置 ANKOLE_FILES_STORE=azblob、ANKOLE_FILES_AZBLOB_CONTAINER 和 ANKOLE_FILES_AZBLOB_ENDPOINT。下表列出了 Ankole 支持的全部字段;若必填字段缺失或为空,控制面启动会直接失败。

后端 必填字段 可选字段
azblob CONTAINER, ENDPOINT ROOT, ACCOUNT_NAME, ACCOUNT_KEY, SAS_TOKEN
d1 ACCOUNT_ID, DATABASE_ID, TOKEN, TABLE, KEY_FIELD, VALUE_FIELD ROOT
cos BUCKET, ENDPOINT ROOT, SECRET_ID, SECRET_KEY, SECURITY_TOKEN
postgresql CONNECTION_STRING, TABLE, KEY_FIELD, VALUE_FIELD ROOT
oss BUCKET, ENDPOINT ROOT, ACCESS_KEY_ID, ACCESS_KEY_SECRET, SECURITY_TOKEN
tos BUCKET, ENDPOINT, REGION ROOT, ACCESS_KEY_ID, SECRET_ACCESS_KEY, SECURITY_TOKEN
gcs BUCKET ROOT, ENDPOINT, CREDENTIAL, CREDENTIAL_PATH
sftp ENDPOINT ROOT, USER, KEY, KNOWN_HOSTS_STRATEGY
webdav ENDPOINT ROOT, USERNAME, PASSWORD, TOKEN

各类凭据均应保存在控制面的部署 Secret 中。GCS 的 CREDENTIAL 为经 Base64 编码的凭据 JSON,CREDENTIAL_PATH 则指向原始 JSON 文件路径;若两者均未提供,控制面将使用上游 Google 默认凭据链。SFTP 调用控制面镜像内置的 ssh 客户端,KEY 填写私钥文件路径;主机指纹校验策略默认为 strict,需预先配置控制面运行用户的 ~/.ssh/known_hosts。WebDAV 支持用户名密码(Basic)认证或 Bearer TOKEN 认证。

使用 D1 或 PostgreSQL 作为对象存储后端时,必须预先手动建表——Ankole 不会自动创建这张表。其中 D1 表需使用 TEXT 主键与 BLOB 值列,PostgreSQL 表需使用 TEXT 主键与 BYTEA 值列,再通过 TABLE、KEY_FIELD 和 VALUE_FIELD 指定表名与列名。需要注意,D1、PostgreSQL 和 WebDAV 后端在读写时都会在内存中缓冲完整对象;此外,D1 的字符串、BLOB 和单行大小上限均为 2,000,000 字节,且 Ankole 不会跨行拆分单个对象。若有大文件存储需求,请改用对象存储桶后端。

SFTP 后端在写入时会先在目标路径旁生成临时文件,写完关闭后再重命名落盘,因此服务端必须支持原子替换重命名(例如 OpenSSH 的 posix-rename 扩展)。若控制面进程在写入中途异常退出,存储目录中可能会残留 blobs/<digest>.<uuid>.tmp 临时文件,可在所有写入进程停止的维护窗口内统一清理。

在 Helm 部署中,通过 files.store 选择后端:非敏感变量填入 controlPlane.extraEnv,凭据变量放入 secrets.existingSecret。Chart 会将该 Secret 注入控制面容器和数据库迁移容器的环境变量,同时在控制面容器内将其只读挂载至 /etc/ankole/bootstrap;若使用 SFTP,私钥文件权限与 known_hosts 都必须允许 uid 10001 读取。在 Docker Compose 部署中,可参考下文覆盖文件(override)的写法,将所选后端的变量同时传给迁移服务与控制面服务。正式上线前,请逐一验证对象的读取、写入、覆盖替换、删除及大文件传输。

本地文件夹与持久卷

ANKOLE_FILES_STORE=fs
ANKOLE_FILES_FS_ROOT=/var/lib/ankole/files

ANKOLE_FILES_FS_ROOT 填写控制面进程视角下的路径。容器化部署必须将该路径挂载到持久化存储上,否则重建或删除容器就会丢失全部文件。控制面镜像以 uid/gid 10001 运行,该用户必须对该目录具备创建、写入、重命名和删除权限;fs 后端还会在根目录下自动创建 .tmp 子目录。

官方 Docker Compose 默认已将 files_data 命名卷挂载到 /var/lib/ankole/files。若需改用宿主机目录,请先创建目录并授予 uid/gid 10001 写权限,再通过 Compose 覆盖文件替换卷挂载:

services:
  control-plane:
    volumes:
      - ./ankole-files:/var/lib/ankole/files

对已有数据的站点更换挂载目录前,必须先把原存储卷中的内容完整复制过去,切勿直接将空目录挂载到同一路径——替换挂载并不会自动迁移旧卷中的文件。

Helm 的本地存储配置如下:

controlPlane:
  replicaCount: 1
files:
  store: fs
  persistence:
    size: 100Gi
    storageClass: YOUR_STORAGE_CLASS
    # existingClaim: YOUR_EXISTING_FILES_PVC

Chart 会创建(或接管已有)文件 PVC 并挂载至 /var/lib/ankole/files,且在卸载 Release 时默认保留由 Chart 创建的 PVC。复用已有 PVC 时,同样需确保目录权限符合要求并纳入备份范围。该 PVC 仅承载控制面对象存储(如云盘与附件),Agent 持久 Home 使用独立的存储配置。

AWS S3

先创建私有 S3 存储桶,并为控制面配置 IAM 身份权限,允许在所选前缀下读取、写入、删除对象以及执行分段上传(Multipart Upload);若存储桶启用了 KMS 加密,还需授予配套的 KMS 加解密权限。

ANKOLE_FILES_STORE=s3
ANKOLE_FILES_S3_BUCKET=ankole-files
ANKOLE_FILES_S3_REGION=ap-southeast-1
ANKOLE_FILES_S3_ROOT=/ankole/production/

若使用 AWS 工作负载身份(如 EKS Pod Identity 或 IAM Role),可省略静态凭据变量;若使用静态访问密钥,则需在部署 Secret 中同时提供 ANKOLE_FILES_S3_ACCESS_KEY_ID 与 ANKOLE_FILES_S3_SECRET_ACCESS_KEY。

Helm 配置示例:

files:
  store: s3
  s3:
    bucket: ankole-files
    region: ap-southeast-1
    root: /ankole/production/

可通过 secrets.existingSecret 引用包含上述两项 S3 密钥的引导 Secret;该 Secret 还必须一并包含部署所需的数据库凭据(DATABASE_URL,以及启用内置 PostgreSQL 时的 POSTGRES_PASSWORD)、原 ANKOLE_SECRET_BASE、ANKOLE_FUNCTION_RUNTIME_TOKEN 与 RELEASE_COOKIE。Chart 也支持通过 secrets.filesS3AccessKeyID 和 secrets.filesS3SecretAccessKey 传入密钥,但切勿将真实密钥明文提交到 values 文件中。

Cloudflare R2 与其他 S3 兼容服务

Cloudflare R2 同样复用 s3 后端:

ANKOLE_FILES_STORE=s3
ANKOLE_FILES_S3_BUCKET=ankole-files
ANKOLE_FILES_S3_REGION=auto
ANKOLE_FILES_S3_ENDPOINT=https://ACCOUNT_ID.r2.cloudflarestorage.com
ANKOLE_FILES_S3_ROOT=/ankole/production/
ANKOLE_FILES_S3_ACCESS_KEY_ID=YOUR_R2_ACCESS_KEY_ID
ANKOLE_FILES_S3_SECRET_ACCESS_KEY=YOUR_R2_SECRET_ACCESS_KEY

请使用 R2 专用的 S3 API 访问密钥;ANKOLE_FILES_S3_ENDPOINT 需填写账户级 S3 API 端点地址,而非公开访问域名或 Cloudflare Worker URL。关于 auto 区域设置及受支持的接口范围,请参阅 R2 S3 API 兼容说明。使用 Helm 部署时,对应设置 files.s3.endpoint、files.s3.region 和 files.s3.root 即可。

MinIO 等其他 S3 兼容存储同样将后端设为 s3,并填写实际端点地址与签名区域。存储服务宣称兼容 S3 并不代表所有行为完全一致,正式上线前务必实测读取、写入、删除、分段上传及大文件传输。Ankole 仅开放本页列出的后端与启动字段,不支持 S3 虚拟主机风格寻址或自定义签名参数。底层参数细节可参考 OpenDAL 的 S3 后端文档。

Compose 使用 S3

官方 compose.yaml 在配置中将对象存储后端固定为 fs,仅在 .env 中添加 ANKOLE_FILES_STORE=s3 并不会覆盖该设置。请新建一份覆盖文件(例如 compose.files-s3.yaml),把相同的存储配置同时传给数据库迁移服务与控制面服务。以下示例采用静态凭据:

x-files-environment: &files-environment
  ANKOLE_FILES_STORE: s3
  ANKOLE_FILES_S3_BUCKET: ${ANKOLE_FILES_S3_BUCKET:?Set the files bucket}
  ANKOLE_FILES_S3_REGION: ${ANKOLE_FILES_S3_REGION:?Set the files region}
  ANKOLE_FILES_S3_ENDPOINT: ${ANKOLE_FILES_S3_ENDPOINT:-}
  ANKOLE_FILES_S3_ROOT: ${ANKOLE_FILES_S3_ROOT:-/ankole/}
  ANKOLE_FILES_S3_ACCESS_KEY_ID: ${ANKOLE_FILES_S3_ACCESS_KEY_ID:?Set the access key}
  ANKOLE_FILES_S3_SECRET_ACCESS_KEY: ${ANKOLE_FILES_S3_SECRET_ACCESS_KEY:?Set the secret key}
services:
  migrate:
    environment: *files-environment
  control-plane:
    environment: *files-environment

在 .env 或部署环境中填好对应变量值后,新建站点可直接按下列命令启动;已有数据的站点请先完成下一节的文件迁移:

docker compose -f compose.yaml -f compose.files-s3.yaml up -d

后续执行 run、exec、版本升级和一次性 Home 导入命令时,也必须同时带上这两个 -f 参数,确保所有操作都写入同一个存储后端。若改用 AWS 默认凭据链,请移除覆盖文件中对两项静态凭据的必填校验,并向容器注入实际的工作负载身份。

更换后端、桶或前缀

切换存储配置本身不会自动搬运已有文件。PostgreSQL 中只记录内容引用,底层对象则以 blobs/<完整 SHA-256> 为键存放在所选根目录或 S3 前缀下,并非按 Agent 云盘里的文件夹名称组织目录。

  1. 暂停外部请求与定时任务,停用所有 Agent 并等待在途工作结束;随后停止全部 Worker 与控制面实例,防止迁移期间继续产生文件提交或触发清理任务。
  2. 将数据库、原对象存储、Agent 持久 Home 及部署密钥一并完整备份。
  3. 将原存储下的 blobs/ 目录完整复制到新后端的目标根目录或前缀下,保持对象键不变(从本地文件系统复制时排除 .tmp 目录),切勿按云盘逻辑路径重命名对象。
  4. 更新所有控制面实例的存储配置,确认均指向同一目标后启动服务,依次验证历史文件的下载与内容完整性、新文件上传、Worker 云盘读写以及对话附件收发。
  5. 验证通过后恢复业务运行,并暂留原存储用于应急回滚。若回滚时还需保留切换后新写入的数据,也必须将对应的底层对象与数据库引用一并同步回原存储。

切勿让两个独立的 Ankole 站点共用同一个对象存储前缀——任一站点的未引用对象清理任务,都可能把另一站点仍在使用的数据当作孤儿对象删除。相反,同一站点的多个控制面副本则必须共享完全一致的存储配置。

备份和存储清理

数据库备份只包含元数据引用,存储桶或目录备份只包含底层对象字节,恢复时两者必须配套还原。当某个底层 blob 对象在 Agent 云盘、Pod file 页面、Pod 文档/Base/Chat 与对话附件以及已编译 Applet 产物包中均不再被引用时,控制面的垃圾回收任务会统一将其清理;请勿在存储桶上额外设置会删除有效对象的自动过期规则。

S3 后端写入大文件时使用分段上传(Multipart Upload),进程异常中断可能留下未完成的分段。建议为存储桶配置自动中止未完成分段上传的生命周期规则,并根据实际负载设定超时天数。本地文件系统(fs)后端会在启动打开存储时清理超过一天未变动的临时文件,但这一机制不能代替数据备份。

排查存储故障时,可先在不启动任何 Worker 的情况下通过 Console 上传、下载已知文件,单独验证控制面存储后端;确认正常后,再启用一个 Worker 验证文件读写与附件发送。遇到 AccessDenied 时重点检查工作负载身份与桶权限策略;fs 写入失败时检查卷挂载、uid 10001 写权限与磁盘空间;找不到历史文件时先核对桶名、区域、前缀及 blobs/ 复制结果。还原流程见 备份与还原,1.x 旧版文件导入见 升级到 2.0。