badmin

badmin 是一个可直接开箱的前后端分离后台模板，目标不是演示概念，而是提供一套能继续演进的管理后台基座。

• 前端：TanStack Start、shadcn/ui、UnoCSS
• 后端：Hono、Drizzle ORM、SQLite、Zod
• 基础能力：登录鉴权、Session Cookie、RBAC、用户管理、角色管理、多主题切换、中英文 i18n
• 测试：Vitest

特性

• 标准后台布局：桌面端固定侧边栏、移动端抽屉导航、顶部 Header 与 Breadcrumb
• 鉴权链路完整：登录、登出、会话读取、改密码、会话失效、权限校验全部打通
• RBAC 开箱可用：权限点、角色、用户关系可直接扩展
• 用户生命周期默认可用：重置密码、强制下线、启停账号、批量操作、删除用户
• 管理列表能力完整：搜索、筛选、分页、行级动作、批量动作都已接入
• SQLite 默认集成：本地开发成本低，适合作为模板起点
• 多主题支持：light、dark、system 加品牌色盘切换
• 中英文默认可用：前端界面内置 zh-CN / en-US，设置页可直接切换语言
• API 错误支持本地化：前端请求自动携带 X-Locale，服务端按语言返回错误消息
• 文档站已接入 Fumadocs：独立 apps/docs 应用 + 根目录 Markdown 内容源
• Monorepo 结构清晰：apps/docs、apps/web、apps/server、packages/* 分层明确

技术栈

Frontend

• TanStack Start
• React 19
• shadcn/ui
• UnoCSS
• Lucide Icons

Backend

• Hono
• Drizzle ORM
• better-sqlite3
• Zod

Tooling

• Bun Workspaces
• Turbo
• TypeScript
• ESLint
• Prettier
• Vitest

项目结构

.
├── apps
│   ├── docs     # Fumadocs 文档站
│   ├── server   # Hono API、Drizzle、SQLite、seed
│   └── web      # TanStack Start 管理后台
├── docs         # 文档内容源（Fumadocs MD/MDX）
├── packages
│   ├── contracts # 前后端共享的 Zod schema / 类型契约
│   └── ui        # shadcn/ui 组件与全局样式
└── .github
    └── workflows # CI / Release

快速开始

1. 安装依赖

bun install

2. 初始化环境变量

cp apps/server/.env.example apps/server/.env
cp apps/web/.env.example apps/web/.env

3. 初始化数据库

bun run db:migrate
bun run db:seed

4. 启动开发环境

bun run dev

启动后：

• 前端默认地址：http://localhost:3000
• 后端默认地址：http://localhost:4000
• 文档站默认地址：http://localhost:3001

默认管理员账号

• 邮箱：admin@badmin.dev
• 密码：ChangeMe123!

文档

• 文档总览
• 快速开始
• 架构总览
• 鉴权与 RBAC
• 定制与扩展
• 开发与发布

国际化

• 默认支持 zh-CN 和 en-US
• 首屏默认使用中文，前端 hydration 后会根据本地设置或浏览器语言切换
• 语言切换入口位于设置页，切换结果会持久化到本地存储
• Web 端 API 客户端会自动附带 X-Locale 请求头，服务端会返回对应语言的校验和鉴权错误

常用命令

# 开发
bun run dev

# 代码质量
bun run lint
bun run typecheck
bun run test
bun run build

# 数据库
bun run db:generate
bun run db:migrate
bun run db:seed
bun run db:studio

环境变量

apps/server/.env

DB_FILE_NAME=./data/badmin.sqlite
PORT=4000
WEB_ORIGIN=http://localhost:3000
SESSION_SECRET=replace-with-a-long-random-string-at-least-32-chars
SESSION_DOMAIN=
SESSION_SAME_SITE=lax
SESSION_SECURE=false
SEED_ADMIN_EMAIL=admin@badmin.dev
SEED_ADMIN_PASSWORD=ChangeMe123!

其中：

• SESSION_DOMAIN：跨子域部署时可显式指定 Cookie 域
• SESSION_SAME_SITE：可选 lax / strict / none
• SESSION_SECURE：可显式覆盖 Cookie 的 Secure 标记

apps/web/.env

VITE_API_BASE_URL=http://localhost:4000

数据库说明

• 默认数据库为 SQLite
• 默认文件路径：apps/server/data/badmin.sqlite
• 迁移文件目录：apps/server/drizzle

CI 与 Release

仓库内置两套 GitHub Actions：

• CI：在 push main 和 pull_request 时执行 lint、typecheck、test、build
• Release：在推送 v* 标签时调用 changelogithub 自动生成 GitHub Release

如果你使用标准语义化版本标签，例如：

git tag v0.1.0
git push origin v0.1.0

对应的 Release workflow 会自动运行。