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

feat(api): 新增节点墙检测自动托管与显隐

Browse Source 
新增定时墙检测命令与节点托管字段，自动为开启托管的父
节点创建检测任务，并在 blocked 时自动隐藏节点、normal
时仅恢复由墙检测自动隐藏的节点

更新自动上线服务以尊重 blocked 与自动隐藏状态，避免疑
似被墙节点被重新发布；同时补齐管理端墙检测托管开关、
刷新入口、批量设置与相关测试和知识库同步
This commit is contained in:
yinjianm
2026-04-28 00:51:49 +08:00
parent 73b1696b0a
commit ff50030364
27 changed files with 998 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.helloagents/archive/2026-04/202604280024_node-gfw-auto-check-and-online/.status.json
+10
View File
@@ -0,0 +1,10 @@
{
"status": "completed",
"completed": 8,
"failed": 0,
"pending": 0,
"total": 8,
"percent": 100,
"current": "开发实施完成，准备归档方案包",
"updated_at": "2026-04-28 00:48:00"
}
.helloagents/archive/2026-04/202604280024_node-gfw-auto-check-and-online/proposal.md
+229
View File
@@ -0,0 +1,229 @@
# 变更提案: node-gfw-auto-check-and-online
## 元信息
```yaml
类型: 新功能
方案类型: implementation
优先级: P1
状态: 已确认
创建: 2026-04-28
```
---
## 1. 需求
### 背景
节点墙状态检测已具备手动触发、节点端执行、结果上报和节点列表展示能力，但当前仍需要管理员手动检测。实际运营需要后台自动检测所有父节点，并在节点疑似被中国防火墙拦截时自动隐藏，避免继续发布到用户订阅配置。
### 目标
- 自动为开启托管的父节点创建墙状态检测任务，子节点不单独检测，继续继承父节点状态。
- 节点可单独关闭自动墙检测托管；关闭后不参与自动检测和自动墙状态显隐动作。
- 仅当检测结果为 `blocked` 时自动隐藏节点；恢复 `normal` 时只恢复由墙检测自动隐藏过的节点。
- 自动上线服务必须尊重墙状态：`blocked` 是显示否决条件，防止现有 `auto_online` 把疑似被墙节点重新发布。
- 节点管理页新增刷新数据按钮，并展示/切换墙检测托管状态。
### 约束条件
```yaml
时间约束: 本轮完成后端、前端、测试和知识库同步
性能约束: 自动检测调度不得重复创建 pending/checking 任务，避免对节点端和三网目标造成无意义压力
兼容性约束: 不改变 mi-node 现有 gfw.check 协议；不改变手动检测接口；现有节点默认开启自动墙检测托管
业务约束: show=0 是订阅发布边界；子节点不创建独立检测任务；partial/failed 不触发自动下线
```
### 验收标准
- [ ] 后端存在定时命令，可自动为开启墙检测托管的父节点创建检测任务，并跳过子节点、关闭托管节点和已有待执行任务的节点。
- [ ] `blocked` 上报后节点自动 `show=0`，并记录自动隐藏标记；`normal` 上报后只恢复曾由墙检测自动隐藏的节点。
- [ ] `sync:server-auto-online` 在节点疑似被墙时不会把节点重新显示。
- [ ] 管理端节点列表可刷新数据、可切换节点自动墙检测托管开关，并能通过搜索/筛选继续识别疑似被墙和正常节点。
- [ ] 前端构建通过；PHP 侧至少完成新增测试用例或说明本机 PHP 不可用导致未执行。
---
## 2. 方案
### 技术方案
采用方案 A：复用现有墙检测链路和自动上线链路，新增节点级墙检测托管字段与自动隐藏标记。
- 数据层在 `v2_server` 新增:
- `gfw_check_enabled`: 是否参与自动墙检测和墙状态自动显隐，默认 `true`。
- `gfw_auto_hidden`: 是否由墙检测自动隐藏，默认 `false`，用于避免恢复管理员手动隐藏的节点。
- `gfw_auto_action_at`: 最近一次墙检测自动显隐动作时间。
- `ServerGfwCheckService` 新增自动检测入口:
- 只查询 `parent_id is null` 且 `gfw_check_enabled=1` 的节点。
- 若已有 `pending/checking` 检测任务则跳过。
- 创建任务后沿用 `NodeSyncService::push(..., 'gfw.check', ...)` 和节点端 REST 兜底领取。
- `ServerGfwCheckService::reportResult()` 在写入最终状态后执行自动显隐:
- `blocked`: 对父节点及其子节点中仍开启 `gfw_check_enabled` 的节点设置 `show=0`、`gfw_auto_hidden=1`。
- `normal`: 仅对 `gfw_auto_hidden=1` 的节点恢复 `show=1` 并清理标记。
- `partial/failed`: 只记录状态，不改变 `show`。
- `ServerAutoOnlineService` 同步时把最新继承墙状态为 `blocked` 作为显示否决条件，避免自动上线覆盖墙检测隐藏。
- 管理端节点页在现有 Apple 风格工作台上增量扩展：
- 工具栏新增刷新数据按钮，调用 `loadNodeBoard()`。
- 表格新增“墙检测”托管开关；父节点会自动检测，子节点不独立检测但可单独关闭随父节点自动隐藏/恢复。
- 批量修改弹窗支持统一设置自动墙检测托管。
- 搜索文本补充自动墙检/自动隐藏关键字。
### 影响范围
```yaml
涉及模块:
- Laravel 数据模型: 新增 v2_server 墙检测托管与自动隐藏字段
- node-gfw-check: 新增自动检测调度、自动显隐动作和状态查询辅助
- admin-frontend: 节点列表刷新入口、墙检测托管开关、类型和筛选文案
- 测试: 扩展自动上线与墙检测服务测试
预计变更文件: 12-16
```
### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| 自动恢复显示误覆盖管理员手动隐藏 | 高 | 使用 `gfw_auto_hidden` 标记，只恢复由墙检测自动隐藏的节点 |
| 自动上线重新显示 blocked 节点 | 高 | 在 `ServerAutoOnlineService` 中加入墙状态否决 |
| 自动检测任务堆积 | 中 | 自动调度前跳过已有 `pending/checking` 任务的节点 |
| 子节点行为误解 | 中 | 子节点不检测，但继承父节点状态；自动动作只作用于仍开启托管的子节点 |
| 前端列宽变密 | 低 | 延续现有表格密度，新增窄列和 Tooltip，不重做页面结构 |
### 方案取舍
```yaml
唯一方案理由: 复用现有检测协议和自动上线服务，新增最少字段解决自动检测、自动隐藏、自动恢复和手动隐藏冲突问题。
放弃的替代路径:
- 只在上报时直接改 show: 会被 auto_online 覆盖，也无法区分管理员手动隐藏。
- 新建完整策略中心: 审计与扩展更完整，但本轮范围过大，后续接入墙内检测 IP 时再升级更合适。
回滚边界: 可回滚新增迁移、命令、服务逻辑和前端字段；历史 server_gfw_checks 检测记录不需要删除。
```
---
## 3. 技术设计
### 架构设计
```mermaid
flowchart TD
A[Laravel Scheduler] --> B[sync:server-gfw-checks]
B --> C[ServerGfwCheckService::startAutomaticChecks]
C --> D[server_gfw_checks pending]
C --> E[NodeSyncService gfw.check]
F[mi-node WS/REST] --> G[ping 三网目标]
G --> H[POST /server/gfw/report]
H --> I[ServerGfwCheckService::reportResult]
I --> J{status}
J -->|blocked| K[show=0 + gfw_auto_hidden=1]
J -->|normal| L[恢复 gfw_auto_hidden 节点 show=1]
M[sync:server-auto-online] --> N[blocked 状态否决显示]
```
### API 设计
#### POST `server/manage/update`
- **新增请求字段**: `gfw_check_enabled?: boolean`
- **行为**: 父节点可切换自动墙检测托管；子节点保存字段但不创建独立检测任务。
#### POST `server/manage/batchUpdate`
- **新增请求字段**: `gfw_check_enabled?: boolean`
- **行为**: 支持批量开启/关闭自动墙检测托管。
#### GET `server/manage/getNodes`
- **新增响应字段**:
- `gfw_check_enabled`
- `gfw_auto_hidden`
- `gfw_auto_action_at`
- **保留响应字段**: `gfw_check` 继续承载墙状态、继承来源和检测时间。
### 数据模型
| 字段 | 类型 | 说明 |
|------|------|------|
| `v2_server.gfw_check_enabled` | boolean | 是否参与自动墙检测和墙状态自动显隐 |
| `v2_server.gfw_auto_hidden` | boolean | 是否由墙检测自动隐藏 |
| `v2_server.gfw_auto_action_at` | unsignedInteger nullable | 最近一次墙检测自动显隐动作 Unix 时间 |
---
## 4. 核心场景
### 场景: 自动检测父节点
**模块**: node-gfw-check
**条件**: 父节点 `gfw_check_enabled=1`，且没有 `pending/checking` 检测任务
**行为**: 定时命令创建检测记录并推送 `gfw.check`
**结果**: 节点端通过 WS 或 REST 兜底执行检测并上报结果
### 场景: 疑似被墙自动隐藏
**模块**: node-gfw-check
**条件**: 检测结果判定为 `blocked`
**行为**: 后端将开启墙检测托管的父节点及其子节点 `show=0`，并设置 `gfw_auto_hidden=1`
**结果**: `ServerService::getAvailableServers()` 不再返回这些节点，订阅配置不再发布
### 场景: 恢复正常自动显示
**模块**: node-gfw-check
**条件**: 后续检测结果判定为 `normal`，节点存在 `gfw_auto_hidden=1`
**行为**: 后端恢复 `show=1` 并清理自动隐藏标记
**结果**: 只恢复曾由墙检测自动隐藏的节点，不恢复管理员原本手动隐藏的节点
---
## 5. 技术决策
### node-gfw-auto-check-and-online#D001: 使用自动隐藏标记隔离管理员手动显隐
**日期**: 2026-04-28
**状态**: ✅采纳
**背景**: 自动恢复显示必须避免把管理员手动隐藏的节点误发布。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: 新增 `gfw_auto_hidden` 标记 | 可精确恢复自动隐藏节点，和手动显隐互不覆盖 | 需要新增字段和测试 |
| B: 只根据最新状态直接设置 `show` | 实现少 | 会恢复管理员手动隐藏节点 |
**决策**: 选择方案 A
**理由**: 发布控制属于高影响业务行为，必须可追踪自动动作来源。
**影响**: `v2_server`、`ServerGfwCheckService`、管理端节点列表。
### node-gfw-auto-check-and-online#D002: 自动上线服务必须把 blocked 作为显示否决
**日期**: 2026-04-28
**状态**: ✅采纳
**背景**: 现有 `sync:server-auto-online` 会按在线状态同步 `show`，若不接入墙状态，疑似被墙节点可能被重新显示。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: 在自动上线服务中加入墙状态否决 | 和现有定时链路一致，避免状态互相覆盖 | 需要查询最新墙状态 |
| B: 只依赖检测上报时改 `show` | 改动少 | 后续自动上线可能覆盖 |
**决策**: 选择方案 A
**理由**: 自动上线是当前 `show` 的定时真相源之一，必须在同一服务中纳入墙状态。
**影响**: `ServerAutoOnlineService`、相关单元测试。
---
## 6. 验证策略
```yaml
verifyMode: test-first
reviewerFocus:
- ServerGfwCheckService 自动创建任务、自动显隐、子节点继承边界
- ServerAutoOnlineService 与 blocked 状态的冲突处理
- 管理端字段类型和子节点托管提示
testerFocus:
- tests/Unit/ServerAutoOnlineServiceTest.php
- 新增 tests/Unit/ServerGfwCheckServiceTest.php
- admin-frontend npm run build
uiValidation: optional
riskBoundary:
- 不执行真实生产调度
- 不修改 mi-node 检测协议
- 不删除历史检测记录
```
---
## 7. 成果设计
### 设计方向
- **美学基调**: Apple 风格后台工作台的克制密度；以白色工作台、黑色标题区、Apple Blue 交互强调和语义状态色承载新增控制。
- **记忆点**: 节点行内形成“显隐 / 自动上线 / 墙检测”三段式托管开关，运营人员能快速判断哪个自动机制正在接管发布状态。
- **参考**: `apple/DESIGN.md` 与现有 `NodesView.vue`。
### 视觉要素
- **配色**: 保持 `#000000` Hero、`#ffffff` 工作台、`#0071e3` 交互蓝；blocked 继续使用危险语义色。
- **字体**: 延续项目现有系统字体栈和 Element Plus 字体，不引入远程字体。
- **布局**: 新增窄列表格列和工具栏刷新按钮，不重构页面；移动端沿用现有表格横向滚动能力。
- **动效**: 使用 Element Plus `loading` 状态和 Switch 反馈，不增加额外动效。
- **氛围**: 维持低装饰成本，无渐变、无背景纹理。
### 技术约束
- **可访问性**: 子节点墙检测开关提供继承行为 Tooltip，刷新按钮带图标和文本。
- **响应式**: 工具栏继续换行，新增按钮不固定宽度，避免窄屏溢出。
.helloagents/archive/2026-04/202604280024_node-gfw-auto-check-and-online/tasks.md
+98
View File
@@ -0,0 +1,98 @@
# 任务清单: node-gfw-auto-check-and-online
> **@status:** completed | 2026-04-28 00:41
```yaml
@feature: node-gfw-auto-check-and-online
@created: 2026-04-28
@status: completed
@mode: R2
```
## LIVE_STATUS
```json
{"status":"completed","completed":8,"failed":0,"pending":0,"total":8,"percent":100,"current":"开发实施完成，准备归档方案包","updated_at":"2026-04-28 00:48:00"}
```
## 进度概览
| 完成 | 失败 | 跳过 | 总数 |
|------|------|------|------|
| 8 | 0 | 0 | 8 |
---
## 任务列表
### 1. 后端数据与调度
- [√] 1.1 新增 `database/migrations/*_add_gfw_auto_fields_to_v2_server_table.php`
- 预期变更: 为 `v2_server` 增加 `gfw_check_enabled`、`gfw_auto_hidden`、`gfw_auto_action_at` 字段。
- 完成标准: 迁移包含字段存在性保护和 down 回滚逻辑；默认节点自动墙检测开启。
- 验证方式: 代码审查迁移字段和回滚逻辑。
- depends_on: []
- [√] 1.2 修改 `app/Models/Server.php`、`app/Http/Requests/Admin/ServerSave.php`、`app/Http/Controllers/V2/Admin/Server/ManageController.php`
- 预期变更: 模型 casts、保存、单节点更新和批量更新支持新增字段。
- 完成标准: `getNodes/save/update/batchUpdate` 可读写新增字段，现有字段不回退。
- 验证方式: 代码审查请求校验和 payload 字段。
- depends_on: [1.1]
- [√] 1.3 修改 `app/Services/ServerGfwCheckService.php`
- 预期变更: 新增自动检测批量创建、跳过 active 任务、blocked/normal 自动显隐、blocked 状态查询辅助。
- 完成标准: 自动检测只作用父节点；子节点继承检测结果但不创建任务；partial/failed 不改变 show。
- 验证方式: 单元测试覆盖自动检测、自动隐藏、自动恢复和子节点联动。
- depends_on: [1.2]
- [√] 1.4 新增 `app/Console/Commands/SyncServerGfwChecks.php` 并修改 `app/Console/Kernel.php`
- 预期变更: 新增 `sync:server-gfw-checks` 命令并加入 Laravel Scheduler。
- 完成标准: 命令输出 started/skipped/active 等统计；调度不与现有命令冲突。
- 验证方式: 代码审查命令签名、调度频率和 withoutOverlapping。
- depends_on: [1.3]
- [√] 1.5 修改 `app/Services/ServerAutoOnlineService.php`
- 预期变更: 自动上线同步时把最新 inherited/source 墙状态 `blocked` 作为显示否决条件。
- 完成标准: `auto_online=1` 且在线的 blocked 节点仍保持隐藏；非 blocked 继续按在线状态同步。
- 验证方式: 单元测试覆盖 blocked 不被自动上线重新显示。
- depends_on: [1.3]
### 2. 管理端前端
- [√] 2.1 修改 `admin-frontend/src/types/api.d.ts`、`admin-frontend/src/api/admin.ts`、`admin-frontend/src/utils/nodes.ts`
- 预期变更: 类型、更新 payload、统计和搜索文本支持 `gfw_check_enabled/gfw_auto_hidden/gfw_auto_action_at`。
- 完成标准: TypeScript 可识别新增字段；搜索可命中自动墙检/自动隐藏相关关键词。
- 验证方式: `npm run build`。
- depends_on: [1.2]
- [√] 2.2 修改 `admin-frontend/src/views/nodes/NodesView.vue`、`NodeBatchEditDialog.vue`、节点编辑映射工具
- 预期变更: 新增刷新数据按钮、墙检测托管开关、批量设置入口和编辑保存字段映射。
- 完成标准: 父节点可切换自动墙检测；子节点开关提示只控制随父节点自动隐藏/恢复；刷新按钮显示加载反馈。
- 验证方式: `npm run build` + 代码级 UI 审查。
- depends_on: [2.1]
### 3. 测试与知识库
- [√] 3.1 修改/新增 `tests/Unit/ServerAutoOnlineServiceTest.php`、`tests/Unit/ServerGfwCheckServiceTest.php`
- 预期变更: 覆盖自动墙检测任务创建、blocked 自动隐藏、normal 自动恢复、自动上线 blocked 否决。
- 完成标准: 测试断言自动动作不会误恢复手动隐藏节点。
- 验证方式: 本机可用时运行 PHPUnit；不可用时报告 PHP CLI 缺失。
- depends_on: [1.3, 1.5]
---
## 执行日志
| 时间 | 任务 | 状态 | 备注 |
|------|------|------|------|
| 2026-04-28 00:24 | 方案设计 | in_progress | 已选择方案 A，准备开发实施 |
| 2026-04-28 00:36 | 后端开发 | completed | 已新增自动检测字段、命令、服务联动和测试 |
| 2026-04-28 00:43 | 前端开发 | completed | 已新增刷新按钮、墙检测托管开关和批量设置入口 |
| 2026-04-28 00:48 | 验证 | completed | `npm run build` 通过；PHP/Composer 不在 PATH，PHPUnit 未执行 |
---
## 执行备注
- 用户确认“隐藏”即不发布到订阅配置；当前实现以 `show=0` 为发布边界。
- 子节点不创建自动检测任务，但可继承父节点检测结果；子节点开关只控制是否随父节点自动隐藏/恢复。
- `partial/failed` 不主动恢复由墙检测隐藏的节点；只有 `normal` 结果会恢复 `gfw_auto_hidden=1` 的节点。
.helloagents/archive/_index.md
+2
View File
@@ -7,6 +7,7 @@
| 时间戳 | 名称 | 类型 | 涉及模块 | 决策 | 结果 |
|--------|------|------|---------|------|------|
| 202604280024 | node-gfw-auto-check-and-online | implementation | node-gfw-check,admin-frontend | node-gfw-auto-check-and-online#D001,#D002 | ✅完成 |
| 202604272338 | admin-frontend-node-auto-online | - | - | - | ✅完成 |
| 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 | ✅完成 |
@@ -39,6 +40,7 @@
## 按月归档
### 2026-04
- [202604280024_node-gfw-auto-check-and-online](./2026-04/202604280024_node-gfw-auto-check-and-online/) - 为节点墙状态检测打通自动检测与自动显隐，支持开启托管的父节点定时检测、疑似被墙自动隐藏、恢复正常自动显示，并让自动上线尊重 blocked 状态
- [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` 复合过滤规则，支持按活跃 / 非活跃筛选用户