网关权限控制

「网关权限」是云开发资源访问控制的第一道防线。当携带 云开发用户身份 的请求通过 HTTP API 域名、HTTP 访问服务域名 或 云托管域名 访问云开发资源（云函数、云托管、云存储、AI 能力等）时，请求首先到达网关层，由网关根据配置的策略决定：

• 放行（allow）：请求通过网关，进入资源层继续鉴权
• 拒绝（deny）：请求被网关拦截，不会到达资源层

鉴权顺序

网关鉴权 早于 资源鉴权。查看资源权限文档

以云函数为例：

网关策略	执行情况	结果
未放行	网关直接拒绝（403/无权限）	函数不会被执行
已放行	请求到达云函数	继续资源层/业务层鉴权

提示

网关权限只控制"能否访问"，不控制"能做什么"。细粒度的数据权限应在资源层（如数据库安全规则）或业务层实现。

默认策略

平台默认为每个角色关联了一定的预设策略，使不同的角色通过不同的链路访问时默认拥有不同的访问权限。具体如下：

HTTP API

资源类型	资源标识	管理员	组织成员	注册用户	匿名用户
云存储 API	storages	✅	❌	❌	❌
云函数 API	functions	✅	❌	❌	❌
云托管 API	cloudrun	✅	❌	❌	❌
知识库 API	knowledge	✅	❌	❌	❌
大模型接入 API	ai	✅	✅	✅	❌
AI 智能体 API	aibot	✅	✅	✅	✅
数据模型 API	model	✅	✅	✅	✅
MySQL API	rdb	✅	✅	✅	✅

提示

• ✅ 表示该角色具备该功能的默认权限，❌ 表示该角色不具备该功能的默认权限，如需调整权限，请参考下文中的方法为对应角色关联策略。
• 数据模型 API 可参考 数据权限管理 进行权限控制，MySQL API 可参考 MySQL 权限管理 进行权限控制，
• 平台默认策略可能会根据实际情况进行调整。

匿名用户权限生效前提

匿名用户的网关权限要实际生效，请先确认环境已开启「匿名登录」方式，否则客户端无法获取匿名身份，相应权限也不会触发。开启方式参见 匿名登录。

HTTP 访问服务

通过 HTTP 访问服务 为云资源配置访问路径后，如路径启用了身份认证，携带云开发用户身份访问资源时会受到网关权限控制。

启用身份认证后的默认权限：

资源类型	资源标识	管理员	组织成员	注册用户	匿名用户
云函数	functions	✅	✅	✅	❌
静态托管存储	storages	✅	✅	✅	❌
云托管	cloudrun	✅	✅	✅	❌

提示

• ✅ 表示该角色具备该功能的默认权限，❌ 表示该角色不具备该功能的默认权限，如需调整权限，请参考下文中的方法为对应角色关联策略。
• 平台默认策略可能会根据实际情况进行调整。

匿名用户权限生效前提

匿名用户的网关权限要实际生效，请先确认环境已开启「匿名登录」方式，否则客户端无法获取匿名身份，相应权限也不会触发。开启方式参见 匿名登录。

配置入口

进入 云开发平台/权限控制，选择目标角色卡片的【配置权限】

进入角色详情页 → 点击「添加自定义策略」

资源类型选择「网关」

策略配置

网关权限支持两种策略配置方式：预设策略和自定义策略。预设策略为一系列策略鉴权模板，可直接关联到用户所属角色，使角色具备相应的权限。如预设策略不满足需求，可根据语法编写自定义策略实现更灵活的权限控制。

预设策略

系统提供常用的预设策略，开箱即用，适合大多数场景。

场景 1：开发测试阶段 - 管理员全权限

• 适用场景：个人开发、快速验证功能
• 推荐策略：AdministratorAccess
• 优势：无权限阻断，快速迭代
• 注意事项：⚠️ 生产环境不要将此策略绑定到面向公网的应用身份

场景 2：团队协作 - 按资源类型拆分

• 适用场景：多人协作开发，按资源域分工
• 推荐策略：
  • StoragesAccess：云存储访问权限
  • FunctionsAccess：云函数访问权限
  • CloudrunAccess：云托管访问权限
• 优势：按资源隔离权限，降低误操作风险

场景 3：对外服务 - HTTP 访问控制

• 适用场景：通过 HTTP API 对外提供服务
• 推荐策略：
  • FunctionsHttpApiAllow / FunctionsHttpServiceAllow
  • CloudrunHttpApiAllow
  • StoragesHttpServiceAllow
• 最佳实践：⚡ 先开放最小权限集合，再根据需求逐步扩展

自定义策略

当预设策略无法满足需求时，可以自定义策略实现精细化权限控制。

策略语法说明

策略 policy 由版本 version 和语句 statement 构成。每条语句 statement 包含以下字段：

字段	是否必填	说明
effect	必填	策略效果：allow（允许）或 deny（拒绝）
action	必填	操作类型采用四段式格式：资源标识:域名:HTTP方法:请求路径 格式说明： 1. 资源标识（必填）：参考下方资源标识，如 functions、storages、cloudrun 等 2. 域名（可选）：实际访问的自定义域名，通过HTTP API 访问时域名统一为 tcloudbasegateway，省略时表示 *（所有域名） 3. HTTP方法（可选）：大写的 HTTP 请求方法（如 GET、POST、PUT、DELETE），省略时表示 *（所有方法） 4. 请求路径（必填）：HTTP 请求路径，使用 * 通配符匹配。* 表示所有路径，/path/* 表示 /path/ 下的所有路径 示例： - functions:* → 允许所有云函数访问（省略域名和方法） - functions:/hello → 仅允许访问路径 /hello - functions:/api/* → 允许访问 /api/ 下的所有路径（如 /api/users、/api/orders） - cloudrun:tcloudbasegateway:POST:/v1/cloudrun/* → 允许通过指定域名 POST 方法访问云托管 API 下的所有路径 - storages:*.tcloudbaseapp.com:GET:* → 允许通过静态托管域名 GET 所有存储资源
resource	必填	资源范围：固定填写 *（表示所有资源），细粒度控制通过 action 字段实现

资源标识

HTTP API 资源

通过开放 API 访问的资源类型及其标识：

资源标识	标识	说明
云存储	storages	对象存储操作
云函数	functions	云函数调用
云托管	cloudrun	云托管服务访问
大模型	ai	AI 大模型接入
AI 智能体	aibot	AI 智能体服务
数据模型	model	数据模型管理
知识库	knowledge	知识库管理
MySQL 访问	rdb	MySQL 数据库访问

HTTP 访问服务资源

通过 HTTP 访问服务访问的资源类型及其标识：

资源标识	标识	说明
云函数	functions	通过 HTTP 路径访问云函数
静态托管存储	storages	静态网站托管、文件访问
云托管	cloudrun	容器服务访问

策略结构示例(允许访问所有云函数)

{
  "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": "*"
    }
  ]
}

AI 大模型访问

允许访问所有 AI 大模型资源：

{
  "version": "1.0",
  "statement": [
    {
      "effect": "allow",
      "action": "ai:*",
      "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，如果问题消失，说明是网关权限配置问题；如果问题依然存在，则需要检查资源层或业务层。