EleAdmin Plus Gin API

基于 Gin + GORM 的 EleAdmin Plus Java 后端复刻服务。

项目默认可在本地用 SQLite + embedded KV 跑通，不需要独立 MySQL/Redis；
生产环境可通过配置切换到 MySQL(或MariaDB) + Redis。

配套前端

Ele Admin Plus高级版永久授权v1.6.0

技术栈

• Web 框架：Gin
• ORM：GORM
• 本地数据库：SQLite
• 生产数据库：MySQL / MariaDB
• 本地 KV：embedded file KV
• 生产缓存：Redis
• 认证：JWT + token blacklist
• 配置：YAML profile + 环境变量覆盖
• 日志：自定义 logger + Gin middleware
• 热重载：Air

快速开始

1. 安装依赖

go mod download

2. 本地开发启动：SQLite + embedded KV

推荐使用 dev profile：

$env:APP_ENV="dev"
go run ./cmd/server

默认地址：

http://127.0.0.1:5179

默认本地账号：

username: admin
password: 123456

端口被占用时可覆盖：

$env:APP_ENV="dev"
$env:APP_HTTP_ADDR=":5180"
go run ./cmd/server

也可以不用 profile，完全通过环境变量启动：

$env:APP_DB_ENABLED="true"
$env:APP_DB_DRIVER="sqlite"
$env:APP_DB_DSN="data/eleadmin.db"
$env:APP_DB_AUTO_MIGRATE="true"
$env:APP_DB_SEED="true"
$env:APP_CACHE_DRIVER="embedded"
$env:APP_CACHE_EMBEDDED_PATH="data/eleadmin-kv.json"
$env:APP_REDIS_ENABLED="false"
go run ./cmd/server

3. Air 热重载

go install github.com/air-verse/air@latest
$env:APP_ENV="dev"
air

如果提示EleAdmin Gin API failed to listen on :5179:，可先执行强杀被占用的5179端口：

netstat -ano | Select-String ":5179" | ForEach-Object {taskkill /F /PID $_.ToString().Split()[-1]}

项目已提供 .air.toml，会监听 cmd/、configs/、internal/ 中的 Go/YAML 文件变化，编译到 tmp/server.exe 并自动重启。

生产启动：MySQL + Redis

推荐使用 prod profile，并用环境变量或外部配置文件覆盖敏感信息。

cd "D:\xfx\xfxAdmin\归档\EleAdmin Plus\gin-api"
$env:APP_ENV="prod"
$env:APP_DB_ENABLED="true"
$env:APP_DB_DRIVER="mysql"
$env:APP_DB_DSN="user:pass@tcp(host:3306)/eleadmin_gin?charset=utf8mb4&parseTime=True&loc=Local"
$env:APP_DB_AUTO_MIGRATE="false"
$env:APP_DB_SEED="false"
$env:APP_CACHE_DRIVER="redis"
$env:APP_REDIS_ENABLED="true"
$env:APP_REDIS_ADDR="host:6379"
$env:APP_REDIS_PASSWORD="password"
$env:APP_SECURITY_STRICT_AUTH="true"
$env:APP_SECURITY_STRICT_CAPTCHA="true"
go run ./cmd/server

生产默认地址：

http://127.0.0.1:8080

使用外部配置文件：

$env:APP_ENV="prod"
$env:APP_CONFIG="D:\deploy\eleadmin-gin.yaml"
go run ./cmd/server

APP_CONFIG 在内置 configs/config.yaml 和 configs/config.$APP_ENV.yaml 之后加载，环境变量仍拥有最终优先级。显式指定的 APP_ENV 或 APP_CONFIG 不存在、YAML 无法解析时会直接启动失败。

项目结构

gin-api/
├── cmd/
│   └── server/          # 服务入口
├── configs/             # 默认/dev/prod 配置
├── internal/
│   ├── bootstrap/       # GORM、Cache、MQTT、Logger、Validator、事务
│   ├── config/          # 配置加载、环境变量覆盖、校验
│   ├── controller/      # Gin Handler
│   ├── dto/             # 请求/响应 DTO
│   ├── middleware/      # JWT、CORS、Recovery、日志、权限
│   ├── model/           # GORM Model
│   ├── repo/            # 数据访问层
│   ├── router/          # 路由注册
│   ├── service/         # 业务逻辑层
│   └── pkg/             # 通用工具
├── docs/                # 验收、路线、路由差异、巡检文档
├── migrations/
└── scripts/             # smoke 与契约验证脚本

API 概览

统一前缀：/api

• 认证：/captcha、/login、/logout、/auth/user、/auth/menu、/auth/password
• 用户管理：/system/user/*
• 角色管理：/system/role/*、/system/role-menu/*
• 菜单管理：/system/menu/*
• 组织机构：/system/organization/*
• 字典管理：/system/dictionary/*、/system/dictionary-data/*
• 文件管理：/file/*
• 登录日志：/system/login-record/*
• 操作日志：/system/operation-record/*
• 用户文件：/system/user-file/*
• 租户管理：/system/tenant/*
• 邮件发送：/system/email
• AI 对话：/chat/completions

前端联调

Gin 后端：

$env:APP_ENV="dev"
go run ./cmd/server

前端：

npx vite --mode gin --host 127.0.0.1 --port 5174 --strictPort

前端 .env.gin 会关闭 mock，并代理 /api 到 Gin dev 服务。VITE_API_PROXY_URL 必须以 /api 结尾。

常见问题

端口被占用

服务启动时如果提示端口占用，可换端口：

$env:APP_ENV="dev"
$env:APP_HTTP_ADDR=":5180"
go run ./cmd/server

或查看占用进程：

Get-NetTCPConnection -LocalPort 5179 -State Listen
Get-NetTCPConnection -LocalPort 8080 -State Listen

本地不想安装 MySQL/Redis

直接使用 APP_ENV=dev。该模式使用 SQLite + embedded KV，数据落在 data/eleadmin.db 和 data/eleadmin-kv.json。

生产不想自动改表

设置：

$env:APP_DB_AUTO_MIGRATE="false"
$env:APP_DB_SEED="false"

生产表结构建议由迁移脚本或 Java 原始 SQL 契约管理。