Permify 是一个用 Go 编写的授权服务。其文档称它为 “an open-source authorization service for creating fine-grained and scalable authorization systems”(一个用于创建细粒度、可扩展授权系统的开源授权服务),“inspired by Google’s consistent, global authorization system, Google Zanzibar”(受 Google 的一致性全球授权系统 Google Zanzibar 启发)(Permify 文档)。你在 Permify Schema 中描述实体类型及其关系,把关系写成元组,然后通过 gRPC 或 HTTP 询问服务器某个主体是否拥有某项权限。
FusionAuth 收购 Permify 一事于 2025-11-20 宣布(Permify 公告,FusionAuth 公告)。FusionAuth 现在把该产品命名为 “FusionAuth FGA by Permify”(FusionAuth 支持文章),文档位于 fusionauth.io/permify-docs。Permify 的文章说 “The core Permify project remains open source and will continue to live on GitHub.”(Permify 的核心项目仍然开源,并将继续托管在 GitHub 上。)
论文与 Permify 对照
每一行列出论文中的一个概念以及 Permify 文档中最接近的东西。Permify 没有可比之物的地方,单元格中会注明。
| 论文中 | Permify 中 |
|---|---|
| 命名空间配置(§2.3) | Permify Schema 中的一个 entity 块,包含 relation、permission(或其同义词 action)、attribute 和 rule(建模) |
关系元组 object#relation@user(§2.1) |
关系型元组(relational tuple)entity#relation@subject,例如 doc:readme#owner@user:anne(存储数据) |
_this |
某个 relation 的已存储元组;权限通过写出该关系的名称来包含它们 |
computed_userset |
写出同一实体的另一个关系或权限的名称,例如 view = viewer or edit 中的 edit |
tuple_to_userset |
通过关系的点号遍历,例如 parent.view |
| 并集、交集、排除 | or、and、not |
| zookie(§2.2、§2.4) | Snap token,即 snap_token 字段(snap tokens) |
| Check(§2.4.4) | Permission.Check,以及 BulkCheck(service.proto) |
| Read(§2.4.1) | Data.ReadRelationships,以及 ReadAttributes |
| Write(§2.4.2) | Data.Write、WriteRelationships、Delete、DeleteRelationships |
| Watch(§2.4.3) | Watch.Watch,一个服务器流(Watch 操作) |
| Expand(§2.4.5) | Permission.Expand |
| Leopard(§3.2.4) | 文档中没有对应物 |
| Spanner(§3.1) | PostgreSQL,或内存引擎(配置默认值)(配置) |
Permify 还有论文没有描述的查找调用:LookupEntity、LookupSubject 和 SubjectPermission。
用 Permify Schema 表示贯穿示例
论文的图 1 为文档设定了三个同心关系:所有者是编辑者,编辑者是查看者,父文件夹的查看者是文档的查看者(§2.3.1)。下面用 Permify Schema、按贯穿示例的类型写出这个模型。
entity user {}
entity group {
relation member @user
}
entity folder {
relation viewer @user @group#member
permission view = viewer
}
entity doc {
relation parent @folder
relation owner @user
relation editor @user @group#member
relation viewer @user @group#member
permission edit = owner or editor
permission view = viewer or edit or parent.view
}
@group#member 让关系可以存放一个用户集:“该组的所有成员”。parent.view 沿着 parent 关系到达文件夹,并在那里评估文件夹的 view 权限;文档说 “The same traversal rule applies to both relation.userset and relation.permission”(同样的遍历规则既适用于 relation.userset,也适用于 relation.permission)(建模)。
贯穿示例是五个元组:
doc:readme#owner@user:anne
group:eng#member@user:beto
doc:readme#viewer@group:eng#member
doc:readme#parent@folder:A
folder:A#viewer@user:chen
哪些已存储的元组和哪些规则让三个人分别获得 readme 的访问权?
注意,从 folder:A 到 readme 的箭头是一个已存储的元组(doc:readme#parent@folder:A),而从 Chen 的文件夹访问权到 readme 的那一步并没有存储在任何地方:schema 中的 parent.view 在检查时把它计算出来,就像论文中的 tuple_to_userset 一样。
架构
Permify 服务器如何分担工作,元组存放在哪里?
各个组成部分,均来自文档:
- 服务器默认监听 HTTP 端口 3476 和 gRPC 端口 3478(配置)。数据库部分接受独立的
writer和readerURI。 - 每个 pod 维护一个进程内的 Ristretto 检查结果缓存;“there is no shared cache layer”(没有共享缓存层)(缓存)。
- 启用
distributed.enabled后,pod 把每个请求哈希到一致性哈希环上,因此 “subsequent API calls with the same hash will retrieve the response from the instance 2, regardless of which instance that API called from”(之后具有相同哈希的 API 调用都会从实例 2 获取响应,无论该 API 是从哪个实例调用的)。数据库宕机时,熔断器会停止对它的调用。 - PostgreSQL 以 MVCC 方式存储元组:Permify 创建 “a separate database snapshot for each write and delete operation”(为每次写入和删除操作创建一个单独的数据库快照),一个可选的垃圾回收器会删除旧版本。
- 每个 Watch 流 “opens a long-lived connection with a continuous polling loop against the database”(打开一条长连接,并对数据库执行持续的轮询循环)(Watch 操作)。
一致性
Permify 的 snap token 扮演 zookie 的角色。Write 返回它;客户端把它与资源一起存储,并在之后的检查中作为 snap_token 发回。文档把它描述为 “a token that consists of an encoded timestamp”(一个由编码后的时间戳构成的令牌),在访问检查中用于比较,“to ensure that the snapshot of the access control is at least as fresh as the resource timestamp”(以确保访问控制的快照至少与资源的时间戳一样新)(snap tokens)。这正是论文为携带 zookie 的检查所给出的保证:“a consistent snapshot no earlier than”(一个不早于给定 zookie 的一致快照)(§2.4.4)。
共享变更之后进行的检查如何看到该变更?
注意不带令牌时的行为。论文允许 Zanzibar “choose a reasonably recent snapshot, possibly offering a lower-latency response”(选择一个合理较新的快照,这可能带来更低的响应延迟)(§2.4.1)。Permify 则从其 transactions 表中读取最新事务的 ID,并在该快照上进行评估;结果以包含该 ID 的键缓存(snap tokens)。缓存键为 check_{tenant_id}_{schema_version}:{snapshot_token}:{check_request}(缓存),因此一次新的写入会产生新的键,而不是使旧键失效。
与论文的差异
- 属性与规则。 Permify Schema 增加了用于基于属性检查的
attribute和rule,例如permission view = check_ip_range(ip_range) or admin(建模)。Zanzibar 的重写只作用于元组(§2.3.1)。 - 上下文元组。 “dynamically added to permission request operations”(动态添加到权限请求操作中)的关系与已存储的关系一起评估,且永远不会被写入(上下文元组)。
- 租户。
Tenancy服务用于创建、列出和删除租户(service.proto);论文中没有租户的概念。 - 存储。 使用带 MVCC 快照的 PostgreSQL,而不是 Spanner;Spanner 的 TrueTime 机制为每次 ACL 写入打上时间戳(§2.2、§3.1)。分布式缓存可以 “across availability zones (within an AWS region)”(跨可用区(在同一 AWS 区域内))工作(缓存)。
- 没有反规范化索引。 论文用 Leopard 回答深度嵌套组的检查(§3.2.4)。Permify 文档记载的是结果缓存和一致性哈希,而不是集合索引。
- 查找。
LookupEntity和LookupSubject回答论文的 API 不涵盖的“哪些资源”和“哪些主体”问题。
状态
- 首个版本 v0.0.0-alpha1 发布于 2022-08-03;最新版本 v1.7.6 发布于 2026-11-05;默认分支的最后一次提交在 2026-11-10;约 6.0k 个 star(releases,GitHub API,2026-11-13)。
- 许可证:LICENSE 文件于 2023-02-14 被替换为 Apache-2.0 文本(提交 97285f9),又于 2025-05-12 在一次标题为 “docs: update license” 的提交中被替换为 AGPL-3.0 文本(提交 26912d9)。在此之前,2022 年该文件先后为 Apache-2.0 文本(2022-07-14)、GPL-3.0(2022-08-25)和 AGPL-3.0(2022-08-26)(LICENSE 历史)。
- 所有权:被 FusionAuth 收购,于 2025-11-20 在 Permify 博客上宣布(文章);FusionAuth 的公告页面没有显示日期(文章)。二者都由厂商撰写。
- 文档已从 docs.permify.co 迁至 fusionauth.io/permify-docs。
来源
- Permify 仓库:https://github.com/Permify/permify
- Permify 文档(FusionAuth):https://fusionauth.io/permify-docs
- 建模:https://fusionauth.io/permify-docs/getting-started/modeling
- 存储数据:https://fusionauth.io/permify-docs/getting-started/sync-data
- Snap tokens:https://fusionauth.io/permify-docs/operations/snap-tokens
- 缓存机制:https://fusionauth.io/permify-docs/operations/cache
- Watch 操作:https://fusionauth.io/permify-docs/operations/watch
- 上下文元组:https://fusionauth.io/permify-docs/operations/contextual-tuples
- 配置:https://fusionauth.io/permify-docs/setting-up/configuration
- gRPC 服务:https://github.com/Permify/permify/blob/master/proto/base/v1/service.proto
- 示例 schema:https://github.com/Permify/permify/blob/master/assets/example-shapes/google-docs-simplified.yaml
- 许可证历史:https://github.com/Permify/permify/commits/master/LICENSE
- 许可证相关提交:https://github.com/Permify/permify/commit/97285f94d5e40d3f29f22fd01dc972655af122d7、https://github.com/Permify/permify/commit/26912d91f5a8c2ed3298bd29fdefd00f55da17b5
- 收购:https://permify.co/post/fusionauth-acquires-permify/、https://fusionauth.io/blog/fusionauth-acquires-permify
- 产品名称:https://fusionauth.io/blog/how-to-get-support-for-fusionauth-fga-permify