makemd/serverjava/docs/06_Security_Guide.md

安全指南

1. 安全概述

Crawlful Hub 项目采用了全面的安全措施，确保系统的安全性和可靠性。本文档详细介绍了项目的安全措施和最佳实践。

2. 认证与授权

2.1 JWT 认证

Crawlful Hub 项目使用 JWT（JSON Web Token）进行认证，确保用户身份的安全性。

实现细节：

• 使用 Spring Security 实现 JWT 认证
• 配置 JWT 密钥和过期时间
• 验证 JWT 令牌的有效性

配置示例：

spring:
  security:
    jwt:
      secret: your-secret-key
      expiration: 86400000

2.2 角色授权

Crawlful Hub 项目使用基于角色的访问控制（RBAC），确保用户只能访问其权限范围内的资源。

预设角色：

• ADMIN - 全权
• MANAGER - 运营主管
• OPERATOR - 运营专员
• FINANCE - 财务主管
• SOURCING - 采购专家
• LOGISTICS - 物流专家
• ANALYST - 数据分析师

授权实现：

• 使用 @PreAuthorize 注解进行方法级别的授权
• 实现 authorize() 中间件进行路由级别的授权

示例代码：

@PreAuthorize("hasRole('ADMIN')")
public void deleteUser(Long id) {
    // 实现删除用户的逻辑
}

3. 数据安全

3.1 密码加密

Crawlful Hub 项目使用 BCrypt 对用户密码进行加密，确保密码的安全性。

实现细节：

• 使用 BCryptPasswordEncoder 对密码进行加密
• 存储加密后的密码，不存储明文密码

示例代码：

@Autowired
private PasswordEncoder passwordEncoder;

public User createUser(User user) {
    user.setPassword(passwordEncoder.encode(user.getPassword()));
    return userRepository.save(user);
}

3.2 敏感数据保护

Crawlful Hub 项目对敏感数据进行保护，确保数据的安全性。

保护措施：

• 对敏感数据进行加密存储
• 避免在日志中记录敏感信息
• 使用 HTTPS 协议传输数据

示例代码：

@Column(columnDefinition = "VARBINARY(255)")
private byte[] sensitiveData;

4. 输入验证

4.1 参数验证

Crawlful Hub 项目对输入参数进行验证，确保输入的合法性。

实现细节：

• 使用 @Valid 注解和 BindingResult 进行参数验证
• 实现 ValidationUtil 工具类进行数据验证

示例代码：

@PostMapping("/create")
public ResponseEntity<User> createUser(@Valid @RequestBody User user, BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        return ResponseEntity.badRequest().build();
    }
    return ResponseEntity.ok(userService.createUser(user));
}

4.2 SQL 注入防护

Crawlful Hub 项目使用参数化查询，防止 SQL 注入攻击。

实现细节：

• 使用 JPA 或 MyBatis 进行数据库操作
• 避免直接拼接 SQL 语句

示例代码：

// 正确的做法
@Query("SELECT u FROM User u WHERE u.username = :username")
User findByUsername(@Param("username") String username);

// 错误的做法（避免）
String sql = "SELECT * FROM user WHERE username = '" + username + "'";

5. 跨站请求伪造（CSRF）防护

Crawlful Hub 项目实现了 CSRF 防护，防止跨站请求伪造攻击。

实现细节：

• 使用 Spring Security 的 CSRF 保护
• 配置 CSRF 令牌的生成和验证

配置示例：

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse());
    }
}

6. 速率限制

Crawlful Hub 项目实现了速率限制，防止暴力破解和 DoS 攻击。

实现细节：

• 实现 RateLimitFilter 过滤器
• 基于客户端 IP 和请求 URI 进行限制
• 限制客户端每分钟最大请求数为 60 次

示例代码：

@Component
public class RateLimitFilter implements Filter {
    private final Map<String, AtomicInteger> requestCounts = new ConcurrentHashMap<>();
    private final Map<String, Long> lastResetTimes = new ConcurrentHashMap<>();
    private static final int MAX_REQUESTS_PER_MINUTE = 60;

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        String clientIp = httpRequest.getRemoteAddr();
        String requestUri = httpRequest.getRequestURI();
        String key = clientIp + ":" + requestUri;

        long currentTime = System.currentTimeMillis();
        long lastResetTime = lastResetTimes.getOrDefault(key, 0L);

        if (currentTime - lastResetTime > 60000) {
            requestCounts.put(key, new AtomicInteger(1));
            lastResetTimes.put(key, currentTime);
        } else {
            AtomicInteger count = requestCounts.get(key);
            if (count != null && count.incrementAndGet() > MAX_REQUESTS_PER_MINUTE) {
                ((HttpServletResponse) response).setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
                return;
            }
        }

        chain.doFilter(request, response);
    }
}

7. 安全日志

Crawlful Hub 项目实现了安全日志，记录系统的安全事件。

实现细节：

• 使用 Logback 配置安全日志
• 记录用户登录、登出、权限变更等安全事件
• 记录异常登录尝试和权限错误

配置示例：

<appender name="SECURITY" class="ch.qos.logback.core.rolling.RollingFileAppender">
  <file>logs/security.log</file>
  <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
    <fileNamePattern>logs/security.%d{yyyy-MM-dd}.log</fileNamePattern>
    <maxHistory>30</maxHistory>
  </rollingPolicy>
  <encoder>
    <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
  </encoder>
</appender>

<logger name="com.crawlful.hub.security" level="INFO" additivity="false">
  <appender-ref ref="SECURITY" />
</logger>

8. 安全最佳实践

8.1 代码安全

• 使用最新的依赖：定期更新项目依赖，修复安全漏洞
• 避免硬编码：避免在代码中硬编码密钥、密码等敏感信息
• 使用安全的加密算法：使用强加密算法，如 BCrypt、AES 等
• 定期代码审查：定期进行代码审查，发现和修复安全问题

8.2 服务器安全

• 使用 HTTPS：使用 HTTPS 协议传输数据
• 限制访问：限制服务器的访问范围，只允许必要的端口和 IP 访问
• 定期更新：定期更新服务器操作系统和软件，修复安全漏洞
• 使用防火墙：使用防火墙保护服务器，防止未授权访问

8.3 数据库安全

• 最小权限原则：只授予数据库用户必要的权限
• 定期备份：定期备份数据库，防止数据丢失
• 使用参数化查询：防止 SQL 注入攻击
• 加密敏感数据：对敏感数据进行加密存储

8.4 应用安全

• 使用 CSRF 保护：防止跨站请求伪造攻击
• 实现速率限制：防止暴力破解和 DoS 攻击
• 验证输入：对所有输入进行验证，防止恶意输入
• 使用安全的会话管理：使用安全的会话管理机制，防止会话劫持

9. 安全审计

9.1 审计日志

Crawlful Hub 项目实现了审计日志，记录系统的操作和事件。

实现细节：

• 使用 cf_audit 表存储审计日志
• 记录用户操作、资源访问、权限变更等事件
• 记录 IP 地址、用户代理等信息

示例代码：

@Service
public class AuditService {
    @Autowired
    private AuditRepository auditRepository;

    public void logAudit(String tenantId, String shopId, Long userId, String action, String resourceType, String resourceId, String ipAddress, String userAgent, String details) {
        Audit audit = new Audit();
        audit.setTenantId(tenantId);
        audit.setShopId(shopId);
        audit.setUserId(userId);
        audit.setAction(action);
        audit.setResourceType(resourceType);
        audit.setResourceId(resourceId);
        audit.setIpAddress(ipAddress);
        audit.setUserAgent(userAgent);
        audit.setDetails(details);
        audit.setCreatedAt(new Date());
        auditRepository.save(audit);
    }
}

9.2 安全扫描

Crawlful Hub 项目定期进行安全扫描，发现和修复安全漏洞。

扫描工具：

• OWASP ZAP：用于 Web 应用安全扫描
• SonarQube：用于代码安全扫描
• Nmap：用于网络安全扫描

扫描频率：

• 开发环境：每次代码提交后
• 测试环境：每周一次
• 生产环境：每月一次

10. 总结

本安全指南详细介绍了 Crawlful Hub 项目的安全措施和最佳实践。通过本指南，您可以了解如何确保系统的安全性和可靠性。