# ⚙️ Garrison 配置指南
> Garrison 配置由 `GarrisonConfig` 统一管理,支持三级配置源合并与 `tokio::sync::watch` 热更新能力。
>
> - 适用版本:0.9.0-rc.4(核心配置 + JWT / 签名 / SSO / remember-me / Redis 部署模式 / 多租户 / 账号安全引擎 / 微服务架构 / ABAC / OAuth2 Server 等扩展配置;rc.4 起 `rate_limit_backend` 真正驱动限流后端切换)
> - 配置类型:`GarrisonConfig`,实现 `serde::Serialize / Deserialize`
> 架构设计详见 [🏗️ 架构文档](./ARCHITECTURE.md);部署配置详见 [🚀 部署指南](./DEPLOYMENT.md)。
## 📋 目录
- [配置源优先级](#-配置源优先级)
- [完整配置项表](#-完整配置项表)
- [配置文件示例](#-配置文件示例)
- [热更新机制](#-热更新机制)
- [配置校验规则](#-配置校验规则)
---
## 🎯 配置源优先级
<div align="center">
<img src="assets/config-priority.svg" alt="配置优先级" width="800">
</div>
Garrison 配置按以下优先级合并(**高优先级覆盖低优先级**):
```text
环境变量 (GARRISON_*) > toml 文件 (garrison.toml) > 代码默认值 (GarrisonConfig::default_config())
```
| 优先级 | 来源 | 说明 |
|--------|------|------|
| 高 | 环境变量 | 以 `GARRISON_` 前缀 + 字段名大写下划线形式,例如 `GARRISON_TIMEOUT`、`GARRISON_JWT_SECRET` |
| 中 | toml 文件 | 通过 `GarrisonConfig::load(Some(path))` 加载 toml 文件(基于 confers 0.6,文件加载改用 confers `FileSource`——confers 0.6.0-rc.4 起已放行 Windows 盘符前缀,手写的 `TomlContentSource` workaround 已删除) |
| 低 | 代码默认值 | `GarrisonConfig::default_config()` 内联的默认值 |
> 三源合并在 `GarrisonConfig::load()` 阶段完成:先加载 toml(`None` 时使用代码默认值),再由环境变量覆盖,最后 `validate()` 校验。
---
## 📋 完整配置项表
### 2.1 核心配置(0.1.0)
| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `timeout` | `i64` | `2592000` | `GARRISON_TIMEOUT` | 会话超时秒数(默认 30 天,必须 > 0) |
| `active_timeout` | `i64` | `-1` | `GARRISON_ACTIVE_TIMEOUT` | 活跃超时秒数,`-1` 表示不启用(跟随整体会话超时) |
| `is_share` | `bool` | `false` | `GARRISON_IS_SHARE` | 同账号多端是否共享会话 |
| `is_concurrent` | `bool` | `true` | `GARRISON_IS_CONCURRENT` | 是否允许并发登录 |
| `token_name` | `String` | `"garrison_token"` | `GARRISON_TOKEN_NAME` | Cookie / Header 中的 token 字段名 |
| `token_style` | `String` | `"uuid"` | `GARRISON_TOKEN_STYLE` | Token 风格,可选 `uuid` / `random_64` / `simple` / `jwt` |
| `is_read_cookie` | `bool` | `true` | `GARRISON_IS_READ_COOKIE` | 是否从 Cookie 读取 Token |
| `is_read_header` | `bool` | `true` | `GARRISON_IS_READ_HEADER` | 是否从 Header 读取 Token |
| `is_write_header` | `bool` | `true` | `GARRISON_IS_WRITE_HEADER` | 是否在登录后写入 Header |
| `throw_on_not_login` | `bool` | `true` | `GARRISON_THROW_ON_NOT_LOGIN` | 未登录时是否抛出异常(`false` 时返回 `false`) |
| `cookie_secure` | `bool` | `true`(`development` profile 为 `false`) | `GARRISON_COOKIE_SECURE` | Cookie 是否标记 `Secure`(仅 HTTPS 传输);默认随 profile:启用 `development` 聚合特性为 `false`(本地 HTTP 调试),其余为 `true`(rc.4 起,两种 profile 均可显式覆盖) |
| `cookie_same_site` | `String` | `"Lax"` | `GARRISON_COOKIE_SAME_SITE` | Cookie 的 `SameSite` 策略(`Lax` / `Strict` / `None`;`None` 仅在 `cookie_secure=true` 时生效,非 Secure 上下文构建点降级为 `Lax`) |
| `is_read_body` | `bool` | `false` | `GARRISON_IS_READ_BODY` | 是否从请求体读取 Token |
| `is_write_cookie` | `bool` | `false` | `GARRISON_IS_WRITE_COOKIE` | 是否在续签后将新 Token 写入 Cookie |
| `frontend_separation` | `bool` | `false` | `GARRISON_FRONTEND_SEPARATION` | 是否启用前后端分离模式 |
| `session_hover_timeout` | `i64` | `-1` | `GARRISON_SESSION_HOVER_TIMEOUT` | 会话悬停超时秒数(-1 不启用) |
| `auto_renewal_threshold` | `i64` | `-1` | `GARRISON_AUTO_RENEWAL_THRESHOLD` | 自动续签阈值百分比(-1 不启用,0-100) |
| `token_map_cleanup_interval_secs` | `i64` | `300` | `GARRISON_TOKEN_MAP_CLEANUP_INTERVAL_SECS` | token map 清理间隔秒数 |
| `max_login_count` | `u32` | `0` | `GARRISON_MAX_LOGIN_COUNT` | 最大登录数量(0 不限制) |
| `device_binding_mode` | `String` | `"disabled"` | `GARRISON_DEVICE_BINDING_MODE` | 设备绑定模式(`strict` / `loose` / `disabled`) |
| `replaced_login_exit_mode` | `String` | `"old_device"` | `GARRISON_REPLACED_LOGIN_EXIT_MODE` | 顶人下线策略 |
| `overflow_logout_mode` | `String` | `"logout"` | `GARRISON_OVERFLOW_LOGOUT_MODE` | 溢出处理策略 |
| `audit_mask_mode` | `String` | `"partial"` | `GARRISON_AUDIT_MASK_MODE` | 审计日志脱敏模式 |
| `seed_primary_amr` | `bool` | `true` | `GARRISON_SEED_PRIMARY_AMR` | 登录是否向会话播种主认证因子(`amr=["pwd"]` / AAL 1 / `auth_time`)。默认 `true` 保持「login 即主认证」既有契约;**安全敏感部署建议显式 `false`**——凭证委托 / 零凭证 login 路径并未发生密码校验,播种 `pwd` 会向 amr_ledger 与 JWT claim 断言一次从未发生的认证,误导下游 step-up 判定(`assert_freshness` / `ledger_max_aal`)。关闭后会话 `amr_ledger` 为空、`auth_time` 为 `None`、JWT 不携带 `amr`/`auth_time` claim(MFA step-up 追加不受影响) |
| `login_id_max_len` | `u32` | `255` | `GARRISON_LOGIN_ID_MAX_LEN` | stp 登录收口(`login` / `login_with_token` / `login_by_token`)的 login_id 字节长度上限,超限拒绝签发会话;`0` = 框架层不限。HTTP 请求层 `LoginRequest` 反序列化恒按 255 封顶(wire 层不读运行时配置),本配置只可进一步收紧 |
| `require_tenant_bound_jwt` | `bool` | `false` | `GARRISON_REQUIRE_TENANT_BOUND_JWT` | 严格收口:Stateless JWT(`token_style="jwt"` + `jwt_mode=Stateless`)在租户上下文内必须携带签发租户绑定 claim `tid`。默认 `false`——无 `tid` 的存量 token(无租户上下文签发 / 历史签发)放行(向后兼容,绑定语义随 token 自然轮替收敛);`true` 时 `check_login_stateless` 对无 `tid` token 显性拒绝(`stp-check-login-tenant-unbound`),封住存量无绑定 token 不受租户约束的窗口(jti 黑名单跨请求租户命名空间 miss 的吊销逃逸面)。无租户上下文部署不受影响;开启前应确认存量 token 已轮替(或可接受其显性失效)。覆盖范围见下方「租户绑定严格开关覆盖矩阵」:本项仅作用于 Stateless,会话模式由 `require_session_tenant_binding` 覆盖 |
| `require_session_tenant_binding` | `bool` | `false` | `GARRISON_REQUIRE_SESSION_TENANT_BINDING` | 严格收口:会话模式(`jwt_mode=Simple` / `Mixin`)在租户上下文内必须持有会话租户绑定(attr `__garrison_tenant_id`)。默认 `false`——无绑定的存量会话(本字段与绑定机制引入前登录产生,含 `remember_me` 90 天长会话)放行(向后兼容;绑定只在登录时刻写入,存量会话只能靠 TTL 自然过期收敛);`true` 时 `check_login` 对无绑定会话显性报错(`stp-check-login-session-tenant-unbound`),封住旧会话不受租户约束的窗口。无租户上下文部署不受影响;开启前应确认存量无绑定会话已轮替(或可接受其显性失效)。覆盖范围见下方「租户绑定严格开关覆盖矩阵」:本项不覆盖 Stateless(由 `require_tenant_bound_jwt` 覆盖) |
#### 租户绑定严格开关覆盖矩阵
两个开关各覆盖一半,**开启其一不代表全部收紧**:
| `jwt_mode` | token 绑定校验 | 会话绑定校验 |
|---|---|---|
| `Stateless` | `require_tenant_bound_jwt`(读 `tid` claim) | 不适用(无会话存储) |
| `Mixin` | 不校验 `tid`(仅验签) | `require_session_tenant_binding` |
| `Simple` | 不适用 | `require_session_tenant_binding` |
绑定只在登录时刻写入(`create_token_session_inner` 在 `TENANT` 上下文存在时写 attr),框架**不做惰性补绑**——`X-Tenant-Id` 为客户端可控输入,补绑等于把「豁免面」换成「钉定型 DoS」。
### 2.2 扩展配置(0.2.0 新增)
| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `jwt_algorithm` | `String` | `"HS256"` | `GARRISON_JWT_ALGORITHM` | JWT 签名算法,白名单 6 值:`HS256` / `HS384` / `HS512` / `RS256` / `ES256` / `EdDSA`(非对称算法需配套对应私钥 PEM 字段) |
| `jwt_secret` | `String` | `""` | `GARRISON_JWT_SECRET` | JWT 签名密钥(启用 `protocol-jwt` 时必填) |
| `sign_window_seconds` | `i64` | `300` | `GARRISON_SIGN_WINDOW_SECONDS` | API 签名时间窗口(秒),防重放 |
| `sso_ticket_ttl_seconds` | `u64` | `60` | `GARRISON_SSO_TICKET_TTL_SECONDS` | SSO ticket 有效期(秒) |
### 2.3 remember-me 配置(0.6.0 新增)
| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `remember_me_enabled` | `bool` | `false` | `GARRISON_REMEMBER_ME_ENABLED` | 是否启用 remember-me 扩展会话超时 |
| `remember_me_timeout` | `i64` | `7776000`(90 天) | `GARRISON_REMEMBER_ME_TIMEOUT` | remember-me 会话超时秒数(必须 > `timeout`) |
### 2.4 多租户隔离配置(0.5.0 新增)
| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `tenant_isolation.enabled` | `bool` | `false` | `GARRISON_TENANT_ISOLATION__ENABLED` | 是否启用多租户隔离 |
| `tenant_isolation.resolver` | `String` | `"header"` | `GARRISON_TENANT_ISOLATION__RESOLVER` | 租户解析器类型(`header` / `subdomain` / `claim`) |
> 启用后需配合 `tenant-isolation` Cargo feature + `tenant_resolution_middleware` 才能生效。
### 2.5 密码哈希配置(password_hasher)
驱动 `Argon2Hasher` / `BcryptHasher` 的构造参数(`config.password_hasher.build_hasher()` 工厂,产出后经 `with_password_hasher` 注入)。默认值即 OWASP 建议档,选型论证见 [ADR-0001](./adr/0001-argon2id-password-hashing.md)。
| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `password_hasher.algorithm` | `String` | `"argon2id"` | 新哈希算法(`"argon2id"` / `"bcrypt"`);verify 路径按哈希前缀自动识别,不受本字段影响 |
| `password_hasher.argon2_m_cost` | `u32` | `19456` | Argon2id 内存成本(KiB),下限 19456 |
| `password_hasher.argon2_t_cost` | `u32` | `2` | Argon2id 时间成本(迭代次数),下限 1 |
| `password_hasher.argon2_p_cost` | `u32` | `1` | Argon2id 并行度,下限 1 |
| `password_hasher.argon2_pool_size` | `u32` | `1` | Argon2 并发令牌池大小,允许区间 `[1, 256]`;同时执行中的 Argon2 hash/verify 上限,进程内存驻留上界 ≈ `argon2_pool_size × argon2_m_cost` KiB(任何取消时序下不超卖),等待中的调用异步排队不拒绝。默认 1(secure-by-default);bcrypt 不入池(单次执行工作区 KB 级,池化无内存防护收益,CPU DoS 由限流与 cost 校验承担) |
| `password_hasher.bcrypt_cost` | `u32` | `12` | bcrypt cost,允许区间 `[10, 15]` |
| `password_hasher.allow_weak_argon2_params` | `bool` | `false` | 显式风险接受:允许 `argon2_m_cost` 低于 19456(内存受限部署逃生口),放行时输出 warn 日志 |
**校验规则(`validate_core`,fail-closed)**:`algorithm` 白名单外拒绝;Argon2id `m_cost < 19456` 且未显式风险接受拒绝、`t_cost`/`p_cost` 为 0 拒绝、`argon2_pool_size` 越出 `[1, 256]` 拒绝(0 = 零 permit 永久饥饿,fail-fast;256 × 19 MiB ≈ 4.8 GiB 为误配上界);bcrypt cost 越出 `[10, 15]` 拒绝。
**池大小调优**:环境变量 `GARRISON_PASSWORD_HASHER__ARGON2_POOL_SIZE`。容量模型:Argon2id 单次执行驻留内存 ≈ `argon2_m_cost` KiB(默认 19 MiB),`argon2_pool_size = N` 时进程 Argon2 内存上界 ≈ `N × 19 MiB`;**verify 路径的每 permit 驻留上界按存量哈希内嵌 `m_cost` 计(PHC 自描述)**,混合存量部署(新旧参数并存)按 `max(配置 m_cost, 存量 m_cost)` 评估,不能只按配置 `m_cost`;按 `可接受内存预算 ÷ m_cost` 取值,并保持 `pool_size ≤ 登录 QPS 限流阈值`(限流承担 QPS 维度、池承担内存驻留维度,双层防护)。
> 仅影响**新哈希**;存量哈希参数自 PHC 字符串自描述解析(无需迁移即可 verify),参数升级采用"新密码/重登录时重哈希"自然演进。
### 2.6 JWKS 密钥轮换配置
驱动多 kid JWKS 密钥库(`oauth2_server::jwks::JwksKeystore`,注入 `OAuth2State::jwks_keystore` 后生效;单钥静态形态 `jwks_source` 不受本节影响)。钥状态三态:`Active`(签名)/ `Passive`(轮换退役保留验证,仍发布于 JWKS)/ `Disabled`(退役移出发布与验证面)。
| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `jwks_retention_secs` | `u64` | `7200` | Passive 钥退役保留时长(秒):轮换后旧钥转 Passive,超此时长转 `Disabled` 并移出 JWKS 发布面(存量旧 token 验证自此失败,需重新认证)。默认 7200 = 2 × access token TTL(1h),保证轮换前签发的 access token 在整个有效期内仍可验证。同时决定 JWKS 端点 `Cache-Control: max-age`(取 retention 的一半,工程折中非精确安全界) |
**校验规则(`validate`,fail-closed)**:`0` 拒绝(等价于轮换瞬间退役旧钥,存量 token 验证立即中断)。
**调优**:retention 必须 ≥ access token 有效期(否则旧钥退役早于其签发 token 过期,出现验证失败窗口);放宽验证需求(超长 TTL token)按 `2 × 最大 access TTL` 取值。
### 2.7 密码哈希导入约束(R11)
批量导入 / 凭据写入路径的密码哈希校验门 `validate_imported_hash`(白名单 + 参数上限,越界整体拒绝、错误显性)。防止单次登录 OOM / CPU DoS(对齐 zitadel passwap `ValidateEncodedHash` 防御意图)。
| 约束 | 允许值 | 说明 |
|------|--------|------|
| 格式白名单 | `$argon2id$` / `$2b$` / `$2a$` / `$2y$` 前缀 | 白名单外前缀拒绝(`$argon2i$` 等不再接受导入) |
| `ARGON2_IMPORT_MAX_M_COST` | ≤ 1 GiB(`1_048_576` KiB) | Argon2 内存成本上限 |
| `ARGON2_IMPORT_MAX_T` | ≤ 10 | Argon2 迭代次数上限 |
| `ARGON2_IMPORT_MAX_P` | ≤ 4 | Argon2 并行度上限 |
| bcrypt cost | ≤ 15 | 登录期单次 verify 成本上界 |
**登录期惰性升级**:存量低档位哈希在登录 verify 成功后自动重哈希到当前配置档位(走 Argon2 并发令牌池,失败不阻塞登录)——导入约束只把守入口,存量演进靠惰性升级自然收敛。
### 2.8 弃用配置键(R12)
`src/config/deprecation.rs` 注册表(加载期处置:可映射键自动迁移 + warn;不可映射键 0.x warn 放行、**1.0 起一律报错**):
| 弃用键 | since | 迁移目标 | 处置 |
|--------|-------|---------|------|
| `waf_config` | 0.9.0 | (无——能力移除) | 0.x warn 指引;1.0 起加载报错 |
新弃用键随 Breaking 变更逐键登记(每键一条映射/报错测试);不注册虚构键。
### 2.9 字段静态加密(field-encryption,R17)
启用 `field-encryption` feature 后,选定敏感列(`oauth2:atoken:` / `oauth2:rtoken:` / `oauth2:codeused:` / `totp:seed:`)落库自动加密为 `enc:v1:<key_id>:<base64(nonce|ciphertext)>`(AES-256-GCM,AAD 绑定 `garrison:{tenant}:{table}:{key}`)。密钥复用 config-encryption 既有设施(支持多 key_id);**启用 feature 未配密钥 → 启动 fail-closed Err**。读路径兼容明文遗留行(双读迁移期语义),写路径全加密。密钥轮换用 `change_key` / `check_key` 运维接口(garrison-cli 接线见 R16)。
### 2.10 WebAuthn/Passkey 配置(protocol-webauthn,R07)
`protocol::webauthn::WebauthnConfig`(构造后不可变;经 `WebauthnService::new` 注入)。RP 配置不自立配置项,从 issuer 派生:`rp_id` = issuer URL host、`origins` = [issuer](issuer 变更后 rp_id 跟随)。
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `issuer` | `String` | 无(必填) | RP 派生源(如 `https://sso.example.com`);非法 URL 显性拒绝 |
| `challenge_ttl_secs` | `u64` | `120` | 仪式 challenge 暂存 TTL(秒);过期后消费显性拒绝(与重放同错误面) |
| `passwordless.enabled` | `bool` | `false` | Passwordless 用途准入;关闭时该用途的注册/认证显性拒绝 |
| `second_factor.enabled` | `bool` | `false` | 2FA 二次认证用途准入(完整 MFA 编排归 R09);2FA 接线点经 `stp::mfa::webauthn_factor::register_webauthn_factor` 注册 |
**Cargo feature**:`protocol-webauthn`(依赖 webauthn-rs 0.5;其 rustc ≥ 1.88 要求已低于本仓 MSRV 1.97.1,工具链口径见 [DEVELOPMENT.md](DEVELOPMENT.md))。
### 2.11 MFA/step-up 编排配置(mfa,R09)
`GarrisonConfig.mfa`(`MfaConfig`)。chain factor 词汇表:`otp` / `webauthn`(`pwd` 为主因子不进 chain);引用未知 factor 启动期 fail-closed 报错。
```toml
[mfa]
global_chain = ["otp"] # 全局默认链(空 = 不强制 MFA)
recovery_misuse_tolerance = 0 # 恢复码误用豁免额度(默认 0,超限锁定)
[mfa.per_client_chains]
"legacy-client" = [] # 空数组 = 显式禁用(即使全局有默认链)
"admin-console" = ["webauthn"] # 非空 = 强制该集合
```
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `mfa.global_chain` | `Vec<String>` | `[]` | 全局默认强制链;空 = 不强制 |
| `mfa.per_client_chains` | `HashMap<String, Vec<String>>` | `{}` | per-client 覆盖(三态语义见上) |
| `mfa.recovery_misuse_tolerance` | `u32` | `0` | 恢复码连续无效 verify 的豁免次数,超过即锁定(fail-closed,正确码也拒绝) |
### 2.12 找回密码配置(account-password-reset,R14)
`account::password_reset` 模块(feature `account-password-reset`,依赖 protocol-jwt + account-credential + account-policy + email-verification)。行为常量与安全不变式:
| 项 | 默认值 | 说明 |
|----|--------|------|
| 防枚举限流窗口 | 3600 秒 | 每标识的请求计数窗口(与 email-verification 小时窗口同口径);未知标识同路径 dummy 签发,响应外形不可区分 |
| ActionToken TTL | 短时效(构造参数) | `purpose=password_reset` 的自包含 JWT;jti 一次性消费(DAO set_if_absent + 原子消费,并发恰一成功) |
| 密码历史比对 | 与 HistoryRule 硬上限对齐(24 条) | 重置成功追加 `app_password_history`;重用历史密码被拒且 token 不消费 |
| restricted 会话 | `pwdreset_restricted` 标记 | 恢复会话仅可达改密端点(其余 403) |
**运维提示**:`app_password_history` 表随 `016_password_history.sql` 迁移创建;注册/常规改密路径的追加由 host 责任接入(保证「上一代密码」在历史中可查)。
### 2.13 JWT 撤销与限流后端配置(0.9.x 新增)
| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `enable_jwt_revocation` | `bool` | `false` | `GARRISON_ENABLE_JWT_REVOCATION` | 启用 JWT 撤销黑名单:`logout` / `kickout` 时将 `jti` 写入 DAO(TTL = 剩余有效期),`check_login_stateless` 验签后前置检查,已撤销返回 `TokenRevoked`;仅 `protocol-jwt` + `token_style="jwt"` 时生效 |
| `allow_stateless_jwt_no_revocation` | `bool` | `false` | `GARRISON_ALLOW_STATELESS_JWT_NO_REVOCATION` | 显式风险接受:允许 `token_style="jwt"` + `JwtMode::Stateless` + 不启用撤销的组合(不可吊销的永久 JWT 凭证;`jwt_mode` 为代码注入的 `JwtMode` 枚举,非配置字段);正常部署应使用 `enable_jwt_revocation=true` 或 `JwtMode::Mixin` |
| `rate_limit_backend` | `String` | `"memory"` | `GARRISON_RATE_LIMIT_BACKEND` | 限流后端选择(`memory` / `redis`)。**生效面**:登录防火墙 hook(`fw:ip:*` / `fw:acct:*` 计数)与 `RateLimitStrategy`(含 `from_garrison_config` / `with_runtime`);`memory` 跟随主 DAO(进程内 oxcache),`redis` 使用独立 Redis 限流运行时(oxcache `RedisBackend` + limiteron `RedisDistributedLimiter`),会话 / token / geo / device 数据仍走主 DAO。`redis` 需 `rate-limit-redis` feature 与 `GARRISON_REDIS_URL`;启动连接失败拒绝启动(fail-closed),运行期错误向上传播。非 TLS `redis://` 受 oxcache 策略约束:生产用 `rediss://`,开发/测试可设 `OXCACHE_ALLOW_INSECURE_REDIS=I_UNDERSTAND_THE_RISKS`。**未覆盖**:`BruteForceStrategy` 封禁账本、`DDoSStrategy`、OAuth2 `/token` 限流、邀请码防爆破、SMS/email 配额、API Key 锁定、账号锁定、auth_server 边缘 `rate_limit_middleware`(进程内令牌桶)仍按各自后端独立运作 |
---
### 2.14 Refresh Token 重用检测与宽限窗口配置(oauth2-server,R06)
驱动 `RefreshTokenRotation`(`TokenHandler::with_refresh_rotation`)的重用检测与并发双刷容忍。重用三级分类:`RecentPrev`(命中存活链头 parent,回溯 1 跳)/ `OrphanedBranch`(回溯 >1 跳)/ `StaleLineage`(无存活血缘,恒按盗用吊销整条 chain,不受本组配置影响)。三项均从 `garrison.toml` 加载。
| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `recent_reuse_behaviour` | `RecentReuseBehaviour` | `TheftDetected`(toml 值 `theft_detected`) | `RecentPrev` / `OrphanedBranch` 的处置分派:`TheftDetected`(默认,吊销整条 chain + `TokenRevoked`)/ `Unauthorised`(仅拒绝本次请求 401,不吊销 chain);非法值启动期 fail-fast |
| `refresh_grace_period_secs` | `i64` | `0` | 并发双刷宽限窗口秒数(`0` = 关闭)。窗口内已轮换的旧 token 再次呈现时返回轮换签发的既有新 token(不重旋转);兑现凭据进程内暂存不落库,多实例仅签发实例可命中,其余退化为既有重用处置。负值配置校验拒绝 |
| `refresh_grace_max_uses` | `u32` | `1` | 宽限窗口内同一旧 token 的最大兑现次数;预算耗尽后的窗口内重放按 `recent_reuse_behaviour` 处置。仅当 `refresh_grace_period_secs > 0` 时生效;`0` 配置校验拒绝(窗口形同虚设) |
---
## 📝 配置文件示例
### 3.1 `garrison.toml`
在项目根目录创建 `garrison.toml`:
```toml
# Garrison 配置文件
# 详见 docs/CONFIGURATION.md
# 会话策略
timeout = 2592000 # 会话超时 30 天
active_timeout = -1 # -1 表示跟随 timeout
is_share = true # 同账号多端共享会话
is_concurrent = true # 允许并发登录
# Token 策略
token_name = "garrison_token"
token_style = "uuid" # 可选: uuid / random_64 / simple / jwt
is_read_cookie = true
is_read_header = true
is_write_header = true
# 异常行为
throw_on_not_login = true
# Cookie 策略
cookie_secure = true
cookie_same_site = "Lax"
# 0.2.0 扩展(不启用 protocol-* 时可省略)
# jwt_algorithm = "HS256"
# sign_window_seconds = 300
# sso_ticket_ttl_seconds = 60
# 0.6.0 remember-me 扩展会话超时
# remember_me_enabled = false
# remember_me_timeout = 7776000 # 90 天
# 0.5.0 多租户隔离
# [tenant_isolation]
# enabled = false
# resolver = "header"
# 密码哈希参数(默认即 OWASP 建议档,通常无需配置)
# [password_hasher]
# algorithm = "argon2id" # 可选: argon2id / bcrypt
# argon2_m_cost = 19456 # KiB,下限 19456(低于需 allow_weak_argon2_params = true)
# argon2_t_cost = 2
# argon2_p_cost = 1
# argon2_pool_size = 1 # 并发令牌池,区间 [1, 256];内存上界 ≈ pool_size × m_cost
# bcrypt_cost = 12 # 仅 algorithm = "bcrypt" 时生效,区间 [10, 15]
```
### 3.2 环境变量完整列表
通过 `.env` 或容器环境注入(生产环境建议使用容器/编排平台的环境注入):
```env
# 会话策略
GARRISON_TIMEOUT=2592000
GARRISON_ACTIVE_TIMEOUT=-1
GARRISON_IS_SHARE=true
GARRISON_IS_CONCURRENT=true
# Token 策略
GARRISON_TOKEN_NAME=garrison_token
GARRISON_TOKEN_STYLE=uuid
GARRISON_IS_READ_COOKIE=true
GARRISON_IS_READ_HEADER=true
GARRISON_IS_WRITE_HEADER=true
GARRISON_IS_READ_BODY=false
GARRISON_IS_WRITE_COOKIE=false
GARRISON_THROW_ON_NOT_LOGIN=true
# 前后端分离
GARRISON_FRONTEND_SEPARATION=false
# Cookie 策略
GARRISON_COOKIE_SECURE=true
GARRISON_COOKIE_SAME_SITE=Lax
# 0.2.0 扩展
GARRISON_JWT_SECRET=change-me-in-production
GARRISON_JWT_ALGORITHM=HS256
GARRISON_SIGN_WINDOW_SECONDS=300
GARRISON_SSO_TICKET_TTL_SECONDS=60
# 0.6.0 remember-me
GARRISON_REMEMBER_ME_ENABLED=false
GARRISON_REMEMBER_ME_TIMEOUT=7776000
# 0.9.x JWT 撤销与限流后端
GARRISON_ENABLE_JWT_REVOCATION=false
GARRISON_ALLOW_STATELESS_JWT_NO_REVOCATION=false
GARRISON_RATE_LIMIT_BACKEND=memory
# 会话管理
GARRISON_SESSION_HOVER_TIMEOUT=-1
GARRISON_AUTO_RENEWAL_THRESHOLD=-1
GARRISON_TOKEN_MAP_CLEANUP_INTERVAL_SECS=300
GARRISON_MAX_LOGIN_COUNT=0
GARRISON_DEVICE_BINDING_MODE=disabled
# 多租户隔离
GARRISON_TENANT_ISOLATION__ENABLED=false
GARRISON_TENANT_ISOLATION__RESOLVER=header
# 密码哈希(可选)
GARRISON_PASSWORD_HASHER__ARGON2_POOL_SIZE=1
# 数据库与缓存
# 注意:数据库 URL 不走环境变量——框架不读取 GARRISON_DB_URL,须由宿主编程式传入
# garrison::dao::init_dbnexus(&db_url)(CLI 对应 --db-url 参数)。
GARRISON_REDIS_URL=redis://127.0.0.1:6379/0
# 日志
RUST_LOG=garrison=info
```
> 加载顺序提示:`.env` 文件由应用自行选择 `dotenvy` 之类的 crate 加载,Garrison 只读取进程环境变量;`garrison.toml` 与环境变量同时存在时,环境变量优先。
---
## 🔄 热更新机制
Garrison 通过 `tokio::sync::watch` 通道广播配置变更,订阅方收到通知后响应:
### 4.1 工作流程
```mermaid
graph LR
A[ConfigLoader::load] --> B[GarrisonConfig 实例]
B --> C[with_watcher 创建 watch channel]
C --> D[watch::Sender]
D --> E[watch::Receiver]
E --> F[GarrisonManager 订阅]
F --> G[清空权限缓存 / 重建策略]
```
### 4.2 使用示例
```rust
use garrison::config::GarrisonConfig;
// 创建带 watcher 的配置实例
let config = GarrisonConfig::default_config();
// 订阅配置变更
let mut rx = config.watch().expect("default_config 应有 watcher");
// 闭包式修改配置并广播(自动校验)
config.update(|c| {
c.timeout = 3600;
}).unwrap();
// 订阅方接收新配置
let new_config = rx.borrow_and_update();
assert_eq!(new_config.timeout, 3600);
```
### 4.3 热更新语义
| 行为 | 是否影响已存在会话 |
|------|---------------------|
| 修改 `timeout` / `active_timeout` | 否,仅影响后续创建的会话 |
| 修改 `token_style` | 否,已签发 token 不受影响 |
| 修改 `is_share` / `is_concurrent` | 否,仅影响后续登录 |
| 修改 `jwt_algorithm` | 否,已签发 JWT 验签按旧密钥失效后才切换 |
> `update()` 闭包修改后的配置会自动通过 `validate()` 校验,非法值将被拒绝且不广播(no-op)。
---
## ✅ 配置校验规则
`GarrisonConfig::validate()` 会执行字段校验,非法值抛出 `GarrisonError::Config`:
| 字段 | 校验规则 | 错误 i18n key(`GarrisonError::Config`) |
|------|----------|--------------|
| `timeout` | 必须 > 0 | `config-timeout-must-positive::` |
| `token_style` | 必须在 `["uuid", "random_64", "simple", "jwt"]` 内 | `config-unknown-token-style::{值}` |
| `token_style=jwt` | `jwt_secret` 不能为空 | `config-jwt-secret-empty::` |
| `token_style=simple` | `jwt_secret` 长度必须 ≥ 32 字节(simple 风格密钥即 HMAC-SHA256 签名密钥,可离线爆破;原 warn 已升级为启动错误) | `config-jwt-secret-too-short::simple (min 32 bytes)::{长度}` |
| `token_style=jwt`(HS 系)/ `simple` | `jwt_secret` 不得命中弱密钥黑名单(16 条常见弱密钥;剥除首尾填充字符后整串比对、忽略大小写,不做子串匹配,不误伤高熵密钥) | `config-jwt-secret-weak::blacklist hit` |
| `GARRISON_CSRF_ENABLED`(环境变量,`web-csrf`) | 仅接受 `true` / `false`(大小写不敏感),其他取值在配置加载(环境变量覆盖阶段)即失败——原 `"1"`/`"yes"` 等 truthy 习惯值会静默禁用 CSRF 防护 | `config-csrf-enabled-unsupported::{值}` |
| `cookie_same_site` | 必须在 `["Lax", "Strict", "None"]` 内 | `config-unknown-cookie-same-site::{值}` |
| `is_share=true` | 要求 `is_concurrent=true` | `config-is-share-requires-concurrent::` |
| `remember_me_timeout` | `remember_me_enabled=true` 时必须 > `timeout`;`remember_me_enabled=false` 时必须 > 0 | `config-remember-me-timeout-mismatch::{值}::{timeout}` / `config-remember-me-timeout-positive::{值}` |
| `auto_renewal_threshold` | 必须为 `-1` 或 `0..=100` | `config-auto-renewal-threshold-invalid::{值}` |
| `device_binding_mode` | 必须在 `["strict", "loose", "disabled"]` 内 | `config-unknown-device-binding-mode::{值}` |
> 环境变量覆盖后也会触发 `validate()`,非法值(如 `GARRISON_TIMEOUT=not-a-number`)会被拒绝并返回 `GarrisonError::Config`。
### Cookie 写入语义(Set-Cookie 单一构建点)
所有 Set-Cookie 写路径(三框架适配器、续签中间件、CSRF 中间件)统一经 `context::cookie` 构建点产出,属性顺序统一为 `name=value; HttpOnly; [Secure; ]SameSite=<ss>; Path=<p>[; Domain=<d>][; Max-Age=<n>]`:
- **白名单 fail-fast**:`cookie_same_site` 非法值在构建点同样被拒绝(合法值与启动期校验白名单 `COOKIE_SAME_SITE_VALUES` 一一对应,由跨引用测试锁定),拒绝后不产出 Set-Cookie。
- **None→Lax 降级**:`cookie_same_site = "None"` 仅在 `cookie_secure = true` 时生效;`cookie_secure = false`(HTTP 调试)时自动降级为 `Lax` 并输出一次 warn——浏览器拒收不带 Secure 的 `SameSite=None`。
- **production 前缀**:启用 `production` feature 且 `cookie_secure = true` 时 cookie 名强制加前缀——`Path=/` 且无 Domain 的 cookie(会话 token、CSRF cookie)为 `__Host-<name>`,限定路径或带 Domain 的为 `__Secure-<name>`;`cookie_secure = false`(http 降级)不加前缀。框架读写两侧同步解析(读侧统一入口 `token_cookie_name`)。**注意**:升级到带此前缀的版本后,在线用户旧 cookie 失效,需重新登录一次;业务侧自行读取 cookie 的代码需改用同名解析。
### 5.1 Redis 部署模式配置(0.6.0 新增)
`RedisDeploymentMode` 枚举覆盖生产环境常见 Redis 拓扑,通过 `RedisConfig` 聚合结构配置(注意:`RedisConfig` 并非 `GarrisonConfig` 的字段,只能编程式传给缓存构建器 `with_redis_config`;环境变量 `GARRISON_REDIS_URL` 仅作用于限流后端 `rate-limit-redis`,不注入缓存侧 `RedisConfig`):
| 模式 | 字段 | 说明 |
|------|------|------|
| `Single` | `url: String` | 单节点模式(默认 `redis://127.0.0.1:6379`) |
| `Sentinel` | `primary_name: String`, `urls: Vec<String>` | 哨兵模式:通过 Sentinel 集群自动故障转移(配置值仍可用旧键 `master_name`,`#[serde(alias)]` 兼容) |
| `Cluster` | `urls: Vec<String>` | 集群模式:Redis Cluster 分片存储(至少 3 个 primary 节点) |
| `PrimaryReplica` | `primary_url: String`, `replica_urls: Vec<String>` | 主从模式:1 primary + N replica,读分离需客户端支持(配置值仍可用旧变体名 `MasterSlave`,`#[serde(alias)]` 兼容) |
`RedisConfig` 完整字段:`mode`(部署模式)/ `password`(认证密码)/ `db`(数据库编号 0-15)/ `connection_timeout_secs`(默认 5)/ `pool_size`(默认 10)。
> ⚠️ **接线状态如实说明**:当前版本缓存侧 Redis L2 尚未实际接线——`with_redis_config` 仅存储配置并输出一次 warn(`src/dao/oxcache_impl.rs` 的 M4 注记),缓存仍走进程内内存;多实例会话共享当前不可用。上述拓扑结构为接口预留,实际生效待后续版本;当前真实消费 Redis 的是限流后端(`rate-limit-redis`)。
---
## 六、各 Feature 的配置说明
Garrison 通过 feature flag 在编译期裁剪,不同 feature 下需要的配置项不同:
| Feature | 默认 | 关联配置项 |
|---------|------|------------|
| `cache-memory` | 关 | 无(使用 oxcache 内存缓存) |
| `cache-redis` | 关 | 缓存侧 Redis 拓扑编程式经 `RedisConfig` + `with_redis_config` 传入(L2 当前仅存储配置未接线,见 §5.1 注);`GARRISON_REDIS_URL` 属限流后端(`rate-limit-redis`) |
| `db-sqlite` | 关 | SQLite 路径由宿主编程式传给 `garrison::dao::init_dbnexus(&db_url)`(无 `GARRISON_DB_URL` 环境变量) |
| `web-axum` | 关 | 启用 axum extractor / router |
| `protocol-jwt` | 关 | `jwt_algorithm`(`GARRISON_JWT_SECRET` 必填) |
| `protocol-oauth2` | 关 | 需配套 oauth2 client 配置 |
| `protocol-sso` | 关 | `sso_ticket_ttl_seconds` |
| `protocol-sign` | 关 | `sign_window_seconds` |
| `protocol-apikey` | 关 | 由 ApiKey dao 管理;自动启用 `dao-key-index`(使 `list_by_namespace` 生产可用);secret 以 sha256 哈希存储;生产建议配 `cache-redis`(AOF),可选 `firewall-bruteforce` 启用 IP 级失败限速 |
| `protocol-temp` | 关 | 临时 token TTL 由调用方指定 |
| `secure-totp` | 关 | TOTP secret 由用户绑定关系存储 |
| `secure-sign` | 关 | 复用 `sign_window_seconds` |
| `protocol-httpbasic` | 关 | 凭据由调用方提供 |
| `protocol-httpdigest` | 关 | nonce / opaque 由内部生成 |
> **⚠️ Refresh Token 轮换退化行为(`db-sqlite` + `oauth2-server` 部署必读)**
>
> `/oauth2/token` 的 refresh grant 始终可用,但其安全强度取决于是否注入
> `RefreshTokenRotation`(`TokenHandler::with_refresh_rotation`):
>
> - **已注入(推荐)**:hash chain 轮换 + reuse detection——盗用的旧 refresh_token
> 被重放时触发整链撤销,攻击者会话即刻失效。
> - **未注入(退化)**:DAO 键值存储(`oauth2:rtoken:` 前缀),无 reuse detection、
> 无链式撤销——旧 token 重放仅因单次消费失败被拒,**不会触发链式撤销**,同链
> 其他 token 不受影响。
>
> 退化形态在两处显性告警(非静默):`OAuth2State::new` 构造完成时输出一次结构性
> warn;每次退化路径刷新输出请求级 warn(`refresh_token rotation not configured`)。
> 生产部署请注入 rotation 消除告警。未启用 `db-sqlite` 的构建不支持轮换注入,
> refresh grant 恒为退化路径(如无 refresh 需求可忽略)。
### 6.0.1 X-Request-ID 请求标识中间件(R04)
> **头名固定非配置**:`X-Request-ID` / `Retry-After` 为编译期常量
> (`context::request_id::REQUEST_ID_HEADER` / `RETRY_AFTER_HEADER`),
> **不提供配置项**——中间件行为一致性与安全校验规则(长度 ≤128 + 可见 ASCII)
> 不应随部署漂移(见 ADR-0004)。
三框架挂载示例:
```toml
# Cargo.toml
[dependencies]
garrison = { version = "0.9.0-rc.4", features = ["web-axum"] } # 或 web-actix / web-warp
```
```rust,ignore
// axum:middleware::from_fn,建议挂最外层(错误体 request_id 覆盖全部下游错误)
use axum::{routing::get, Router};
let app = Router::new()
.route("/api", get(handler))
.layer(axum::middleware::from_fn(garrison::web::request_id::request_id_middleware));
// actix-web:Transform wrap
use actix_web::App;
let app = App::new().wrap(garrison::web_actix::RequestIdMiddleware);
// warp:wrap_fn 包装(错误体 request_id 走后置回填,见 ADR-0004)
let routes = routes.with(warp::wrap_fn(garrison::web_warp::with_request_id));
```
行为:入站 `X-Request-ID` 合法(非空、≤128 字节、可见 ASCII)则原样回传,
否则丢弃重新生成 UUID v4;所有响应回传 `X-Request-ID` 头,统一错误体携带
`request_id` 字段;handler 经 `Extension<RequestId>`(axum)或 request
extensions(actix)读取;中间件输出结构化日志(span + 事件均含 `request_id`
字段)。错误响应附带 `Retry-After` 头(仅 `GarrisonError::RateLimited`,
delta-seconds 整数秒,下限 1)。
### 6.1 启用 JWT + Redis 的组合示例
```toml
[dependencies]
garrison = {
version = "0.9.0-rc.4",
features = [
"cache-memory",
"cache-redis",
"db-sqlite",
"web-axum",
"protocol-jwt",
],
}
```
并配套 `garrison.toml`:
```toml
jwt_algorithm = "HS256"
```
与 `.env`:
```env
GARRISON_JWT_SECRET=your-256-bit-secret
GARRISON_REDIS_URL=redis://127.0.0.1:6379/0
```
---
## 六点五、serve 子命令环境变量(src/cli/serve.rs,原 auth_server bin)
经 confers 派生宏从 `GARRISON_*` 读取(`#[config(env_prefix = "GARRISON_")]`,字段名大写映射)。容器部署的逐项注意见 [🚀 部署指南 · 运行环境变量(容器)](./DEPLOYMENT.md#运行环境变量容器)。
| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `GARRISON_EXTERNAL_PORT` / `GARRISON_INTERNAL_PORT` | 8080 / 8081 | 外网 / 内网监听端口 |
| `GARRISON_EXTERNAL_BIND` / `GARRISON_INTERNAL_BIND` | **127.0.0.1** | 外网 / 内网绑定地址(secure-by-default,仅本机可达;容器内须设 `0.0.0.0` 才能被端口映射,镜像已内置该 ENV)。仅接受 IPv4/IPv6 字面量,非法值拒绝启动(fail-closed)。缺省回环由 bin 提供——库层 `AuthServerConfig::default()` 仍为 `0.0.0.0` |
| `GARRISON_TRUSTED_PROXIES` | 空(不信任任何 XFF) | 可信代理 IP 列表(逗号分隔)。仅部署在可信反代之后才配置;配置后 XFF 解析(限速键 / 客户端 IP)才启用。仅接受回环 / RFC 1918 / link-local / IPv6 ULA,非法或公网值拒绝启动 |
| `GARRISON_RATE_LIMIT` | 100 | 外网每 IP 限速(必须 > 0,0 拒绝启动) |
| `GARRISON_INTERNAL_API_KEY` | 无(必填) | 内网 API Key,缺失或为空时 fail-closed 拒绝启动;长度下限由库层 `MIN_INTERNAL_API_KEY_LEN`(32 字节)统一强制 |
| `GARRISON_MAX_LOGIN_COUNT` | **10** | 同账号最大并发会话数(超出踢出最早登录的会话);显式传 `0` = 不限制(覆盖框架 `default_config()` 的 `0`) |
| `GARRISON_SEED_PRIMARY_AMR` | **true** | 登录是否向会话播种主认证因子(`amr=["pwd"]` / AAL 1 / `auth_time`)。安全敏感部署建议显式 `false`——参考部署 login 不校验凭证,默认播种会断言一次从未发生的密码认证,误导下游 step-up 判定 |
| `GARRISON_EXTERNAL_LOGIN_ENABLED` | **false** | **是否启用外网登录端点**。框架 login 不校验凭证(职责边界:凭证校验属业务层,框架只签发会话),默认对 `POST /api/v1/auth/login` 返回 404(secure-by-default)。业务方注入凭证校验后才设为 `true`;仅接受 `true`/`false`(大小写不敏感),非法值拒绝启动 |
| `GARRISON_EXTERNAL_LOGIN_ACK` | 无(条件必填) | 开启外网登录且外网绑定为非回环地址时的显式风险确认:取值必须精确为 `i-understand-no-credential-check`,缺失或不匹配拒绝启动(fail-closed) |
| `GARRISON_STRICT_SECURITY` | **true** | 严格安全档:内网 API Key 长度下限(库层 `MIN_INTERNAL_API_KEY_LEN` = 32 字节)与外网登录暴露未 ACK 均在启动期由库层 `AuthServerConfig::validate()` 拒绝(早于建库与迁移)。`false` 仅作为密钥尚未轮换时的一次性逃生阀,同条件降级为库层告警。本路径经 confers 只接受 `true`/`false`(大小写不敏感),非法值拒绝启动(库层 `AuthServerConfig::default()` 读同名变量时语义不同:非法值告警后回退缺省 `false`) |
| `GARRISON_FIELD_ENCRYPTION_KEYS` | 无(`field-encryption` feature 启用时必填) | 落库敏感字段静态加密密钥表(逗号分隔 `key_id:hex64`,hex64 = 32 字节 AES-256 钥材,首项为主钥);feature 启用但未配置即拒绝启动(fail-closed)。garrison-cli 的同名变量用作 `change-key` / `check-key` 的密钥来源 |
| `GARRISON_FIELD_ENCRYPTION_TENANT` | `default` | 字段加密 AAD 租户段 |
| `GARRISON_WORKER_THREADS` | CPU 核数 | Tokio worker 线程数 |
| `GARRISON_MAX_BLOCKING_THREADS` | 512 | Tokio blocking 线程上限 |
对应库级配置:`AuthServerConfig::external_login_enabled`(`with_external_login_enabled(bool)`)。另有库层(`AuthServerConfig` / `GarrisonAuthServer`)读取的 `GARRISON_HEALTH_DETAILS`、`GARRISON_API_KEY_LOCKOUT_THRESHOLD` / `GARRISON_API_KEY_LOCKOUT_WINDOW_SECS`、`GARRISON_RATE_LIMIT_BACKEND`,同样列入上述部署指南表格。
---
## 📚 相关文档
| 文档 | 说明 |
|------|------|
| [🏗️ 架构文档](./ARCHITECTURE.md) | 设计原则与模块划分 |
| [🚀 部署指南](./DEPLOYMENT.md) | 生产部署注意事项 |
| [🛠️ 开发规范](./DEVELOPMENT.md) | TDD 工作流与代码规范 |