# mss-boot-admin
**Repository Path**: mss-boot-io/mss-boot-admin
## Basic Information
- **Project Name**: mss-boot-admin
- **Description**: 基于Gin + React + Atndv5 + Umiv4 + mss-boot 的前后端分离权限管理系统, beta环境: https://admin-beta.mss-boot-io.top swagger: https://mss-boot-io.github.io/mss-boot-admin-api/swagger.json
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 4
- **Forks**: 0
- **Created**: 2024-01-04
- **Last Updated**: 2026-06-30
## Categories & Tags
**Categories**: Uncategorized
**Tags**: admin, mss-boot, mss-boot-admin, Ant-Design, Go语言
## README
# mss-boot-admin
[](https://github.com/mss-boot-io/mss-boot-admin/actions/workflows/ci.yml)
[](https://github.com/mss-boot-io/mss-boot-admin/releases)
[](https://github.com/mss-boot-io/mss-boot-admin/blob/main/LICENSE)
English | [简体中文](./README.zh-CN.md)
## Introduction
> `mss-boot-admin` is a front-end and back-end separation admin platform based on Gin, React, Ant Design v5, Umi v4, and mss-boot. Its current product focus is governance, operations, configuration, access control, internationalization, and AI-annotation-assisted engineering collaboration.
> The repository still contains some historical dynamic-model and code-generation related capabilities, but they are no longer the primary direction for future product investment.
## Recent Updates
The project has undergone comprehensive polish rounds focusing on:
- **Stability (P0)**: Fixed nil dereference risks, boundary checks, panic prevention, auth coverage, and polling cleanup
- **Code Quality**: Eliminated all TypeScript errors, unified page structures, removed duplicate keys
- **Abstraction**: Created reusable components (AuthShell, useMonitorData hook), unified API response format
- **Testing**: Documented 70+ test cases, executed core scenarios successfully
- **Documentation**: Added CHANGELOG, CONTRIBUTING guide, and comprehensive configuration tutorial
[Beta Environment](https://admin-beta.mss-boot-io.top)
[Swagger](https://mss-boot-io.github.io/mss-boot-admin/swagger.json)
## Tutorial
[Online documentation](https://docs.mss-boot-io.top)
[Video tutorial](https://space.bilibili.com/597294782/channel/seriesdetail?sid=3881026)
## Project address
[Backend project](https://github.com/mss-boot-io/mss-boot-admin)
[Front-end project](https://github.com/mss-boot-io/mss-boot-admin-antd)
## 🎬 Experience environment
[Experience address](https://admin-beta.mss-boot-io.top)
> Account: admin Password: 123456
## ✨ Features
- Support internationalization
- Standard Restful API development specifications
- RBAC permission management based on Casbin
- Database storage based on Gorm
- Middleware development based on Gin
- Swagger document generation based on Gin
- Support oauth2.0 third-party login
- Support swagger document generation
- Support multiple configuration sources (local files, embed, object storage s3, etc., databases supported by gorm, mongodb)
- Support database migration
- Support governance-oriented admin modules such as users, roles, menus, departments, posts, APIs, and configuration
- Support operational modules such as notices, tasks, monitoring, and statistics
- Evolving toward AI-annotation-assisted engineering workflows for clearer collaboration and delivery discipline
## 📦 Built-in functions
- User management: Users are system operators, and this function mainly completes the configuration of system users.
- Department management: Maintain organization hierarchy and ownership boundaries.
- Post management: Maintain post data for organization and permission collaboration.
- Role management: Role menu permission allocation, set role data range permission division by organization.
- Menu management: Configure system menus, operation permissions, button permission identifiers, etc.
- API management: Maintain API registry information for governance and permission mapping.
- Option management: dynamically configure enumerations.
- System configuration: Manage the configuration of various environments.
- Notice announcement: user notification message.
- Task management: Manage scheduled tasks, including execution logs.
- Internationalization management: Manage internationalization resources.
- Account and token management: Support OAuth2 binding and personal access tokens.
- Monitoring and statistics: Provide runtime visibility and statistics querying capabilities.
## RBAC Glossary
| Term | Meaning in mss-boot-admin |
| --- | --- |
| User | A system operator. Users authenticate, receive roles, and operate within the permissions granted by those roles. |
| Role | A permission group stored in `mss_boot_roles`. Roles are the main subject in Casbin policies and are assigned to users. |
| Menu | A frontend navigation or permission node stored in `mss_boot_menus`. Menu records can represent directories, pages, components, or API permission nodes. |
| API | A backend route record stored in `mss_boot_api`, usually generated from Gin route metadata and used for permission governance. |
| Permission path | The menu/API path written into authorization requests and Casbin rules. Duplicate or blank paths are ignored before rules are built. |
| Casbin rule | A policy row in `mss_boot_casbin_rule`. The common shape is `p, roleID, accessType, path, method`. |
| Access type | The rule scope, such as `MENU`, `API`, or component access. Role authorization can combine menu rules and child API rules. |
| Data scope | The organization/data boundary attached to a role. It controls which department-owned data a role should be able to access. |
| Default role | A role marked as default. New menu access can be granted to it automatically when menu records are created. |
## 📦 Preparation
- Install Go 1.26+
- Optional for backend integration testing: MySQL 8.0+ and Redis 7+
- Frontend development: Node.js 22+ and pnpm 9+
## 📦 Quick start
### 1. Download the project
```shell
# Download the backend project
git clone https://github.com/mss-boot-io/mss-boot-admin.git
# Download the front-end project
git clone https://github.com/mss-boot-io/mss-boot-admin-antd.git
```
### 2. Migrate the database
```shell
# Enter the backend project
cd mss-boot-admin
# The default local config uses SQLite: mss-boot-admin-local.db
go run main.go migrate
```
If you want to use MySQL locally, start `compose/mysql/docker-compose.yml` and update
`config/application.yml` (`database.driver` and `database.source`) before running the
migration command.
### 3. Generate API interface information
```shell
# Generate API interface information
go run main.go server -a
```
### 4. Start the backend service
```shell
# Start the backend service
go run main.go server
```
### 5. Start the front-end service
```shell
# Enter the front-end project
cd mss-boot-admin-antd
# Install dependencies
corepack enable
pnpm install
# Start the front-end service
pnpm start:dev
```
## 📨 Interaction
 |
 |
 |
 |
mss-boot-io |
| telegram🔥🔥🔥 |
WeChat |
WeChat MP🔥🔥🔥 |
 |
bilibili🔥🔥🔥 |
## 💎 Contributors
## JetBrains open source certificate support
The `mss-boot-io` project has always been developed in the GoLand integrated development environment under JetBrains, based on the **free JetBrains Open Source license(s)** genuine free license. I would like to express my gratitude.
## 🤝 Special thanks
1. [ant-design](https://github.com/ant-design/ant-design)
2. [ant-design-pro](https://github.com/ant-design/ant-design-pro)
3. [umi](https://umijs.org)
4. [gin](https://github.com/gin-gonic/gin)
5. [casbin](https://github.com/casbin/casbin)
6. [gorm](https://github.com/jinzhu/gorm)
7. [gin-swagger](https://github.com/swaggo/gin-swagger)
8. [jwt-go](https://github.com/dgrijalva/jwt-go)
9. [oauth2](https://pkg.go.dev/golang.org/x/oauth2)
## 🤟 Sponsor Us
If you think this project helped you, you can buy a glass of juice for the author to show encouragement 🍹
## Testing
The project follows strict testing requirements to ensure code quality and reliability.
### Local Test Prerequisites
`make test` runs `go test -coverprofile=coverage.out ./...`. Before opening a backend PR, check these local prerequisites:
- Use Go 1.26+, matching `go.mod` and GitHub Actions.
- Run `make deps` once after pulling dependency or `go.sum` changes.
- Redis-backed tests generally use `miniredis`, but a local Redis 7 instance is useful when validating cache/session behavior manually.
- No real production DSN, token, Kubernetes cluster, or private credential is required for `make test`.
- CI starts Redis 7 with `supercharge/redis-github-action`, then runs `make deps`, `make test`, and `make build`.
If a local test fails because an optional external service is unavailable, mention that in the PR verification notes and include the exact command output. Do not paste real credentials or production endpoints.
### Test Types
#### 1. Unit Tests
- **Location**: `*_test.go` alongside source files
- **Minimum coverage**: **80%**
- **Run command**:
```bash
go test ./... -v -coverprofile=coverage.out
```
- **Verify coverage**:
```bash
go tool cover -html=coverage.out
# Or check terminal summary
go tool cover -func=coverage.out | grep total
```
#### 2. Integration Tests
- **Focus**: API endpoints with database interactions
- **Test databases**: Use test databases (SQLite in-memory for unit tests, real DB for integration)
- **Run command**:
```bash
go test -tags=integration ./...
```
- **Verify**: Database migrations, API contracts, and service integrations
#### 3. End-to-End (E2E) Tests
- **Full Stack Testing**: Uses Playwright for browser automation
- **Critical user flows**: login, CRUD operations, permissions
- **Run command**: `pnpm e2e` (executed in frontend project)
### Development Workflow
```text
1. DEVELOPMENT PHASE
└── Write code
└── Write tests (TDD preferred)
└── Ensure compilation
2. TESTING PHASE (MANDATORY)
├── Unit Tests: go test ./...
├── Integration Tests: go test -tags=integration ./...
└── E2E Tests: pnpm e2e (for major features)
3. VERIFICATION PHASE
├── Check test coverage (≥80%)
├── All tests must pass
└── Document test results
```
### Coverage Requirements by Component
| Component | Unit Tests | Integration Tests | Min Coverage |
|-----------|-----------|-------------------|--------------|
| Models | ✅ Required | Optional | 80% |
| Services | ✅ Required | ✅ Required | 85% |
| APIs | ✅ Required | ✅ Required | 80% |
| Utils | ✅ Required | Optional | 90% |
### Test Structure Example
```go
// service/user_test.go
package service
import (
"testing"
"github.com/stretchr/testify/assert"
)
func TestUserService_Create(t *testing.T) {
// Setup
db := setupTestDB(t)
svc := &UserService{}
// Execute
user, err := svc.Create(ctx, &CreateUserRequest{...})
// Verify
assert.NoError(t, err)
assert.NotNil(t, user)
assert.Equal(t, "expected", user.Field)
}
```
### Pre-commit Hooks
Before committing, run:
```bash
# Run all tests
go test ./... -v -race -coverprofile=coverage.out
# Check coverage meets requirements
go tool cover -func=coverage.out | grep total # Must be ≥ 80.0%
```
## 🔑 License
[MIT](https://github.com/mss-boot-io/mss-boot-admin/blob/main/LICENSE)
Copyright (c) 2024 mss-boot-io