admin/getDomain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0295f7d06dac82c31a74cf0d161b85461aa7db6e
getDomain/docs/13_domainCheck_Linux测试服交接文档.md
Your Name ebf632e651 first
2026-04-16 21:35:47 +08:00

12 KiB
Raw Blame History

13 domainCheck Linux 测试服交接文档

一、文档目的

本文档用于把当前 domainCheck 项目的 Linux 测试服联调状态，完整交接给后续接手的开发、运维或 Linux 上的 Codex。

目标是回答 4 个问题：

  1. 当前到底完成到了什么程度
  2. 这次 Linux 测试服已经验证通过了哪些内容
  3. 还有哪些事情没有做完
  4. 后续继续收口时，应该按什么顺序做

二、当前结论

当前项目状态可以明确分成两部分：

1. 已完成

  • 本地 Windows 开发与联调已完成
  • domain-api 与 domain-web 已完成主要功能开发
  • Web/API 本地整栈自测已通过
  • 交付包、验包、SHA256、最新交付指针已完成
  • Linux 测试服数据库初始化问题已定位并修复
  • Linux 测试服在“临时 API 进程 + 已初始化数据库”的模式下，smoke test 已通过
  • Linux 测试服已经完成正式 systemd 服务化联调，domaincheck-api 与 domaincheck-worker 均已拉起
  • 正式服务态下 /health 已确认 worker_mode = linux-systemd
  • 正式服务态 smoke test 已通过
  • 已补做一轮真实导入回归，确认“导入域名 -> 写入 domains -> 自动创建 detect_tasks”链路正常

2. 未完全完成

  • Linux 测试服虽然已完成正式服务化联调，但仍属于“测试服验证通过”，不等于生产观察期已经完成
  • Worker 当前通过 QT_QPA_PLATFORM=offscreen 运行，属于“无头 Qt 托管态”，后续仍建议继续观察稳定性
  • 真实业务网络环境下的长时检测、代理池质量、Wayback 首次全量列表耗时，还需要继续压测和观察
  • 当前数据库里仅导入了少量回归样本，不代表真实大批量数据已完成验收

一句话结论：

功能、数据库和正式服务化都已经打通；后续工作转入真实业务回归、稳定性观察和上线前优化。

三、这次 Linux 测试服已验证通过的内容

1. 数据库初始化问题已确认根因

本次 Linux 测试服最初失败的根因是：

  • PostgreSQL 可连接
  • 但业务库是空库
  • 缺少 domains 等核心表
  • 导致这些 API 因 psycopg2.errors.UndefinedTable 直接 500

受影响接口至少包括：

  • /api/v1/dashboard/overview
  • /api/v1/detect/status
  • /api/v1/imports/summary

2. 正确修复方式已确认

在 Linux 测试服执行：

cd /www/wwwroot/getDomain/domainCheck
python init_database.py

执行后，核心业务表已成功创建/补齐：

  • domains
  • detect_tasks
  • domain_blacklist
  • sensitive_words
  • domain_detections

数据库核查结果为：

  • table_count = 5
  • domains_count = 0

说明：

  • 库结构已正常
  • 只是当前还没有正式业务数据导入

3. 临时验证态 smoke test 已通过

新版 smoke test 结果：

{
  "ok": true
}

这说明在当前测试服条件下：

  • API 主服务逻辑可用
  • PostgreSQL 连接可用
  • Redis 连接可用
  • 缺表问题已解除

4. 临时验证态诊断包已导出

本次测试服诊断产物：

  • 目录：/www/wwwroot/getDomain/diagnostics/diag_20260416_133701
  • 压缩包：/www/wwwroot/getDomain/diagnostics/diag_20260416_133701.tar.gz

可用于后续继续排障或归档。

四、正式服务态已补验证通过

在后续继续收口过程中，已经额外完成了正式 systemd 服务态验证，结果如下：

1. 正式服务已落地

已安装并启用：

  • domaincheck-api
  • domaincheck-worker

并已确认两者为 active (running)。

2. 运行模式已切换成功

正式服务态下接口返回已确认：

  • /health 中 worker_mode = linux-systemd
  • /api/v1/runtime/preflight 中 worker_mode = linux-systemd
  • /api/v1/runtime/status 中：
    • api.service_name = domaincheck-api
    • worker.service_name = domaincheck-worker
    • worker.running = true
    • process_count = 1

3. 正式服务态 smoke test 已通过

正式服务态下再次执行：

python smoke_test.py --base-url http://127.0.0.1:8100

结果仍为：

{
  "ok": true
}

4. 正式服务态诊断包已导出

正式服务态诊断产物：

  • 目录：/opt/domaincheck/diagnostics/diag_20260416_134923
  • 压缩包：/opt/domaincheck/diagnostics/diag_20260416_134923.tar.gz

5. 正式服务态中已确认的兼容与权限问题

本轮继续联调还确认并处理了两类真实 Linux 问题：

  • detect/jucha.py、detect/juming.py 中存在 Windows 专属 subprocess.STARTUPINFO() 写法，已改为跨平台兼容处理
  • 若曾以 root 手工运行过 API/Worker，可能会留下 root 所有者的运行文件，导致正式 systemd 服务用户无法写入

其中已实际踩到并修复的权限点包括：

  • domain-api/runtime/ 目录权限
  • domainCheck/detect_worker.log 文件权限

这个问题的表现是：

  • /api/v1/imports/upload 因无法创建 runtime/imports/ 返回 500
  • Worker 因无法写 detect_worker.log 进入循环重启

6. 运行中心控制链路已补通

本轮继续验证后，运行中心里的 Linux 控制动作也已经打通：

  • Worker start / stop 已可通过 sudo -n systemctl 正常执行
  • API 自重启已改为 systemctl --no-block restart domaincheck-api

这样处理后，systemd 会异步接管重启流程，接口可以先返回成功，避免出现“服务其实已经重启成功，但调用方因为等待自身停机而收到 500”的误导性现象。

7. 服务态日志噪音已进一步收敛

本轮还额外处理了两类不会阻断功能、但会影响正式服务观察体验的日志噪音：

  • Redis 配置订阅从阻塞 listen() 改为短轮询 get_message()，Linux 空闲时不再每分钟刷 Redis订阅失败: Timeout reading from socket
  • offscreen 模式下去掉 Qt 不支持的按钮样式属性，Worker 启动时不再刷 Unknown property transition/transform/box-shadow
  • Worker 图标资源定位改为优先使用 detect_worker.py 同目录，Linux 服务态不再误报 /opt/new_logo.svg、/opt/favicon2.ico 不存在
  • 付费检测器改为按需初始化，默认关闭 detect_jucha / detect_juziseo 时，不再在启动阶段报 cookie 文件缺失
  • Redis 未加载 Bloom 模块时保留为降级说明，继续使用普通缓存，不再作为故障级告警处理

这几项修改的结果是：

  • domaincheck-worker 仍保持 active (running)
  • /api/v1/runtime/status 中 worker.running = true
  • 正式测试服日志更适合持续观察和上线前留档

五、这次联调后已经明确固化的部署规则

后续无论谁再部署到 Linux，新环境都必须遵守下面这条：

如果 PostgreSQL 使用的是新库，必须先执行 domainCheck/init_database.py 初始化数据库结构。

否则至少这些接口会直接失败：

  • /api/v1/dashboard/overview
  • /api/v1/detect/status
  • /api/v1/imports/summary

这个规则已经同步补入：

六、当前已完成项清单

以下内容可以视为“已经完成”：

1. 代码与仓库层

  • domainCheck 已并入外层总仓库，不再是子模块指针
  • 根目录总 README.md 已补齐
  • .gitignore 已补强
  • 本地敏感文件、cookies、本地 Node runtime 已从 git 中移除

2. Web/API 层

  • domain-web 主要页面已完成
  • domain-api 主要接口已完成
  • 运行中心、系统设置、导入、导出、日志诊断、自检、自测均已具备
  • 正式 systemd 服务态下 /health、/runtime/preflight、/runtime/status、smoke test 已全部通过

3. 交付层

  • 交付包已生成
  • SHA256 校验已生成
  • 验包脚本可用
  • 发布准备报告可用
  • 最新交付指针可用

4. Linux 文档层

  • Linux 部署清单已完成
  • Linux 诊断采集脚本已完成
  • Linux 联调输入清单已完成
  • 导航索引文档已完成

5. 真实业务回归层

  • 已通过 API 上传样本 TXT
  • 已确认导入结果：
    • 总数 5
    • 有效 3
    • 新增 3
    • 无效 2
  • 已确认 domains_total = 3
  • 已确认 detect_tasks_total = 3
  • 已确认导入后会自动创建 detect_tasks

七、当前未完成项清单

以下内容仍属于“后续要做”：

1. Worker 真实联动验证

还应继续确认：

  • Worker 在线状态
  • Worker 进程数
  • 检测控制页读取是否正常
  • detect_worker.log 是否正常写入

2. 导入更多真实数据后的业务复测

当前已经完成一轮小样本回归，不再是空库空表态。

后续应至少补一次真实业务复测：

  • 导入更接近真实业务规模的域名样本
  • 查看 domains 持续增长
  • 查看 detect_tasks 持续生成
  • 再验证筛选与导出

3. 长时间运行与代理池观察

仍建议继续验证：

  • Worker 长时运行稳定性
  • Redis 订阅超时后的重连是否持续稳定
  • 国内网络环境下代理池真实可用率
  • Wayback 首次全量快照列表的耗时表现

八、后续继续收口的推荐顺序

建议 Linux 上的下一位接手人严格按下面顺序执行。

第一步：确认目录完整

确认至少存在：

  • /opt/domaincheck/domainCheck
  • /opt/domaincheck/domain-api
  • /opt/domaincheck/domain-web

第二步：确认数据库结构

如果是新库，先执行：

cd /opt/domaincheck/domainCheck
python3 init_database.py

然后确认：

select tablename
from pg_tables
where schemaname = 'public'
order by tablename;

第三步：落 systemd

使用这些模板：

  • domain-api/deploy/systemd/domain-api.service
  • domain-api/deploy/systemd/domain-worker.service

如果此前用 root 手工跑过 API 或 Worker，建议先确认下面这些路径对正式服务用户可写：

  • domain-api/runtime/
  • domainCheck/detect_worker.log

第四步：启动正式服务

sudo systemctl daemon-reload
sudo systemctl enable domaincheck-api
sudo systemctl enable domaincheck-worker
sudo systemctl start domaincheck-api
sudo systemctl start domaincheck-worker

第五步：检查服务状态

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

第六步：检查 API 状态

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/status

第七步：做一轮导入回归

至少验证：

  • /api/v1/imports/upload
  • /api/v1/imports/tasks
  • /api/v1/imports/summary
  • domains 增长
  • detect_tasks 自动创建

目标是确认：

  • status = ok
  • worker_mode = linux-systemd

第七步：运行 smoke test

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

第八步：如异常则导出诊断包

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

九、后续交接给 Linux 上 Codex 时，最该提供的材料

如果后续换一位 Linux 上的 Codex 接手，优先给他这些：

1. 当前关键结论

  • 当前最大已修复问题：数据库未初始化
  • 当前最大未收口问题：正式 systemd 服务态还没完全落定

2. 当前最关键文件

  • domainCheck/.env
  • api_health_curl.txt
  • api_preflight_curl.txt
  • api_runtime_curl.txt
  • 诊断包：
    • diag_20260416_133701.tar.gz

3. 必看文档

十、最终交接结论

当前项目不再是“开发未完成”，而是：

开发已完成，Linux 测试服联调已完成第一轮关键打通，剩余工作集中在正式服务化部署与上线前最后复测。

因此，对下一位接手者的要求不是“继续开发功能”，而是：

  • 完成正式 Linux 服务落地
  • 跑正式服务态 smoke test
  • 如有异常，基于诊断包继续排障
  • 最终完成上线前收口
Reference in New Issue View Git Blame Copy Permalink