跳到主要内容

密钥服务

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本技术文档围绕密钥服务展开，覆盖设备密钥管理机制（生成、存储、轮换、销毁）、加密解密实现（对称加密、签名与验签、哈希验证）、密钥分发与同步（下发、版本控制、一致性与冲突处理）、安全策略（隔离、访问控制、审计与合规）、以及监控运维（使用统计、安全告警、合规报告、备份恢复）。同时提供密钥API接口文档与客户端集成指南，帮助开发者与运维人员快速理解与落地。

项目结构​

密钥服务位于任务模块（task）中，采用“接口 + 服务 + 数据对象 + Mapper + DTO + 枚举”的分层组织方式，并通过通用安全工具类提供加密、解密与签名能力。关键目录与文件如下：

  • 通用安全工具：EncryptionUtils（对称加密、解密、签名、MD5）
  • 任务模块密钥管理：TaskSecretKeyServiceImpl（业务逻辑）、TaskSecretKeyMapper（数据访问）、TaskSecretKeyDO（领域对象）
  • 密钥类型枚举：TaskSecretKeyTypeEnum（域名分发、固件、签名）
  • 控制器参数VO：TaskSecretKeyPageReqVO、TaskSecretKeySaveReqVO
  • RPC接口：AppSdkSecurityKeyApi（Feign声明式接口）、AppSdkSecurityKeyApiImpl（实现）
  • DTO：SecretKeyDTO（对外传输对象）
  • API常量：ApiConstants（服务名、前缀、版本）
  • 文档：签名与加解密对接文档、监控中心文档

Mermaid Diagram Code:

graph TB
subgraph "通用安全工具"
EU["EncryptionUtils<br/>对称加密/解密/签名/MD5"]
end
subgraph "任务模块-密钥管理"
SVC["TaskSecretKeyServiceImpl<br/>业务逻辑"]
MAPPER["TaskSecretKeyMapper<br/>数据访问"]
DO["TaskSecretKeyDO<br/>领域对象"]
ENUM["TaskSecretKeyTypeEnum<br/>密钥类型枚举"]
PAGE_VO["TaskSecretKeyPageReqVO"]
SAVE_VO["TaskSecretKeySaveReqVO"]
end
subgraph "RPC接口"
API["AppSdkSecurityKeyApi<br/>Feign接口"]
IMPL["AppSdkSecurityKeyApiImpl<br/>实现"]
DTO["SecretKeyDTO"]
CONST["ApiConstants<br/>服务名/前缀/版本"]
end
EU --> SVC
SVC --> MAPPER
MAPPER --> DO
ENUM --> SVC
PAGE_VO --> SVC
SAVE_VO --> SVC
API --> IMPL
IMPL --> SVC
SVC --> DTO
CONST --> API

图表来源

章节来源

核心组件​

  • 加密工具类 EncryptionUtils：提供 AES/CBC/PKCS5Padding 对称加解密、MD5 签名与验签、时间差校验。
  • 业务服务 TaskSecretKeyServiceImpl：负责密钥的创建、更新、删除、分页查询、按类型+键查询与本地缓存穿透。
  • 数据访问 TaskSecretKeyMapper：基于 MyBatis Plus 的基础 Mapper，提供分页查询。
  • 领域对象 TaskSecretKeyDO：封装密钥类型、键、值（加密存储）、备注、时间差等字段，并提供明文解密方法。
  • 枚举 TaskSecretKeyTypeEnum：密钥类型（域名分发AES、固件AES、域名签名）。
  • 控制器参数 VO：分页与保存请求参数。
  • RPC 接口与实现：AppSdkSecurityKeyApi（Feign）与 AppSdkSecurityKeyApiImpl（实现），提供按 key+type 查询密钥并返回明文。
  • DTO SecretKeyDTO：对外传输对象，包含密钥基本信息与明文值。
  • API 常量 ApiConstants：统一服务名、前缀与版本。

章节来源

架构总览​

密钥服务采用“RPC + 本地缓存 + 数据库”的架构：

  • 外部系统通过 Feign 接口调用密钥服务，按 key+type 获取密钥。
  • 服务端在本地缓存命中后返回，未命中则查询数据库并回填缓存。
  • 密钥值在数据库中加密存储，返回给调用方前进行解密。
  • 加密与签名由通用工具类提供，确保跨模块一致性。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant API as "AppSdkSecurityKeyApiImpl"
participant Svc as "TaskSecretKeyServiceImpl"
participant Cache as "本地缓存"
participant Mapper as "TaskSecretKeyMapper"
participant DB as "数据库"
participant Util as "EncryptionUtils"
Client->>API : GET /task/AppSdkSecurityKey/getSecretKeyByKey
API->>Svc : getSecretKeyByTypeAndKeyOnCahe(type,key)
Svc->>Cache : 读取缓存
alt 命中
Cache-->>Svc : 返回密钥DO
else 未命中
Svc->>Mapper : 查询密钥DO
Mapper-->>Svc : 返回密钥DO
Svc->>Cache : 写入缓存
end
Svc-->>API : 返回密钥DO
API->>Svc : getPlainValue()
Svc->>Util : decrypt(密文, SAVE_KEY)
Util-->>Svc : 明文
Svc-->>API : 明文密钥
API-->>Client : {id,type,key,value,remarks,timeDiff}

图表来源

详细组件分析​

加密与签名组件（EncryptionUtils）​

  • 对称加密：AES/CBC/PKCS5Padding，随机IV（16字节），IV前置拼接并Base64输出；密钥长度支持16/24/32字节。
  • 解密：从Base64解码后分离IV与密文，使用相同密钥与IV完成解密。
  • 签名：MD5签名，输入包含域名、MAC、CPU、时间戳、盐值与SDK版本等字段，严格顺序与拼接。
  • 验签：计算时间差阈值（毫秒），超限直接拒绝；否则重新计算签名并与传入签名比对。
  • MD5：固定使用UTF-8编码，输出小写十六进制串。

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> CheckKey["校验密钥长度<br/>16/24/32字节"]
CheckKey --> GenIV["生成16字节随机IV"]
GenIV --> InitCipher["初始化Cipher(AES/CBC/PKCS5Padding)"]
InitCipher --> Encrypt["执行加密"]
Encrypt --> Combine["IV前置拼接密文"]
Combine --> Base64["Base64编码输出"]
Base64 --> End(["结束"])

图表来源

章节来源

密钥管理服务（TaskSecretKeyServiceImpl）​

  • 创建/更新：对密钥值进行合法性校验（字符集、长度、多字节字符），支持16/24/32字符长度。
  • 查询：支持按主键、分页、按类型+键查询；按类型+键查询支持本地缓存穿透。
  • 删除：校验存在后删除。
  • 明文解密：在返回DTO前调用工具类解密数据库中加密的密钥值，兼容历史未加密数据。

Mermaid Diagram Code:

classDiagram
class TaskSecretKeyServiceImpl {
+createSecretKey(createReqVO)
+updateSecretKey(updateReqVO)
+deleteSecretKey(id)
+getSecretKey(id)
+getSecretKeyPage(pageReqVO)
+getSecretKeyByTypeAndKey(type,key)
+getSecretKeyByTypeAndKeyOnCahe(type,key)
-validValue(req)
}
class TaskSecretKeyMapper {
+selectPage(reqVO)
}
class TaskSecretKeyDO {
+getPlainValue()
}
class EncryptionUtils {
+decrypt(encryptedText, secretKey)
}
TaskSecretKeyServiceImpl --> TaskSecretKeyMapper : "依赖"
TaskSecretKeyServiceImpl --> TaskSecretKeyDO : "操作"
TaskSecretKeyDO --> EncryptionUtils : "解密"

图表来源

章节来源

密钥类型与参数​

  • 密钥类型枚举：域名分发AES、固件AES、域名签名。
  • 分页请求参数：支持按类型、键、值、备注、创建时间区间查询。
  • 保存请求参数：包含主键、类型、键、值、时间差、备注。

章节来源

RPC接口与客户端集成​

  • 接口定义：Feign 接口，路径前缀由 ApiConstants 提供，版本化管理。
  • 实现：按 key+type 查询密钥，返回 SecretKeyDTO；在返回前解密密钥值。
  • 客户端集成：在调用方工程引入 Feign 接口依赖，配置服务名与网关路由，即可通过接口获取密钥。

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant Feign as "AppSdkSecurityKeyApi"
participant Impl as "AppSdkSecurityKeyApiImpl"
participant Svc as "TaskSecretKeyServiceImpl"
Caller->>Feign : getSecretKeyByKeyAndType(key,type)
Feign->>Impl : 路由到实现
Impl->>Svc : getSecretKeyByTypeAndKeyOnCahe
Svc-->>Impl : 密钥DO
Impl->>Svc : getPlainValue()
Svc-->>Impl : 明文密钥
Impl-->>Caller : {id,type,key,value,remarks,timeDiff}

图表来源

章节来源

依赖分析​

  • 低耦合高内聚：业务服务仅依赖Mapper与工具类，领域对象封装解密逻辑，避免上层重复实现。
  • 本地缓存：按 key=type&&key 缓存，减少数据库压力，提升查询性能。
  • 数据一致性：分页查询与条件过滤由Mapper统一实现，避免业务侧分散逻辑。
  • 版本化与可扩展：密钥类型枚举支持扩展，接口前缀与版本集中管理。

Mermaid Diagram Code:

graph LR
EU["EncryptionUtils"] --> SVC["TaskSecretKeyServiceImpl"]
SVC --> MAPPER["TaskSecretKeyMapper"]
MAPPER --> DO["TaskSecretKeyDO"]
ENUM["TaskSecretKeyTypeEnum"] --> SVC
PAGE["TaskSecretKeyPageReqVO"] --> SVC
SAVE["TaskSecretKeySaveReqVO"] --> SVC
API["AppSdkSecurityKeyApi"] --> IMPL["AppSdkSecurityKeyApiImpl"]
IMPL --> SVC
SVC --> DTO["SecretKeyDTO"]
CONST["ApiConstants"] --> API

图表来源

章节来源

性能考虑​

  • 本地缓存命中：按 key+type 查询支持本地缓存，显著降低数据库压力。
  • 分页查询：Mapper 提供条件过滤与分页，避免一次性加载大量数据。
  • 加解密成本：AES/CBC 为轻量级对称加密，建议在高并发场景下结合连接池与异步处理优化。
  • 密钥长度校验：提前校验密钥长度与字符集，减少无效请求带来的开销。

[本节为通用性能建议，无需特定文件引用]

故障排查指南​

  • 密钥解密失败：当数据库中密钥值无法解密时，会记录错误并返回原始值，便于历史数据兼容。请检查密钥长度与保存密钥是否一致。
  • 密钥值非法：保存密钥时会校验字符集、长度与多字节字符，不符合要求将抛出异常。请确保密钥仅包含允许的ASCII字符且长度为16/24/32。
  • RPC调用失败：确认服务名与前缀配置正确，Feign 接口路径与参数一致。
  • 验签失败：检查时间戳与时间差阈值，确保设备时间与服务端时间一致。

章节来源

结论​

密钥服务通过统一的加密工具、严格的密钥校验、本地缓存与RPC接口，实现了设备密钥的安全管理与高效分发。配合签名与验签机制，保障了通信完整性与时效性。建议在生产环境中结合监控与审计，完善密钥轮换与备份恢复策略，确保系统的长期稳定与合规。

[本节为总结性内容，无需特定文件引用]

附录​

密钥API接口文档​

  • 服务名：task-server
  • 前缀：/api/task
  • 版本：1.0.0
  • 接口：GET /task/AppSdkSecurityKey/getSecretKeyByKey
    • 参数：
      • key：密钥标识（字符串）
      • type：密钥类型（整型，0=域名分发，1=固件，2=签名）
    • 返回：CommonResult<SecretKeyDTO>
      • SecretKeyDTO 包含：id、type、key、value（明文）、remarks、timeDiff

章节来源

客户端集成指南​

  • 引入依赖：在调用方工程引入任务模块API依赖，确保Feign接口可用。
  • 配置服务名：与 ApiConstants 中的服务名保持一致。
  • 调用接口：构造 key 与 type 参数，调用 getSecretKeyByKeyAndType 获取密钥。
  • 处理返回：对返回的 SecretKeyDTO 进行业务处理，注意不要将密钥明文落库或日志。

章节来源

密钥分发与同步机制​

  • 下发流程：客户端通过RPC接口按 key+type 获取密钥，服务端本地缓存命中优先，未命中查询数据库并回填缓存。
  • 版本控制：密钥类型枚举支持扩展，不同SDK版本可配置不同密钥。
  • 一致性保证：本地缓存同步数据库，避免脏读；分页查询与条件过滤确保查询一致性。
  • 冲突处理：密钥值保存时进行严格校验，非法值直接拒绝，避免冲突与错误传播。

章节来源

安全策略​

  • 密钥隔离：密钥值在数据库中加密存储，返回给调用方前才解密。
  • 访问控制：通过Feign接口与服务名控制访问范围。
  • 审计日志：结合监控中心与API日志模块，记录接口调用与异常信息。
  • 合规性检查：密钥长度与字符集严格校验，符合对称加密与签名规范。

章节来源

监控与运维​

  • 监控中心：提供Redis、MySQL、Kafka等中间件监控，便于观察密钥服务运行状态。
  • API日志：支持查询访问日志、异常日志与性能分析，辅助定位问题。
  • 合规报告：结合审计日志与监控指标，形成合规性报告材料。

章节来源

对接文档要点​

  • 仅域名分发场景对data进行加密，返回体中的data需解密，msg与code保持不变。
  • 测试环境提供SDK版本、签名盐值、加密密钥与时间差阈值配置，便于联调。

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答