fix(api): 修复自动墙检父节点筛选与启用语义

统一自动墙检查询逻辑，兼容 parent_id 为 null 或 0 的父节点将 gfw_check_enabled 的空值视为开启，避免页面显示已启用却未入队同时调整管理端自动墙检统计仅计算父节点并更新 CI 配置以忽略 .helloagents 变更触发后端发布
2026-04-28 14:53:19 +08:00
parent 4c66d1fbe0
commit a62a124710
18 changed files with 506 additions and 13 deletions
@@ -3,6 +3,7 @@
 | 模块名 | 说明 | 最近更新 |
 |--------|------|----------|
 | [admin-frontend](admin-frontend.md) | 管理端前端登录、布局、仪表盘、用户管理、节点管理与管理 API 封装 | 2026-04-28 |
+| [ci-workflows](ci-workflows.md) | GitHub Actions 镜像发布工作流、路径触发规则与前后端镜像发布边界 | 2026-04-28 |
 | [deploy](deploy.md) | 可复制到服务器的 Xboard Compose 部署模板、环境变量模板和运维脚本 | 2026-04-28 |
 | [node-gfw-check](node-gfw-check.md) | 节点墙状态检测任务、父/子节点继承规则、mi-node 检测上报链路 | 2026-04-28 |
 | [order-payment](order-payment.md) | 订单支付成功快照、第三方回调元信息透传与后台支付成功信息展示 | 2026-04-25 |
@@ -44,7 +44,7 @@
 - 节点列表现支持本地分页、在线 / 离线筛选、父/子节点筛选，以及跨分页稳定勾选；批量修改 / 批量删除仅作用于已勾选节点，其中批量修改可统一更新 `host / group_ids / rate / auto_online`
 - 节点管理页新增“自动上线”托管开关；开启后后台 `sync:server-auto-online` 会按节点在线状态自动同步 `show`，在线 / 待同步时显示、离线时隐藏，未开启的节点仍保持手动显隐控制；疑似被墙或仍处于墙检测自动隐藏状态的节点不会被自动上线重新发布
 - 节点管理页现支持墙状态展示、墙状态筛选与关键词搜索；父节点可通过行级或批量操作发起检测，子节点不单独检测并显示“随父节点”的继承状态
- 节点管理页现支持“墙检测托管”开关、批量设置和刷新数据按钮；父节点开启后参与 `sync:server-gfw-checks` 自动检测，子节点不独立检测但可控制是否随父节点自动隐藏 / 恢复
+- 节点管理页现支持“墙检测托管”开关、批量设置和刷新数据按钮；父节点开启后参与 `sync:server-gfw-checks` 自动检测，自动墙检统计只计算父节点；子节点不独立检测但可控制是否随父节点自动隐藏 / 恢复
 - 节点行级菜单现已补齐“置顶节点”，会复用当前排序结果生成新的顺序 payload 并提交到 `server/manage/sort`
 - 权限组管理页使用真实后端 `server/group/fetch`、`server/group/save` 与 `server/group/drop`，支持关键字搜索、新增/编辑中央弹窗、删除确认，以及从节点数量列跳转到 `#/nodes?group={id}` 的筛选联动
 - 路由管理页使用真实后端 `server/route/fetch`、`server/route/save` 与 `server/route/drop`，支持路由列表、关键词搜索、新增/编辑中央弹窗、删除与动作值展示
@@ -0,0 +1,21 @@
+# ci-workflows
+
+## 职责
+
+- 维护 GitHub Actions 镜像发布工作流的触发边界
+- 区分 Laravel 后端镜像与 `admin-frontend` 独立静态镜像的构建发布链路
+- 记录不参与镜像构建的协作元数据路径，避免无意义触发 Docker 发布任务
+
+## 行为规范
+
+- 后端镜像发布工作流位于 `.github/workflows/docker-publish.yml`，名称为 `Backend Docker Build and Publish`
+- 后端 workflow 在 `master` 和 `new-dev` 分支 push 时触发，并保留 `workflow_dispatch` 手动触发入口
+- 后端 workflow 使用 `paths-ignore` 排除 `admin-frontend/**`、`.helloagents/**` 和 `.github/workflows/admin-frontend-docker-publish.yml`
+- GitHub Actions 的 `paths-ignore` 语义是：push 中所有变更路径都被 ignore 覆盖时跳过 workflow；只要混有未被 ignore 的后端相关路径，后端 workflow 仍会运行
+- 管理端前端镜像发布工作流位于 `.github/workflows/admin-frontend-docker-publish.yml`，只关注 `admin-frontend/**` 和自身 workflow 变更
+
+## 依赖关系
+
+- 依赖 GitHub Actions 的 `paths-ignore` 过滤行为
+- 依赖 GHCR 作为镜像发布目标
+- 依赖 `.helloagents/**` 仅作为知识库、方案包、归档和协作记录，不作为后端镜像构建输入
@@ -9,14 +9,14 @@

 ## 行为规范

- 检测任务只对父节点创建；带 `parent_id` 的子节点不单独下发任务
+- 检测任务只对父节点创建；父节点兼容 `parent_id IS NULL` 与历史 `parent_id=0` 两种表示，带真实父节点 ID 的子节点不单独下发任务
 - 子节点列表展示继承父节点最新 `gfw_check`，并返回 `inherited=true` 与 `source_node_id`
 - `server_gfw_checks.status` 使用 `pending / checking / normal / blocked / partial / failed / skipped`
 - 管理端 `POST server/manage/checkGfw` 接收 `{ ids: number[] }`，响应中区分 `started` 与 `skipped`
- 后端定时命令 `sync:server-gfw-checks` 会自动为 `gfw_check_enabled=1` 的父节点创建检测任务；已有未超时的 `pending/checking` 任务时跳过，超过 5 分钟未领取或未上报的任务会自动标记为 `failed`
+- 后端定时命令 `sync:server-gfw-checks` 会自动为未明确关闭墙检托管的父节点创建检测任务；`gfw_check_enabled=1` 或 `NULL` 均视为开启，只有 `false/0` 视为关闭；已有未超时的 `pending/checking` 任务时跳过，超过 5 分钟未领取或未上报的任务会自动标记为 `failed`
 - Docker all-in-one 镜像通过 supervisor 独立运行 `php artisan schedule:work`；`compose.sample.yaml` 的分进程样例和 `deploy/xboard-server/compose.yaml` 服务器部署模板也包含 `scheduler` 服务，确保 `sync:server-gfw-checks` 和其他 Laravel Scheduler 任务会持续执行
 - 节点端 `GET server/gfw/task` 只向父节点返回待执行任务；节点端 `POST server/gfw/report` 必须校验 `check_id` 归属当前节点
- `v2_server.gfw_check_enabled` 控制节点是否参与自动墙检测与墙状态自动显隐；管理端开启父节点墙检测托管时会立即发起一次检测，后续由定时命令持续检测；子节点不独立检测但可单独关闭随父节点自动隐藏 / 恢复
+- `v2_server.gfw_check_enabled` 控制节点是否参与自动墙检测与墙状态自动显隐；该字段按“未明确关闭即开启”处理，管理端开启父节点墙检测托管时会立即发起一次检测，后续由定时命令持续检测；子节点不独立检测但可单独关闭随父节点自动隐藏 / 恢复
 - `blocked` 结果会自动隐藏仍开启墙检测托管且当前显示中的父节点及其子节点，并设置 `gfw_auto_hidden=1`
 - `normal` 结果只恢复 `gfw_auto_hidden=1` 的节点，避免误恢复管理员手动隐藏的节点；`partial/failed` 只记录状态，不触发自动上线或下线
 - `sync:server-auto-online` 会把最新墙状态 `blocked` 和未恢复的 `gfw_auto_hidden` 作为显示否决条件，防止自动上线重新发布疑似被墙节点