企业官网建设流程全解析

Octop COS/S3 远程存储后端完整指南：3 步把 Agent 工作区送上云

【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop

Octop是一个更聪明、可自托管（self-hosted）的多用户、多智能体 AI 助手。除了开箱即用的本地存储，Octop 内置了COS/S3 远程存储后端能力：在管理后台填入对象存储的密钥与桶信息，就能把每个 Agent 的工作区文件（SOUL.md、技能、工作文档等）直接落到腾讯云 COS、AWS S3、MinIO 等云端对象存储上，实现工作区上云、数据安全可备份、多机共享同一份 Agent 记忆。本文面向新手，用通俗的方式讲清楚 Octop 远程存储后端支持哪些类型、如何一键配置 COS/S3、以及如何把它绑定给 Agent。

为什么要把 Agent 工作区上云？

Agent 的"人格"和"知识"都以文件形式存放在工作区目录里，默认落在服务器本地的~/.octop/agents/<agent_id>/。这带来三个常见痛点：

• 怕丢：磁盘故障、误删、重装系统，Agent 人设与积累的技能文件可能全部消失；
• 难迁移：换服务器后，Agent 的"记忆"需要手动搬运；
• 不好共享：多台机器无法直接共享同一个 Agent 工作区。

Octop 的远程存储后端把内容文件的读写通道从"本地磁盘"切换成"云对象存储"，而Agent 看到的路径完全不变——这正是它设计上最聪明的地方：只换 I/O 通道，不换路径（详见 docs/agent-backend-file-io.md）。对 Agent 来说，读写的依然是/SOUL.md、/skills/xxx/SKILL.md这样的路径，背后却已经写到了云端。

Octop 支持哪些远程存储类型？

Octop 在 dashboard/src/pages/Admin/Storage/useStorageBackends.tsx 中预置了 10 种存储类型，对象存储相关的有 5 种：

此外还支持filesystem（本地目录）、shell、docker、opensandbox（远程沙箱）和postgres（数据库）等类型，全部走同一套管理界面。类型到实际后端参数的映射逻辑见 src/octop/infra/backend/adapter.py。

如何一键配置 COS 远程存储后端

整个配置流程在 Web 管理后台完成，无需碰代码：

1. 进入存储管理页：以管理员身份登录 Octop，在左侧「管理」分组中找到存储菜单（即 dashboard/src/pages/Admin/Storage/index.tsx 对应的页面）；
2. 选择预设类型：页面分「我的存储」和「支持的类型」两个标签页，在类型卡片上点击COS，系统会自动锁定类型并带出该类型专属的字段表单；
3. 填写 4 个必填项 + 1 个可选项：
   • Access Key（SecretId，形如AKIDxxx）
   • Secret Key（SecretKey，形如SKEYxxx）
   • Bucket（桶名，如my-bucket-1250000000）
   • Region（地域，如ap-guangzhou）
   • Endpoint（选填，如cos.ap-guangzhou.myqcloud.com；COS 类型下可留空由 SDK 推导）；
4. 保存并探测：Octop 会对配置执行一次真实的「写入→读取」回环探测，连通性由 src/octop/infra/backend/probe.py 保证，返回ok: true即代表密钥、桶名、权限全部正确。

💡 小提示：探测接口同时支持"未保存的表单值"直接试连（/probe端点），意味着你可以先探测、满意了再保存，避免把坏配置写进数据库。所有 API 定义见 src/octop/api/routers/storage_backends.py。

S3 / MinIO 兼容后端怎么配？

如果你的对象存储是AWS S3、MinIO或其他 S3 兼容服务，选S3或Custom类型即可，字段与 COS 类似，但有一个关键差异：Endpoint 建议显式填写。

• 填写时如果不带协议前缀（如minio.example.com:9000），Octop 会自动补上https://前缀（见 adapter.py 中endpoint_url的构造逻辑）；
• Region对 AWS S3 是必填的（如us-east-1）；对 MinIO 可填任意占位值；
• Custom 类型额外允许在config_json中透传其他 S3 客户端参数，覆盖默认行为。

一次探测通过 = 上传下载链路打通，后续 Agent 的所有文件读写都会走这条云端通道。

如何把存储后端绑定给 Agent？

配置好存储后端只是"装好了硬盘"，还需要让 Agent 用上它。Octop 提供了两种优雅的方式（见 src/octop/infra/backend/resolver.py）：

① 命名引用（named ref）在 Agent 的config.backend中引用存储后端的名称，例如把后端命名为my-cos，Agent 配置一个指向my-cos的引用即可。名称变更或后端调整时，所有引用它的 Agent 自动跟随，无需逐个修改。

② 组合路由（composite）更高级的玩法：一个 Agent 可以同时挂多个后端，按路径前缀路由——比如把/docs/目录映射到 S3，其余文件留在本地filesystem。这让你可以"热数据上云、冷数据留本地"，自由组合。

在「专家」页面从模板新建 Agent 时，就可以在配置里指定上述远程后端。整体架构上，远程后端（S3、COS 等）在 Agent 启动时即完成挂载，详见 docs/architecture.md。

远程工作区如何查看与管理？

配置完成后，管理后台对每个远程后端都提供了几样"安心"能力：

• 目录浏览：/tree接口可以逐级浏览桶内目录树（实现见 src/octop/infra/backend/browse.py），随时确认 Agent 写进去的文件；
• 密钥脱敏：列表和详情接口中，secret_key永远不会返回，access_key也只显示前 4 位加星号，密钥安全有保障；
• 引用保护：如果某个存储后端正被 Agent 引用，删除操作会被直接拒绝并列出引用它的 Agent 名单，防止"删了存储、Agent 集体失联"的意外；
• 一键测试：对已保存的后端可再次发起/test探测，密钥轮换后随手验证连通性。

新手常见问题

Q1：配置远程后端后，本地还会残留文件吗？内容文件（模板、SOUL、技能等）会统一改走后端通道读写；而 checkpoint、会话 JSONL、记忆数据库等"本地产物"仍保留在本地workspace_dir，这是有意为之的设计（见 docs/agent-backend-file-io.md 的范围说明）。

Q2：COS 和 S3 类型怎么选？用腾讯云 COS 就选COS（原生协议，字段最少）；其他对象存储（AWS、MinIO、R2……）一律选S3或Custom，填对 Endpoint 即可。

Q3：密钥泄露怎么办？直接在编辑表单中留空 Secret Key 表示"不修改"，填入新值则覆盖；建议为 Octop 单独创建最小权限的密钥，只授予目标桶的读写权限。

总结

Octop 把"Agent 工作区上云"这件事做到了极简：选类型 → 填四个字段 → 点一次探测，COS/S3/OSS/OBS/MinIO 全部通吃。再配合命名引用和组合路由，多用户团队可以轻松实现工作区集中备份、跨机迁移与多 Agent 共享。如果你的自托管 AI 助手还在担心磁盘故障或迁移成本，这套远程存储后端值得第一个配置。

【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop