> 摘要: SaaS 产品做多租户存储时，"单 Bucket + 前缀隔离"是教科书答案，但隔离粒度、配额管控、故障爆炸半径三件事迟早会逼你重构。本文以一次租户越权访问工单为切入点，拆解 Agent Bucket「智能体桶 + 空间」的架构思路，给出 5 个维度的量化对比、3 个真实踩坑，以及一套迁移成本核算，帮你在动手前算清这笔账。

这次实践全部基于 COS 控制台的智能体桶完成，控制台操作从存储桶列表页开始：
![04-multi-tenant-storage-architecture-agent-bucket-screen-01.png](https://developer.qcloudimg.com/http-save/yehe-2059497/fff47d86425c84d3fdca0cbc7538dc1c.png)

*图 1：COS 控制台存储桶列表——智能体桶入口*

## 一、背景：一次"租户 A 能看到租户 B 文件"的工单

事情发生在今年 3 月的一个周五下午。监控里跑出来一条异常访问日志：

```text
2026-03-06 15:42:17  GET  /bucket-saas/tenant_B/uploads/invoice-0312.pdf
                      STS=tenant_A-sess-7f3a  403  denied=iam-policy
```

租户 A 的一次预签名 URL 请求，目标却是租户 B 的发票文件。

好在这次被 IAM Policy 拦住了，没有实际读到内容。但复盘时我们把整个访问链路拆开看，发现拦截依赖的是**我们自己在策略里写死的那串前缀字符串**——

```json
{
  "Effect": "Allow",
  "Action": "cos:GetObject",
  "Resource": "qcs::cos:ap-chengdu:uid/1253467900:bucket-saas/tenant_A/*"
}
```

`tenant_A` 这四个字符，就是我们全部的安全边界。它挡得住误操作，挡不住策略配错、挡不住 STS 复用、也挡不住未来某天某个新服务"顺手"把前缀写宽。

更麻烦的是三个连带问题：

1. **配额算不清**。租户 B 的存储增长把整个桶的流量带宽打满，租户 A 的下载延迟跟着涨了 30%。我们想按租户限速，只能给每个租户单独建桶——可当时已经有 47 个租户了。
2. **删除成本高**。一个租户退网，要把 `tenant_X/` 前缀下所有对象批量删除。第一次做的时候写脚本跑了 6 小时，还漏了 200 多个带日期子目录的对象，靠人工兜底清掉的。
3. **审计链路长**。一个租户的安全审计要拉出它的所有访问记录，按前缀过滤日志，平均 40 分钟一份。

这次工单没有酿成事故，但它把一个判断摆到了台面上：**前缀隔离是应用层自律，不是平台层约束**。47 个租户、每天 200 万次对象请求，继续在前缀上打补丁，下一个工单只会更贵。

## 二、为什么是 Agent Bucket：五个维度的量化对比

候选方案其实只有三个：继续单桶前缀、每租户一桶、换带原生隔离粒度的存储。我把三者在 5 个维度上拉了表：
![04-multi-tenant-storage-architecture-agent-bucket_compare.png](https://developer.qcloudimg.com/http-save/yehe-2059497/ae6ff13a50cccde2cc516d0ced5f9b6d.png)

*图 2：三种多租户存储方案架构对比*

| 维度 | 单 Bucket + 前缀 | 每租户一桶 | Agent Bucket + 空间 |
|------|-----------------|-----------|---------------------|
| 隔离粒度 | 字符串约定（应用层自律） | 物理隔离 | 空间级（平台层约束） |
| 租户数量上限 | 无限制但运维线性劣化 | 桶数上限 + 管理成本爆炸 | 单桶内按空间划分 |
| 配额/限速 | 只能整桶配置 | 天然支持 | 空间级配额与限速 |
| 单租户故障爆炸半径 | 全桶 | 单桶 | 单空间 |
| 迁移成本 | 零 | 高（重建 + 回灌） | 中（Key 改写 + 双写灰度） |

几个值得展开讲的点：

**每租户一桶为什么被否掉。** 47 个租户意味着 47 个桶的 IAM、47 套生命周期规则、47 个监控告警模板。我们试过给 3 个大客户单独开桶，光监控配置就写了 3 遍。而且桶的创建有配额限制，租户数上去之后这条路走不通。

**空间隔离的本质是什么。** 空间（Space）ID 就是 ObjectKey 的一级目录，但平台把它当成一个**独立的管理对象**：配额、限速、用量统计、访问策略都挂在空间上，而不是挂在字符串上。前缀是"我们说好按这个目录放"，空间是"平台保证这个目录只能按这个规则用"。这个区别决定了越权问题的责任边界从应用层挪回了平台层。
![04-multi-tenant-storage-architecture-agent-bucket_decision.png](https://developer.qcloudimg.com/http-save/yehe-2059497/fca07863dbb72172f1916b1a46088049.png)

*图 3：选型决策树——租户规模决定隔离方案*

判断标准可以浓缩成两条线：

- **租户 < 10、数据敏感度低**：前缀隔离够用，别过度设计。
- **租户 > 10 或有合规要求**：上原生隔离粒度。当时我们 47 个租户 + 3 个金融客户，没有第二个选项。

## 三、接入实战：从创建空间到租户上传

接入分三步：控制台建桶建空间、SDK 侧创建空间目录、业务侧按空间上传。

### 3.1 控制台：建智能体桶 + 配空间配额

在 COS 控制台进入「存储桶列表」，切到「智能体桶」页签创建。智能体桶名称是系统生成的（形如 `smh3vu03m7shyzz8-1253467900`），创建后进入桶详情的「空间管理」页签，给每个空间配 ID、配额和备注：
![04-multi-tenant-storage-architecture-agent-bucket-screen-02.png](https://developer.qcloudimg.com/http-save/yehe-2059497/c9ae152d77260b4f6154b9c0bbcafa77.png)

*图 4：桶详情页——空间管理页签，创建空间并配置配额*

空间 ID 的约束是英文字母和数字、1~32 个字符。我们把租户 ID 映射成空间 ID 做了一层转换，方便和内部账号体系对齐。

### 3.2 桶级访问权限：先把隔离底线锁死

空间隔离解决的是租户之间的隔离，但前提是桶本身没有公共入口。在桶详情的「权限管理」页，我们把公共访问权限锁死：
![04-multi-tenant-storage-architecture-agent-bucket-screen-03.png](https://developer.qcloudimg.com/http-save/yehe-2059497/0089b488f08eca8fd222396224d72626.png)

*图 5：桶权限管理——公共访问权限设置页（附数据泄露风险警示）*

页面上的官方警示说得很直白：开启公有读或公有读写存在数据泄露和被盗刷风险，建议仅在必要时开启并优先选择私有读写。多租户场景下这是第一道红线——桶级底线私有读写，所有租户访问必须走鉴权：
![04-multi-tenant-storage-architecture-agent-bucket-screen-04.png](https://developer.qcloudimg.com/http-save/yehe-2059497/de506d4beeda49cff730b437b2edc51f.png)

*图 6：公共权限设为「私有读写」——多租户的默认安全基线*

### 3.3 SDK 侧：上传空一级目录对象创建空间

文档里有一句关键的话：**"需要预先通过 PUT Object 接口上传大小为空的一级目录对象来创建对应的 SpaceId"**。也就是说 SDK 没有单独的"创建空间"接口，空间目录的存在由对象 Key 体现，这一步是幂等的——重复执行不会覆盖空间内已有文件。

### 3.4 上传代码：Key 格式 `<SpaceID>/<ObjectKey>`

下面是我们迁移后实际在跑的最小接入代码（Python 3，依赖官方 SDK）：

```python
# agent_bucket_upload.py —— 租户空间文件上传（已验证可运行）
# 依赖：pip install cos-python-sdk-v5   # 官方 Python 3 SDK，导入名是 qcloud_cos

from qcloud_cos import CosConfig, CosS3Client

CONFIG = {
    "region": "ap-chengdu",
    "secret_id": "your_secret_id",      # 建议改从环境变量读取
    "secret_key": "your_secret_key",
    "bucket": "smh3vu03m7shyzz8-1253467900",  # 智能体桶名称
    "space_id": "tenant00123",          # 空间 ID = ObjectKey 一级目录
}

client = CosS3Client(CosConfig(
    Region=CONFIG["region"],
    SecretId=CONFIG["secret_id"],
    SecretKey=CONFIG["secret_key"],
    Scheme="https",
))

# 步骤 1：创建空间 = 上传大小为 0 的一级目录对象（幂等）
client.put_object(
    Bucket=CONFIG["bucket"],
    Key=f"{CONFIG['space_id']}/",
    Body=b"",
)

# 步骤 2：上传文件，完整 Key = <SpaceID>/<ObjectKey>
with open("report.docx", "rb") as f:
    resp = client.put_object(
        Bucket=CONFIG["bucket"],
        Key=f"{CONFIG['space_id']}/docs/2026-08/report.docx",
        Body=f,
    )
print(resp["ETag"])
```

实测运行结果（小文件验证）：

```text
空间目录已创建: tenant00123/
文件上传成功: tenant00123/docs/2026-08/report.docx（25 字节，ETag: "92b8008d1cf8fd47504938f7eff1b972"）
```

这段代码的完整版（带 `--demo` 离线模式、配置校验、命令行参数）放在系列仓库的 `scripts/agent_bucket_upload.py`：
![04-multi-tenant-storage-architecture-agent-bucket-screen-06.png](https://developer.qcloudimg.com/http-save/yehe-2059497/59d9159140d8cbb3f829e1aa55551990.png)

*图 7：完整脚本 `scripts/agent_bucket_upload.py`——配置校验、离线模式与命令行参数*

用真实业务文件（17.4MB 的产品手册 PDF）跑一遍，终端输出如下：
![04-multi-tenant-storage-architecture-agent-bucket-screen-07.png](https://developer.qcloudimg.com/http-save/yehe-2059497/cfdbd5e88b2e36a92c60f9cc6f975b94.png)

*图 8：终端实测——18,254,847 字节文件上传至租户空间，返回 ETag*

再回到控制台的「空间列表」页，文件已落在对应空间下：
![04-multi-tenant-storage-architecture-agent-bucket-screen-05.png](https://developer.qcloudimg.com/http-save/yehe-2059497/d28e6a1b22cda0b93a98f2cbe1ac2076.png)

*图 9：控制台空间文件列表（tenant00123/files）——上传结果核对*

### 3.5 业务侧改造：租户上下文注入

代码本身不难，真正的改造量在业务层。我们做了一件事：**把租户 ID 从请求头里取出来，统一注入到存储客户端的 Key 拼装逻辑里**，业务代码不再感知前缀字符串：

```python
# 改造前：业务代码自己拼前缀，47 处调用点
key = f"tenant_{tenant_id}/uploads/{filename}"

# 改造后：客户端封装空间，业务只传空间内 ObjectKey
key = storage_client.object_key(tenant_id, "uploads", filename)
# → tenant00123/uploads/filename，租户 ID 与空间 ID 的映射收敛在一处
```

这一步让"前缀写宽"这类事故在代码结构上无法发生——Key 的拼装逻辑只有一处，而不是散落在 47 个调用点。

## 四、踩坑记录：3 个真实问题

### 1：官方 SDK 包名和导入名不一致

按文档找 `qcloud_cos` 装包，结果 PyPI 上那个 3.3.6 是 Python 2 老版本，setup.py 里直接写死只支持 2.6/2.7，Python 3 上装必失败。

**解决**：官方 Python 3 的包名是 `cos-python-sdk-v5`，**导入名仍然是 `qcloud_cos`**。查版本用 `pip show cos-python-sdk-v5`，SDK 对象上没有 `__version__` 属性。

```bash
# 错误：这是 Python 2 老包
pip install qcloud_cos

# 正确：Python 3 官方 SDK
pip install cos-python-sdk-v5
```

### 2：拿旧文档的接口名去调 SDK，全部查无实据

早期体验文档里出现过 `create_agent_bucket_space` 这类"创建空间"的独立接口名，直接按名字调：

```text
AttributeError: 'CosS3Client' object has no attribute 'create_agent_bucket_space'
```

**解决**：翻遍已安装 SDK 源码，没有任何空间管理接口。真实机制就是 3.2 节说的——空一级目录对象。写接入代码前先 `grep` 一遍本地 SDK 的方法列表，比对着文档猜要快得多。

### 3：把智能体桶当普通 COS 桶访问

用普通 COS 的访问逻辑（不带空间前缀的 Key）去读智能体桶里的对象，要么 404 要么落在错误的空间视图里。

**解决**：Key 必须带 `<SpaceID>/` 一级前缀，没有例外。这条约束建议直接写进团队存储规范，而不是靠口口相传。

## 五、迁移成本与效果核算

### 5.1 迁移怎么做的

双写灰度，分三周：

1. **第一周**：新写入双写到旧桶和智能体桶，读仍走旧桶。
2. **第二周**：历史数据用批量工具回灌，按空间 ID 重写 Key（脚本跑了一夜，47 个空间共 1.2 亿对象）。
3. **第三周**：读切到智能体桶，旧桶停写保留 30 天后归档删除。

全程业务侧改动只有一处：存储客户端的 Key 拼装封装。因为 3.4 节的收敛是在迁移前做的，这一步只花了两天。

### 5.2 迁移后的变化

| 指标 | 迁移前（前缀隔离） | 迁移后（空间隔离） |
|------|------------------|------------------|
| 租户级配额/限速 | 不支持 | 空间级配置，控制台 5 分钟生效 |
| 退网租户清理耗时 | 6 小时 + 人工兜底 | 空间级批量操作，20 分钟内 |
| 单租户审计报告耗时 | 40 分钟 | 8 分钟 |
| 越权风险边界 | 应用层字符串约定 | 平台级空间约束 |

### 5.3 成本账

- **直接成本**：智能体桶存储单价与普通 COS 标准存储一致，空间隔离不额外收费；我们 1.2 亿对象的月度存储费迁移前后基本持平（±2% 在波动范围内）。
- **隐性成本**：迁移开发 3 人天（双写 + 回灌脚本 + 灰度验证），监控告警按空间维度重建 1 人天。
- **省下的钱**：退网清理和审计报告的人力，按每月 2 个退网租户 + 15 份审计估算，每月省约 1 人天。

结论很直接：**租户规模过了两位数，这笔账是划算的；没到两位数，继续前缀隔离不要动**。

## 六、写在最后

这次迁移最大的收获不是换了个存储产品，而是把"隔离"的责任边界挪回了它该在的地方：**应用层负责数据怎么放，平台层负责放错了也读不出来**。前缀隔离的 47 个租户跑了一年，问题出在"自律"两个字上——自律在 47 个调用点、十几个服务、几次团队交接之后，必然松动。

Agent Bucket 的空间机制对 SaaS 多租户和 Multi-Agent 系统都是同一套思路：**每个隔离单元是一个有配额、有统计、有策略的独立管理对象**。它的限制也要说清楚：空间是单桶内的逻辑隔离，不是物理隔离，跨地域容灾、私有协议这类需求它不解决。

对正在选型的人，建议的动手顺序是：先用 3.3 节的代码在你自己的桶上跑通一次"建空间 + 上传"（半小时的事），再按 5.2 的表对照自己的指标，最后决定要不要动存量。


摘要: SaaS 产品做多租户存储时，"单 Bucket + 前缀隔离"是教科书答案，但隔离粒度、配额管控、故障爆炸半径三件事迟早会逼你重构。本文以一次租户越权访问工单为切入点，拆解 Agent Bucket「智能体桶 + 空间」的架构思路，给出 5 个维度的量化对比、3 个真实踩坑，以及一套迁移成本核算，帮你在动手前算清这笔账。

多租户存储别再自己造轮子：从「单 Bucket + Prefix」到 Agent Bucket 空间隔离的架构实践

SaaS 产品做多租户存储时，"单 Bucket + 前缀隔离"是教科书答案，但隔离粒度、配额管控、故障爆炸半径三件事迟早会逼你重构。本文以一次租户越权访问工单为切入点，拆解 Agent Bucket「智能体桶 + 空间」的架构思路，给出 5 个维度的量化对比、3 个真实踩坑，以及一套迁移成本核算，帮你在动手前算清这笔账。

云计算

架构设计

后端

租户隔离方案重构：从"前缀自律"到"空间约束"。单桶+前缀隔离在47租户规模下暴露配额失控、删除低效、审计长等痛点。AgentBucket空间隔离实现平台级租户边界，支持独立配额与限速，迁移成本3人天，越权风险转移至平台层。租户超10个建议采用，提供完整接入代码与踩坑指南。

数据泄露

安全审计

代码解释

智能体

容灾

Agent

SaaS

2026上云采购 | AI焕新·智启新局

tclm

对象存储COS新用户低至1元！


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

多租户存储别再自己造轮子：从「单 Bucket + Prefix」到 Agent Bucket 空间隔离的架构实践-腾讯云开发者社区-腾讯云

多租户存储别再自己造轮子：从「单 Bucket + Prefix」到 Agent Bucket 空间隔离的架构实践

多租户存储别再自己造轮子：从「单 Bucket + Prefix」到 Agent Bucket 空间隔离的架构实践

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐