# sshkey_manager
**Repository Path**: linyongwei/sshkey_manager
## Basic Information
- **Project Name**: sshkey_manager
- **Description**: ssh key 管理应用
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-11-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# SSH公钥管理网页应用
一个基于Flask的SSH公钥管理网页应用,专为内网环境设计,提供完整的SSH公钥生命周期管理、机器状态监控和自动化运维功能。
## 🚀 项目概述
本项目是一个现代化的SSH公钥管理平台,通过Web界面集中管理内网所有机器的公钥部署。采用模块化设计,具备实时监控、自动修复、批量操作等企业级功能。
### ✨ 核心特性
- 🔑 **完整的公钥管理** - 添加、删除、查看SSH公钥,支持过期时间设置和批量操作
- 🖥️ **智能机器管理** - 管理内网机器IP地址,实时状态监控和连接配置
- ⚡ **一键批量部署** - 快速将公钥部署到指定机器,支持批量操作
- 📊 **实时状态监控** - 实时检测机器在线状态和公钥部署状态
- 🔄 **自动修复机制** - 自动检测并修复异常的公钥关系,确保系统可靠性
- 🤖 **CI设备集成** - 自动同步CI设备IP,支持定时任务调度
- 🏷️ **标签化管理** - 支持机器标签分类,便于组织和管理
## 🏗️ 系统架构
### 架构图
```mermaid
graph TB
A[Web前端界面] --> B[Flask路由层]
B --> C[业务逻辑层]
C --> D[数据访问层]
D --> E[MongoDB数据库]
C --> F[SSH连接模块]
F --> G[远程机器集群]
H[定时任务调度器] --> I[机器状态监控]
H --> J[公钥关系修复]
H --> K[过期公钥清理]
H --> L[CI设备同步]
I --> M[状态缓存]
M --> E
J --> N[关系状态更新]
N --> E
K --> O[公钥状态更新]
O --> E
L --> P[设备信息同步]
P --> E
subgraph 核心模块
Q[database.py
数据库操作]
R[scheduler.py
定时任务]
S[ssh_helper.py
SSH连接]
T[routes.py
API路由]
U[app.py
应用入口]
end
B --> T
C --> Q
C --> R
C --> S
U --> C
```
### 模块设计
| 模块 | 职责 | 主要功能 |
|------|------|---------|
| **app.py** | 应用入口 | Flask应用初始化、服务启动 |
| **database.py** | 数据访问 | MongoDB操作、状态缓存、核心业务逻辑 |
| **scheduler.py** | 定时任务 | 状态监控、自动修复、设备同步 |
| **routes.py** | API路由 | HTTP接口定义、请求处理 |
| **ssh_helper.py** | SSH连接 | 远程机器连接、文件操作 |
| **key_validation.py** | 数据验证 | 公钥格式验证、输入校验 |
## 🛠️ 技术栈
- **后端框架**: Flask 2.3.3
- **数据库**: MongoDB 4.0+ (PyMongo 4.5.0)
- **SSH连接**: SSH Helper (系统SSH + sshpass)
- **前端技术**: HTML5 + CSS3 + JavaScript (ES6+)
- **定时调度**: Schedule 1.2.2
- **配置管理**: Python-dotenv 1.0.0
- **环境隔离**: Python虚拟环境 (venv)
## 📦 安装部署
### 环境要求
- Python 3.7+
- MongoDB 4.0+
- Linux/Unix环境 (支持sshpass)
- 内网环境 (推荐)
### 快速启动
1. **克隆项目**
```bash
git clone
cd sshkey_manager
```
2. **环境配置**
```bash
# 复制环境变量模板
cp .env.example .env
# 编辑配置文件
nano .env
```
3. **依赖安装**
```bash
# 使用启动脚本(推荐)
./start.sh
# 或手动安装
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
4. **启动服务**
```bash
python app.py
```
访问地址: `http://localhost:5588`
### 配置说明
#### 环境变量 (.env)
```env
# MongoDB配置
MONGODB_URI=mongodb://your-mongodb-host:27017/
# 应用配置 (可选,默认值已在config.py中设置)
# HOST=0.0.0.0
# PORT=5588
# DEBUG=True
# 定时任务配置
# MACHINE_STATUS_CHECK_INTERVAL=30 # 机器状态检查间隔(秒)
# MACHINE_KEYS_REPAIR_INTERVAL=600 # 公钥修复间隔(秒)
# EXPIRED_KEYS_CLEANUP_INTERVAL=3600 # 过期公钥清理间隔(秒)
```
#### 应用配置 (config.py)
```python
# MongoDB集合配置
COLLECTION_NAME = "public_keys" # 公钥集合
MACHINE_IPS_COLLECTION_NAME = "machine_ips" # 机器IP集合
MACHINE_KEYS_RELATION_COLLECTION_NAME = "machine_keys_relations" # 关系集合
CI_RESOURCES_NAME = "board_IPs" # CI设备集合
# 定时任务配置
MACHINE_STATUS_CHECK_INTERVAL = 30 # 机器状态检查(秒)
MACHINE_KEYS_REPAIR_INTERVAL = 600 # 公钥修复间隔(秒)
EXPIRED_KEYS_CLEANUP_INTERVAL = 3600 # 过期公钥清理(秒)
# 功能开关
MACHINE_KEYS_REPAIR_ENABLED = True # 启用自动修复
EXPIRED_KEYS_CLEANUP_ENABLED = True # 启用过期清理
```
## 📋 核心功能详解
### 1. 🔐 公钥管理
#### 功能特性
- **多格式支持**: RSA、ECDSA、Ed25519等主流SSH公钥格式
- **智能验证**: 自动验证公钥格式有效性和完整性
- **过期管理**: 支持设置公钥过期时间,到期自动禁用
- **批量导入**: 支持批量导入多个公钥文件
- **分类管理**: 通过标签和描述进行分类管理
#### API接口
```http
GET /ssh_key_manager/keys # 获取所有公钥
GET /ssh_key_manager/keys_paginated # 分页获取公钥(支持搜索)
POST /ssh_key_manager/add_public_key # 添加新公钥
POST /ssh_key_manager/delete # 删除指定公钥
```
#### 数据模型
```json
{
"name": "developer-key-001",
"public_key": "ssh-rsa AAAAB3NzaC1yc2E...",
"description": "开发人员SSH密钥",
"key_type": "ssh-rsa",
"created_at": "2024-01-15T10:30:00Z",
"expires_at": "2025-01-15T10:30:00Z"
}
```
### 2. 🖥️ 机器管理
#### 功能特性
- **实时状态**: 30秒间隔ping检测,实时显示机器在线状态
- **连接配置**: 管理SSH用户名、密码、端口等连接信息
- **标签分类**: 支持为机器添加多个标签,便于分组管理
- **状态缓存**: 智能缓存机制,减少不必要的网络请求
- **自动发现**: 支持从CI设备自动发现和导入机器
#### API接口
```http
GET /ssh_key_manager/machine_ips # 获取机器列表
POST /ssh_key_manager/add_machine_ip # 添加新机器
POST /ssh_key_manager/delete_machine_ip # 删除机器
POST /ssh_key_manager/update_machine_ip # 更新机器信息
POST /ssh_key_manager/check_machine_status # 检查机器状态
```
#### 数据模型
```json
{
"ip_address": "192.168.1.100",
"username": "root",
"password": "encrypted_password",
"port": 22,
"description": "Web服务器01",
"tags": ["web", "production", "linux"],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"is_active": true,
"status": "在线",
"last_checked": "2024-01-15T15:45:00Z"
}
```
### 3. ⚡ 公钥部署管理
#### 功能特性
- **一键部署**: 选择公钥和目标机器,一键完成部署
- **批量操作**: 同时向多台机器部署相同或不同的公钥
- **部署验证**: 部署后自动验证公钥是否正确写入authorized_keys
- **智能路径**: 自动识别不同用户的主目录路径(root/home)
- **权限管理**: 自动设置正确的文件权限(600)
- **重复检测**: 自动检测已存在的公钥,避免重复部署
#### 部署流程
```mermaid
sequenceDiagram
participant U as 用户
participant A as API
participant S as SSH Helper
participant M as 远程机器
U->>A: 请求部署公钥
A->>A: 验证输入和权限
A->>A: 检查重复部署
A->>S: 创建SSH连接
S->>M: 连接远程机器
M-->>S: 连接成功
S->>M: 检查.ssh目录
M-->>S: 目录状态
S->>M: 创建/检查authorized_keys
M-->>S: 文件状态
S->>M: 写入新公钥
M-->>S: 写入完成
S->>M: 设置文件权限
M-->>S: 权限设置完成
S-->>A: 部署成功
A->>A: 更新关系状态
A-->>U: 返回部署结果
```
#### API接口
```http
POST /ssh_key_manager/deploy_key # 部署单个公钥
POST /ssh_key_manager/add_keys_to_machine # 批量添加公钥
POST /ssh_key_manager/remove_authorized_key # 移除授权公钥
POST /ssh_key_manager/add_authorized_keys # 批量添加公钥
POST /ssh_key_manager/get_disk_space_from_remote # 获取磁盘空间
```
### 4. 🔧 机器公钥关系管理
#### 核心概念
机器公钥关系是系统的核心概念,维护机器IP与公钥名称之间的映射关系,确保部署的可追溯性和一致性。
#### 关系模型
```json
{
"ip": "192.168.1.100",
"key_name": "developer-key-001",
"username": "root",
"description": "Web服务器开发环境",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"last_checked": "2024-01-15T15:45:00Z",
"is_active": true,
"needs_repair": false,
"repair_attempts": 0
}
```
#### 管理功能
- **自动关系创建**: 部署成功时自动创建关系记录
- **关系状态追踪**: 实时追踪每个关系的健康状态
- **异常检测**: 自动识别需要修复的关系
- **历史记录**: 保存关系的变更历史
#### API接口
```http
POST /ssh_key_manager/save_machine_key_relation # 保存关系
GET /ssh_key_manager/get_machine_key_relations # 获取关系列表
POST /ssh_key_manager/delete_machine_key_relation # 删除关系
POST /ssh_key_manager/update_machine_key_relation_status # 更新状态
```
### 5. 🤖 自动化运维
#### 定时任务架构
项目采用独立的 `scheduler.py` 模块管理所有定时任务,确保系统的自动化运维能力。
#### 5.1 机器状态监控
- **监控间隔**: 30秒
- **检测方式**: ICMP Ping
- **缓存策略**: 60秒缓存超时
- **状态更新**: 实时更新机器在线状态
#### 5.2 公钥关系自动修复
- **检查间隔**: 10分钟
- **修复策略**:
- 机器离线:标记为待修复
- 公钥缺失:重新部署公钥
- 权限异常:修复文件权限
- **重试机制**: 智能重试和失败记录
#### 5.3 过期公钥自动清理
- **清理间隔**: 1小时
- **清理策略**:
- 从远程机器移除过期公钥
- 删除机器公钥关系映射
- 保留公钥记录供查看
- **安全机制**: 避免误删活跃公钥
#### 5.4 CI设备自动同步
- **同步间隔**: 30分钟
- **数据源**: `ci_boards_collection` MongoDB集合
- **同步逻辑**:
- 检测新设备IP
- 自动ping测试连通性
- 添加到机器管理系统
- 标记CI来源便于识别
#### 定时任务管理API
```http
POST /ssh_key_manager/start_machine_keys_repair_monitor # 启动修复监控
POST /ssh_key_manager/stop_machine_keys_repair_monitor # 停止修复监控
GET /ssh_key_manager/get_machine_keys_repair_status # 获取修复状态
GET /ssh_key_manager/get_all_monitors_status # 获取所有任务状态
```
## 🗄️ 数据库设计
### 集合结构
#### public_keys (公钥集合)
```javascript
{
_id: ObjectId("..."),
name: "developer-key-001",
public_key: "ssh-rsa AAAAB3NzaC1yc2E...",
description: "开发人员SSH密钥",
key_type: "ssh-rsa",
created_at: ISODate("2024-01-15T10:30:00Z"),
updated_at: ISODate("2024-01-15T10:30:00Z"),
expires_at: ISODate("2025-01-15T10:30:00Z")
}
```
#### machine_ips (机器IP集合)
```javascript
{
_id: ObjectId("..."),
ip_address: "192.168.1.100",
username: "root",
password: "encrypted_password",
port: 22,
description: "Web服务器01",
tags: ["web", "production"],
created_at: ISODate("2024-01-15T10:30:00Z"),
updated_at: ISODate("2024-01-15T10:30:00Z"),
is_active: true,
source: "ci_boards_sync",
ci_board_id: "board_001"
}
```
#### machine_keys_relations (关系集合)
```javascript
{
_id: ObjectId("..."),
ip: "192.168.1.100",
key_name: "developer-key-001",
username: "root",
description: "开发环境访问",
created_at: ISODate("2024-01-15T10:30:00Z"),
updated_at: ISODate("2024-01-15T10:30:00Z"),
last_checked: ISODate("2024-01-15T15:45:00Z"),
is_active: true,
needs_repair: false,
repair_attempts: 0
}
```
#### board_IPs (CI设备集合)
```javascript
{
_id: ObjectId("..."),
ip: "192.168.1.150",
name: "CI-Board-001",
type: "development_board",
status: "active",
created_at: ISODate("2024-01-15T10:30:00Z")
}
```
### 索引策略
```javascript
// public_keys集合
db.public_keys.createIndex({"name": 1}, {unique: true})
db.public_keys.createIndex({"public_key": 1}, {unique: true})
db.public_keys.createIndex({"expires_at": 1})
// machine_ips集合
db.machine_ips.createIndex({"ip_address": 1}, {unique: true})
db.machine_ips.createIndex({"tags": 1})
// machine_keys_relations集合
db.machine_keys_relations.createIndex({"ip": 1, "key_name": 1}, {unique: true})
db.machine_keys_relations.createIndex({"needs_repair": 1})
```
## 🚀 生产部署
### 系统要求
#### 硬件要求
- **CPU**: 2核心以上
- **内存**: 4GB以上
- **存储**: 20GB以上可用空间
- **网络**: 稳定的内网连接
#### 软件要求
- **操作系统**: Linux (Ubuntu 18.04+, CentOS 7+)
- **Python**: 3.7+ (推荐3.8+)
- **MongoDB**: 4.0+ (推荐4.4+)
- **SSH工具**: sshpass (用于密码认证)
### 部署步骤
#### 1. 环境准备
```bash
# 安装系统依赖
sudo apt update
sudo apt install -y python3 python3-pip python3-venv mongodb sshpass
# 创建应用用户
sudo useradd -m -s /bin/bash sshkeymgr
sudo su - sshkeymgr
```
#### 2. 应用部署
```bash
# 克隆代码
git clone
cd sshkey_manager
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate
# 安装依赖
pip install -r requirements.txt
```
#### 3. 生产配置
```bash
# 创建生产环境配置
cp .env.example .env.production
nano .env.production
# 编辑配置文件
MONGODB_URI=mongodb://prod-mongo-host:27017/
DEBUG=False
PORT=8080
```
#### 4. 服务化部署
```bash
# 创建systemd服务文件
sudo nano /etc/systemd/system/sshkey-manager.service
```
```ini
[Unit]
Description=SSH Key Manager Service
After=network.target
[Service]
Type=simple
User=sshkeymgr
WorkingDirectory=/home/sshkeymgr/sshkey_manager
Environment=PATH=/home/sshkeymgr/sshkey_manager/venv/bin
ExecStart=/home/sshkeymgr/sshkey_manager/venv/bin/python app.py
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
```bash
# 启动和启用服务
sudo systemctl daemon-reload
sudo systemctl enable sshkey-manager
sudo systemctl start sshkey-manager
sudo systemctl status sshkey-manager
```
#### 5. Nginx反向代理 (可选)
```nginx
server {
listen 80;
server_name sshkey-manager.company.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### 性能优化
#### 数据库优化
```javascript
// 启用连接池
const MongoClient = require('mongodb').MongoClient;
const client = new MongoClient(uri, {
maxPoolSize: 50,
minPoolSize: 5,
maxIdleTimeMS: 30000
});
```
#### 缓存策略
- **状态缓存**: 60秒缓存超时,减少ping频率
- **查询缓存**: 热点数据内存缓存
- **连接复用**: MongoDB连接池管理
#### 并发控制
- **线程池**: 限制并发SSH连接数
- **队列机制**: 批量操作队列化处理
- **限流控制**: 防止资源耗尽
## 🔒 安全配置
### 认证与授权
```python
# 建议在生产环境添加基础认证
from flask_httpauth import HTTPBasicAuth
auth = HTTPBasicAuth()
@auth.verify_password
def verify_password(username, password):
# 实现用户验证逻辑
return check_user_credentials(username, password)
@app.route('/admin')
@auth.login_required
def admin_panel():
return render_template('admin.html')
```
### 数据加密
```python
# 密码加密存储
from cryptography.fernet import Fernet
def encrypt_password(password):
key = Fernet.generate_key()
f = Fernet(key)
encrypted_password = f.encrypt(password.encode())
return encrypted_password, key
```
### 网络安全
- **内网部署**: 仅在可信内网环境运行
- **HTTPS配置**: 生产环境启用SSL/TLS
- **防火墙规则**: 限制访问源IP范围
- **VPN访问**: 通过VPN进行远程管理
### 审计日志
```python
import logging
# 配置审计日志
audit_logger = logging.getLogger('audit')
audit_handler = logging.FileHandler('audit.log')
audit_handler.setFormatter(
logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
)
audit_logger.addHandler(audit_handler)
audit_logger.setLevel(logging.INFO)
# 记录关键操作
audit_logger.info(f"User {username} deployed key {key_name} to {ip_address}")
```
## 🔧 运维管理
### 监控指标
```python
# 系统健康检查
@app.route('/health')
def health_check():
return {
'status': 'healthy',
'database': check_database_connection(),
'cache_size': len(machine_status_cache),
'active_tasks': get_active_tasks_count(),
'timestamp': datetime.now().isoformat()
}
```
### 日志管理
```python
import logging
from logging.handlers import RotatingFileHandler
# 配置轮转日志
handler = RotatingFileHandler(
'app.log',
maxBytes=100*1024*1024, # 100MB
backupCount=5
)
handler.setFormatter(
logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
)
app.logger.addHandler(handler)
```
### 备份策略
```bash
#!/bin/bash
# 数据库备份脚本
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/mongodb"
# 创建备份目录
mkdir -p $BACKUP_DIR
# 执行备份
mongodump --uri="$MONGODB_URI" --out="$BACKUP_DIR/backup_$DATE"
# 压缩备份
tar -czf "$BACKUP_DIR/backup_$DATE.tar.gz" -C "$BACKUP_DIR" "backup_$DATE"
# 清理旧备份(保留30天)
find $BACKUP_DIR -name "backup_*.tar.gz" -mtime +30 -delete
```
## 🐛 故障排除
### 常见问题
#### 1. MongoDB连接问题
```bash
# 检查MongoDB状态
sudo systemctl status mongod
# 检查连接
mongosh "mongodb://localhost:27017/ssh_key_manager"
# 查看日志
sudo tail -f /var/log/mongodb/mongod.log
```
#### 2. SSH连接失败
```bash
# 检查SSH服务
sudo systemctl status ssh
# 测试SSH连接
ssh -o ConnectTimeout=10 user@target-ip
# 安装sshpass (Ubuntu/Debian)
sudo apt install sshpass
# 安装sshpass (CentOS/RHEL)
sudo yum install sshpass
```
#### 3. 权限问题
```bash
# 检查文件权限
ls -la /home/user/.ssh/
ls -la /root/.ssh/
# 修复权限
chmod 700 /home/user/.ssh/
chmod 600 /home/user/.ssh/authorized_keys
chown user:user /home/user/.ssh/authorized_keys
```
#### 4. 性能问题
```python
# 调整并发限制
MAX_CONCURRENT_SSH = 10
# 优化查询
db.machine_ips.find({"is_active": true}).hint("is_active_1")
# 清理缓存
if len(machine_status_cache) > 1000:
machine_status_cache.clear()
```
### 调试模式
```bash
# 启用调试模式
export DEBUG=True
export LOG_LEVEL=DEBUG
python app.py
```
### 日志分析
```bash
# 查看应用日志
tail -f app.log
# 查看错误日志
grep ERROR app.log
# 统计部署次数
grep "成功部署" app.log | wc -l
# 查看SSH连接错误
grep "SSH连接" app.log | grep -i error
```
## 📚 API参考
### 认证
当前版本无需认证,生产环境建议添加认证机制。
### 响应格式
```json
{
"success": true,
"message": "操作成功",
"data": {...},
"timestamp": "2024-01-15T10:30:00Z"
}
```
```json
{
"success": false,
"error": "错误描述",
"error_code": "ERROR_CODE",
"timestamp": "2024-01-15T10:30:00Z"
}
```
### 分页参数
```http
GET /ssh_key_manager/keys_paginated?page=1&page_size=10&search=developer
```
- `page`: 页码(从1开始)
- `page_size`: 每页数量(最大100)
- `search`: 搜索关键词(可选)
## 🤝 贡献指南
### 开发环境搭建
```bash
# 1. Fork项目到你的GitHub账户
# 2. 克隆你的Fork
git clone https://github.com/your-username/sshkey_manager.git
cd sshkey_manager
# 3. 创建开发分支
git checkout -b feature/your-feature-name
# 4. 设置开发环境
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# 5. 配置开发数据库
# 编辑 .env 文件使用本地MongoDB
```
### 代码规范
```python
# 函数命名使用下划线
def get_public_keys_from_db():
pass
# 类命名使用驼峰式
class SSHKeyManager:
pass
# 常量使用大写
MAX_RETRY_COUNT = 3
DEFAULT_TIMEOUT = 30
# 添加类型提示
from typing import List, Dict, Tuple
def validate_key_format(key_content: str) -> Tuple[bool, str]:
return True, "格式正确"
```
### 提交规范
```bash
# 功能开发
git commit -m "feat: 添加批量部署功能"
# Bug修复
git commit -m "fix: 修复SSH连接超时问题"
# 文档更新
git commit -m "docs: 更新API文档"
# 代码重构
git commit -m "refactor: 重构定时任务模块"
```
### 测试要求
```bash
# 运行代码检查
flake8 *.py
# 运行类型检查
mypy database.py
# 运行单元测试
python -m pytest tests/
# 运行集成测试
python -m pytest tests/integration/
```
## 📄 许可证
本项目采用 [MIT License](LICENSE) 开源协议。
## 📞 支持与联系
- **问题反馈**: [GitHub Issues](https://github.com/your-repo/sshkey_manager/issues)
- **功能请求**: [GitHub Discussions](https://github.com/your-repo/sshkey_manager/discussions)
- **安全问题**: 请通过私有渠道报告安全问题
---
## 🎯 版本历史
### v2.0.0 (最新)
- ✨ 新增定时任务模块化架构
- 🤖 新增CI设备自动同步功能
- 🔄 优化SSH连接使用ssh_helper
- 📊 新增综合状态监控API
- 🔧 重构代码结构,提升可维护性
### v1.5.0
- ⚡ 批量部署功能增强
- 🏷️ 机器标签管理
- 📊 实时状态监控
- 🔄 自动修复机制
### v1.0.0
- 🔑 基础公钥管理
- 🖥️ 机器IP管理
- ⚡ 一键部署功能
- 📱 Web界面
---
*最后更新: 2024年1月*