MrleeAdmin/doc/api-encryption-design.md

# 接口加密方案设计（适配 MrleeAdmin / Madong 项目）

## 1. 文档目标

本文档用于为当前项目设计一套**符合现有架构、可渐进落地、支持前后台统一接入**的接口加密方案。

设计目标：

- 在**不破坏现有接口返回规范**的前提下，为 API 增加可配置的请求/响应加密能力。
- 同时适配：
  - `backend`（Webman / PHP）
  - `frontend/admin`（Vue 3 + Axios）
  - `frontend/web`（Nuxt 4 + fetch 封装）
- 支持：
  - **关闭加密**
  - **部分加密**
  - **全局加密**
- 支持后续扩展：
  - 密钥轮换
  - 按模块排除
  - 注解/Attribute 标记接口是否加密
  - 管理端可视化配置页面

本文档是**总体方案设计文档**，不是直接实现文档；但所有设计都以当前项目真实结构为前提，可直接指导后续开发。

---

## 2. 当前项目现状结论

### 2.1 当前接口未做统一加密

经核实，当前项目主链路没有统一接口加密能力。

现状如下：

- 后端统一返回封装 `backend/core/tool/Json.php`
  - 直接输出标准 JSON：`code / msg / data`
  - 没有 AES / RSA / 自定义密文包装逻辑
- 前台 Web 请求封装 `frontend/web/app/utils/request.ts`
  - 直接 `response.json()`
  - 按 `code / msg / data` 处理
  - 没有解密逻辑
- Admin 请求封装 `frontend/admin/src/utils/http/index.ts`
  - `transformResponse` 直接 `JSON.parse`
  - 响应拦截器直接读取 `response.data.code / msg / data`
  - 没有解密逻辑

### 2.2 当前项目没有代码层强制 HTTPS

经核实，当前仓库代码没有发现全局强制 HTTPS 的逻辑：

- 没有发现统一 `forceScheme('https')`
- 没有发现 HTTP -> HTTPS 跳转中间件
- 前端 `.env` 使用相对 API 路径：
  - `frontend/admin/.env.production` 中 `VITE_API_URL=/adminapi`
  - `frontend/web/.env` 中 `VITE_APP_BASE_URL=/api`
- `backend/config/session.php` 中 `secure => false`

结论：

- 当前生产环境是否使用 HTTPS，取决于 **Nginx / 反向代理 / 宝塔站点 / CDN** 等部署层配置。
- 接口加密方案**不能替代 HTTPS**，建议生产环境必须启用 HTTPS。

---

## 3. 设计原则

### 3.1 不使用“前端持有私钥”方案

必须明确：

- **RSA 私钥不能下发到前端**
- 前端只能持有 **RSA 公钥**
- 后端持有 **RSA 私钥**

如果将私钥配置到浏览器侧，则任何接口加密都失去意义。

### 3.2 采用 RSA + AES 混合加密

不直接使用 RSA 加密整个请求/响应包体，原因：

- RSA 性能较差
- RSA 明文长度有限制
- JSON 包体、分页数据、列表数据通常不适合直接用 RSA 全量加密

采用混合加密：

- **请求体 / 响应体**：使用 AES 加密
- **AES 会话密钥**：使用 RSA 公钥加密传输
- **AES 解密密钥**：后端使用 RSA 私钥解出

这是兼顾安全性、可用性、性能和扩展性的主流方案。

### 3.3 保持现有响应协议语义不变

当前项目大量前后端逻辑依赖如下结构：

```json
{
  "code": 0,
  "msg": "获取成功",
  "data": {}
}
```

加密改造后，必须尽量保持**业务语义兼容**，避免影响错误处理、Token 刷新、UI 消息提示、分页通用逻辑。

### 3.4 先支持 JSON 接口，再扩展其他流类型

第一阶段仅支持：

- `application/json`
- 普通 GET / POST / PUT / DELETE 业务接口

第一阶段不直接纳入：

- 文件上传 `multipart/form-data`
- 文件下载 `blob / stream`
- SSE / 长连接
- 第三方回调接口
- Swagger / OpenAPI 文档接口

这些接口应通过**排除策略**先保持明文。

### 3.5 渐进落地，先可切换后全量接入

建议分阶段：

- 第一阶段：支持开关和部分加密
- 第二阶段：支持全局加密
- 第三阶段：补齐密钥轮换、排除规则、监控、告警

---

## 4. 目标能力范围

方案最终应支持以下能力：

### 4.1 加密开关

- 关闭
- 部分加密
- 全局加密

### 4.2 加密方向

- 请求体加密
- 响应体加密

说明：

- 只做响应加密意义有限
- 推荐请求与响应一起做

### 4.3 前后端统一接入

- Admin 端统一请求封装接入
- Web 端统一请求封装接入
- 后端统一请求解密中间件 + 响应加密中间件接入

### 4.4 接口排除与例外能力

需要支持排除：

- 登录前置公钥获取接口
- Token 刷新接口
- 文件上传/下载接口
- SSE 接口
- 第三方回调接口
- OpenAPI / Swagger 文档接口

### 4.5 密钥管理能力

- RSA 密钥对生成
- RSA 公钥发布
- RSA 私钥仅服务端存储
- 支持重新生成密钥
- 后续支持密钥版本号和轮换

---

## 5. 总体架构设计

### 5.1 核心流程

#### 请求流程

1. 前端生成一次性 AES Key + IV
2. 前端使用 AES 加密业务请求数据
3. 前端使用 RSA 公钥加密 AES Key（必要时也包含 IV）
4. 前端将密文提交给后端
5. 后端使用 RSA 私钥解出 AES Key
6. 后端使用 AES 解密业务数据
7. 后端将解密结果重新写回请求上下文，供控制器正常读取

#### 响应流程

1. 控制器照常返回 `Json::success()` / `Json::fail()`
2. 响应加密中间件判断当前接口是否需要加密
3. 将原始 JSON 响应体用 AES 加密
4. 按统一密文结构返回前端
5. 前端响应拦截器识别密文结构并解密
6. 还原为原始 `code / msg / data` 结构，再继续走现有业务流程

### 5.2 推荐密文协议结构

#### 请求体结构

```json
{
  "encrypted": true,
  "algorithm": "rsa-aes",
  "key_version": "v1",
  "key": "<RSA加密后的AES密钥>",
  "iv": "<Base64 IV 或并入 key 元数据>",
  "data": "<AES加密后的业务密文>",
  "timestamp": 1720000000,
  "nonce": "random-string"
}
```

#### 响应体结构

```json
{
  "encrypted": true,
  "algorithm": "rsa-aes",
  "key_version": "v1",
  "data": "<AES加密后的响应密文>"
}
```

说明：

- 如果请求与响应共用同一个 AES Key，则响应体中可以不再返回 `key`
- 如果设计为响应重新生成一次性响应 AES Key，则响应体还要额外返回新的加密 key
- 对本项目第一阶段，建议：
  - **响应复用请求里的 AES Key**
  - 可降低协议复杂度

---

## 6. 加密算法建议

### 6.1 RSA 方案

建议：

- `RSA 2048` 起步
- 填充模式建议：`OAEP`
- 密钥格式：PEM

用途：

- 仅用于加密 AES 会话密钥
- 不直接加密大包体 JSON

### 6.2 AES 方案

建议：

- `AES-256-CBC` 或 `AES-256-GCM`

建议优先级：

- 如果当前 PHP / 前端依赖兼容良好，优先 `AES-256-GCM`
- 如果需要兼顾实现稳定性与现有库接入复杂度，可先落地 `AES-256-CBC`

说明：

- `GCM` 更现代，带认证标签
- `CBC` 更容易快速落地，但需要额外做好完整性校验

### 6.3 编码格式

建议统一：

- 二进制密文转 `Base64`
- JSON 结构继续使用标准 JSON

---

## 7. 本项目推荐的实现分层

### 7.1 后端分层设计

建议新增以下模块：

#### 1. 配置层

建议新增：

- `backend/config/api_encrypt.php`

用途：

- 全局开关
- 加密范围
- 排除规则
- 密钥读取配置
- 算法配置

#### 2. 密钥服务层

建议新增：

- `backend/core/security/ApiEncrypt/KeyManager.php`
- `backend/core/security/ApiEncrypt/CryptoService.php`

职责：

- 读取公钥/私钥
- 生成密钥对
- RSA 加解密
- AES 加解密

#### 3. 请求解密中间件

建议新增：

- `backend/app/middleware/DecryptApiRequestMiddleware.php`

职责：

- 判断当前请求是否需要解密
- 解密请求体
- 将解密后的 JSON 数据重新注入 Request
- 解密失败时统一返回错误响应

#### 4. 响应加密中间件

建议新增：

- `backend/app/middleware/EncryptApiResponseMiddleware.php`

职责：

- 判断当前响应是否需要加密
- 对 `Json::success / Json::fail` 的响应体进行加密包装
- 排除文件流、SSE、下载等响应类型

#### 5. 注解 / Attribute

建议新增：

- `backend/core/attribute/EncryptResponse.php`
- `backend/core/attribute/SkipApiEncrypt.php`

职责：

- 部分加密模式下，用于标记哪些接口需要加密
- 某些接口在全局加密时仍需排除

### 7.2 前端分层设计

#### Admin 端

接入点：

- `frontend/admin/src/utils/http/index.ts`

建议新增：

- `frontend/admin/src/utils/security/api-encrypt.ts`

职责：

- 获取公钥
- 生成 AES Key
- 请求加密
- 响应解密
- 根据配置判断是否对当前请求启用加密

#### Web 端

接入点：

- `frontend/web/app/utils/request.ts`

建议新增：

- `frontend/web/app/utils/security/api-encrypt.ts`

职责同上。

#### 共通原则

- 不直接把加密逻辑散落在业务页面
- 统一在请求封装层处理
- 页面和业务 API 文件无感知

---

## 8. 配置设计

### 8.1 后端全局配置文件

建议新增：

`backend/config/api_encrypt.php`

建议结构：

```php
return [
    'enabled' => env('API_ENCRYPT_ENABLED', false),
    'scope' => env('API_ENCRYPT_SCOPE', 'off'), // off | partial | all
    'algorithm' => env('API_ENCRYPT_ALGORITHM', 'rsa-aes'),
    'rsa_public_key_path' => env('API_ENCRYPT_RSA_PUBLIC_KEY_PATH', base_path('runtime/keys/api_encrypt_public.pem')),
    'rsa_private_key_path' => env('API_ENCRYPT_RSA_PRIVATE_KEY_PATH', base_path('runtime/keys/api_encrypt_private.pem')),
    'aes_mode' => env('API_ENCRYPT_AES_MODE', 'AES-256-CBC'),
    'exclude_paths' => [
        '/auth/public-key',
        '/auth/refresh',
        '/upload',
        '/swagger',
    ],
];
```

### 8.2 环境变量设计

建议新增：

```env
API_ENCRYPT_ENABLED=false
API_ENCRYPT_SCOPE=off
API_ENCRYPT_ALGORITHM=rsa-aes
API_ENCRYPT_AES_MODE=AES-256-CBC
API_ENCRYPT_RSA_PUBLIC_KEY_PATH=runtime/keys/api_encrypt_public.pem
API_ENCRYPT_RSA_PRIVATE_KEY_PATH=runtime/keys/api_encrypt_private.pem
```

### 8.3 动态配置设计

如果后续要做成你截图里的后台配置页，建议将以下配置支持数据库存储：

- 是否启用接口加密
- 加密范围：`partial / all`
- 当前密钥版本号
- RSA 公钥展示
- RSA 私钥只允许后端存储，不在前端展示原文

说明：

- 如果需要“重新生成密钥”，由后端管理命令或管理接口生成
- 页面只触发生成动作，不直接在浏览器生成私钥

---

## 9. 加密范围设计

### 9.1 模式一：关闭

- 所有接口明文传输
- 保持当前项目行为

### 9.2 模式二：部分加密

只加密满足以下条件的接口：

- 控制器方法标记了 `#[EncryptResponse]`
- 或者请求经过明确的加密白名单匹配

适用场景：

- 登录
- 用户资料
- 支付前置接口
- 涉及敏感个人信息的查询与更新

### 9.3 模式三：全局加密

默认所有 JSON API 都加密，以下接口默认排除：

- 公钥获取接口
- 登录前预检接口
- Token 刷新
- 文件上传
- 文件下载
- SSE
- Swagger/OpenAPI 文档接口
- 第三方回调

---

## 10. 必须排除的接口类型

### 10.1 公钥获取接口

需要提供一个**明文可访问**的公钥接口，例如：

- `GET /system/security/api-encrypt/public-key`

返回：

- `key_version`
- `public_key`
- `enabled`
- `scope`

该接口必须明文，否则前端无法开始第一次加密通信。

### 10.2 Token 刷新接口

建议第一阶段排除：

- `/auth/refresh`

原因：

- Token 过期后的刷新链路要尽量简单可靠
- 避免与解密失败 / Token 失效形成耦合死循环

### 10.3 文件上传接口

如：

- `multipart/form-data`

原因：

- 上传流不适合直接套 JSON 密文结构
- 第一阶段先排除

### 10.4 文件下载 / Blob / 导出接口

原因：

- Admin 和 Web 当前请求封装对 `blob` 有专门处理
- 这类返回体不是标准 JSON，不应进入统一加密中间件

### 10.5 SSE / 流式接口

原因：

- SSE 是持续输出，不适合标准 JSON 包装加密

### 10.6 Swagger / OpenAPI 接口

原因：

- 文档接口要便于调试、对接和生成 SDK

### 10.7 第三方回调接口

原因：

- 第三方平台无法适配你本项目自定义加密协议

---

## 11. 前端接入设计

### 11.1 Admin 端接入点

目标文件：

- `frontend/admin/src/utils/http/index.ts`

建议改造点：

#### 请求前

- 判断当前接口是否启用加密
- 若启用：
  - 获取缓存公钥
  - 生成 AES Key / IV
  - 加密请求体
  - 用 RSA 公钥加密 AES Key
  - 将请求体替换为密文协议
  - 标记请求头，例如：
    - `X-Api-Encrypt: 1`
    - `X-Api-Encrypt-Version: v1`

#### 响应后

- 判断响应体是否为加密协议
- 若是：
  - 使用本次请求缓存的 AES Key 解密响应
  - 还原为 `code / msg / data`
  - 再进入现有业务处理链

### 11.2 Web 端接入点

目标文件：

- `frontend/web/app/utils/request.ts`

改造逻辑与 Admin 一致。

### 11.3 公钥缓存策略

建议：

- 启动后首次调用公钥接口并缓存
- 缓存内容包含：
  - `key_version`
  - `public_key`
  - `expire_at`（可选）

当出现以下情况时刷新公钥：

- 服务端返回“密钥版本不匹配”
- 公钥缓存过期
- 管理员手动重新生成密钥

---

## 12. 后端接入设计

### 12.1 请求解密中间件

职责：

- 识别密文协议
- 验证请求头与请求体格式
- RSA 解出 AES Key
- AES 解出业务 JSON
- 写回 `$request` 可读取结构
- 校验时间戳 / nonce（防重放，第二阶段可增强）

失败返回建议：

```json
{
  "code": 400,
  "msg": "请求解密失败",
  "data": null
}
```

### 12.2 响应加密中间件

职责：

- 仅拦截 JSON 响应
- 判断当前接口是否需加密
- 读取原始响应体
- 使用当前请求上下文里的 AES Key 对响应整体 JSON 加密
- 替换成密文结构返回

### 12.3 中间件挂载建议

当前项目全局中间件在：

- `backend/config/middleware.php`

建议：

- 先作为**主项目全局中间件**挂载
- 中间件内部再根据：
  - 配置开关
  - 路由前缀
  - 排除名单
  - Attribute
  做是否启用的判断

推荐顺序：

1. 跨域 / 语言中间件
2. 请求解密中间件
3. 业务鉴权 / Token 验证中间件
4. 控制器处理
5. 响应加密中间件

原因：

- 鉴权前应拿到解密后的真实请求参数
- 响应加密应放在业务执行后

### 12.4 Attribute 风格保持一致

当前项目已大量使用 PHP Attribute，例如：

- `#[AllowAnonymous]`
- OpenAPI `#[OA\Get] / #[OA\Post]`

因此接口加密标记也建议采用 Attribute 风格，而不是单独再引入一套注释体系。

建议：

- `#[EncryptResponse]`
- `#[SkipApiEncrypt]`

---

## 13. 与现有返回结构的兼容策略

### 13.1 明文模式

仍返回：

```json
{
  "code": 0,
  "msg": "成功",
  "data": {}
}
```

### 13.2 密文模式

传输层返回：

```json
{
  "encrypted": true,
  "algorithm": "rsa-aes",
  "key_version": "v1",
  "data": "..."
}
```

前端解密后，还原为：

```json
{
  "code": 0,
  "msg": "成功",
  "data": {}
}
```

这样可以最大程度复用当前：

- Admin 响应拦截器
- Web 请求封装错误处理
- 页面业务逻辑

---

## 14. 密钥管理设计

### 14.1 密钥存储原则

- **公钥**：可向前端公开
- **私钥**：仅允许服务端读取
- **私钥绝不进入前端页面、接口返回、构建产物**

### 14.2 密钥存储位置建议

建议文件存储：

- `runtime/keys/api_encrypt_public.pem`
- `runtime/keys/api_encrypt_private.pem`

也可后续支持：

- 数据库存储公钥元信息
- 私钥文件仅存磁盘
- 或接入云 KMS（长期方案）

### 14.3 密钥生成方式

建议新增后端命令，例如：

- `php webman api-encrypt:generate-keypair`

职责：

- 生成 RSA 密钥对
- 写入目标路径
- 记录 `key_version`

### 14.4 密钥轮换设计

建议第二阶段支持：

- 当前生效版本 `v1`
- 待切换版本 `v2`
- 前端获取公钥时拿到当前版本
- 服务端解密时可兼容多个版本一段时间

---

## 15. 安全增强建议

### 15.1 时间戳校验

请求带：

- `timestamp`

后端校验：

- 请求时间与服务器时间差不得超过 5 分钟

防止离线重放攻击。

### 15.2 nonce 去重

请求带：

- `nonce`

后端使用 Redis 记录一段时间内已用 nonce：

- 防止短时间重复提交同一密文包

### 15.3 签名校验（可选二阶段）

如果后续安全要求更高，可加：

- 对密文包进行签名
- 服务端验签

但第一阶段不建议同时引入过多复杂度。

### 15.4 敏感日志脱敏

启用接口加密后，后端日志中不能直接打印：

- 原始请求密钥
- AES 明文
- 私钥内容

日志只能打印：

- 路径
- key_version
- nonce
- 时间戳
- 错误码

---

## 16. 性能与运维影响

### 16.1 性能影响

加密会增加：

- 前端加密耗时
- 后端解密 / 加密耗时
- 大列表响应的 CPU 消耗

建议：

- 第一阶段仅在敏感接口上验证性能
- 对大列表、报表、导出接口默认排除

### 16.2 调试复杂度

启用后：

- 浏览器 Network 面板看到的是密文
- 抓包看到的也是密文
- 后端日志不能打印明文

需要增加：

- 开发环境关闭开关
- 测试环境单独验证
- 日志打印加密链路状态而不是明文内容

### 16.3 故障排查

建议新增错误码：

- `API_ENCRYPT_INVALID_PAYLOAD`
- `API_ENCRYPT_DECRYPT_FAILED`
- `API_ENCRYPT_KEY_VERSION_INVALID`
- `API_ENCRYPT_TIMESTAMP_EXPIRED`
- `API_ENCRYPT_NONCE_REPLAY`

---

## 17. 与本项目现有模块的兼容策略

### 17.1 Admin 端

兼容点：

- 当前 Axios 响应拦截器依赖 `code / msg / data`
- 解密必须发生在这套业务判断之前

### 17.2 Web 端

兼容点：

- 当前 `request.ts` 里有 401 刷新 Token 逻辑
- 解密必须在业务 code 判断之前完成
- `showErrorMessage: false` 等语义必须保持不变

### 17.3 插件系统

兼容点：

- 插件接口默认也应继承主项目加密能力
- 插件中如有上传/下载/SSE，需要支持排除

### 17.4 Swagger / OpenAPI

建议保持明文访问，不进入统一加密链路。

---

## 18. 管理端配置页面建议

如果后续做成你截图里的配置页面，建议字段如下：

### 18.1 基础开关

- 接口加密：开 / 关
- 加密范围：
  - 部分加密
  - 全局加密

### 18.2 密钥信息

- 当前密钥版本
- RSA 公钥（可复制）
- RSA 私钥：
  - 不直接展示完整明文
  - 仅支持“已配置 / 未配置”状态展示
  - 仅服务端生成和存储

### 18.3 操作项

- 重新生成密钥
- 导出公钥
- 同步前端缓存失效标记

### 18.4 排除规则

- 路径排除列表
- 控制器/模块排除列表
- 文件上传/下载排除开关

### 18.5 安全参数

- 请求时间窗口
- nonce 有效期
- 是否启用重放校验

---

## 19. 分阶段实施计划

### 第一阶段：最小可用方案

目标：先跑通主链路。

内容：

- 新增全局配置 `api_encrypt.php`
- 新增 RSA 密钥生成命令
- 新增公钥获取接口
- 后端新增：
  - 请求解密中间件
  - 响应加密中间件
- Web 前端接入请求/响应加解密
- 仅支持：
  - JSON 接口
  - 部分加密模式
- 排除：
  - 登录刷新
  - 上传下载
  - SSE
  - Swagger

### 第二阶段：全局加密方案

内容：

- 支持 `scope=all`
- 支持路径排除
- 支持 `#[SkipApiEncrypt]`
- 支持 Admin 端统一接入

### 第三阶段：增强安全与运维能力

内容：

- 支持 nonce 防重放
- 支持时间戳过期校验
- 支持密钥轮换 / 多版本兼容
- 支持后台可视化配置
- 支持链路日志和告警

---

## 20. 推荐实施顺序

建议按以下顺序推进：

1. **先强制生产 HTTPS**
   - 不先做 HTTPS，接口加密的实际收益会打折
2. **实现后端密钥管理与公钥接口**
3. **先接 Web 端请求加密**
   - 范围更可控
4. **再接 Admin 端统一请求封装**
5. **最后接全局开关与管理端配置页面**

---

## 21. 风险清单

### 21.1 风险：前后端版本不一致

可能出现：

- 前端已发密文，后端还未解密
- 后端已返回密文，前端还未解密

规避：

- 必须通过配置开关灰度上线
- 先测试环境联调，再小范围启用

### 21.2 风险：Token 刷新链路被加密耦合破坏

规避：

- 第一阶段将 `/auth/refresh` 排除加密

### 21.3 风险：文件下载/上传被误加密

规避：

- 根据 `Content-Type` / `responseType` 明确排除

### 21.4 风险：前端调试困难

规避：

- 开发环境默认关闭
- 提供调试日志开关，仅打印协议状态，不打印明文

---

## 22. 最终建议结论

对于当前项目，推荐的接口加密方案是：

- **以 HTTPS 为基础**
- **采用 RSA + AES 混合加密**
- **后端私钥、前端公钥**
- **请求与响应统一加密**
- **支持关闭 / 部分加密 / 全局加密**
- **第一阶段只覆盖 JSON 业务接口**
- **排除上传、下载、SSE、刷新 Token、Swagger、第三方回调**
- **前后端统一在请求封装层与中间件层接入**
- **保持现有 `code / msg / data` 业务语义不变**

这是最符合本项目现状、改造成本、后续可维护性和安全收益平衡的一套方案。

---

## 23. 后续开发文档建议

本方案文档确认后，建议继续拆成 4 份执行文档：

1. **后端实现设计**
   - 中间件、配置、命令、公钥接口、Attribute
2. **Web 前端接入设计**
   - `frontend/web/app/utils/request.ts` 改造方案
3. **Admin 前端接入设计**
   - `frontend/admin/src/utils/http/index.ts` 改造方案
4. **联调与灰度上线清单**
   - 测试用例、排除清单、回滚方案