张翔
627 lines
14 KiB
Markdown
627 lines
14 KiB
Markdown
# 健身房管理系统安全设计文档
|
||
|
||
> 文档编号：GYM-SEC-DESIGN-001
|
||
> 版本：v1.0
|
||
> 创建日期：2026-03-08
|
||
> 最后更新日期：2026-03-08
|
||
> 作者：张翔
|
||
> 状态：正式发布
|
||
|
||
## 文档修订历史
|
||
|
||
| 版本 | 日期 | 作者 | 修订内容 |
|
||
| ---- | ---------- | ---- | -------- |
|
||
| v1.0 | 2026-03-08 | 张翔 | 创建安全设计文档 |
|
||
|
||
## 参考文档
|
||
|
||
- OWASP Top 10 安全规范
|
||
- Spring Security 官方文档
|
||
- GDPR 数据保护条例
|
||
- 网络安全等级保护 2.0
|
||
|
||
---
|
||
|
||
## 一、安全架构设计
|
||
|
||
### 1.1 安全分层
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ 应用层安全 │
|
||
│ (认证、授权、输入验证、输出编码) │
|
||
├─────────────────────────────────────┤
|
||
│ 数据层安全 │
|
||
│ (加密、脱敏、审计、备份) │
|
||
├─────────────────────────────────────┤
|
||
│ 基础设施安全 │
|
||
│ (网络安全、主机安全、容器安全) │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.2 安全原则
|
||
|
||
1. **纵深防御**：多层安全防护
|
||
2. **最小权限**：只授予必要权限
|
||
3. **默认安全**：默认配置即安全
|
||
4. **零信任**：始终验证，永不信任
|
||
5. **安全审计**：所有操作可追溯
|
||
|
||
---
|
||
|
||
## 二、认证与授权
|
||
|
||
### 2.1 认证机制
|
||
|
||
#### 2.1.1 JWT Token 认证
|
||
|
||
**Token 生成**：
|
||
```java
|
||
@Component
|
||
public class JwtTokenProvider {
|
||
|
||
@Value("${jwt.secret}")
|
||
private String secretKey;
|
||
|
||
@Value("${jwt.expiration}")
|
||
private long expiration;
|
||
|
||
public String generateToken(Authentication auth) {
|
||
UserPrincipal principal = (UserPrincipal) auth.getPrincipal();
|
||
|
||
Date now = new Date();
|
||
Date expiryDate = new Date(now.getTime() + expiration);
|
||
|
||
return Jwts.builder()
|
||
.setSubject(principal.getId().toString())
|
||
.claim("tenantId", principal.getTenantId())
|
||
.claim("storeId", principal.getStoreId())
|
||
.claim("roles", principal.getRoles())
|
||
.setIssuedAt(now)
|
||
.setExpiration(expiryDate)
|
||
.signWith(SignatureAlgorithm.HS512, secretKey)
|
||
.compact();
|
||
}
|
||
}
|
||
```
|
||
|
||
**Token 验证**：
|
||
```java
|
||
@Component
|
||
public class JwtAuthenticationFilter extends OncePerRequestFilter {
|
||
|
||
@Autowired
|
||
private JwtTokenProvider tokenProvider;
|
||
|
||
@Override
|
||
protected void doFilterInternal(HttpServletRequest request,
|
||
HttpServletResponse response,
|
||
FilterChain filterChain)
|
||
throws ServletException, IOException {
|
||
try {
|
||
String jwt = getJwtFromRequest(request);
|
||
|
||
if (StringUtils.hasText(jwt) && tokenProvider.validateToken(jwt)) {
|
||
Authentication auth = tokenProvider.getAuthentication(jwt);
|
||
SecurityContextHolder.getContext().setAuthentication(auth);
|
||
}
|
||
} catch (Exception ex) {
|
||
logger.error("Could not set user authentication", ex);
|
||
}
|
||
|
||
filterChain.doFilter(request, response);
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.1.2 Token 刷新机制
|
||
|
||
**双 Token 机制**：
|
||
- Access Token：有效期 2 小时
|
||
- Refresh Token：有效期 7 天
|
||
|
||
**刷新流程**：
|
||
```java
|
||
@PostMapping("/refresh")
|
||
public Mono<ApiResponse<TokenResponse>> refreshToken(
|
||
@RequestBody RefreshTokenRequest request) {
|
||
return authService.refreshToken(request.getRefreshToken())
|
||
.map(tokens -> ApiResponse.success(tokens));
|
||
}
|
||
```
|
||
|
||
### 2.2 授权机制
|
||
|
||
#### 2.2.1 基于角色的访问控制 (RBAC)
|
||
|
||
**角色定义**：
|
||
```java
|
||
public enum Role {
|
||
SUPER_ADMIN, // 超级管理员
|
||
TENANT_ADMIN, // 租户管理员
|
||
STORE_MANAGER, // 店长
|
||
COACH, // 教练
|
||
MEMBER // 会员
|
||
}
|
||
```
|
||
|
||
**权限配置**：
|
||
```java
|
||
@Configuration
|
||
@EnableWebFluxSecurity
|
||
public class SecurityConfig {
|
||
|
||
@Bean
|
||
public SecurityWebFilterFilterChain securityFilterChain(
|
||
ServerHttpSecurity http) {
|
||
http
|
||
.authorizeExchange(exchanges -> exchanges
|
||
.pathMatchers("/api/v1/auth/**").permitAll()
|
||
.pathMatchers("/api/v1/admin/**").hasRole("ADMIN")
|
||
.pathMatchers("/api/v1/members/**").hasAnyRole("ADMIN", "COACH")
|
||
.pathMatchers("/api/v1/my/**").authenticated()
|
||
.anyExchange().permitAll()
|
||
)
|
||
.oauth2ResourceServer(oauth2 -> oauth2.jwt());
|
||
|
||
return http.build();
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.2.2 数据权限隔离
|
||
|
||
**租户隔离**：
|
||
```java
|
||
@Component
|
||
public class TenantInterceptor implements HandlerInterceptor {
|
||
|
||
@Override
|
||
public boolean preHandle(HttpServletRequest request,
|
||
HttpServletResponse response,
|
||
Object handler) {
|
||
String tenantId = request.getHeader("X-Tenant-ID");
|
||
if (StringUtils.isEmpty(tenantId)) {
|
||
throw new UnauthorizedException("缺少租户标识");
|
||
}
|
||
TenantContext.setTenantId(tenantId);
|
||
return true;
|
||
}
|
||
|
||
@Override
|
||
public void afterCompletion(HttpServletRequest request,
|
||
HttpServletResponse response,
|
||
Object handler,
|
||
Exception ex) {
|
||
TenantContext.clear();
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、数据安全
|
||
|
||
### 3.1 数据加密
|
||
|
||
#### 3.1.1 敏感数据加密存储
|
||
|
||
**加密算法**：AES-256-GCM
|
||
|
||
**加密工具类**：
|
||
```java
|
||
@Component
|
||
public class EncryptionUtil {
|
||
|
||
@Value("${encryption.key}")
|
||
private String encryptionKey;
|
||
|
||
public String encrypt(String plaintext) throws Exception {
|
||
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
|
||
SecretKeySpec keySpec = new SecretKeySpec(
|
||
encryptionKey.getBytes(), "AES");
|
||
GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(
|
||
128, generateIV());
|
||
|
||
cipher.init(Cipher.ENCRYPT_MODE, keySpec, gcmParameterSpec);
|
||
byte[] cipherText = cipher.doFinal(plaintext.getBytes());
|
||
|
||
return Base64.getEncoder().encodeToString(cipherText);
|
||
}
|
||
|
||
public String decrypt(String cipherText) throws Exception {
|
||
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
|
||
SecretKeySpec keySpec = new SecretKeySpec(
|
||
encryptionKey.getBytes(), "AES");
|
||
|
||
cipher.init(Cipher.DECRYPT_MODE, keySpec,
|
||
new GCMParameterSpec(128, generateIV()));
|
||
byte[] plainText = cipher.doFinal(
|
||
Base64.getDecoder().decode(cipherText));
|
||
|
||
return new String(plainText);
|
||
}
|
||
}
|
||
```
|
||
|
||
**加密字段**：
|
||
- 手机号
|
||
- 身份证号
|
||
- 银行卡号
|
||
- 地址
|
||
|
||
#### 3.1.2 密码加密
|
||
|
||
**BCrypt 加密**：
|
||
```java
|
||
@Bean
|
||
public PasswordEncoder passwordEncoder() {
|
||
return new BCryptPasswordEncoder(12);
|
||
}
|
||
```
|
||
|
||
### 3.2 数据脱敏
|
||
|
||
#### 3.2.1 脱敏规则
|
||
|
||
**手机号脱敏**：
|
||
```java
|
||
public class DesensitizationUtil {
|
||
|
||
public static String maskPhone(String phone) {
|
||
if (StringUtils.isEmpty(phone)) {
|
||
return "";
|
||
}
|
||
return phone.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
|
||
}
|
||
|
||
public static String maskIdCard(String idCard) {
|
||
if (StringUtils.isEmpty(idCard)) {
|
||
return "";
|
||
}
|
||
return idCard.replaceAll("(\\d{6})\\d{8}(\\d{4})", "$1********$2");
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.2.2 JSON 序列化脱敏
|
||
|
||
**自定义注解**：
|
||
```java
|
||
@Target(ElementType.FIELD)
|
||
@Retention(RetentionPolicy.RUNTIME)
|
||
@JacksonAnnotationsInside
|
||
@JsonSerialize(using = DesensitizationSerializer.class)
|
||
public @interface Desensitization {
|
||
DesensitizationType type();
|
||
}
|
||
|
||
public enum DesensitizationType {
|
||
PHONE, // 手机号
|
||
ID_CARD, // 身份证
|
||
BANK_CARD, // 银行卡
|
||
ADDRESS // 地址
|
||
}
|
||
```
|
||
|
||
**使用示例**：
|
||
```java
|
||
public class MemberDTO {
|
||
|
||
@Desensitization(type = DesensitizationType.PHONE)
|
||
private String phone;
|
||
|
||
@Desensitization(type = DesensitizationType.ID_CARD)
|
||
private String idCard;
|
||
}
|
||
```
|
||
|
||
### 3.3 数据备份
|
||
|
||
#### 3.3.1 备份策略
|
||
|
||
**全量备份**：
|
||
- 频率：每天凌晨 2 点
|
||
- 保留：最近 30 天
|
||
- 存储：异地灾备中心
|
||
|
||
**增量备份**：
|
||
- 频率：每小时
|
||
- 保留：最近 7 天
|
||
- 存储：本地高速存储
|
||
|
||
#### 3.3.2 恢复演练
|
||
|
||
- 频率：每季度一次
|
||
- 范围：随机抽取 10% 数据
|
||
- 验证：数据完整性校验
|
||
|
||
---
|
||
|
||
## 四、网络安全
|
||
|
||
### 4.1 HTTPS 强制
|
||
|
||
**配置**：
|
||
```yaml
|
||
server:
|
||
ssl:
|
||
enabled: true
|
||
key-store: classpath:keystore.p12
|
||
key-store-password: ${SSL_KEY_PASSWORD}
|
||
key-store-type: PKCS12
|
||
```
|
||
|
||
**HTTP 重定向**：
|
||
```java
|
||
@Bean
|
||
public SecurityWebFilterFilterChain securityFilterChain(
|
||
ServerHttpSecurity http) {
|
||
http
|
||
.redirectHttpsRedirect(Customizer.withDefaults());
|
||
return http.build();
|
||
}
|
||
```
|
||
|
||
### 4.2 CORS 配置
|
||
|
||
**跨域配置**：
|
||
```java
|
||
@Bean
|
||
public WebMvcConfigurer corsConfigurer() {
|
||
return new WebMvcConfigurer() {
|
||
@Override
|
||
public void addCorsMappings(CorsRegistry registry) {
|
||
registry.addMapping("/api/**")
|
||
.allowedOrigins("https://yourdomain.com")
|
||
.allowedMethods("GET", "POST", "PUT", "DELETE")
|
||
.allowedHeaders("*")
|
||
.allowCredentials(true)
|
||
.maxAge(3600);
|
||
}
|
||
};
|
||
}
|
||
```
|
||
|
||
### 4.3 限流与防 DDOS
|
||
|
||
**限流配置**：
|
||
```yaml
|
||
resilience4j:
|
||
ratelimiter:
|
||
instances:
|
||
apiRateLimiter:
|
||
limit-for-period: 100
|
||
limit-refresh-period: 1s
|
||
timeout-duration: 0
|
||
|
||
loginRateLimiter:
|
||
limit-for-period: 5
|
||
limit-refresh-period: 1m
|
||
timeout-duration: 0
|
||
```
|
||
|
||
**IP 黑名单**：
|
||
```java
|
||
@Component
|
||
public class IpBlacklistFilter implements Filter {
|
||
|
||
@Autowired
|
||
private RedisTemplate<String, String> redisTemplate;
|
||
|
||
@Override
|
||
public void doFilter(ServletRequest request,
|
||
ServletResponse response,
|
||
FilterChain chain) {
|
||
String ip = getClientIp(request);
|
||
|
||
if (isBlacklisted(ip)) {
|
||
((HttpServletResponse) response).sendError(403);
|
||
return;
|
||
}
|
||
|
||
chain.doFilter(request, response);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、输入验证与输出编码
|
||
|
||
### 5.1 输入验证
|
||
|
||
**请求体验证**：
|
||
```java
|
||
public class CreateMemberRequest {
|
||
|
||
@NotBlank(message = "手机号不能为空")
|
||
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
|
||
private String phone;
|
||
|
||
@NotBlank(message = "姓名不能为空")
|
||
@Size(min = 1, max = 50, message = "姓名长度不能超过 50 个字符")
|
||
private String name;
|
||
|
||
@Email(message = "邮箱格式不正确")
|
||
private String email;
|
||
|
||
@Min(value = 0, message = "年龄不能小于 0")
|
||
@Max(value = 150, message = "年龄不能大于 150")
|
||
private Integer age;
|
||
}
|
||
```
|
||
|
||
**SQL 注入防护**：
|
||
```java
|
||
// ❌ 错误示例
|
||
@Query("SELECT m FROM Member m WHERE m.phone = :phone")
|
||
Member findByPhone(@Param("phone") String phone);
|
||
|
||
// ✅ 正确示例（使用参数化查询）
|
||
@Query("SELECT m FROM Member m WHERE m.phone = :phone")
|
||
Member findByPhone(@Param("phone") String phone);
|
||
```
|
||
|
||
**XSS 防护**：
|
||
```java
|
||
@Component
|
||
public class XssFilter implements Filter {
|
||
|
||
@Override
|
||
public void doFilter(ServletRequest request,
|
||
ServletResponse response,
|
||
FilterChain chain)
|
||
throws IOException, ServletException {
|
||
XssHttpServletRequestWrapper xssRequest =
|
||
new XssHttpServletRequestWrapper(
|
||
(HttpServletRequest) request);
|
||
chain.doFilter(xssRequest, response);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 输出编码
|
||
|
||
**HTML 编码**：
|
||
```java
|
||
public class HtmlUtil {
|
||
|
||
public static String escapeHtml(String html) {
|
||
return StringEscapeUtils.escapeHtml4(html);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、安全审计
|
||
|
||
### 6.1 审计日志
|
||
|
||
**审计内容**：
|
||
- 登录/登出
|
||
- 创建/更新/删除操作
|
||
- 数据导出
|
||
- 权限变更
|
||
|
||
**日志格式**：
|
||
```json
|
||
{
|
||
"timestamp": "2026-03-08T10:30:00Z",
|
||
"userId": 1,
|
||
"action": "CREATE_MEMBER",
|
||
"resource": "member",
|
||
"resourceId": 123,
|
||
"ip": "192.168.1.100",
|
||
"userAgent": "Mozilla/5.0...",
|
||
"result": "SUCCESS",
|
||
"details": {...}
|
||
}
|
||
```
|
||
|
||
**审计注解**：
|
||
```java
|
||
@Target(ElementType.METHOD)
|
||
@Retention(RetentionPolicy.RUNTIME)
|
||
public @interface AuditLog {
|
||
String action();
|
||
String resource();
|
||
}
|
||
```
|
||
|
||
**使用示例**：
|
||
```java
|
||
@AuditLog(action = "CREATE", resource = "member")
|
||
public Mono<Member> createMember(CreateMemberRequest request) {
|
||
return memberRepository.save(request.toEntity());
|
||
}
|
||
```
|
||
|
||
### 6.2 日志存储
|
||
|
||
**存储策略**：
|
||
- 热存储：最近 30 天，Elasticsearch
|
||
- 冷存储：30-180 天，对象存储
|
||
- 归档：180 天以上，磁带库
|
||
|
||
**日志保护**：
|
||
- 完整性：数字签名
|
||
- 机密性：加密存储
|
||
- 可用性：多副本备份
|
||
|
||
---
|
||
|
||
## 七、安全监控
|
||
|
||
### 7.1 监控指标
|
||
|
||
**认证监控**：
|
||
- 登录成功率
|
||
- 登录失败次数
|
||
- Token 刷新率
|
||
- 异常登录行为
|
||
|
||
**授权监控**：
|
||
- 权限拒绝次数
|
||
- 越权访问尝试
|
||
- 敏感操作频率
|
||
|
||
**数据监控**：
|
||
- 敏感数据访问
|
||
- 大批量数据导出
|
||
- 异常数据修改
|
||
|
||
### 7.2 告警规则
|
||
|
||
**告警级别**：
|
||
- P0（紧急）：系统被入侵、数据泄露
|
||
- P1（严重）：大规模认证失败、DDOS 攻击
|
||
- P2（警告）：异常登录行为、权限异常
|
||
- P3（提示）：配置变更、版本升级
|
||
|
||
**告警渠道**：
|
||
- 短信：P0、P1
|
||
- 邮件：P1、P2
|
||
- 钉钉/企业微信：P2、P3
|
||
|
||
---
|
||
|
||
## 八、合规性
|
||
|
||
### 8.1 GDPR 合规
|
||
|
||
**数据主体权利**：
|
||
- 知情权：明确告知数据收集目的
|
||
- 访问权：用户可查询个人数据
|
||
- 更正权：用户可修改个人数据
|
||
- 删除权：用户可申请删除数据
|
||
- 可携带权：支持数据导出
|
||
|
||
**数据保护措施**：
|
||
- 数据最小化：只收集必要数据
|
||
- 目的限制：仅用于声明的目的
|
||
- 存储限制：到期自动删除
|
||
- 安全保障：加密、访问控制
|
||
|
||
### 8.2 等保 2.0 合规
|
||
|
||
**技术要求**：
|
||
- 身份鉴别：多因素认证
|
||
- 访问控制：最小权限原则
|
||
- 安全审计：操作可追溯
|
||
- 入侵防范：实时监测告警
|
||
- 数据完整性：校验和验证
|
||
- 数据保密性：加密传输存储
|
||
|
||
**管理要求**：
|
||
- 安全管理制度
|
||
- 安全管理机构
|
||
- 人员安全管理
|
||
- 系统建设管理
|
||
- 系统运维管理
|
||
|
||
---
|
||
|
||
**文档结束**
|