# ❓ Garrison FAQ
本文件汇总 Garrison 框架在设计、使用与部署过程中最常被问到的问题。如果你是初次接触 Garrison,建议先阅读本文件再查阅 API 文档。
> 项目仓库:<https://github.com/Kirky-X/garrison>
> 当前版本:0.9.0-rc.4(发布候选,2026-10-20)|下一版本:1.0.0(门禁启动,2027 Q2)
## 📋 目录
- [设计相关](#-设计相关)
- [使用相关](#-使用相关)
- [部署相关](#-部署相关)
---
## 🧭 设计相关
### Q: 为什么采用 13 特性域的领域建模?
A: 认证授权领域边界清晰、职责单一才能做到可组合、可裁剪。Garrison 将认证授权划分为 13 个特性域,每个域边界清晰、API 简洁直观,这种模块化划分非常适合 Rust 生态——用 Rust 的类型系统、所有权与 Feature 门控获得零成本抽象。相比 Actix-Web 的 `actix-identity` 或 `axum-login` 这类只解决单一问题的轻量库,全场景覆盖更符合 Garrison 的"一站式认证授权框架"目标。
### Q: 为什么使用全局单例 `GarrisonManager` 而非依赖注入?
A: 这是 Garrison 在工程便利性与架构纯净之间做出的权衡。全局单例允许我们提供 `GarrisonUtil` 这类静态 API,业务代码无需层层传递 `Arc<Manager>` 即可调用 `login`、`checkPermission` 等方法,大幅降低使用心智成本。同时我们保留了 `GarrisonInterface` trait 抽象,配合 `GarrisonManager::reset_for_test()`(`#[cfg(any(test, feature = "testing"))]` 门控),可以在单元测试中注入 mock 实现而无需引入任何 DI 容器依赖。换言之:**生产用单例取便利,测试用 trait 取可替换**。
### Q: 为什么使用 `inventory` 编译期注册而非运行时反射?
A: Rust 本身没有 Java/C# 那样的运行时反射机制,无法在运行时扫描类型并自动注册。可选方案有 `linkme`(链接期收集)与 `inventory`(编译期分布式切片),二者实现思路相近。Garrison 选择 `inventory` 是因为它:
- 零运行时开销(无 `OnceLock` 初始化抖动);
- 跨 crate 注册(插件 crate 只需 `inventory::submit!` 即可被主框架发现);
- 与 `cargo feature` 门控天然兼容(feature 关闭则对应 submit 宏不编译)。
代价是注册项不能动态卸载,但 Garrison 的插件(Listener、Plugin、Strategy)本就是启动期装配,运行期不可变,因此编译期注册完全够用。
### Q: 为什么默认使用 `oxcache` + `dbnexus` 而非现有 crate?
A: 现有 crate 各有局限:`moka` 不支持 per-entry TTL,`cached` 抽象层级偏底层,`sqlx` 直接耦合数据库连接池而不抽象后端。Garrison 需要的是:
- **统一抽象层**:`GarrisonDao` trait 屏蔽底层差异,业务代码只面向 trait;
- **per-entry TTL**:不同 Token / Session 有不同过期时间,必须支持单条级别过期;
- **与框架设计一致**:`oxcache` 0.5 提供 per-entry TTL 与 layer 抽象,`dbnexus` 0.6 提供 SQLite / PostgreSQL / MySQL 多后端统一接口,二者组合正好覆盖 Garrison 的“内存 + 持久化”两级缓存需求,无需再自行造轮子。
### Q: 为什么不直接用 `jsonwebtoken` 而要包装 `JwtHandler`?
A: 直接使用 `jsonwebtoken` 有三个痛点:
1. Claims 结构由用户自定义,框架无法注入标准字段(如 `sub`、`iss`、`garrison:*` 命名空间字段),导致每次集成都要重复造 claims;
2. 错误类型是 `jsonwebtoken::errors::Error`,与 `GarrisonError` 体系不互通,业务侧需要 `map_err` 转译;
3. 多算法支持、密钥轮换、kid 头部等生产级需求,`jsonwebtoken` 不提供高层 API。
`JwtHandler` 包装层在 `GarrisonJwtClaims` 中预置了框架标准字段,统一错误转换为 `GarrisonError` 的既有变体(无独立的 `Jwt` 变体:验签/解析失败 → `InvalidToken`、过期 → `ExpiredToken`、密钥与算法配置问题 → `Config`、PEM/系统时钟等内部错误 → `Internal`,见 `src/protocol/jwt/handler.rs`),并提供 `sign`/`verify`/`refresh` 一站式 API。业务侧通过自定义自己的 claims 结构并调用 `sign`/`verify` 传入即可扩展自定义字段,无需关心底层算法细节(框架未提供 `GarrisonJwtClaimsExt` 之类的扩展 trait——`GarrisonJwtClaims` 是固定结构体)。
---
## 💻 使用相关
### Q: 如何切换 Token 风格(uuid / random-64 / jwt)?
A: 在 `GarrisonConfig` 中配置 `token_style` 字段即可:
```rust
let mut config = GarrisonConfig::default_config();
config.token_style = "uuid".to_string(); // 32 位 UUID
// config.token_style = "random_64".to_string(); // 64 位随机串
// config.token_style = "jwt".to_string(); // JWT(需启用 protocol-jwt feature)
// 初始化时需注入 dao 与 interface(参见下文「如何自定义权限数据源」)
GarrisonManager::builder()
.dao(dao)
.config(Arc::new(config))
.interface(interface)
.build()
.await?;
```
需要注意:
- `uuid` 与 `random_64` 无需额外 feature;
- `jwt` 风格需要启用 `protocol-jwt` feature(0.2.0 起已支持);
- `token_style` 字段为字符串类型,合法值见 `TOKEN_STYLES` 常量(`uuid` / `random_64` / `simple` / `jwt`);
- 切换风格后,已签发的旧 Token 仍可正常校验,直至其自然过期。
### Q: 如何实现多端登录互踢?
A: 配置 `is_concurrent = false` 即可。Garrison 默认允许多端并发登录(如 Web + App 同时在线),当 `is_concurrent` 关闭时,同一账号在新端登录会自动踢掉旧端会话,旧端下次请求会收到 `NotLoginException`。
```rust
let mut config = GarrisonConfig::default_config();
config.is_concurrent = false;
config.max_login_count = 5; // 可选:同一账号最多保留 5 个活跃 Token,超出按 overflow_logout_mode 处理
```
如需更细粒度控制(如 PC 端互踢但 PC 与 App 共存),可启用 `device-binding` feature(参考 `device_binding_mode` 字段:`strict` / `loose` / `disabled`),按设备维度分别配置绑定策略。
### Q: 如何在非 axum 框架(如 actix-web、warp、自研 HTTP 框架)中使用?
A: Garrison 的核心逻辑与 HTTP 框架解耦,axum 集成只是 `garrison` crate 的 `web-axum` feature。在其他框架中:
```rust
use garrison::stp::with_current_token;
// 1. 在请求中间件中手动设置 task_local
async fn auth_middleware(req: Request, next: Next) -> Response {
let token = req.headers().get("Authorization")
.and_then(|v| v.to_str().ok())
.and_then(|v| v.strip_prefix("Bearer "));
with_current_token(token.unwrap_or("").to_string(), next.run(req)).await
}
// 2. 在 handler 中直接调用 GarrisonUtil
async fn handler() -> &'static str {
GarrisonUtil::check_login(); // 自动从 task_local 取当前 Token
"ok"
}
```
只需实现 `with_current_token` 这一层 task_local 注入即可。Garrison 已提供 `web-actix`、`web-warp` 官方适配 feature(0.4.2 起 ActixContext / WarpContext 4 件套 Extractor 适配)。
### Q: 如何自定义权限数据源(如从 RPC 服务、文件、自研权限中心加载)?
A: 实现 `GarrisonInterface` trait 并在 `GarrisonManager::builder().build().await` 时注入:
```rust
struct MyAuthSource;
#[async_trait]
impl GarrisonInterface for MyAuthSource {
async fn get_permission_list(&self, login_id: &str) -> GarrisonResult<Vec<String>> {
// 从你的权限中心 RPC 拉取
let perms = rpc_client.query_permissions(login_id).await?;
Ok(perms)
}
// 其他方法按需实现
}
let config = Arc::new(GarrisonConfig::default_config());
let interface: Arc<dyn GarrisonInterface> = Arc::new(MyAuthSource);
GarrisonManager::builder()
.dao(dao)
.config(config)
.interface(interface)
.build()
.await?;
```
`GarrisonInterface` 提供 Default 实现(返回空集合),你只需覆写关心的方法。该 trait 对所有方法都返回 `GarrisonResult`,便于把外部错误统一收敛进 `GarrisonError`。
### Q: 如何禁用"未登录抛异常",改为返回 `false` 或自定义错误?
A: 配置 `throw_on_not_login = false`。默认情况下 `GarrisonUtil::check_login` 在未登录时会返回 `Err(GarrisonError::NotLogin)`;关闭后,所有 check 系列方法在未登录时返回 `Ok(false)`,便于业务侧用 `if !GarrisonUtil::check_login().await? { ... }` 的柔和分支。
```rust
let mut config = GarrisonConfig::default_config();
config.throw_on_not_login = false;
```
> 注:当前版本仅有 `throw_on_not_login`,无独立的 `throw_on_not_permission` 字段。`check_permission` 在未登录时与 `check_login` 行为一致(受 `throw_on_not_login` 控制);已登录但无权限时始终返回 `Ok(false)`,不抛异常。
如需自定义错误响应体(而非 `GarrisonError::into_response()` 默认 JSON),可在 axum handler / middleware 中捕获 `GarrisonError` 后自行构造响应,或为自定义错误类型实现 `axum::response::IntoResponse`。
### Q: 如何在测试中重置全局单例 `GarrisonManager`?
A: 调用 `GarrisonManager::reset_for_test()`。该方法经 `#[cfg(any(test, feature = "testing"))]` 门控(`src/manager/impls.rs:89`)——测试构建与启用公开 `testing` feature 的构建中均存在,会中止后台清理任务并清空全局 logic / strategy 引用,使管理器回到未初始化状态(后续需重新 `builder().build()`),便于每个测试用例从干净的初始状态开始:
```rust
#[cfg(test)]
mod tests {
use super::*;
fn setup() {
GarrisonManager::reset_for_test();
// 重新 init 你的测试 config(注入测试 dao / interface)
let config = Arc::new(GarrisonConfig::default_config());
GarrisonManager::builder()
.dao(test_dao())
.config(config)
.interface(test_interface())
.build()
.await.unwrap();
}
#[test]
fn test_login() {
setup();
// ... 测试逻辑
}
}
```
切勿在生产代码中调用此方法——它会无条件清空所有在线会话。该方法由 `#[cfg(any(test, feature = "testing"))]` 门控,因此并非「release 构建中不存在」:显式启用公开 `testing` feature(`Cargo.toml`)的 release 构建同样会编译出该符号。
---
## 🚀 部署相关
### Q: 生产环境应该启用哪些 feature?
A: 推荐使用聚合 feature `production`,它包含以下子特性:
```toml
[dependencies]
garrison = { version = "0.9.0-rc.4", features = ["production"] }
```
`production` 聚合下列 41 个特性(权威列表见 `Cargo.toml` 的 `[features] production`):
- `cache-redis`(Redis 缓存后端,含 `cache-memory`)、`three-tier-cache`(三层缓存架构)、`cache-batch`、`cache-audit`
- `db-postgres`(PostgreSQL 持久化)、`db-sharding`、`db-replica`
- `web-axum`(axum extractor + Router + Interceptor)
- `protocol-jwt`(JWT 签发与验证)、`protocol-sign`(API 签名 + nonce 防重放)、`protocol-webauthn`(WebAuthn / Passkey)、`backchannel-logout`
- `secure-sign`(HMAC 签名工具)、`field-encryption`
- `listener`(事件监听器,用于审计、日志)
- `tracing-log`(追踪日志)、`metrics-prometheus`(Prometheus 指标导出)
- `audit-inklog`(inklog 结构化审计日志)
- `tenant-isolation`(多租户逻辑隔离)
- `security-alert`(安全告警系统)、`session-hijack-detection`、`security-extra`
- `device-binding`(设备绑定策略)
- `mfa-recovery`、`account-password-reset`
- `core-advanced`(决策溯源 / 权限注册表 / forbid 优先语义)
- `firewall-waf`(WAF 请求内容校验)、`firewall-gcra`、`firewall-tower`、`firewall-monitoring`、`firewall-parallel`
- `sms-rate-limit`(SMS 验证码渐进式限速)
- `backend-embedded`(默认嵌入式后端)、`backend-kit`(trait-kit typestate DI 构建)
- `auth-server`(独立 Auth Server 模式)、`auth-server-sdforge`(声明式路由)
- `abac`(基于 Cedar DSL 的属性访问控制引擎)
- `api-docs`、`config-yaml`、`config-distributed`、`config-audit`
> 注意:`email-verification` / `email-verification-smtp` **不在** `production` 聚合内,仅在 `full` 面中提供——邮箱验证码属可选项,需按需显式追加。
如需 OAuth2、SSO 等其他协议层特性,单独追加:
```toml
features = ["production", "protocol-oauth2", "protocol-sso"]
```
若需 OAuth2 Server( authorize / token / revoke / introspect 端点 + PKCE),追加 `oauth2-server`:
```toml
features = ["production", "protocol-oauth2", "oauth2-server"]
```
注意:`default = ["backend-embedded"]`(仅启用嵌入式后端),仅 `cargo build` 不带 `--features` 时只编译核心模块 + 嵌入式后端,便于在无外部依赖的环境(如 Edge、WASM)中使用。
### Q: 是否支持 PostgreSQL / MySQL?
A: **支持。** 0.5.0 起 `dbnexus` 0.4+ 提供 SQLite / PostgreSQL / MySQL 三种后端统一抽象,通过 `db-sqlite` / `db-postgres` / `db-mysql` feature 选择。`production` 聚合 feature 默认使用 `db-postgres`。
- 0.5.0 起 PostgreSQL 后端可用(`db-postgres` feature)
- 0.5.3 起 MySQL 后端可用(`db-mysql` feature)
- 当前 `dbnexus` 已升级至 0.6(参见 `Cargo.toml`)
注意:关系型后端至多启用一个。dbnexus 有两条编译期 `compile_error!` 约束——① 嵌入式(sqlite / duckdb)与服务端(postgres / mysql)不可混用;② 在未启用嵌入式后端时,`postgres` 与 `mysql` 互斥。MySQL 后端的集成测试需要 Docker 环境(使用 `testcontainers`)。
### Q: 是否支持分布式会话?
A: 分两层回答——**分布式限流支持(rc.4 起),分布式会话当前不支持**。
- **限流(支持)**:启用 `rate-limit-redis` 并设 `GARRISON_RATE_LIMIT_BACKEND=redis`、`GARRISON_REDIS_URL=…`,登录防火墙 hook 与 `RateLimitStrategy` 的限流计数落到独立 Redis 运行时,多实例共享计数(覆盖面与故障语义见 [deployment.md](./DEPLOYMENT.md) 的多实例限流章节)。
- **会话 / 权限缓存(不支持)**:会话、token、互踢等运行期状态仍存放在各实例本地的 DAO 与进程内 oxcache。缓存侧的 Redis L2 接口(`cache-redis` 的 `with_redis_config`)当前**仅存储配置、未实际接入 Redis 后端**(见 `src/dao/oxcache_impl.rs` 的 M4 注记),`GARRISON_REDIS_URL` 也不会注入缓存侧——多个 Garrison 实例无法通过共享同一 Redis 构成会话集群。跨实例会话请用 sticky session 或 stateless JWT 方案;整 DAO 切 Redis(候选 A)在 [roadmap](./ROADMAP.md) 中保持 backlog。
`RedisDeploymentMode`(0.6.1 起 Single / Sentinel / Cluster / PrimaryReplica,旧配置值 `MasterSlave` 经 `#[serde(alias)]` 兼容)是缓存侧 `RedisConfig` 的拓扑描述结构,只能编程式经 `with_redis_config` 传入(`GarrisonConfig` **没有** `cache` / `redis` 字段,配置文件无法直接设置):
```rust
use garrison::dao::{RedisConfig, RedisDeploymentMode};
let redis = RedisConfig {
mode: RedisDeploymentMode::Single {
url: "redis://:password@10.0.0.1:6379/0".to_string(),
},
password: None,
db: 0,
connection_timeout_secs: 5,
pool_size: 10,
};
// 交给缓存构建器(with_redis_config),而非塞进 GarrisonConfig
// 注意:当前版本该配置仅被存储(Redis L2 未接线),缓存仍走进程内内存
let dao = build_dao().with_redis_config(redis);
```
注意:单机 `oxcache` 内存模式无法跨实例共享,仅适合单实例部署或开发环境。
### Q: 如何监控框架运行状态(QPS、延迟、失败率、活跃会话数)?
A: 启用 `listener` 与 `metrics-prometheus` feature:
```rust
// Cargo.toml: features = ["listener", "metrics-prometheus"]
let config = Arc::new(GarrisonConfig::default_config());
GarrisonManager::builder()
.dao(dao)
.config(config)
.interface(interface)
.build()
.await?;
```
随后:
- **Listener**:实现 `GarrisonListener` trait,在唯一的 `async fn on_event(&self, event: &GarrisonEvent)` 回调中按 `GarrisonEvent` 变体(31 个,如 `Login` / `Logout` / `Kickout` / `PermissionCheck`)分支处理,打日志或上报到 ELK;
- **Prometheus metrics**:库层不自动挂载任何抓取端点——业务方需自行把 `GarrisonMetrics::gather()`(`metrics-prometheus` feature)暴露为路由(如 axum 下 `Router::new().route("/metrics", get(handler))`,见 mdbook《可观测性 · 指标》)。参考部署 `auth_server` 的指标端点为 `/api/v1/metrics`(`auth-server-sdforge` 的 `#[forge]` 路由 `path = "/metrics"` + `version = "v1"`,经宏自动前缀为 `/api/{version}{path}`),且该端点返回 JSON 序列化字符串而非标准 Prometheus `text/plain`,标准 scraper 无法直接解析。指标集合包含:
- `garrison_login_total{result}`
- `garrison_token_validation_duration_seconds`
- `garrison_permission_query_total`
- `garrison_role_query_total`
0.3.0 起已集成 OpenTelemetry(`otlp` feature),提供分布式追踪能力,便于把 Garrison 内部耗时计入全链路 trace span。
---
> 本 FAQ 随版本迭代持续更新。如果你有未涵盖的问题,欢迎在 [GitHub Discussions](https://github.com/Kirky-X/garrison/discussions) 提问。