Rust 版说明(RuYi Panel Rust Edition)
如意面板目前提供 Python(Django) 与 Rust 两种后端版本,二者共存:
- Python 版:经典版本,基于 Python 3 + Django,社区使用广泛,文档与生态资料最全
- Rust 版:新一代主线下文版本,基于 Rust(Axum + Tokio)重写后端,完整兼容 Python 版的 Web 前端与 API 契约。Django 侧已停止新功能开发(收尾状态),此后表结构、Web 面板与新功能均在 Rust 版上独立演进
两种版本使用同一套 Vue3 + Vite + Element Plus 前端,界面与操作体验完全一致。
核心特性
- 零依赖部署:单一原生可执行文件,无需安装 Python 运行时与 pip 依赖,启动更快
- 极低内存占用:实测稳态内存占用仅 10~20MB,约为 Python 版(空闲约 80MB)的 1/4 ~ 1/8,小内存服务器/软路由/NAS 也能轻松运行
- API 完全兼容:
/api/<module>/路由、响应格式、JWT 认证、多库 SQLite 布局均与 Django 版一致,前端无需改造 - Manager / Agent 双进程架构:Manager 提供 Web/API 服务,Agent 独立运行并负责计划任务调度、监控自动采集、多节点安全巡检、磁盘自动清理;Manager 通过受限本机 IPC 将已授权操作交给 Agent,Agent 独占调度锁并持久化执行状态,避免重复调度
- 跨服务器 Agent 通道:Manager 与 Agent 之间使用独立的 bootstrap CA + 按权限 scope 授权的 mTLS 业务通道,邀请需目标节点管理员批准后激活
- 签名升级体系:发布包使用 Ed25519 签名(
ruyi_rust.zip+.sig),在线/离线升级均先验签,解压前检查版本、平台、Agent IPC 协议与数据库迁移清单,启动失败自动回滚;data/与logs/不被升级包覆盖 - 首次启动全自动初始化:等价原版
manage.py init,自动生成密钥/端口/安全入口/根 CA 与面板证书(默认启用 HTTPS),建库建表并写入默认数据,初始管理员账号输出到启动日志与data/init_account.txt
技术架构
| 项目 | 说明 |
|---|---|
| 后端语言 | Rust(stable,edition 2021) |
| Web 框架 | Axum 0.8 + Tokio 异步运行时 |
| 数据库 | 多库 SQLite(default / logs / tasks / monitor / waf / ai 等,别名与 Django 版一致) |
| 前端 | Vue3 + Vite + Element Plus(源码位于仓库 web/,构建产物输出到后端托管目录 dist/) |
| 数据库结构演进 | 内嵌基线结构(163 个对象)+ 幂等增量迁移(每库 _migrations 表记录版本),启动时自动应用,老数据零迁移 |
关键配置
| 配置项 | 默认值 | 覆盖方式 |
|---|---|---|
| 数据目录 | ./data | 环境变量 RUYI_DATA_DIR |
| 前端静态目录 | ./dist | 环境变量 RUYI_DIST_DIR |
| 监听端口 | 6789 | {数据目录}/port.ry 文件内容 |
| JWT 密钥 | 内置回退密钥 | {数据目录}/secret_key.ry 文件内容 |
| 可信反向代理 | 不信任任何代理 | 环境变量 RUYI_TRUSTED_PROXIES(逗号分隔 IP/CIDR,命中时才解析 X-Forwarded-For) |
| headless 模式 | 关闭 | 存在 data/web_off.ry 标志文件时不启动 Web/API/终端,Agent 继续运行(端口零暴露) |
| 面板 SSL | 空目录首启自动生成并启用 HTTPS | data/ssl.ry 标志 + data/key/{privateKey,certificate}.pem |
运行与服务管理
- Linux:安装器创建
ruyi.service与ruyi-agent.service两个 systemd 服务;ruyi-cmd(装到/usr/local/bin/ruyi-cmd)提供 start / stop / restart / status / weboff / webon 命令。计划任务、监控采集等由 Agent 执行,单独重启 Manager 不会使 Agent 退出 - Windows:
ruyi-service.ps1注册低权限 Manager 服务与 LocalSystem Agent 服务;Windows 升级请求经固定 IPC 交给 LocalSystem Agent 在私有目录验签后执行 - 日志布局:与 Django 版一致,站点/软件日志及任务执行日志在
/ruyi/logs/(任务输出在/ruyi/logs/ruyitask/);面板运行日志(server.log 等)写入程序所在目录logs/(可用RUYI_PANEL_LOG_DIR覆盖)
安装与升级
- Linux:通过 在线安装 页面一条命令安装(Rust 版安装器为
install_ry_rust.sh),支持 x86_64 与 ARM64(manylinux2014,glibc 基线 2.17) - Windows:图形化安装包,安装后可用
ruyi-service.ps1注册系统服务 - 在线升级:面板内检查更新,自动下载
ruyi_rust.zip与.sig验签后升级,失败自动回滚 - 离线升级:在【面板设置】-【关于面板】中同时上传 ZIP 与
.sig两个文件 - 卸载(Linux):
ruyi-cmd uninstall默认保留数据(data/、站点配置与证书、网站、备份、日志等);--remove-swap同时移除 swap;--purge彻底清理/ruyi(需输入DELETE /ruyi确认)
Python 版与 Rust 版对比
| 维度 | Python 版(Django) | Rust 版 |
|---|---|---|
| 运行依赖 | Python 3.12+ 及 pip 依赖 | 单一原生可执行文件,无运行时依赖 |
| Web 框架 | Django | Axum + Tokio |
| 数据库 | 多库 SQLite | 多库 SQLite(结构兼容,含自动迁移机制) |
| 前端 | Vue3 + Vite + Element Plus | 同一套前端,完全复用 |
| API 契约 | /api/<module>/ + JWT | 与 Python 版一致 |
| 进程模型 | 单进程(start.py) | Manager + Agent 双服务 |
| 升级机制 | 常规升级包 | Ed25519 签名验签 + 回滚保护 |
| 维护状态 | 收尾(仅维护) | 主线,持续演进 |
| 内存占用 | 稳态约 116MB(空闲约 80MB) | 实测仅 10~20MB |
老用户升级建议
已有 Python 版用户升级到 Rust 版后,数据目录结构与数据库布局保持兼容;首次启动只补齐缺失对象,不会改动已有数据。升级前请照常备份面板数据。
源码仓库
Rust 版后端与前端源码在 ruyi-rust 仓库中独立演进,Python 版(RuYi-Panel)仓库继续保留供社区查阅。
