访问控制

Sira 的访问控制由四件事组合而成——没有"5 层 RBAC + 部门级数据权限 + 字段级控制"，旧文档描述的多数特性是 marketing 图景，不是代码实现。本页讲实际能做什么。

1. 身份认证（谁登录）

通过环境变量 NEXT_PUBLIC_ENABLE_KEYCLOAK 切换：

模式	适用	凭证来源
默认（统一 JWT）	单系统部署、企微 / 飞书自带身份	用户名密码 / WeWork code 换 token
Keycloak SSO	接入企业现有 IdP（OIDC）	Keycloak 颁发的 JWT

支持的 Auth Provider 类型（AuthProviderType 枚举）：

• local —— 本地账户密码
• keycloak —— Keycloak SSO
• wework —— 企业微信传统应用 OAuth
• wework_saas —— SaaS 多租户企业微信
• oauth —— 通用 OAuth2

后端会按 "统一 JWT 优先 → Keycloak 兜底" 的顺序自动尝试。前端可同时挂多种登录入口。

2. 用户 / 组织 / 角色 模型

User ──┐
       │     UserRole (user_id, role_id, organization_id) ─→ Role（命名字符串）
       └──→  ↑ 同一用户可在不同组织有不同角色

• 多组织：同一个 User 可以同时是组织 A 的 admin、组织 B 的 member
• 三类角色：system（系统内置）/ organization（组织内自建）/ custom（自定义模板）
• 角色 = 命名字符串：运行时按角色名匹配（admin / owner / super_admin / member + 自定义角色名），无独立 Permission 对象

Permission（权限点）系统已下线（2026-05-22）

旧版的 Permission(resource, action, scope) 三元组模型已整体移除，连同角色继承（parent_roles）和 has_permission() 递归判定。访问控制现在纯粹按角色名匹配。

3. 内置角色名

代码里硬编码识别的字符串（中英文都接受）：

角色	等价英文
超级管理员	super_admin
管理员	admin
组织拥有者	owner

服务端的便捷依赖：require_admin() / require_super_admin()，前端的便捷组件：<PermissionGuard requiredRoles={['super_admin']}>。

自定义角色

组织管理员可以在 /admin/permissions 页仅做 Role CRUD（如"工单分析师"），并通过 UserRole 表分配给员工。新创建的角色不带任何特殊代码识别——靠角色名由业务页面自行判定。

4. License v2 = 真正的功能开关

代码里最具威慑力的访问控制其实是 License——大多数高价值能力（专用沙箱、决策审计、DMZ 中转、各种编排器、各类渠道）都用 @require_feature("xxx") 装饰器把守，缺失时直接 HTTP 402 拒绝，无论用户角色多高。

@router.post("/sandboxes/dedicated")
@require_feature("sandbox.dedicated")  # → ENTERPRISE only
async def create_dedicated_sandbox(...):
    ...

详细的 22 项功能键和等级映射见 License 管理。

5. API Key（程序化访问）

每个 Application 可以签发任意多个 API Key（api_sk_{32 chars}）用于程序化访问：

字段	用途
application_id	绑定到一个 Application，不是用户
rate_limit	速率限制（次/分钟）
quota_limit / quota_used	总量配额
allowed_ips	IP 白名单（JSON 数组）
allowed_origins	CORS 允许来源
expires_at	过期时间
is_active	软停用

Application 级、不是 User 级

API Key 不能跨 Application 使用——一把 key 只能调它绑定的那个 Application 的编排器。如果一个团队需要调多个 Application，得为每个 Application 分别申请 key。

API Key 管理：/agent-system/api-services 页。

当前可以做什么

✅ 切换 JWT / Keycloak SSO
✅ 创建组织自定义角色（命名字符串）
✅ 给用户在不同组织赋予不同角色（多组织）
✅ 通过 License 在功能维度统一开关
✅ 为每个 Application 发 API Key，按 IP / Origin / 速率 / 配额限制
✅ 用 <PermissionGuard> 组件保护前端页面

当前不支持

❌ "部门"层级（用户表 / 角色表里都没这个概念）
❌ 字段级权限（访问控制只到角色名匹配，再细就要应用代码自己判定）
❌ 工作时间限制 / 设备指纹 / 设备认证
❌ 用户级 IP 白名单（API Key 有，用户没有）
❌ "数据分级"（公开 / 内部 / 机密 / 绝密）
❌ 操作前邮件 / 短信验证码
❌ 水印 / 端到端加密导出
❌ 权限变更邮件 / 短信通知

旧文档幻觉清理

旧版描述的 5 层（系统 / 租户 / 部门 / 功能 / 数据级）权限层级、预设的 5 种角色（超级管理员 / 企业管理员 / 部门经理 / 普通员工 / 访客用户）、敏感操作短信验证、设备指纹绑定、字段脱敏配置等——代码均未实现。本页只描述实际可用功能，旧文档若与本页冲突以本页为准。

推荐配置

小型团队（< 50 人）

• 用统一 JWT
• 仅区分 super_admin / admin / 普通用户三种
• License 选 STANDARD 或 PROFESSIONAL

大型企业 / 多租户

• 接 Keycloak
• 多组织：每个事业部一个 Organization
• 每个组织自建几个 Custom Role（如"客服管理员"、"知识库编辑"）
• License 选 ENTERPRISE，开启 deploy.multi_tenant + deploy.dmz_bridge
• API Key 配置 IP 白名单 + 配额，对外开放给业务系统

集成场景（内部系统调 AI）

• 不需要真实用户登录
• 在目标 Application 下签发多把 API Key
• 每把 key 配置 rate_limit + quota_limit + allowed_ips
• 集成方用 Authorization: Bearer api_sk_xxx 调用 OpenAI / LangGraph 兼容接口

相关文档

• License 管理 —— 功能级开关（22 项）
• API Service —— API Key 用法
• 日志查看 —— 操作审计
• 沙箱权限网关 —— 员工 PC 上的访问控制