[feat] rainbox

2026-04-06 08:54:29 +08:00
parent 9b61ce3b61
commit 4bb9455b36
10 changed files with 346 additions and 62 deletions
@@ -7,6 +7,10 @@ const sidebarAuto: SidebarAutoItem[] = [
    text: 'Kinesin',
    path: '/kinesin',
  },
+  {
+    text: 'Rainbox',
+    path: '/rainbox',
+  },
  {
    text: 'Columba',
    path: '/columba',
@@ -1,20 +1,18 @@
 ---
 outline: deep
-order: 4
+order: 1
+heading: 开发
+sub-order: 4
 ---

-# 与我们一起
+# 模块详解

 个人的力量总是有限的，Columba 仍有许多可以改进之处。如果您有任何建议、想法或遇到了问题，欢迎在 [GitHub 仓库](https://github.com/gtxykn0504/columba) 中提出 Issue 或通过 Pull Request 贡献代码。

-
-
-## 模块详解
-
 > [!TIP]
 > 实在写不动了，这一部分由AI编写，本人审核了下。如果有问题，欢迎反馈，感激不尽

-### 常量定义
+## 常量定义

 ```python
 CONFIG_FILE = "config.ini"
@@ -24,9 +22,7 @@ ICON_FILE = "columba.ico"

 - 定义配置文件名、日志文件名、图标文件名。程序运行时从当前目录读取这些文件。

---
-
-### 日志配置
+## 日志配置

 ```python
 handler = RotatingFileHandler(LOG_FILE, maxBytes=3*1024*1024, backupCount=0, encoding='utf-8')
@@ -45,9 +41,7 @@ log = logging.info
 - 同时输出到控制台（`StreamHandler`），方便调试。
 - `log` 简写为 `logging.info` 的引用，用于记录日志。

---
-
-### 工具函数 `show_error`
+## 工具函数 `show_error`

 ```python
 def show_error(msg):
@@ -58,11 +52,9 @@ def show_error(msg):
 - `0x10` 对应 `MB_ICONERROR`，显示错误图标。
 - 用于提权失败、启动错误等场景，给用户明确提示。

---
+## 权限检查与提权

-### 权限检查与提权
-
-####  is_admin
+###  is_admin

 ```python
 def is_admin():
@@ -75,7 +67,7 @@ def is_admin():
 - 调用 `Shell32.IsUserAnAdmin` 判断当前进程是否以管理员身份运行。
 - 异常时返回 `False`（如未找到函数）。

-#### run_as_admin
+### run_as_admin

 ```python
 def run_as_admin():
@@ -112,11 +104,9 @@ def run_as_admin():
  - 其他值表示失败，显示包含错误码的提示框（异常时错误码显示“未知”）。
 - **注意**：调用后当前进程立即退出（`sys.exit(0)`），新进程以管理员身份运行。

---
+## 配置管理

-### 配置管理
-
-#### check_config
+### check_config

 ```python
 def check_config():
@@ -127,7 +117,7 @@ def check_config():

 - 检查配置文件是否存在，不存在则记录日志并退出程序。

-#### load_config
+### load_config

 ```python
 def load_config():
@@ -151,7 +141,7 @@ def load_config():

 ---

-### 登录类型描述 `get_logon_type_desc`
+## 登录类型描述 `get_logon_type_desc`

 ```python
 def get_logon_type_desc(logon_type):
@@ -172,9 +162,8 @@ def get_logon_type_desc(logon_type):
 - 将数字登录类型代码转换为可读的中文描述（带英文原文）。
 - 若代码不在映射表中，返回“未知类型 (代码)”。

---

-### 邮件发送 `send_mail`
+## 邮件发送 `send_mail`

 ```python
 def send_mail(smtp_cfg, msg_cfg, event_data, test=False):
@@ -231,11 +220,10 @@ def send_mail(smtp_cfg, msg_cfg, event_data, test=False):
  - 否则直接使用 `SMTP_SSL` 建立 SSL 连接（通常用于 465 端口）。
 - **异常处理**：任何发送失败均记录日志并返回 `False`，不影响主流程。

---

-### `LoginMonitor` 类（安全日志监听）
+## `LoginMonitor` 类（安全日志监听）

-#### __ init __
+### __ init __

 ```python
 def __init__(self, callback, allowed_logon_types):
@@ -250,7 +238,7 @@ def __init__(self, callback, allowed_logon_types):
 - `processed`：字典，键为事件记录号，用于去重。限制大小 1000，自动清理。
 - `allowed_logon_types`：允许的登录类型集合。

-#### _parse_logon_type
+### _parse_logon_type

 ```python
 def _parse_logon_type(self, strings, index):
@@ -271,7 +259,7 @@ def _parse_logon_type(self, strings, index):
 - 如果该索引不存在或不是数字，则遍历整个字符串列表，找到第一个纯数字项作为登录类型（兼容某些旧系统）。
 - 返回整数或 `None`。

-#### _parse_event
+### _parse_event

 ```python
 def _parse_event(self, event):
@@ -285,7 +273,7 @@ def _parse_event(self, event):
  - 4625：用户名 5，域 6，状态码 7，子状态 9，登录类型索引 10，源 IP 19。
 - 返回包含所有所需字段的字典，若解析失败返回 `None`。

-#### run
+### run

 ```python
 def run(self):
@@ -334,7 +322,7 @@ def run(self):
  - 若无异常，休眠 2 秒后继续；若异常，休眠 5 秒后重试。
 - **退出**：`CoUninitialize` 释放 COM。

-#### stop
+### stop

 ```python
 def stop(self):
@@ -345,9 +333,9 @@ def stop(self):

 ---

-### `TrayApp` 类（托盘应用）
+## `TrayApp` 类（托盘应用）

-#### __ init __
+### __ init __

 ```python
 def __init__(self):
@@ -358,7 +346,7 @@ def __init__(self):

 - 加载配置，初始化实例变量。

-#### send_notification
+### send_notification

 ```python
 def send_notification(self, data):
@@ -367,7 +355,7 @@ def send_notification(self, data):

 - 事件回调函数，调用邮件发送。

-#### test_mail
+### test_mail

 ```python
 def test_mail(self):
@@ -377,7 +365,7 @@ def test_mail(self):

 - 发送测试邮件，不依赖事件数据。

-#### edit_config
+### edit_config

 ```python
 def edit_config(self):
@@ -395,7 +383,7 @@ def edit_config(self):
 - 用记事本打开 `config.ini`，通过 `CREATE_NO_WINDOW` 避免控制台窗口。
 - 重新加载配置，并更新监控线程的允许类型（如果监控已启动）。

-#### view_log
+### view_log

 ```python
 def view_log(self):
@@ -408,7 +396,7 @@ def view_log(self):

 - 用记事本打开日志文件，同样避免控制台窗口。

-#### on_quit
+### on_quit

 ```python
 def on_quit(self, icon):
@@ -421,7 +409,7 @@ def on_quit(self, icon):

 - 停止监控线程，关闭托盘图标，强制退出进程（`os._exit` 确保立即终止）。

-#### run
+### run

 ```python
 def run(self):
@@ -453,9 +441,7 @@ def run(self):
 - 检查图标文件是否存在，加载失败则退出。
 - 构建托盘菜单，创建托盘图标并进入消息循环（`icon.run()` 阻塞，直到调用 `icon.stop()`）。

---
-
-### `main` 函数
+## `main` 函数

 ```python
 def main():
@@ -479,9 +465,8 @@ def main():
 - 若已管理员运行，创建 `TrayApp` 实例并运行。
 - 捕获所有未处理异常，记录日志并暂停，方便调试。

---

-### 入口
+## 入口

 ```python
 if __name__ == "__main__":
@@ -491,18 +476,4 @@ if __name__ == "__main__":
 - 程序入口，调用 `main`。


-## 依赖与安装

-### 开发环境依赖
-
-```bash
-pip install pywin32 pystray pillow
-```
-
-### 打包（Nuitka）
-
-可使用以下命令生成独立可执行文件：
-
-```bash
-nuitka --standalone --windows-console-mode=disable --windows-uac-admin --include-data-files=config.ini=./config.ini --include-data-files=login_notifier.log=./login_notifier.log --include-data-files=columba.ico=./columba.ico --windows-icon-from-ico=columba.ico 1.py
-```
@@ -0,0 +1,34 @@
+---
+outline: deep
+order: 2
+---
+
+# 依赖与打包
+
+## 开发环境依赖
+
+```bash
+pip install pywin32 pystray pillow
+```
+
+## 打包（Nuitka）
+
+可使用以下命令生成独立可执行文件：
+
+```bash
+nuitka --standalone --windows-console-mode=disable --windows-uac-admin --include-data-files=config.ini=./config.ini --include-data-files=login_notifier.log=./login_notifier.log --include-data-files=columba.ico=./columba.ico --windows-icon-from-ico=columba.ico 1.py
+```
+
+## 制作安装包（Inno Setup）
+
+[Inno Setup](https://jrsoftware.org/isinfo.php)是一个非常好用的安装包制作软件。本软件由于需要管理员权限，直接打包会出现「要求的操作需要提升的权限」的错误消息，您可以参考一下步骤编辑iss脚本配置权限：
+
+1. 在 Inno Setup 的 Script 的 [Setup] 中加上：`PrivilegesRequired=admin`
+
+2. 在 [Run] 所有的 Flags 都加上：`runascurrentuser`，例如：
+
+```
+[Run]
+Filename: "{app}\{#MyAppExeName}"; Description: "{cm:LaunchProgram,{#StringChange(MyAppName, '&', '&&')}}"; Flags: nowait postinstall skipifsilent runascurrentuser
+
+```
@@ -5,7 +5,7 @@ order: 1

 # 何为Columba

-Columba 是一款专为 Windows 设计的轻量级登录监控工具，它能够实时捕获系统的安全登录事件（成功与失败），并通过邮件即时通知您。无论是托管在公网的 Windows Server，还是家中的个人电脑，Columba 作为“信使”，都能帮助您及时掌握异常登录行为，守护系统安全。
+Columba 是一款专为 Windows 设计的轻量级登录监控工具，它能够实时捕获系统的安全登录事件，并通过邮件即时通知您。无论是托管在公网的 Windows Server，还是家中的个人电脑，Columba 作为“信使”，都能帮助您及时掌握异常登录行为，守护系统安全。

 ## 功能
 1. 实时监控：监听 Windows 安全日志中的登录事件（事件 ID 4624 成功、4625 失败），支持过滤指定的登录类型（如远程桌面、交互式登录等）。
@@ -0,0 +1,96 @@
+---
+outline: deep
+order: 4
+---
+
+# 开发
+
+## 配置文件
+API Key 保存在 `C:\Users\[user]\.rain\config.json` 中，配置文件格式示例：
+```json
+{
+  "api_key": "xxxxxxxxxx",
+  "servers": [
+    { "id": "123456", "name": "my-server" },
+    { "id": "789012", "name": "production" }
+  ]
+}
+```
+
+## 开发环境依赖
+
+```cmd
+pip install requests
+```
+
+## 打包
+
+```cmd
+nuitka --standalone --windows-console-mode=force --include-package=charset_normalizer --output-filename=rain.exe --windows-icon-from-ico=ico.ico 1.py
+```
+
+## 安装包
+[Inno Setup](https://jrsoftware.org/isinfo.php)是一个非常好用的安装包制作软件。您可以参考一下步骤编辑iss脚本为安装包添加"添加到用户环境变量 PATH"选项：
+
+1. 在`[Setup]`中，添加`gesEnvironment=yes`
+2. 在`[Tasks]`中，添加选项
+```
+Name: "addtopath"; Description: "添加到用户环境变量 PATH"; GroupDescription: "其他任务:"; Flags: unchecked
+```
+
+3. 在任意位置添加以下脚本
+```
+[Registry]
+; 仅当用户勾选 addtopath 且路径不存在时才添加
+Root: HKCU; Subkey: "Environment"; ValueType: expandsz; ValueName: "Path"; \
+    ValueData: "{olddata};{app}"; Check: NeedsAddPath(ExpandConstant('{app}')); \
+    Tasks: addtopath
+
+[Code]
+const
+  EnvironmentKey = 'Environment';
+
+// 检查路径是否已存在于 PATH 中
+function NeedsAddPath(Param: string): boolean;
+var
+  OrigPath: string;
+begin
+  if not RegQueryStringValue(HKEY_CURRENT_USER, EnvironmentKey, 'Path', OrigPath) then
+  begin
+    Result := True;
+    exit;
+  end;
+  // 前后加分号判断，避免误匹配
+  Result := Pos(';' + Param + ';', ';' + OrigPath + ';') = 0;
+end;
+
+// 从 PATH 中移除指定路径（卸载时调用，幂等操作）
+procedure RemovePath(Path: string);
+var
+  Paths: string;
+  P: Integer;
+begin
+  if not RegQueryStringValue(HKEY_CURRENT_USER, EnvironmentKey, 'Path', Paths) then
+    exit;
+  // 确保路径前后有分号进行匹配
+  P := Pos(';' + Path + ';', ';' + Paths + ';');
+  if P = 0 then exit;
+  if P > 1 then P := P - 1;
+  Delete(Paths, P, Length(Path) + 1);
+  // 清理首尾可能残留的分号
+  while (Length(Paths) > 0) and (Paths[1] = ';') do Delete(Paths, 1, 1);
+  while (Length(Paths) > 0) and (Paths[Length(Paths)] = ';') do Delete(Paths, Length(Paths), 1);
+  // 如果 PATH 变为空字符串，则删除该值；否则写入新值
+  if Paths = '' then
+    RegDeleteValue(HKEY_CURRENT_USER, EnvironmentKey, 'Path')
+  else
+    RegWriteStringValue(HKEY_CURRENT_USER, EnvironmentKey, 'Path', Paths);
+end;
+
+// 卸载时自动清理 PATH
+procedure CurUninstallStepChanged(CurUninstallStep: TUninstallStep);
+begin
+  if CurUninstallStep = usUninstall then
+    RemovePath(ExpandConstant('{app}'));
+end;
+```
@@ -0,0 +1,32 @@
+---
+outline: deep
+order: 3
+---
+
+# 错误提示
+
+## 输入格式错误
+| 错误信息 | 触发条件 |
+|---------|----------|
+| `错误：缺少子命令` | `rain key` 无参数；`rain server` 无子命令 |
+| `错误: 缺少服务器 ID` | `rain server add` 后未提供 ID |
+| `错误: 缺少服务器标识` | `rain server remove` 后未提供标识符 |
+| `错误: 缺少服务器` | `rain start`、`rain stop`、`rain reboot` 或 `rain <服务器>` 无参数 |
+
+## 配置相关错误
+| 错误信息 | 触发条件 |
+|---------|----------|
+| `错误: 服务器 ID 不能为空` | `add_server` 收到空 ID |
+| `错误: 服务器 ID {id} 已存在` | 添加重复 ID |
+| `错误: 服务器名称 {name} 已存在` | 添加重复名称 |
+| `错误: 未找到服务器 '{identifier}'` | 操作指定了不存在的服务器 |
+| `错误:未配置服务器` | `rain server list` 或 `rain status` 无服务器时 |
+| `错误:未设置 API Key` | 执行需要 API 的操作但未配置 key|
+
+## 网络与 API 错误
+| 错误信息 | 触发条件 |
+|---------|----------|
+| `错误: requests 库不存在` | 未安装 requests |
+| `请求失败: {code}` | API 返回其他非 2xx 状态码 |
+| `错误: 获取服务器状态失败` | `get_server_status` `display_server_status` 返回 None toggle 命令中获取状态失败 |
+| `错误: 当前状态为 '{status}'，无法互换（仅支持 running/stopped）` | toggle 时服务器状态不是 running 或 stopped |
@@ -0,0 +1,15 @@
+---
+outline: deep
+order: 5
+---
+# HTML版本
+
+> 实际上，HTML版本才是Rainbox的最初版本
+
+如果对您而言，安装软件来使用Rainbox太复杂了，您还可以使用HTML版本，您可按照以下步骤来配置：
+
+1. 打开[Github仓库](https://github.com/gtxykn0504/rainbox)，下载`rainbox.html`文件
+
+2. 打开页面，点击系统配置，输入API密钥与服务器ID，点击保存
+
+3. 查看并检查是否正常运行
@@ -0,0 +1,20 @@
+---
+outline: deep
+order: 1
+---
+
+# 雨云的盒子
+
+Rainbox 是一款轻量、高效的命令行工具，专为雨云RCS 云服务器产品设计，让您无需登录网页，即可在终端中快速完成服务器的日常管理操作。
+
+1. 一键开关机 – 快速启动、停止或重启您的 RCS 实例
+
+2. 状态监控 – 实时查看服务器运行状态、IP 地址、CPU 及内存使用率
+
+3. 智能切换 – 输入服务器标识即可自动判断当前状态，执行开机或关机（toggle）
+
+4. 多服务器管理 – 支持添加、删除、列表展示多个服务器，并可为每个服务器设置易记的名称
+
+5. 交互式 Shell – 双击运行 rain.exe 直接进入 rain> 提示符，支持 help 查看帮助，exit 退出，方便日常快速操作
+
+6. 命令行兼容 – 所有功能均支持在 CMD、PowerShell 或终端中直接调用，适合集成到脚本或自动化任务中
@@ -0,0 +1,112 @@
+---
+outline: deep
+order: 2
+---
+
+# 两种模式
+
+Rainbox支持通过交互式 Shell 或者 命令行使用，但在使用前，请您先完成初始化。
+
+
+## 安装
+
+1. 下载 [Github Repo中的安装包](https://github.com/gtxykn0504/rainbox)。
+2. 运行安装程序，按照提示完成安装。
+3. **可选**：勾选“添加到用户环境变量 PATH”，安装完成后可在任意命令行窗口直接使用 `rain` 命令。
+
+::: danger 重要提示
+使用命令行窗口输入命令时，务必带有`rain`，而在交互模式（双击打开）无需。
+:::
+
+4. 安装完成后，可选择立即启动 Rainbox（进入交互模式）。
+
+## 初始化
+
+### 获取 API Key
+1. 登录 [雨云控制台](https://www.rainyun.com/)。
+2. 进入 **API 密钥管理** 页面，点击“创建 API Key”，复制生成的密钥。
+
+### 设置 API Key
+```cmd
+(rain) key xxxxxxxxxxxxxx
+```
+成功后会显示 `✓ API Key 已保存`。
+
+
+## 添加服务器
+
+### 获取服务器 ID
+1. 登录雨云控制台，进入 **RCS 云服务器** 产品页面。
+2. 每个服务器都有一个数字 ID（例如 `123456`）。
+
+### 添加服务器
+```cmd
+(rain) server add 123456 my-server
+```
+- `123456`：服务器 ID
+- `my-server`：自定义名称
+
+### 查看已添加的服务器
+```cmd
+(rain) server list
+```
+
+### 删除服务器
+```cmd
+(rain) server remove my-server
+```
+可使用 ID 或名称删除。
+
+
+## 常用操作
+
+### 查看服务器状态
+- **查看单个服务器**：
+  ```cmd
+  (rain) status my-server
+  ```
+- **查看所有已配置服务器**：
+  ```cmd
+  (rain) status
+  ```
+
+
+### 启动服务器
+```cmd
+(rain) start my-server
+```
+
+### 停止服务器
+```cmd
+(rain) stop my-server
+```
+
+### 重启服务器
+```cmd
+(rain) reboot my-server
+```
+
+### 智能切换（Toggle）
+根据服务器当前状态自动执行开机或关机：
+- 若服务器 **运行中** → 执行关机
+- 若服务器 **已停止** → 执行开机
+- 其他状态（如启动中、错误等）会提示无法切换
+
+```cmd
+(rain) my-server
+```
+
+
+## 命令
+| 输入 | 作用 |
+|------|------|
+| `(rain) help` | 显示帮助信息 |
+| `(rain) key <KEY>` | 设置 API Key |
+| `(rain) server add <ID> [名称]` | 添加服务器 |
+| `(rain) server remove <服务器>` | 删除服务器 |
+| `(rain) server list` | 列出所有服务器 |
+| `(rain) status [服务器]` | 查看状态（未指定服务器则显示所有服务器状态） |
+| `(rain) start <服务器>` | 开机 |
+| `(rain) stop <服务器>` | 关机 |
+| `(rain) reboot <服务器>` | 重启 |
+| `<服务器>` | 智能切换（toggle） |
@@ -1,5 +1,5 @@
 # Kedocs

-1. Build Command：npm run docs:build
+1. Build Command：npm run build
 2. Output Directory：.vitepress/dist
 3. Install Command：npm install