基于 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 整体架构图

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）将读操作和写操作分离：

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