把权限判断交给 OpenFGA 前，我会先画清 tuple 和模型边界

在 SaaS 产品里，权限逻辑很容易散在 controller、SQL scope、前端菜单和后台脚本里。早期靠角色字段还能撑住，等到团队空间、项目、文档、仓库和外部协作者都出现后，判断语句会越来越难验证。OpenFGA 的价值在于把“用户和对象的关系”抽成模型与 tuple，应用只在关键路径发起 check，规则就能从业务分支里收拢出来。

原创示意图：应用服务发起权限检查，模型版本、关系 tuple、存储和测试共同组成可审计的授权边界。来源：Codex image generation

先画对象关系

OpenFGA 的建模指南建议从资源和对象出发，回答“用户为什么可以对某个对象执行某个动作”。我会先选一个高频场景，例如团队文档或项目仓库访问，用业务语言写清楚：团队成员能查看团队文档，仓库维护者能修改配置，文档所有者能分享给外部协作者。随后再把这些句子拆成 object type、relation 和 permission。user、team、document、repository 各自有哪些 relation，哪些 relation 能推导出 can_view、can_edit、can_share，这些问题要在模型阶段被讨论清楚。

tuple 收进业务事件

OpenFGA 的关系 tuple 可以理解成权限事实，例如 user:123 是 document:456 的 viewer，或 team:7 是某个仓库的 maintainer。应用服务负责把真实业务事件转换成 tuple 写入，比如加入团队、移出项目、转让文档所有者。官方最佳实践提醒不要在 tuple 里存个人可识别信息，所以 user id 和 object id 应使用内部标识，避免邮箱、手机号、真实姓名这类值进入授权系统。成员移除、共享撤销、项目归档这类负向事件也要纳入重试和补偿设计。

模型发布要可回滚

OpenFGA 的 authorization model 是不可变的，每次写入都会生成新版本。生产 API 调用里应尽量指定 authorization model id，避免服务无意间使用最新模型造成行为漂移。我的流程是让模型变更先进入 pull request，配套更新应用代码和 tuple 迁移脚本；灰度阶段做 shadow check，对同一批请求验证新旧模型结果；确认差异符合预期后，再把服务配置切到新 model id。这样权限模型的发布节奏能和应用发布节奏对齐。

测试先走

OpenFGA 支持用 .fga.yaml 描述模型、tuple 和测试断言，覆盖 Check、ListObjects、ListUsers 这些应用会调用的接口。我会先写几组真实样例：团队成员可以查看团队文档，普通访客不能修改仓库，文档所有者移交后旧所有者失去分享权限。模型测试通过后，再让业务服务接入 SDK 或 HTTP API。权限问题常常表现成按钮消失或接口返回 403，有模型测试时，团队能直接围绕样例校准预期。

小团队落地方式

建议先从一个边界清晰的模块开始。先建 store，写最小模型，准备一批匿名化 tuple，用 CLI 或 CI 跑模型测试，再把应用里的一个 read path 接到 OpenFGA check。确认延迟、错误处理和日志字段稳定后，再覆盖 write path、列表过滤和后台任务。同时要把不可用路径写清楚：授权服务超时、tuple 同步延迟、model id 配错时，接口应该返回可观测的错误，并在日志里带上 store、model id、relation 和 object id。日志字段最好统一接入 tracing，方便把一次 check 和业务请求串起来，后续也能定位模型与 tuple 的责任边界。OpenFGA 真正需要投入的地方在对象边界、关系来源、模型版本、tuple 审计和测试样例。只要这些先画清楚，从简单角色走向细粒度授权时，团队就不用每次都重新拆一遍权限迷宫。