# ruoyi-rust

**Repository Path**: trainliang/ruoyi-rust

## Basic Information

- **Project Name**: ruoyi-rust
- **Description**: RuoYi-Rust(tokio，axum)是一个雄心勃勃的项目，旨在通过现代、高性能的 Rust 语言及其强大的生态系统，完整重写主流Ruoyi的Java Web 框架 后端服务
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 19
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# RuoYi-Rust  高性能 Rust 重构后端 
#### 丰盛辉煌

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Rust Version](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) 

---
有任何需求，请直接在requests中提出，我有时间会慢慢的补充上
---
---
**RuoYi-Rust** 是一个雄心勃勃的项目，旨在通过现代、高性能的 Rust 语言及其强大的生态系统，完整重写主流 Java Web 框架 [RuoYi](https://gitee.com/y_project/RuoYi) 的后端服务。我们追求的目标不仅是功能对等，更是在性能、资源占用(目前仅几M的内存占用)、安全性及现代化开发体验上实现全面超越，为Rust生态提供一个可复用的管理系统。

本项目后端与 [RuoYi-Vue3(rust后台配套微调版)](https://gitee.com/rustdev/ruo-yi-vue3.git) 前端项目配套使用。

## ✨ 核心亮点 (Why RuoYi-Rust?)

*   🚀 **极致性能**: 基于 `Tokio` 和 `Axum` 框架，原生异步，无 GC 延迟。提供比原生 JVM 应用更快的 API 响应速度和显著降低的内存占用。

*   🔒 **内存安全**: 借助 Rust 强大的所有权和借用检查机制，从编译层面根除空指针、数据竞争等常见的运行时安全隐患，构建坚如磐石的系统。

*   📦 **极简部署**: 整个后端项目可编译为单个可执行文件(内置缓存系统)，不依赖 JRE、Tomcat、Nginx 等任何外部运行时。部署过程从未如此简单：上传文件，启动，仅此而已。

*   🛠️ **现代化开发体验**:
    *   **编译时 SQL 校验**: 采用 `SeaORM` 作为数据库交互层，提供类型安全的 ORM 操作，遵循 Rust 的编译时安全原则。任何不符合数据库表结构的查询都将在编译时被发现，杜绝大量潜在的数据库运行时错误。
    *   **声明式权限控制**: 通过自定义过程宏实现类型安全的声明式 API 权限校验，将权限元数据与业务逻辑高度内聚，彻底告别手写权限字符串带来的风险。
    *   **模块化设计**: 采用清晰的 Cargo Workspace 结构和分层架构，实现高内聚、低耦合，便于维护与扩展。

## 📊 项目状态 (截至 2026-01-20)

我们正在逐步实现 RuoYi 的全部功能。当前已完成的核心模块如下：

-   [x] **核心框架**
    -   [x] 配置加载 (`config-rs`)
    -   [x] 结构化日志 (`tracing`) - 支持文件输出、环境过滤、JSON格式
    -   [x] 数据库连接池 (`SeaORM`) - 支持 MySQL、PostgreSQL、SQLite，支持连接池配置
    -   [x] 统一响应 (`AjaxResult`) 与错误处理 (`AppError`)
    -   [x] 认证授权中间件 (`sa-token`)
    -   [x] 高性能本地缓存 (`moka`) - 内置缓存系统，无需外部Redis
    -   [x] DuckDB 冷备份 - 自动备份历史日志数据，支持数据归档和查询
-   [x] **系统模块 (`system`)**
    -   [x] 登录、获取用户信息、动态路由 (`/login`, `/getInfo`, `/getRouters`)
    -   [x] 菜单管理 - 完整的CRUD、树形结构、权限标识
    -   [x] 部门管理 - 树形结构、数据权限支持
    -   [x] 字典管理 - 字典类型和字典数据管理
    -   [x] 参数管理 - 系统参数配置
    -   [x] 角色管理 - 角色权限分配、数据范围权限
    -   [x] 用户管理 - 用户CRUD、角色分配、岗位管理
    -   [x] 岗位管理 - 岗位信息管理
    -   [x] 文件管理 - 文件上传、下载、临时文件清理
        -   [x] 文件上传接口（支持 multipart/form-data）
        -   [x] 文件下载接口（支持文件名和资源路径下载）
        -   [x] 存储抽象层（支持本地文件系统和对象存储）
        -   [x] 多种访问模式（直链、程序代理、nginx代理）
        -   [x] 支持流式传输（大文件下载）
    -   [x] 通知公告 - 完整的CRUD、公告发布、状态管理
-   [x] **权限体系**
    -   [x] 声明式权限校验过程宏 (`ruoyi-macros`)
    -   [x] 基于 Sa-Token 的认证授权
    -   [x] 数据权限控制
-   [x] **监控模块 (`monitor`)**
    -   [x] **操作日志** - 自动记录API操作、支持查询导出、中间件自动记录
    -   [x] **登录日志** - 登录成功/失败记录、支持清理过期日志
    -   [x] **在线用户** - 在线用户监控、强制下线
    -   [x] **定时任务** - 完整的任务调度系统
        -   [x] 任务CRUD（新增、修改、删除、查询）
        -   [x] 任务状态管理（正常/暂停）
        -   [x] Cron表达式支持
        -   [x] 立即执行一次（手动触发）
        -   [x] 任务执行日志记录
        -   [x] 任务执行结果追踪
        -   [x] 支持分布式锁（Database/Redis），防止多节点重复执行
        -   [x] 支持调度开关配置，可禁用自动调度
        -   [x] 支持多种任务类型（无参、单参、多参）
        -   [x] Excel导出功能
        -   [x] 内置任务：临时文件清理、登录日志清理
    -   [x] **任务执行日志** - 定时任务执行历史记录、执行结果查询
    -   [x] **缓存监控** - 缓存信息查看、缓存清理
    -   [x] **服务器监控** - 服务器性能指标监控
    -   [x] **日志适配器** - 支持从 DuckDB 冷备份中查询历史日志数据

## 🛠️ 技术栈 (Tech Stack)

| 领域            | 技术选型                | 理由                                                     |
| --------------- | ----------------------- | -------------------------------------------------------- |
| **语言/运行时** | Rust (Stable) / Tokio   | 性能、安全、现代化的异步生态。                           |
| **Web 框架**    | Axum                    | 模块化、符合人体工程学、与 `tower` 生態無縫集成。        |
| **数据库交互**  | SeaORM                  | 异步、类型安全、编译时 SQL 检查，完美契合原生 SQL 风格。 |
| **序列化**      | Serde                   | Rust 生态的事实标准，性能卓越，功能强大。                |
| **配置管理**    | `config-rs`             | 支持多种格式，支持环境覆盖，简单易用。                   |
| **日志系统**    | `tracing`               | 结构化日志，与 `tokio` 和 `axum` 深度集成。              |
| **认证/授权**   | `argon2` / `sa-token`   | 现代密码哈希标准；基于Sa-Token的统一认证授权框架。       |
| **缓存**        | `moka`                  | 高性能纯 Rust 本地并发缓存，完美替代单体应用中的 Redis。 |
| **权限宏**      | `syn`, `quote`          | 自定义过程宏，实现声明式、编译时安全的权限校验。         |
| **任务调度**    | `tokio-cron-scheduler`  | 基于Tokio的异步任务调度器，支持Cron表达式。              |
| **Excel导出**   | `rust_xlsxwriter`       | 纯Rust实现的Excel文件生成库，支持任务列表导出。           |
| **对象存储**    | `object_store`          | Apache Arrow项目的对象存储抽象层，支持多种存储后端。      |
| **冷备份**      | `duckdb`                | 高性能分析型数据库，用于历史日志数据的冷备份和查询。      |

## 📝 日志系统说明

本项目实现了完整的多层次日志系统，包括应用日志和业务日志：

### 应用日志 (Application Logging)
-   **技术栈**: `tracing` + `tracing-subscriber` + `tracing-appender`
-   **功能特性**:
    -   ✅ 结构化日志输出，支持JSON格式
    -   ✅ 文件日志输出，自动按日期滚动
    -   ✅ 环境过滤，可根据日志级别过滤输出
    -   ✅ 与 `tokio` 和 `axum` 深度集成，自动追踪异步任务
    -   ✅ 支持日志级别：`TRACE`、`DEBUG`、`INFO`、`WARN`、`ERROR`
    -   ✅ 自动记录请求路径、响应状态码、执行时间等

### 业务日志 (Business Logging)

#### 1. 操作日志 (OperLog)
-   **自动记录**: 通过 `OperLogLayer` 中间件自动记录所有API操作
-   **记录内容**: 
    -   操作标题、业务类型
    -   请求方法（GET/POST/PUT/DELETE）、请求路径
    -   操作人、部门信息
    -   请求参数、响应结果
    -   IP地址、地理位置
    -   操作状态（成功/失败）、错误信息
    -   执行耗时
-   **功能**: 查询、导出Excel、删除

#### 2. 登录日志 (LoginLog)
-   **自动记录**: 登录成功/失败时自动记录
-   **记录内容**:
    -   登录账号、登录状态（成功/失败）
    -   登录IP、地理位置
    -   浏览器类型、操作系统
    -   登录时间、失败原因
-   **功能**: 查询、导出、清理过期日志（支持定时任务自动清理）

#### 3. 定时任务执行日志 (JobLog)
-   **自动记录**: 每次定时任务执行时自动记录
-   **记录内容**:
    -   任务ID、任务名称、任务组
    -   调用目标、执行结果（成功/失败）
    -   执行消息、异常信息
    -   执行时间、执行状态
-   **功能**: 查询、删除、统计执行结果

#### 4. DuckDB 冷备份系统
-   **自动备份**: 定时将历史日志数据备份到 DuckDB 分析型数据库
-   **备份内容**:
    -   操作日志（超过保留期的历史数据）
    -   登录日志（超过保留期的历史数据）
    -   任务执行日志（超过保留期的历史数据）
-   **功能特性**:
    -   ✅ 自动按年月切分备份文件（格式：`backup_YYYY_MM.duckdb`）
    -   ✅ 支持配置备份间隔和数据保留天数
    -   ✅ 自动清理主数据库中超过保留期的数据
    -   ✅ 通过日志适配器接口查询历史数据
    -   ✅ 高性能分析查询，适合大数据量场景

### 日志级别说明
-   `[TRACE]`: 最详细的调试信息，通常仅用于开发环境
-   `[DEBUG]`: 调试信息，帮助排查问题
-   `[INFO]`: 常规信息，记录系统运行状态和重要事件
-   `[WARN]`: 警告信息，不影响系统运行但需要注意
-   `[ERROR]`: 错误信息，系统异常或操作失败

### 日志格式示例
```
[INFO] [HANDLER] Entering job::list with params: ListJobQuery { ... }
[INFO] [SERVICE] Entering job::select_job_list with params: ...
[INFO] [SCHEDULER] Successfully added job_id '1' to scheduler with UUID '...'
```

## 🚀 快速开始

请确保您的开发环境中已安装以下软件：
*   **Rust**: `1.88` 或更高版本 (通过 `rustup` 安装)
*   **SQLite/MySQL/PostgreSQL**: 根据配置选择相应的数据库（SQLite无需额外安装）

### 1. 克隆项目

```bash
git clone https://gitee.com/rustdev/ruoyi-rust.git
cd ruoyi-rust
```

### 2. 数据库设置

系统支持多种数据库类型：
-   **SQLite**（默认）：无需额外安装数据库服务器，适合开发和测试环境
-   **MySQL**：生产环境常用选择
-   **PostgreSQL**：功能强大的开源数据库
-   **DuckDB**：分析型数据库

> **注意**: 
> - 使用 SQLite 时，系统会自动创建数据库文件 `./data/ry_vue.db`（请确保 `data` 目录存在）
> - 使用 MySQL/PostgreSQL 时，需要先创建数据库，然后在配置文件中设置连接信息

### 3. 后端配置(重要！重要！重要！)

系统使用 TOML 格式的配置文件，支持多环境配置和环境变量覆盖。

#### 配置加载顺序（优先级从高到低）：
1. 环境变量（`APP_*` 前缀）
2. `config/local.toml`（可选，用于本地覆盖）
3. `config/default.toml`（基础配置）

#### 配置数据库连接

编辑 `config/default.toml` 文件，根据您使用的数据库类型进行配置：

**SQLite 配置（默认，推荐用于开发环境）：**
```toml
[database]
db_type = "sqlite"
sqlite_url = "sqlite://./data/ry_vue.db"
```

**MySQL 配置：**
```toml
[database]
db_type = "mysql"
mysql_url = "mysql://your_user:your_password@127.0.0.1:3306/ry-vue?connect_timeout=8"

# 可选：数据库连接池配置
[database.pool]
max_connections = 100      # 最大连接数
min_connections = 5        # 最小连接数
connect_timeout_secs = 8   # 连接超时时间（秒）
acquire_timeout_secs = 8   # 获取连接超时时间（秒）
idle_timeout_secs = 600    # 空闲连接超时时间（秒）
max_lifetime_secs = 1800   # 连接最大生存时间（秒）
```

**PostgreSQL 配置：**
```toml
[database]
db_type = "postgresql"
postgres_url = "postgresql://your_user:your_password@127.0.0.1:5432/ry_vue?connect_timeout=8"

# 可选：数据库连接池配置（同上）
[database.pool]
max_connections = 100
min_connections = 5
# ... 其他配置
```

#### 其他重要配置

**服务器配置：**
```toml
[server]
host = "0.0.0.0"  # 监听地址，0.0.0.0 表示监听所有网络接口
port = 8080       # 监听端口
```

**认证配置（Sa-Token）：**
```toml
[satoken]
expiration_hours = 2  # Token 过期时间（小时）
```

**Redis 配置（可选，用于分布式场景）：**
```toml
[redis]
# 方式1：使用 URL（简单场景）
# url = "redis://127.0.0.1:6379"

# 方式2：分别配置（推荐，支持密码中包含特殊字符）
host = "127.0.0.1"
port = 6379
password = "your_password"
database_id = 0
```

**定时任务调度配置：**
```toml
[job_scheduler]
scheduler_enabled = true      # 是否启用自动调度
lock_type = "database"        # 锁类型：database 或 redis
lock_ttl_seconds = 300        # 分布式锁过期时间（秒）
```

**文件存储配置：**
```toml
[storage]
# 存储类型: local, s3, minio, aliyun_oss, azure, gcp
type = "local"
# 基础路径（本地存储为目录路径，对象存储为bucket名称）
base_path = "uploads"

# 访问模式: direct（直链）, proxy（代理）, nginx_proxy（nginx代理）
# direct: 返回对象存储的直接访问URL，客户端直接访问存储服务（性能好，但暴露存储地址）
# proxy: 通过应用程序转发文件（安全，但增加服务器负载）
# nginx_proxy: 通过nginx代理转发（需要在nginx中配置代理规则）
access_mode = "proxy"

# 代理URL前缀（当 access_mode 为 proxy 或 nginx_proxy 时使用）
proxy_url_prefix = "/prod-api/common/download/resource"

# S3/MinIO 配置（当 type 为 s3 或 minio 时）
# [storage.s3]
# endpoint = "http://127.0.0.1:9000"
# bucket = "ruoyi-files"
# access_key_id = "minioadmin"
# secret_access_key = "minioadmin"
# region = "us-east-1"
# use_path_style = true        # 是否使用路径风格访问，MinIO通常需要设置为true
# presigned_url_expiry = 3600  # 预签名URL过期时间（秒，仅直链模式有效）
```

**DuckDB 冷备份配置：**
```toml
[duckdb_backup]
# 是否启用DuckDB冷备份功能
enabled = true
# DuckDB备份文件基础目录（按年月切分文件，格式：backup_YYYY_MM.duckdb）
# 如果未设置，将使用 ./data/backup
base_dir = "./data/backup"
# 备份间隔（小时），默认24小时执行一次备份
backup_interval_hours = 24
# 数据保留天数，超过此天数的日志数据将从主数据库删除并备份到DuckDB
retention_days = 90
```

**文件存储访问模式说明：**

1. **直链模式（direct）**：
   - 客户端直接访问对象存储服务
   - 性能最好，减轻服务器负载
   - 适合公开文件或已配置访问权限的对象存储
   - 本地存储返回 `/uploads/{path}` 路径

2. **程序代理模式（proxy）**：
   - 通过应用程序转发文件流
   - 可以添加权限验证和流量统计
   - 适合需要权限控制的文件访问
   - 支持流式传输，适用于大文件

3. **nginx代理模式（nginx_proxy）**：
   - 通过nginx代理转发文件
   - 性能介于直链和程序代理之间
   - 适合生产环境的大文件场景
   - 需要在nginx中配置代理规则（示例见下文）

**nginx代理配置示例**（当 `access_mode = "nginx_proxy"` 时）：
```nginx
# 对象存储代理配置
location /storage/ {
    proxy_pass http://minio:9000/ruoyi-files/;  # 根据实际对象存储地址配置
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    
    # 添加安全头（可选）
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    
    # 设置超时
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}
```

> **提示**: 
> - 对于生产环境，建议创建 `config/local.toml` 文件存放敏感配置（如数据库密码、对象存储密钥），并确保该文件已添加到 `.gitignore` 中
> - 支持通过环境变量覆盖配置，例如：`APP_DATABASE__DB_TYPE=mysql`（使用双下划线表示嵌套配置）
> - 对象存储密钥建议使用环境变量配置，避免硬编码到配置文件中
> - DuckDB 冷备份功能可以显著减少主数据库的存储压力，特别适合日志数据量大的生产环境

### 4. 运行后端服务

```bash
cargo run -p app
```

*看到 "✅ Server listening on 127.0.0.1:8080" 日志表示后端启动成功。*

> **注意**: 实体模型已预生成在 `common/src/models` 目录下，如需重新生成，可使用：
> ```bash
> sea-orm-cli generate entity -o common/src/models --database-url sqlite://data/ry_vue.db
> ```

### 5. 前端设置

```bash
# 克隆前端项目
git clone https://gitee.com/rustdev/ruo-yi-vue3.git
cd ruo-yi-vue3

# 安装依赖
npm install

# 运行开发服务器
npm run dev
```

访问 `http://localhost:80`，使用默认账号登录：
-   **账号**: `admin`
-   **密码**: `admin123`

## 🏗️ 项目结构

本项目采用 Cargo Workspace 进行模块化管理，结构清晰，职责分明。

-   `ruoyi-rust/` (Workspace 根目录)
    -   `app`: **主程序入口**。负责组装所有模块、初始化服务、启动 Web 服务器。
    -   `common`: **通用基础库**。存放跨模块共享的组件（如 `AppError`, `AjaxResult`, 共享模型等）。
    -   `framework`: **核心框架库**。提供基础设施服务（如配置、数据库、日志、JWT、中间件）。
    -   `modules/`: **业务模块聚合**。
        -   `system`: **核心系统模块**。实现 RuoYi 的所有核心后台管理功能。
        -   `monitor`: **系统监控模块**。包含操作日志、登录日志、在线用户、定时任务、缓存监控、服务器监控、日志适配器等。
        -   `user`: **用户模块**（实验性，DDD架构示例）。
    -   `common/`: **通用基础库**。
        -   `backup`: **备份服务**。DuckDB 冷备份功能实现。
        -   `macros`: **过程宏库**。存放自定义的过程宏，如 `#[require_permission(...)]`。

##🤝 贡献指南

我们热烈欢迎任何形式的贡献！无论是提交 Issue、修复 Bug 还是实现新功能。请参考我们的 [CONTRIBUTING.md](CONTRIBUTING.md) 文件了解详细的贡献流程和编码规范。

##📄 许可证 (License)

本项目采用 [MIT License](LICENSE) 开源许可证。
## ruoyi-rust： 交流QQ群: 512670767

## 🙏 鸣谢

*   感谢原项目 [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue) 提供的优秀设计和前端实现。
*   感谢 [RuoYi-Vue3](https://gitcode.com/yangzongzhuan/RuoYi-Vue3) 提供的 Vue3 前端版本。
*   演示 https://demo.ruoyi.vip/index