开发指引
本页是官网精简版，完整内容见仓库文档
docs/developer.md。
目录结构
| 目录 | 内容 |
|---|---|
./ | 程序入口薄壳（go build -o GoPanel .），转发到 internal/app |
internal/ | 后端业务代码（handler / service / repository / model 分层） |
internal/app/ | 启动编排唯一实现：参数解析、配置加载、库迁移、服务启动 |
cmd/gopanel/ | 等价的入口薄壳（go build -o GoPanel ./cmd/gopanel） |
internal/bootstrap/ | 版本号与构建信息注入 |
frontend/management/ | 管理后台 React SPA（npm run build 的输出即 go:embed 目标） |
frontend/embed.go | //go:embed all:management/dist 原地嵌入 SPA 产物（不用 ../，无复制） |
internal/handler/frontend/ | SPA 静态文件 gin 处理器（只依赖 gin，资源由入口注入） |
frontend/vitepress/ | 本官网与文档站（VitePress） |
config/ | 配置示例、i18n、预升级 SQL |
docker/ | dev 线多阶段 Dockerfile |
docker-compose/ | 各类编排模板 |
scripts/ | 安装脚本、CI 脚本、自检脚本 |
docs/ | 仓库内开发文档与 Swagger 定义 |
后端开发环境
需要 Go ≥ 1.26。
程序入口有两处薄壳，都转发到 internal/app：
bash
export GOPROXY=https://goproxy.cn,direct
go build -o GoPanel . # 仓库根；等价写法：go build -o GoPanel ./cmd/gopanel
go vet ./... # 静态检查
go test ./... # 单元测试⚠️
go build请带-o：裸跑go build/go build ./...会在根目录留下一个 150MB+ 的无扩展名二进制，被 gvt 钩子的「无扩展名二进制」检查拦下。前端产物目录
frontend/management/dist就是go:embed的目标 （frontend/embed.go），npm run build之后无需任何复制即可编译嵌入； 干净检出下该目录只有一个占位index.html，保证go build不会失败。 完整步骤见 从源码构建。
分层约定
text
handler → service → repository → model- 数据结构统一在
internal/model定义 repository是唯一查询层，分页在 repo 内完成service编排顺序与容错，handler只做参数与响应
代码质量
提交前跑 gvt hook -t（暂存文件）/ gvt hook -a（全量）：
- 格式化、行数限制（单文件警告 250 / 限制 300）、lint、类型、构建
前端开发环境
需要 Node.js ≥ 22。
bash
cd frontend/management
npm ci # 按 lockfile 安装（比 npm install 更可复现）
npm run dev # http://localhost:3003
npm run typecheck # tsc --noEmit
npm run lint # oxlint --max-warnings 0
npm run build # 产物 dist/ —— 就是 frontend/embed.go 的 go:embed 目标，无需复制开发服务器把 /api、/captcha、/term、/server 代理到后端， 目标由 .env.development 的 VITE_API_PROXY_TARGET 控制（默认 http://localhost:12395）。
官网 / 文档站开发
bash
cd frontend/vitepress
npm install
npm run dev # 本地预览
npm run build # 产出 .vitepress/distmaster 推送后由 CNB 流水线自动构建并部署到腾讯云 EdgeOne Pages。