getDomain/docs/14_domainCheck_正式上线前最终检查单.md

# 14 domainCheck 正式上线前最终检查单

## 一、使用场景

本文档用于正式上线前最后一次收口。

适用前提：

- 代码已更新到最新版本
- Linux 测试服已完成基础联调
- PostgreSQL 已执行过 `domainCheck/init_database.py`
- `domaincheck-api` 与 `domaincheck-worker` 已按 `systemd` 托管

如果当前仍处于“新机器首次部署”，请先回看：

- `docs/05_domainCheck_Linux部署清单.md`
- `domain-api/deploy/linux/README.md`
- `docs/13_domainCheck_Linux测试服交接文档.md`

如果后续进入“国外控制面 + 大陆执行面 + 多 Worker 扩容”阶段，请直接补充阅读：

- `docs/16_domainCheck_多机检测与跨地域部署设计.md`
- `domain-api/deploy/multi-region/README.md`

如果当前已经进入“大陆 controller + 海外 control”双地域正式联调，还应额外确认：

- 大陆 `controller` 节点的 `/etc/default/domaincheck-worker`
  - `NODE_ROLE=control`
- 大陆 `domaincheck-sync-agent`
  - 已启动并稳定运行
- 海外控制面 `runtime/sync-summary`
  - 能看到 `detect_result_batches`

如果当前已经切到“海外单脑控制面统一驾驶”模式，建议同时配套阅读：

- `docs/25_domainCheck_海外单脑控制面上线收口总表.md`
- `docs/23_domainCheck_终局运维架构设计_海外单脑控制面.md`
- `docs/24_domainCheck_NodeAgent协议与ReleaseHub设计.md`

## 二、上线前必须确认的结论

上线前至少要确认下面这些结论同时成立：

- `domaincheck-api` 为 `active (running)`
- `domaincheck-worker` 为 `active (running)`
- `/health` 返回 `worker_mode=linux-systemd`
- `/api/v1/runtime/preflight` 返回 `ok=true`
- `smoke test` 返回 `ok=true`
- 运行中心里的 `start_worker / stop_worker / restart_api` 控制链路可用
- 导入、筛选、批量更新、导出四条核心业务链路至少各回归一次
- 诊断包可正常导出

## 三、正式上线前执行顺序

### 0. 先跑一遍统一上线总检

如果当前已经进入“海外单脑控制面 + 多地域 / Node Agent”这条正式链路，建议先跑：

```bash
cd /www/wwwroot/getDomain/domain-api
bash domain-api/deploy/multi-region/drive_ops_center.sh go-live-check http://127.0.0.1:8100 http://152.53.37.118:8100 summary
```

期望：

- `go_live_status` 为 `ready` 或至少没有新的 `blocking_reasons`
- `stack_status` 不为 `blocked`
- `route_surface_complete=true`
- `launchpad_status` 不为 `blocked`
- 如果当前已经纳管执行节点，则 `remote_access_ready` 不应长期为 `0`
- `next_step_action_code` / `operator_title` 应能直接说明当前第一优先动作
- 如果 `log_sync_enabled=true`，则要额外看 `log_sync_state`、`log_sync_covered_nodes`

如果这里已经出现 `bootstrap_run / run_acceptance`，说明当前上线前仍有节点接管缺口，应先收口首个缺口节点，再继续下面的业务核验。

建议这样理解总检输出：

- `blocking_reasons` 只放真正会阻断上线的项，例如 `remote_agent_ready=0`
- `warnings` 表示还能继续联调，但现在还不适合直接宣称“全部收口”
- `recommended_commands.next_step` 就是当前最值得优先执行的一条命令
- `recommended_commands.log_sync_logs` / `recommended_commands.log_sync_inspection` 用来补远端参与节点的日志观测

### 1. 核对服务状态

```bash
systemctl status domaincheck-api --no-pager -l
systemctl status domaincheck-worker --no-pager -l
```

期望：

- 两个服务都为 `active (running)`
- `domaincheck-worker` 不再循环重启

如果当前是大陆 controller 节点，还要补一条：

```bash
systemctl status domaincheck-sync-agent --no-pager -l
```

期望：

- `domaincheck-sync-agent` 为 `active (running)`
- 不循环重启

### 2. 核对健康接口

```bash
curl http://127.0.0.1:8100/health
curl http://127.0.0.1:8100/api/v1/runtime/preflight
curl http://127.0.0.1:8100/api/v1/runtime/readiness
curl http://127.0.0.1:8100/api/v1/runtime/status
```

期望：

- `/health` 返回 `status=ok`
- `/health` 返回 `worker_mode=linux-systemd`
- `/runtime/preflight` 返回 `ok=true`
- `/runtime/readiness` 不应返回 `blocking`
- `/runtime/status` 返回 `worker.running=true`

如果当前已经接入跨地域同步，还建议补看：

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

期望：

- 返回里能看到 `detect_result_batches`
- 至少能区分：
  - `synced`
  - `projected`
  - `failed`
- 若大陆 `sync-agent` 已接上，则最近执行过的检测任务不应长期停留在 `projected`

当前 `runtime/preflight` 还会额外展示：

- RedisBloom 是否安装，若未安装会明确提示“降级为普通缓存”
- `detect_jucha` / `detect_juziseo` 是否启用
- 若启用了付费检测，对应本地 cookie 文件是否已就绪

当前 `detect/status` / `runtime/status` 还会明确展示代理运行态：

- `代理正常`
- `降级直连`
- `等待代理`

解释：

- `降级直连` 表示代理池暂时无可用代理，但当前允许直连兜底，任务不会因此中断
- `等待代理` 表示代理池无可用代理，且当前未允许直连，这会直接影响检测吞吐或导致步骤失败

当前还补充了两类更细的诊断语义：

- `proxy_runtime_reason=supplier_empty_pool`
  - 表示代理源最近都返回了正常 HTTP 响应，但原始代理数为 `0`
  - 这类问题更偏向供应侧空池，不是程序拉取失败
- `dependency_alerts`
  - 表示外部依赖站点当前存在可观测异常
  - 例如 `web.archive.org` 拒连、超时、连接池异常等

当前免费检测链路中的外部依赖异常还采用了“降级继续”策略：

- 例如 `时光机 / 站长之家 / 爱站 / 百度 / 360` 这类外部站点出现明显网络波动、拒连、超时
- 系统会优先记录为步骤级 `degraded`
- 并将域名置为 `待人工复核`
- 同时继续执行后续检测步骤，避免把整条任务链路直接污染成 `检测失败`

### 3. 跑正式服务态 smoke test

```bash
cd /opt/domaincheck/domain-api/deploy/linux
python3 smoke_test.py --base-url http://127.0.0.1:8100
```

如需把 Web 首页一起纳入检查：

```bash
python3 smoke_test.py --base-url http://127.0.0.1:8100 --web-url http://127.0.0.1
```

期望：

- 输出中 `ok=true`

### 4. 回归运行中心控制动作

建议至少各执行一次：

- `start_worker`
- `stop_worker`
- `restart_api`

期望：

- `stop_worker` 后，`runtime/status` 中 `worker.running=false`
- `start_worker` 后，`runtime/status` 中 `worker.running=true`
- `restart_api` 调用返回成功，随后 API 能重新恢复

说明：

- 当前 Linux 正式服务态已改为 `systemctl --no-block restart domaincheck-api`
- 因此 `restart_api` 会先返回成功，再由 `systemd` 异步完成 API 切换

### 5. 回归核心业务链路

建议至少确认下面 4 条：

- 导入域名成功，且会落到 `domains`
- 导入后自动创建 `detect_tasks`
- 筛选接口 `/api/v1/domains` 返回正常
- 批量更新后数据库字段与页面展示一致
- 导出任务可创建、导出文件可下载

如果时间紧，最小回归顺序建议为：

1. 导入一份小样本
2. 查看导入任务结果
3. 查看域名列表
4. 执行一次批量更新
5. 生成一次 TXT 或 CSV 导出

## 四、建议保留的上线证据

正式上线前，建议至少保留下面这些结果：

- `systemctl status domaincheck-api --no-pager -l`
- `systemctl status domaincheck-worker --no-pager -l`
- `journalctl -u domaincheck-api -n 200 --no-pager`
- `journalctl -u domaincheck-worker -n 200 --no-pager`
- `systemctl status domaincheck-sync-agent --no-pager -l`
- `journalctl -u domaincheck-sync-agent -n 200 --no-pager`
- `/health` 返回
- `/api/v1/runtime/preflight` 返回
- `/api/v1/runtime/sync-summary` 返回
- `smoke_test.py` 输出
- 一份最新诊断包

诊断包导出命令：

```bash
cd /opt/domaincheck/domain-api/deploy/linux
bash collect_diagnostics.sh /opt/domaincheck
```

## 五、当前可接受的非阻断项

以下项目目前已确认不会阻断正式服务运行：

- Redis 未安装 Bloom 模块时，会降级为普通缓存
- `worker` 在 `QT_QPA_PLATFORM=offscreen` 下无头运行
- 付费检测默认关闭时，不要求本机预置 `jucha` / `juziseo` cookie 文件

这些项可以在后续优化阶段继续增强，但不应再作为当前上线阻塞条件。

## 六、仍建议继续观察的项

以下内容不属于当前功能阻断，但上线后建议继续观察：

- 真实代理池可用率
- 代理为空时是否长期停留在 `降级直连`
- Wayback 首次全量检测耗时
- 长时间运行下的 Worker 稳定性
- 真实业务数据量上升后的数据库与导出耗时

## 七、最终上线判定

如果下面三类检查都通过，就可以视为已经具备正式上线条件：

- 服务状态检查通过
- 核心接口与 `smoke test` 通过
- 核心业务链路回归通过

一句话判定：

> 当前项目已经完成开发、Linux 测试服联调、正式服务态验证和关键日志降噪；剩余工作主要是正式环境发布与上线后观察，不再是功能性大修。