一套 单二进制即可上线 的后台管理底座:前端产物经 go:embed 内嵌进后端,CGO_ENABLED=0 全静态编译,产出约 44 MB 的 distroless 镜像。proto 是唯一契约来源,前后端类型与校验全部由它生成。
- 声明式契约 — proto 单一来源,生成 Go / TypeScript 类型、connectRPC client 与 protovalidate 校验。
- 类型安全全链路 — 后端 GORM 泛型 API + CLI 代码生成;前端 connect-query + Zod 4。
- 开箱认证授权 — JWT(会话级 jti)+ 最小 RBAC;授权由 Casbin 拦截器统一裁决,handler 零侵入。
- 无默认账号 — 首位注册用户自动成为管理员,安全合规。
- 完善后台 UI — 侧边栏布局、暗/亮主题、中英(zh/en)i18n、表格 / 表单 / 仪表盘。
- 多数据源 — PostgreSQL / MySQL / SQLite(纯 Go 驱动,无 CGO)。
- 质量门禁 — nilaway 空指针分析、govet nilness、golangci-lint、严格 TypeScript。
- 一键化 — Taskfile 收敛全部开发 / 构建 / 部署命令。
| 层 | 选型 |
|---|---|
| 后端 | Go 1.26、connectRPC(h2c)、GORM v1.31 + GORM CLI、protovalidate、Casbin |
| 前端 | React 19、Vite、TanStack Router / Query / Table / Form、Radix(shadcn/ui)、Tailwind v4、Zod 4 |
| 数据 | PostgreSQL / MySQL / SQLite |
| 打包 | go:embed 内嵌 SPA + distroless 静态二进制 |
前置:Go 1.26+、Node + pnpm、Task、buf、Docker。
# 首次设置:装工具/依赖 → 生成代码 → 创建 .env → 启动 dev PostgreSQL
task sync
# 启动开发环境(两个终端各跑一个,Ctrl+C 停止;无热重载,改代码后重跑)
task dev:backend # 后端(含 db:up + go run)
task dev:web # 前端 Vite(:5173 代理到 :8080)打开浏览器访问 http://localhost:5173,在 /register 注册首个用户(即管理员)。
用内置 CLI zerxKit 从本模板克隆并改名,一键生成独立可运行的新项目(改 Go module 路径、二进制名、Docker 镜像/卷名、前端包名、品牌显示名、默认库名、localStorage key 前缀)。
两种用法:
# 1) 仓库内开发:在本仓库根目录跑(task 自动传 --from 仓库根)
task new -- github.com/acme/foo ../foo [--brand Foo] [--db foo]
# 2) 全局安装(无需先 clone):
go install github.com/zerx-lab/zerxlabkit/cmd/zerxKit@latest
zerxKit new github.com/acme/foo ../foo [--brand Foo] [--db foo]提示:
zerxKit help查看命令列表、zerxKit --version查看版本、zerxKit help new查看new用法。
- 位置参数:新 module 路径(必填)、目标目录(可选,缺省
./<module 末段>)。 --brand缺省=module 末段;--db缺省=经 sanitize 的 module 末段;--from <dir>显式指定模板根(跳过缓存)。- 模板来源(三态):
--from指定 → 用该目录;go run(仓库内(devel)态)→ 用当前目录;go install的二进制 → 按其版本把模板克隆/checkout 到~/.ZerxLabKit/<version>再用。CLI 版本与模板版本同 tag 锁定(@v1.2.0装的二进制生成时模板也 checkoutv1.2.0,tag 不可变,几乎免联网);发版前的伪版本则跟远程默认分支最新提交。缓存视为只读镜像,更新时reset --hard丢弃任何手改;离线无法检查更新时回退缓存并提示。需要本机有git。 - proto 包名
zerx.v1保留不改(内部 RPC 命名空间,终端用户不可见;改它需重跑 codegen)。 - 生成码(
*.pb.go/*_pb.ts)逐字节拷贝,其内嵌 descriptor 残留的旧元数据在运行期无害,任意一次task gen即自愈。
新项目仅需 go build 即可编译(创建时无需 buf/protoc 工具链)。首跑:
cd ../foo
cp .env.example .env # 设置 JWT_SECRET
go build ./... # 离线编译,无需 codegen
(cd web && pnpm install && pnpm build)
# 完整开发体验(重生成代码、起 dev DB):task sync && task dev生成的项目会带上 agent-host 配置(.pi / .claude / .opencode),按需删除即可。
task build # 本机单二进制(内嵌 SPA)→ bin/zerxlabkit
task build:dist # 静态 linux/amd64 二进制 → bin/zerxlabkit-linux-amd64
task docker:build # 构建 distroless 镜像
task docker:up # 起整套 compose(app + postgres)生产运行需设置 JWT_SECRET(缺失则启动失败)。
| 命令 | 作用 |
|---|---|
task new |
基于本模板创建新项目(改 module / 品牌 / 库名) |
task gen |
生成全部代码(proto Go/TS + GORM 查询) |
task lint |
后端 golangci-lint + nilaway;前端 ESLint + tsc |
task test |
运行后端测试 |
task deps:update |
升级全部依赖(自动快照,可 deps:rollback 回退) |
提交前请执行 task lint && task test。
浏览器 SPA ──/api/...──► connectRPC handler
│
拦截器链:日志 → 认证 → 校验 → recover
│
service ──► GORM ──► 数据库
生产为单二进制同源部署;开发用 Vite 代理(:5173 → :8080)。
proto/ 唯一契约来源(zerx/v1/*.proto)
gen/ 生成的 Go 代码(提交入库)
cmd/server/ 入口:config → db → migrate → seed → serve
internal/ config / database / model / auth / casbin / service / server ...
web/ React 前端;src/gen/ 为生成的 TS 代码
生成代码全部提交入库,Docker / CI / 日常构建不重跑 codegen。
仓库内置面向 AI 与人类的开发指南,详见 AGENTS.md 及 .agents/skills/(后端、前端、授权、安全、模块脚手架等专题 skill)。