Casbin 学习指南

一、什么是 Casbin？

1.1 一句话介绍

Casbin是一个强大的、高效的访问控制框架，核心功能是：判断「谁」能否对「某资源」做「某操作」。

简单说，它负责判断：

谁，可以对什么东西，做什么操作？

比如：

张三能不能查看订单？
李四能不能删除用户？
管理员能不能修改系统配置？
普通用户能不能下载报表？

如果系统需要判断这些问题，就可以用 Casbin。

一句话理解：

Casbin就是系统里的权限门卫。

用户来了，Casbin 会看一眼规则：

有权限：放行
没权限：拦住

1.2 Casbin 能做什么？

Casbin 的作用是帮后端系统管理权限。

常见场景有：

• 后台管理系统
• 用户权限系统
• 企业内部系统
• SaaS 平台
• 多租户系统
• API 接口权限控制
• 菜单和按钮权限控制

比如一个后台系统里有这些角色：

管理员

运营

财务

普通用户

不同角色能做的事情不一样：

管理员：可以新增、删除、修改、查看用户

运营：可以查看和修改商品

财务：可以查看订单和账单

普通用户：只能查看自己的信息

如果不用权限框架，代码里可能会写很多判断：

if user.Role == "admin" {
return true
}
if user.Role == "finance" && action == "read" && resource == "bill" {
return true
}

项目小的时候还能忍，项目一大，这种代码就会越来越乱。

Casbin 的作用就是把这些权限规则统一管理起来，让代码更清楚。

1.3 技术特点

二、Casbin 核心概念

2.1 三个核心概念

Casbin 的设计围绕三个核心概念展开：Model（模型）、Policy（策略）、Enforcer（执行器）。

2.2 Model（模型）—— 规则的骨架

Model 用 CONF 配置文件来描述权限判断的逻辑结构。

最常见的 Model 是 ACL（访问控制列表），格式如下：

• request_definition：定义请求格式，比如 r = sub, obj, act 代表：谁(sub)、对什么(obj)、做什么(act)
• policy_definition：定义权限格式，和 request 对应
• matchers：核心！定义「请求」和「策略」如何匹配，比如 r.sub == p.sub 表示请求中的用户等于策略中的用户

2.3 Policy（策略）—— 具体权限数据

Policy 是具体的权限记录，每一行代表一个权限规则。

p = sub, obj, act 对应的 Policy 文件（CSV 格式）示例：

• 第一行：alice 能读 data1
• 第二行：bob 能写 data2
• 第三行：admin 对 data1 有所有权限（* 代表通配符）

2.4 Enforcer（执行器）—— 核心引擎

Enforcer 是 Casbin 的核心，它加载 Model 和 Policy，然后提供 Enforce() 方法让你做权限判断。

类比：Model = 设计图，Policy = 材料，Enforcer = 建筑工人

三、Casbin 的工作原理

3.1 权限判断的完整流程

1. 用户发起请求：alice 想读取 data1（请求 = alice, data1, read）
2. 请求到达 Enforcer：Enforcer 接收这个请求
3. 加载所有策略：Enforcer 查看 Policy 文件中有哪些规则
4. Matcher 匹配：把请求代入 Matcher 公式，逐一对比每条 Policy
5. 返回结果：匹配成功返回 true（允许），匹配失败返回 false（拒绝）

3.2 Matcher 公式详解

Matcher 是 Casbin 最核心的逻辑，下面详细拆解：

• r.sub：请求中的用户（alice）
• p.sub：策略中的用户（alice、bob、admin）
• &&：必须同时满足所有条件
• 如果 r.sub == p.sub && r.obj == p.obj && r.act == p.act 都成立 → 允许访问

进阶Matcher示例：支持通配符

加了 || p.act == "*" 之后，p.act 为 * 的规则表示对所有操作都放行。

进阶Matcher示例：基于角色

如果 Model 中定义了角色关系（g），还可以这样写：

这样 r.sub 可以是 alice，但 p.sub 可以是 role:admin，通过 g 找到 alice 的角色，再判断权限。

四、快速上手（Hello World）

4.1 安装

使用 Go 语言环境（以 Go 为例）：

go get github.com/casbin/casbin/v2

4.2 创建 Model 文件（basic_model.conf）

4.3 创建 Policy 文件（basic_policy.csv）

4.4 编写代码（main.go）

五、Model 文件详解

5.1 Model 的标准结构

一个完整的 Model.conf 文件包含以下五个部分（section）：

5.2 经典权限模型

ACL 模型（最简单）

适用场景：用户直接绑定资源权限，适合简单系统

RBAC 模型（基于角色，最常用）

Policy 示例：

适用场景：绝大多数后台管理系统（用户 → 角色 → 权限）

六、Policy 文件详解

6.1 CSV 格式说明

Policy 文件是 CSV 格式，每行一条策略记录，逗号分隔各字段。

格式：p, 字段1, 字段2, 字段3, ... （字段的数量和顺序，必须和Model配置中[policy_definition]里p = sub, obj, act定义的完全一致）

6.2 RBAC Policy 示例

Policy 文件（rbac_policy.csv）：

解释：

• p 开头：定义权限规则（admin 能读写 /admin/users，editor 能读写 /articles）
• g 开头：定义角色关系（alice 属于 admin 角色，bob 属于 editor 角色）

6.3 运行时修改 Policy

Casbin 支持在代码运行时动态添加/删除/修改策略，无需重启应用：

• AddPolicy()：添加一条策略

• RemovePolicy()：删除一条策略

• RemoveFilteredPolicy()：删除符合条件的多条策略

• UpdatePolicy()：更新一条策略

• SavePolicy()：保存修改到策略

七、资源推荐

7.1官方资源

7.2 常见问题

Q：Casbin 和 Spring Security 有什么区别？

Casbin 是通用的权限框架，不依赖具体语言和框架；Spring Security 是 Java 技术栈的解决方案，Casbin 可以集成进 Spring Security 一起用。

Q：Policy 存在哪里？

可以存 CSV 文件、数据库（通过 Adapter），生产环境推荐用数据库。

Q：Model 和 Policy 有什么区别？

Model 是「规则模板」，Policy 是「具体数据」；Model 决定判断逻辑，Policy 决定谁有什么权限。

Q：性能怎么样？

Casbin 做了大量优化，本地判断在微秒级，性能非常好，放心在生产环境使用。