getDomain/docs/项目当前运行流程说明.md

# 项目当前运行流程说明

> 说明：这份文档主要回答“项目现在怎么跑”。当前线上执行基线、观察顺序和是否继续调参，统一以 [当前线上最终Runbook.md](/www/wwwroot/getDomain/docs/当前线上最终Runbook.md) 为准。

更新时间：`2026-04-24`

## 这份文档是干什么的

这不是一份“理想设计稿”，而是按项目现在的真实跑法整理出来的说明。

目标只有一个：让人用人话看明白，这个项目现在到底怎么跑，任务从哪里来，谁在执行，结果又是怎么回来的。

## 先用一句话讲明白

这套系统现在不是“点一下开始，然后一台机器自己跑完”。

它现在的实际跑法是：

海外控制面先挑出要检测的域名，打成一批任务，然后把这批任务交给大陆节点；大陆节点把任务拉下来后，由 worker 一步一步去跑检测；跑出来的结果，再同步回海外控制面，最后由页面统一展示。

## 先认识 5 个角色

### 1. 海外控制面

可以把它理解成“总调度台”。

它主要负责：

- 创建检测任务
- 给大陆节点派动作
- 接收大陆回传的运行状态和检测结果
- 在页面上展示当前进度

当前本机 `overseas-control-01` 就是这个角色。

它本机一般不直接跑检测。

### 2. 大陆控制节点

可以把它理解成“大陆现场调度员”。

它主要负责：

- 去海外把待检测批次拉下来
- 启动大陆这边的 sync-agent、worker
- 把大陆现场的运行情况回传出去

### 3. 大陆 worker 节点

这才是真正“干活”的机器。

它负责：

- 领取待执行任务
- 开线程跑检测
- 把每一步的结果写回本地

### 4. sync-agent

它就是“搬运工”。

负责在海外和大陆之间搬 3 类东西：

- 待检测任务批次
- 当前运行状态
- 检测结果

### 5. node-agent

它就是“远程执行员”。

它会在节点上定时来领控制命令，然后执行，比如：

- 启动 worker
- 开始检测
- 拉取任务
- 重启服务

## 当前现场快照

下面这段，是按 `2026-04-24 01:44 - 01:45` 左右控制面看到的实时数据整理的。

- 当前控制面节点是 `overseas-control-01`
- 角色是 `overseas / control`
- 本机 API 在线
- 本机 worker 不承担实际检测

当时控制面看到的活动任务是：

- `job_id = 208`
- `job_code = sync-overseas-1430`
- 状态是 `running`
- 这一批一共 `5000` 个任务项
- 其中 `4435` 个已经被领取
- `575` 个正在执行

当时控制面汇总看到的执行规模大致是：

- 约 `28` 个参与节点
- 约 `28` 个检测进程
- 约 `575` 个活跃线程

当时积压里最大头还是“注册状态检测”：

- `detect_register` 待处理约 `8235`
- 后续步骤待处理约 `1243`

同一时间段里，系统的 readiness 仍然提示：

- 大陆节点心跳并不稳定
- 还有结果批次待推送

这说明了一件很关键的事：

不是完全没跑，而是“链路在跑，但跑得不稳”。所以现在的主矛盾，确实还是稳定性，不是单纯把线程数继续往上调。

## 整个项目现在是怎么跑的

下面按真实流程，一步一步讲。

### 第 1 步：海外控制面先挑出“需要再检测”的域名

简单理解就是：

- 还没检测过的
- 之前检测失败过的
- 或者状态需要重新确认的

这些域名会先被挑出来，形成一份“待处理名单”。

这时候只是“选名单”，还没有真正开始跑检测。

### 第 2 步：海外控制面创建一轮检测任务

系统会先创建一条“本轮任务”记录。

然后把这批域名拆成很多个“任务项”。

这里要特别注意：

它不是一次就给某个域名下发“整套检测”。

它做的是：

- 先判断这个域名下一步该做什么
- 只给它安排“下一步”

所以这个系统现在跑的是“分步骤推进”，不是“单个域名一次性从头跑到尾”。

### 第 3 步：海外控制面自己不跑，而是把动作派到大陆

当你在页面上点“开始检测”后，海外控制面会去排队发送几类动作给大陆节点：

- 让大陆启动 sync-agent
- 让大陆去拉取待检测批次
- 让大陆启动 worker
- 让大陆开始执行检测

这些动作不是直接 ssh 过去硬敲命令。

而是先进入远程动作队列，再由大陆节点上的 node-agent 定时来领。

所以你可以把它理解成：

海外控制面负责“发指令”，大陆节点负责“取指令并执行”。

### 第 4 步：大陆控制节点先把任务批次拉下来

大陆控制节点会去海外控制面拿一批待检测域名。

拿到以后，会做几件事：

- 把这批域名落到大陆本地库里
- 在大陆本地创建一条对应的 job
- 给每个域名生成“下一步要做什么”的任务项
- 再回头告诉海外：这批任务我已经收到了

这个“确认收到”很重要。

因为如果不确认，海外会以为这批任务还没被接走，后面就可能重复下发。

另外，大陆控制节点不会无脑一直拉新任务。

如果它发现本地已经堆了很多待处理任务，它会先停一下，不再继续拉新批次，避免越堆越多。

### 第 5 步：worker 启动后，先做准备，不会立刻开跑

worker 真正开始检测前，会先做一轮准备动作。

大致包括：

- 重新读取最新配置
- 重新读取线程数和进程数
- 重新加载 cookies
- 刷新代理池
- 回收上次异常退出留下来的遗留任务

所以你看到“worker 已经启动”，并不等于“已经开始稳定出结果”。

它中间还有一个准备阶段。

### 第 6 步：worker 真正领的，是任务队列里的“下一步”

worker 现在不是直接扫整张域名表。

它主要是从任务队列里领取待执行任务。

领取后的状态大致可以这样理解：

- `pending`：还没被谁接手
- `claimed`：已经被某个节点领走了
- `running`：已经开始跑了
- `completed / failed / blacklisted`：这一小步跑完了

也就是说，系统现在盯的不是“这个域名整体做完没”，而是“这个域名现在跑到哪一步了”。

### 第 7 步：一个域名不是一次跑完，而是一小步一小步推进

当前默认的主流程顺序，大致是：

1. 注册状态检测
2. 百度 site 检测
3. 360 site 检测
4. 站长之家检测
5. 爱站检测
6. 时光机检测

有些来源的域名，会跳过注册状态这一步，直接从后面的步骤开始。

所以你不能把它理解成“所有域名一定都从第一步开始”。

更准确地说，是系统会先判断这个域名“现在最该补哪一步”。

### 第 8 步：流程顺序，和 worker 实际优先领什么，不完全一样

这个地方很容易误会，所以单独说一下。

流程顺序上，域名一般是先过前面的关，再去后面的关。

但 worker 实际领任务时，会优先照顾已经走到后面的域名。

为什么要这样做？

因为如果完全按最前面的步骤一直领，后面的域名会永远被堵住，怎么都跑不到尾部。

所以现在的真实策略更像是：

- 流程上按顺序推进
- 调度上优先让已经走到后面的域名尽快跑完

这也是为什么你现在会看到“注册状态检测积压很大”，但后面的步骤也还在继续跑。

### 第 9 步：每一步跑完后，系统会决定下一步怎么走

某一步做完后，系统不会简单地只记一个“成功 / 失败”。

它还会决定后面怎么走。

大致有几种情况：

- 这一步通过了：给这个域名创建“下一步”的任务项
- 这一步命中黑名单：后面的步骤就不再继续
- 这一步属于外部站点异常、超时、代理问题：可能会重试，也可能降级，也可能转成人工复核
- 这一步明确不通过：流程在这里终止

所以这个项目现在不是“跑完就完”，而是“每走完一步，再决定下一步”。

### 第 10 步：结果先写回大陆本地

worker 跑完某一步后，会先把结果写回大陆本地。

写回去的内容包括：

- 这一个任务项是什么结果
- 这个域名当前是什么状态
- 这一步的详细信息
- 是否需要人工复核

所以大陆本地库，先是“第一落点”。

### 第 11 步：大陆再把结果和运行状态同步回海外

大陆这边不是只回传“最终结果”。

它还会把两类信息往海外送：

- 当前运行状态
- 最近有哪些域名开始了、完成了、失败了、进黑名单了

然后海外控制面收到后，再去更新自己的展示和汇总。

这也是为什么页面上看到的数字，不是某一台机器的原始数字。

它其实是“控制面汇总后的结果”。

### 第 12 步：海外页面最后展示出来的，是一份汇总快照

所以现在页面上的数据，本质上是几部分拼起来的：

- 控制面自己知道的任务信息
- 大陆回传的运行状态
- 大陆回传的结果事件
- 当前 job 的统计汇总

这就会带来一个现实情况：

如果大陆心跳断一下，或者结果同步晚一点，页面看起来就会突然不稳定，甚至和现场有一点时间差。

这不一定代表 worker 完全没跑。

很多时候，只是“页面依赖的回传链路断了一下”。

## 你可以把现在的项目理解成两条并行链

### 第一条：任务执行链

海外选域名 -> 建任务 -> 大陆拉批次 -> worker 领任务 -> 按步骤推进 -> 写结果

### 第二条：运行状态和结果同步链

大陆上报运行状态 -> 大陆回推结果事件 -> 海外接收并汇总 -> 页面刷新展示

这两条链只要有一条不稳，使用感受就会变差。

如果任务执行链慢，你会感觉“没速度”。

如果同步链不稳，你会感觉“页面不准、看不清到底跑没跑”。

## 为什么你会一直觉得“没有速度、没有效率”

因为现在影响体验的，不只是“worker 够不够快”。

这套系统至少要同时经过下面这些环节：

- 海外选任务
- 海外派动作
- 大陆领动作
- 大陆拉批次
- worker 领任务
- 外部站点检测
- 结果回传
- 页面汇总展示

任何一段不稳，最后给人的感觉都会像是“整套系统没跑起来”。

所以从当前现场来看，先把主链路稳定跑顺，仍然比继续往上冲性能更重要。

## 如果你只想用最简单的方法判断现在卡在哪

可以按下面这个顺序看：

1. 先看有没有新的活动 job
   - 没有的话，说明卡在“任务还没真正建起来”

2. 再看大陆有没有把任务批次收下
   - 没收下的话，说明卡在“海外发过去了，但大陆没接住”

3. 再看 `claimed` 和 `running` 有没有开始增长
   - 不增长的话，说明 worker 没真正开始领任务

4. 再看 `completed / failed / blacklisted` 有没有开始变化
   - 长时间不变的话，说明任务虽然在跑，但结果没持续产出

5. 最后看海外页面有没有跟着更新
   - 大陆明明在跑，海外不更新，通常就是“结果同步链”有问题

## 最后只记住 4 句话就够了

1. 现在这套项目是“海外控制，大陆执行”，不是单机直跑。
2. 一个域名不是一次跑完，而是按步骤一小步一小步推进。
3. 页面看到的是汇总快照，不是某台机器的原始现场数字。
4. 当前最大的矛盾仍然是链路稳定，不是单纯把性能参数继续调大。

继续看完了，当前是稳推进，不是又卡死。

现在现场是：
- `idx_detect_job_items_release_node_job` 还没转 `valid=1`
- 但已经稳定在 `index validation: scanning table`
- 最新进度到：
  - `229991 / 6197384`
- `watch` 这条后台链是活的，而且一直在连续记进度：
  - `18:09:51 -> 126725`
  - `18:10:52 -> 169564`
  - `18:11:52 -> 210067`
  - `18:12:22 -> 227856`

另外两点也正常：
- `876` 现在还显示 `running`
- worker 已经全恢复：
  - `base=active`
  - `templated=199`
  - `node_agent=active`

一句话说：
**现在已经从“卡住”切成“后台验证扫描中”，而且进度在稳定往前走。**

下一步最合理的动作不是再人工乱动，而是继续让它扫；一旦索引转成 `valid=1`，`codex-job876-tail-watch.service` 就会自动接着去释放 `876` 的尾项。



发布 sync_push_service.py
重启 domaincheck-sync-agent.service
验证：
detect_result_projection push 是否恢复
detect_result_ingest 是否出现