iam-service/README.md

iam-service（多租户 IAM 服务）

一个基于 Rust 的多租户身份识别与访问管理（IAM）服务雏形，当前提供“租户隔离 + 用户注册”能力，并为后续扩展登录、JWT 认证、授权（RBAC/ABAC）、租户管理等功能预留了模块边界。

技术栈

• 语言与运行时：Rust（edition 2024）、Tokio
• Web：Axum
• 数据库：PostgreSQL + SQLx
• 密码：Argon2
• Token：JWT（签发已实现；验签/认证中间件待补齐）
• 可观测性：tracing + common-telemetry（私有 registry：kellnr）
• API 文档：utoipa + Scalar（/scalar）

系统架构

请求链路（当前）

flowchart LR
  C[Client] -->|HTTP + JSON| R[Axum Router]
  R --> M[租户中间件 resolve_tenant]
  M --> H[Handlers]
  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 层通过请求头 X-Tenant-ID: <uuid> 传入租户上下文，并在 Service/SQL 查询中使用 tenant_id 过滤

项目结构说明

• src/main.rs：服务入口、路由组装、Telemetry 初始化、DB 连接池初始化
• src/config/mod.rs：环境变量配置加载
• src/db/mod.rs：PostgreSQL 连接池初始化（迁移功能目前未启用）
• src/middleware/mod.rs：多租户中间件与 TenantId 提取器
• src/handlers/mod.rs：HTTP Handler（控制器层），负责参数解析、调用 Service、返回统一响应
• src/services/mod.rs：业务逻辑（注册/登录）与数据库交互
• src/models.rs：DB Model 与请求/响应 DTO（同时用于 OpenAPI Schema）
• src/utils/mod.rs：密码哈希与 JWT 签发工具
• init.sql：初始化数据库/表结构的 SQL（包含 tenants/users）

快速开始

环境要求

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

安装与运行

1. 克隆仓库并进入目录

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

2. 初始化数据库（示例）

psql -h <pg_host> -U <admin_user> -f init.sql

3. 配置环境变量

cp .env.example .env

按需修改 .env：

• DATABASE_URL：PostgreSQL 连接串
• JWT_SECRET：JWT 签名密钥（务必替换为强随机字符串）
• PORT：监听端口

4. 启动服务

cargo run

启动后：

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

核心功能与 API

用户注册

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"}'

返回（示例）：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com"
}

登录与鉴权（待完善）

代码中已存在 AuthService::login() 与 JWT 签发工具，但目前没有对外暴露的 HTTP 路由，也未实现 JWT 验签/认证中间件与权限控制。

多租户使用指南

创建租户

当前无“租户管理 API”，建议通过 SQL 初始化租户：

INSERT INTO tenants (id, name) VALUES ('22222222-2222-2222-2222-222222222222', 'Tenant A');

访问租户资源

所有请求都需要携带租户头：

• X-Tenant-ID: <tenant_uuid>

建议在后续迭代中：

• 将 tenant_id 与用户身份绑定（JWT claims / session）
• 校验请求头租户与 token 内租户一致，避免伪造跨租户访问

部署指南

本地/测试环境

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

生产环境（建议）

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

测试

cargo test

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