跳到主要内容

生产部署

Casbin 是一个库:enforcer 位于您的进程内部并将整个策略保存在内存中。这使得 Enforce() 速度很快,但也意味着您需要决定如何创建 enforcer、在线程间共享它以及如何与其他实例保持同步。本页是正确执行这些操作的检查清单。

每个进程创建一个 enforcer​

在启动时创建一次 enforcer 并共享它。加载策略开销很大:它会从适配器读取每条规则并重建模型和角色图。

不要在每个请求上调用 LoadPolicy()(或创建新的 enforcer):

// Don't: this reads the whole policy table on every request
func authorize(sub, obj, act string) (bool, error) {
if err := e.LoadPolicy(); err != nil {
return false, err
}
return e.Enforce(sub, obj, act)
}

通过 enforcer 的 Management API (AddPolicy, RemovePolicy, AddGroupingPolicy, ...) 进行的策略更改会同时更新内存,并且在使用 AutoSave 时也会更新数据库。其他实例所做的更改会通过 watcher 到达此实例。在执行之前无需重新加载。

如果策略太大而无法保存在内存中,请使用 Policy subset loading 仅加载每个实例所需的部分。

在多个线程之间安全地共享 Enforcer​

当策略可能在执行请求的过程中发生变化时,普通的 Enforcer 不是并发安全的:在一个线程上运行的 LoadPolicy() 或 AddPolicy() 可能会与另一个线程上的 Enforce() 产生竞争。请使用同步 Enforcer,它通过读写锁来保护读写操作:

语言同步 Enforcer
Gocasbin.NewSyncedEnforcer(), casbin.NewSyncedCachedEnforcer(), casbin.NewSyncedContextEnforcer() (用于 *Ctx API,v3.11.0 之后的版本)
JavaSyncedEnforcer, SyncedCachedEnforcer
Pythoncasbin.SyncedEnforcer
Node.jsnewSyncedEnforcer()
C++casbin::SyncedEnforcer

同步 Enforcer 的 API 与 Enforcer 相同。在 Go 中,ContextEnforcer 也不是同步的:并发的 LoadPolicyCtx() / AddPolicyCtx() 和 Enforce() 可能会导致进程因 concurrent map read and map write 而崩溃,因此请改用 NewSyncedContextEnforcer()(v3.11.0 之后的版本;在早期版本中,请使用你自己的 sync.RWMutex 进行保护)。有关详细信息,请参阅 多线程 和 Enforcers。

谨慎缓存决策结果​

CachedEnforcer 和 SyncedCachedEnforcer 会记住每次 Enforce() 调用的结果。当相同的请求频繁重复出现时,它们很有用,但缓存的决策可能会比产生它的策略存活得更久。在 Go 中:

  • LoadPolicy() 会清除整个缓存。
  • 添加或删除策略规则最多只会丢弃与该规则完全匹配的请求的缓存条目。间接依赖该规则的决策(例如通过角色分配 g)仍然保留在缓存中。
  • 更改角色分配后,请调用 InvalidateCache(),并使用 SetExpireTime() 设置时间限制,以免过期的决策永久存在。

保持副本同步​

当你运行多个实例(多个 Pod,或每个 Pod 中的多个工作进程)时,每个实例都有自己的策略副本。如果没有同步机制,通过实例 A 授予的权限对实例 B 不可见,更糟糕的是,通过 A 撤销 的权限在 B 重启之前仍然有效。

使用 watcher(Redis、etcd、Kafka、NATS、数据库等)。当一个实例更改策略时,它会发布一条消息;其他实例接收该消息并更新其副本。

import (
"github.com/casbin/casbin/v3"
gormadapter "github.com/casbin/gorm-adapter/v3"
rediswatcher "github.com/casbin/redis-watcher/v2"
)

a, _ := gormadapter.NewAdapterByDB(db)
e, _ := casbin.NewSyncedCachedEnforcer("rbac_model.conf", a)

w, _ := rediswatcher.NewWatcher("redis:6379", rediswatcher.WatcherOptions{
Channel: "/casbin",
IgnoreSelf: true,
})
_ = e.SetWatcher(w)

// Reload through the synced, cached enforcer so the reload takes its lock
// and clears its decision cache
_ = w.SetUpdateCallback(func(string) { _ = e.LoadPolicy() })

需要注意的事项:

  • 使用包装后的 enforcer 时,请自行设置回调。 在 Go 中,SetWatcher() 会安装一个默认回调,该回调重新加载内部的 Enforcer,这会绕过 SyncedEnforcer 的锁和 SyncedCachedEnforcer 的缓存。请在 SetWatcher() 之后调用 SetUpdateCallback(),如上所述。
  • AutoSave 和通知是独立的。 EnableAutoSave() 决定更改是否写入适配器;EnableAutoNotifyWatcher() 决定是否通知其他实例。你可以关闭 AutoSave 但仍然发送通知,当你自己持久化策略时就需要这样做(参见 下文)。pycasbin 2.8.0 及更早版本仅在 AutoSave 开启时才发送通知;较新版本的行为与其他语言一致。
  • 增量更新。 普通的 Watcher 会让其他实例重新加载整个策略。WatcherEx 会发送具体的更改内容(UpdateForAddPolicy、UpdateForRemovePolicy 等),接收实例仅应用该更改。在 Python 中,使用 DistributedEnforcer.add_policy_self(False, ...) 等方法来应用它,这些方法只更新内存而不写入适配器。在 Go 中,Self* 方法(SelfAddPolicy、SelfRemovePolicy 等)会跳过 watcher,但在 AutoSave 开启时仍会写入适配器。当所有实例共享同一个数据库时,更改已经存在于数据库中,因此第二次写入会导致重复或失败;应像上面的示例那样,在回调中使用 LoadPolicy() 重新加载。
  • 设置兜底机制。 当实例与消息总线断开连接时,消息可能会丢失。定期全量重新加载可以限制错过的更新持续的时间:在 SyncedEnforcer 上使用 StartAutoLoadPolicy(5 * time.Minute)(Go、Java 和 Python 都支持此功能)。
  • 需要强一致性吗? Watcher 提供最终一致性。如果每个实例必须在写操作返回之前看到更改,请使用 dispatcher,或将授权逻辑移入单个服务,使用 Casbin Server。

在自己的事务中写入策略​

应用程序通常在一个数据库事务中创建用户、团队以及用户的角色。如果 enforcer 在开启 AutoSave 的情况下写入 casbin_rule,该写入操作将位于你的事务之外,如果事务回滚,规则将会残留。

有两种方法可以将它们放在一起:

  1. 自己写入行数据,然后在提交后更新内存。 关闭 AutoSave,在你的事务中插入 casbin_rule 行,并在事务提交后调用 enforcer 的 AddPolicy() / AddGroupingPolicy()。关闭 AutoSave 后,这些操作仅更新内存,且 watcher 仍会通知其他实例。

    enforcer.enable_auto_save(False)

    with db.transaction():
    create_user(...)
    insert_casbin_rule("g", "alice", "team-admin")

    # after commit: update this instance and notify the others
    enforcer.add_grouping_policy("alice", "team-admin")
  2. Go:使用事务性 enforcer。 NewTransactionalEnforcer() 配合事务性适配器(例如 gormadapter.NewTransactionalAdapterByDB())会缓冲更改,并在 Commit() 时将其应用到数据库和内存。参见 Adapters: Transaction。v3.11.0 之后的版本会在 Commit() 成功后通知 watcher,如果 watcher 是 WatcherEx,则包含具体更改;回滚的事务不会通知任何人。在 v3.11.0 及更早版本中,提交不会通知 watcher,因此在提交后需调用 w.Update() 以告知其他实例。

只读副本和迁移​

某些适配器在启动时会创建 casbin_rule 表。在只读数据库副本(例如被动灾难恢复站点)上,该语句会失败。请使用你自己的迁移来创建表,并在适配器支持的地方关闭适配器的自动迁移功能,例如在 Go 中使用 gormadapter.TurnOffAutoMigrate(db)。在只读实例上,仅调用 LoadPolicy() 和 Enforce()。

失败即拒绝 (Fail closed)​

将任何错误视为拒绝:

  • 如果启动时无法创建执行器或加载策略,请拒绝需要授权的请求,而不是放行。
  • 如果 Enforce() 返回错误,则拒绝该请求。
ok, err := e.Enforce(sub, obj, act)
if err != nil || !ok {
return http.StatusForbidden
}

Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.