# ruoyi-rust

**Repository Path**: rustdev/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**: 111
- **Forks**: 39
- **Created**: 2025-09-09
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: backend

**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)

---

> 有任何需求，请直接在 Issues 中提出，有时间会慢慢补充完善。

---

**RuoYi-Rust** 是一个雄心勃勃的项目,始于(2025-08-28)，旨在通过现代、高性能的 Rust 语言及其强大的生态系统，完整重写主流 Java Web
框架 [RuoYi](https://gitee.com/y_project/RuoYi) 的后端服务。我们追求的目标不仅是功能对等，更是在性能、资源占用（目前仅几 M 的内存占用）、安全性及现代化开发体验上实现全面超越，为 Rust 生态提供一个可复用的企业级管理系统方案。

🔗 **在线演示：[http://212.129.155.221:9081](http://212.129.155.221:9081)** | 账号：`admin` 密码：`admin123`

### 2026-06-29 新版发布

- **前端全面升级**：配套前端从 RuoYi-Vue3 升级为基于 **Vue Vben Admin v5.7.0** 的 [ruoyi-rust-ui-plus](https://gitee.com/rustdev/ruoyi-rust-ui-plus.git)，采用 Vue 3 + TypeScript + Element Plus + Tailwind CSS v4 + UnoCSS，开发体验更佳。
- **代码生成工具增强**：新增完整的代码生成前端页面（导入表、创建表、预览代码、编辑配置、拖拽排序、批量下载），前后端全链路打通。
- **AI 协作新范式**：**所有新业务优先使用代码生成工具产出统一规范的项目骨架，保证架构一致、减少低级 bug；剩余业务细节交由 AI 自动填充，整体提升研发效率**。

## 🎯 配套项目

| 项目 | 说明 |
|------|------|
| **后端** | [ruoyi-rust](https://gitee.com/rustdev/ruoyi-rust.git) — 本项目，Rust 后端服务 |
| **前端（推荐）** | [ruoyi-rust-ui-plus](https://gitee.com/rustdev/ruoyi-rust-ui-plus.git) — 基于 Vue Vben Admin v5.7.0 + Element Plus + TypeScript |
| **前端（旧版）** | [ruo-yi-vue3](https://gitee.com/rustdev/ruo-yi-vue3.git) — RuoYi-Vue3 微调版（已停止维护） |

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

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

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

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

- 🗄️ **多数据库支持**: 内置 **MySQL / PostgreSQL / SQLite** 适配，可通过 URL 或 host/port/database 结构化配置切换数据库，连接池大小、连接/空闲超时等参数均可配置。

- ⚡ **多级权限缓存**: 权限数据支持 **moka 本地缓存 (L1)**、**Redis 缓存 (L2)** 或两级混合模式，角色/菜单/用户授权变更时自动失效对应缓存，显著降低高频鉴权的数据库压力。

- 🛠️ **现代化开发体验**:
  - **类型安全的数据库访问**: 采用 **SeaORM** 作为数据库访问层，遵循"数据库 Schema 为唯一真实来源"原则。不仅支持 MySQL / PostgreSQL / SQLite，还能在编译期发现大量不符合数据库表结构的查询错误。
  - **声明式权限控制**: 通过自定义过程宏实现类型安全的声明式 API 权限校验，将权限元数据与业务逻辑高度内聚，彻底告别手写权限字符串带来的风险。
  - **模块化设计**: 采用清晰的 Cargo Workspace 结构和分层架构，实现高内聚、低耦合，便于维护与扩展。
  - **数据库迁移**: 内置 `sea-orm-migration` 数据库迁移模块，Schema 变更通过版本化迁移脚本管理，告别手工维护 SQL。

## 📊 项目状态

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

- [x] **核心框架**
  - [x] 配置加载 (`config-rs`)
  - [x] 结构化日志 (`tracing`)
  - [x] 数据库连接池 (SeaORM，支持 MySQL / PostgreSQL / SQLite)
  - [x] 统一响应 (`AjaxResult`) 与错误处理 (`AppError`)
  - [x] JWT 认证中间件 (`jwt-simple`)
  - [x] 高性能本地缓存 (`moka`)，可选 Redis 二级缓存
  - [x] 数据库迁移 (`sea-orm-migration`)
  - [x] 客户端登录扩展：登录支持透传 `client_id`，可按客户端配置解析设备类型、固定超时与活跃超时
  - [x] 单端登录控制：支持按 `user_id + device_type` 维度顶号；当 `security.concurrent_login = false` 时，同账号同端新登录会挤掉旧会话
  - [x] 在线会话增强：在线用户记录已保存 `device_type`、`client_id`、活跃超时与固定过期上限，便于区分 Web / App 等登录来源

- [x] **系统模块 (`system`)**
  - [x] 登录、获取用户信息、动态路由 (`/login`, `/getInfo`, `/getRouters`)
  - [x] 菜单管理
  - [x] 部门管理
  - [x] 字典管理
  - [x] 参数管理
  - [x] 角色管理
  - [x] 用户管理
  - [x] 系统通知
  - [x] 岗位管理
  - [x] 客户端管理

- [x] **权限体系**
  - [x] 声明式权限校验过程宏 (`ruoyi-macros`)
  - [x] 数据权限（全部 / 本部门 / 本部门及以下 / 自定义 / 仅本人）

- [x] **监控模块 (`monitor`)**
  - [x] 操作日志
  - [x] 登录日志
  - [x] 在线用户
  - [x] 定时任务
  - [x] 服务监控（CPU / 内存 / 磁盘）
  - [x] 缓存监控

- [x] **对象存储 (`oss`)**
  - [x] 文件上传 / 下载
  - [x] AWS S3 协议兼容（推荐 [RustFS](https://github.com/rustfs/rustfs)，同时兼容 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 等）

- [x] **代码生成工具 (`code-tool`)**
  - [x] 数据库元数据自动提取 (MySQL / PostgreSQL / SQLite)
  - [x] Rust 后端全栈生成 (Model, Service, Handler, Mod, Router)
  - [x] Vue 前端全栈生成 (index.vue, api.ts)
  - [x] **自动化权限宏注入**: 自动生成 `#[require_permission("...")]`，无需手动维护 Enum
  - [x] 结构化 ZIP 下载 (自动分类 backend / frontend / sql 文件夹)
  - [x] 在线预览生成代码（左侧文件树 + 右侧代码展示）
  - [x] 导入已有表 / SQL 创建表 / 同步数据库结构
  - [x] 可视化编辑表配置（字段属性、查询方式、显示类型、字典绑定、拖拽排序）
  - [x] 菜单 SQL 自动生成

### 🚧 框架认证 / 客户端能力当前已实现与未实现说明

#### 已实现

- [x] 登录接口已支持传入 `client_id`，并根据 `sys_client` 读取客户端配置
- [x] 可基于客户端配置控制：
  - [x] `device_type`（设备类型隔离）
  - [x] `timeout`（token 固定超时）
  - [x] `active_timeout`（在线会话活跃超时 / 滑动续期）
- [x] 单端登录已接入主登录流程：可按同账号、同设备类型执行顶号
- [x] 已提供后台客户端管理能力：维护 `client_id`、`client_key`、`client_secret`、`grant_type`、`device_type`、超时配置、状态等字段
- [x] 客户端停用后，登录时会拒绝该客户端发起的请求

#### 暂未实现 / 当前限制

- [ ] **授权类型（grant_type）校验尚未真正接入登录认证流程**
  - 当前框架登录认证仍然只有“账号密码登录”这一条主链路
  - 虽然 `sys_client.grant_type` 字段、列表筛选、导入导出、后台维护已经具备，但目前更多是配置存储与展示
  - 也就是说：**现在还没有根据 `grant_type` 去区分或限制 password / sms / social / refresh_token 等不同授权流程**
- [ ] 暂未实现完整 OAuth2 / OIDC 授权中心能力
  - 例如标准意义上的授权码模式、客户端凭证模式、刷新令牌模式、第三方社交授权回调等，当前都还未完整落地
- [ ] 暂未实现基于客户端 + 授权类型的细粒度登录准入校验
  - 例如“某客户端只允许 `password`，另一个客户端只允许 `sms`”这类能力，目前还没有真正生效
- [ ] 暂未实现 `grant_type` 与前端登录入口、后端认证处理器的一一对应扩展
  - 当前前端/后端主流程仍以用户名密码认证为主，后续若扩展短信登录、社交登录、刷新 token，需要继续补齐整条链路

## 🛠️ 技术栈 (Tech Stack)

### 后端

| 领域 | 技术选型 | 理由 |
|------|----------|------|
| **语言/运行时** | Rust (Stable) / Tokio | 性能、安全、现代化的异步生态 |
| **Web 框架** | Axum | 模块化、符合人体工程学、与 `tower` 生态无缝集成 |
| **数据库交互** | SeaORM | 异步 ORM，支持 MySQL / PostgreSQL / SQLite，提供类型安全的数据库访问 |
| **数据库迁移** | sea-orm-migration | Schema 版本化迁移，与 SeaORM 深度集成 |
| **序列化** | Serde | Rust 生态的事实标准，性能卓越，功能强大 |
| **配置管理** | `config-rs` | 支持多种格式，支持环境覆盖，简单易用 |
| **日志系统** | `tracing` | 结构化日志，与 `tokio` 和 `axum` 深度集成 |
| **认证/授权** | `argon2` / `jwt-simple` | 现代密码哈希标准；纯 Rust 实现的 JWT 库，轻量安全 |
| **缓存** | `moka` / Redis | 高性能本地缓存，可选 Redis 二级缓存，灵活应对单机或分布式部署 |
| **权限宏** | `syn` / `quote` | 自定义过程宏，实现声明式、编译时安全的权限校验 |
| **对象存储** | AWS SDK S3 | 兼容 S3 协议，推荐 [RustFS](https://github.com/rustfs/rustfs)（Rust 原生，性能 2.3x MinIO），同时兼容 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 |
| **OpenAPI** | aide / schemars | 自动生成 Swagger/OpenAPI 文档 |

### 旧前端（原若依框架前端）

### 新前端（ruoyi-rust-ui-plus）

| 领域 | 技术选型 | 说明 |
|------|----------|------|
| **框架** | Vue 3.5 + TypeScript 6 | Composition API + `<script setup lang="ts">` |
| **UI 库** | Element Plus 2.14 | 成熟的 Vue 3 组件库 |
| **基础模板** | Vue Vben Admin v5.7.0 | Monorepo 架构，多 UI 变体支持 |
| **CSS** | Tailwind CSS v4 + UnoCSS | 原子化 CSS，高效开发 |
| **状态管理** | Pinia 3 | Vue 3 官方状态管理 |
| **构建工具** | Vite 8 | 极速开发体验 |
| **HTTP 客户端** | Axios + `@vben/request` | 拦截器、Token 刷新、统一错误处理 |
| **包管理** | pnpm + Turborepo | Monorepo 高效管理 |

## 🚀 快速开始

### 环境要求

* **Rust**: `1.88` 或更高版本 (通过 `rustup` 安装)
* **Node.js**: `^22.18.0 || ^24.0.0`（前端需要，通过 `nvm` 安装）
* **pnpm**: `>=11.0.0`（前端包管理）
* **数据库（任选其一）**: **MySQL** `5.7+`、**PostgreSQL**、或 **SQLite**（本地体验推荐）

### 1. 克隆项目

```bash
# 克隆后端
git clone https://gitee.com/rustdev/ruoyi-rust.git
cd ruoyi-rust

# 克隆前端（推荐使用新版 Vben 5 前端）
git clone https://gitee.com/rustdev/ruoyi-rust-ui-plus.git
```

### 2. 数据库设置

本项目支持 **MySQL / PostgreSQL / SQLite**，请任选一种：

- **MySQL**: 创建数据库（如 `ry-vue`），导入 `sql/ry_20250808.sql`。
- **PostgreSQL**: 创建数据库（如 `ry-vue`），导入 `sql/ry_20250808.sql`（PostgreSQL 兼容版本）。
- **SQLite**: 使用项目提供的 `sql/ry-rust_20260620_sqlite.sql` 初始化 SQLite 文件，或让程序自动连接空库。

> 若无需安装 MySQL/PostgreSQL，可直接使用 SQLite 进行本地体验。

### 3. 后端配置

1. 复制环境配置文件：
   ```bash
   cp config/default.toml config/local.toml
   ```

2. 编辑 `config/local.toml`，配置数据库连接。支持以下两种方式：
   - **URL 方式**（推荐）：
     ```toml
     [database]
     url = "mysql://your_user:***@127.0.0.1:3306/ry-vue"
     ```
   - **结构化方式**（便于切换数据库类型）：
     ```toml
     [database]
     host = "127.0.0.1"
     port = 3306
     username = "your_user"
     password = "your_password"
     database = "ry-vue"
     ```
   - 连接池参数可按需调整：
     ```toml
     max_connections = 20
     min_connections = 5
     connect_timeout = 10
     idle_timeout = 600
     ```

3. （可选）配置主键策略（数据库自增 / 雪花 ID）：
   ```toml
   [id]
   # auto = 数据库自增（默认）
   # snowflake = 应用侧生成雪花 ID
   strategy = "auto"
   worker_id = 1
   datacenter_id = 1
   epoch_ms = 1704038400000
   ```

   **配置项说明：**

   - `strategy`
     - `auto`：使用数据库自增主键
     - `snowflake`：使用应用侧雪花 ID
   - `worker_id`：雪花算法工作节点 ID，多实例部署时每个实例必须不同
   - `datacenter_id`：雪花算法机房/分组 ID，同一分组内 `worker_id` 不能重复
   - `epoch_ms`：雪花算法自定义纪元，所有实例必须保持一致

   **使用说明：**

   - **PostgreSQL**
     - 可以在 **数据库自增** 和 **雪花 ID** 之间切换使用。
     - `strategy = "auto"` 时，主键走数据库自增。
     - `strategy = "snowflake"` 时，主键由应用在写入前生成。
     - 如果初始化数据里插入了显式主键，项目迁移会同步 PostgreSQL 序列，避免后续再走自增时发生主键冲突。

   - **MySQL**
     - 只能把 **数据库自增** 和 **雪花 ID** 当成两种长期方案里的**二选一**。
     - 推荐在项目初始化阶段就决定好，不要在已经跑过大量业务数据后频繁来回切换。
     - 原因是：如果 MySQL 表先写入了较大的雪花 ID，会把 `AUTO_INCREMENT` 计数器一并抬高；之后再切回自增，新的自增值也会继续从很大的位置往上走，也就是常说的“自增被撑大”。
     - 因此：
       - 想保持和原若依最接近、最省心：用 `auto`
       - 想做多实例统一发号、避免依赖数据库自增：从一开始就用 `snowflake`

   - **SQLite**
     - 更建议继续使用 `auto`。
     - `snowflake` 主要面向 MySQL / PostgreSQL 的正式部署场景。

   **补充说明：**

   - 切换 `strategy` 后需要**重启应用**才能生效。
   - 多实例部署时，所有实例的 `epoch_ms` 必须一致，且 `worker_id` 不能重复，否则会产生雪花 ID 冲突。

4. （可选）配置缓存驱动。默认使用本地 `moka`；如需 Redis 二级缓存，修改：

   [cache]
   driver = "redis"
   redis_url = "redis://127.0.0.1:6379/"
   ```

4. （可选）配置对象存储。推荐使用 [RustFS](https://github.com/rustfs/rustfs)（Rust 编写的高性能 S3 兼容对象存储，比 MinIO 快 2.3 倍），同时兼容 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 等。
   - **RustFS / MinIO**（推荐，本地部署首选）：
     ```toml
     [oss]
     enabled = true
     endpoint = "http://127.0.0.1:9000"
     access_key = "rustfsadmin"
     secret_key = "rustfsadmin"
     bucket = "ruoyi"
     region = "us-east-1"
     prefix = "ruoyi"
     path_style = true           # RustFS / MinIO 必须开启
     ```
   - **阿里云 OSS**：
     ```toml
     [oss]
     enabled = true
     endpoint = "https://oss-cn-shanghai.aliyuncs.com/"
     access_key = "your_access_key"
     secret_key = "your_secret_key"
     bucket = "your_bucket"
     region = "cn-shanghai"
     prefix = "ruoyi"
     path_style = false           # 阿里云必须关闭，使用虚拟主机风格
     ```
   - **其他 S3 兼容存储**（腾讯云 COS / 华为云 OBS / AWS S3 等）配置方式类似，替换 `endpoint`、`access_key`、`secret_key`、`bucket`、`region` 即可。

   > **RustFS 快速启动**：参见 [RustFS 官方文档](https://github.com/rustfs/rustfs)，单二进制部署，默认监听 `9000` 端口，默认账号 `rustfsadmin`。

### 4. 编译与运行

确保数据库已启动且 `config/local.toml` 中的连接配置正确后，直接编译并启动：

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

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

> **数据库自动迁移**：首次启动时，程序会通过内置的 `migration` 模块自动执行数据库迁移，创建所需的表结构，无需手动导入 SQL 脚本。

### 5. 前端设置（ruoyi-rust-ui-plus）

本项目配套前端基于 **Vue Vben Admin v5.7.0**，采用 pnpm Monorepo 架构。

1. 进入前端项目目录，安装依赖：
   ```bash
   cd ruoyi-rust-ui-plus
   pnpm install
   ```

2. 启动开发服务器：
   ```bash
   pnpm dev          # 启动 Element Plus 版本
   ```

3. 打开浏览器访问 `http://localhost:5777`（或终端显示的地址）。
   - **默认登录账号**: `admin`
   - **默认密码**: `admin123`

> **前端项目说明**：ruoyi-rust-ui-plus 是 Vue Vben Admin v5.7.0 Monorepo 的一个 app 变体（`apps/web-ele/`），内置了完整的 RuoYi 业务页面适配，包括代码生成、系统管理、监控中心等全部功能模块。样式统一使用 UnoCSS 原子化类编写。

### 6. 代码生成使用指南

为了解决 Rust 开发中结构体编写繁琐、权限宏配置复杂的痛点，本项目内置了全栈代码生成器。

#### 准备工作

在 MySQL 中创建好业务表（务必写好表注释和字段注释，生成器会自动将其转为代码注释）。也可以通过前端的"创建表"功能直接用 SQL 建表。

#### 可视化操作

1. 登录后台，进入 **系统工具 → 代码生成** 菜单。
2. **导入**：点击"导入"按钮，从数据库中选择尚未导入的表。
3. **预览**：点击"预览"按钮，左侧文件树 + 右侧代码展示，实时查看生成的 Rust 和 Vue 代码。
4. **编辑**：点击"修改"按钮，配置字段属性（Rust 类型、查询方式、显示类型、字典绑定），支持拖拽排序。
5. **生成**：选中表后点击"生成"，下载自动打包好的 ZIP 文件。

#### ZIP 包结构

下载的 ZIP 包采用标准结构化设计，解压后包含三个目录：

```
ruoyi.zip
├── backend/rust/modules/{模块名}/src/{业务名}/   # Rust 后端代码
│   ├── mod.rs          # 模块声明
│   ├── model.rs        # 数据模型（Query/Vo/Entity）
│   ├── service.rs      # 服务层（CRUD 业务逻辑）
│   ├── handler.rs      # 处理器（HTTP Handler + 权限注解）
│   └── router.rs       # 路由注册
├── frontend/element/
│   ├── api/{模块名}/{业务名}.ts          # TypeScript API 层
│   └── views/{模块名}/{业务名}/index.vue # Vue 3 页面组件
└── sql/
    └── menu.sql       # 菜单权限 SQL（导入数据库即可）
```

#### 后端代码部署 (Rust)

1. 将 `backend/rust/modules/{模块名}/src/{业务名}` 文件夹拷贝到项目的 `modules/system/src/` 目录下。
2. 在 `modules/system/src/lib.rs` 中添加：`pub mod 你的业务名;`。
3. 在 `modules/system/src/router.rs` 中挂载路由：
   ```rust
   .merge(你的业务名::router::router())
   ```

#### 前端代码部署 (Vben 5)

1. 将 `frontend/element/api/` 下的 `.ts` 文件拷贝到 `apps/web-ele/src/api/` 对应目录。
2. 将 `frontend/element/views/` 下的文件夹拷贝到 `apps/web-ele/src/views/` 对应目录。
3. 在后台"菜单管理"中新建菜单，组件路径填写为 `模块名/业务名/index`（系统会自动解析到 `views/模块名/业务名/index.vue`）。
4. 导入 `sql/menu.sql` 中的菜单权限数据。

> **提示**：生成器已自动处理了 `LONGBLOB/TEXT` 等特殊类型的兼容性映射，并实现了前后端命名契约（SnakeCase vs CamelCase）的自动转换。

## 🏗️ 项目结构

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

```
ruoyi-rust/                          # Workspace 根目录
├── app/                             # 主程序入口 — 组装所有模块、启动 Web 服务器
├── common/                          # 通用基础库 — AppError、AjaxResult、分页模型、认证上下文
├── framework/                       # 核心框架 — 配置、数据库、日志、JWT、缓存、中间件、SeaORM 实体
├── migration/                       # 数据库迁移 — sea-orm-migration 版本化 Schema 管理
├── modules/
│   ├── system/                      # 核心系统模块 — 用户、角色、菜单、部门、字典、参数、通知、岗位
│   ├── monitor/                     # 系统监控模块 — 操作日志、登录日志、在线用户、定时任务、缓存、服务监控
│   ├── oss/                         # 对象存储模块 — 文件上传下载（推荐 RustFS，兼容 MinIO / 阿里云 OSS / 腾讯云 COS / AWS S3）
│   ├── code-tool/                   # 代码生成工具 — 数据库元数据提取、Tera 模板渲染、ZIP 打包
│   └── ruoyi-test/                  # 演示模块 — 功能示例与测试
├── ruoyi-macros/                    # 过程宏库 — #[require_permission(...)] 声明式权限校验
├── config/
│   └── default.toml                 # 默认配置文件
└── sql/                             # 数据库初始化脚本
```

## 📦 部署指南

### 交叉编译（Windows → Linux）

当前推荐准备两套方案，按你的环境选择即可。

#### 方案一：`cross` + Docker（适合追求环境一致、可复用镜像）

该方案**依赖 Docker**。如果你本机已经安装并可正常使用 Docker，可以优先使用这一套。

项目根目录下的 `Dockerfile.cross` 就是给这套方案配套使用的，用于基于 `cross` 官方镜像构建自定义交叉编译环境：

- 基于 `ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main`
- 额外安装 `gcc-12 / g++-12`
- 用来规避部分依赖（如 `aws-lc-sys`）在某些默认工具链下的编译问题
- 首次构建会稍慢，但后续可复用 Docker 缓存，环境更稳定

典型用法：

```bash
# 安装 cross（如未安装）
cargo install cross

# 使用 cross 交叉编译 Linux x86_64
cross build --target x86_64-unknown-linux-musl -p app --release
```

编译产物位于：`target/x86_64-unknown-linux-musl/release/app`

> 如果你要使用这套方案，请注意：`Dockerfile.cross` 与其是配套关系，不建议脱离 Docker 单独理解。

#### 方案二：`cargo-zigbuild` + Zig（更轻便，适合本地直接交叉编译）

如果你不想依赖 Docker，或者更偏向轻量方案，可以使用 `zig` + `cargo-zigbuild`。这一套通常更省资源，安装完成后本地直接编译即可。

Windows 下可按如下方式准备环境：

```bash
winget install zig.zig
cargo install cargo-zigbuild
rustup target add x86_64-unknown-linux-musl
cargo zigbuild --target x86_64-unknown-linux-musl -p app --release
```

编译产物同样位于：`target/x86_64-unknown-linux-musl/release/app`

> 如果只是日常在 Windows 开发机上打 Linux 包，`cargo-zigbuild` 往往比 Docker + cross 更轻便，适合个人开发和快速构建。

#### 其他目标平台

- Linux ARM64：
  - 方案一（cross）：`cross build --target aarch64-unknown-linux-gnu -p app --release`
  - 方案二（zigbuild）：`rustup target add aarch64-unknown-linux-musl && cargo zigbuild --target aarch64-unknown-linux-musl -p app --release`
- Linux x86_64：
  - 方案一（cross）：`cross build --target x86_64-unknown-linux-musl -p app --release`
  - 方案二（zigbuild）：`rustup target add x86_64-unknown-linux-musl && cargo zigbuild --target x86_64-unknown-linux-musl -p app --release`
- Windows：
  - `cargo build -p app --release`
- macOS：
  - `cargo build -p app --release`

### 部署目录结构

建议将“可执行文件、配置覆盖、前端静态资源、日志目录”分开组织，方便后续升级与回滚：

```text
ruoyi-deploy/                        # 部署根目录
├── app                              # 后端可执行文件（从 target/.../release/app 复制）
├── config/
│   ├── default.toml                 # 基础默认配置（从项目 config/ 复制）
│   └── local.toml                   # 生产环境覆盖配置（推荐新增，按需填写）
├── dist/                            # 前端构建产物（从 ruoyi-rust-ui-plus/apps/web-ele/dist 复制）
│   └── ...
└── logs/                            # 日志目录（程序自动创建）
    └── app.log
```

说明：

- 程序会先读取 `config/default.toml`，再按需叠加 `config/local.toml`。
- 因此生产环境更推荐“保留默认配置 + 使用 `local.toml` 覆盖差异项”，而不是直接把 `default.toml` 改成一份难维护的生产专用文件。
- 如果前端由 Nginx 单独托管，`dist/` 也可以不和后端放在同一目录，但文档里的这种结构最直观，适合单机部署。
### 部署步骤

1. **构建前端**（在开发机上）：
   - 修改 `apps/web-ele/.env.production` 中的后端 API 地址：
     ```bash
     # 将以下地址替换为你的实际服务器地址
     VITE_GLOB_API_URL=https://your-domain.com/prod-api
     ```
   - 执行构建命令：
     ```bash
     cd ruoyi-rust-ui-plus
     pnpm install
     pnpm build
     ```
   - 构建产物位于：`apps/web-ele/dist/`

2. **上传文件**：将以下文件上传至服务器
   - 后端可执行文件 `app`
   - 配置文件 `config/default.toml`
   - 前端构建产物 `dist/` 目录

3. **赋予执行权限**（Linux）：
   ```bash
   chmod +x app
   ```

4. **修改配置**：编辑 `config/default.toml`，配置生产环境数据库、缓存等

5. **启动服务**：
   ```bash
   # 直接运行
   ./app
   
   # 或使用 systemd 管理（推荐）
   sudo systemctl start ruoyi-rust
   sudo systemctl enable ruoyi-rust  # 开机自启
   ```

### systemd 服务配置（可选）

创建 `/etc/systemd/system/ruoyi-rust.service`：

```ini
[Unit]
Description=RuoYi Rust Backend Service
After=network.target

[Service]
Type=simple
User=www
WorkingDirectory=/opt/ruoyi-deploy
ExecStart=/opt/ruoyi-deploy/app
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

## 🤝 贡献指南

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

## 📄 许可证 (License)

本项目采用 [MIT License](LICENSE) 开源许可证。

## 交流与赞助

如果有对本项目感兴趣的朋友，欢迎加入 QQ 群一起交流学习，让我们一起变得更强。如果你觉得这个项目帮助到了你，你可以请作者喝杯咖啡表示鼓励 ☕。

**ruoyi-rust 交流 QQ 群: 512670767**

<img src="https://gitee.com/rustdev/ruoyi-rust/raw/master/docs/ali.png" alt="赞助" style="zoom: 18%;width=100px" />

## 🙏 鸣谢

* 感谢原项目 [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue) 提供的优秀设计和前端实现。
* 感谢 [RuoYi-Vue3](https://gitcode.com/yangzongzhuan/RuoYi-Vue3) 提供的 Vue3 前端版本。
* 感谢 [Vue Vben Admin](https://github.com/vbenjs/vue-vben-admin) 提供的现代化 Vue 3 管理模板。
* 感谢 [RustFS](https://github.com/rustfs/rustfs) 提供的高性能 Rust 原生 S3 兼容对象存储，作为本项目默认对象存储方案。