基于 Rust + Axum 的企业级权限管理系统设计与实现

基于 Rust + Axum 的企业级权限管理系统设计与实现

一、项目概述

1.1 项目背景

随着企业数字化转型的深入，权限管理系统成为企业级应用的核心基础设施。一个完善的权限管理系统需要支持：

• 用户管理：用户的增删改查、状态管理
• 角色管理：角色的创建、权限分配
• 权限管理：精细化的权限控制，支持树形结构
• 组织管理：多层级组织架构管理
• 审计日志：完整的操作追溯能力

本项目采用 Rust 作为开发语言，结合 Axum Web 框架、SeaORM 数据库 ORM、Disruptor 模式的事件总线，构建了一个高性能、高可用的企业级权限管理系统。目前代码还处于优化阶段，还有部分工作需要迭代，后续会不定期更新

1.2 技术栈

层次	技术选型	说明
Web 框架	Axum 0.8.x	高性能异步 Web 框架
数据库	PostgreSQL	关系型数据库
ORM	SeaORM	Rust 原生 ORM 框架
缓存	Redis	分布式缓存、Session 存储
API 文档	Utoipa + Swagger UI	OpenAPI 3.0 自动生成
事件总线	event	高性能内存事件总线
认证	JWT	无状态令牌认证
配置	YAML	外部化配置管理

1.3 项目结构

rust-permission/
├── services/
│   ├── iam-service/          # 权限服务（核心）
│   │   ├── src/
│   │   │   ├── api/          # API 层（路由、Swagger）
│   │   │   ├── application/ # 应用层（Handler）
│   │   │   ├── domain/      # 领域层（实体、服务、事件）
│   │   │   ├── infrastructure/ # 基础设施层（数据库、Redis）
│   │   │   ├── main.rs
│   │   │   └── lib.rs
│   │   ├── migrations/      # 数据库迁移
│   │   └── config.yml       # 配置文件
│   ├── sysconfig-service/   # 系统配置服务
│   └── gateway/             # API 网关
├── shared/                   # 共享库
└── docs/                    # 设计文档

---

二、架构设计

2.1 整体架构图

IAM Service
API Gateway 层
客户端层
Infrastructure Layer
Domain Layer
Application Layer
API Layer
Web 端
移动端
API Gateway
限流
认证鉴权
请求路由
Router
Handler
Swagger UI
UserHandler
RoleHandler
PermissionHandler
OrganizationHandler
User Service
Role Service
Permission Service
Organization Service
Event Bus (Disruptor)
UserEvent
RoleEvent
PermissionEvent
PostgreSQL
Redis
SeaORM
Snowflake ID

2.2 分层架构详解

2.2.1 API 层

API 作为用户触点，层负责处理 HTTP 请求和响应，采用 Axum 框架的 Router + Handler 模式：

// routes.rs
pub fn create_user_routes(db: sea_orm::DatabaseConnection, ...) -> Router {
    Router::new()
        .route("/users", post(user_handler::create_user))
        .route("/users", get(user_handler::list_users))
        .route("/users/{id}", get(user_handler::get_user))
        .route("/users/{id}", put(user_handler::update_user))
        .route("/users/{id}", delete(user_handler::delete_user))
        .route("/auth/login", post(user_handler::login))
        .with_state(user_handler)
}

界面展示

关键特性：

• 使用 with_state 依赖注入，with_state 是 Axum 框架提供的一种依赖注入机制，用于将共享状态（如数据库连接、缓存、Service 实例等）注入到 Handler 中。状态只创建一次，所有请求共享。
• 路径参数使用 {id} 语法（Axum 0.8+）
• 支持 RESTful 风格的 CRUD 操作

2.2.2 应用层

应用层负责协调领域服务，处理业务逻辑：

// user_handler.rs
pub async fn create_user(
    State(handler): State<Arc<UserHandler>>,
    Json(dto): Json<CreateUserDto>,
) -> Result<Json<ApiResponse<serde_json::Value>>, ...> {
    match handler.user_service.create_user(dto).await {
        Ok(user) => Ok(Json(ApiResponse::success(...))),
        Err(e) => Err((StatusCode::BAD_REQUEST, Json(...))),
    }
}

2.2.3 领域层

领域层是系统的核心，包含：

1. 实体（Entity）：User、Role、Permission、Organization
2. 领域服务（Domain Service）：UserService、RoleService
3. 领域事件（Domain Event）：UserEvent、RoleEvent
4. 仓储接口（Repository Trait）

// domain/user.rs
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct User {
    pub id: i64,
    pub username: String,
    pub email: Option<String>,
    pub phone: Option<String>,
    pub status: UserStatus,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

2.2.4 基础设施层

基础设施层负责与外部系统交互：

1. 数据库层：SeaORM Entity 定义，SeaORM 是一个用 Rust 编写的异步 ORM（对象关系映射）框架，专为现代 Rust Web 应用设计。并且，完全基于 async/await，支持 tokio 运行时。
2. 缓存层：Redis 认证缓存
3. 安全配置：动态安全策略管理

---

三、核心设计模式

3.1 CQRS 模式

CQRS（Command Query Responsibility Segregation）将读操作和写操作分离：
数据存储
读操作流程
写操作流程
Query (读操作)
Command (写操作)
CreateUser
UpdateUser
DeleteUser
AssignRole
GetUser
ListUsers
GetUserTree
SearchUsers
Command Handler
Domain Service
Event Bus
Query Handler
Redis Cache
PostgreSQL

(Event Store + State)

3.2 事件驱动设计

系统采用事件驱动架构，核心组件包括：

1. 领域事件：用户创建、角色变更、权限分配等
2. 事件总线：基于 Disruptor 模式的高性能事件处理
3. 事件订阅者：审计日志、缓存更新、通知发送

// 事件定义
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(tag = "type")]
pub enum UserEvent {
    LoggedIn { id: i64, username: String, ip_address: String },
    LoggedOut { id: i64, username: String, ip_address: String },
    Created { id: i64, username: String, created_by: i64 },
    Updated { id: i64, old_data: UserSnapshot, new_data: UserSnapshot },
    Deleted { id: i64, deleted_by: i64 },
    RoleAssigned { id: i64, role_ids: Vec<i64> },
    RoleRemoved { id: i64, role_ids: Vec<i64> },
}

3.3 Disruptor 事件总线

本项目实现了基于 Disruptor 模式的高性能事件总线：

// disruptor.rs
pub struct DisruptorEventBus {
    sender: Sender<BusCommand>,
    handlers: Arc<RwLock<HashMap<String, Vec<Box<dyn EventHandler<dyn DomainEvent>>>>>,
    worker_handle: Arc<RwLock<Option<thread::JoinHandle<()>>>>,
}

impl DisruptorEventBus {
    pub fn new(buffer_size: usize) -> Self {
        let (sender, receiver) = bounded::<BusCommand>(buffer_size);
        let handlers = Arc::new(RwLock::new(HashMap::new()));
        
        let handle = thread::spawn(move || {
            Self::event_loop(receiver, handlers);
        });
        
        Self {
            sender,
            handlers,
            worker_handle: Arc::new(RwLock::new(Some(handle))),
        }
    }
}

Disruptor 模式优势：

• 高性能：无锁设计，单线程事件处理
• 低延迟：环形缓冲区，避免内存分配
• 可扩展：支持多消费者订阅

---

四、数据库设计

4.1 核心表结构

4.1.1 用户表 (users)

CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    username VARCHAR(100) NOT NULL UNIQUE,
    email VARCHAR(255),
    phone VARCHAR(20),
    password_hash VARCHAR(255) NOT NULL,
    status SMALLINT NOT NULL DEFAULT 1,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_status ON users(status);

4.1.2 角色表 (roles)

CREATE TABLE roles (
    id BIGINT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    code VARCHAR(100) NOT NULL UNIQUE,
    description TEXT,
    status SMALLINT NOT NULL DEFAULT 1,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

4.1.3 权限表 (permissions)

CREATE TABLE permissions (
    id BIGINT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    code VARCHAR(100) NOT NULL UNIQUE,
    description TEXT,
    parent_id BIGINT,
    type SMALLINT NOT NULL,
    path VARCHAR(255),
    component VARCHAR(255),
    icon VARCHAR(50),
    sort_order INT DEFAULT 0,
    status SMALLINT NOT NULL DEFAULT 1,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (parent_id) REFERENCES permissions(id)
);

CREATE INDEX idx_permissions_parent ON permissions(parent_id);
CREATE INDEX idx_permissions_code ON permissions(code);

4.1.4 审计日志表 (audit_logs)

CREATE TABLE audit_logs (
    id BIGINT PRIMARY KEY,
    event_id VARCHAR(100) NOT NULL,
    event_type VARCHAR(100) NOT NULL,
    aggregate_type VARCHAR(50) NOT NULL,
    aggregate_id BIGINT NOT NULL,
    action VARCHAR(20) NOT NULL,
    old_value JSONB,
    new_value JSONB,
    operator_id BIGINT,
    ip_address VARCHAR(50),
    user_agent TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_audit_logs_aggregate ON audit_logs(aggregate_type, aggregate_id);
CREATE INDEX idx_audit_logs_time ON audit_logs(created_at);
CREATE INDEX idx_audit_logs_operator ON audit_logs(operator_id);

4.2 SeaORM Entity 定义

// user_entity.rs
#[derive(Clone, Debug, DeriveEntityModel)]
#[sea_orm(table_name = "users")]
pub struct Model {
    #[sea_orm(column_name = "id", primary_key)]
    pub id: i64,
    #[sea_orm(column_name = "username")]
    pub username: String,
    #[sea_orm(column_name = "email")]
    pub email: Option<String>,
    #[sea_orm(column_name = "password_hash")]
    pub password_hash: String,
    #[sea_orm(column_name = "status")]
    pub status: i16,
    #[sea_orm(column_name = "created_at")]
    pub created_at: DateTime,
    #[sea_orm(column_name = "updated_at")]
    pub updated_at: DateTime,
}

impl ActiveModelBehavior for ActiveModel {}

---

五、认证与授权

5.1 JWT 认证

系统采用 JWT 实现无状态认证：

// shared/src/auth.rs
pub struct JwtManager {
    secret: String,
    access_token_expire_minutes: i64,
    refresh_token_expire_days: i64,
}

impl JwtManager {
    pub fn generate_token(&self, user_id: i64, username: &str) -> AppResult<TokenPair> {
        let now = Utc::now();
        let access_exp = now + Duration::minutes(self.access_token_expire_minutes);
        let refresh_exp = now + Duration::days(self.refresh_token_expire_days);
        
        let access_claims = Claims {
            sub: user_id.to_string(),
            username: username.to_string(),
            exp: access_exp.timestamp(),
            iat: now.timestamp(),
            token_type: "access",
        };
        
        // 生成 access_token 和 refresh_token
        ...
    }
}

5.2 认证缓存

使用 Redis 存储认证信息，支持：

• Token 黑名单：登出时将 Token 加入黑名单
• 登录失败计数：防止暴力破解
• 会话管理：支持多端登录控制

// redis.rs
pub struct AuthCache {
    client: redis::Client,
    token_ttl: Duration,
    max_failures: u32,
    lock_duration: Duration,
}

impl AuthCache {
    pub async fn clear_auth_info(&self, user_id: i64) -> AppResult<()> {
        let mut conn = self.client.get_async_connection().await?;
        
        // 删除用户的所有认证信息
        let key = format!("auth:user:{}", user_id);
        redis::cmd("DEL")
            .arg(&key)
            .arg(format!("refresh:user:{}", user_id))
            .query_async(&mut conn)
            .await?;
        
        Ok(())
    }
}

---

六、配置管理

6.1 YAML 配置

系统采用 YAML 文件进行外部化配置：

# config.yml
database:
  host: localhost
  port: 5432
  username: postgres
  password: password
  name: permission_db

redis:
  host: localhost
  port: 6379

app:
  host: 0.0.0.0
  port: 8002

jwt:
  secret: your-secret-key
  access_token_expire_minutes: 30
  refresh_token_expire_days: 7

swagger:
  enabled: true
  url: /openapi.json

log:
  level: info
  sql_level: warn

events:
  user_events:
    - "UserLoggedIn"
    - "UserLoggedOut"
    - "UserCreated"
    - "UserUpdated"
    - "UserDeleted"
  role_events:
    - "RoleCreated"
    - "RoleUpdated"
    - "RoleDeleted"
  permission_events:
    - "PermissionCreated"
    - "PermissionUpdated"
    - "PermissionDeleted"

6.2 配置加载

#[derive(Debug, Deserialize)]
struct Config {
    database: DatabaseConfig,
    redis: RedisConfig,
    app: AppConfig,
    jwt: JwtConfig,
    swagger: SwaggerConfig,
    log: LogConfig,
    events: EventsConfig,
}

---

七、API 文档

7.1 Swagger 集成

使用 Utoipa 自动生成 OpenAPI 3.0 文档：

#[derive(OpenApi)]
#[openapi(
    paths(
        iam_service::application::user_handler::create_user,
        iam_service::application::user_handler::login,
        // ...
    ),
    components(
        schemas(
            iam_service::domain::user::User,
            iam_service::domain::user::CreateUserDto,
            // ...
        )
    ),
    tags(
        (name = "用户管理", description = "用户相关的 API 接口"),
        (name = "认证授权", description = "认证和授权相关的 API 接口"),
    )
)]
pub struct ApiDoc;

7.2 API 示例

用户登录

POST /api/v1/auth/login
Content-Type: application/json

{
    "username": "admin",
    "password": "password123"
}

响应：

{
    "code": 200,
    "message": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_in": 1800,
        "token_type": "Bearer"
    }
}

---

八、安全特性

8.1 安全配置管理

系统支持动态安全策略：

pub struct SecurityConfigManager {
    configs: RwLock<HashMap<String, SecurityConfig>>,
}

impl SecurityConfigManager {
    pub async fn get_login_failure_config(&self) -> LoginFailureConfig {
        let configs = self.configs.read().await;
        // 从数据库加载配置
    }
}

8.2 审计日志

所有操作都会被记录到审计日志：

pub struct AuditLogHandler {
    repository: Arc<AuditLogRepositoryImpl>,
}

#[async_trait]
impl EventHandler<UserEvent> for AuditLogHandler {
    async fn handle(&self, event: UserEvent) -> AppResult<()> {
        let audit_log = match &event {
            UserEvent::Created { id, username, .. } => {
                AuditLog {
                    event_type: "UserCreated".to_string(),
                    aggregate_type: "user".to_string(),
                    aggregate_id: *id,
                    action: "CREATE".to_string(),
                    new_value: Some(serde_json::json!({ "username": username })),
                    ..
                }
            }
            // ...
        };
        
        self.repository.create(audit_log).await
    }
}

---

九、性能优化

9.1 缓存策略

缓存键	内容	TTL
user:{id}	用户信息	30 分钟
user:{id}:roles	用户角色	1 小时
auth:user:{id}	认证信息	30 分钟

9.2 异步处理

• 使用 tokio 异步运行时
• 事件总线异步发布
• 数据库连接池

---

十、总结

本项目是一个典型的企业级 Rust 微服务架构实践：

1. 清晰的分层架构：API → 应用 → 领域 → 基础设施
2. CQRS 模式：读写分离，提升系统性能
3. 事件驱动：解耦业务逻辑，支持审计追踪
4. 外部化配置：YAML 配置管理
5. API 文档自动化：Utoipa + Swagger UI

---

十一、不足与改进方向

作为一个持续迭代的项目，当前的权限管理系统仍有许多需要改进的地方：系统采用了事件驱动架构，但事件主要用于审计日志记录，未完全实现完整的事件溯源（Event Sourcing）模式，后期迭代引入 ABAC（基于属性的访问控制），支持更细粒度的权限控制。

结语

尽管当前项目还存在诸多不足，但已经搭建了一个较为完整的 Rust 微服务架构骨架。通过不断迭代优化，这些问题都将逐步得到解决，我们也将在实践中积累更多 Rust 企业级应用的经验。

---

参考资料

• Axum 官方文档
• SeaORM 官方文档
• Utoipa 官方文档
• CQRS 模式
• Event Sourcing