Expand description
Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text.
§Garrison
Garrison 是一个面向 Rust 生态的一站式身份认证鉴权框架。
§快速开始
最小可用示例:初始化管理器 → 执行登录 → 校验登录状态。
ⓘ
use std::sync::Arc;
use garrison::prelude::*;
// 1. 准备依赖(业务方实现 GarrisonDao / GarrisonInterface)
let dao: Arc<dyn GarrisonDao> = /* oxcache / dbnexus 实现 */;
let config = Arc::new(GarrisonConfig::default_config());
let interface: Arc<dyn GarrisonInterface> = Arc::new(MyInterface);
// 2. 初始化全局管理器(覆盖式注入 dao / config / interface)
GarrisonManager::init(dao, config, interface).unwrap();
// 3. 执行登录:生成 token 并写入会话
// 注意:login / check_login 依赖 task_local 上下文中的当前 token,
// 通常由 web 中间件(如 axum middleware)设置。
let token = GarrisonUtil::login(1001).await.unwrap();
// 4. 校验登录状态
let logged_in = GarrisonUtil::check_login().await.unwrap();
assert!(logged_in);§特性
Garrison 通过 Cargo feature flags 控制各能力域的编译:
| 类别 | Feature | 说明 |
|---|---|---|
| 默认 | default | 空(按需启用所需 feature;all-defaults 可一键启用常用组合) |
| 缓存 | cache-memory / cache-redis | 基于 oxcache 0.3 的 L1(内存) + L2(redis),均启用 oxcache(语义别名) |
| 数据库 | db-sqlite | 基于 dbnexus 0.2 + auto-migrate |
| Web 框架 | web-axum / web-actix / web-warp | 路由拦截器与 extractor 适配 |
| 协议层 | protocol-jwt / protocol-oauth2 / protocol-sso / protocol-sign / protocol-apikey / protocol-temp | 鉴权协议插件 |
| 安全模块 | secure-totp / secure-sign / secure-httpbasic / secure-httpdigest | TOTP / 签名 / Basic / Digest |
| 可观测性 | listener / tracing-log / metrics-prometheus | 事件监听 / 日志 / 指标 |
| 聚合 | full / production / development | 一键启用一组特性 |
§模块概览
0.2.0 在 0.1.0 基础上扩展了协议层、安全模块与可插拔扩展点:
- 核心扩展(always on)
core::token:Tokentrait +TokenStyleFactory(uuid / random_64 / simple / jwt 四种风格)core::auth:AuthLogictrait +DefaultAuthLogic(login_by_token / verify_token / refresh_token)core::permission:PermissionCheckertrait +DefaultPermissionCheckerplugin:GarrisonPlugintrait +inventory编译期注册 +GarrisonPluginManager(on_login / on_logout / on_permission_check 钩子)strategy:GarrisonPermissionStrategyDefault扩展with_permission_checker/with_role_hierarchy/with_plugin_manager/with_dao(权限缓存)session:GarrisonSession扩展 SSO / OAuth2 / 临时凭证关联(link_sso_ticket/link_oauth2_token/link_temp_credential)
- 协议层(特性门控)
protocol::jwt:JwtHandler(sign / verify / refresh,HS256/HS512)protocol::oauth2:OAuth2Client(Authorization Code / Client Credentials / Password 三种流程)protocol::sso:SsoClient(ticket 签发 / 校验 / 销毁,一次性 60s TTL)protocol::sign:SignHandler(HMAC-SHA256 签名 + 防重放时间窗口)protocol::apikey:ApiKeyHandler(生成 / 校验 / 吊销 / 轮换)protocol::temp:TempCredentialHandler(issue / get / revoke / consume)
- 安全模块(特性门控)
secure::totp:TotpHandler(RFC 6238,±1 时间窗口偏差)secure::sign:SignVerifiertraitsecure::httpbasic/secure::httpdigest:HTTP Basic / Digest 认证
- 可观测性
listener:GarrisonEvent+Listenertrait +GarrisonListenerManager(Login / Logout / PermissionCheck / Kickout 事件)
§特性域
Garrison 采用 13 个特性域设计:
- 登录认证 - 基于 Token 的会话管理
- 权限认证 - RBAC 权限模型
- Session 会话 - 会话生命周期管理
- OAuth2 - 第三方授权
- 单点登录 (SSO) - 跨系统统一登录
- JWT - JSON Web Token 支持
- 微服务网关鉴权 - 网关层签名认证
- API 接口鉴权 - API Key 认证
- TOTP 动态验证码 - 时间一次性密码
- Basic 认证 - HTTP Basic Auth
- Digest 认证 - HTTP Digest Auth
- 路由拦截鉴权 - Web 框架适配
- 插件化扩展 - 编译期插件注册
§架构
Garrison 采用双抽象层 + 全局单例的架构:
- 双抽象层
dbnexus:数据库抽象层(SQLite / PostgreSQL / MySQL),由GarrisonDaotrait 屏蔽后端差异oxcache:缓存抽象层(L1 内存 + L2 redis),承载 Token-Session 与 Account-Session
- GarrisonManager 单例模式
GarrisonManager持有全局Arc<GarrisonLogicDefault>(基于parking_lot::RwLock,支持覆盖式init)- 业务方启动时调用
GarrisonManager::init注入 dao / config / interface 依赖 GarrisonLogicFactory通过inventory::submit!在编译期注册,运行时由inventory::iter选取GarrisonUtil::login/GarrisonUtil::check_login等静态方法委托到全局单例
§双抽象层
- dbnexus - 数据库抽象层(SQLite / PostgreSQL / MySQL)
- oxcache - 缓存抽象层(L1 内存 + L2 redis)
§使用示例
[dependencies]
garrison = { version = "0.7", features = ["web-axum", "protocol-jwt"] }use garrison::prelude::*;
// 通过 prelude 引入核心类型
// let _config: GarrisonConfig = GarrisonConfig::default();Re-exports§
pub use context::tenant::HeaderTenantResolver;pub use context::tenant::SubdomainTenantResolver;pub use context::tenant::TenantContext;pub use context::tenant::TenantResolver;pub use context::tenant::TenantSource;pub use context::tenant::TENANT;pub use context::GarrisonPrincipal;pub use state::TokenState;pub use state::UserStatus;pub use dao::repository::role_hierarchy::RoleHierarchyRecord;pub use prelude::*;
Modules§
- abac
- ABAC 策略引擎模块,提供 AbacEngine(基于 Cedar 策略语言)。
- account
- 账号安全引擎模块(吸收 keycloak 安全能力)。
- annotation
- 注解模块,定义鉴权注解枚举。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 注解模块,定义鉴权注解枚举与 axum extractor。
- backend
backend-embeddedorbackend-remote - 认证后端抽象模块,提供 AuthBackend trait + BackendEmbedded + BackendRemote。
- config
- 配置模块,提供 GarrisonConfig 全局配置。 Copyright (c) 2024-2026 Kirky.X. All rights reserved. See LICENSE for full license text. 配置模块,提供 GarrisonConfig 全局配置。
- constants
- 常量定义模块,提供 DAO key 前缀等类型安全枚举。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 常量模块,提供框架共享的枚举与常量定义。
- context
- 上下文模块,提供请求/响应/存储上下文抽象。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 上下文模块,提供请求 / 响应 / 存储上下文抽象。
- core
- 核心模块,包含认证、权限、Token 的核心抽象。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 核心模块,包含认证、权限、Token 的核心抽象。
- dao
- DAO 模块,定义持久化数据访问抽象层。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. DAO 模块,定义持久化数据访问抽象层。
- error
- 错误类型定义模块。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 错误类型定义模块。
- exception
- 异常模块,定义框架异常类型。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 异常模块,定义框架异常类型。
- health
- 健康检查模块,提供 liveness/readiness 探针与依赖项健康检测。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 健康检查模块,提供 liveness/readiness 探针与依赖项健康检测。
- i18n
- 国际化模块,提供异常消息中英文切换(fluent-rs)。
- json
- JSON 模块,提供 JSON 模板与序列化抽象。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. JSON 模块,提供 JSON 模板与序列化抽象。
- manager
- 管理器模块,提供全局管理器单例。 Copyright (c) 2024-2026 Kirky.X. All rights reserved. See LICENSE for full license text. 管理器模块,提供全局管理器单例与编译期工厂注册。
- plugin
- 插件模块,定义插件 trait 与编译期注册。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 插件模块,定义插件 trait 与编译期注册。
- prelude
- 预导出模块,包含最常用的类型与 trait。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 预导出模块,包含最常用的类型与 trait。
- router
- 路由模块,提供路由器与拦截器抽象。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 路由模块,提供路由器与拦截器抽象。
- session
- 会话模块,提供 GarrisonSession 会话模型。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 会话模块,提供双模会话管理(Account-Session + Token-Session)。
- state
- 状态机模块,定义 Token / User 显式状态机。
- stp
- Stp 模块,提供 GarrisonLogicDefault / GarrisonInterface / GarrisonUtil + 5 个子 trait。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. Stp 模块,提供核心认证逻辑与工具入口。
- strategy
- 策略模块,提供鉴权策略与防火墙策略。 Copyright (c) 2026 Kirky.X. All rights reserved. See LICENSE for full license text. 策略模块,提供鉴权策略与可插拔权限策略。
Macros§
- loc
- 构造本地化错误文案:优先按
key查 FTL 翻译,缺失时回退$fallback字符串。