XiRang（息壤） 是一个现代化的企业级管理系统，采用前后端分离架构，提供完整的用户权限管理、系统配置、操作审计等功能。

息壤是中国古代传说中的神物，能够自动生长。我将项目命名为 xirang，希望在不断学习积累中，项目也能够持续成长，并拥有丰富的生命力。

• 🚀 现代化技术栈 - Go 1.24 + Vue 3 + TypeScript + Element Plus
• 🏗️ 前后端分离 - RESTful API设计，支持多端接入
• 🔐 完整权限系统 - 基于Casbin的RBAC权限控制，支持菜单、API、按钮级权限
• 🎯 自动化管理 - API权限自动注册，智能路径匹配
• 📊 数据库兼容 - 支持MySQL和SQLite3，生产和开发环境灵活切换
• 🐳 容器化部署 - 完整的Docker支持，一键部署
• 📝 完整文档 - 详细的开发指南、API文档和部署说明
• 🔧 开发友好 - 热重载开发环境，自动化开发工具

技术	版本	说明
Go	1.24	高性能编程语言
Gin	1.10	高性能Web框架
GORM	1.24	ORM框架
Casbin	2.22	权限管理框架
JWT	2.6	身份认证
Redis	-	缓存数据库
Zap	1.19	高性能日志库
Swagger	-	API文档
Viper	1.11	配置管理

技术	版本	说明
Vue	3.4	渐进式框架
TypeScript	5.4	类型安全
Element Plus	2.7	UI组件库
Pinia	2.1	状态管理
Vue Router	4.3	路由管理
Vite	5.2	构建工具
TailwindCSS	3.4	CSS框架
Axios	1.7	HTTP客户端

• 用户管理 - 完整的用户CRUD、状态管理、密码重置
• 角色管理 - 灵活的角色配置、权限分配
• 菜单管理 - 动态菜单树、多级权限控制
• API权限 - 细粒度的API权限控制，自动注册机制
• 按钮权限 - 页面内按钮级别的权限控制

• 部门管理 - 组织架构管理
• 操作日志 - 完整的用户操作审计
• 登录日志 - 用户登录行为记录
• 系统配置 - 灵活的系统参数配置
• API管理 - API分组、权限批量管理

• 自动化工具 - API权限自动注册、开发辅助脚本
• 热重载 - 前后端热重载开发环境
• API文档 - 完整的Swagger文档
• 代码规范 - ESLint、Prettier、StyleLint统一代码风格
• 类型安全 - 全面的TypeScript类型支持

• 多数据库 - MySQL/SQLite3双数据库支持
• 缓存系统 - Redis缓存，提升性能
• 文件上传 - 支持本地、阿里云OSS、七牛云等
• 限流保护 - 令牌桶限流，防止接口滥用
• 容器化 - 完整的Docker支持

• Go 1.24+
• Node.js 18+
• MySQL 5.7+ / SQLite3
• Redis (可选)

使用开发辅助脚本快速启动项目：

# 克隆项目
git clone https://github.com/eryajf/xirang.git
cd xirang

# 检查服务状态
./dev-helper.sh status

# 启动所有服务
./dev-helper.sh start-all

# 获取测试token
./dev-helper.sh token

# 测试API接口
./dev-helper.sh test /system/user/info

cd admin-server

# 复制配置文件
cp config.yml.example config.yml
# 修改数据库配置

# 安装依赖
go mod tidy

# 启动服务
go run main.go
# 或使用热重载
air

cd admin-ui-pc

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

• 前端地址: http://localhost:8848
• 后端API: http://localhost:8888/api
• API文档: http://localhost:8888/swagger/index.html

• 用户名: admin
• 密码: 123456

使用 Docker Compose 快速部署完整系统：

# 克隆项目
git clone https://github.com/eryajf/xirang.git
cd xirang

# 一键启动（包含前端、后端、MySQL、Redis）
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

使用开发版本的 Docker Compose 进行开发：

# 启动开发环境（支持热重载）
docker-compose -f docker-compose.dev.yml up -d

# 查看开发环境日志
docker-compose -f docker-compose.dev.yml logs -f

cd admin-server

# 构建后端镜像
docker build -t xirang-backend:latest .

# 运行后端容器（需要先启动MySQL和Redis）
docker run -d \
  --name xirang-backend \
  -p 8888:8888 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config.yml:/app/config.yml:ro \
  --network xirang-network \
  xirang-backend:latest

cd admin-ui-pc

# 构建前端镜像
docker build -t xirang-frontend:latest .

# 运行前端容器
docker run -d \
  --name xirang-frontend \
  -p 80:80 \
  --network xirang-network \
  xirang-frontend:latest

# 创建生产环境配置文件
cp docker-compose.yml docker-compose.prod.yml

# 修改生产环境配置
vim docker-compose.prod.yml

# docker-compose.prod.yml 示例
services:
  backend:
    environment:
      - MYSQL_HOST=your-mysql-host
      - MYSQL_PASSWORD=your-mysql-password
      - REDIS_HOST=your-redis-host
      - REDIS_PASSWORD=your-redis-password

部署完成后的访问地址：

• 前端应用: http://localhost
• 后端API: http://localhost:8888/api
• API文档: http://localhost:8888/swagger/index.html
• MySQL: localhost:3306
• Redis: localhost:6379

所有服务都配置了健康检查，可以通过以下命令查看：

# 查看所有容器健康状态
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 查看特定服务健康状态
docker-compose exec backend wget -q --spider http://localhost:8888/api/system/base/ping

xirang/
├── admin-server/           # 后端服务
│   ├── controller/         # 控制器层
│   ├── logic/              # 业务逻辑层
│   ├── model/              # 数据模型层
│   ├── service/            # 服务层
│   ├── routes/             # 路由层
│   ├── middleware/         # 中间件
│   ├── config/             # 配置文件
│   ├── public/             # 静态资源
│   └── main.go             # 入口文件
├── admin-ui-pc/            # 前端项目
│   ├── src/
│   │   ├── views/          # 页面组件
│   │   ├── components/     # 通用组件
│   │   ├── stores/         # 状态管理
│   │   ├── router/         # 路由配置
│   │   ├── api/            # API接口
│   │   └── utils/          # 工具函数
│   └── package.json
├── dev-helper.sh           # 开发辅助脚本
├── docker-compose.yml      # Docker编排文件
├── DEV-GUIDE.md            # 开发指南
└── README.md               # 项目说明

# 系统配置
system:
  mode: debug                # 运行模式 debug/release
  port: 8888                 # 服务端口
  url-path-prefix: api       # API前缀

# 数据库配置
database:
  driver: mysql              # 数据库类型 mysql/sqlite3

mysql:
  host: 127.0.0.1
  port: 3306
  username: root
  password: 123456
  database: xirang

# JWT配置
jwt:
  key: secret key
  timeout: 12000             # token过期时间(小时)

# Redis配置
redis:
  host: 127.0.0.1
  port: 6379
  password: ""
  db: 0

// .env.development
VITE_API_URL=http://localhost:8888/api
VITE_APP_TITLE=XiRang管理系统

XiRang 提供了自动化的API权限管理系统：

// 使用API注册助手
helper := common.NewAPIRegistrationHelper(userGroup)

// 注册需要认证的API
helper.RegisterWithAuth(
    "GET", "/list", 
    UserController.List, 
    "system_user", 
    "获取用户列表", 
    authHandler, 
    "admin"
)

# 检查服务状态
./dev-helper.sh status

# 获取开发token
./dev-helper.sh token

# 测试API接口
./dev-helper.sh test /system/user/info

# 查看服务日志
./dev-helper.sh logs

详细的开发规范和最佳实践请参考 开发指南

我们欢迎所有形式的贡献！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

• 遵循现有的代码风格
• 添加必要的测试
• 更新相关文档
• 确保所有检查通过

本项目基于 MIT License 开源协议。

• Vue.js - 优秀的前端框架
• Gin - 高性能的Go Web框架
• Element Plus - 基于Vue3的组件库
• Casbin - 强大的权限管理框架
• Pure Admin - UI设计灵感来源

• 🐛 报告Bug
• 💡 功能建议
• 📧 邮件联系

---