# GKMS

**Repository Path**: DaLangYangFan_admin/gkms

## Basic Information

- **Project Name**: GKMS
- **Description**: Golang写的KMS简称GKMS。一个使用Go语言开发的高性能KMS（密钥管理系统），支持多种主流加密算法，提供完整的密钥生命周期管理功能。系统采用模块化设计，支持多种存储后端，具有良好的扩展性和高性能特性。支持无线多节点集群部署，机器够多十万并发百万不是梦！
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/xcmrfc-thanos/gkms
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KMS (Key Management System) - 高性能密钥管理系统

## 项目简介

本项目是一个使用Go语言开发的高性能KMS（密钥管理系统），支持多种主流加密算法，提供完整的密钥生命周期管理功能。系统采用模块化设计，支持多种存储后端，具有良好的扩展性和高性能特性。

## 功能特性

### 🔐 支持的加密算法
- **对称加密**：AES-256-GCM、**SM4**（国密，支持CBC和ECB模式）
- **非对称加密**：RSA-2048/3072/4096、**SM2**（国密）
- **数字签名**：RSA-PSS、SM2数字签名、HMAC、ECDSA、Ed25519、**SM3**（国密哈希签名）
- **哈希算法**：**SM3**（国密，不依赖密钥，支持独立计算与验证）

### 💾 存储后端
- **SQLite**：轻量级关系数据库存储
- **Binary**：自定义二进制文件存储（AES-GCM加密）
- **Memory**：内存存储（适用于测试和临时使用）
- **Hybrid**：混合存储（SQLite元数据+自定义二进制+LRU缓存）

### 🚀 核心功能
- 密钥生成（对称/非对称/签名）
- 密钥存储和检索
- 数据加密/解密
- 数字签名/验签
- 密钥生命周期管理
- 过期密钥自动清理
- 密钥搜索和标签管理
- RESTful API接口
- LRU缓存优化

### 📊 系统特性
- 高性能并发处理
- 完整的日志系统
- 灵活的配置管理
- 健康检查和监控
- CORS支持
- 错误恢复机制
- 智能缓存机制
- 混合存储架构

## 项目结构

```
kms/
├── main.go                    # 程序入口
├── go.mod                     # Go模块定义
├── config.json               # 配置文件（运行时生成）
├── internal/
│   ├── api/                  # HTTP API层
│   │   ├── routes.go         # 路由配置
│   │   ├── KeyController.go  # 密钥管理控制器
│   │   ├── CryptoController.go # 加密解密控制器
│   │   └── SystemController.go # 系统信息控制器
│   ├── config/               # 配置管理
│   │   └── config.go
│   ├── cache/                # 缓存机制
│   │   └── lru.go           # LRU缓存实现
│   ├── crypto/               # 加密算法实现
│   │   ├── interface.go      # 加密接口定义
│   │   ├── factory.go        # 加密工厂
│   │   ├── aes.go           # AES实现
│   │   ├── sm4.go           # SM4实现
│   │   ├── rsa.go           # RSA实现
│   │   ├── sm2.go           # SM2实现（国密）
│   │   ├── sm3.go           # SM3实现（国密哈希/签名）
│   │   ├── hmac.go          # HMAC实现
│   │   ├── ecdsa.go         # ECDSA实现
│   │   └── ed25519.go       # Ed25519实现
│   ├── logger/               # 日志系统
│   │   └── logger.go
│   ├── service/              # 业务逻辑层
│   │   ├── KeyService.go     # 密钥管理服务
│   │   └── CryptoService.go  # 加密解密服务
│   └── storage/              # 存储层
│       ├── interface.go      # 存储接口
│       ├── factory.go        # 存储工厂
│       ├── sqlite.go         # SQLite实现
│       ├── binary.go         # 二进制文件实现
│
│       ├── hybrid.go         # 混合存储实现
│       └── hybrid_adapter.go # 混合存储适配器
└── logs/                     # 日志文件目录（运行时生成）
```

## 安装和使用

### 环境要求
- Go 1.21+
- Windows/Linux/macOS

### 安装依赖

```bash
go mod tidy
```

### 配置文件

首次运行会自动生成 `config.json` 配置文件：

```json
{
  "port": 8080,
  "storage_type": "memory",
  "storage_path": "./data",
  "encrypt_key": "",
  "logger": {
    "level": "INFO",
    "output": "console",
    "file_path": "logs/kms.log",
    "max_size": 100,
    "max_backups": 5
  }
}
```

### 启动服务

```bash
go run main.go
```

服务启动后，访问 `http://localhost:8080/api/v1/health` 检查服务状态。

### 启动模式（参考 Redis/Nacos）

- **`run_mode`**：`"single"`（默认）单机 | `"cluster"` 集群。
  - **single**：单机模式，本进程处理所有请求，**不启网关**。单机可不配 gateway；若需 **IP 白名单**，可只配 `gateway.ip_whitelist`，单机也会生效（与集群共用该配置）。
  - **cluster**：集群模式，启用网关（按 key_id 路由、节点列表、注册 API）。**集群不事先指定“哪个是网关”**：谁被客户端连接谁就承担网关角色；每个节点的 `gateway.node_url` 填**本节点自己的**对外地址（用于判断请求是否本机处理）。

**集群模式配置**（仅 `run_mode: "cluster"` 时生效；单机可忽略）：

- `node_id`：本节点 ID，如 `0x0`、`0x1`，用于生成带前缀的 `key_id` 及路由。
- `gateway`：网关子配置（单机可不配；单机若只配 `ip_whitelist` 也会生效）
  - `ip_whitelist`：IP 白名单（CIDR 或单 IP），空则不过滤；**单机与集群共用**，都放在 gateway 内。
  - `nodes_file`：节点列表持久化文件路径，如 `./data/gateway_nodes.json`。
  - **`node_url`**：**本节点自己的**对外地址（如 `http://本机IP:端口`），用于判断“请求是否该本机处理”；每个节点都填自己。
  - **`gateway_url`**：**网关入口地址**（仅后端节点配置）。填网关的 URL 后，启动时会向该地址 **POST 注册本节点**（服务注册）；不填则需运维在网关的 `nodes_file` 里写死或手动调用注册 API。
  - `register_self`：**默认 true**（启动时把本节点写入节点列表）。不需要 KMS 功能（纯代理、本机不存密钥）时设 `false`。
  - **`pick_node_algorithm`**：创建密钥时选节点算法（见下）。
- **谁才是网关 / 服务注册**：不事先指定“哪个是网关”。若部署为**一个对外服务 + 多个后端**，则客户端只连该对外服务（即网关）；后端节点在配置里填 **`gateway_url` = 网关地址**，启动时自动向网关注册，无需手写 nodes_file。

**创建密钥选节点算法**（`gateway.pick_node_algorithm`）：**仅在没有 key_id 的创建密钥时生效**；之后所有带 key_id 的请求（解密、加密、签名等）**一律按 key_id 路由**到存钥节点，否则会解密错误。

| 值 | 含义 |
|----|------|
| **random**（默认） | 在已启用节点中**随机**选一个，负载较均匀。 |
| **round_robin** | **轮询**：按请求顺序依次选节点 0、1、2… 循环，各节点请求数尽量均分。 |
| **local_first** | **优先本节点**：若本节点在列表中且启用则选本节点，否则退化为 random；适合希望尽量在本机建密钥的场景。 |
| **ip_hash** | **按客户端 IP 哈希**：对 ClientIP 做哈希后对节点数取模，同一 IP 的创建密钥请求固定到同一节点；适合按来源 IP 做会话/缓存亲和。 |

**启用集群步骤**：

1. `config.json` 中设置 `"run_mode": "cluster"`，并在 `gateway` 块中配置 `node_id`、`node_url` 等。
2. 将 `gateway_nodes.example.json` 复制为 `gateway_nodes.json` 并按实际节点修改。
3. 启动各节点；客户端连到任意 cluster 节点即为网关入口，按 key_id 路由。

**网关 API**（仅 `run_mode=cluster` 时注册）：

- `POST /api/v1/gateway/nodes`：注册/更新节点。
- `GET /api/v1/gateway/nodes`：获取节点列表。
- `POST /api/v1/gateway/reload`：从 `nodes_file` 重新加载节点配置。

## API 文档

### 系统信息

#### 健康检查
```http
GET /api/v1/health
```
集群模式下 `data` 中会包含 `run_mode`、`node_id`、`node_url`、`pick_node_algorithm`；与 `/info` 均为本地处理，不转发。

#### 系统信息
```http
GET /api/v1/info
```
集群模式下 `data` 中会包含 `run_mode`、`node_id`、`node_url`、`pick_node_algorithm`。

#### 算法信息
```http
GET /api/v1/algorithms
```

#### 存储统计
```http
GET /api/v1/storage/stats
```

### 密钥管理

#### 生成对称密钥
```http
POST /api/v1/keys/symmetric
Content-Type: application/json

{
  "name": "my-aes-key",
  "algorithm": "AES",
  "key_size": 256,
  "description": "测试AES密钥",
  "tags": ["test", "aes"],
  "expired_at": "2024-12-31T23:59:59Z"
}
```

#### 生成非对称密钥
```http
POST /api/v1/keys/asymmetric
Content-Type: application/json

{
  "name": "my-rsa-key",
  "algorithm": "RSA",
  "key_size": 2048,
  "description": "测试RSA密钥",
  "tags": ["test", "rsa"]
}
```

#### 生成签名密钥
```http
POST /api/v1/keys/signature
Content-Type: application/json

{
  "name": "my-hmac-key",
  "algorithm": "HMAC",
  "key_size": 256,
  "hash_algo": "SHA256",
  "description": "测试HMAC密钥",
  "tags": ["test", "hmac"]
}
```

```http
POST /api/v1/keys/signature
Content-Type: application/json

{
  "name": "my-ecdsa-key",
  "algorithm": "ECDSA",
  "curve": "P-256",
  "hash_algo": "SHA256",
  "description": "测试ECDSA密钥",
  "tags": ["test", "ecdsa"]
}
```

```http
POST /api/v1/keys/signature
Content-Type: application/json

{
  "name": "my-ed25519-key",
  "algorithm": "Ed25519",
  "description": "测试Ed25519密钥",
  "tags": ["test", "ed25519"]
}
```

#### 获取支持的算法
```http
GET /api/v1/keys/algorithms/symmetric
GET /api/v1/keys/algorithms/asymmetric
GET /api/v1/keys/algorithms/signature
```

#### 获取密钥
```http
GET /api/v1/keys/{id}
GET /api/v1/keys/name/{name}
```

#### 列出密钥
```http
GET /api/v1/keys?offset=0&limit=20
```

#### 搜索密钥
```http
GET /api/v1/keys/search?q=test&algorithm=AES&key_type=symmetric
```

#### 根据标签获取密钥
```http
GET /api/v1/keys/tag/{tag}
```

#### 更新密钥
```http
PUT /api/v1/keys/{id}
Content-Type: application/json

{
  "description": "更新后的描述",
  "tags": ["updated", "test"],
  "expired_at": "2025-12-31T23:59:59Z"
}
```

#### 删除密钥
```http
DELETE /api/v1/keys/{id}
```

#### 清理过期密钥
```http
DELETE /api/v1/keys/expired
```

### 加密解密

#### 数据加密
```http
POST /api/v1/crypto/encrypt
Content-Type: application/json

{
  "key_id": "key-uuid",
  "plaintext": "Hello, World!",
  "output_type": "hex"
}
```

#### 数据解密
```http
POST /api/v1/crypto/decrypt
Content-Type: application/json

{
  "key_id": "key-uuid",
  "ciphertext": "encrypted-data-in-hex",
  "input_type": "hex"
}
```

#### 数字签名
```http
POST /api/v1/crypto/sign
Content-Type: application/json

{
  "key_id": "key-uuid",
  "data": "data-to-sign",
  "output_type": "hex"
}
```

#### 验证签名
```http
POST /api/v1/crypto/verify
Content-Type: application/json

{
  "key_id": "key-uuid",
  "data": "original-data",
  "signature": "signature-in-hex",
  "input_type": "hex"
}
```

#### 哈希计算（国密 SM3，不依赖密钥）
```http
POST /api/v1/crypto/hash
Content-Type: application/json

{
  "algorithm": "SM3",
  "data": "待哈希数据或 hex/base64",
  "input_type": "text",
  "output_type": "hex"
}
```

#### 哈希验证（国密 SM3）
```http
POST /api/v1/crypto/verify-hash
Content-Type: application/json

{
  "algorithm": "SM3",
  "data": "原始数据",
  "expected_hash": "期望的哈希值(hex或base64)",
  "input_type": "text"
}
```

## 配置说明

### 存储类型
- `sqlite`: SQLite数据库存储（默认）
- `binary`: 自定义二进制文件存储
- `hybrid`: 混合存储，结合SQLite元数据、自定义二进制存储和LRU缓存

### 混合存储配置（`hybrid_storage`）
- `db_path`: SQLite数据库路径（元数据存储）
- `data_path`: 二进制数据存储路径（密钥数据）
- `cache_size`: LRU缓存大小（默认5000）
- `cache_ttl`: LRU缓存TTL，单位分钟（默认60）
- `cache_enabled`: 是否启用LRU缓存（默认true）
- `memory_cache_enabled`: 是否启用全量内存缓存，启动时加载所有密钥到内存（默认true，性能优化）

### 日志配置
- `level`: 日志级别（DEBUG, INFO, WARN, ERROR, FATAL）
- `output`: 输出方式（console, file, both）
- `file_path`: 日志文件路径
- `max_size`: 单个日志文件最大大小（MB）
- `max_backups`: 最大备份文件数

## 安全特性

1. **存储加密**: 二进制存储使用AES-GCM加密
2. **密钥隔离**: 每个密钥独立存储和管理
3. **访问控制**: 基于ID的密钥访问控制
4. **审计日志**: 完整的操作日志记录
5. **过期管理**: 自动清理过期密钥

## 性能特性

1. **并发安全**: 支持高并发访问
2. **内存优化**: 高效的内存使用
3. **缓存机制**: 
   - **LRU缓存**: 智能LRU缓存提升性能（`cache_enabled`）
   - **全量内存缓存**: 启动时加载所有密钥到内存，大幅提升读取性能（`memory_cache_enabled`，默认启用）
4. **连接池**: 数据库连接池管理
5. **异步处理**: 非阻塞操作处理
6. **预编译SQL**: 常用查询使用预编译语句
7. **批量更新**: last_used_at 批量更新机制

## 开发和扩展

### 添加新的加密算法
1. 在 `internal/crypto/` 目录下实现新算法
2. 实现 `SymmetricCrypto` 或 `AsymmetricCrypto` 接口
3. 在 `factory.go` 中注册新算法

### 添加新的存储后端
1. 在 `internal/storage/` 目录下实现新存储
2. 实现 `Storage` 接口
3. 在 `factory.go` 中注册新存储类型

## 故障排除

### 常见问题

1. **端口被占用**
   - 修改 `config.json` 中的 `port` 配置

2. **存储初始化失败**
   - 检查存储路径权限
   - 确保磁盘空间充足

3. **密钥生成失败**
   - 检查算法名称是否正确
   - 验证密钥长度是否支持

### 日志查看

```bash
# 查看实时日志
tail -f logs/kms.log

# 查看错误日志
grep ERROR logs/kms.log
```

## 许可证

本项目采用 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进本项目。

---

## 历史需求记录

### 【本次功能】网关开关与配置
- 启动模式 `run_mode`：single（默认单机）/ cluster（集群网关）；`node_id` 与 `gateway` 配置块（cluster 时生效）。
- 提供完整 `config.json` 示例及节点列表示例 `gateway_nodes.example.json`。
- 代码：`internal/config/config.go` 中 `IsGatewayMode()` 仅根据 `run_mode=cluster` 判断；`main.go` 据此注册网关中间件与网关 API。

### 【参考文件】
- `config.json` - 增加 run_mode、node_id、gateway 示例
- `gateway_nodes.example.json` - 节点列表示例（可复制为 data/gateway_nodes.json）
- `internal/config/config.go` - GatewayConfig、Config 中 run_mode/node_id/gateway 字段
- `internal/gateway/gateway.go` - 网关路由、IP 白名单、节点注册与 Reload
- `main.go`、`internal/api/routes.go` - 网关初始化与路由注册

### 【差距总结】
无；现以 run_mode 为唯一开关（已移除 gateway_enabled）。

### 【2025-02-05 错误处理与 Context 优化】
- **业务错误类型定义**：新增 `internal/errors/errors.go`，定义 ErrKeyNotFound、ErrKeyExpired、ErrKeyInactive、ErrInvalidKeySize、ErrInvalidFormat 等业务错误类型，便于错误分类与处理。
- **统一错误处理**：Controller 层新增 `HandleServiceError` 函数，根据 Service 层错误类型自动返回合适的 HTTP 状态码（400/404/500），替代手动判断。
- **Context 传递**：为 Service 层关键方法（Encrypt、Decrypt、Sign、Verify、Hash、VerifyHash、GetKey、GenerateSymmetricKey 等）增加 `context.Context` 参数，支持超时控制、取消操作和链路追踪。
- **错误包装**：Service 层使用 `WrapError` 包装错误，保留原始错误信息，便于调试与日志记录。

### 【参考文件】
- `internal/errors/errors.go` - 新增业务错误类型定义
- `internal/api/response.go` - 新增 HandleServiceError 函数
- `internal/service/CryptoService.go` - 方法签名增加 context.Context，使用错误类型
- `internal/service/KeyService.go` - 方法签名增加 context.Context，使用错误类型
- `internal/api/CryptoController.go` - 调用 Service 时传递 context，使用 HandleServiceError
- `internal/api/KeyController.go` - 调用 Service 时传递 context，使用 HandleServiceError

### 【2025-02-05 国密 SM2/SM3/SM4 优化】
- **SM3 独立哈希 API**：新增 `POST /api/v1/crypto/hash`（计算 SM3 哈希）、`POST /api/v1/crypto/verify-hash`（验证 SM3 哈希），不依赖密钥，支持 input_type/output_type（hex、base64、text）。
- **系统算法信息**：`GET /api/v1/algorithms` 响应增加 `hash_algorithms` 字段（含 SM3），与 symmetric/asymmetric/signature 并列，便于前端展示国密算法能力。
- **readme**：在“支持的加密算法”中明确标注国密 SM2/SM3/SM4，并补充哈希计算/哈希验证接口文档。

### 【参考文件】
- `internal/service/CryptoService.go` - 新增 HashRequest/HashResponse、VerifyHashRequest/VerifyHashResponse 及 Hash()、VerifyHash() 方法
- `internal/api/CryptoController.go` - 新增 Hash、VerifyHash 请求/响应结构及 Hash、VerifyHash 处理器
- `internal/api/routes.go` - 新增 POST /crypto/hash、POST /crypto/verify-hash 路由
- `internal/api/SystemController.go` - AlgorithmInfoResponse 增加 HashAlgorithms，GetAlgorithmInfo 填充 hash_algorithms
- `readme.md` - 国密算法说明与哈希 API 文档

### 【2025-02-05 代码与设计优化】
- **路由顺序修复**：将 `/keys/search`、`/keys/name/:name`、`/keys/tag/:tag`、`/keys/algorithms/*` 等具体路径注册在 `GET /:id` 之前，避免被误匹配导致搜索、按名称/标签查询不可用。
- **加密/签名 input_type 透传**：加密与签名接口支持请求体中的 `input_type`（hex/base64/text），透传到 Service 层解析明文或待签名数据，与解密/验签行为一致。
- **CryptoFactory 单例注入**：在 main 中创建单例 CryptoFactory，通过构造函数注入 KeyService、CryptoService、KeyController、SystemController，便于扩展与测试。
- **统一错误响应与分页常量**：新增 `internal/api/response.go`，提供 `RespondBadRequest`、`RespondNotFound`、`RespondInternalError` 及分页常量 `DefaultListLimit`、`MaxListLimit`；ListKeys 增加 offset≥0 校验与 limit 上限。

### 【参考文件】
- `internal/api/routes.go` - 路由顺序调整、SetupRoutes 增加 cryptoFactory 参数
- `internal/api/CryptoController.go` - 加密/签名/验签 input_type 透传
- `internal/api/KeyController.go` - 使用 response 辅助与分页常量
- `internal/api/response.go` - 新增统一错误响应与分页常量
- `internal/api/SystemController.go` - NewSystemController 增加 factory 参数
- `internal/service/KeyService.go` - NewKeyService 增加 factory 参数
- `internal/service/CryptoService.go` - NewCryptoService 增加 factory 参数
- `main.go` - 创建并注入 CryptoFactory

### 【2024-01-21 SM3哈希算法独立实现】
将SM3算法从HMAC模块中独立出来，实现完整的SM3哈希功能：
- 创建独立的SM3Crypto实现，提供完整的哈希功能
- 添加HashCrypto接口定义，规范哈希算法实现
- 在CryptoFactory中添加CreateHashCrypto方法
- 新增/api/v1/keys/algorithms/hash接口，返回支持的哈希算法
- 从HMAC实现中移除SM3相关代码，保持模块独立性
- 更新签名算法API返回值，SM3同时作为哈希和签名算法，签名算法列表包含HMAC、ECDSA、Ed25519、SM3
- 支持SM3哈希计算、验证、批量处理等功能
- 提供十六进制格式的哈希值输入输出

### 【2024-01-21 加密解密接口格式支持扩展】
完善了KMS系统的加密解密接口，支持多种数据格式：
- 扩展parseInputData和formatOutputData函数支持base64格式
- 修复CryptoController中加密接口的输入输出格式处理逻辑
- 统一加密、解密、签名、验签接口的格式处理方式
- 支持hex、base64、text三种数据格式的输入输出
- 修复之前明文解析失败的问题（"Hello, World!"等文本输入）
- 确保所有加密解密接口能正确处理不同格式的数据转换
- 提升API接口的易用性和兼容性

### 【KMS 集群网关方案文档】
- 网关方案**仅按 key_id 路由**，不依赖用户 ID（uid）。
- 详见 `KMS集群网关方案.md`：key_id 格式（0xN:uuid）、路由规则、网关配置、节点列表、网关 API、IP 白名单与部署扩展建议。

### 【2024-01-21 混合存储和SQLite优化配置】
优化了KMS系统的存储性能和缓存配置：
- 将默认存储类型从sqlite改为hybrid混合存储
- 增大LRU缓存大小从1000提升到5000个密钥
- 缓存TTL从30分钟延长到60分钟
- 应用SQLite性能优化：WAL模式、NORMAL同步、20MB页面缓存、内存临时存储
- 启用256MB内存映射、30秒忙等待超时、最大10个连接
- 新增HybridStorageConfig和SQLiteOptimization配置结构
- 实现NewHybridStorageWithOptimization函数支持优化配置
- 修改main.go支持混合存储配置和SQLite优化参数
- 预期性能提升：4核8G服务器下从200-300 QPS提升到500-800 QPS

### 【2024-01-21 密钥大小单位转换修复】
修复了密钥生成API中密钥大小单位混淆问题：
- 修复密钥生成API中密钥大小单位混淆问题
- 添加convertKeySizeToBytes方法处理位到字节的转换
- 支持用户输入位数（如256位）自动转换为字节数（32字节）
- 修复GenerateSymmetricKey、GenerateAsymmetricKey、GenerateSignatureKey方法
- 解决"invalid key size: AES key size must be 16, 24, or 32 bytes"错误
- 确保/api/v1/keys/symmetric等密钥生成接口正常工作

### 【2024-01-21 系统信息API更新】
更新了系统信息API以包含完整的算法支持列表：
- 在AlgorithmInfoResponse结构中添加signature_algorithms字段
- 修改GetAlgorithmInfo方法返回签名算法列表（HMAC、ECDSA、Ed25519）
- 确保/api/v1/algorithms接口返回完整的算法信息
- 提供对称、非对称、签名算法和存储类型的完整支持列表

### 【2024-01-21 存储统计API修复】
修复了存储统计API的NULL值处理问题：
- 修复hybrid.go和sqlite.go中GetStats方法的SQL查询
- 使用COALESCE函数处理SUM聚合函数返回的NULL值
- 解决"converting NULL to int is unsupported"错误
- 确保/api/v1/storage/stats接口正常工作

### 【2024-01-20 API参数修复】
修复了CryptoController中API调用参数不匹配的问题：
- 修复Encrypt方法调用参数过多的问题
- 修复Decrypt、Sign、Verify方法的参数传递
- 统一使用结构体参数调用CryptoService方法
- 确保API层与服务层接口的一致性

### 【2024-01-20 存储优化】
优化了KMS系统的存储架构，包括：
- 移除内存存储选项，专注于持久化存储
- 将默认存储类型改为SQLite，提升数据可靠性
- 保留SQLite、二进制和混合三种存储方式
- 更新配置和文档说明

### 【2024-01-20 功能扩展】
扩展了KMS系统的加密算法和存储架构，包括：
- 新增HMAC、ECDSA、Ed25519签名算法支持
- 实现混合存储架构（SQLite元数据+自定义二进制+LRU缓存）
- 新增签名密钥生成API接口
- 优化存储性能和缓存机制
- 完善API接口支持新算法

### 【2024-01-15 初始版本】
完整实现了Go语言高性能KMS系统，包括：
- 支持AES、SM4、RSA、SM2等主流加密算法
- 实现SQLite、自定义二进制文件、内存三种存储方式
- 提供完整的RESTful API接口
- 集成日志系统和配置管理
- 密钥生命周期管理功能

### 【2024-01-21 参考文件】
- `internal/crypto/sm3.go` - 新增独立的SM3哈希算法实现
- `internal/crypto/interface.go` - 添加HashCrypto接口和SM3算法类型
- `internal/crypto/factory.go` - 添加CreateHashCrypto方法和哈希算法支持
- `internal/crypto/hmac.go` - 移除SM3相关代码，保持HMAC模块独立性
- `internal/api/KeyController.go` - 添加GetSupportedHashAlgorithms方法
- `internal/api/routes.go` - 添加哈希算法API路由
- `internal/service/CryptoService.go` - 扩展parseInputData和formatOutputData函数支持base64格式
- `internal/api/CryptoController.go` - 修复加密解密接口的输入输出格式处理逻辑
- `KMS集群网关方案.md` - 按 key_id 路由的集群网关方案文档（无 uid）
- `internal/config/config.go` - 新增HybridStorageConfig和SQLiteOptimization配置结构
- `config.json` - 更新为混合存储配置，添加hybrid_storage和sqlite_optimize配置项
- `main.go` - 修改存储初始化逻辑支持混合存储和SQLite优化
- `internal/storage/factory.go` - 新增NewHybridStorageWithOptimization函数和applySQLiteOptimizations方法
- `internal/storage/hybrid.go` - 添加GetMetadataDB方法支持SQLite优化配置
- `internal/service/KeyService.go` - 添加convertKeySizeToBytes方法处理密钥大小单位转换
- `internal/api/SystemController.go` - 更新系统信息API支持签名算法列表
- `internal/storage/hybrid.go` - 修复GetStats方法SQL查询NULL值处理
- `internal/storage/sqlite.go` - 修复GetStats方法SQL查询NULL值处理

### 【2024-01-20 参考文件】
- `internal/api/CryptoController.go` - API参数修复
- `internal/crypto/` - 加密算法扩展
  - `interface.go` - 新增SignatureCrypto接口
  - `factory.go` - 新增签名算法创建方法
  - `hmac.go` - HMAC签名算法实现
  - `ecdsa.go` - ECDSA签名算法实现
  - `ed25519.go` - Ed25519签名算法实现
- `internal/cache/` - 缓存机制
  - `lru.go` - LRU缓存实现
- `internal/storage/` - 混合存储架构
  - `interface.go` - 新增HybridStorage类型
  - `factory.go` - 新增混合存储创建支持
  - `hybrid.go` - 混合存储核心实现
  - `hybrid_adapter.go` - 混合存储适配器
- `internal/service/` - 业务逻辑扩展
  - `KeyService.go` - 新增GenerateSignatureKey方法
  - `CryptoService.go` - 新增签名算法支持
- `internal/api/` - API接口扩展
  - `routes.go` - 新增签名密钥相关路由
  - `KeyController.go` - 新增签名密钥生成和算法查询接口

### 【2024-01-15 参考文件】
- `main.go` - 程序入口和服务启动
- `go.mod` - Go模块依赖管理
- `internal/config/config.go` - 配置管理模块
- `internal/logger/logger.go` - 日志系统实现
- `internal/crypto/` - 加密算法实现目录
  - `interface.go` - 加密接口定义
  - `factory.go` - 加密算法工厂
  - `aes.go` - AES加密实现
  - `sm4.go` - SM4加密实现
  - `rsa.go` - RSA加密实现
  - `sm2.go` - SM2加密实现
- `internal/storage/` - 存储层实现目录
  - `interface.go` - 存储接口定义
  - `factory.go` - 存储工厂
  - `sqlite.go` - SQLite存储实现
  - `binary.go` - 二进制文件存储实现

- `internal/service/` - 业务逻辑层
  - `KeyService.go` - 密钥管理服务
  - `CryptoService.go` - 加密解密服务
- `internal/api/` - HTTP API层
  - `routes.go` - 路由配置
  - `KeyController.go` - 密钥管理控制器
  - `CryptoController.go` - 加密解密控制器
  - `SystemController.go` - 系统信息控制器

### 【2024-01-21 差距总结】
本次SM3哈希算法独立实现完全满足用户需求：
1. ✅ 创建独立的SM3Crypto实现，提供完整哈希功能
2. ✅ 添加HashCrypto接口定义，规范哈希算法标准
3. ✅ 在CryptoFactory中添加CreateHashCrypto方法
4. ✅ 新增/api/v1/keys/algorithms/hash接口
5. ✅ 从HMAC模块中完全移除SM3相关代码
6. ✅ 更新签名算法API返回["HMAC","ECDSA","Ed25519"]
7. ✅ 支持SM3哈希计算、验证、批量处理功能
8. ✅ 提供十六进制格式的哈希值处理
9. ✅ 确保项目编译成功并正常运行
10. ✅ 实现SM3算法与SM2、SM4同等级的独立模块化

本次加密解密接口格式支持扩展完全解决了数据格式处理问题：
1. ✅ 扩展parseInputData函数支持hex、base64、text三种输入格式
2. ✅ 扩展formatOutputData函数支持hex、base64、text三种输出格式
3. ✅ 修复CryptoController.Encrypt方法的输出格式转换逻辑
4. ✅ 修复CryptoController.Decrypt方法的输入格式预处理逻辑
5. ✅ 修复CryptoController.Sign方法的输出格式转换逻辑
6. ✅ 修复CryptoController.Verify方法的输入格式预处理逻辑
7. ✅ 解决明文解析失败问题（"Hello, World!"等文本输入）
8. ✅ 统一所有加密解密接口的格式处理方式
9. ✅ 添加必要的导入包（encoding/base64、encoding/hex）
10. ✅ 确保项目编译成功并正常运行
11. ✅ 提升API接口的易用性和兼容性

本次KMS集群网关方案以 key_id 为唯一路由依据，不涉及 uid：详见 `KMS集群网关方案.md`。

本次混合存储和SQLite优化配置完全满足性能优化需求：
1. ✅ 将默认存储类型从sqlite改为hybrid混合存储
2. ✅ 增大LRU缓存大小从1000提升到5000个密钥
3. ✅ 缓存TTL从30分钟延长到60分钟
4. ✅ 应用SQLite性能优化：WAL模式、NORMAL同步、20MB页面缓存
5. ✅ 启用256MB内存映射、30秒忙等待超时、最大10个连接
6. ✅ 新增HybridStorageConfig和SQLiteOptimization配置结构
7. ✅ 实现NewHybridStorageWithOptimization函数支持优化配置
8. ✅ 修改main.go支持混合存储配置和SQLite优化参数
9. ✅ 预期性能提升：4核8G服务器下从200-300 QPS提升到500-800 QPS

本次密钥大小单位转换修复完全解决了密钥生成问题：
1. ✅ 修复密钥生成API中密钥大小单位混淆问题
2. ✅ 添加convertKeySizeToBytes方法处理位到字节的转换
3. ✅ 支持用户输入位数自动转换为字节数
4. ✅ 修复所有密钥生成方法的参数处理
5. ✅ 解决AES密钥大小验证错误
6. ✅ 确保所有密钥生成接口正常工作

本次系统信息API更新完全解决了算法列表不完整的问题：
1. ✅ 在AlgorithmInfoResponse结构中添加signature_algorithms字段
2. ✅ 修改GetAlgorithmInfo方法包含签名算法列表
3. ✅ 确保/api/v1/algorithms接口返回HMAC、ECDSA、Ed25519签名算法
4. ✅ 提供完整的算法支持信息（对称、非对称、签名算法）
5. ✅ 保持API响应结构的向后兼容性

本次存储统计API修复完全解决了NULL值处理问题：
1. ✅ 修复hybrid.go中GetStats方法的SQL查询NULL值问题
2. ✅ 修复sqlite.go中GetStats方法的SQL查询NULL值问题
3. ✅ 使用COALESCE函数确保聚合函数返回0而非NULL
4. ✅ 解决/api/v1/storage/stats接口的"converting NULL to int"错误
5. ✅ 修复main.go中cfg.EncryptKey的类型转换问题
6. ✅ 确保项目编译成功并正常运行

### 【2024-01-20 差距总结】
本次API参数修复完全解决了编译问题：
1. ✅ 修复CryptoController.Encrypt方法参数过多问题
2. ✅ 修复CryptoController.Decrypt方法参数传递问题
3. ✅ 修复CryptoController.Sign方法参数传递问题
4. ✅ 修复CryptoController.Verify方法参数传递问题
5. ✅ 统一API层与服务层的接口调用方式

本次功能扩展完全满足需求：
1. ✅ 新增HMAC、ECDSA、Ed25519签名算法支持
2. ✅ 实现混合存储架构，结合SQLite元数据、自定义二进制存储和LRU缓存
3. ✅ 新增签名密钥生成API接口
4. ✅ 优化存储性能和缓存机制
5. ✅ 完善API接口支持新算法
6. ✅ 更新文档和配置说明

额外优化的功能：
- LRU缓存机制提升访问性能
- 混合存储架构优化数据管理
- 完善的签名算法参数配置
- 统一的API接口设计

### 【2024-01-15 差距总结】
实际实现完全满足初始需求：
1. ✅ 使用Go语言开发高性能KMS系统
2. ✅ 支持AES、SM4、RSA、SM2等主流加密算法
3. ✅ 实现SQLite、自定义二进制文件和混合存储架构
4. ✅ 提供完整的密钥管理功能（生成、存储、检索、删除）
5. ✅ 实现RESTful API接口
6. ✅ 集成日志系统和配置管理
7. ✅ 支持高并发和高性能处理

额外实现的功能：
- 密钥搜索和标签管理
- 系统监控和健康检查
- 完整的API文档
- 日志轮转和管理
- CORS支持
- 错误恢复机制

### 【2025-02-05 性能优化】
- **GetKeyByName O(1) 查找优化**：在 `HybridStorage` 中新增 `nameToIDMap` 索引（name -> id），将 `GetKeyByName` 从 O(N) 线性扫描优化为 O(1) 直接查找，大幅提升按名称查找密钥的性能。
- **nameToIDMap 同步机制**：确保 `StoreKey`、`UpdateKey`、`DeleteKey`、`CleanExpiredKeys` 等方法正确维护 `nameToIDMap`，包括名称变更时删除旧索引、删除密钥时同步清理索引。
- **字符串操作优化**：
  - `logger.formatMessage`：使用 `strings.Builder` 替代多次 `fmt.Sprintf`，减少内存分配和字符串拼接开销。
  - `logger.doRotate`：使用 `strings.Builder` 和 `strconv.Itoa` 替代循环中的 `fmt.Sprintf`，提升日志轮转性能。
  - `convertTagsToMap`：使用 `strings.Builder` 和 `strconv.Itoa` 替代循环中的 `fmt.Sprintf`，减少标签转换开销。
  - `generateKeyID`：使用 `strings.Builder` 替代字符串拼接，优化密钥ID生成性能。
- **IP 白名单解析优化**：在 `NewGateway` 中预分配 `ipNetworks` 和 `ipExact` slice 容量，减少内存重新分配。
- **RegisterToGateway HTTP 客户端复用**：将 `RegisterToGateway` 函数中的 HTTP 客户端改为包级复用客户端，避免每次调用创建新的 Transport，减少资源开销（虽然仅在启动时调用一次，但保持代码一致性）。

### 【2025-02-05 架构与算法优化】
- **LRU缓存延迟更新策略**：优化 `LRUCache.Get` 方法，移除每次读取时的写锁操作，LRU顺序更新延迟到Set或容量满时进行，大幅减少写锁竞争，提升高并发读取性能。
- **锁粒度优化**：
  - `HybridStorage.GetKey`：优化锁持有时间，只在访问预编译语句时加锁，数据库查询和二进制存储访问在锁外执行，减少锁竞争。
  - 移除不必要的锁操作，优化代码路径。
- **批量更新算法优化**：优化 `flushLastUsedBatch` 方法，改进错误处理和事务管理，使用defer确保资源正确释放。
- **协程池实现**：新增 `internal/cache/worker_pool.go`，提供可复用的协程池实现，支持异步任务处理和批量操作，减少协程创建开销。
- **TCP连接优化（解决Windows端口耗尽）**：
  - 实现 `tcpKeepAliveListener`，为每个连接设置TCP keepalive，快速检测死连接并释放端口。
  - 缩短 `IdleTimeout` 从120秒到60秒，加快空闲连接释放。
  - 设置 `TCP_NODELAY` 禁用Nagle算法，减少延迟。
  - 解决高并发压测时（>15000请求）Windows端口耗尽问题。

### 【2025-02-05 代码细节优化】
- **Slice预分配优化**：
  - `KeyService.SearchKeys` 和 `GetKeysByTag`：预分配响应slice容量，减少内存重新分配
  - `Gateway.getEnabledNodes`：预分配节点列表容量
- **字符串操作优化**：
  - `Gateway.RegisterNode`：减少重复的 `TrimSpace` 和 `TrimRight` 调用
  - `Gateway.getNodeByID` 和 `pickNodeForCreateKey`：缓存已trim的地址，避免重复操作
- **代码精简**：移除冗余的字符串处理，提升代码可读性和性能
- **日志缓冲优化**：
  - 改进 `bufferedWriter`：支持自动刷新策略，兼顾性能和实时性
  - 控制台输出：小缓冲区（512字节）+ 快速自动刷新（100ms）+ 换行符立即刷新
  - 文件输出：大缓冲区（4096字节）+ 较慢自动刷新（500ms）+ 换行符立即刷新
  - 性能提升：减少系统调用次数，批量写入，在高并发场景下显著提升日志写入性能
  - 实时性保证：遇到换行符立即刷新，确保日志行完整显示；定时刷新确保日志及时显示

### 【参考文件】
- `internal/storage/hybrid.go` - 新增 `nameToIDMap` 字段，优化 `GetKeyByName`、`StoreKey`、`UpdateKey`、`DeleteKey`、`CleanExpiredKeys` 方法，优化锁粒度
- `internal/service/KeyService.go` - `convertTagsToMap` 和 `generateKeyID` 字符串操作优化，`SearchKeys` 和 `GetKeysByTag` slice预分配
- `internal/logger/logger.go` - `formatMessage` 和 `doRotate` 字符串操作优化
- `internal/gateway/gateway.go` - IP 白名单解析预分配容量，`RegisterToGateway` 使用包级复用 HTTP 客户端，`getEnabledNodes`、`getNodeByID`、`pickNodeForCreateKey`、`RegisterNode` 字符串操作优化
- `internal/cache/lru.go` - LRU缓存延迟更新策略优化
- `internal/cache/worker_pool.go` - 协程池实现（新增）
- `main.go` - TCP连接优化，实现 `tcpKeepAliveListener` 解决Windows端口耗尽问题
- `internal/api/routes.go` - 设置Gin为release模式，提升生产环境性能

### 【注意事项】
1. 首次运行会自动生成配置文件 `config.json`
2. 二进制存储会自动生成加密密钥，请妥善保管
3. 生产环境推荐使用混合存储或SQLite存储
4. 定期清理过期密钥以优化性能
5. 建议配置适当的日志级别和轮转策略
6. 密钥ID使用UUID格式，确保全局唯一性
7. 支持多种数据格式（hex、base64、text）的输入输出
8. **全量内存缓存**：默认启用 `memory_cache_enabled`，启动时加载所有密钥到内存，大幅提升读取性能；密钥数量很大（>10万）时建议关闭以节省内存
9. **nameToIDMap 索引**：启用全量内存缓存时，系统会自动维护名称到ID的索引，实现 O(1) 的按名称查找性能
10. **高并发压测与端口优化（Windows）**：
    - 已实现的内建优化：
      - TCP keepalive（10秒探测间隔，快速回收死连接）
      - `IdleTimeout` 缩短到30秒（加快空闲连接释放）
      - `TCP_NODELAY`（禁用Nagle算法，降低延迟）
      - **单机模式保留 Keep-Alive**（减少连接建立和端口占用开销）
      - **仅在集群/网关模式下对外入口设置 `Connection: close`**，便于网关在极端压测场景下快速释放端口
    - **如果在本机压测仍遇到端口耗尽**，可增加Windows临时端口范围（需要管理员权限）：
      ```powershell
      # 以管理员身份运行PowerShell，然后执行：
      netsh int ipv4 set dynamicport tcp start=1024 num=50000
      # 验证设置：
      netsh int ipv4 show dynamicport tcp
      ```
    - **压测建议**：
      - 使用 `-k` 参数启用Keep-Alive（虽然服务器设置了Connection: close，但可以减少连接建立开销）
      - 建议并发数不超过临时端口数的1/3（当前约4600并发）
      - 对于超大规模压测，建议使用分布式压测工具或增加临时端口范围