garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
<!-- markdownlint-disable MD041 -->
<div align="center">

<img src="docs/assets/garrison.png" alt="Garrison Logo" width="240">

[![Rust 2021](https://img.shields.io/badge/Rust-2021-edded?logo=rust&style=for-the-badge)](https://www.rust-lang.org/) [![Rustc 1.97.1+](https://img.shields.io/badge/rust-1.97.1%2B-orange.svg?style=for-the-badge)](https://www.rust-lang.org/) [![crates.io](https://img.shields.io/crates/v/garrison?style=for-the-badge)](https://crates.io/crates/garrison) [![docs.rs](https://img.shields.io/docsrs/garrison?style=for-the-badge)](https://docs.rs/garrison) [![downloads](https://img.shields.io/crates/d/garrison?style=for-the-badge)](https://crates.io/crates/garrison) [![CI](https://img.shields.io/github/actions/workflow/status/Kirky-X/garrison/ci.yml?branch=main&label=CI&style=for-the-badge)](https://github.com/Kirky-X/garrison/actions/workflows/ci.yml) [![coverage](https://img.shields.io/badge/coverage-95%25%2B-brightgreen.svg?style=for-the-badge)](https://github.com/Kirky-X/garrison) [![license](https://img.shields.io/crates/l/garrison?style=for-the-badge)](LICENSE)

**中文** | [English](README_EN.md)

<b>面向 Rust 生态的一站式身份认证鉴权框架</b>

[✨ 功能特性](#-功能特性) • [🚀 快速开始](#-快速开始) • [📚 文档](#-文档) • [💻 示例](#-示例) • [🤝 参与贡献](#-参与贡献)

</div>

---

<div align="center">

### 🎯 注解声明保护点,静态 API 零状态调用

启动时向 `GarrisonManager` 注入一次依赖,此后从登录到登出交给框架接管:

<table style="width:100%; border-collapse: collapse">
<tr>
<td align="center" width="25%">🧩<br><b>注解驱动</b><br><span style="color:#64748B">13 个属性宏 · 声明式接入</span></td>
<td align="center" width="25%">🔀<br><b>双模会话</b><br><span style="color:#64748B">账号级 · 登录级 · 多端策略</span></td>
<td align="center" width="25%">🌐<br><b>Web 集成</b><br><span style="color:#64748B">axum · actix · warp</span></td>
<td align="center" width="25%">⚙️<br><b>特性门控</b><br><span style="color:#64748B">100+ flag · 按需编译</span></td>
</tr>
</table>

</div>

---

## 📋 目录

<details open>
<summary>📑 目录</summary>

- [✨ 功能特性](#-功能特性)
- [🚀 快速开始](#-快速开始)
- [🎨 特性标志](#-特性标志)
- [📚 文档](#-文档)
- [💻 示例](#-示例)
- [🏗️ 架构](#️-架构)
- [🧪 测试](#-测试)
- [📊 性能](#-性能)
- [🔒 安全](#-安全)
- [🗺️ 开发路线图](#️-开发路线图)
- [🤝 参与贡献](#-参与贡献)
- [📋 更新日志](#-更新日志)
- [📄 许可证](#-许可证)
- [🙏 致谢](#-致谢)
- [📞 联系与支持](#-联系与支持)
- [⭐ Star 历史](#-star-历史)

</details>

---

## ✨ 功能特性

<table style="width:100%; border-collapse: collapse">
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">⚡ <b>零运行时开销</b><br><span style="color:#64748B">编译期 <code>inventory::submit!</code> 工厂注册,无反射、无动态加载</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">🔒 <b>完整鉴权链</b><br><span style="color:#64748B">登录认证 → 权限校验 → 会话管理 → 路由拦截,开箱即用</span></td>
</tr>
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">📦 <b>多后端抽象</b><br><span style="color:#64748B"><code>GarrisonDao</code> + <code>oxcache</code> + <code>dbnexus</code>,切换存储后端零业务代码改动</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">🔧 <b>可插拔扩展</b><br><span style="color:#64748B">trait + Default 实现模式,替换任意组件(DAO / 策略 / 逻辑)无需改业务</span></td>
</tr>
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">🎯 <b>Feature 门控</b><br><span style="color:#64748B">100+ 个特性 flag,按需编译减小体积</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">📊 <b>高可观测</b><br><span style="color:#64748B"><code>tracing</code> 日志 + <code>listener</code> 事件订阅 + <code>prometheus</code> 指标(可选)</span></td>
</tr>
<tr>
<td width="50%" style="vertical-align:top; padding: 12px">🧪 <b>高覆盖</b><br><span style="color:#64748B">5990+ 个测试(lib 约 5454 + 验收/集成/示例约 540),95%+ 行覆盖率,clippy 零警告</span></td>
<td width="50%" style="vertical-align:top; padding: 12px">🌐 <b>Web 框架适配</b><br><span style="color:#64748B">axum/actix/warp 三框架注解式 extractor + 过程宏</span></td>
</tr>
</table>

除上述核心能力外,其余能力(认证协议、防火墙、账号安全、多租户、可观测性、微服务组件等)也均以独立特性标志提供、按需编译;按能力域汇总的功能矩阵见 [🎨 特性标志](#-特性标志) 一节(完整清单以 `Cargo.toml` 的 `[features]` 为准)。

---

## 🚀 快速开始

### 📦 安装

在 `Cargo.toml` 中添加依赖(`development` 聚合 = 内存缓存 DAO + SQLite + axum 适配):

<details>
<summary>📄 代码 · toml</summary>

```toml
[dependencies]
garrison = { version = "0.9", features = ["development"] }
async-trait = "0.1"
tokio = { version = "1", features = ["full"] }
```

</details>

要求 Rust **1.97.1 及以上**(`Cargo.toml` 的 `rust-version = "1.97.1"`):依赖面中的兄弟生态 crate(confers / oxcache / dbnexus / sdforge / limiteron / inklog / trait-kit 的 rc 线)各自声明 `rust-version = "1.97.1"`,这是依赖图可满足的最低工具链,低于该版本 `cargo check` 直接拒绝构建(`rustc ... is not supported by the following packages`);CI 测试矩阵按 `1.97.1`(MSRV 下限)/ `stable` / `beta` 三档显式验证。

> 预发布版本需显式写完整版本号,`"0.9"` 无法匹配 prerelease。如需启用全部协议层与安全模块:`features = ["full"]`。

<details>
<summary>📋 表格</summary>

| 预设 | 安装方式 | 适用场景 |
|------|----------|----------|
| 开发 | `features = ["development"]` | 内存缓存 + SQLite + axum,快速验证 |
| 生产 | `features = ["production"]` | 生产环境推荐组合 |
| 完整 | `features = ["full"]` | 全部能力 |

</details>

### 💡 最小示例

以下示例改编自 [`examples/src/bin/readme_quickstart.rs`](examples/src/bin/readme_quickstart.rs)(完整业务场景:初始化管理器 → 执行登录 → 校验登录状态 → 登出):

<details>
<summary>📄 代码 · rust</summary>

```rust
use std::sync::Arc;
use garrison::prelude::*;
use async_trait::async_trait;

// 1. 业务方实现 GarrisonInterface(提供权限/角色数据)
struct MyInterface;
#[async_trait]
impl GarrisonInterface for MyInterface {
    async fn get_permission_list(&self, _login_id: &str) -> GarrisonResult<Vec<String>> {
        Ok(vec!["user:read".into(), "user:write".into()])
    }
    async fn get_role_list(&self, _login_id: &str) -> GarrisonResult<Vec<String>> {
        Ok(vec!["user".into()])
    }
}

#[tokio::main]
async fn main() -> GarrisonResult<()> {
    // 2. 准备依赖
    let dao: Arc<dyn GarrisonDao> = Arc::new(GarrisonDaoOxcache::new().await?);
    let config = Arc::new(GarrisonConfig::default_config());
    let interface: Arc<dyn GarrisonInterface> = Arc::new(MyInterface);

    // 3. 初始化全局管理器
    GarrisonManager::builder()
        .dao(dao).config(config).interface(interface)
        .build().await?;

    // 4. 在 task_local 上下文中执行登录
    let token = garrison::stp::with_current_token(
        String::new(), GarrisonUtil::login("1001", &LoginParams::default()),
    ).await?;
    println!("登录成功,token = {}", &token[..8.min(token.len())]);

    // 5. 校验登录状态
    garrison::stp::with_current_token(token.clone(), GarrisonUtil::check_login()).await?;

    // 6. 校验权限
    garrison::stp::with_current_token(
        token.clone(), GarrisonUtil::check_permission("user:read"),
    ).await?;

    // 7. 登出
    garrison::stp::with_current_token(token.clone(), GarrisonUtil::logout()).await?;
    Ok(())
}
```

</details>

<details>
<summary>📄 代码 · bash</summary>

```bash
cargo run -p garrison-examples --bin readme_quickstart --features "cache-memory"
# 输出: 登录成功,token = <8 位随机 token 前缀>
```

</details>

> 本示例已由 [examples/tests/readme_quickstart.rs](./examples/tests/readme_quickstart.rs) 持续验证(随 CI 运行),业务代码与 [`examples/src/web/readme_quickstart.rs`](examples/src/web/readme_quickstart.rs) 逐字对应。

### 🧭 核心概念

- **全局单例 + 静态 API**:`GarrisonManager` 启动时一次性注入 dao / config / interface,业务代码经 `GarrisonUtil` 静态 API 零状态调用。
- **token 上下文**:token 经 task_local 上下文(`garrison::stp::with_current_token`)携带,Web 中间件自动绑定,静态 API 自动读取当前 token。
- **双模会话**:Account-Session(账号级)与 Token-Session(登录级)双会话由 `is_share` / `is_concurrent` 控制多端策略。
- **特性门控**:全部可选能力均为独立 feature,编译产物只包含启用的部分。

> token 上下文、双抽象层存储等概念详解见 [📖 用户指南 · 核心概念](docs/USER_GUIDE.md#-核心概念)。

---

## 🎨 特性标志

### 📋 功能矩阵

下表按能力域汇总 `Cargo.toml` 的 `[features]` 主要特性(100+ 个 flag,完整清单以 `Cargo.toml` 的 `[features]` 为准),`default = ["backend-embedded"]`。

<details>
<summary>📋 表格</summary>

<table style="width:100%; border-collapse: collapse">
<tr><th style="text-align:left">特性</th><th style="text-align:center">默认</th><th style="text-align:left">说明</th></tr>
<tr><td><code>backend-embedded</code></td><td align="center">✅</td><td>内嵌后端模式(进程内认证,委托 GarrisonManager)</td></tr>
<tr><td><code>backend-remote</code></td><td align="center">❌</td><td>远程后端适配器(通过 HTTP 调用远程 Auth Server)</td></tr>
<tr><td><code>backend-kit</code></td><td align="center">❌</td><td>trait-kit typestate DI 构建</td></tr>
<tr><td><code>auth-server</code></td><td align="center">❌</td><td>独立认证服务器(sdforge 声明式路由 + TLS)</td></tr>
<tr><td><code>abac</code></td><td align="center">❌</td><td>基于 Cedar DSL 的属性访问控制引擎</td></tr>
<tr><td><code>oauth2-server</code></td><td align="center">❌</td><td>完整 OAuth2 Server 4 端点</td></tr>
<tr><td><code>cache-memory</code></td><td align="center">❌</td><td>内存缓存后端(oxcache 内存层)</td></tr>
<tr><td><code>cache-redis</code></td><td align="center">❌</td><td>Redis 缓存后端(oxcache L2)</td></tr>
<tr><td><code>db-sqlite</code></td><td align="center">❌</td><td>SQLite 数据库后端</td></tr>
<tr><td><code>db-postgres</code></td><td align="center">❌</td><td>PostgreSQL 后端</td></tr>
<tr><td><code>db-mysql</code></td><td align="center">❌</td><td>MySQL 后端</td></tr>
<tr><td><code>web-axum</code></td><td align="center">❌</td><td>axum Web 框架适配</td></tr>
<tr><td><code>web-actix</code></td><td align="center">❌</td><td>actix-web Web 框架适配</td></tr>
<tr><td><code>web-warp</code></td><td align="center">❌</td><td>warp Web 框架适配</td></tr>
<tr><td><code>web-cors</code> / <code>web-csrf</code></td><td align="center">❌</td><td>CORS / CSRF 中间件(WAF 已并入 <code>firewall-waf</code>)</td></tr>
<tr><td><code>protocol-jwt</code></td><td align="center">❌</td><td>JWT 签发与验证(HS256 / HS384 / HS512,另支持 RS / ES / EdDSA 非对称算法 + refresh)</td></tr>
<tr><td><code>protocol-oauth2</code></td><td align="center">❌</td><td>OAuth2 四种模式</td></tr>
<tr><td><code>protocol-sso</code> / <code>protocol-sso-server</code></td><td align="center">❌</td><td>SSO ticket / SSO Server 抽象</td></tr>
<tr><td><code>protocol-sign</code></td><td align="center">❌</td><td>API 签名 + nonce 防重放</td></tr>
<tr><td><code>protocol-apikey</code></td><td align="center">❌</td><td>API Key 认证</td></tr>
<tr><td><code>protocol-temp</code></td><td align="center">❌</td><td>临时凭证</td></tr>
<tr><td><code>protocol-qrlogin</code></td><td align="center">❌</td><td>第一方扫码登录(Web 扫码 + App 确认,两票分离)</td></tr>
<tr><td><code>protocol-oidc</code></td><td align="center">❌</td><td>OIDC id_token 签发/验证 + discovery</td></tr>
<tr><td><code>protocol-invitation</code></td><td align="center">❌</td><td>邀请码定向注册(一次性/N 次、TTL、吊销、防爆破)</td></tr>
<tr><td><code>oauth2-scope-handler</code></td><td align="center">❌</td><td>OAuth2 Scope Handler 注册表(ScopeHandler trait + ScopeRegistry)</td></tr>
<tr><td><code>protocol-httpbasic</code> / <code>protocol-httpdigest</code></td><td align="center">❌</td><td>HTTP Basic / Digest 认证</td></tr>
<tr><td><code>protocol-saml</code></td><td align="center">❌</td><td>SAML 2.0 骨架</td></tr>
<tr><td><code>protocol-zeroize</code></td><td align="center">❌</td><td>协议层密钥零化</td></tr>
<tr><td><code>secure-totp</code></td><td align="center">❌</td><td>TOTP 动态验证码 (RFC 6238)</td></tr>
<tr><td><code>secure-sign</code></td><td align="center">❌</td><td>HMAC-SHA256/SHA512 工具</td></tr>
<tr><td><code>secure-confusable</code> / <code>secure-masking</code> / <code>secure-xss</code> / <code>secure-sanitize</code></td><td align="center">❌</td><td>安全工具集</td></tr>
<tr><td><code>secure-simple-token</code> / <code>secure-ct-eq</code></td><td align="center">❌</td><td>签名 / 常量时间比较</td></tr>
<tr><td><code>account-credential</code> / <code>account-policy</code> / <code>account-lockout</code> / <code>account-authflow</code></td><td align="center">❌</td><td>账号安全引擎</td></tr>
<tr><td><code>firewall</code> / <code>firewall-*</code></td><td align="center">❌</td><td>安全防护套件(暴力破解/限流/异常/GeoIP/DDoS/WAF)</td></tr>
<tr><td><code>listener</code></td><td align="center">❌</td><td>事件监听器(31 个事件变体)</td></tr>
<tr><td><code>tracing-log</code> / <code>metrics-prometheus</code> / <code>otlp</code></td><td align="center">❌</td><td>可观测性</td></tr>
<tr><td><code>annotation-macros</code></td><td align="center">❌</td><td>13 个属性宏</td></tr>
<tr><td><code>tenant-isolation</code></td><td align="center">❌</td><td>多租户逻辑隔离</td></tr>
<tr><td><code>social-wechat</code> / <code>social-alipay</code></td><td align="center">❌</td><td>社交登录</td></tr>
<tr><td><code>core-advanced</code> / <code>session-extra</code></td><td align="center">❌</td><td>核心增强 / 会话增强合并</td></tr>
<tr><td><code>email-verification</code> / <code>email-verification-smtp</code></td><td align="center">❌</td><td>邮箱验证码</td></tr>
<tr><td><code>config-*</code></td><td align="center">❌</td><td>配置文件加密/校验/热更新/插值/动态/开关(confers 透传)</td></tr>
<tr><td><code>i18n-icu</code></td><td align="center">❌</td><td>国际化(基础 i18n 层无需 feature,ICU 集成按此门控)</td></tr>
<tr><td><code>protocol-webauthn</code></td><td align="center">❌</td><td>WebAuthn / Passkey 凭据注册与认证仪式(challenge 防重放 / sign_count 克隆检测)</td></tr>
<tr><td><code>backchannel-logout</code></td><td align="center">❌</td><td>OIDC Back-Channel Logout(logout token 签发 + 持久化投递队列)</td></tr>
<tr><td><code>keycloak-oidc</code></td><td align="center">❌</td><td>Keycloak OIDC 依赖方(RP)集成</td></tr>
<tr><td><code>field-encryption</code></td><td align="center">❌</td><td>落库敏感字段 AES-256-GCM 静态加密(AAD 租户/表/键绑定 + 迁移期双读)</td></tr>
<tr><td><code>mfa-recovery</code></td><td align="center">❌</td><td>MFA 恢复码管理器(SHA-256 哈希落库 + 原子消费)</td></tr>
<tr><td><code>account-password-reset</code></td><td align="center">❌</td><td>找回密码流程(防枚举 / ActionToken 一次性消费 / 两段式防竞态)</td></tr>
<tr><td><code>policy-hibp</code></td><td align="center">❌</td><td>HIBP 泄露密码检查(k-anonymity range search)</td></tr>
<tr><td><code>credential-zeroize</code></td><td align="center">❌</td><td>凭据密钥零化(Drop 清零)</td></tr>
<tr><td><code>tls</code></td><td align="center">❌</td><td>HTTPS/TLS 终止(axum-server + rustls)</td></tr>
<tr><td><code>tls-cert-watch</code></td><td align="center">❌</td><td>TLS 证书进程内热重载(换证不重启进程,两端口新握手同时生效)</td></tr>
<tr><td><code>server-health-check</code> / <code>server-graceful-shutdown</code></td><td align="center">❌</td><td>健康/就绪探针 / 优雅停机</td></tr>
<tr><td><code>web-security</code> / <code>web-security-headers</code></td><td align="center">❌</td><td>Web 安全中间件聚合(CORS+CSRF+响应头)/ 独立安全响应头</td></tr>
<tr><td><code>cache-lock</code> / <code>cache-batch</code> / <code>cache-invalidation</code> / <code>cache-audit</code> / <code>cache-hotkey</code> / <code>ban-sync</code></td><td align="center">❌</td><td>缓存增强:分布式锁 / 批量 / 跨实例失效 / 审计事件流 / 热 key 观测 / 封禁同步(oxcache 透传)</td></tr>
<tr><td><code>db-retry</code> / <code>db-sharding</code> / <code>db-replica</code> / <code>db-saga</code></td><td align="center">❌</td><td>数据库增强:重试 / 分片 / 读写分离 / Saga(dbnexus 透传)</td></tr>
<tr><td><code>three-tier-cache</code></td><td align="center">❌</td><td>三层缓存架构(L1 本地 + L2 redis + DB)</td></tr>
<tr><td><code>security-alert</code> / <code>device-binding</code> / <code>session-hijack-detection</code></td><td align="center">❌</td><td>安全告警系统 / 设备绑定 / 会话劫持检测</td></tr>
<tr><td><code>grpc</code></td><td align="center">❌</td><td>gRPC async 鉴权层(tonic 拦截器)</td></tr>
<tr><td><code>credit-metering</code></td><td align="center">❌</td><td>信用/配额计量(活跃度写路径节流聚合)</td></tr>
<tr><td><code>audit-log</code></td><td align="center">❌</td><td>审计日志(落库 + HMAC 防篡改事件链)</td></tr>
<tr><td><code>audit-inklog</code> / <code>audit-inklog-http</code> / <code>audit-inklog-siem</code></td><td align="center">❌</td><td>inklog 结构化审计日志 / HTTP / SIEM 外送</td></tr>
<tr><td><code>alone-cache</code> / <code>parameter-query</code></td><td align="center">❌</td><td>DAO 单飞缓存(防击穿)/ STP 参数化查询</td></tr>
<tr><td><code>api-docs</code> / <code>cli-ops</code></td><td align="center">❌</td><td>OpenAPI 文档 / 运维子命令(garrison 单根二进制)</td></tr>
<tr><td><code>data-erasure</code></td><td align="center">❌</td><td>数据主体擦除编排(GDPR / 个保法删除权)</td></tr>
<tr><td><code>authorize-api</code> / <code>manager-explicit</code></td><td align="center">❌</td><td>核心扩展:请求对象式授权 API / 显式 Manager API</td></tr>
<tr><td><code>miette</code> / <code>embedded-migrations</code></td><td align="center">❌</td><td>富诊断错误(miette::Diagnostic)/ 嵌入式迁移文件</td></tr>
<tr><td><code>full</code> / <code>production</code> / <code>development</code></td><td align="center">❌</td><td>聚合特性</td></tr>
</table>

</details>

> **v0.9.0 Feature 改名映射**:
>
> | 旧名称 (≤0.8.x) | 新名称 (≥0.9.0) | 说明 |
> |-----------------|-----------------|------|
> | `secure-saml` | `protocol-saml` | SAML 2.0 签名验证 |
> | `secure-httpbasic` | `protocol-httpbasic` | HTTP Basic 认证 |
> | `secure-httpdigest` | `protocol-httpdigest` | HTTP Digest 认证 |
> | `observability-otlp` | `otlp` | OpenTelemetry OTLP |
> | `decision-trace` / `permission-registry` / `safe-defaults` | `core-advanced` | 核心增强合并 |
> | `dynamic-active-timeout` / `login-token-map-persistence` / `anonymous-session` / `session-search` | `session-extra` | 会话增强合并 |

---

## 📚 文档

<details>
<summary>📋 表格</summary>

| 文档 | 说明 |
|------|------|
| [📖 用户指南](docs/USER_GUIDE.md) | 从安装到进阶的完整使用教程 |
| [📘 API 参考](docs/API_REFERENCE.md) | 公开 API 与模块参考 |
| [🏗️ 架构文档](docs/ARCHITECTURE.md) | 设计原则、模块划分与数据流 |
| [⚙️ 配置指南](docs/CONFIGURATION.md) | 三级配置源、完整配置项与热更新 |
| [⚡ 性能指南](docs/PERFORMANCE.md) | 性能目标、基准测试与优化建议 |
| [🧱 API 稳定性分级](docs/API_STABILITY.md) | v1.0 稳定性层级、冻结清单与公共面基线 |
| [🏭 参考生产案例](docs/PRODUCTION_CASES.md) | 自托管参考部署案例与提交模板 |
| [🔎 安全审计就绪包](docs/SECURITY_AUDIT.md) | 审计范围、证据矩阵与第三方 RFP 清单 |
| [🧪 测试场景矩阵](docs/TEST_SCENARIOS.md) | 验收场景穷举、特性组合矩阵与质量门禁 |
| [🔒 安全文档](SECURITY.md) | 安全策略、漏洞报告流程 |
| [🛡️ 威胁模型](docs/THREAT.md) | STRIDE 分析、框架防御与业务方责任边界 |
| [❓ FAQ](docs/FAQ.md) | 常见问题解答 |
| [🔧 问题排查](docs/TROUBLESHOOTING.md) | 常见问题与解决方案 |
| [🛠️ 开发规范](docs/DEVELOPMENT.md) | TDD 工作流、代码规范与调试技巧 |
| [🚀 部署指南](docs/DEPLOYMENT.md) | 生产部署注意事项 |
| [🗺️ 路线图](docs/ROADMAP.md) | 版本演进规划 |
| [📦 发布工作流](docs/RELEASING.md) | 版本发布流程与门禁 |
| [🤝 贡献指南](docs/CONTRIBUTING.md) | 如何参与项目开发 |
| [📋 更新日志](docs/CHANGELOG.md) | 每个版本的变更记录 |
| [📦 在线 API 文档](https://docs.rs/garrison) | docs.rs 自动生成的最新文档 |
| [📦 crates.io](https://crates.io/crates/garrison) | 发布页面 |

</details>

---

## 💻 示例

全部 65 个可运行示例位于 [`examples/`](examples/) 目录(独立 workspace member,`garrison-examples` crate),每个示例配套 1:1 独立测试,按「登录 / 会话 / Token 基础、注解与 Web 集成、认证协议、安全防护、可观测性与基础设施」等主题分组,完整清单与各示例所需 feature 见 [examples/README.md](examples/README.md)。

<details>
<summary>📄 代码 · bash</summary>

```bash
# 运行单个示例
cargo run -p garrison-examples --bin basic_login --features full

# 验证全部示例可编译
cargo build -p garrison-examples --features full
```

</details>

---

## 🏗️ 架构

Garrison 采用**双抽象层 + 全局单例**架构:`GarrisonDao` trait 统一屏蔽 `dbnexus`(SQLite / PostgreSQL / MySQL)+ `oxcache`(L1 内存 / L2 redis)存储后端差异,核心模块 always on、可选能力(`protocol-*`、`secure-*`、`firewall-*`、`account-*`、`web-*` 等)按 feature 独立门控,核心数据通路为「业务代码 → `GarrisonUtil` → `GarrisonManager` 单例 → `GarrisonLogicDefault` → `GarrisonDao` / `GarrisonPermissionStrategy` → 存储后端」。

模块分层、trait 关系与请求处理数据流的完整说明见 [🏗️ 架构文档](docs/ARCHITECTURE.md)。

---

## 🧪 测试

### 🎯 测试策略

测试按「单元(`src/` 内联 `#[cfg(test)]`)→ 验收 / 集成(`tests/acceptance/` 按域组织 + db 专用 target + trybuild UI 测试)→ 示例级集成(`examples/tests/` 与示例 bin 一一对应)」三层组织,另有 Criterion 基准、文档测试与特性组合编译矩阵(`ci.yml` test-compile-guard + 每周 `feature-matrix.yml`)。场景穷举、真实服务矩阵(Redis / PostgreSQL / MySQL / Keycloak 26 / HIBP)与特性依赖分析见 [🧪 测试场景矩阵](docs/TEST_SCENARIOS.md)。

### ▶️ 运行命令(与 CI 一致)

<details>
<summary>📄 代码 · bash</summary>

```bash
# 单元测试(CI test job 的两种特性面)
cargo test --no-default-features --features "default" --lib --locked
cargo test --features "full" --lib --locked

# 验收 / 集成测试(CI integration-test job;services 含 Redis 与 PostgreSQL)
cargo test --features "full" --tests --no-fail-fast

# 验收矩阵(full + testing 特性面)
cargo test --test acceptance --features "full testing"

# 性能基线(concurrency 域 #[ignore] 的 perf_* 用例)
cargo test --test acceptance --features "full testing" perf_ -- \
    --nocapture --test-threads=1 --ignored

# 文档测试(CI Linux/MSRV 腿)
cargo test --features "full" --doc --locked

# 一键 E2E(auth_server_serve 冒烟 + 全量验收 + 性能基线 + 报告聚合)
bash scripts/e2e_run.sh
# 本地全量流水线(compose 真服务自举 + 静态门禁 + 全部测试 + 特性矩阵 + 基准)
bash scripts/e2e_matrix.sh

# Lint 与格式门禁
cargo clippy --no-default-features --features "default" -- -D warnings
cargo clippy --features "full" -- -D warnings
cargo fmt --all -- --check

# 覆盖率门禁:行覆盖率不低于 95%
cargo llvm-cov --features "full" --fail-under-lines 95

# 依赖安全门禁
cargo deny --all-features --locked check

# 基准测试(--bench 限定 criterion 目标,避免连带 lib unittest)
cargo bench --bench garrison_benchmark --features full --locked -- --quick
```

</details>

> 构建依赖:`protoc`(sdforge build script 需要,CI 经 taiki-e/install-action 安装)。

### 📊 测试规模

约 5994 个测试(lib 单元 5454 + 验收 / 集成 416 + 示例级 116 + 过程宏 8;lib 与验收数为 `cargo test --list` 实测,示例与过程宏为属性静态计数,截至 2026-10-28)与 6 个 Criterion 基准场景;覆盖率门禁为行覆盖率不低于 95%(2026-10-14 实测约 95.15%)。统计口径与明细见 [🧪 测试场景矩阵 · 测试规模统计](docs/TEST_SCENARIOS.md#-测试规模统计)。

---

## 📊 性能

基准场景与目标定义于 [`benches/garrison_benchmark.rs`](benches/garrison_benchmark.rs)(`login_flow` / `token_verify_stateless` / `permission_check` / `oxcache_backend_switch` / `convert_placeholders` / `circuit_execute_closed_passthrough` 六个 Criterion 场景),以 `cargo bench` 在本机复现;验收层另有 HTTP 性能基线(P99 < 200ms / 1000 RPS),经 `scripts/e2e_run.sh` 采集并聚合报告。性能设计要点(单例无锁化、慢哈希 `spawn_blocking` 下沉、请求内快照复用、缓存 TTL 抖动、全量 feature 门控)与逐项优化建议见 [⚡ 性能指南](docs/PERFORMANCE.md)。

---

## 🔒 安全

### 🛡️ 安全设计

Garrison 围绕身份认证全生命周期做纵深防护:Argon2id / Bcrypt 慢哈希经 `spawn_blocking` 下沉、Token 常量时间比较(`secure-ct-eq`,CWE-208)、API Key 哈希存储与 IP 级限速(CWE-916 / CWE-307)、多租户 IDOR 防护、审计事件 token 统一掩码(CWE-532)、外网登录端点 fail-closed 等。逐项机制的代码级细节见 [🏗️ 架构文档](docs/ARCHITECTURE.md) 与 [📖 用户指南 · 安全与防护](docs/USER_GUIDE.md),安全配置最佳实践与漏洞处理流程见 [🔒 安全文档](SECURITY.md)。

### ⛓️ 供应链与门禁

CI 与发布流程内置两道供应链门禁:`cargo deny check`(RustSec 公告 / 许可证 / 禁用依赖 / 来源校验,`ci.yml` 与 `release.yml` 均执行)与 gitleaks 私钥扫描(pre-commit 覆盖 staged,CI 全量 git history)。`cargo audit` 不在 CI 中——cargo-deny 已覆盖同等漏洞检查,避免维护两份忽略列表;它仅作为本地发布 precheck 由 `scripts/release.sh` 执行。门禁标准与处置细节见 [🔒 安全文档 · 供应链与门禁](SECURITY.md)。

### 🚨 报告安全漏洞

请勿通过公开 issue 报告安全漏洞。请优先使用 GitHub [Security Advisories](https://github.com/Kirky-X/garrison/security/policy) 私密披露通道提交报告(不可用时再发送邮件至 <Kirky-X@outlook.com>,受理人 Kirky.X)。项目承诺 48 小时内确认、7 天内给出初步评估。完整政策见 [SECURITY.md](SECURITY.md)。

---

## 🗺️ 开发路线图

<details>
<summary>📋 表格</summary>

<table style="width:100%; border-collapse: collapse">
<tr><th style="text-align:center">状态</th><th style="text-align:left">方向</th><th style="text-align:left">条目</th></tr>
<tr><td align="center">✅</td><td>核心引擎</td><td>登录认证 + 权限校验 + 双模会话 + axum/actix/warp 适配</td></tr>
<tr><td align="center">✅</td><td>协议层</td><td>JWT / OAuth2 / SSO / OIDC / SAML 2.0 / API Key / TOTP / Basic / Digest / Sign</td></tr>
<tr><td align="center">✅</td><td>安全与防护</td><td>账号安全引擎 / 安全防护套件 / 防火墙 / 多租户 / 审计日志</td></tr>
<tr><td align="center">✅</td><td>微服务架构</td><td>backend-remote / Auth Server / ABAC / OAuth2 Server / gRPC</td></tr>
<tr><td align="center">✅</td><td>可观测性</td><td>tracing / metrics-prometheus / OTLP / i18n</td></tr>
<tr><td align="center">✅</td><td>安全加固(已落地,随下一版本发布)</td><td>外网登录端点暴露确认 fail-closed、密码登录时序侧信道对齐、OAuth2 password grant 限流 fail-closed、JWT 黑名单写失败重试、SAML Destination/Audience 缺省 strict、SSO secret ≥32 字节 + pub/sub 消息 HMAC 信封、check_safe/check_disable 会话前置校验、多租户隔离强化(会话-租户绑定 / 标识符注册表 / 设备接口)。作用域提示:绑定地址缺省收敛 127.0.0.1 与内网 API Key 强制 ≥32 字节仅约束参考部署 <code>auth_server</code> bin,库层 <code>AuthServerConfig</code> 默认仍为 0.0.0.0 且只拒绝空 Key,须自行显式收口(见 [docs/CHANGELOG.md](docs/CHANGELOG.md) · 0.9.0-rc.3)</td></tr>
<tr><td align="center">📋</td><td>v1.0.0 稳定版</td><td>API 冻结 + 性能基准 + 生产案例</td></tr>
</table>

</details>

完整规划见 [docs/ROADMAP.md](./docs/ROADMAP.md)。

---

## 🤝 参与贡献

详细的贡献流程与代码规范请参阅 [🤝 贡献指南](docs/CONTRIBUTING.md)。

### 🛠️ 开发环境

工具链为 Rust 1.97.1+(兄弟生态依赖 rc 线要求 ≥ 1.97.1;CI 按 `1.97.1` / `stable` / `beta` 三档矩阵显式验证);提交前运行 `cargo fmt --all -- --check` 与 `cargo clippy --features full --lib --tests -- -D warnings`(不可用 `--all-features`:它同时启用 db-sqlite 与 db-postgres,而 dbnexus 禁止 embedded×server-side 驱动共存,必然 compile_error);提交信息遵循 Conventional Commits(`feat`、`fix`、`docs` 等)。完整环境搭建步骤见 [🤝 贡献指南 · 开发环境搭建](docs/CONTRIBUTING.md#-开发环境搭建)。

### 💖 贡献方式

<table style="width:100%; border-collapse: collapse">
<tr>
<td width="33%" align="center" style="padding: 16px">

### 🐛 报告 Bug

发现问题?<br>
<a href="https://github.com/Kirky-X/garrison/issues/new">创建 Issue</a>

</td>
<td width="33%" align="center" style="padding: 16px">

### 💡 功能建议

有好想法?<br>
<a href="https://github.com/Kirky-X/garrison/issues/new?template=feature_request.md">提交功能建议</a>

</td>
<td width="33%" align="center" style="padding: 16px">

### 🔧 提交 PR

想贡献代码?<br>
<a href="https://github.com/Kirky-X/garrison/pulls">Fork 并提交 PR</a>

</td>
</tr>
</table>

---

## 📋 更新日志

完整版本历史见 [📋 更新日志](docs/CHANGELOG.md)(遵循 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) 格式,语义化版本)。

<details>
<summary>📋 表格</summary>

| 版本 | 日期 | 要点 |
|------|------|------|
| 0.9.0 | 2026-11-14 | 正式版定版:自研依赖面转稳定线(confers 0.6 / trait-kit 0.5 / oxcache 0.5 / dbnexus 0.6 / inklog 0.3 / sdforge 0.5 / limiteron 0.3)、i18n 归一 trait-kit 供给、单根 garrison 二进制、CI 供应链告警清零 |
| 0.9.0-rc.3 | 2026-10-14 | 安全审计整改 R01–R18:统一错误模型(request-id / Retry-After)/ 字段静态加密 / WebAuthn / 密码找回 / MFA 编排 / back-channel logout / 多租户强化 / garrison-cli |
| 0.9.0-rc.2 | 2026-08-26 | fail-closed 安全加固(check_api_key / check_abac) |
| 0.9.0-rc.1 | 2026-08-25 | 验收测试体系 + DAO 原子契约收严 + gRPC async 鉴权层 |
| 0.8.1 | 2026-07-24 | 审计日志 token 泄漏修复(CWE-532) |

</details>

---

## 📄 许可证

本项目基于 [Apache-2.0](LICENSE) 许可证开源。为何选择 Apache-2.0 而非 MIT:Apache-2.0 包含专利授权条款,更适合企业级框架使用。

---

## 🙏 致谢

### 🌟 核心依赖

Garrison 站在以下优秀开源项目的肩膀上:

<details>
<summary>📋 表格</summary>

| 依赖 | 用途 |
|------|------|
| [axum](https://github.com/tokio-rs/axum) | tokio 团队出品的 Rust Web 框架 |
| [oxcache](https://github.com/Kirky-X/oxcache) | Rust 多级缓存库(L1 内存 + L2 redis) |
| [dbnexus](https://github.com/Kirky-X/dbnexus) | Rust 数据库抽象层(SQLite / PostgreSQL / MySQL) |
| [inventory](https://github.com/dtolnay/inventory) | David Tolnay 的编译期插件注册库 |
| [confers](https://github.com/Kirky-X/confers) | Rust 配置管理库(零样板代码) |
| [sdforge](https://github.com/Kirky-X/sdforge) | 声明式 Web 框架 |
| [trait-kit](https://github.com/Kirky-X/trait-kit) | trait 工具集 |

</details>

### 💝 特别感谢

- 感谢 Rust 社区与所有 [贡献者](https://github.com/Kirky-X/garrison/graphs/contributors)

---

## 📞 联系与支持

<table style="width:100%; max-width: 600px">
<tr>
<td align="center" width="33%">
<a href="https://github.com/Kirky-X/garrison/issues"><b style="color:#991B1B">Issues</b></a><br>
<span style="color:#64748B">报告问题和 Bug</span>
</td>
<td align="center" width="33%">
<a href="docs/FAQ.md"><b style="color:#1E40AF">FAQ</b></a><br>
<span style="color:#64748B">常见问题解答</span>
</td>
<td align="center" width="33%">
<a href="https://github.com/Kirky-X/garrison"><b style="color:#1E293B">GitHub</b></a><br>
<span style="color:#64748B">查看源代码</span>
</td>
</tr>
</table>

---

## ⭐ Star 历史

[![Star History Chart](https://api.star-history.com/svg?repos=Kirky-X/garrison&type=Date)](https://star-history.com/#Kirky-X/garrison&Date)

如果这个项目对您有帮助,请考虑给它一个 ⭐️!

<b>由 Kirky.X 构建</b>

---

<sub>© 2026 Kirky.X. 保留所有权利。</sub>