# Kylin Core - 法律合规文档

> **版本**: 1.0  
> **最后更新**: 2026-06-19  
> **适用范围**: 所有使用 kylin/core 作为基础依赖的扩展包  

---

## 一、适用法律法规

### 1.1 等保 2.0 (GB/T 22239-2019)

| 控制点 | 要求 | 合规要点 |
|------|------|----------|
| 通信安全 (8.1.4.3) | 应在通信前基于密码技术对通信双方进行验证或认证 | 全站 HTTPS 强制 |
| 安全响应头 (8.1.4.3) | 应采取必要措施防止敏感信息泄露 | 安全响应头中间件 |
| 安全审计 (8.1.4.6) | 应启用安全审计功能，审计覆盖到每个用户 | 全局异常处理 + 请求日志 |
| 入侵防范 (8.1.3.2) | 应遵循最小安装的原则，仅安装需要的组件和应用程序 | 速率限制、安全响应头 |

### 1.2 《中华人民共和国网络安全法》(2017.6.1)

| 条款 | 要求 | 合规要点 |
|------|------|----------|
| 第二十一条 | 采取防范计算机病毒和网络攻击、网络侵入等危害网络安全行为的技术措施 | 安全响应头、速率限制、XSS防护 |
| 第二十二条 | 网络产品、服务应当符合相关国家标准的强制性要求 | 等保 2.0 合规 |
| 第二十四条 | 网络运营者为用户提供服务时，应当要求用户提供真实身份信息 | 认证模块需支持实名 |

### 1.3 《中华人民共和国数据安全法》(2021.9.1)

| 条款 | 要求 | 合规要点 |
|------|------|----------|
| 第二十一条 | 建立数据分类分级保护制度 | 统一响应格式支持数据分类标记 |
| 第二十七条 | 数据处理活动风险监测 | Trace ID 全链路追踪 |

### 1.4 《中华人民共和国个人信息保护法》(2021.11.1)

| 条款 | 要求 | 合规要点 |
|------|------|----------|
| 第五十一条 | 采取加密、去标识化等安全技术措施 | 安全响应头、HSTS |

### 1.5 OWASP Top 10 (2021)

| 风险 | 防护措施 | 合规要点 |
|------|------|----------|
| A01:2021 访问控制失效 | 速率限制、安全响应头 | 全局限流 |
| A02:2021 加密失败 | HSTS 强制 HTTPS | 安全响应头 |
| A03:2021 注入 | 统一异常处理拦截 | 异常即安全 |
| A05:2021 安全配置错误 | 安全响应头默认开启 | CSP、X-Frame-Options |
| A07:2021 认证失败 | 速率限制防暴力破解 | 认证路由限流 |

### 1.6 RFC 9457 Problem Details for HTTP APIs

| 要求 | 合规要点 |
|------|------|
| type 字段 | 错误类型 URI |
| title 字段 | 人类可读错误摘要 |
| status 字段 | HTTP 状态码 |
| detail 字段 | 详细错误说明 |

---

## 二、行业规范

### 2.1 企业级 API 设计

- 依据 **RFC 9457** Problem Details 规范，统一错误响应格式
- 依据 **Google API Design Guide**，错误码采用语义化设计
- 依据 **Microsoft REST API Guidelines**，响应结构统一

### 2.2 安全基线

- 最小权限原则：仅暴露必要的 API 端点
- 纵深防御：全局异常处理 + 安全响应头 + 速率限制
- 默认安全：安全配置默认开启，需显式关闭

---

## 三、合规检查清单

### 3.1 安全响应头

- [x] X-Content-Type-Options: nosniff
- [x] X-Frame-Options: DENY
- [x] X-XSS-Protection: 1; mode=block
- [x] Referrer-Policy: strict-origin-when-cross-origin
- [x] Permissions-Policy: camera=(), microphone=(), geolocation=()
- [x] Content-Security-Policy: script-src/style-src/img-src 完整配置
- [x] Strict-Transport-Security: max-age=31536000（生产环境）

### 3.2 速率限制

- [x] 全局 API 速率限制（默认 60次/分钟）
- [x] 认证路由限流（默认 5次/分钟）
- [x] 游戏路由限流（默认 30次/分钟）

### 3.3 统一响应格式

- [x] code + message + data + trace_id 结构
- [x] 兼容 RFC 9457 Problem Details
- [x] 错误码语义化（{包前缀}-{分类}-{编号}）

### 3.4 异常处理

- [x] 全局异常处理器
- [x] 策略模式映射异常类型
- [x] 生产环境不泄露敏感错误信息

### 3.5 请求追踪

- [x] X-Trace-Id 请求链追踪
- [x] 跨服务传递

---

## 四、代码检测报告

### 4.1 检测结果

| 检测项 | 状态 | 说明 |
|------|------|------|
| X-Content-Type-Options | ✅ 已通过 | nosniff |
| X-Frame-Options | ✅ 已修复 | 从 SAMEORIGIN 修正为 DENY，与配置一致 |
| X-XSS-Protection | ✅ 已通过 | 1; mode=block |
| Referrer-Policy | ✅ 已通过 | strict-origin-when-cross-origin |
| Permissions-Policy | ✅ 已通过 | camera=(), microphone=(), geolocation=() |
| Content-Security-Policy | ✅ 已修复 | 新增 `buildCspHeader()` 方法，从配置读取 CSP 策略并设置响应头 |
| HSTS | ✅ 已修复 | 新增 HSTS 响应头，支持 max_age/includeSubDomains/preload 配置 |
| 速率限制 | ✅ 已通过 | 全局 + 认证 + 游戏三级限流 |
| 统一响应格式 | ✅ 已通过 | RFC 9457 Problem Details |
| Trace ID 追踪 | ✅ 已通过 | X-Trace-Id 请求链追踪 |
| 全局异常处理 | ✅ 已通过 | ApiExceptionHandler 策略模式 |
| 错误码体系 | ✅ 已通过 | ErrorCodeInterface 枚举 |

### 4.2 审查结论

**本包代码合规性良好。** 核心基础包作为所有扩展包的底层依赖，安全响应头、速率限制、统一响应格式等基础设施已完备。

---

## 五、免责声明

本扩展包在代码层面实现了安全合规的基础能力，但不构成法律建议。使用方应：

1. 根据实际部署环境配置安全响应头参数
2. 生产环境启用 HSTS
3. 定期进行安全渗透测试
4. 咨询专业安全顾问，确保系统整体安全合规