🚀 Surpass API权限开放平台 完全使用手册

📖 项目简介

Surpass 是一个企业级API权限开放平台，专为REST API资源提供无状态认证和调用服务。该平台实现了企业统一权限管理，支持通过SQL配置即可定义RESTful OpenAPI接口，无需编写代码。

✨ 核心特性

• • 🔐 无状态认证：支持JWT令牌认证

• • 🛡️ RBAC权限管理：基于角色的访问控制

• • 📝 SQL配置接口：无需代码开发，SQL配置即可定义API

• • 📚 Swagger自动生成：自动生成API文档

• • 🎯 REST API标准化：符合RESTful规范

• • 🏢 企业级统一管理：集中管理所有API资源

🏗️ 系统架构

核心组件

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端UI        │    │   API网关       │    │   数据库        │
│   Vue.js        │◄──►│   Spring Boot   │◄──►│   MySQL 8.4.2+  │
│   Element Plus  │    │   JWT认证       │    │   权限存储      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

数据库表结构

• • auth_resource：API资源表

• • auth_role：角色表

• • auth_user：用户表

• • auth_role_resource_bind：角色资源绑定表

• • auth_user_role_bind：用户角色绑定表

🛠️ 快速部署指南

环境要求

• • JDK: 17+

• • MySQL: 8.4.2+

• • Node.js: 推荐16+

• • 操作系统: Windows/Linux/macOS

第一步：数据库初始化

-- 创建数据库
CREATE DATABASE surpass CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 导入表结构（执行 db/1.0.0/schema.sql）
-- 导入初始数据（执行 db/1.0.0/data.sql）

第二步：后端服务启动

# 1. 克隆项目
git clone https://gitee.com/dromara/surpass.git
cd surpass

# 2. 修改配置文件
# 编辑 application.yml 配置数据库连接信息

# 3. 启动服务
mvn spring-boot:run
# 或打包运行
mvn clean package
java -jar target/surpass-*.jar

第三步：前端服务启动

# 1. 进入前端目录
cd surpass-ui

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev

# 4. 生产环境构建
npm run build

访问地址：http://localhost:3154

📋 核心功能使用

🔐 用户认证

1. 用户注册登录

• • 支持用户名、手机号、邮箱登录

• • 密码采用MD5+盐值加密存储

• • 支持多端登录（Web、Android、iOS、Windows、Mac、Linux）

2. JWT令牌获取

POST /auth/login
{
  "username": "admin",
  "password": "password"
}

# 返回JWT令牌
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": 3600
}

🛡️ 权限管理

1. 角色管理

• • 创建角色：管理员、开发者、访客等

• • 角色权限配置：细粒度权限控制

• • 角色状态管理：启用/禁用角色

2. 资源管理

• • API资源注册：支持GET、POST、PUT、DELETE、PATCH方法

• • 资源分类管理：按业务模块分类

• • 访问控制：基于URL路径的权限控制

3. 用户授权

• • 用户-角色绑定：一个用户可拥有多个角色

• • 角色-资源绑定：一个角色可访问多个资源

• • 权限继承：支持角色层级管理

📝 OpenAPI配置

1. SQL配置API

-- 示例：查询用户列表
INSERT INTO auth_resource (
  name, code, uri, type, method, description
) VALUES (
'用户列表查询', 
'user.list', 
'/api/users', 
'SELECT', 
'GET',
'查询系统用户列表'
);

-- 对应的SQL配置
-- SELECT id, username, email, phone FROM auth_user WHERE status = 1

2. API调试

• • Swagger UI集成：可视化API调试

• • 在线测试：支持参数传递和响应查看

• • 认证测试：支持JWT令牌认证测试

📊 监控与日志

1. 访问日志

• • 用户操作日志：登录、注册、登出记录

• • API调用日志：接口访问成功/失败记录

• • 异常日志：系统错误和异常信息

2. 实时监控

• • 在线用户统计

• • API调用频率监控

• • 系统性能指标

⚙️ 高级配置

JWT配置

jwt:
  secret: your-secret-key
  expiration: 3600  # 令牌过期时间（秒）
  refresh-expiration: 604800  # 刷新令牌过期时间

数据库连接配置

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/surpass?useUnicode=true&characterEncoding=utf8
    username: root
    password: your-password
    driver-class-name: com.mysql.cj.jdbc.Driver

CORS配置

cors:
  allowed-origins: "*"
  allowed-methods: "GET,POST,PUT,DELETE,OPTIONS"
  allowed-headers: "*"
  allow-credentials: true

🔄 常见操作流程

1. 新API接入流程

创建API资源
配置SQL语句
设置访问权限
测试API接口
生成Swagger文档
发布API

2. 用户权限配置流程

创建用户
分配角色
配置角色权限
权限验证测试
正式授权

🚨 注意事项

安全配置

1. 1. JWT密钥：使用强密钥，定期更换

2. 2. 数据库安全：限制数据库访问权限

3. 3. HTTPS部署：生产环境必须使用HTTPS

4. 4. 密码策略：强制复杂密码要求

性能优化

1. 1. 数据库索引：为常用查询字段添加索引

2. 2. 缓存策略：使用Redis缓存热点数据

3. 3. 连接池配置：合理配置数据库连接池

4. 4. API限流：防止API恶意调用

🆘 故障排查

常见问题

1. JWT令牌过期

问题：API调用返回401未授权
解决：刷新令牌或重新登录

2. 权限不足

问题：API调用返回403禁止访问
解决：检查用户角色和资源权限配置

3. 数据库连接失败

问题：启动时数据库连接异常
解决：检查数据库服务状态和连接配置

日志查看

# 查看应用日志
tail -f logs/surpass.log

# 查看错误日志
grep ERROR logs/surpass.log

📚 相关资源

官方文档

• • Gitee仓库：https://gitee.com/dromara/surpass

• • GitHub仓库：https://github.com/tomsun28/surpass

技术栈

• • 后端：Spring Boot + MyBatis + JWT

• • 前端：Vue.js + Element Plus + Axios

• • 数据库：MySQL 8.4.2+

• • 文档：Swagger/OpenAPI 3.0

开源协议

本项目采用 Apache License 2.0 开源协议

🎯 最佳实践

开发建议

1. 1. API设计：遵循RESTful设计原则

2. 2. 权限粒度：按业务需求细化权限控制

3. 3. 版本管理：API版本控制策略

4. 4. 文档维护：及时更新API文档

运维建议

1. 1. 定期备份：数据库定期备份策略

2. 2. 监控告警：设置系统监控和告警

3. 3. 安全审计：定期进行安全审计

4. 4. 性能监控：持续监控系统性能指标

📞 技术支持

如遇到问题，可以通过以下方式获取帮助：

• • 提交Issue到Gitee仓库

• • 查看项目文档和FAQ

• • 参与社区讨论和交流

Surpass API权限开放平台 - 让API管理更简单！ 🎉

本文档基于Surpass项目最新版本编写，如有更新请以官方文档为准。