- 多前端适配:同时提供
Vue3 Vben(Ant Design Vue)、Vue3 Element Plus、React19 Antd三套前端,满足不同团队偏好 - 企业级 RBAC:支持多租户、多角色、多部门、菜单/按钮/数据级权限控制
- 契约驱动的代码生成:Protobuf 是唯一 API 契约——构建期确定性生成 291 条路由、491 条错误状态映射、602 个服务接口(按 RPC 声明数计),零手写路由;前端 TypeScript 客户端三份字节相同
- 安全与等保合规:按等保 2.0 技术要求内置 180 天审计日志留存归档、口令策略三件套、TOTP MFA、口令应用层加密、动态 RBAC 与多租户隔离,详见安全与等保合规
- 生产就绪基座:JWT RS256 鉴权、统一四字段错误信封、CORS、SSE 消息推送(:7789 /events)、异步任务队列(Postgres 队列 worker + cron 生产者)
- 质量门禁:契约同步门 + 三道前端快照门 + fmt / clippy / test,七道 CI 检查(ubuntu + windows 矩阵)
| 前端版本 | 演示地址 |
|---|---|
| Vue3 Vben | https://vben.admin.gowind.cloud |
| Vue3 Element Plus | https://ele.admin.gowind.cloud |
| React | https://react.admin.gowind.cloud |
- 后端 Swagger:https://api.demo.admin.gowind.cloud/docs/
- 默认账号密码:
admin/Abcd@1234
三套前端与本仓后端零改动对接,以下界面截自本仓后端(REST :7788)与 React 版前端:
登录 —— 图形验证码 + 租户编号(留空为平台登录),口令在应用层加密后传输
仪表盘 —— 用户 / 角色 / 登录与操作审计实时统计,含登录趋势与占比分布
用户管理 —— 组织树 + 高级查询,支持多角色、多部门、状态与主管配置
菜单管理 —— 目录 / 菜单 / 按钮三类节点,权限标识与路由、组件路径一一对应
操作审计日志 —— 操作类型、资源定位与请求 ID 全程留痕,成功失败均可追溯
在线用户 —— 会话与设备视图,支持强制下线
后端自带 API 文档服务(server.yaml 的 enable_swagger / enable_redoc 开关,原始规格见 /q/openapi.yaml),服务启动后即可访问,无需另行部署文档站点。
Swagger UI —— /q/swagger-ui:全量接口按服务分组,带鉴权入口,可直接在线调试
ReDoc —— /q/redoc:三栏式接口文档,参数说明与请求 / 响应示例并列呈现
| 层级 | 技术 |
|---|---|
| 后端框架 | Rust(edition 2021 / MSRV 1.81) · RushWind 框架 · axum 0.8 · tokio |
| 契约链 | Protobuf · buf + protox · prost / prost-reflect / pbjson · rushwind-gen-http(路由生成) |
| 存储层 | SeaORM · PostgreSQL · Redis(会话 / 验证码 / 发布订阅) |
| 认证授权 | JWT RS256(rushwind-authn-jwt) · 动态 RBAC(策略存库,热更新) |
| Vue Vben 版 | Vue 3 · TypeScript · Vite · Ant Design Vue · Vben Admin |
| Vue Element 版 | Vue 3 · TypeScript · Vite · Element Plus(轻量纯净版) |
| React 版 | React 19 · TypeScript · Vite · Zustand · Ant Design V6(无 UMI) |
| 质量门禁 | cargo fmt / clippy / test · GitHub Actions(ubuntu + windows 矩阵) |
Protobuf 是唯一 API 契约:路由、错误状态表、服务接口、挂载胶水、前端 TypeScript 客户端全部在构建期从契约确定性生成,仓库里没有一条手写路由;契约改一处,后端与三套前端同时生效。
backend/apps/admin/api/protos/ proto 契约·admin 树(唯一事实源,MANIFEST 校验门,禁手改)
backend/apps/admin/api/fork/ proto 契约·fork 模块树(fork 自有,自由编辑)
│ 一个 buf 工作区编译出一份注解描述符(一池一类型)
▼
backend/apps/admin build.rs 构建期生成(crate::proto 面)
├── ROUTES 路由表(291 条,含 additional_bindings)
├── 错误状态表(491 条 reason → HTTP 状态映射)
├── 服务 trait(59 个服务面 · 286 个方法)+ mounts 挂载胶水
└── protojson 编解码(金样测试锁定)
▼
src/admin/ 手写服务实现挂到生成的 trait 上(上行同步落点)
src/modules/ fork 业务模块(copy-rename template 起步)
浏览器 → edge(CORS / 请求预算)→ 绑定层(protojson body + form query,绑定失败即 400,先于鉴权)
→ 鉴权门(JWT RS256 验签 + Redis 会话检查 → 租户检查 → authz 授权评估)
→ 生成 handler → Service(业务逻辑)→ Repo(查询谓词由 Viewer 派生)
→ 数据层租户规则(平台视图全见 / 租户视图强制 tenant_id / 系统视图旁路)→ PostgreSQL
横切关注点不写进业务代码:认证在鉴权门、行级隔离在 Viewer 派生的查询谓词、字段级权限在服务端响应裁剪、六类审计在中间件层——业务代码“看不见”它们,但每条路径都在覆盖之下。
| 通道 | 端口 | 用途 |
|---|---|---|
| REST | :7788 | 全部管理面路由 |
| SSE | :7789 /events |
站内信 / 通知服务端推送,流按用户归属校验,连接独立鉴权 |
| 任务 worker | —(无监听端口) | 消费 Postgres 队列:消息广播扇出、审计归档、定时备份等异步任务 |
| cron 生产者 | —(无监听端口) | 周期投递任务:租户到期扫描、审计归档、sys_tasks 表驱动的用户任务 |
| 位置 | 产生方式 | 能否手改 |
|---|---|---|
backend/apps/admin/api/protos/** |
sync-protos.sh 从契约源同步(MANIFEST 校验门) |
❌ 改契约源后重新同步 |
backend/apps/admin/api/fork/protos/** |
fork 自有契约树 | ✅ 模块契约面 |
backend/apps/admin/src/proto 生成面 |
build.rs 构建期确定性再生 |
❌ |
前端 src/api/generated/** |
从契约生成的 TypeScript 客户端 | ❌ |
backend/apps/admin/src/admin/services/**、backend/apps/admin/src/admin/data/** |
手写业务逻辑与数据层(上行同步落点) | fork 只读 |
src/modules/** |
fork 业务模块 | ✅ |
逐层拆解与机制细节见教程第一章:架构全景。
本项目的安全能力参照《网络安全等级保护 2.0》(二级/三级)技术要求设计,面向企业高隐私私有化部署场景开箱即用:
| 等保技术要求 | 落地实现 |
|---|---|
| 安全审计 | 六类审计日志全覆盖:登录 / 操作 / API / 数据访问 / 权限变更 / 策略评估,记录 IP 归属地与 trace_id;留存与归档策略可调(默认库内留存 180 天,超期数据导出 JSONL 归档文件留痕) |
| 身份鉴别 | 口令复杂度(≥8 位、小写/大写/数字/符号四类取三)、历史口令复用检查(默认近 3 条)、口令有效期(默认 90 天),阈值经「参数管理」平台参数调整;TOTP 多因素认证(MFA);图形验证码;登录失败限流(IP + 用户名双维度);可配置登录限制策略 |
| 访问控制 | 动态 RBAC 权限引擎,角色—权限—接口映射存于数据库,权限变更即时热更新生效;菜单/按钮级权限控制,角色级行数据权限范围与字段级权限(黑名单字段自响应裁剪);每次鉴权判定落策略评估日志可追溯 |
| 多租户隔离 | 存储层数据隔离:读查询自动注入租户过滤,写入防伪造租户、更新/删除强制租户谓词;租户请求按 (path, method) 经 Api 表 fail-closed 校验(缺权限点即拒绝);套餐模块白名单与到期只读策略 |
| 数据保密性 | 登录口令应用层 AES 加密传输、bcrypt 哈希存储;JWT RS256 非对称签名;refresh token 走 HttpOnly Cookie;传输层 TLS 由部署层启用 |
| 数据备份恢复 | 定时全量备份(pg_dump,默认保留 30 份自动轮换),支持 Docker 容器 / 本地直连双模式 |
| 前端安全 | 三套前端生产构建均启用 CSP、X-Frame-Options、HSTS 等安全响应头 |
说明:等保测评除技术要求外,还包含管理制度、物理环境、人员组织等非软件范畴的内容。本项目覆盖的是技术措施部分,可为私有化部署的等保测评准备提供直接支撑,但不能替代完整的等保测评流程。
项目按 docs/development-plan.md 的阶段推进,契约面已完成,服务实现按模块渐进落地。
已落地
- 契约流水线:proto 同步(MANIFEST 校验门 + 漂移检测)→ 注解描述符 → 构建期确定性生成路由 / 错误状态表 / 服务接口 / 挂载胶水
- REST :7788 装配:291 条路由、8 个免鉴权端点白名单、JWT RS256 鉴权门、CORS、统一四字段错误信封(code / reason / message / metadata)
- 编解码对齐:protojson 请求绑定与响应发射(64 位整数字符串化、presence 省略、well-known 类型语义),金样测试锁定
- 真实服务实现覆盖全部组织 / 权限 / 认证 / 消息 / 审计 / 监控域,并完整移植 ce8ab49 vintage 的新域:OIDC SSO 单点登录与租户白标、通知偏好与模板、渠道扩展(39 个 EXT 渠道 schema 注册表 + settings 存取)、监控告警(阈值评估器 + 冷却/恢复状态机)、系统任务巡检、BI 仪表盘(乐观锁 + 内置模板)、打印模板(服务端 HTML→PDF 渲染)、AI 全域(提供商 / 对话 / 消息 / 用量 / 知识库 RAG / Agent 图引擎 / 内容生成)
- NL2SQL(智能问数)按显式边界声明 NOT_IMPLEMENTED:其四重只读护栏链(表白名单 / LIMIT 钳制 / 语句只读校验 / 租户后置 fail-closed)须整链落地后才放行生成 SQL 执行
进行中 / 规划
- 出站投递:SMTP / WEBHOOK / SMS 三渠道真实 sender 与台账实投已上线(EXT 渠道待接);告警周期扫描、事务性邮件按用户偏好语言渲染仍在路上
- 站内信的实时 SSE 下发已接入(消息管理发送面,指定收件人与全员直发均随投随推);通知规则 / 告警触发面与全员广播队列投递的 SSE 下发、审计日志归档导出仍在路上
- 文件域入知识库(UploadDocFile)
| 工具 | 版本 |
|---|---|
| Rust | stable(workspace rust-version = 1.81) |
| buf | 最新版(`curl -fsSL https://buf.build/install.sh |
| bash | 运行同步脚本(Windows 推荐 Git Bash) |
| Docker | 20.0+(本地中间件) |
| Node.js + pnpm | 以各前端 package.json 的 engines 为准(当前约束交集 ≥ 20.19.0),pnpm >= 10.0.0 |
框架与工具库依赖(RushWind 框架、rust-utils)以 Git 依赖按 revision 钉死,clone 本仓即可构建,无需兄弟仓。仅当需要本地迭代框架仓时,才将 rushwind/ 克隆到同级目录,并通过 workspace 的 [patch] 段临时指向本地路径(框架贡献者工作流)。
cd backend
cargo run -p admin # 二进制 admin,监听 REST :7788(+ 业务模块面同进程)- 启动时连接 PostgreSQL 与 Redis,配置位于
backend/apps/admin/assets/(auth.yaml/data.yaml/oss.yaml) assets/jwt_public_key.pem与auth.yaml内嵌密钥为演示密钥,生产部署必须更换- 启动序列:迁移 → 种子 → REST(:7788)+ SSE(:7789,
/events)+ 任务 worker + cron 四个 transport 一并起
proto 契约由脚本从上游契约源同步进本仓,并加 MANIFEST 校验门防止手改:
bash backend/apps/admin/api/sync-protos.sh # 同步 proto 并重建 MANIFEST
bash backend/apps/admin/api/sync-protos.sh --check # 校验门(与 CI 一致)同步源的默认路径与覆盖方式见脚本头部说明(backend/apps/admin/api/sync-protos.sh)。不要手改 backend/apps/admin/api/protos/。
cd backend
cargo fmt -p auth -p admin -p admin-diff -p biz-proto-build -- --check
cargo clippy --workspace -- -D warnings
cargo test --workspaceCI(ubuntu + windows 矩阵)执行同样的七道检查:契约同步校验(proto MANIFEST)、三道前端快照校验、fmt / clippy / test,见 .github/workflows/ci.yml。
前端与后端是零改动兼容契约:API 基址指向本仓后端(REST :7788)即可,无需改动任何前端代码。三套前端均随本仓同步(同步快照 + RushWind 品牌覆写层 + 双清单校验门防手改),dev 代理默认已指向 :7788:
| 前端版本 | 目录 | 状态 | 启动命令 | 端口 |
|---|---|---|---|---|
| React | frontend/admin/react |
✅ 随仓快照 + 品牌覆写 | pnpm dev |
15888 |
| Vue Element | frontend/admin/vue-element |
✅ 随仓快照 + 品牌覆写 | pnpm dev |
15777 |
| Vue Vben | frontend/admin/vue-vben |
✅ 随仓快照 + 品牌覆写 | pnpm dev |
15666 |
# React 版(本仓 frontend/admin/react)
cd frontend/admin/react
pnpm install
pnpm dev # :15888,代理转发至 REST :7788
# Vue Element 版(本仓 frontend/admin/vue-element)
cd frontend/admin/vue-element
pnpm install
pnpm dev # :15777,代理转发至 REST :7788
# Vue Vben 版(本仓 frontend/admin/vue-vben)
cd frontend/admin/vue-vben
pnpm install
pnpm dev # :15666,代理转发至 REST :7788全部功能在单应用(apps/admin)内交付,三套前端功能同构,以下按组织与权限 / 系统功能 / 消息与日志 / 个人中心四组列出。
各列表页(业务数据与审计日志)均支持按当前筛选条件分页聚合导出,格式可选 CSV / XLSX(上限 1 万行)。后端各模块的实现覆盖情况见当前进度。
| 功能 | 说明 |
|---|---|
| 用户管理 | 管理和查询用户,支持高级查询和按部门联动用户,用户可禁用/启用、设置/取消主管、重置密码、配置多角色、多部门和上级主管、一键登录指定用户等功能 |
| 租户管理 | 管理租户,新增租户后自动初始化租户部门、默认角色和管理员。支持配置套餐、禁用/启用、一键登录租户管理员、租户回收站(删除即入回收站,平台门禁查看/恢复/彻底清除,purge 全域级联)功能 |
| 套餐与配额管理 | 管理租户订阅套餐及其资源配额(如模块白名单、用量上限),支持套餐与配额项的增删改查 |
| 角色管理 | 管理角色和角色分组,支持按角色联动用户,设置菜单授权、数据权限范围(五档 / 自定义组织单元集)与字段级权限(黑名单字段集),批量添加和移除员工;支持父子角色权限继承(子角色权限集必须落在父角色已授予集合内,改父/改权双向重对齐,沿父链防环) |
| 权限管理 | 管理权限分组、菜单、权限点,支持树形列表展示 |
| 组织管理 | 管理组织,支持树形列表展示 |
| 职位管理 | 用户职务管理,职务可作为用户的一个标签;支持 Excel 导入(客户端模板下载、逐行走既有创建接口、行级错误回报,所属组织列按组织名称精确匹配回填组织单元) |
| 菜单管理 | 配置系统菜单,操作权限,按钮权限标识等,包括目录、菜单、按钮;支持菜单同步(三端齐备,事务化清空重建或增量合并两种模式,合并模式按全路径匹配原位更新并保留既有菜单 ID 与角色授权) |
| 功能 | 说明 |
|---|---|
| 接口管理 | 管理接口,支持接口同步功能,主要用于新增权限点时选择接口,支持树形列表展示、操作日志请求参数和响应结果配置 |
| 字典管理 | 管理数据字典大类及其小类,支持按字典大类联动字典小类、服务端多列排序、数据导入和导出 |
| 任务调度 | 管理和查看任务及其任务运行日志,支持任务新增、修改、删除、启动、暂停、立即执行 |
| 文件管理 | 管理文件上传,支持文件查询、上传到 OSS 或本地、下载、复制文件地址、删除文件、图片支持查看大图功能 |
| 登录策略 | 管理登录限制策略,配置目标用户的限制类型、限制方式、限制值与限制原因 |
| 账号登录 | 支持用户名 / 邮箱 / 手机号多标识登录,可叠加图形验证码、登录策略与 TOTP 多因素认证;支持 OIDC 单点登录(SSO_OIDC_* 环境开启,discovery 缓存 + state 单次防重放 + 邮箱映射本地账号,可自动预置)与租户白标查询(登录前按租户编号取名称 / Logo,未命中与未配置同样回答防枚举) |
| 多因素认证(MFA) | 基于 TOTP 的多因素认证,含登录挑战、个人中心绑定管理,以及管理员救援重置用户 MFA 的解锁路径 |
| 找回密码 | 绑定邮箱验证码找回密码:验证码 10 分钟单次有效、重置成功即吊销全部会话,静默处理防用户枚举 |
| 通知渠道 | 管理通知渠道(EMAIL / WEBHOOK / SMS 与 39 个 EXT 扩展渠道),扩展渠道配置整包按 schema 动态渲染(敏感字段加密落库、回显脱敏、留空保留),测试发送前按类型做配置在场预检 |
| 通知模板 | 平台全局 {{var}} 占位模板管理,编码全局唯一,支持按变量集试渲染(未识别占位符按名报错) |
| 通知偏好 | 用户自助静音时段(支持跨零点窗口)与站内信分类退订,读写锚定为当前操作人 |
| 服务监控 | 只读展示服务运行时指标(CPU 核数、内存、运行时长等),自动刷新 |
| 脚本系统 | 脚本级插件系统(Lua / JavaScript,数据库为事实源,管理页增改即时生效):实体生命周期钩子(before 可否决 / after 异步)、定时任务、HTTP 出站(域名白名单 fail-closed)、试运行与执行日志 |
| 参数管理 | 平台全局系统参数的键值管理(区别于业务字典),内置参数启动时播种、禁删可改;服务侧经缓存 accessor 读取,多实例部署下参数变更经 Redis 发布订阅广播失效各实例缓存 |
| 机器凭证(AK/SK) | 租户级 AccessKey / SecretKey 管理:创建时 Secret 一次性展示,支持启停、删除与密钥轮换重置(轮换后旧 Secret 立即失效);AK / Secret 可经令牌交换端点换取租户作用域机器 JWT(machine 角色、仅签发 access 令牌),交换端点按 IP + AK 接入尝试限流 |
| BI 仪表盘 | 管理设计器产出的仪表盘 / 大屏 / 模板,设计器 schema 原文透传,编码租户内唯一,更新带乐观锁版本校验,内置模板禁删、复制派生一键成租户资产,启动播种基线模板 |
| 打印模板 | 打印模板管理 + 服务端 PDF 渲染:前端内核产出最终文档 HTML,后端经本机 Chrome/Edge(CHROME_PATH 探测 / Edge 兜底)零边距打印,"预览即所得",后端不重排不解析模板 |
| 监控告警 | 指标阈值告警规则(goroutine / 内存 / DB 连接 / DB 连通 / Redis 容量),手动立即评估;告警→恢复成对通知、持续越限按冷却重发、采集失败轮不清 firing 状态(抖动不是恢复) |
| 系统任务巡检 | 系统级常驻任务只读巡检:调度条目(cron / 上次 / 下次入队)+ 各任务类型队列状态与最近失败明细,worker 未起过时回答空面而非报错 |
| AI 助手 | LLM 提供商管理(OpenAI 兼容 / 本地模型,API Key 加密落库 + 脱敏回显)、对话与消息、知识库(文档切片向量化入库、pgvector 余弦检索)、Agent 应用(五节点图编排引擎:start / knowledge / llm / condition / end,模板与条件表达式、执行轨迹与 token 用量落库)、内容生成(四场景)、用量台账与月度汇总 |
| 语言管理 | 管理系统支持的多语言,配置语言名称、语言代码、本地名称、启用与默认状态 |
| 功能 | 说明 |
|---|---|
| 消息分类 | 管理消息分类,支持 2 级自定义消息分类,用于消息管理消息分类选择 |
| 消息管理 | 管理消息,支持按发送范围(全员 / 指定用户)发送与消息撤销,全员广播走异步任务队列投递(断点恢复、幂等),可查看用户是否已读和已读时间 |
| 站内信 | 站内消息管理,支持消息详细查看、删除、标为已读、全部已读功能 |
| 登录日志 | 登录日志列表查询,记录用户登录成功和失败日志,支持 IP 归属地记录 |
| 操作日志 | 操作日志列表查询,记录用户操作正常和异常日志,支持 IP 归属地记录与资源对象定位,查看操作日志详情 |
| API 日志 | API 日志列表查询,记录 API 请求的操作者、请求路径、方法与成功状态,支持 IP 归属地记录 |
| 数据日志 | 数据访问日志列表查询,记录数据访问行为,SQL 词法脱敏,自动提取涉及表名与数据分类 |
| 权限日志 | 权限变更日志列表查询,记录权限变更的操作者、目标对象与原因,留存请求快照 |
| 策略评估日志 | 策略评估日志列表查询,记录每次鉴权判定的结果与评估上下文,支持 trace_id 关联排障 |
| Redis 缓存监控 | Redis 缓存监控,只读展示 Redis INFO、DBSIZE 与慢日志数据,不执行写操作 |
| 功能 | 说明 |
|---|---|
| 个人中心 | 个人信息展示和修改,查看最后登录信息,密码修改、邮箱绑定 / 换绑(验证码校验)等功能 |
rushwind-admin/
├── backend/
│ ├── crates/
│ │ ├── auth/ # 鉴权门(框架 crate:门状态钉字面量,等值守卫在 app 侧)
│ │ └── biz-proto-build/ # 契约构建引擎(manifest_dir/api 布局,单池多 face)
│ ├── testbed/
│ │ └── admin-diff/ # URL 驱动的差分台架(对拍 Go 参考实现;corpus/exemptions/compose 同址)
│ └── apps/
│ └── admin/ # ★ 唯一的产品应用:一个 crate,一个二进制
│ ├── api/ # 应用的契约工作区(一个 buf.yaml + 一个 buf.lock)
│ │ ├── protos/ # admin 契约树(★ 上行同步落点,MANIFEST 校验门)
│ │ ├── fork/protos/ # fork 模块契约树(★ fork 自有,自由编辑)
│ │ └── sync-protos.sh # 契约同步与校验脚本
│ ├── src/
│ │ ├── main.rs # 装配:迁移链→种子→route packs→cron/sse/tasks(每模块四行)
│ │ ├── proto/ # 契约面(生成:类型/池/gen 各 face)
│ │ ├── admin/ # ★ 上行同步机房:59 服务 + 数据层 + 路由边 + 审计(fork 只读)
│ │ └── modules/ # ★ fork 自有的一切(copy-rename template 起步)
│ └── tests/ # 线契约守卫 + 模板守卫 + 等值守卫
├── frontend/ # 三套前端同步快照(sync-frontend.sh + 双清单门 + RushWind 品牌覆写)
├── docs/ # 项目文档(教程 tutorial / 索引 README / binding-spec / development-plan / operator-matrix / screenshots)
└── .github/workflows/ # CI(契约同步门 + 三道前端快照门 + fmt / clippy / test)
所有权一句话:上行同步只落 src/admin/ 与 api/protos/;你的一切代码活在 src/modules/、api/fork/protos/ 和 main.rs 的装配行里。
教程与参考文档体系从 docs/README.md 进入:
- 教程层(docs/tutorial/)—— 九章渐进:架构全景 → 从零跑起来 → 契约与生成链路 → 第一个服务模块 → 权限模型 → 多租户与行级隔离 → 审计与等保 → 部署上线 → 写你的第一个业务模块(fork 工作流)
- 参考层 —— binding-spec(线上字节契约基准)等工程档案,动对应子系统前必读
- rushwind —— RushWind 框架 monorepo(http / http-binding / authn / transport-axum / gen-http 等)
- rust-utils —— Rust 工具库(
query_parser等)
欢迎参与 RushWind Admin 的建设:
- 微信个人号:
yang_lin_bo(备注:rushwind-admin) - 掘金专栏:https://juejin.cn/column/7541283508041826367
感谢 JetBrains 提供的免费开源授权。







