网关权限控制
「网关权限」是云开发资源访问控制的第一道防线。当携带 云开发用户身份 的请求通过 HTTP API 域名、HTTP 访问服务域名 或 云托管域名 访问云开发资源（云函数、云托管、云存储、AI 能力等）时，请求首先到达网关层，由网关根据配置的策略决定：
- 放行（allow）：请求通过网关，进入资源层继续鉴权
- 拒绝（deny）：请求被网关拦截，不会到达资源层
鉴权顺序
网关鉴权 早于 资源鉴权。查看资源权限文档
以云函数为例：
| 网关策略 | 执行情况 | 结果 |
|---|---|---|
| 未放行 | 网关直接拒绝（403/无权限） | 函数不会被执行 |
| 已放行 | 请求到达云函数 | 继续资源层/业务层鉴权 |
网关权限只控制"能否访问"，不控制"能做什么"。细粒度的数据权限应在资源层（如数据库安全规则）或业务层实现。
默认策略
平台默认为每个角色关联了一定的预设策略，使不同的角色通过不同的链路访问时默认拥有不同的访问权限。具体如下：
- HTTP API
- HTTP 访问服务
| 资源类型 | 资源标识 | 管理员 | 组织成员 | 注册用户 | 匿名用户 |
|---|---|---|---|---|---|
| 云存储 API | storages | ✅ | ❌ | ❌ | ❌ |
| 云函数 API | functions | ✅ | ❌ | ❌ | ❌ |
| 云托管 API | cloudrun | ✅ | ❌ | ❌ | ❌ |
| 知识库 API | knowledge | ✅ | ❌ | ❌ | ❌ |
| 大模型接入 API | ai | ✅ | ✅ | ✅ | ✅ |
| AI 智能体 API | aibot | ✅ | ✅ | ✅ | ✅ |
| 数据模型 API | model | ✅ | ✅ | ✅ | ✅ |
| MySQL API | rdb | ✅ | ✅ | ✅ | ✅ |
- ✅ 表示该角色具备该功能的默认权限，❌ 表示该角色不具备该功能的默认权限，如需调整权限，请参考下文中的方法为对应角色关联策略。
- 数据模型 API 可参考 数据权限管理 进行权限控制，MySQL API 可参考 MySQL 权限管理 进行权限控制，
- 平台默认策略可能会根据实际情况进行调整。
配置入口
进入 云开发平台/权限控制，选择目标角色卡片的【配置权限】
进入角色详情页 → 点击「添加自定义策略」
资源类型选择「网关」
策略配置
网关权限支持两种策略配置方式：预设策略和自定义策略。预设策略为一系列策略鉴权模板，可直接关联到用户所属角色，使角色具备相应的权限。如预设策略不满足需求，可根据语法编写自定义策略实现更灵活的权限控制。
预设策略
系统提供常用的预设策略，开箱即用，适合大多数场景。
场景 1：开发测试阶段 - 管理员全权限
- 适用场景：个人开发、快速验证功能
- 推荐策略：
AdministratorAccess - 优势：无权限阻断，快速迭代
- 注意事项：⚠️ 生产环境不要将此策略绑定到面向公网的应用身份
场景 2：团队协作 - 按资源类型拆分
- 适用场景：多人协作开发，按资源域分工
- 推荐策略：
StoragesAccess：云存储访问权限FunctionsAccess：云函数访问权限CloudrunAccess：云托管访问权限
- 优势：按资源隔离权限，降低误操作风险
场景 3：对外服务 - HTTP 访问控制
- 适用场景：通过 HTTP API 对外提供服务
- 推荐策略：
FunctionsHttpApiAllow/FunctionsHttpServiceAllowCloudrunHttpApiAllowStoragesHttpServiceAllow
- 最佳实践：⚡ 先开放最小权限集合，再根据需求逐步扩展
自定义策略
当预设策略无法满足需求时，可以自定义策略实现精细化权限控制。
策略语法说明
策略 policy 由版本 version 和语句 statement 构成。每条语句 statement 包含以下字段：
| 字段 | 是否必填 | 说明 |
|---|---|---|
effect | 必填 | 策略效果：allow（允许）或 deny（拒绝） |
action | 必填 | 操作类型采用四段式格式：资源标识:域名:HTTP方法:请求路径格式说明： 1. 资源标识（必填）：参考下方资源标识，如 functions、storages、cloudrun 等2. 域名（可选）：实际访问的域名，省略时表示 *（所有域名）3. HTTP方法（可选）：大写的 HTTP 请求方法（如 GET、POST、PUT、DELETE），省略时表示 *（所有方法）4. 请求路径（必填）：HTTP 请求路径，使用 * 通配符匹配。* 表示所有路径，/path/* 表示 /path/ 下的所有路径示例： - functions:* → 允许所有云函数访问（省略域名和方法）- functions:/hello → 仅允许访问路径 /hello- functions:/api/* → 允许访问 /api/ 下的所有路径（如 /api/users、/api/orders）- cloudrun:env-xxxx.api.tcloudbasegateway.com:POST:/v1/cloudrun/* → 允许通过指定域名 POST 方法访问云托管 API 下的所有路径- storages:*.tcloudbaseapp.com:GET:* → 允许通过静态托管域名 GET 所有存储资源 |
resource | 必填 | 资源范围：固定填写 *（表示所有资源），细粒度控制通过 action 字段实现 |
资源标识
- HTTP API 资源
- HTTP 访问服务资源
策略结构示例(允许访问所有云函数)
{
"version": "1.0",
"statement": [
{
"effect": "allow",
"action": "functions:*",
"resource": "*",
}
]
}
策略优先级规则
当同一请求匹配多个策略时：
- ❌
deny优先于 ✅allow - 未匹配任何策略时，默认拒绝访问
当 allow 语句和 deny 语句同时存在时，遵循 deny 优先原则。
常见自定义策略示例
- 允许特定云函数
- 禁止危险操作
- 云存储访问
- 混合策略
允许通过 HTTP 访问路径为 /hello 的云函数：
{
"version": "1.0",
"statement": [
{
"effect": "allow",
"action": "functions:/hello",
"resource": "*"
}
]
}
禁止访问特定的敏感云函数：
{
"version": "1.0",
"statement": [
{
"effect": "deny",
"action": "functions:/dangerousFunction",
"resource": "*"
}
]
}
允许访问所有云存储资源：
{
"version": "1.0",
"statement": [
{
"effect": "allow",
"action": "storages:*",
"resource": "*"
}
]
}
允许访问所有云函数，但禁止访问特定敏感函数（deny 优先级更高）：
{
"version": "1.0",
"statement": [
{
"effect": "allow",
"action": "functions:*",
"resource": "*"
},
{
"effect": "deny",
"action": "functions:/admin",
"resource": "*"
}
]
}
最佳实践
最小权限原则
遵循「最小权限原则」（Least Privilege），按实际需要授权：
| 身份类型 | 推荐策略 | 说明 |
|---|---|---|
| 开发者/管理员 | AdministratorAccess | 开发阶段可使用高权限，提升效率 |
| 生产环境应用 | 自定义策略 | 仅授予必需的 action |
| 自动化服务 | 最小权限集合 | CI/CD、定时任务等仅开放所需接口 |
分层防护策略
安全防护应该在多个层次实施，而非依赖单一机制：
┌─────────────────────────────────────────┐
│ 网关层（网关权限） │ ← 控制"能否访问"
│ • 决定请求能否进入资源层 │
└─────────────────────────────────────────┘
↓ 放行
┌─────────────────────────────────────────┐
│ 资源层（安全规则） │ ← 控制"能做什么"
│ • 数据库安全规则 │
│ • 云存储访问控制 │
│ • 云函数认证配置 │
└─────────────────────────────────────────┘
↓ 通过
┌─────────────────────────────────────────┐
│ 业务层（应用鉴权） │ ← 控制"细粒度权限"
│ • 用户角色校验 │
│ • 数据权限过滤 │
│ • 业务规则限制（额度、风控等） │
└─────────────────────────────────────────┘
策略配置建议
1. 优先使用预设策略
- ✅ 预设策略经过充分测试，更规范、不易出错
- ⚠️ 自定义策略需充分测试后再投入生产使用
2. 使用 deny 做全局兜底
当需要"全局禁止某类危险操作"时，使用 deny 策略（因为 deny 优先级高于 allow）：
{
"effect": "deny",
"action": "functions:*",
"resource": "*"
}
3. 定期审查权限配置
- 定期检查各角色的权限配置是否合理
- 及时回收不再需要的权限
- 关注异常访问日志，调整策略
故障排查路径
遇到权限问题时，按以下顺序排查：
| 现象 | 排查重点 | 处理方向 |
|---|---|---|
| 请求返回 403，请求体内错误码为 ACTION_FORBIDDEN | 网关策略 | 检查网关权限配置，确认策略是否放行 |
| 请求进入资源，但执行失败 | 资源层安全规则 | 检查数据库安全规则、云存储权限等 |
| 资源层通过，业务逻辑报错 | 业务层鉴权 | 检查应用代码中的权限校验逻辑 |
可以临时将角色策略改为 AdministratorAccess，如果问题消失，说明是网关权限配置问题；如果问题依然存在，则需要检查资源层或业务层。