admin/Xboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(api): 新增节点墙状态检测闭环

Browse Source 
新增父节点墙状态检测任务、结果上报与节点列表状态装饰，
支持子节点继承父节点检测结果并通过 WS/REST 双链路执行

管理端补充墙状态筛选、搜索、单行与批量检测入口，
同时更新知识库归档并新增后续自动上线方案包
This commit is contained in:
yinjianm
2026-04-27 23:45:44 +08:00
parent b3a8d504d1
commit 9af9dd0df7
23 changed files with 1365 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.helloagents/archive/2026-04/202604272325_node-gfw-check/proposal.md
+223
View File
@@ -0,0 +1,223 @@
# 变更提案: node-gfw-check
## 元信息
```yaml
类型: 新功能
方案类型: implementation
优先级: P1
状态: 已选方案
创建: 2026-04-27
```
---
## 1. 需求
### 背景
节点管理页目前无法判断节点公网 IP 是否疑似被中国防火墙拦截。用户确认墙是双向影响，但当前暂时没有墙内探测 IP，因此第一阶段只让节点服务器主动 ping 国内三网目标，参考 `E:\code\shell\shell-script\network-tools\test_delay.sh` 的检测思路，不复用其中 Telegram 通知与自动安装依赖逻辑。
### 目标
- 在 Xboard 管理端支持对父节点发起墙状态检测，并在节点列表中显示检测结果。
- 子节点默认不单独检测，展示与筛选继承父节点最新墙状态，并标记为随父节点。
- 节点端 `E:\code\go\mi-node` 支持接收检测任务、执行国内三网 ping、结构化上报结果。
- 搜索与筛选支持区分被墙、正常、异常、未检测、随父节点。
### 约束条件
```yaml
时间约束: 本轮落地基础闭环，不等待后续墙内检测 IP。
性能约束: 检测任务低频触发，节点端并发 ping 要设置超时与并发上限，避免阻塞主服务循环。
兼容性约束: 现有节点同步、用户同步、设备同步、REST fallback 不可回归；旧节点端未支持 gfw.check 时管理端应保留 pending/failed 可见状态。
业务约束: 只对父节点创建实际检测任务；子节点继承父节点结果，不作为独立检测目标。
安全约束: 不引入 Telegram token/chat_id；不在生产节点自动安装系统依赖；不执行破坏性命令。
```
### 验收标准
- [ ] 管理端节点列表可以发起单个/批量墙状态检测，子节点不会被独立下发检测。
- [ ] `getNodes` 返回 `gfw_check` 字段；子节点返回父节点结果并带 `inherited=true` 与 `source_node_id`。
- [ ] mi-node 收到 `gfw.check` WS 事件后执行检测并上报；WS 不可用时可通过 REST 任务接口兜底。
- [ ] 前端节点旁显示墙状态标签，筛选和搜索可过滤被墙/正常/异常/未检测/随父节点。
- [ ] PHP 语法检查、前端 build、mi-node Go 测试通过或明确记录无法执行原因。
---
## 2. 方案
### 技术方案
采用已确认的方案 A：`WS 触发 + REST 兜底 + 子节点继承父节点状态`。
- 后端新增 `server_gfw_checks` 表与 `ServerGfwCheck` 模型，记录每次父节点检测任务、状态、摘要、原始结果和错误。
- 后端新增 `ServerGfwCheckService`，负责发起检测、过滤子节点、推送 `gfw.check`、提供 REST 兜底任务读取、接收节点端报告、计算最终状态。
- 管理端新增 `POST /server/manage/checkGfw`，支持单个/批量节点 ID。输入中子节点不下发任务，按父节点继承规则返回 skipped/inherited。
- 节点端新增 `GET /server/gfw/task` 与 `POST /server/gfw/report`，由 `ServerV2` 鉴权保护。
- mi-node 新增 `internal/gfwcheck` 包，内置三网目标，使用系统 `ping` 并发检测。Docker runtime 安装 `iputils`。
- 前端新增墙状态类型、筛选器、标签和动作入口。关键词搜索覆盖中文状态词。
### 影响范围
```yaml
涉及模块:
- Xboard 后端: 新表、新模型、新服务、管理端接口、节点端接口、节点列表返回字段、WS 推送事件。
- admin-frontend: 节点页筛选、搜索、状态标签、单行/批量检测动作、API 类型。
- mi-node: WS 事件解析、控制面事件转发、服务层检测执行、REST 兜底轮询与上报、Docker 运行依赖。
预计变更文件: 20 个左右，覆盖 PHP、Vue/TypeScript、Go、Dockerfile 与方案包。
```
### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| 部分节点环境没有 `ping` 或缺 ICMP 权限 | 中 | 节点端检测失败时上报 `failed` 与错误；Docker 镜像补 `iputils`，不自动安装依赖 |
| 国内目标临时不可达导致误判 | 中 | 按运营商分组统计，区分 `blocked` 与 `partial`，保存 raw_result 供人工核对 |
| 旧 mi-node 不支持新事件 | 中 | 后端保留 REST task 与 checking/pending 状态，前端清楚显示未完成/失败 |
| 子节点继承状态造成误解 | 低 | `gfw_check.inherited=true`，前端显示“随父节点”并在 tooltip 中说明来源 |
| 检测任务阻塞主服务循环 | 中 | mi-node 在 goroutine 中执行，服务层避免同一 check 并发重复执行 |
### 方案取舍
```yaml
唯一方案理由: WS 触发能让在线节点立即执行检测，REST 兜底能覆盖 WS 不可用或旧链路；只检测父节点符合当前子节点中转落地到父节点的业务模型。
放弃的替代路径:
- 只用管理端远程 ping 节点: 无法判断节点主动访问国内目标是否被墙，且与用户确认的双向墙逻辑不匹配。
- 立即引入墙内探测节点: 当前没有墙内检测 IP，无法落地；后续可在同一数据模型中扩展为双向检测。
- 子节点逐个检测: 子节点一般是中转入口，实际落地到父节点；逐个检测会制造噪音并增加不必要任务。
回滚边界: 可回滚新增接口、服务、前端入口和 mi-node 事件处理；数据库新增表独立，不改动 v2_server 结构。
```
---
## 3. 技术设计
### 架构设计
```mermaid
flowchart TD
A[Admin NodesView] -->|POST checkGfw| B[ManageController]
B --> C[ServerGfwCheckService]
C --> D[(server_gfw_checks)]
C -->|gfw.check| E[NodeSyncService / WS]
C -->|pending task| F[GET /server/gfw/task]
E --> G[mi-node service]
F --> G
G --> H[internal/gfwcheck ping runner]
H -->|structured result| I[POST /server/gfw/report]
I --> C
C --> D
A -->|fetchNodes| J[getNodes + latest gfw_check]
```
### API 设计
#### POST `/api/v2/{secure_path}/server/manage/checkGfw`
- **请求**: `{ "ids": [1, 2, 3] }`
- **响应**: `{ "started": [...], "skipped": [...], "total": 3 }`
#### GET `/api/v2/server/gfw/task`
- **请求**: `token/node_id` 鉴权参数
- **响应**: `{ "data": { "check_id": 123, "targets": {...}, "ping_count": 2, "timeout_seconds": 2, "parallel": 12 } }` 或 `null`
#### POST `/api/v2/server/gfw/report`
- **请求**: `{ "check_id": 123, "status": "normal|blocked|partial|failed", "summary": {...}, "raw_result": {...}, "error_message": null }`
- **响应**: `{ "data": true }`
### 数据模型
| 字段 | 类型 | 说明 |
|------|------|------|
| id | big integer | 检测记录 ID |
| server_id | big integer | 父节点 ID |
| status | string | pending/checking/normal/blocked/partial/failed/skipped |
| triggered_by | unsigned big integer nullable | 发起检测的管理员 ID |
| summary | json nullable | 后端/前端摘要 |
| operator_summary | json nullable | 三网聚合结果 |
| raw_result | json nullable | 节点端原始结构化结果 |
| error_message | text nullable | 失败原因 |
| checked_at | unsigned integer nullable | 完成检测时间戳 |
| timestamps | timestamps | 创建/更新时间 |
---
## 4. 核心场景
### 场景: 管理员检测父节点
**模块**: Xboard 后端 + admin-frontend
**条件**: 管理员在节点列表选择父节点，点击检测墙状态。
**行为**: 后端创建 checking 记录并推送 `gfw.check`，前端刷新显示“检测中”。
**结果**: mi-node 上报后节点旁显示正常/疑似被墙/部分异常/检测失败。
### 场景: 管理员选择子节点
**模块**: Xboard 后端 + admin-frontend
**条件**: 管理员选择子节点发起检测。
**行为**: 后端不对该子节点创建独立任务，返回 skipped/inherited。
**结果**: 前端提示子节点随父节点，列表显示父节点检测结果来源。
### 场景: WS 不可用
**模块**: Xboard 后端 + mi-node
**条件**: 节点端没有收到 `gfw.check` WS 事件。
**行为**: mi-node 定期查询 `/server/gfw/task` 获取未完成任务。
**结果**: 任务仍可被执行并上报。
---
## 5. 技术决策
### node-gfw-check#D001: 使用 WS 触发 + REST 兜底
**日期**: 2026-04-27
**状态**: ✅采纳
**背景**: 管理端需要尽快触发在线节点检测，但不能依赖 WS 一定可用。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: WS 触发 + REST 兜底 | 在线响应快，离线/断连可兜底，符合现有节点同步架构 | 需要同时改两条链路 |
| B: 仅 REST 轮询 | 实现较少，行为稳定 | 检测响应慢，用户点击后等待不确定 |
| C: 仅 WS | 响应最快 | WS 不可用时任务丢失 |
**决策**: 选择方案 A。
**理由**: 与现有 `NodeSyncService`、`NodeWorker`、mi-node 控制面抽象兼容，兼顾及时性与可靠性。
**影响**: 后端新增任务接口与推送事件；mi-node 新增 WS 事件和 REST 轮询。
### node-gfw-check#D002: 子节点继承父节点墙状态
**日期**: 2026-04-27
**状态**: ✅采纳
**背景**: 用户明确说明子节点通常作为中转，实际落地到父节点。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: 子节点继承父节点 | 符合业务模型，减少噪音 | 需要 UI 明确说明来源 |
| B: 子节点也独立检测 | 看似更完整 | 结果不代表真实落地路径，任务成本高 |
**决策**: 选择方案 A。
**理由**: 检测目标应代表落地 IP，父节点更接近真实出口。
**影响**: 后端 `getNodes` 拼接继承状态；前端筛选按有效状态处理。
---
## 6. 验证策略
```yaml
verifyMode: review-first
reviewerFocus:
- app/Services/ServerGfwCheckService.php 的状态判定和子节点过滤
- app/Http/Controllers/V2/Server/ServerController.php 的节点端报告鉴权与 check_id 归属校验
- E:/code/go/mi-node/internal/gfwcheck 的 ping 超时、并发和错误处理
testerFocus:
- php -l 新增/修改 PHP 文件
- cd admin-frontend && npm run build
- cd E:/code/go/mi-node && go test ./...
uiValidation: required
riskBoundary:
- 不执行数据库迁移到生产库
- 不复用参考脚本中的 Telegram token/chat_id
- 不自动安装节点系统依赖
```
---
## 7. 成果设计
### 设计方向
- **美学基调**: Apple 式后台精致极简，延续当前节点页黑色 hero 与白色工作台，不新增抢眼装饰色。
- **记忆点**: 节点名旁新增一个轻量“连通性信号”状态胶囊，正常、检测中、疑似被墙、随父节点可以一眼区分但不压过节点名。
- **参考**: `apple/DESIGN.md` 与现有 `NodesView.vue`。
### 视觉要素
- **配色**: 继续使用页面黑白主节奏；交互强调使用 Apple Blue `#0071e3`；风险态沿用 Element Plus 语义色，避免新增复杂色盘。
- **字体**: 继承项目现有字体栈与 Element Plus 表格字号，节点状态使用较小胶囊标签保持信息密度。
- **布局**: 筛选栏增加“墙状态”下拉；节点单元格内在在线状态下方并列墙状态标签，不新增大面积卡片。
- **动效**: 检测中使用按钮 loading 与标签文案反馈，不加额外动画。
- **氛围**: 维持白色工作台与细分隔的管理后台质感，不使用渐变、纹理或装饰背景。
### 技术约束
- **可访问性**: 状态不只靠颜色区分，标签文本必须明确；操作按钮 loading/disabled 状态可见。
- **响应式**: 复用现有 toolbar wrap；新增筛选宽度与现有 select 一致，移动端自然换行。
.helloagents/archive/2026-04/202604272325_node-gfw-check/tasks.md
+135
View File
@@ -0,0 +1,135 @@
# 任务清单: node-gfw-check
> **@status:** completed | 2026-04-27 23:40
```yaml
@feature: node-gfw-check
@created: 2026-04-27
@status: completed
@mode: R2
```
## LIVE_STATUS
```json
{"status":"completed","completed":15,"failed":0,"pending":0,"total":15,"percent":100,"current":"实现与验证完成，准备归档方案包","updated_at":"2026-04-27 23:58:00"}
```
## 进度概览
| 完成 | 失败 | 跳过 | 总数 |
|------|------|------|------|
| 15 | 0 | 0 | 15 |
---
## 任务列表
### 1. Xboard 后端数据与服务
- [√] 1.1 新增 `database/migrations/*_create_server_gfw_checks_table.php`
- 预期变更: 创建 `server_gfw_checks` 表，保存父节点检测任务、状态、摘要、原始结果、错误和完成时间。
- 完成标准: migration 结构完整，down 可删除表，索引覆盖 `server_id/status/created_at` 查询。
- 验证方式: `php -l database/migrations/*_create_server_gfw_checks_table.php`（当前环境无 PHP CLI，已做代码审查）
- depends_on: []
- [√] 1.2 新增 `app/Models/ServerGfwCheck.php` 并扩展 `app/Models/Server.php`
- 预期变更: 增加检测记录模型、JSON casts、状态常量、`Server::gfwChecks()` 关系。
- 完成标准: 模型可被服务层创建、查询、更新，PHP 语法通过。
- 验证方式: `php -l app/Models/ServerGfwCheck.php app/Models/Server.php`（当前环境无 PHP CLI，已做代码审查）
- depends_on: [1.1]
- [√] 1.3 新增 `app/Services/ServerGfwCheckService.php`
- 预期变更: 实现 `startChecks`、`getPendingTaskForNode`、`reportResult`、`decorateServers`、状态判定与子节点继承。
- 完成标准: 父节点下发任务；子节点返回 skipped/inherited；报告 check_id 必须归属当前节点。
- 验证方式: `php -l app/Services/ServerGfwCheckService.php`（当前环境无 PHP CLI，已做代码审查）
- depends_on: [1.2]
### 2. Xboard 后端接口与 WS
- [√] 2.1 修改 `app/Http/Controllers/V2/Admin/Server/ManageController.php` 与 `app/Http/Routes/V2/AdminRoute.php`
- 预期变更: `getNodes` 附加 `gfw_check`；新增 `checkGfw` 管理接口。
- 完成标准: 管理端可以按 ids 发起检测，响应包含 started/skipped/total。
- 验证方式: `php -l app/Http/Controllers/V2/Admin/Server/ManageController.php app/Http/Routes/V2/AdminRoute.php`（当前环境无 PHP CLI，已做代码审查）
- depends_on: [1.3]
- [√] 2.2 修改 `app/Http/Controllers/V2/Server/ServerController.php` 与 `app/Http/Routes/V2/ServerRoute.php`
- 预期变更: 新增 `gfwTask` 和 `gfwReport` 节点端接口。
- 完成标准: 通过 `server.v2` 鉴权读取节点；节点只能领取/上报自己的父节点检测任务。
- 验证方式: `php -l app/Http/Controllers/V2/Server/ServerController.php app/Http/Routes/V2/ServerRoute.php`（当前环境无 PHP CLI，已做代码审查）
- depends_on: [1.3]
- [√] 2.3 修改 `app/WebSocket/NodeWorker.php` 或相关事件处理
- 预期变更: 确保 `gfw.check` 作为 panel->node 推送事件能经现有 Redis/NodeRegistry 发送到节点端。
- 完成标准: 不影响现有 `sync.*` 和 `report.devices` 事件。
- 验证方式: 代码审查确认现有 Redis/NodeRegistry 已支持任意 panel->node event，无需修改 `NodeWorker.php`
- depends_on: [2.1]
### 3. admin-frontend 节点管理 UI
- [√] 3.1 修改 `admin-frontend/src/types/api.d.ts` 与 `admin-frontend/src/api/admin.ts`
- 预期变更: 增加 `AdminNodeGfwCheck`、`AdminNodeGfwStatus`、`checkNodeGfw` API。
- 完成标准: TypeScript 类型覆盖节点列表字段和检测接口响应。
- 验证方式: `cd admin-frontend && npm run build`
- depends_on: [2.1]
- [√] 3.2 修改 `admin-frontend/src/utils/nodes.ts`
- 预期变更: 增加墙状态 meta、tooltip、状态筛选类型，搜索文本包含被墙/正常/异常/未检测/随父节点。
- 完成标准: `filterNodes` 可按墙状态过滤，关键词可命中墙状态中文词。
- 验证方式: `cd admin-frontend && npm run build`
- depends_on: [3.1]
- [√] 3.3 修改 `admin-frontend/src/views/nodes/NodesView.vue`
- 预期变更: 增加墙状态筛选、节点旁状态标签、单行检测、批量检测与 loading 状态。
- 完成标准: 父节点可检测；子节点操作提示随父节点；UI 保持现有节点页风格。
- 验证方式: `cd admin-frontend && npm run build`
- depends_on: [3.2]
### 4. mi-node 检测执行与上报
- [√] 4.1 新增 `E:/code/go/mi-node/internal/gfwcheck`
- 预期变更: 实现三网目标定义、并发 ping runner、结果汇总与状态判定。
- 完成标准: 不依赖 shell 脚本，不包含 Telegram/自动安装逻辑；超时和并发可控。
- 验证方式: `cd E:/code/go/mi-node && go test ./internal/gfwcheck`
- depends_on: []
- [√] 4.2 修改 `E:/code/go/mi-node/internal/panel` 与 `E:/code/go/mi-node/internal/controlplane`
- 预期变更: 支持 `gfw.check` WS 事件、REST 获取任务、上报检测结果。
- 完成标准: 事件可转为 service 层事件；REST payload 自动携带 token/node_id。
- 验证方式: `cd E:/code/go/mi-node && go test ./internal/panel ./internal/controlplane`
- depends_on: [4.1]
- [√] 4.3 修改 `E:/code/go/mi-node/internal/service/service.go` 与 `E:/code/go/mi-node/internal/config/config.go`
- 预期变更: 服务层处理 WS 检测事件，增加低频 REST 兜底轮询，避免重复执行同一 check。
- 完成标准: 检测在后台执行，不阻塞主 select 循环；支持配置默认轮询间隔。
- 验证方式: `cd E:/code/go/mi-node && go test ./internal/service ./internal/config`
- depends_on: [4.2]
- [√] 4.4 修改 `E:/code/go/mi-node/Dockerfile`
- 预期变更: runtime 镜像安装 `iputils` 以提供 `ping`。
- 完成标准: 不新增无关依赖，不改变入口。
- 验证方式: 文件审查
- depends_on: [4.1]
### 5. 验证与知识库同步
- [√] 5.1 执行端到端验证命令
- 预期变更: 运行 PHP 语法检查、前端 build、mi-node Go 测试，记录结果。
- 完成标准: 可执行验证通过；不可执行项记录原因与残余风险。
- 验证方式: `php -l ...`、`cd admin-frontend && npm run build`、`cd E:/code/go/mi-node && go test ./...`
- depends_on: [1.1,1.2,1.3,2.1,2.2,2.3,3.1,3.2,3.3,4.1,4.2,4.3,4.4]
- [√] 5.2 更新 `.helloagents/CHANGELOG.md` 与方案包状态
- 预期变更: 记录本次新增墙状态检测闭环，更新任务状态、LIVE_STATUS 和执行日志。
- 完成标准: CHANGELOG 与 tasks.md 反映实际完成内容和验证结果。
- 验证方式: 文件审查
- depends_on: [5.1]
---
## 执行日志
| 时间 | 任务 | 状态 | 备注 |
|------|------|------|------|
| 2026-04-27 23:25 | DESIGN | in_progress | 创建方案包并固化方案 A |
| 2026-04-27 23:42 | backend/frontend/mi-node | completed | 完成后端接口、前端节点页、mi-node 检测与上报链路 |
| 2026-04-27 23:50 | verification | completed | `npm run build` 通过，`go test ./...` 通过；PHP CLI 不在 PATH |
| 2026-04-27 23:55 | knowledge | completed | 更新 CHANGELOG 与模块知识库 |
---
## 执行备注
- 当前没有墙内检测 IP，本轮只做节点主动 ping 国内三网目标。
- 子节点默认不独立检测，显示和筛选继承父节点墙状态。
- 参考脚本中的 Telegram 通知和自动安装依赖不进入项目实现。
.helloagents/archive/_index.md
+2
View File
@@ -7,6 +7,7 @@
| 时间戳 | 名称 | 类型 | 涉及模块 | 决策 | 结果 |
|--------|------|------|---------|------|------|
| 202604272325 | node-gfw-check | implementation | node-gfw-check,admin-frontend,mi-node | node-gfw-check#D001,#D002 | ✅完成 |
| 202604272310 | ticket-chat-image-dnd-paste-upload | implementation | admin-frontend | ticket-chat-image-dnd-paste-upload#D001 | ✅完成 |
| 202604250018 | admin-frontend-user-activity-status-filter | implementation | admin-frontend,backend | admin-frontend-user-activity-status-filter#D001,#D002,#D003 | ✅完成 |
| 202604250002 | order-payment-snapshot | implementation | admin-frontend,order-payment | order-payment-snapshot#D001,#D002 | ✅完成 |
@@ -37,6 +38,7 @@
## 按月归档
### 2026-04
- [202604272325_node-gfw-check](./2026-04/202604272325_node-gfw-check/) - 新增节点墙状态检测闭环，支持父节点检测、子节点继承、管理端展示筛选，以及 mi-node WS/REST 检测上报
- [202604272310_ticket-chat-image-dnd-paste-upload](./2026-04/202604272310_ticket-chat-image-dnd-paste-upload/) - 为工单工作台回复区补齐图片拖拽上传与剪贴板粘贴上传，并将上传逻辑与样式从超大 SFC 中拆分
- [202604250018_admin-frontend-user-activity-status-filter](./2026-04/202604250018_admin-frontend-user-activity-status-filter/) - 为用户管理高级筛选新增“活跃状态”条件，并在后端补齐 `activity_status` 复合过滤规则，支持按活跃 / 非活跃筛选用户
- [202604250002_order-payment-snapshot](./2026-04/202604250002_order-payment-snapshot/) - 补齐订单支付成功快照保存链路，并在后台订单详情中集中展示支付渠道、支付方法、平台订单号、商户订单号、实付金额与支付 IP