first
This commit is contained in:
Your Name
244
docs/14_domainCheck_正式上线前最终检查单.md
Normal file
244
docs/14_domainCheck_正式上线前最终检查单.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# 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`
|
||||
|
||||
## 二、上线前必须确认的结论
|
||||
|
||||
上线前至少要确认下面这些结论同时成立：
|
||||
|
||||
- `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` 控制链路可用
|
||||
- 导入、筛选、批量更新、导出四条核心业务链路至少各回归一次
|
||||
- 诊断包可正常导出
|
||||
|
||||
## 三、正式上线前执行顺序
|
||||
|
||||
### 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 测试服联调、正式服务态验证和关键日志降噪；剩余工作主要是正式环境发布与上线后观察，不再是功能性大修。
|
||||
Reference in New Issue
Block a user