# gg-admin

**Repository Path**: go-study/gg-admin

## Basic Information

- **Project Name**: gg-admin
- **Description**: 基于 go-zero 的多租户 SaaS 后台管理系统
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-10-26
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gg-admin

基于 [go-zero](https://github.com/zeromicro/go-zero) 的多租户 SaaS 后台管理系统。

## 特性

- **多租户架构**：租户间数据隔离，超管统一管理
- **RBAC 权限体系**：基于 Casbin，支持 API 级 + 菜单级 + 按钮级权限控制
- **微服务架构**：go-zero + gRPC + Etcd 服务注册与发现
- **JWT 鉴权**：AccessToken + 黑名单机制，支持登出失效
- **操作日志**：全请求链路记录，支持分页查询
- **微信小程序登录**：支持微信授权登录
- **K8s API 集成**：命名空间级别 Pod 管理

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Go 1.23 |
| 框架 | go-zero 1.7 |
| 通信 | HTTP (REST) + gRPC |
| 服务发现 | Etcd |
| 数据库 | MySQL (GORM) |
| 缓存 | Redis |
| 权限 | Casbin |
| 对象存储 | MinIO |
| 消息队列 | RabbitMQ |
| 容器化 | Docker + Kubernetes |

## 项目结构

```
gg-admin/
├── api/admin/          # HTTP API 网关（管理后台入口）
│   └── internal/
│       ├── handler/    # 请求处理器（按业务模块分组）
│       ├── logic/      # 业务逻辑
│       ├── middleware/  # 中间件（JWT黑名单、RBAC、租户、操作日志）
│       ├── svc/        # 服务上下文（依赖注入）
│       └── types/      # 请求/响应类型定义
├── rpc/                # gRPC 微服务
│   ├── sys/            # 系统管理服务（用户/角色/菜单/操作日志）
│   ├── authHub/        # 认证中心（登录/注册/Casbin权限）
│   ├── superAdmin/     # 超管服务（租户/菜单/API管理）
│   └── k8sApi/         # K8s API 服务
├── common/             # 公共库
│   ├── errorx/         # 三码一体错误码体系
│   ├── interceptor/    # gRPC 拦截器 & API 中间件
│   ├── jwtTool/        # JWT 签发与解析
│   ├── result/         # 统一响应格式
│   └── tool/           # 工具集（加密/Redis/MinIO/微信支付/RabbitMQ）
├── deploy/             # 部署配置
│   ├── db/init/        # 数据库初始化脚本
│   ├── docker/         # Docker Compose & 镜像构建
│   ├── k8s/            # Kubernetes YAML
│   └── pm-grafana/     # Prometheus + Grafana 监控
└── .env.example        # 环境变量模板
```

## 服务端口

| 服务 | 默认端口 | 说明 |
|------|---------|------|
| api-admin | 8010 | 管理后台 HTTP API 网关 |
| rpc-sys | 7010 | 系统管理 RPC |
| rpc-superAdmin | 7020 | 超管 RPC |
| rpc-authHub | 7030 | 认证中心 RPC |
| rpc-k8sApi | 7040 | K8s API RPC |

## 数据库表

| 表名 | 说明 |
|------|------|
| sys_user | 系统用户 |
| sys_user_info | 用户扩展信息 |
| sys_user_token | 用户登录令牌 |
| sys_tenant | 租户 |
| sys_role | 角色 |
| sys_user_role | 用户-角色关联 |
| sys_menu | 菜单 |
| sys_menu_btn | 菜单按钮 |
| sys_role_menu | 角色-菜单关联 |
| sys_role_btn | 角色-按钮关联 |
| sys_api | API 接口（用于 Casbin 权限） |
| sys_operate_log | 操作日志 |
| sys_area | 地区 |
| casbin_rule | Casbin 权限规则 |

## 快速开始

### 环境要求

- Go 1.23+
- MySQL 8.0+
- Redis 6.0+
- Etcd 3.5+

### 1. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，修改为实际的数据库/Redis/Etcd 连接信息
```

### 2. 启动中间件

```bash
# 使用 Docker Compose 一键启动 MySQL + Redis + Etcd
docker-compose -f deploy/docker/docker-compose-docker.yaml up -d
```

### 3. 初始化数据库

```bash
# 创建数据库和用户
mysql -u root -p < deploy/db/init/db-create.sql

# 导入表结构（需先启动 sys RPC 服务生成 GORM AutoMigrate）
```

### 4. 启动服务

```bash
# 依次启动各 RPC 服务
cd rpc/sys && go run sys.go -f etc/sys.yaml
cd rpc/superAdmin && go run superAdmin.go -f etc/superAdmin.yaml
cd rpc/authHub && go run authHub.go -f etc/authHub.yaml
cd rpc/k8sApi && go run k8sApi.go -f etc/k8sApi.yaml

# 启动 API 网关
cd api/admin && go run admin.go -f etc/api-admin.yaml
```

### 5. 访问

API 网关默认运行在 `http://localhost:8010`

## 更多部署方式

- [Docker 部署](docs/deployment/docker-deploy.md)
- [Kubernetes 部署](docs/deployment/k8s-deploy.md)
- [手动部署](docs/deployment/manual-deploy.md)

## 架构图

```mermaid
graph TB
    subgraph "前端"
        Web[管理后台 Web]
        MP[微信小程序]
    end

    subgraph "API 网关层"
        Admin[api-admin :8010]
    end

    subgraph "RPC 服务层"
        Auth[ authHub :7030<br/>认证中心 ]
        Sys[ sys :7010<br/>系统管理 ]
        SA[ superAdmin :7020<br/>超管服务 ]
        K8s[ k8sApi :7040<br/>K8s API ]
    end

    subgraph "基础设施"
        Etcd[(Etcd<br/>服务发现)]
        MySQL[(MySQL<br/>主数据库)]
        Redis[(Redis<br/>缓存)]
        MinIO[(MinIO<br/>对象存储)]
        RabbitMQ[(RabbitMQ<br/>消息队列)]
    end

    Web --> Admin
    MP --> Auth
    Admin --> Auth
    Admin --> Sys
    Admin --> SA
    Admin --> K8s
    Auth --> Etcd
    Auth --> MySQL
    Auth --> Redis
    Sys --> MySQL
    Sys --> Redis
    SA --> MySQL
    SA --> Redis
    K8s --> Etcd
    Admin --> MinIO
```

## API 文档

启动服务后访问 Swagger 文档：`http://localhost:8010/swagger`

Swagger JSON 文件由 `scripts/generate_swagger.py` 脚本从 `api/admin/desc/*.api` 定义文件自动生成。若修改了 `.api` 文件，请重新运行：

```bash
python scripts/generate_swagger.py
```

## 许可证

[Apache License 2.0](LICENSE) · Copyright 2026 ctenni