163 lines
4.9 KiB
Markdown
163 lines
4.9 KiB
Markdown
# 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`）
|
||
|
||
## 系统架构
|
||
|
||
### 请求链路（当前）
|
||
|
||
```mermaid
|
||
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](file:///home/shay/project/backend/iam-service/src/main.rs)：服务入口、路由组装、Telemetry 初始化、DB 连接池初始化
|
||
- [src/config/mod.rs](file:///home/shay/project/backend/iam-service/src/config/mod.rs)：环境变量配置加载
|
||
- [src/db/mod.rs](file:///home/shay/project/backend/iam-service/src/db/mod.rs)：PostgreSQL 连接池初始化（迁移功能目前未启用）
|
||
- [src/middleware/mod.rs](file:///home/shay/project/backend/iam-service/src/middleware/mod.rs)：多租户中间件与 `TenantId` 提取器
|
||
- [src/handlers/mod.rs](file:///home/shay/project/backend/iam-service/src/handlers/mod.rs)：HTTP Handler（控制器层），负责参数解析、调用 Service、返回统一响应
|
||
- [src/services/mod.rs](file:///home/shay/project/backend/iam-service/src/services/mod.rs)：业务逻辑（注册/登录）与数据库交互
|
||
- [src/models.rs](file:///home/shay/project/backend/iam-service/src/models.rs)：DB Model 与请求/响应 DTO（同时用于 OpenAPI Schema）
|
||
- [src/utils/mod.rs](file:///home/shay/project/backend/iam-service/src/utils/mod.rs)：密码哈希与 JWT 签发工具
|
||
- [init.sql](file:///home/shay/project/backend/iam-service/init.sql)：初始化数据库/表结构的 SQL（包含 tenants/users）
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Rust：支持 edition 2024 的版本（建议使用最新 stable）
|
||
- PostgreSQL：建议 14+
|
||
|
||
### 安装与运行
|
||
|
||
1. 克隆仓库并进入目录
|
||
|
||
```bash
|
||
git clone <your-repo-url>
|
||
cd iam-service
|
||
```
|
||
|
||
2. 初始化数据库（示例）
|
||
|
||
```bash
|
||
psql -h <pg_host> -U <admin_user> -f init.sql
|
||
```
|
||
|
||
3. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
按需修改 `.env`：
|
||
|
||
- `DATABASE_URL`：PostgreSQL 连接串
|
||
- `JWT_SECRET`：JWT 签名密钥（务必替换为强随机字符串）
|
||
- `PORT`：监听端口
|
||
|
||
4. 启动服务
|
||
|
||
```bash
|
||
cargo run
|
||
```
|
||
|
||
启动后：
|
||
|
||
- 服务地址：`http://127.0.0.1:<PORT>`
|
||
- API 文档：`http://127.0.0.1:<PORT>/scalar`
|
||
|
||
## 核心功能与 API
|
||
|
||
### 用户注册
|
||
|
||
`POST /auth/register`（需要请求头 `X-Tenant-ID`）
|
||
|
||
```bash
|
||
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"}'
|
||
```
|
||
|
||
返回（示例）：
|
||
|
||
```json
|
||
{
|
||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"email": "user@example.com"
|
||
}
|
||
```
|
||
|
||
### 登录与鉴权（待完善）
|
||
|
||
代码中已存在 `AuthService::login()` 与 JWT 签发工具，但目前没有对外暴露的 HTTP 路由，也未实现 JWT 验签/认证中间件与权限控制。
|
||
|
||
## 多租户使用指南
|
||
|
||
### 创建租户
|
||
|
||
当前无“租户管理 API”，建议通过 SQL 初始化租户：
|
||
|
||
```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、限流与审计日志（视需求）
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
cargo test
|
||
```
|
||
|
||
当前仓库尚未包含单元测试/集成测试用例；建议在新增登录、鉴权与授权功能时补充覆盖（尤其是租户隔离与权限边界）。
|