CadHubManage

基于WebSocket的实时软件控制管理系统，用于通过Web接口控制Windows服务器上的软件。

项目方案设计

一、技术架构概述

核心技术栈：

• 后端：Python + FastAPI
• 实时通信：WebSocket（纯WebSocket架构）
• 进程管理：subprocess + psutil
• 数据格式：JSON
• 日志系统：异步文件存储

二、项目目录结构

project-root/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 主入口
│   ├── config.py               # 配置文件
│   │
│   ├── api/                    # API 路由
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       └── websocket.py   # WebSocket API（所有功能）
│   │
│   ├── core/                   # 核心功能
│   │   ├── __init__.py
│   │   ├── security.py         # JWT 认证逻辑
│   │   ├── software_manager.py # 软件管理核心类
│   │   ├── process_monitor.py  # 进程监控
│   │   ├── websocket_manager.py # WebSocket 连接管理
│   │   └── log_manager.py      # 操作日志管理
│   │
│   ├── models/                 # 数据模型
│   │   ├── __init__.py
│   │   ├── user.py            # 用户模型
│   │   ├── software.py        # 软件定义模型
│   │   ├── task.py            # 任务模型
│   │   └── operation_log.py   # 操作日志模型
│   │
│   ├── schemas/                # Pydantic 模型
│   │   ├── __init__.py
│   │   ├── auth.py            # 认证请求/响应模型
│   │   ├── software.py        # 软件操作请求/响应模型
│   │   └── task.py            # 任务状态模型
│   │
│   ├── services/               # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── software_service.py # 软件操作服务
│   │   └── notification.py     # 通知服务
│   │
│   └── utils/                  # 工具函数
│       ├── __init__.py
│       ├── logger.py           # 日志配置
│       └── exceptions.py       # 自定义异常
│
├── configs/                    # 配置文件目录
│   ├── software_config.yaml    # 软件配置（路径、参数等）
│   └── users.json             # 用户配置（简单认证）
│
├── logs/                       # 日志目录
│   ├── operation_logs/          # 操作日志文件目录
│   └── app.log                 # 系统日志文件
│
├── tests/                      # 测试目录
│   ├── __init__.py
│   └── test_software.py
│
├── requirements.txt            # Python 依赖
├── .env                       # 环境变量
├── .env.example               # 环境变量示例
└── README.md                  # 项目文档

三、核心功能设计

1. 软件配置管理 (software_config.yaml)

software:
  creo:
    name: "PTC Creo"
    executable_path: "C:\\Program Files\\PTC\\Creo 5.0.0.0\\Parametric\\bin\\parametric.exe"
    startup_args: []
    startup_timeout: 60
    check_process_name: ["xtop.exe", "pro_comm_msg.exe"]  # 支持多进程检测
    stop_timeout: 15  # 停止超时时间
    
  revit:
    name: "Autodesk Revit 2017"
    executable_path: "C:\\Program Files\\Autodesk\\Revit 2017\\Revit.exe"
    startup_args: ["/language", "CHS"]
    startup_timeout: 90
    check_process_name: "Revit.exe"
    
  autocad:
    name: "AutoCAD"
    executable_path: "C:\\Program Files\\Autodesk\\AutoCAD 2024\\acad.exe"
    startup_args: []
    startup_timeout: 45
    check_process_name: "acad.exe"
    
  pdms:
    name: "AVEVA PDMS 12.1 SP4"
    executable_path: "C:\\AVEVA\\Plant\\PDMS12.1.SP4\\pdms.bat"
    startup_args: ["Design", "noconsole"]
    startup_timeout: 120
    check_process_name: ["des.exe", "PDMSConsole.exe"]
    stop_timeout: 20
    
  # ... 其他软件配置

2. 纯WebSocket架构

架构设计理念：

• 所有功能通过WebSocket实现统一接口
• 实时双向通信，支持服务器主动推送
• 连接建立后通信开销小，性能优异
• 统一的JSON消息格式，易于开发和调试

WebSocket功能覆盖：

• 软件控制：启动、停止、重启、状态查询
• 日志管理：记录、查询、统计、清理
• 系统监控：服务状态、连接管理
• 实时通知：状态变化、错误推送

WebSocket支持的消息类型：

• ping - 心跳检测
• get_status - 获取服务状态
• get_software_list - 获取软件列表
• start_software - 启动软件
• stop_software - 停止软件
• restart_software - 重启软件
• log_operation - 记录用户操作日志
• query_logs - 查询操作日志
• get_log_by_id - 根据ID获取日志
• get_log_stats - 获取日志统计信息
• cleanup_logs - 清理过期日志
• get_operation_types - 获取操作类型列表

四、接口设计

1. WebSocket接口（主要API）

WS     /api/v1/ws/connect          # WebSocket连接端点

支持的消息类型：

• 软件控制：start_software, restart_software, get_software_list
• 日志管理：log_operation, query_logs, get_log_by_id, get_log_stats, cleanup_logs, get_operation_types
• 系统监控：ping, get_status

2. HTTP接口（辅助功能）

GET    /                           # 服务信息
GET    /health                     # 健康检查

五、WebSocket通信机制

1. 连接管理

• 支持多客户端同时连接
• 自动生成客户端ID
• 支持用户身份标识
• 连接状态实时监控

2. 消息处理

• 异步消息处理机制
• 任务立即返回ID
• 实时状态推送
• 统一错误处理

六、安全考虑

1. 进程隔离

   • 限制可执行的软件白名单
   • 验证所有路径输入
   • 使用受限的进程权限

2. API安全

   • JWT认证
   • 请求频率限制
   • 日志审计

3. 网络安全

   • WSS (WebSocket Secure) 传输
   • CORS配置，允许跨域
   • 连接状态监控和管理

七、监控与日志

1. 进程监控

   • 使用psutil监控软件进程
   • 定期检查进程状态
   • 异常自动告警

2. 日志记录

   • 操作日志：谁在什么时间启动了什么软件
   • 错误日志：启动失败原因
   • 性能日志：启动耗时统计

八、操作日志系统

1. 日志类型

• 系统操作日志 - 软件启动、重启等系统自动记录
• 用户操作日志 - 前端发送的用户自定义操作记录

2. 日志存储

• 格式 - JSON Lines (.jsonl) 格式
• 轮转 - 按日期自动分割文件
• 清理 - 自动清理过期日志文件
• 位置 - logs/operation_logs/ 目录

3. 日志查询

• 支持按时间、类型、用户等多维度过滤
• 提供统计信息和操作类型汇总
• WebSocket实时查询接口
• 支持分页和复杂查询条件

九、开发注意事项

1. 软件启动检测

   • 不同软件启动时间差异大
   • 需要合理的超时机制

2. 权限问题

   • 服务运行账户需要有启动目标软件的权限
   • 某些软件可能需要桌面交互权限

3. 并发控制

   • 限制同时启动的软件数量，一次只能启动1个，默认，也需要在配置文件中添加

4. WebSocket连接管理

   • 处理客户端断线重连
   • 消息队列和状态同步
   • 连接数量监控

5. 代码质量

   • 消除硬编码，使用枚举和配置
   • 参数化所有可配置项
   • 遵循MVP设计原则
   • 纯WebSocket架构，统一接口

十、架构变更说明

从混合架构到纯WebSocket架构

变更原因：

• 统一API接口，简化前端开发
• 提升实时性，支持服务器主动推送
• 减少HTTP连接开销，提高性能
• 便于功能扩展和维护

变更内容：

• 移除HTTP REST API（认证、软件控制、日志查询）
• 保留基础HTTP接口（健康检查、服务信息）
• 所有业务功能通过WebSocket实现
• 统一JSON消息格式

前端开发影响：

• 只需维护一个WebSocket连接
• 统一的消息处理机制
• 实时状态更新和错误推送
• 完整的日志查询和管理功能

迁移优势：

• ✅ 架构简化，代码更清晰
• ✅ 实时性能提升
• ✅ 资源使用优化
• ✅ 功能完整性保持
• ✅ 开发效率提升