Go React Template

Go + React 管理后台模板。仓库保持前后端分离开发，生产部署走单应用镜像：

• backend/：Gin API、RBAC、文件上传、通知、Swagger、SQL migrations
• frontend/：React 19 + Vite 管理台
• docker-compose.yml：PostgreSQL、Redis、backend 全栈编排

目录

.
├─ backend/
├─ frontend/
├─ docker-compose.yml
└─ Makefile

开发模式

开发时继续保持前后端分离：

make docker-up
make migrate-up
make dev-backend
make dev-frontend

说明：

• 根目录命令默认通过 GNU Make 执行。
• 如果当前机器没有 make，可直接运行对应的 bun、go、docker compose 原生命令。
• make docker-up 只启动 PostgreSQL 和 Redis，方便本地前后端直接跑。
• 前端通过 Vite proxy 转发 /api 和 /api/v1/ws。
• 后端默认读取 backend/config.yaml，需要覆盖时使用环境变量。

默认地址：

• 前端：http://localhost:5173
• 后端：http://localhost:8080
• Swagger：http://localhost:8080/swagger/index.html（debug 模式）
• PostgreSQL：localhost:5434
• Redis：localhost:6380

生产 / 一键启动

生产目标是一个后端容器同时提供 API 和前端静态资源：

docker compose up -d

启动链路：

1. postgres 启动并通过健康检查。
2. redis 启动并通过健康检查。
3. backend 容器启动时自动执行 backend/migrations。
4. backend 容器提供 API、/healthz、/readyz 和前端页面。

补充命令：

make docker-up-full
make docker-down

说明：

• 当前仓库采用应用启动内自动迁移，通过 SERVER_AUTO_MIGRATE=true 控制。
• 生产容器内后端会托管 frontend/dist，刷新前端深链不会 404。
• Redis 对宿主机默认映射到 6380，避免与本机已安装 Redis 的 6379 冲突。

配置策略

推荐分工：

• backend/config.yaml：提交到仓库的开发默认值
• backend/.env.example：可覆盖的环境变量示例
• Docker Compose environment：容器部署注入

决策：

• 后端进程当前不自动读取 .env
• 本地开发覆盖通过 shell 环境变量完成
• 容器部署覆盖通过 Compose environment 或 env_file 完成

高频变量：

• SERVER_MODE
• SERVER_PORT
• SERVER_FRONTEND_DIST
• SERVER_AUTO_MIGRATE
• DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME / DB_SSL_MODE
• REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_DB
• JWT_SECRET / JWT_REFRESH_SECRET
• UPLOAD_DIR
• CORS_ORIGINS

常用命令

make docker-up
make docker-up-full
make docker-down
make migrate-up
make migrate-down
make dev-backend
make dev-frontend
make build-frontend
make typecheck-frontend
make format-check-frontend
make test-backend
make test-frontend
make lint-frontend
make lint-backend
make verify-clean-machine
make swag-init
make gen-types

Clean Machine 验证脚本

用于新机器或重装后的环境自检，统一检查 PATH 中的基础工具，并按仓库现有 Makefile 跑最小验证链。

Windows PowerShell：

.\scripts\verify-clean-machine.ps1
make verify-clean-machine

macOS / Linux：

./scripts/verify-clean-machine.sh

可选参数：

• 默认执行：Docker 配置检查、后端 lint + test、前端 typecheck + lint + build-check
• format-check 默认不跑，因为仓库当前仍有历史格式债务；需要时显式开启
• 前端测试默认不跑；需要时显式开启

示例：

.\scripts\verify-clean-machine.ps1 -IncludeFormatCheck -IncludeFrontendTests

./scripts/verify-clean-machine.sh --include-format-check --include-frontend-tests

最小验收流程

前端：

make typecheck-frontend
make lint-frontend
make format-check-frontend
make build-check-frontend
make test-frontend

后端：

make lint-backend
make test-backend

一键启动链路：

docker compose build backend
docker compose up -d

2026-04-29 实测通过：

• docker compose build backend
• docker compose up -d
• GET /healthz
• GET /readyz
• GET /
• GET /system/users

说明文档

• 后端说明：backend/README.md
• 前端说明：frontend/README.md