# AutoSwitch

**Repository Path**: jeckchen666/auto-switch

## Basic Information

- **Project Name**: AutoSwitch
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-30
- **Last Updated**: 2025-11-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### AutoSwitch 项目说明

#### 项目概述
AutoSwitch 是一个基于 Node.js 的 Web 应用程序，运行在 Linux 系统上，旨在解决 Spring Boot 服务更新时的短暂中断问题。通过管理两个实例（A 和 B）的切换，利用 Nginx 进行流量控制，实现无缝更新。核心功能包括：管理员登录、执行 Shell 脚本、动态编写 Nginx 配置文件、监控实例状态 via URL 轮询，以及提供管理界面用于配置和监控。项目使用 MySQL 存储配置数据，前端采用 Vue3 + TypeScript + Vite + Ant Design Vue，后端使用 Node.js。

#### 核心业务场景
假设实例 A 正在运行服务，管理员需要更新程序：
1. 启动实例 B（使用新 Jar 包）。
2. AutoSwitch 检测到实例 B 上线（通过轮询 URL），并确认其为最新实例。
3. AutoSwitch 等待 5 秒（确保实例 B 稳定），然后自动覆盖写入 Nginx 配置文件，并执行 Shell 脚本重载 Nginx，将流量从实例 A 切换到实例 B。
4. 管理员在界面上看到切换成功提示后，手动关闭实例 A。

整个过程中，服务中断时间极短，用户几乎无感知。

#### 用户使用示例
1. **登录管理**  
   - 管理员打开 AutoSwitch Web 界面，输入用户名和密码登录。  
   - 系统验证凭证后，跳转到综合看板页面。  
   - 示例：管理员使用默认账户 `admin` 登录，密码在首次部署时设置。

2. **项目组配置**  
   - 在“项目组配置”页面，管理员可以添加或编辑项目组，每个项目组代表一个 Spring Boot 服务（如“用户服务”）。  
   - 配置内容包括：实例 A 和 B 的标识、端口号、健康检查 URL（用于轮询）、Nginx 配置模板路径等。  
   - 示例：管理员创建项目组“OrderService”，设置实例 A 的 URL 为 `http://localhost:8080/health`，实例 B 的 URL 为 `http://localhost:8081/health`，并指定 Nginx 配置模板。

3. **Shell 脚本管理**  
   - 在“Shell 脚本管理”页面，管理员可以上传或编辑 Shell 脚本，这些脚本用于执行 Nginx 重载等操作。  
   - 系统会记录脚本的路径和参数，便于在切换时调用。  
   - 示例：管理员上传脚本 `reload_nginx.sh`，内容为 `nginx -s reload`，并测试脚本是否可在 Linux 上正常运行。

4. **Nginx 配置文件管理**  
   - 在“Nginx 配置管理”页面，管理员可以编写或导入 Nginx 配置模板，使用变量（如 `{{instance_url}}`）动态替换实例地址。  
   - 当触发切换时，AutoSwitch 会根据当前活跃实例覆盖写入配置文件。  
   - 示例：管理员定义配置模板，设置 `upstream` 指向实例 B 的地址，然后保存模板。在切换时，系统自动将模板渲染为实际配置并写入文件。

5. **轮询 URL 管理**  
   - 在“轮询 URL 管理”页面，管理员可以为每个项目组设置健康检查 URL，并配置轮询间隔（如每 3 秒一次）。  
   - AutoSwitch 会持续轮询这些 URL，根据响应状态和延迟判断哪个实例是活跃的。  
   - 示例：系统轮询实例 A 和 B 的 `/health` 端点，如果实例 B 响应成功且延迟较低，则标记实例 B 为“最新”。

6. **综合看板**  
   - 在“综合看板”页面，管理员可以查看所有项目组的状态：实例 A 和 B 的在线状态、最后轮询时间、Nginx 当前流量指向。  
   - 看板提供手动触发切换的按钮，用于测试或紧急情况。  
   - 示例：管理员看到实例 B 状态变为“在线”，点击“切换流量”按钮，系统自动执行配置写入和脚本重载，完成后看板显示“流量已切换至实例 B”。

#### 功能模块详细描述
- **登录功能**：基于会话的简单认证，管理员账户存储在 MySQL 中。密码加密存储，支持登出。
- **项目组配置**：管理项目组的基本信息，包括实例细节和关联的 Nginx 配置。数据库表存储项目组数据。
- **Shell 脚本管理**：存储脚本路径和内容，后端使用 Node.js 的 `child_process` 模块执行脚本，确保在 Linux 上运行。
- **Nginx 配置文件管理**：提供编辑器界面用于编写配置模板，后端使用文件系统模块动态生成和覆盖配置文件。
- **轮询 URL 管理**：后端定时任务（如使用 `node-cron`）轮询配置的 URL，根据 HTTP 状态码和响应时间判断实例健康状态，结果存储到数据库。
- **综合看板**：聚合所有数据，显示实例状态和切换历史，支持手动操作切换。使用 WebSocket 或定时轮询实现实时更新。

#### 技术实现逻辑
- **后端（Node.js）**：
  - 使用 Express 框架构建 RESTful API。
  - 数据库使用 MySQL，通过 Sequelize 或类似 ORM 管理数据。
  - 文件操作：使用 `fs` 模块读写 Nginx 配置文件。
  - 脚本执行：使用 `child_process.exec` 运行 Shell 脚本，处理错误和输出。
  - 轮询逻辑：设置定时器，发送 HTTP 请求到实例 URL，记录响应时间和状态。
  - 认证：使用会话中间件（如 `express-session`）管理登录状态。

- **前端（Vue3 + TypeScript）**：
  - 使用 Vite 作为构建工具，Ant Design Vue 提供 UI 组件。
  - 页面包括：登录页、项目组配置页、脚本管理页、配置管理页、轮询 URL 管理页、综合看板。
  - 通过 Axios 调用后端 API，实时显示数据。
  - 看板使用图表或表格展示实例状态，支持手动触发操作。

- **部署与集成**：
  - AutoSwitch 本身作为服务运行在 Linux 上，需要访问 Nginx 配置目录和执行脚本的权限。
  - 确保 Node.js 和 MySQL 环境已配置，前端构建后由 Node.js 服务托管或单独部署。

#### 注意事项
- 安全性：Shell 脚本执行和文件写入需谨慎，避免任意代码执行。建议限制管理员权限。
- 错误处理：轮询失败或脚本执行失败时，应有日志记录和界面提示。
- 最小化实现：优先实现核心切换流程，其他功能如历史记录或高级监控可后续迭代。