# Garrison 架构设计文档
> Garrison 是面向 Rust 生态的身份认证鉴权框架。
>
> - 版本:0.7.0(微服务架构 + ABAC/Cedar + OAuth2 Server + 架构加固 + 依赖优化:backend-remote / Auth Server / ABAC 引擎 / OAuth2 Server 4 端点 / secure-sanitize / 错误类型统一 / mod.rs 加固)
> - 运行时:tokio 1.x
> - Web 适配:axum 0.8 / actix-web 4 / warp 0.4
> - 存储:dbnexus 0.4(SQLite / PostgreSQL / MySQL + auto-migrate)+ Repository 层(10 trait + SqliteRepository,tenant_id 隔离)
> - 缓存:oxcache 0.3(L1 内存 + L2 redis,per-entry TTL + ttl_sync 查询)
> - License:Apache-2.0
> 配置相关字段说明详见 [configuration.md](./CONFIGURATION.md);开发规范详见 [development.md](./DEVELOPMENT.md)。
---
## 一、架构概览
Garrison 采用 **双抽象层 + 全局单例** 架构,核心设计目标:
1. 业务代码只面向 trait 编程,存储后端可平滑替换;
2. 启动时一次性注入依赖,运行期零状态调用,业务代码通过 `GarrisonManager` 静态 API 即可使用。
### 1.1 双抽象层
- **DAO 抽象层**:`GarrisonDao` trait 屏蔽存储后端差异,底层由 `dbnexus`(数据库)+ `oxcache`(缓存)实现,切换 SQLite / PostgreSQL / MySQL 时上层无需改动。
- **缓存抽象层**:`oxcache` 0.3 提供 L1(oxcache 内存层)+ L2(redis 分布式)两级缓存,支持 per-entry TTL 精细化过期控制,对上层呈现统一 `get / set / remove` 语义。
### 1.2 全局单例
- `GarrisonManager` 通过 `parking_lot::RwLock` 持有 `Arc<GarrisonLogicDefault>`(v0.5.2 起 `GarrisonLogic` trait 拆分为 `GarrisonCore` base trait + 5 个子 trait:`SessionLogic` / `PermissionLogic` / `TokenLogic` / `MfaLogic` / `PasswordLogic`),启动时调用 `GarrisonManager::init()` 一次性注入 dao / config / interface。
- `GarrisonLogicFactoryEntry` 通过 `inventory::submit!` 在编译期注册,运行时由 `inventory::iter` 选取默认实现。
- `GarrisonUtil` 暴露静态方法(`login` / `check_login` / `logout` 等),内部全部委托 `GARRISON_MANAGER` 单例,业务侧零状态调用。
### 1.3 双模会话
Garrison 同时维护两种会话维度:
- **Account-Session**:以 `login_id` 为 key,存储账号级长生命周期数据(角色、权限、用户画像)。
- **Token-Session**:以 `token` 为 key,存储该次登录的临时数据(设备、登录时间、临时授权)。
由 `is_share` / `is_concurrent` 配置控制多端共享与并发登录策略。
---
## 二、模块划分
Garrison 分为四层模块,由 feature flag 控制编译裁剪:
```mermaid
graph TB
subgraph CoreLayer["核心模块(always on)"]
core[core<br/>token / permission / auth]
stp[stp<br/>GarrisonCore + 5 个子 trait / GarrisonUtil]
session[session<br/>GarrisonSession]
config[config<br/>GarrisonConfig]
context[context<br/>task_local 上下文]
dao[dao<br/>GarrisonDao trait]
strategy[strategy<br/>GarrisonPermissionStrategy]
manager[manager<br/>GarrisonManager 单例]
annotation[annotation<br/>注解枚举]
router[router<br/>GarrisonRouter]
json[json<br/>JSON 模板]
exception[exception<br/>异常类型]
plugin[plugin<br/>插件 trait]
account[account<br/>凭证 / 密码策略 / 锁定 / 认证流]
listener[listener<br/>事件监听器]
error[error<br/>GarrisonError]
health[health<br/>健康检查]
state[state<br/>运行时状态]
i18n[i18n<br/>国际化基础层]
constants[constants<br/>常量定义]
prelude[prelude<br/>预导入]
end
subgraph ProtocolLayer["协议层(feature 门控)"]
protocol-jwt[protocol-jwt]
oauth2[protocol-oauth2]
sso[protocol-sso]
sign[protocol-sign]
apikey[protocol-apikey]
temp[protocol-temp]
oidc[protocol-oidc<br/>0.4.0 新增]
scope-handler[oauth2-scope-handler<br/>0.4.0 新增]
sso-server[protocol-sso-server<br/>0.4.0 新增]
end
subgraph ExtensionLayer["扩展层(feature 门控,0.4.0 新增)"]
alone-cache[alone-cache<br/>多实例隔离]
parameter-query[parameter-query<br/>参数化查询]
end
subgraph SecureLayer["安全层(feature 门控)"]
secure-totp[secure-totp]
secure-sign[secure-sign]
httpbasic[secure-httpbasic]
httpdigest[secure-httpdigest]
sms[sms-rate-limit]
confusable[secure-confusable]
masking[secure-masking]
sanitize[secure-sanitize]
xss[secure-xss]
end
subgraph InfraLayer["基础设施"]
oxcache[oxcache 0.3<br/>L1 内存 + L2 redis]
dbnexus[dbnexus 0.4<br/>SQLite / PostgreSQL / MySQL + auto-migrate]
sdforge[sdforge 0.4<br/>声明式路由]
trait-kit[trait-kit 0.3<br/>typestate DI]
end
subgraph ServerLayer["服务器层(feature 门控)"]
auth-server[auth-server<br/>独立认证服务器]
oauth2-server[oauth2-server<br/>OAuth2 授权服务器]
grpc[grpc<br/>gRPC 拦截器]
backend-remote[backend-remote<br/>远程后端]
end
subgraph WebLayer["Web 安全层(feature 门控)"]
web-axum[web-axum<br/>axum 适配]
web-actix[web-actix<br/>actix-web 适配]
web-warp[web-warp<br/>warp 适配]
waf[web-waf<br/>WAF]
cors[web-cors<br/>CORS]
csrf[web-csrf<br/>CSRF]
end
subgraph Observable["可观测性(feature 门控)"]
listener-events[listener<br/>事件监听]
metrics[metrics-prometheus<br/>Prometheus 指标]
tracing[tracing-log<br/>结构化日志]
otlp[observability-otlp<br/>OTLP 分布式追踪]
end
CoreLayer --> InfraLayer
ProtocolLayer --> CoreLayer
ExtensionLayer --> CoreLayer
SecureLayer --> CoreLayer
Observable --> CoreLayer
ServerLayer --> CoreLayer
ServerLayer --> InfraLayer
WebLayer --> CoreLayer
```
### 2.1 核心模块(always on,无 feature flag)
| `core/` | 核心层:`core/token`(Token 生成校验)、`core/permission`(权限校验)、`core/auth`(登录鉴权) |
| `stp/` | `GarrisonCore` + 5 个子 trait(`SessionLogic` / `PermissionLogic` / `TokenLogic` / `MfaLogic` / `PasswordLogic`)+ `GarrisonInterface` trait + `GarrisonUtil` 静态门面 |
| `session/` | `GarrisonSession` 会话模型(Account + Token 双模) |
| `config/` | `GarrisonConfig` 全局配置 + 热更新 |
| `context/` | `GarrisonContext` 请求上下文抽象 + axum 适配器 + task_local |
| `dao/` | `GarrisonDao` trait + dbnexus 实现 |
| `strategy/` | `GarrisonPermissionStrategy` 权限策略 |
| `manager/` | `GarrisonManager` 全局单例 + inventory 编译期注册 |
| `annotation/` | 鉴权注解枚举 |
| `router/` | `GarrisonRouter` + Interceptor 路由拦截 |
| `json/` | JSON 模板与序列化抽象 |
| `exception/` | 框架异常类型 |
| `plugin/` | `GarrisonPlugin` trait 与编译期注册 |
### 2.2 协议层(feature 门控,默认关闭)
| `protocol/jwt` | `protocol-jwt` | JWT 签发与验证(HS256/HS512 + refresh) | 0.2.0 |
| `protocol/oauth2` | `protocol-oauth2` | OAuth2 四种模式(授权码 / 客户端凭证 / 密码 / RefreshToken) | 0.2.0(0.4.0 扩展 RefreshToken) |
| `protocol/sso` | `protocol-sso` | SSO 单点登录 ticket(一次性 60s TTL) | 0.2.0 |
| `protocol/sign` | `protocol-sign` | API 签名 + nonce 防重放 | 0.2.0 |
| `protocol/apikey` | `protocol-apikey` | API Key 认证(生成/校验/吊销/轮换) | 0.2.0 |
| `protocol/temp` | `protocol-temp` | 临时凭证(issue/get/revoke/consume) | 0.2.0 |
| `protocol/oauth2/oidc` | `protocol-oidc` | OIDC id_token 签发/验证 + discovery + 三重防重放(iss/aud/nonce) | 0.4.0 |
| `protocol/oauth2/scope` | `oauth2-scope-handler` | `ScopeHandler` trait + `ScopeRegistry` 注册表,OAuth2Client 委托校验 | 0.4.0 |
| `protocol/sso/server` | `protocol-sso-server` | `SsoServer` trait + `CenterIdConverter` + `SsoChannel` + `DefaultSsoServer` | 0.4.0 |
| `protocol/sso/saml` | `protocol-sso` | SAML 2.0 骨架:`SamlProvider` trait + `DefaultSamlProvider`(quick-xml 解析) | 0.6.0 |
| `protocol/sso/oidc` | `protocol-sso` | OIDC RP 骨架:`OidcProvider` trait + `DefaultOidcProvider`(discovery + token exchange) | 0.6.0 |
| `protocol/sso/channel` | `cache-redis` + `protocol-sso-server` | `RedisPubSubSsoChannel`:Redis pub/sub 跨实例 SsoChannel 实现 | 0.6.0 |
### 2.3 扩展层(feature 门控,默认关闭,0.4.0 新增)
| `dao/alone_cache` | `alone-cache` | `AloneCache` 装饰器(实现 GarrisonDao,key_prefix 隔离)+ `AloneCacheManager`(多实例管理) |
| `stp/parameter` | `parameter-query` | `ParameterQuery` trait + `ParameterQueryBuilder`(链式 with_login_id/with_device/with_token + async check_permission/check_role) |
### 2.4 安全层(feature 门控,默认关闭)
| `secure/totp` | `secure-totp` | TOTP 动态验证码(RFC 6238) |
| `secure/sign` | `secure-sign` | HMAC 签名工具 |
| `secure/httpbasic` | `secure-httpbasic` | HTTP Basic 认证 |
| `secure/httpdigest` | `secure-httpdigest` | HTTP Digest 认证 |
| `secure/sms` | `sms-rate-limit` | SMS 验证码限速 |
| `secure/confusable` | `secure-confusable` | Unicode 同形异义字检测 |
| `secure/masking` | `secure-masking` | 敏感数据脱敏(regex 真实脱敏) |
| `secure/sanitize` | `secure-sanitize` | 通用输入消毒 |
| `secure/xss` | `secure-xss` | XSS 防护 |
---
## 三、关键 trait 关系图
Garrison 的核心抽象通过 trait 解耦,业务方实现 trait 即可接入:
```mermaid
graph LR
BC[GarrisonCore<br/>base trait]
SL[SessionLogic<br/>会话逻辑 trait]
PL[PermissionLogic<br/>权限逻辑 trait]
TL[TokenLogic<br/>Token 逻辑 trait]
ML[MfaLogic<br/>MFA 逻辑 trait]
PWL[PasswordLogic<br/>密码逻辑 trait]
BI[GarrisonInterface<br/>业务数据源 trait]
BD[GarrisonDao<br/>持久化抽象 trait]
BS[GarrisonSession<br/>会话模型]
BCtx[GarrisonContext<br/>请求上下文 trait]
BFS[GarrisonPermissionStrategy<br/>权限策略 trait]
BM[GarrisonManager<br/>全局单例]
BU[GarrisonUtil<br/>静态门面]
BU --> BM
BM --> BLD[GarrisonLogicDefault<br/>聚合实现]
BLD --> BC
SL --> BC
PL --> SL
TL --> SL
ML --> SL
PWL --> SL
BLD --> BS
BLD --> BFS
BLD --> BCtx
BS --> BD
BLD --> BI
BD --> oxcache[oxcache 0.3<br/>L1 内存 + L2 redis]
BD --> dbnexus[dbnexus 0.4<br/>SQLite / PostgreSQL / MySQL]
```
### trait 职责说明
| `GarrisonCore` | base trait(1 方法) | `GarrisonLogicDefault` |
| `SessionLogic` | 会话逻辑:登录、登出、校验、kickout(13 方法,继承 GarrisonCore) | `GarrisonLogicDefault` |
| `PermissionLogic` | 权限逻辑:check_permission / check_role / has_permission / has_role / get_permission_list / get_role_list(6 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `TokenLogic` | Token 逻辑:check_access_token / check_client_token / check_temp_token / verify_token / refresh_token(5 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `MfaLogic` | MFA 逻辑:二级认证与账号禁用校验(5 async 方法 + 2 关联函数,继承 SessionLogic) | `GarrisonLogicDefault` |
| `PasswordLogic` | 密码逻辑:login_with_password(1 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `GarrisonInterface` | 业务数据源接入点:查询用户权限、角色等 | 业务方必须实现 |
| `GarrisonDao` | 持久化抽象:session CRUD、token 映射 + `RedisDeploymentMode` 配置 | dbnexus + oxcache 实现 |
| `GarrisonContext` | 请求上下文:读取当前 token、请求头、Cookie | axum adapter 实现 |
| `GarrisonPermissionStrategy` | 权限策略:`check_permission` 判定 | 框架提供默认实现 |
| `SessionExpiryListener` | 会话过期回调:会话过期时触发异步回调(0.6.0 新增) | 框架提供默认实现 |
> 所有 trait 采用 **trait + Default 模式**:框架提供默认实现,业务方可覆盖。任何组件都可被替换为自定义实现,框架默认实现仅在未被覆盖时生效。
---
## 四、数据流:请求处理链路
以 axum 集成为例,一个受保护请求的完整处理链路:
```mermaid
sequenceDiagram
participant C as Client
participant AX as axum middleware
participant TL as task_local CURRENT_TOKEN
participant BU as GarrisonUtil
participant BM as GarrisonManager
participant BL as GarrisonLogicDefault
participant BS as GarrisonSession
participant BD as GarrisonDao
participant OC as oxcache (L1 内存 + L2 redis)
participant DB as dbnexus (SQLite / PostgreSQL / MySQL)
C->>AX: HTTP 请求 (Header/Cookie: garrison_token)
AX->>TL: 提取 token, CURRENT_TOKEN.scope(token, fut)
AX->>BU: GarrisonUtil::check_login()
BU->>BM: 委托 GARRISON_MANAGER.logic()
BM->>BL: logic.check_login()
BL->>TL: current_token() 读取 token
TL-->>BL: Some(token)
BL->>BS: session.get_token_session(token)
BS->>BD: dao.get_session(token)
BD->>OC: L1 内存命中?
alt L1 命中
OC-->>BD: 命中返回
else L1 未命中
BD->>OC: L2 redis 查询
OC-->>BD: 返回数据
BD->>OC: 回填 L1 (per-entry TTL)
end
BD-->>BS: TokenSession
BS-->>BL: 会话数据
BL->>BL: 校验超时 / 活跃超时 / 并发策略
alt 校验通过
BL-->>BM: Ok(())
BM-->>BU: Ok
BU-->>AX: 通过
AX-->>C: 200 业务响应
else 校验失败
BL-->>BM: Err(GarrisonError::NotLogin)
BM-->>BU: Err
BU-->>AX: Err 抛出
AX-->>C: 401 / 异常 JSON
end
```
---
## 五、设计决策
### 1. 为什么用 inventory 编译期注册?
**问题**:Rust 无反射,无法在运行时枚举 trait 实现并自动选择。若用运行时注册,需要全局可变状态与锁,增加启动复杂度。
**方案**:
- 使用 `inventory::submit!` 宏在编译期把 `GarrisonLogicFactoryEntry` 注册到全局 link list。
- `GarrisonManager::init()` 启动时遍历 `inventory::iter::<GarrisonLogicFactoryEntry>()`,按 `name` 选定默认实现。
- 优点:**无反射、无运行时开销、跨 crate 注册**,与 feature flag 配合实现按需启用。
### 2. 为什么用 task_local 上下文?
**问题**:async 请求级 token 在 `Arc<dyn GarrisonLogic>` 中无法通过参数传递(trait 方法签名固定),若用 thread_local 则跨 `.await` 不安全。
**方案**:
- `context` 模块定义 `CURRENT_TOKEN: tokio::task_local`。
- axum middleware 在请求入口提取 token 后 `CURRENT_TOKEN.scope(token, fut)` 设置。
- `GarrisonUtil::current_token()` 通过 `CURRENT_TOKEN.get()` 取值,自动落到当前请求作用域。
- 优点:无锁、无穿透、跨 `.await` 安全。
### 3. 为什么用 trait + Default 模式?
**问题**:框架需要提供「开箱即用」的默认行为,同时允许业务方按需替换任一组件。
**方案**:
- 所有核心抽象(`GarrisonCore` + 5 个子 trait / `GarrisonDao` / `GarrisonContext` / `GarrisonPermissionStrategy` / `GarrisonListener`)均以 trait 定义。
- 框架提供默认实现,业务方实现 trait 后通过 `GarrisonManager::init()` 注入即可覆盖。
- 优点:扩展点清晰,符合 Rust 的零成本抽象哲学。
### 4. 为什么用双抽象层(DAO + 缓存)?
**问题**:存储后端多样(SQLite/PostgreSQL/MySQL/Redis),缓存策略多变,业务代码不应感知具体后端。
**方案**:
- `GarrisonDao` trait 定义统一接口(`get_session` / `set_session` / `delete_token` 等),底层由 dbnexus + oxcache 实现。
- `oxcache` 作为缓存抽象,L1 为 oxcache 内存层 LRU,L2 为 redis 分布式,per-entry TTL 精细控制。
- 切换存储后端时仅替换 `GarrisonLogicFactoryEntry` 的实现,**上层零改动**。
### 5. 为什么用 feature 门控?
**问题**:协议/安全/可观测层并非所有项目都需要,强行全量编译会带来依赖膨胀。
**方案**:
- 13 个特性域独立编译,通过 `#[cfg(feature = "...")]` 在编译期裁剪。
- 默认 `default = []`(空),仅核心模块总是编译。
- 聚合特性 `full` / `production` / `development` 一键启用一组特性。
---
## 六、扩展点
### 1. 自定义 GarrisonDao 实现
替换存储后端(如 PostgreSQL / MongoDB / 自研存储):
```rust
#[async_trait]
impl GarrisonDao for MyDao {
async fn get_session(&self, key: &str) -> GarrisonResult<Option<SessionData>> {
// 自定义查询逻辑
}
// ...
}
```
通过 `GarrisonManager::init()` 注入即可,上层业务代码零改动。
### 2. 自定义 GarrisonLogicFactoryEntry
替换核心逻辑(如自定义 token 生成规则、自定义登录策略):
```rust
inventory::submit! {
GarrisonLogicFactoryEntry {
name: "my-logic",
factory: || Arc::new(MyLogic) as Arc<GarrisonLogicDefault>,
}
}
```
### 3. 自定义 GarrisonPermissionStrategy
替换权限策略(如基于 ABAC、基于外部策略引擎):
```rust
#[async_trait]
impl GarrisonPermissionStrategy for MyStrategy {
async fn check_permission(&self, login_id: &str, permission: &str) -> bool {
// 自定义权限判定
}
}
```
---
## 七、参考
- 配置字段说明:[configuration.md](./CONFIGURATION.md)
- 开发规范与 TDD 工作流:[development.md](./DEVELOPMENT.md)
- 版本演进规划:[roadmap.md](./ROADMAP.md)
- 部署指南:[deployment.md](./DEPLOYMENT.md)
- 早期领域建模参考
- specmark specs:`specmark/specs/*`