Storage 存储与隔离

为什么要双层存储

Agent 工作流对存储有两个冲突的需求：

需求	矛盾点
快 — 当前会话读写要即时	对象存储有 RTT，不够快
持久 — 会话结束文件不能丢	本地磁盘容器回收就没了

所以 combo agent 采用本地 + MinIO 双层存储：本地管"活跃 Session"，MinIO 管"跨节点 / 跨时间的持久化与隔离"。

Rendering diagram…

存储分层原则

层	用途	特性
本地文件系统	当前活跃 Session 的临时读写	快、单节点、容器回收会丢
MinIO 对象存储	持久化、跨节点共享、多租户隔离	慢、集群、高可靠

关键规则（源自 agent-behavior 守则）：

✅ 本地路径是首发写入目标（快），MinIO 为异步备份
✅ 容器内不做持久化 — 文件写到宿主机映射目录或 MinIO
✅ MinIO 管隔离、本地管活跃 — 不反过来用

多租户严格隔离

Storage 按 tenant → user → session 三级隔离：

minio/
├── tenant-A/
│   ├── user-1/
│   │   ├── session-abc/
│   │   │   ├── inputs/        # 上传的原始文件
│   │   │   ├── artifacts/     # Agent 生成的工件
│   │   │   └── cache/         # 中间缓存
│   │   └── session-def/
│   └── user-2/
└── tenant-B/
    └── ...

租户之间：物理隔离（不同 bucket 或强制 prefix）
用户之间：逻辑隔离（路径前缀 + 权限校验）
Session 之间：按需共享（同一用户默认隔离，可显式通过 Graft 或 Memory 打通）
所有访问经过 Credential 层校验，不能绕过权限直接访问 bucket

支持的存储后端

后端	特性
本地文件系统	默认，开发 / 小规模 / 单机私有化部署
MinIO（推荐）	自部署对象存储，兼容 S3 API
AWS S3 / 阿里云 OSS / 腾讯云 COS	云原生部署
NFS / Ceph	传统企业存储（按 S3 Gateway 接入）

知识库数据的三层存储

除了 Session 本地文件，知识库（KB）还有结构化数据：

数据类型	存储位置
原始文件（PDF / DOCX / MP4）	对象存储（MinIO / S3）
解析产物（分块 / 向量 / 元数据）	搜索引擎（ES）
实体 / 关系 / 图谱	搜索引擎 + 关系数据库（用于 GraphRAG）
会话记忆（KB / LTM fact）	搜索引擎（按 `sources=kb / fact` 标签）

详见 Memory 记忆系统。

异步同步机制

Session 文件的生命周期：

1. Agent 写入 → 本地优先
2. 本地写完立即返回（Agent 继续往下跑）
3. 后台 Worker 异步上传 MinIO
4. 上传成功 → 元数据标记 synced
5. 跨节点 Session 迁移时，从 MinIO 拉取 → 新节点本地

一致性保证：

同一 Session 的操作通过 Session ID 路由到同一节点，避免并发写冲突
节点故障下 Failover：新节点从 MinIO 拉取最新 synced 状态继续
未同步的本地改动会在下次有机会时继续同步（幂等）

文件生命周期

阶段	行为
活跃	本地 + MinIO 双副本
Session 归档	本地清理，MinIO 保留
长期归档（按策略）	MinIO 热层 → 冷层（降低成本）
删除	按数据保留策略（默认不删，可配合规周期）

加密与合规

传输加密 — 组件间强制 TLS
静态加密 — MinIO Server-Side Encryption（SSE-S3 / SSE-KMS）
审计 — 所有读写操作落地审计日志，支持事后核对
合规 — 支持私有化部署满足数据主权要求；SaaS 部署按合同约定数据边界