{"id":43429701,"url":"https://github.com/wannanbigpig/gin-layout","last_synced_at":"2026-02-02T19:16:14.853Z","repository":{"id":38849748,"uuid":"491788395","full_name":"wannanbigpig/gin-layout","owner":"wannanbigpig","description":"Gin framework is used as the core of this project to build a template, based on this project can quickly complete business development","archived":false,"fork":false,"pushed_at":"2025-12-17T08:16:22.000Z","size":38301,"stargazers_count":155,"open_issues_count":0,"forks_count":48,"subscribers_count":3,"default_branch":"x_l_admin","last_synced_at":"2025-12-20T21:42:14.274Z","etag":null,"topics":["gin","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wannanbigpig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-05-13T06:49:39.000Z","updated_at":"2025-12-17T08:16:26.000Z","dependencies_parsed_at":"2024-02-27T10:59:43.134Z","dependency_job_id":"e7586369-33e6-4768-8e48-8c91a4836c9b","html_url":"https://github.com/wannanbigpig/gin-layout","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/wannanbigpig/gin-layout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wannanbigpig%2Fgin-layout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wannanbigpig%2Fgin-layout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wannanbigpig%2Fgin-layout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wannanbigpig%2Fgin-layout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wannanbigpig","download_url":"https://codeload.github.com/wannanbigpig/gin-layout/tar.gz/refs/heads/x_l_admin","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wannanbigpig%2Fgin-layout/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29017941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T18:51:31.335Z","status":"ssl_error","status_checked_at":"2026-02-02T18:49:20.777Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gin","go","golang"],"created_at":"2026-02-02T19:16:14.764Z","updated_at":"2026-02-02T19:16:14.843Z","avatar_url":"https://github.com/wannanbigpig.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gin-layout\n\n[![Go](https://github.com/wannanbigpig/gin-layout/actions/workflows/go.yml/badge.svg)](https://github.com/wannanbigpig/gin-layout/actions/workflows/go.yml)\n[![CodeQL](https://github.com/wannanbigpig/gin-layout/actions/workflows/codeql.yml/badge.svg)](https://github.com/wannanbigpig/gin-layout/actions/workflows/codeql.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/wannanbigpig/gin-layout)](https://goreportcard.com/report/github.com/wannanbigpig/gin-layout)\n[![GitHub license](https://img.shields.io/github/license/wannanbigpig/gin-layout)](https://github.com/wannanbigpig/gin-layout/blob/master/LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-%3E%3D1.23-blue.svg)](https://golang.org/)\n\n\u003e 基于 Gin 框架的企业级 Go 项目脚手架（Go Admin 后台管理系统），开箱即用的 Go 管理后台框架，快速构建 RESTful API 服务和管理后台系统\n\n**前端项目：** [go-admin-ui](https://github.com/wannanbigpig/go-admin-ui) - 基于 Vue 3 + Element Plus 的管理后台前端项目\n\n**API 文档：** [在线文档](https://wannanbigpig.apifox.cn/) - 完整的接口文档和使用说明\n\n**演示地址：** [在线演示](https://x-l-admin.wannanbigpig.com/) - 可直接体验完整的管理后台功能\n\n## 📌 项目简介\n\n**gin-layout** 是一个功能完整的 **Go Admin 后台管理系统**框架，专为快速构建企业级管理后台而设计。本项目提供了完整的 RBAC 权限管理、JWT 认证、日志系统等核心功能，是构建 Go 管理后台、Go Admin Panel、Go 后台管理系统的理想选择。\n\n## ✨ 特性\n\n- 🚀 **开箱即用** - 完整的 Go Admin 项目结构，无需从零开始搭建\n- 🔐 **RBAC 权限管理** - 基于 Casbin 的完整权限控制系统，适合构建 Go 管理后台系统\n- 📝 **JWT 认证** - 支持 Token 生成、刷新和黑名单管理，保障 Go Admin 系统安全\n- 📦 **数据库迁移** - 使用 migrate 进行数据库版本管理\n- 📊 **日志系统** - 基于 zap 的高性能日志，支持文件和控制台输出\n- 🔄 **CORS 支持** - 完整的跨域资源共享配置\n- 📤 **文件上传** - 支持公开/私有文件存储，UUID 标识\n- 🛡️ **参数验证** - 基于 validator 的请求参数验证\n- 📈 **请求日志** - 自动记录 API 请求日志，便于 Go Admin 系统监控\n- 🎯 **统一响应** - 标准化的 API 响应格式\n- ⚙️ **配置管理** - 基于 Viper 的灵活配置系统\n- 🔧 **CLI 工具** - 支持 server、command、cron 等多种命令\n- 📱 **软删除** - 支持数据库软删除功能\n- 🔒 **数据加密** - 支持敏感数据加密存储（如 Token 加密）\n\n## 📋 目录结构\n\n```\ngin-layout/\n├── cmd/                    # 命令行工具\n│   ├── service/           # 服务器启动命令\n│   ├── command/           # 单次执行命令\n│   ├── cron/              # 定时任务\n│   └── version/           # 版本信息\n├── config/                # 配置文件\n│   ├── autoload/          # 配置结构体定义\n│   └── config.yaml.example  # 配置示例文件\n├── data/                  # 数据层\n│   ├── migrations/        # 数据库迁移文件\n│   ├── mysql.go          # MySQL 连接\n│   └── redis.go          # Redis 连接\n├── internal/              # 内部代码（不对外暴露）\n│   ├── controller/        # 控制器层\n│   ├── service/           # 业务逻辑层\n│   ├── model/             # 数据模型\n│   ├── middleware/        # 中间件\n│   ├── pkg/               # 内部工具包\n│   ├── resources/         # 资源转换器\n│   ├── routers/           # 路由定义\n│   └── validator/         # 参数验证\n├── pkg/                   # 公共包（可对外暴露）\n│   └── utils/             # 工具函数\n├── storage/               # 文件存储\n│   ├── public/            # 公开文件\n│   └── private/           # 私有文件\n├── logs/                  # 日志文件目录\n├── main.go                # 程序入口\n└── README.md              # 项目说明\n```\n\n## 🚀 快速开始\n\n本 Go Admin 框架支持快速搭建管理后台系统，适用于企业级 Go 后台管理系统开发。\n\n### 环境要求\n\n- Go \u003e= 1.23\n- MySQL \u003e= 5.7\n- Redis \u003e= 5.0 (可选)\n\n### 安装步骤\n\n1. **克隆项目**\n```bash\ngit clone https://github.com/wannanbigpig/gin-layout.git\ncd gin-layout\n```\n\n2. **安装依赖**\n```bash\ngo mod download\n```\n\n3. **配置数据库**\n\n安装 migrate 工具（[安装文档](https://github.com/golang-migrate/migrate/tree/master/cmd/migrate)）\n\n执行数据库迁移：\n```bash\nmigrate -database 'mysql://root:root@tcp(127.0.0.1:3306)/go_layout?charset=utf8mb4\u0026parseTime=True\u0026loc=Local' \\\n  -path data/migrations up\n```\n\n4. **配置应用**\n\n首次运行会自动从 `config/config.yaml.example` 复制配置文件到项目根目录的 `config.yaml`。\n\n编辑项目根目录的 `config.yaml`，配置数据库和 Redis 连接信息：\n\n```yaml\nmysql:\n  enable: true\n  host: 127.0.0.1\n  port: 3306\n  database: go_layout\n  username: root\n  password: your_password\n\nredis:\n  enable: true\n  host: 127.0.0.1\n  port: 6379\n  password: \"\"\n  database: 0\n```\n\n5. **启动服务**\n\n**正常启动（日常使用）：**\n```bash\nGO_ENV=development go run main.go service\n```\n\n**首次初始化（仅首次部署时需要）：**\n\n首次部署时，需要初始化数据库中的 API 路由表和菜单-API 映射关系。你可以选择两种方式：\n\n**方式一：完整初始化系统（推荐）**\n\n一键完成所有初始化操作，包括回滚迁移、重新执行迁移、初始化路由和路由映射：\n\n```bash\nGO_ENV=development go run main.go command init-system\n```\n\n该命令会执行以下操作：\n1. 回滚所有数据库迁移\n2. 重新执行所有迁移\n3. 重新初始化 API 路由表\n4. 重新初始化菜单-API 映射关系\n\n**方式二：分步初始化**\n\n如果需要分步执行，可以使用以下命令：\n\n**步骤 1：初始化 API 路由表**\n\n扫描系统中定义的所有 API 路由并写入 `a_api` 表：\n\n```bash\nGO_ENV=development go run main.go command api-route\n```\n\n该命令会自动扫描系统中定义的所有 API 路由，并将路由信息（路径、方法、处理器等）写入 `a_api` 表中，用于权限管理和 API 文档生成。\n\n**步骤 2：初始化菜单-API 映射关系**\n\nAPI 路由表初始化完成后，建立菜单与 API 的映射关系：\n\n```bash\nGO_ENV=development go run main.go command menu-api-map\n```\n\n该命令会根据 `casbin_rule` 表中的权限规则，自动建立默认菜单与 API 的映射关系，初始化 `a_menu_api_map` 表。\n\n\u003e **重要提示**：\n\u003e - 初始化命令是独立的，可以随时单独执行\n\u003e - 日常启动服务时直接使用 `go run main.go service` 即可，无需任何参数\n\u003e - 如果只需要更新 API 路由表或菜单映射，可以单独执行对应的初始化命令\n\u003e - `command init-system` 命令会直接执行，无需确认\n\u003e - 系统会在每天凌晨2点自动执行初始化任务（通过 `go-layout cron` 启动定时任务服务）\n\n**生产模式：**\n```bash\ngo build -o go-layout main.go\n./go-layout service\n```\n\n6. **测试接口**\n\n```bash\n# 健康检查\ncurl http://127.0.0.1:9001/ping\n# 响应: {\"message\":\"pong\"}\n\n# 示例接口\ncurl http://127.0.0.1:9001/admin/v1/demo\n```\n\n## 📖 使用说明\n\n### Go Admin 系统功能\n\n本框架提供了完整的 Go 管理后台功能，包括：\n\n- **用户管理** - 管理员用户管理、角色分配、部门管理\n- **权限管理** - 基于 RBAC 的权限控制系统，支持角色、菜单、API 权限管理\n- **登录认证** - JWT Token 认证、登录日志记录、Token 刷新机制\n- **日志管理** - 登录日志、请求日志记录和查询\n- **菜单管理** - 动态菜单配置，支持多级菜单\n- **API 管理** - API 路由自动扫描和权限配置\n\n### 命令行工具\n\n项目支持多种命令，使用 `-h` 查看帮助：\n\n```bash\ngo run main.go -h\n```\n\n**可用命令：**\n\n- `service` - 启动 API 服务器\n- `command` - 执行单次命令（包括初始化命令）\n  - `command api-route` - 初始化 API 路由表\n  - `command menu-api-map` - 初始化菜单-API 映射关系\n  - `command init-system` - 初始化系统数据（回滚迁移、重新执行迁移、重新初始化路由和路由映射）\n  - `command demo` - 执行示例命令\n- `cron` - 启动定时任务（每天凌晨2点自动执行系统初始化）\n- `version` - 查看版本信息\n\n### 配置说明\n\n配置文件位置：\n- **开发模式**：项目根目录的 `config.yaml`\n- **生产模式**：执行文件所在目录的 `config.yaml`\n- **自定义路径**：可通过 `-c` 或 `--config` 参数指定配置文件绝对路径\n\n主要配置项：\n\n- **app** - 应用配置（环境、调试模式、语言等）\n- **jwt** - JWT 配置（密钥、过期时间等）\n- **mysql** - MySQL 数据库配置\n- **redis** - Redis 配置\n- **logger** - 日志配置（输出方式、文件切割等）\n\n详细配置说明请参考 `config/config.yaml.example`。\n\n**配置文件查找顺序**：\n1. 如果通过 `-c` 或 `--config` 参数指定了路径，使用指定的配置文件\n2. 开发模式（`GO_ENV=development`）：从当前工作目录查找 `config.yaml`\n3. 生产模式：从执行文件所在目录查找 `config.yaml`\n\n### API 路由\n\n- **公开接口** - `/admin/v1/login`、`/admin/v1/login-captcha` 等\n- **需要认证** - 其他接口需要在请求头中携带 `Authorization: Bearer \u003ctoken\u003e`\n\n### 分支说明\n\n- **basic_layout** - 基础脚手架分支，提供干净的开发环境\n  - [接口文档](https://apifox.com/apidoc/shared-721e0594-dea4-4d86-bad3-851b51c16e03)\n- **x_l_admin** - 管理台服务分支，包含完整的 RBAC 权限管理\n  - [接口文档](https://apifox.com/apidoc/shared-c429e6ec-8246-4eb4-a503-3927602af312)\n\n### 前端项目\n\n本项目配套的前端管理后台项目：\n\n- **[go-admin-ui](https://github.com/wannanbigpig/go-admin-ui)** - 基于 Vue 3 + Element Plus + Vite 构建的现代化管理后台前端\n  - 完整的 RBAC 权限控制\n  - 动态路由和菜单生成\n  - 响应式布局设计\n  - 丰富的组件和工具函数\n\n## 🚢 部署\n\n### 构建\n\n```bash\n# 构建可执行文件\ngo build -o go-layout main.go\n```\n\n### 使用 Supervisor 管理进程\n\n创建 `/etc/supervisor/conf.d/go-layout.conf`：\n\n```ini\n[program:go-layout]\ncommand=/path/to/go-layout service -c=/path/to/config.yaml\ndirectory=/path/to/go-layout\nautostart=true\nautorestart=true\nstartsecs=5\nuser=www-data\nredirect_stderr=true\nstdout_logfile=/path/to/go-layout/supervisord.log\n```\n\n启动服务：\n```bash\nsupervisorctl reread\nsupervisorctl update\nsupervisorctl start go-layout\n```\n\n### Nginx 反向代理\n\n```nginx\nserver {\n    listen 80;\n    server_name api.example.com;\n\n    location / {\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_pass http://127.0.0.1:9001;\n    }\n}\n```\n\n### Docker 部署（可选）\n\n```dockerfile\nFROM golang:1.23-alpine AS builder\nWORKDIR /app\nCOPY . .\nRUN go build -o go-layout main.go\n\nFROM alpine:latest\nRUN apk --no-cache add ca-certificates\nWORKDIR /root/\nCOPY --from=builder /app/go-layout .\nCOPY --from=builder /app/config/config.yaml.example ./config.yaml\n# 或者使用自定义配置文件路径：\n# CMD [\"./go-layout\", \"service\", \"-c\", \"/path/to/config.yaml\"]\nEXPOSE 9001\nCMD [\"./go-layout\", \"service\"]\n```\n\n## ⚙️ 生产环境注意事项\n\n1. **配置文件路径** - 生产环境建议使用 `-c` 参数指定配置文件的绝对路径，或确保 `config.yaml` 位于执行文件所在目录\n2. **日志路径** - 配置 `base_path`，日志文件会保存在 `{base_path}/logs/` 目录\n3. **JWT 密钥** - 确保 JWT secret_key 足够复杂且保密\n4. **数据库连接** - 配置合适的连接池大小\n5. **CORS 配置** - 生产环境建议配置具体的允许源，而不是允许所有源\n\n## 🛠️ 技术栈\n\n本 Go Admin 框架采用现代化的技术栈，为构建高性能的管理后台系统提供坚实基础。\n\n### 核心框架\n- [Gin](https://github.com/gin-gonic/gin) - HTTP Web 框架\n- [GORM](https://gorm.io/) - ORM 框架\n- [Viper](https://github.com/spf13/viper) - 配置管理\n- [Cobra](https://github.com/spf13/cobra) - CLI 框架\n\n### 认证与权限\n- [JWT](https://github.com/golang-jwt/jwt) - JWT 认证\n- [Casbin](https://github.com/casbin/casbin) - 权限控制\n\n### 数据存储\n- [MySQL](https://github.com/go-sql-driver/mysql) - 关系型数据库\n- [Redis](https://github.com/go-redis/redis) - 缓存数据库\n\n### 工具库\n- [Zap](https://github.com/uber-go/zap) - 高性能日志库\n- [Validator](https://github.com/go-playground/validator) - 参数验证\n- [UUID](https://github.com/google/uuid) - UUID 生成\n\n更多依赖请查看 `go.mod` 文件。\n\n## 📝 开发指南\n\n### 构建 Go Admin 系统\n\n使用本框架可以快速构建功能完整的 Go 管理后台系统，支持用户管理、权限控制、数据管理等核心功能。\n\n### 添加新接口\n\n1. 在 `internal/controller/` 创建控制器\n2. 在 `internal/service/` 实现业务逻辑\n3. 在 `internal/routers/` 注册路由\n4. 在 `internal/validator/form/` 定义参数验证\n\n### 数据库迁移\n\n创建新的迁移文件：\n```bash\nmigrate create -ext sql -dir data/migrations -seq add_user_table\n```\n\n执行迁移：\n```bash\nmigrate -database 'mysql://...' -path data/migrations up\n```\n\n回滚迁移：\n```bash\nmigrate -database 'mysql://...' -path data/migrations down\n```\n\n## 🔍 相关搜索关键词\n\n- Go Admin - Go 后台管理系统框架\n- Go 管理后台 - 基于 Gin 的管理后台系统\n- Go Admin Panel - Go 管理面板框架\n- Go 后台框架 - 企业级 Go 后台管理系统\n- Go Admin System - 完整的 Go 管理后台解决方案\n- Gin Admin - 基于 Gin 框架的管理后台\n- Go 管理系统 - RBAC 权限管理的 Go 系统\n- Go 后台管理 - 开箱即用的 Go Admin 框架\n\n## 🤝 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n## 📄 许可证\n\n本项目采用 MIT 许可证，详情请查看 [LICENSE](LICENSE) 文件。\n\n## 🙏 致谢\n\n感谢所有为这个项目做出贡献的开发者！\n\n## 📮 联系方式\n\n如有问题或建议，请通过以下方式联系：\n\n- 提交 [Issue](https://github.com/wannanbigpig/gin-layout/issues)\n- 查看 [接口文档](https://apifox.com/apidoc/shared-721e0594-dea4-4d86-bad3-851b51c16e03)\n\n---\n\n⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwannanbigpig%2Fgin-layout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwannanbigpig%2Fgin-layout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwannanbigpig%2Fgin-layout/lists"}