본문으로 건너뛰기

프로덕션 배포

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를 통해 이 인스턴스로 전달됩니다. Enforce 전에 다시 로드할 필요가 없습니다.

정책이 메모리에 유지하기에 너무 큰 경우, Policy subset loading을 사용하여 각 인스턴스에 필요한 부분만 로드하세요.

Model을 스레드 간에 안전하게 공유하기​

기본 Enforcer는 정책이 변경되는 동안 요청을 처리할 때 동시 사용에 안전하지 않습니다. 한 스레드에서 실행되는 LoadPolicy() 또는 AddPolicy()가 다른 스레드의 Enforce()와 경쟁 상태(race condition)를 일으킬 수 있습니다. 읽기 및 쓰기를 읽기-쓰기 락(read-write lock)으로 보호하는 동기화 enforcer를 사용하세요:

LanguageSynchronized enforcer
Gocasbin.NewSyncedEnforcer(), casbin.NewSyncedCachedEnforcer(), casbin.NewSyncedContextEnforcer() (v3.11.0 이후 버전의 *Ctx API용)
JavaSyncedEnforcer, SyncedCachedEnforcer
Pythoncasbin.SyncedEnforcer
Node.jsnewSyncedEnforcer()
C++casbin::SyncedEnforcer

동기화 enforcer는 Enforcer와 동일한 API를 제공합니다. Go에서는 ContextEnforcer도 동기화되지 않으므로, 동시 LoadPolicyCtx() / AddPolicyCtx() 및 Enforce() 호출로 인해 프로세스가 concurrent map read and map write 오류로 충돌할 수 있습니다. 따라서 대신 NewSyncedContextEnforcer()를 사용하세요(v3.11.0 이후 버전; 이전 버전에서는 자체 sync.RWMutex로 보호해야 함). 자세한 내용은 Multithreading 및 Enforcers를 참조하세요.

결정 캐싱 주의사항​

CachedEnforcer와 SyncedCachedEnforcer는 각 Enforce() 호출의 결과를 기억합니다. 동일한 요청이 자주 반복될 때는 유용하지만, 캐시된 결정이 해당 결정을 생성한 정책보다 오래 지속될 수 있습니다. Go에서는:

  • LoadPolicy()는 전체 캐시를 지웁니다.
  • 정책 규칙을 추가하거나 삭제하면 해당 규칙과 정확히 일치하는 요청의 캐시 항목만 제거됩니다. 역할 할당(g) 등을 통해 규칙에 간접적으로 의존했던 결정은 계속 캐시됩니다.
  • 역할 할당을 변경한 후에는 InvalidateCache()를 호출하고, SetExpireTime()으로 시간 제한을 설정하여 만료된 결정이 영원히 남지 않도록 하세요.

복제본 동기화 유지​

여러 인스턴스(여러 pod 또는 pod당 여러 worker 프로세스)를 실행하는 경우, 각 인스턴스는 정책의 고유한 사본을 가지고 있습니다. 동기화가 없으면 인스턴스 A를 통해 부여된 권한은 인스턴스 B에는 보이지 않으며, 더 나쁜 점은 A를 통해 취소된 권한은 B가 재시작될 때까지 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(Go, Java, Python 모두 지원)에서 StartAutoLoadPolicy(5 * time.Minute)를 사용하세요.
  • 강력한 일관성이 필요한가요? Watcher는 최종 일관성(eventually consistent)을 제공합니다. 쓰기 작업이 반환되기 전에 모든 인스턴스가 변경 사항을 확인해야 한다면 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)​

모든 오류를 거부(denial)로 처리하세요:

  • 시작 시 enforcer를 생성할 수 없거나 policy를 로드할 수 없는 경우, 권한 확인이 필요한 요청을 허용하지 않고 거부합니다.
  • 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.