# Keymanager

**Repository Path**: NekohaMao/Keymanager

## Basic Information

- **Project Name**: Keymanager
- **Description**: 密钥管理系统
- **Primary Language**: Shell
- **License**: 0BSD
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-03
- **Last Updated**: 2025-12-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 密钥管理系统

一个安全、高效的密钥管理系统，包含服务端和客户端组件，支持多种存储模式和加密通信。

## 系统特性

### 服务端特性
- **多存储模式**: 支持文件存储、MySQL、PostgreSQL和SQLite
- **安全通信**: HTTPS加密通信，数字签名验证
- **密钥管理**: 完整的密钥生命周期管理（增删改查）
- **防重放攻击**: 基于nonce的防重放机制
- **交互式界面**: 友好的命令行交互界面
- **系统监控**: 实时系统资源监控
- **自动清理**: 自动清理过期密钥
- **审计日志**: 详细的操作日志记录

### 客户端特性
- **强兼容性**: 支持多种Linux发行版
- **防重放攻击**: 客户端nonce缓存机制
- **自动重试**: 网络异常自动重试
- **用户命令**: 验证成功/失败后执行自定义命令
- **调试模式**: 详细的调试信息输出
- **配置灵活**: JSON配置文件，易于定制

## 系统架构

```
┌─────────────────┐    HTTPS/8443    ┌─────────────────┐
│                 │◄─────────────────►│                 │
│   客户端        │                  │   服务端        │
│   (Shell)       │                  │   (Python)      │
│                 │                  │                 │
└─────────────────┘                  └─────────────────┘
                                              │
                                              ▼
                                    ┌─────────────────┐
                                    │   存储层        │
                                    │ File/MySQL/PG   │
                                    └─────────────────┘
```

## 环境要求

### 服务端
- **操作系统**: CentOS 7/8、Ubuntu 20.04、OpenCloudOS 9.4
- **Python**: 3.7+
- **依赖**: cryptography, psutil, pymysql, psycopg2-binary
- **可选**: MySQL 5.7+, PostgreSQL 10+

### 客户端
- **操作系统**: 任何支持Bash的Linux发行版
- **必需工具**: curl, openssl, date, base64
- **可选工具**: jq (用于更好的JSON解析)

## 快速开始

### 1. 服务端部署

```bash
# 进入服务端目录
cd server

# 运行一键部署脚本
chmod +x deploy.sh
./deploy.sh

# 启动交互式界面
./venv/bin/python app.py

# 或启动服务器模式
./venv/bin/python app.py --server
```

### 2. 客户端部署

```bash
# 进入客户端目录
cd client

# 运行一键部署脚本
chmod +x deploy.sh
./deploy.sh

# 测试连接
./client.sh --test

# 验证密钥
./client.sh <密钥ID>
```

## 详细使用说明

### 服务端使用

#### 交互式模式
```bash
./venv/bin/python app.py
```

交互式菜单选项：
1. **生成密钥** - 创建新的密钥
2. **列出密钥** - 查看所有密钥状态
3. **激活/禁用密钥** - 管理密钥状态
4. **删除密钥** - 永久删除密钥
5. **系统监控** - 查看系统资源使用情况
6. **启动服务器** - 启动HTTPS服务

#### 服务器模式
```bash
./venv/bin/python app.py --server
```

#### 系统服务模式
```bash
# 启动服务
sudo systemctl start keymanager

# 查看状态
sudo systemctl status keymanager

# 查看日志
tail -f logs/server.log
```

### 客户端使用

#### 基本用法
```bash
# 验证密钥
./client.sh <密钥ID>

# 指定服务器
./client.sh -s https://server:8443 <密钥ID>

# 调试模式
./client.sh --debug <密钥ID>

# 测试连接
./client.sh --test
```

#### 高级用法
```bash
# 自定义配置文件
./client.sh -c custom_config.json <密钥ID>

# 设置超时和重试
./client.sh -t 15 -r 5 <密钥ID>

# 指定nonce（测试用）
./client.sh -n custom_nonce <密钥ID>
```

## 配置说明

### 服务端配置 (server/config.json)

```json
{
  "port": 8443,
  "storage_type": "file",
  "db_config": {
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "user": "keymanager",
      "password": "password",
      "database": "keymanagement"
    }
  },
  "ssl_cert": "server/certs/server.crt",
  "ssl_key": "server/certs/server.key"
}
```

### 客户端配置 (client/client_config.json)

```json
{
  "server_url": "https://localhost:8443",
  "timeout": 10,
  "retry_count": 3,
  "debug": false,
  "user_commands": {
    "success": "echo '验证成功，执行业务逻辑'",
    "failure": "echo '验证失败，拒绝访问'"
  }
}
```

## API接口

### 密钥验证接口
```
POST /validate
Content-Type: application/json

{
  "key_id": "密钥ID",
  "nonce": "防重放随机数"
}
```

响应：
```json
{
  "success": true,
  "message": "验证成功"
}
```

### 系统监控接口
```
POST /system
```

响应：
```json
{
  "success": true,
  "data": {
    "cpu_percent": 15.2,
    "memory_percent": 45.8,
    "disk_percent": 60.1,
    "timestamp": "2025-01-01T12:00:00"
  }
}
```

## 安全特性

### 通信安全
- **HTTPS加密**: 所有通信使用TLS 1.2+加密
- **证书验证**: 支持自签名和CA签名证书
- **数字签名**: 关键数据使用RSA数字签名

### 密钥安全
- **加密存储**: 密钥值使用Fernet对称加密存储
- **访问控制**: 管理员权限控制
- **生命周期管理**: 自动过期和清理机制

### 防攻击机制
- **防重放攻击**: 基于nonce的时间窗口验证
- **连接限制**: 连接超时和重试限制
- **日志审计**: 详细的操作日志记录

## 故障排除

### 常见问题

#### 1. 服务端启动失败
```bash
# 检查Python环境
python3 --version

# 检查依赖
pip list | grep cryptography

# 查看详细错误
./venv/bin/python app.py --debug
```

#### 2. 客户端连接失败
```bash
# 测试网络连接
curl -k https://localhost:8443/system

# 检查防火墙
sudo firewall-cmd --list-ports

# 查看客户端日志
tail -f client.log
```

#### 3. SSL证书问题
```bash
# 重新生成证书
cd server/certs
openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 365 -nodes
```

#### 4. 数据库连接问题
```bash
# 检查数据库服务
systemctl status mysql
systemctl status postgresql

# 测试连接
mysql -u keymanager -p -h localhost
```

### 日志分析

#### 服务端日志
```bash
# 实时查看日志
tail -f server/logs/server.log

# 搜索错误
grep ERROR server/logs/server.log

# 查看最近的验证请求
grep "密钥验证" server/logs/server.log | tail -10
```

#### 客户端日志
```bash
# 查看客户端日志
tail -f client/client.log

# 调试模式运行
./client.sh --debug <密钥ID>
```

## 性能优化

### 服务端优化
- **数据库索引**: 为key_id字段创建索引
- **连接池**: 使用数据库连接池
- **缓存机制**: 实现密钥缓存减少数据库查询
- **异步处理**: 使用异步框架提高并发性能

### 客户端优化
- **连接复用**: 复用HTTP连接
- **并发验证**: 支持批量密钥验证
- **本地缓存**: 缓存验证结果（短时间）

## 扩展开发

### 添加新的存储后端
```python
class CustomStorageManager(DatabaseManager):
    def __init__(self, config):
        # 实现自定义存储逻辑
        pass
    
    def add_key(self, key_info):
        # 实现添加密钥逻辑
        pass
```

### 自定义认证机制
```python
class CustomAuthenticator:
    def authenticate(self, credentials):
        # 实现自定义认证逻辑
        pass
```

## 许可证

本项目采用MIT许可证，详见LICENSE文件。

## 贡献指南

1. Fork本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启Pull Request

## 支持

如有问题或建议，请提交Issue或联系维护团队。

---

**注意**: 本系统设计用于内部网络环境，在生产环境中使用前请进行充分的安全评估和测试。