基于 Hono v4 + React 19 + Semi Design v2 + Drizzle ORM 的全栈后台管理系统，覆盖认证授权、组织架构、系统配置、通知公告、日志审计、在线会话、定时任务、文件管理与运行监控等后台场景。
项目采用 npm monorepo 结构：后端使用 Hono + PostgreSQL 提供 API 服务，前端使用 React 19 + Vite + Semi Design v2 构建后台界面，shared 包统一维护前后端共享类型、常量与 Zod 校验 schema。
- 文档站：https://iwangbowen.github.io/zenith-admin/
- 演示站：https://iwangbowen.github.io/zenith-admin/demo/（账号
admin/ 密码123456，无需后端）
Zenith Admin 专为 AI 辅助开发场景设计，提供开箱即用的 AI 集成机制，让 GitHub Copilot、Claude、Cursor 等工具在生成代码时能精准理解项目约定。
| 文件 / 目录 | 用途 |
|---|---|
AGENTS.md |
AI 工具的"项目说明书"，包含架构约定、常用命令与注意事项 |
.claude/skills/zenith/ |
Zenith CRUD Skill：完整的模块开发工作流，一句话触发自动化生成 |
在支持 Skills 的 AI 工具（如 GitHub Copilot）中直接描述需求，即可自动完成 Schema → 迁移 → 类型 → 路由 → 前端页面 → Mock 数据的全流程生成：
实现「商品分类」的 CRUD 管理功能
详细说明参见文档站：AI 辅助开发。
| 层级 | 技术 |
|---|---|
| 后端框架 | Hono v4 + Node.js |
| 前端框架 | React 19 + Vite 6 |
| UI 组件库 | Semi Design v2 |
| 图标体系 | lucide-react |
| 数据库 ORM | Drizzle ORM + PostgreSQL |
| 会话持久化 | Redis（ioredis） |
| 前端路由 | React Router v7 |
| 参数验证 | Zod（前后端共享） |
| 认证方案 | JWT Bearer Token（7 天有效期） |
| 会话机制 | Access Token + Refresh Token 自动续期 |
| 实时通信 | WebSocket |
| 文件存储 | 本地存储 / 阿里云 OSS |
| 包管理器 | npm（monorepo） |
zenith-admin/
├── packages/
│ ├── server/ # Hono 后端服务
│ │ ├── src/
│ │ │ ├── routes/ # API 路由（认证、用户、部门、岗位、角色、菜单、字典、日志、监控、会话、定时任务等）
│ │ │ ├── db/ # Drizzle schema、迁移与种子数据
│ │ │ ├── lib/ # 验证码、文件存储、日志、权限、WebSocket、定时任务调度等能力封装
│ │ │ └── middleware/ # 日志、认证与权限中间件
│ │ └── drizzle/ # 数据库迁移文件
│ ├── web/ # React 前端
│ │ └── src/
│ │ ├── pages/ # 页面组件（登录、仪表盘、个人中心、组织与系统管理、日志、监控等）
│ │ ├── layouts/ # AdminLayout 主布局与导航容器
│ │ ├── components/ # 公共组件（图标选择器、进度条、Cron 表达式构建器等）
│ │ ├── hooks/ # 认证、主题、偏好设置、标签页、WebSocket 等 hooks
│ │ └── utils/ # 请求封装、日期格式化、图标映射等工具
│ └── shared/ # 前后端共享类型、常量与 Zod schema
└── package.json # Monorepo 根配置
- Node.js >= 18
- PostgreSQL（本地或远程）
- Redis（本地或远程，用于会话持久化）
npm install在 packages/server/ 下创建 .env 文件：
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/zenith_admin
JWT_SECRET=your-secret-key
PORT=3300
# Redis 连接（URL 格式，支持带密码）
REDIS_URL=redis://127.0.0.1:6379
# REDIS_KEY_PREFIX=zenith: # 所有 Redis key 的命名空间前缀（默认 zenith:）在 packages/web/ 下创建 .env 文件（可选，有默认值）：
VITE_API_BASE_URL=http://localhost:3300
VITE_APP_TITLE=Zenith Admin# 执行迁移
npm run db:migrate
# 填充初始数据（创建 admin 账号等）
npm run db:seed# 同时启动前端 + 后端
npm run dev
# 或分别启动
npm run dev:server # 后端：http://localhost:3300
npm run dev:web # 前端：http://localhost:5373# 本地开发
npm run docs:dev
# 生产构建
npm run docs:build
# 本地预览构建结果
npm run docs:preview默认本地地址：http://localhost:4177
- 用户登录、注册、个人中心、资料维护、密码修改
- JWT Bearer Token 鉴权，配合 Refresh Token 自动续期
- 登录支持验证码校验，降低暴力尝试风险
- 用户管理：用户 CRUD、启停用、角色分配
- 角色管理：角色 CRUD、菜单权限配置
- 菜单管理：支持目录 / 菜单 / 按钮三级能力模型
- 动态菜单路由：前端根据当前用户菜单自动注册可访问页面
- 部门管理：组织层级维护
- 岗位管理：岗位信息维护与关联使用
- 数据字典：字典类型与字典项统一管理
- 系统配置：可维护系统运行相关配置项
- 通知公告：发布记录、已读状态管理，并支持实时通知推送
- 登录日志：记录登录行为，便于安全审计
- 操作日志：记录关键业务操作轨迹
- 在线会话：查看当前在线会话，并支持强制下线
- 文件管理：上传、列表查询、下载等基础能力
- 存储配置：支持本地文件系统与阿里云 OSS
- 默认存储切换：通过配置切换当前默认文件存储策略
- 定时任务管理：维护 Cron 任务并由服务端调度执行
- 系统监控：查看运行状态相关信息
- WebSocket：支持实时通知与会话下线消息推送
- 健康检查：提供
/api/health接口用于服务探活
所有接口挂载在 /api 前缀下，遵循统一响应格式：
{
"code": 0,
"message": "success",
"data": {}
}列表接口返回分页结构：
{
"code": 0,
"message": "success",
"data": {
"list": [],
"total": 100,
"page": 1,
"pageSize": 10
}
}认证接口需携带 Authorization: Bearer <token> 请求头。
npm run db:generate # 根据 schema 变更生成迁移文件
npm run db:migrate # 执行迁移
npm run db:seed # 重置并填充种子数据修改
packages/server/src/db/schema.ts后，必须 先db:generate再db:migrate，不要直接手动修改 SQL。
# 生产构建（顺序：shared → server → web）
npm run build构建产物：
- 后端：
packages/server/dist/ - 前端：
packages/web/dist/
生产环境部署前，请收紧 CORS 配置（当前允许所有来源）。
本项目采用 MIT License。