Lannamokia_vhdmount/VHDSelectServer/README.md

VHD选择服务器 - 跨平台版本

一个现代化的跨平台VHD关键词管理服务器，提供Web GUI界面和HTTP API接口。

✨ 特性

• 🌐 跨平台支持: 支持Windows、Linux、macOS
• 🎨 现代化Web界面: 响应式设计，支持移动设备
• 🔧 RESTful API: 标准HTTP API接口
• 💾 持久化存储: 自动保存配置到JSON文件
• 🚀 零配置启动: 开箱即用
• 📱 实时更新: 界面自动刷新状态
• 🔒 输入验证: 安全的用户输入处理

🛠️ 系统要求

Node.js版本（推荐）

• Node.js 14.0+
• npm（随Node.js安装）

Python版本（备选）

• Python 3.6+
• 无需额外依赖

🚀 快速开始

方法1: Docker部署（推荐）

选项1: 使用内置数据库（默认）

# 使用Docker Compose启动（内置PostgreSQL数据库）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

选项2: 使用外部数据库

# 使用外部数据库配置文件
docker-compose -f docker-compose.external-db.yml up -d

# 或者手动配置环境变量
docker run -d \
  --name vhd-select-server \
  -p 8080:8080 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/vhd-data:/app/vhd-data \
  -e USE_EMBEDDED_DB=false \
  -e DB_HOST=your-db-host \
  -e DB_PORT=5432 \
  -e DB_NAME=vhd_select \
  -e DB_USER=your-db-user \
  -e DB_PASSWORD=your-db-password \
  lty271104/vhd-select-server:latest

方法2: Node.js版本

1. 安装Node.js

   • 访问 https://nodejs.org/
   • 下载并安装LTS版本

2. 启动服务器

   # 双击运行
   start.bat
   
   # 或者命令行运行
   npm install
   npm start
   

🌐 访问界面

服务器启动后，访问以下地址：

• Web界面: http://localhost:8080
• API文档: http://localhost:8080/api/status

📡 API接口

VHD Select Server 提供完整的RESTful API接口，支持机台管理、VHD关键词设置和状态监控。

🔐 认证接口

登录

POST /api/auth/login
Content-Type: application/json

{
  "password": "admin123"
}

响应示例:

{
  "success": true,
  "message": "登录成功"
}

登出

POST /api/auth/logout

响应示例:

{
  "success": true,
  "message": "已登出"
}

检查认证状态

GET /api/auth/check

响应示例:

{
  "isAuthenticated": true
}

修改管理员密码

POST /api/auth/change-password
Content-Type: application/json
Authorization: 需要登录

{
  "currentPassword": "admin123",
  "newPassword": "newPassword123",
  "confirmPassword": "newPassword123"
}

响应示例:

{
  "success": true,
  "message": "密码修改成功"
}

错误响应示例:

{
  "success": false,
  "message": "当前密码错误"
}

🖥️ VHD关键词接口

获取当前VHD关键词

GET /api/boot-image-select?machineId=MACHINE001

参数说明:

• machineId (必需): 机台唯一标识符

响应示例:

{
  "success": true,
  "BootImageSelected": "SDEZ",
  "machineId": "MACHINE001",
  "timestamp": "2025-10-21T11:39:43.809Z"
}

设置全局VHD关键词 🔒

POST /api/set-vhd
Content-Type: application/json
Authorization: 需要登录

{
  "BootImageSelected": "NEW_KEYWORD"
}

响应示例:

{
  "success": true,
  "BootImageSelected": "NEW_KEYWORD",
  "message": "VHD关键词更新成功"
}

🛡️ 机台保护接口

获取机台保护状态

GET /api/protect?machineId=MACHINE001

参数说明:

• machineId (必需): 机台唯一标识符

响应示例:

{
  "success": true,
  "protected": false,
  "machineId": "MACHINE001",
  "timestamp": "2025-10-21T11:39:43.809Z"
}

设置机台保护状态 🔒

POST /api/protect
Content-Type: application/json
Authorization: 需要登录

{
  "machineId": "MACHINE001",
  "protected": true
}

响应示例:

{
  "success": true,
  "protected": true,
  "machineId": "MACHINE001",
  "message": "机台保护状态已更新"
}

🏭 机台管理接口

获取所有机台信息 🔒

GET /api/machines
Authorization: 需要登录

响应示例:

{
  "success": true,
  "machines": [
    {
      "machine_id": "MACHINE001",
      "protected": false,
      "vhd_keyword": "SDEZ",
      "last_seen": "2025-10-21T11:39:43.809Z",
      "created_at": "2025-10-21T10:00:00.000Z"
    }
  ],
  "count": 1,
  "timestamp": "2025-10-21T11:39:43.809Z"
}

设置特定机台的VHD关键词 🔒

POST /api/machines/{machineId}/vhd
Content-Type: application/json
Authorization: 需要登录

{
  "vhdKeyword": "CUSTOM_VHD"
}

响应示例:

{
  "success": true,
  "machineId": "MACHINE001",
  "vhdKeyword": "CUSTOM_VHD",
  "message": "机台VHD关键词已更新"
}

删除机台 🔒

DELETE /api/machines/{machineId}
Authorization: 需要登录

响应示例:

{
  "success": true,
  "machineId": "MACHINE001",
  "message": "机台已删除"
}

📊 系统状态接口

获取服务器状态

GET /api/status

响应示例:

{
  "success": true,
  "status": "running",
  "BootImageSelected": "SDEZ",
  "uptime": 30.415774368,
  "timestamp": "2025-10-21T11:39:43.809Z",
  "version": "1.2.0"
}

📝 API使用说明

认证要求:

• 🔒 标记的接口需要先通过 /api/auth/login 登录
• 登录后会话有效期为24小时
• 默认管理员密码: admin123

错误响应格式:

{
  "success": false,
  "error": "错误描述",
  "requireAuth": true  // 仅在需要认证时出现
}

状态码说明:

• 200: 请求成功
• 400: 请求参数错误
• 401: 未认证或认证失败
• 404: 资源不存在
• 500: 服务器内部错误

🎯 使用说明

Web界面操作

1. 查看当前状态: 页面会显示服务器运行状态和当前VHD关键词
2. 设置新关键词: 在输入框中输入新的VHD关键词，点击"更新"按钮
3. 自动刷新: 页面每30秒自动刷新状态
4. 实时反馈: 操作结果会立即显示在界面上

配置持久化

• Docker部署: 配置保存在 /app/config/vhd-config.json，通过卷映射到主机的 ./config 目录
• 本地部署: 配置保存在项目根目录的 vhd-config.json 文件中
• 环境变量: 可通过 CONFIG_PATH 环境变量自定义配置文件路径

Docker相关

数据库配置选项

内置数据库模式（默认）

• 自动在容器内启动PostgreSQL数据库
• 数据持久化到Docker卷
• 零配置，开箱即用

外部数据库模式

• 连接到外部PostgreSQL数据库
• 支持云数据库服务
• 更好的扩展性和可维护性

环境变量

应用配置

• PORT: 服务端口（默认: 8080）
• CONFIG_PATH: 配置文件目录路径（默认: /app/config）
• NODE_ENV: 运行环境（默认: production）

数据库配置

• USE_EMBEDDED_DB: 是否使用内置数据库（默认: true）
• DB_HOST: 数据库主机地址（默认: localhost）
• DB_PORT: 数据库端口（默认: 5432）
• DB_NAME: 数据库名称（默认: vhd_select）
• DB_USER: 数据库用户名（默认: postgres）
• DB_PASSWORD: 数据库密码（默认: vhd_select_password）
• DB_MAX_CONNECTIONS: 最大连接数（默认: 20）
• DB_IDLE_TIMEOUT: 空闲连接超时时间（默认: 30000ms）
• DB_CONNECTION_TIMEOUT: 连接超时时间（默认: 5000ms）
• DB_SSL: 是否启用SSL连接（默认: false）

数据卷

• /app/config: 配置文件持久化目录
• /app/vhd-data: VHD数据文件持久化目录
• /var/lib/postgresql/data: 内置数据库数据持久化目录

健康检查

• 端点: http://localhost:8080/api/health
• 间隔: 30秒
• 超时: 10秒
• 重试: 3次
• 启动等待时间: 60秒

配置文件说明

docker-compose.yml: 使用内置数据库的默认配置 docker-compose.external-db.yml: 使用外部数据库的示例配置

故障排除

内置数据库问题

# 检查数据库初始化日志
docker-compose logs vhd-select-server | grep -i postgres

# 重新初始化数据库
docker-compose down -v
docker-compose up -d

外部数据库连接问题

# 测试数据库连接
docker run --rm -it postgres:15-alpine psql -h your-db-host -U your-db-user -d vhd_select

# 检查网络连接
docker-compose exec vhd-select-server ping your-db-host

数据持久化问题

# 检查数据卷
docker volume ls | grep vhd

# 备份数据
docker run --rm -v vhd_db_data:/data -v $(pwd):/backup alpine tar czf /backup/vhd_backup.tar.gz /data

命令行测试

# 获取当前VHD关键词
curl http://localhost:8080/api/boot-image-select

# 设置新的VHD关键词
curl -X POST http://localhost:8080/api/set-vhd \
     -H "Content-Type: application/json" \
     -d '{"BootImageSelected":"CUSTOM_VHD"}'

📁 文件结构

VHDSelectServer/
├── server.js          # Node.js服务器
├── server.py          # Python服务器
├── package.json       # Node.js依赖配置
├── start.bat          # Windows启动脚本
├── public/
│   └── index.html     # Web界面
├── vhd-config.json    # 配置文件（自动生成）
└── README.md          # 说明文档

🔧 配置说明

• 端口: 默认8080，可通过环境变量PORT修改
• 配置文件: vhd-config.json自动生成，存储当前VHD关键词
• 日志: 服务器会在控制台输出访问日志

🔗 与VHD挂载程序集成

此服务器与原有的VHD挂载程序完全兼容：

1. API兼容: 保持原有的/api/boot-image-select接口
2. 数据格式: 返回相同的JSON格式
3. 配置持久化: VHD关键词会自动保存和恢复

🛡️ 安全特性

• 输入验证: 自动验证和清理用户输入
• CORS支持: 支持跨域请求
• 错误处理: 完善的错误处理和用户反馈
• 格式标准化: 自动转换为大写格式
• 用户认证: 基于会话的管理员认证系统
• 密码安全: bcrypt加密存储，支持在线修改管理员密码
• 会话管理: 24小时会话有效期，自动登出保护
• 数据库安全: 密码哈希持久化存储，支持密码策略验证

🐛 故障排除

端口被占用

# 检查端口占用
netstat -ano | findstr :8080

# 使用其他端口
python server.py 8081

Node.js未安装

• 下载安装: https://nodejs.org/
• 使用Python版本作为备选方案

权限问题

• 确保有写入配置文件的权限
• 在管理员模式下运行（如需要）

📝 更新日志

v1.2.0

• ✅ 完整Docker化支持（内置/外部数据库）
• ✅ PostgreSQL数据库集成
• ✅ 机台管理功能
• ✅ 机台保护状态控制
• ✅ 用户认证和会话管理
• ✅ 管理员密码在线修改功能
• ✅ bcrypt密码加密存储
• ✅ 密码安全策略验证
• ✅ 完整的RESTful API文档
• ✅ 健康检查和监控
• ✅ 数据持久化和备份

v1.0.0

• ✅ 跨平台支持（Node.js + Python）
• ✅ 现代化Web界面
• ✅ RESTful API接口
• ✅ 用户自定义VHD关键词
• ✅ 配置持久化存储
• ✅ 实时状态更新

🤝 技术支持

如有问题，请检查：

1. 服务器是否正常启动
2. 端口是否被占用
3. 防火墙设置
4. 浏览器控制台错误信息

---

🎉 享受使用全新的跨平台VHD选择服务器！