Skip to content

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空目录首启自动生成并启用 HTTPSdata/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 框架DjangoAxum + 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)仓库继续保留供社区查阅。

Released under the 如意开源许可协议.