WebShelf：Rust 全栈生产级 Admin 系统，K8s 一键部署 + 自动读写主从数据库

标签: Rust / Axum / Dioxus / 全栈框架 / Admin 系统 / 开源 / PostgreSQL / Redis / Kubernetes / 分布式限流 / JWT / SeaORM
GitHub: https://github.com/aiqubits/webshelf
官网/文档: https://www.openpick.org/webshelf
Crate: https://crates.io/crates/webshelf

一句话定位

WebShelf 是一个生产就绪的 Rust 全栈框架，基于 Axum 后端 + Dioxus 前端（Web/Desktop/Mobile 三端），包含完整认证、数据库集成、分布式锁、分布式限流、灰度发布和 K8s 一键部署能力。

如果说你在找一个用 Rust 写的、能直接上生产的 Admin 脚手架，WebShelf 值得关注。

技术栈：完整 Rust 全端

一句话总结：后端、前端、部署、运维，全链路 Rust 化。

核心功能清单

🔐 认证与权限

• JWT 令牌认证
• Argon2 密码哈希
• 邮箱/密码验证规则
• 密码重置、邮箱验证

🗄️ 数据库

• PostgreSQL 集成
• SeaORM 异步 ORM
• 数据库迁移脚本
• 自动读写主从数据库（见下文）

🔒 分布式能力

• Redis 分布式锁
• Redis 分布式限流
• 中间件栈：Panic 捕获、CORS、Tracing、认证层

🌐 全端前端

• Dioxus/WASM Web 端
• Dioxus Desktop 桌面端
• Dioxus Mobile 移动端
• 统一 UI 组件库

🚀 工程化

• 结构化日志（Tracing）
• TOML 配置 + CLI 参数覆盖
• 单元测试 + 集成测试
• 错误处理、压缩、优雅关闭

🐳 部署与灰度

• Docker Compose 编排
• Kubernetes 完整清单
• 滚动升级 + 金丝雀发布
• CI/CD GitHub Actions

项目结构

webshelf/
├── server/                     # 后端服务 (Rust + Axum)
│   ├── src/
│   │   ├── handlers/           # HTTP 请求处理
│   │   ├── middlewares/        # 中间件：auth、panic、ratelimit
│   │   ├── repositories/       # 数据访问层 (SeaORM)
│   │   ├── routes/             # 路由定义
│   │   ├── services/           # 业务逻辑：auth、user、lock、限流
│   │   ├── utils/              # 配置、错误、日志、验证
│   │   ├── bootstrap.rs        # 应用启动
│   │   ├── lib.rs / main.rs
│   │   └── migrations.rs
│   ├── migrations/
│   └── tests/
│
├── app/                        # 前端应用 (Dioxus)
│   ├── ui/                     # UI 组件库
│   ├── web/                    # Web 端
│   ├── desktop/                # 桌面端
│   └── mobile/                 # 移动端
│
├── crates/                     # 独立 crate
│   ├── distributed-ratelimit/  # Redis 分布式限流
│   └── emailserver/            # SMTP 邮件服务
│
├── nginx/                      # Nginx 反向代理配置
├── k8s/                        # Kubernetes 部署清单
├── docker-compose.yml
├── Dockerfile.server / Dockerfile.web
├── config.toml.example
└── README.md / DEPLOYMENT.md

架构图

┌─────────────────────────────────────────┐
│  Frontend (app/)                       │
│  Web / Desktop / Mobile (Dioxus)       │
├─────────────────────────────────────────┤
│  Nginx 反向代理                         │
│  路由 / 安全头 / 静态资源                 │
├─────────────────────────────────────────┤
│  Backend (Axum)                         │
│  ├─ Middleware: Panic / Auth / RateLimit│
│  ├─ Handlers (REST API)                 │
│  ├─ Services (业务逻辑)                  │
│  ├─ Repositories (SeaORM)               │
│  └─ Redis (分布式锁 / 限流)               │
├─────────────────────────────────────────┤
│  PostgreSQL (主从 / 读写分离)             │
└─────────────────────────────────────────┘

快速开始

环境要求

• Rust 1.92+
• PostgreSQL 16+
• Redis 7+
• Docker / Docker Compose（可选）

本地开发

git clone https://github.com/aiqubits/webshelf.git
cd webshelf
cargo build --release
cargo run --bin server

Docker Compose 一键启动

docker-compose up -d

Kubernetes 一键部署

kubectl apply -f k8s/

K8s 清单包含：

• namespace.yml
• postgres.yml / redis.yml
• webshelf.yml / webshelf-web.yml
• configmap.yml / secret.yml.example
• ingress.yml

API 示例

健康检查

GET /api/health

{
  "status": "ok",
  "version": "0.1.0"
}

注册

POST /api/public/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "name": "User Name"
}

密码规则：

• 最少 8 字符
• 至少 1 个小写字母
• 至少 1 个大写字母
• 至少 1 个数字

登录

POST /api/public/auth/login

{
  "token": "eyJ0eXAiOiJKV1Qi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user_id": "...",
  "role": "user"
}

用户 CRUD

POST   /api/users
GET    /api/users/{id}
PUT    /api/users/{id}
DELETE /api/users/{id}
GET    /api/users?page=1&per_page=10

统一错误响应

所有错误遵循统一格式：

{
  "error": "error_type",
  "message": "Detailed error message"
}

亮点解读

1. 完整全端 Rust 技术栈

很多 Rust 项目只做了后端。WebShelf 把**后端（Axum）、前端（Dioxus）、反向代理（Nginx）、部署（K8s）**都统一在 Rust 或云原生技术栈里，适合想“All in Rust”的团队。

2. 自动读写主从数据库

WebShelf 支持 PostgreSQL 读写分离与主从数据库配置。读请求走从库，写请求走主库，配合 K8s 部署可以 scale 读能力。这是 Admin 系统在高并发场景下的关键能力。

3. 分布式锁 + 分布式限流

基于 Redis 实现：

• 分布式锁：防止并发冲突（如订单处理、库存扣减）
• 分布式限流：保护 API 不被刷爆

已经把限流单独抽成一个 distributed-ratelimit crate，复用性强。

4. 灰度发布

K8s 部署支持滚动升级和金丝雀发布。这意味着：

• 新版本可以先放 5% 流量验证
• 没问题再全量切换
• 出问题快速回滚

5. 多端前端一套 UI 组件库

Dioxus 最大的卖点就是一次写 Rust，输出 Web、桌面、移动端。WebShelf 内置了 ui/ 组件库，包括导航栏、侧边栏、表格、按钮、模态框、Toast 等，Admin 界面常见组件基本都有。

适合谁用？

• 🏢 需要 Rust 技术栈 Admin 系统的团队
• 🚀 想从 0 到 1 快速搭建生产级 Web 服务的开发者
• 🧑‍💻 学习 Rust 全栈工程化实践（Axum + Dioxus + K8s）
• 🏗️ 需要内置认证、限流、锁、日志、部署的脚手架项目

竞品对比

WebShelf 的差异化很明确：Rust 原生 + 全端 + 云原生部署。

总结

WebShelf 把 Rust 后端、Dioxus 多端前端、K8s 部署、PostgreSQL 读写分离、Redis 分布式锁/限流整合到了一个项目里。它不是简单的 Demo，而是可以直接拿去改一改上生产的 Admin 脚手架。

如果你正在用 Rust 做 Web 服务，或者想找一套工程化比较完整的 Rust 全栈方案，WebShelf 可以作为一个不错的起点。

相关链接

• GitHub: https://github.com/aiqubits/webshelf
• 官网: https://www.openpick.org/webshelf
• Crate: https://crates.io/crates/webshelf
• License: MIT

Keywords: WebShelf, Rust 全栈, Axum, Dioxus, Admin 系统, 分布式锁, 分布式限流, Kubernetes, PostgreSQL 读写分离, Redis, SeaORM, JWT, Argon2, 生产就绪, 开源项目