flowchart LR
  C[Client] -->|HTTP + JSON| R[Axum Router]
  R --> A[认证中间件 authenticate]
  A --> M[租户中间件 resolve_tenant]
  M --> H[Handlers + RBAC 校验]
  H --> S[Services]
  S --> DB[(PostgreSQL)]

  H --> O[统一错误 AppError]
  R --> D[OpenAPI/Scalar /scalar]

多租户实现方式

当前采用“共享数据库 + 共享表，通过 tenant_id 区分”的模式：

users.tenant_id 外键引用 tenants.id（强制用户必须归属某个租户）
users(tenant_id, email) 联合唯一索引（同租户邮箱唯一，不同租户可重复）
HTTP 层优先通过 Authorization: Bearer <access_token> 中的 tenant_id claim 传入租户上下文，并在 Service/SQL 查询中使用 tenant_id 过滤
兼容：仍支持请求头 X-Tenant-ID: <uuid>，若同时提供 Header 与 Token，将强制校验两者一致，否则返回 403

项目结构说明

src/main.rs：服务入口、路由组装、Telemetry 初始化、DB 连接池初始化
src/config/mod.rs：环境变量配置加载
src/db/mod.rs：PostgreSQL 连接池初始化（迁移功能目前未启用）
src/middleware/mod.rs：多租户中间件与 TenantId 提取器
src/middleware/auth.rs：JWT 认证中间件与 AuthContext 提取器
src/handlers/mod.rs：HTTP Handler（控制器层），负责参数解析、调用 Service、返回统一响应
src/services/mod.rs：业务逻辑（注册/登录）与数据库交互
src/models.rs：DB Model 与请求/响应 DTO（同时用于 OpenAPI Schema）
src/utils/mod.rs：密码哈希与 JWT 签发工具
scripts/db/README.md：数据库迁移/校验/回滚说明（开发/测试/生产）
scripts/db/rebuild_iam_db.sh：开发用一键重建（会清库重建+迁移+校验，不适合生产）

快速开始

环境要求

Rust：支持 edition 2024 的版本（建议使用最新 stable）
PostgreSQL：建议 14+

安装与运行

git clone <your-repo-url>
cd iam-service

初始化数据库（开发/测试示例）

export DATABASE_URL='postgres://iam_service_user:***@<pg_host>:5432/iam_service_db'
BACKUP=1 ./scripts/db/rebuild_iam_db.sh

配置环境变量

cp .env.example .env

按需修改 .env：

DATABASE_URL：PostgreSQL 连接串
JWT_SECRET：用于 refresh token 指纹（HMAC pepper），不是 JWT 签名密钥
JWT_PRIVATE_KEY_PEM / JWT_PUBLIC_KEY_PEM / JWT_KEY_ID：RS256 签发/验签密钥（详见 jwt-rs256-keys-and-e2e.md）
PORT：监听端口

启动服务

cargo run

启动后：

服务地址：http://127.0.0.1:<PORT>
API 文档：http://127.0.0.1:<PORT>/scalar

核心功能与 API

租户注册

POST /tenants/register

curl -X POST "http://127.0.0.1:3000/tenants/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tenant A","config":{"theme":{"primary":"#1d4ed8"}}}'

返回（示例）：

{
  "code": 0,
  "message": "Created",
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "name": "Tenant A",
    "status": "active",
    "config": { "theme": { "primary": "#1d4ed8" } }
  },
  "trace_id": null
}

用户注册

POST /auth/register（需要请求头 X-Tenant-ID）

curl -X POST "http://127.0.0.1:3000/auth/register" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 11111111-1111-1111-1111-111111111111" \
  -d '{"email":"user@example.com","password":"securePassword123"}'

返回（示例）：

{
  "code": 0,
  "message": "Created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com"
  },
  "trace_id": null
}

租户信息维护（需要鉴权 + 权限）

GET /tenants/me（需要 tenant:read）
PATCH /tenants/me（需要 tenant:write）
POST /tenants/me/status（需要 tenant:write）
DELETE /tenants/me（需要 tenant:write）

调用示例：

curl -X GET "http://127.0.0.1:3000/tenants/me" \
  -H "Authorization: Bearer <access_token>"

权限控制（当前实现方式）

认证（Authentication）：在中间件层完成（auth.rs），统一解析 Authorization，验签 JWT，并注入 AuthContext。
租户上下文（Tenant Context）：在中间件层完成（mod.rs），优先使用 AuthContext.tenant_id，并兼容 X-Tenant-ID（强制一致性校验）。
授权（Authorization / RBAC）：在 Handler 层作为请求级拦截点调用 Service（authorization.rs），把“查库/规则”放在 Service 层，避免 Handler 直接拼 SQL。

更完整的“RBAC + ABAC 混合模型”落地建议见 AUTHZ_DESIGN.md。

限流（生产建议）

登录/注册已在路由级挂载限流（见 rate_limit.rs）。
生产推荐在网关/边缘层做全局限流与 Bot 防护，服务内限流作为兜底。
可信代理模式：
- 配置 TRUSTED_PROXY_CIDRS，仅当对端连接 IP 命中这些网段时，才信任 Forwarded / X-Forwarded-For / X-Real-IP 提取真实客户端 IP 进行限流。
- 未命中可信代理时，将忽略这些 Header，退回按对端连接 IP 限流，避免 Header 伪造绕过。

部署指南

本地/测试环境

使用 .env 配置连接串、端口、日志等
直接运行：cargo run

生产环境（建议）

构建：cargo build --release
以环境变量方式注入 DATABASE_URL/JWT_SECRET/...，避免把 .env 放入镜像或仓库
使用反向代理（Nginx/Envoy）处理 TLS、限流与审计日志（视需求）

测试

cargo test

当前仓库尚未包含单元测试/集成测试用例；建议在新增登录、鉴权与授权功能时补充覆盖（尤其是租户隔离与权限边界）。

README.md Unescape Escape

iam-service（多租户 IAM 服务）

技术栈

系统架构

请求链路（当前）