getDomain/docs/20_domainCheck_临时海外控制面联调清单.md

# domainCheck 临时海外控制面联调清单

适用场景：

- 暂时不使用正式海外机器
- 先把大陆 `controller + worker` 对接到当前测试海外机
- 先跑通“控制面 + 同步 + 观测”全链路，再切回正式海外环境

当前临时海外控制面：

- 节点编码：`overseas-control-01`
- 节点角色：`overseas / control`
- 机器 IP：`152.53.37.118`
- 后台地址：`http://152.53.37.118/`
- API 基址：`http://152.53.37.118:8100`

## 1. 当前目标拓扑

本次联调按下面的角色分工：

- 大陆 controller
  - 承担 API 控制面
  - 承担 Sync Agent
  - 可以兼跑本机 Worker
- 大陆 worker
  - 只承担检测执行
- 临时海外控制面
  - 只承担 API 控制与同步接收
  - 不承载本机 Worker
  - 不承载 Sync Agent

## 2. 临时海外控制面应有状态

在临时海外控制面机器上执行：

```bash
bash domain-api/deploy/multi-region/check_temp_overseas_control.sh
```

预期：

- `domaincheck-api` 为 `active (running)`
- `domaincheck-worker` 为 `inactive (dead)` 或禁用
- `runtime.status.data.node`
  - `code=overseas-control-01`
  - `region=overseas`
  - `role=control`
- `runtime.status.data.worker.expected_on_this_node=false`
- `runtime.status.data.sync_agent.expected_on_this_node=false`
- `runtime.status.data.detect.phase_label=当前节点不承载`

## 3. 大陆 controller 切到临时海外控制面

在大陆 controller 上执行：

```bash
sed -i 's#^SYNC_TARGET_API_BASE_URL=.*#SYNC_TARGET_API_BASE_URL=http://152.53.37.118:8100#' /etc/default/domaincheck-api
sed -i 's/^SYNC_PUSH_ENABLED=.*/SYNC_PUSH_ENABLED=true/' /etc/default/domaincheck-api

systemctl restart domaincheck-api
systemctl restart domaincheck-sync-agent
systemctl restart domaincheck-worker
sleep 3
```

然后检查：

```bash
curl -s http://127.0.0.1:8100/api/v1/runtime/readiness
echo
curl -s http://127.0.0.1:8100/api/v1/runtime/sync-summary
```

预期：

- `runtime/readiness` 至少不是大陆本机配置错误导致的 `blocking`
- `runtime/sync-summary.data.enabled=true`
- `runtime/sync-summary.data.target_api_base_url=http://152.53.37.118:8100`

## 4. 大陆 worker 检查项

在大陆 worker 上执行：

```bash
bash domain-api/deploy/multi-region/check_mainland_worker.sh
```

预期：

- `NODE_CODE=mainland-worker-01`
- `NODE_REGION=mainland`
- `NODE_ROLE=worker`
- `domaincheck-worker` 为 `active (running)`

如果大陆 controller 也兼跑检测，再执行：

```bash
systemctl status domaincheck-worker --no-pager -l
echo
curl -s http://127.0.0.1:8100/api/v1/runtime/status
```

预期：

- `worker.running=true`
- `worker.expected_on_this_node=true`

## 5. 最短联调命令

### 5.1 在大陆 controller 上

```bash
bash domain-api/deploy/multi-region/check_temp_link.sh http://127.0.0.1:8100 http://152.53.37.118:8100
```

关注点：

- `push_sync` 返回 `code=0` 或幂等成功
- 不再出现目标地址为空
- 不再出现 `SYNC_PUSH_ENABLED=false`

关注点：

- `cluster` 中至少能看到：
  - `overseas-control-01`
  - 大陆 `mainland-controller-01`
  - 大陆 `mainland-worker-01`
- `sync-summary` 中能看到来自大陆的接收记录
- `readiness` 不再是“完全单节点海外态”

## 6. 后台页面应如何理解

打开：

- `http://152.53.37.118/`

在运行中心里看到下面这些内容时，属于正常：

- `本机 Worker：当前节点不承载`
- `Sync Agent：当前节点不承载`
- `当前检测阶段：当前节点不承载`
- `代理运行态：不适用`

这不是故障，而是因为当前节点就是临时海外控制面。

真正应该关注的是：

- `集群节点`
- `有效执行节点`
- `同步状态`
- `多机就绪度`

## 7. 判断“到底有几台 Worker 在工作”

如果页面上“在线 Worker 数”和“实际正在跑检测的节点数”看起来不一致，以数据库为准。

在大陆 controller 上执行：

```bash
bash domain-api/deploy/multi-region/check_worker_participation.sh
```

判断规则：

- `detect_worker_nodes`
  - 看谁在线
  - 看谁是 `worker_online=true`
  - `detect_participating=true` 只能说明它曾被判断为“正在参与”
- `detect_job_items`
  - 看任务到底被哪台节点 `claimed_by`
  - 这才是“当前真正干活的节点”
- `runtime/status`
  - 看 `participation_summary.dispatch_active_nodes`
    - 这是“当前真正执行/领任务的节点”
  - 看 `participation_summary.non_participating_nodes`
    - 这是“在线但未参与的节点”
  - 看 `non_participating_nodes[].participation_state`
    - `standby` 表示在线待命
    - `load_syncing` 表示负载待确认，不要直接算成“正在干活”
  - 看 `log_sync`
    - 能直接确认远端日志回传是否开启、是关键还是全量、样本来自哪些节点

## 8. 常见误判

### 8.1 海外控制面显示“本机 Worker 不承载”

这是正常，不是故障。

### 8.2 页面显示“在线 Worker 1”，但你部署了 2 台大陆机器

先区分：

- “有效执行节点”是可承担任务的在线节点数
- “当前参与检测节点”是当前真的在领任务、跑任务的节点
- “在线但未参与节点”是已经在线、可承接任务，但当前这轮还没分到任务的节点

如果 controller 没兼跑检测，通常只会看到独立 worker 在真正执行。

### 8.3 controller 机器也开了 worker 服务，但没有领任务

这不一定是 bug，可能只是当前调度没有分到它。应以 `detect_job_items.claimed_by` 为准，不要只看服务在线。

### 8.4 页面显示“负载待确认”

这不是新的故障状态，而是为了避免误判：

- 节点已经上报 `busy` 或有 `current_load`
- 但当前还没看到明确的 `items_claimed / items_running / processed_recent`

通常是心跳和任务快照还没完全对齐。先等下一轮刷新，再结合 `claimed_by` 和 `participation_summary` 判断，不要立刻当作“这台机器已经在跑检测”。

### 8.5 日志控制台看不到大陆节点过程

先看 `runtime/status` 或页面里的“远端日志回传”：

- 若 `enabled=false`
  - 说明本来就没开回传
- 若 `enabled=true` 但 `line_count=0`
  - 说明开关已开，但当前还没有远端样本
- 若 `source_nodes` 里没有目标大陆节点
  - 说明该节点这轮还没回传日志，先看它是否真的在参与检测

## 9. 联调完成后的回滚

如果你后续要切回正式海外机器，在大陆 controller 上把目标地址改回正式值即可：

```bash
sed -i 's#^SYNC_TARGET_API_BASE_URL=.*#SYNC_TARGET_API_BASE_URL=http://正式海外控制面IP:8100#' /etc/default/domaincheck-api
systemctl restart domaincheck-api
systemctl restart domaincheck-sync-agent
sleep 3
```

如果临时海外控制面不再使用，可在该机器上保留 `domaincheck-api` 供后续调试，也可以停掉：

```bash
systemctl stop domaincheck-api
```

## 10. 本次临时海外控制面结论

当前这台测试海外机已经整理为：

- 纯 `overseas-control`
- API 正常
- Worker 不承载
- Sync Agent 不承载
- 数据已清空并按首装态初始化
- 可直接作为大陆 controller 的临时同步接收端

## 11. 配套脚本

- 临时海外控制面自检：
  - `domain-api/deploy/multi-region/check_temp_overseas_control.sh`
- 大陆 controller -> 临时海外控制面联调检查：
  - `domain-api/deploy/multi-region/check_temp_link.sh`
- 三机拓扑总览检查：
  - `domain-api/deploy/multi-region/check_temp_topology.sh`
- 当前活跃任务由谁真正执行：
  - `domain-api/deploy/multi-region/check_worker_participation.sh`
- 大陆 worker 本机自检：
  - `domain-api/deploy/multi-region/check_mainland_worker.sh`