admin/getDomain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ff32aa50bf95be6a85e06abb1329bfbc4c3e5fd9
getDomain/docs/13_domainCheck_Linux测试服交接文档.md
Your Name ff32aa50bf docs: add linux handoff and wayback env example
2026-04-16 13:43:50 +08:00

9.1 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 已通过

2. 未完全完成

  • Linux 测试服当前还不是最终正式部署形态
  • 这次通过的是“临时启动 API 进程”的验证，不是正式 systemd 服务托管态
  • worker_mode 当前仍表现为 windows-local
  • domaincheck-api / domaincheck-worker 还没有按正式生产口径落成 Linux systemd 服务闭环

一句话结论：

功能和数据库问题已经打通；正式 Linux 上线态还差最后一段服务化收口。

三、这次 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

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

四、当前测试服不是正式上线态的原因

虽然 smoke test 已通过，但当前仍不是正式上线态，原因如下：

1. 当前通过的是临时 API 进程验证

本次验证是通过“当前工作区里手动启动的 API 进程”完成的，不是通过正式服务方式完成的。

2. worker_mode 仍不是 Linux 正式模式

当前表现仍是：

  • worker_mode = windows-local

这意味着：

  • 运行中心、配置项、控制逻辑还没有真正切到 Linux 正式托管模式
  • 当前仍属于“测试验证态”

3. systemd 服务还未正式落地闭环

还没有最终确认以下两项处于正式可用状态：

  • domaincheck-api
  • domaincheck-worker

也就是说：

  • 现在能证明代码跑得通
  • 但还没有证明“服务化部署后也稳定可用”

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

后续无论谁再部署到 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 主要接口已完成
  • 运行中心、系统设置、导入、导出、日志诊断、自检、自测均已具备

3. 交付层

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

4. Linux 文档层

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

七、当前未完成项清单

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

1. 正式 Linux 目录落地

需要确认正式部署目录结构为：

/opt/domaincheck
├── domainCheck
├── domain-api
├── domain-web

如果测试服当前目录不是这一套，需要统一。

2. 正式 systemd 服务化

需要把以下服务真正落好并验证：

  • domaincheck-api
  • domaincheck-worker

至少要完成：

  • 安装 service 文件
  • daemon-reload
  • enable
  • start
  • status
  • journalctl

3. worker_mode 切换为 linux-systemd

需要确认：

  • Web 系统设置中运行模式改为 linux-systemd
  • API /health 或运行中心能正确反映：
    • worker_mode = linux-systemd

4. 正式服务态再跑一次 smoke test

不是临时 API 进程跑通就结束，还要在正式服务态下再跑一次：

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

5. Worker 真实联动验证

还应继续确认：

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

6. 导入真实数据后的业务复测

当前 domains_count = 0，说明库表正常，但业务数据还没开始导入。

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

  • 导入域名
  • 查看 domains 增长
  • 查看 detect_tasks 生成
  • 再验证筛选与导出

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

建议 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

第四步：启动正式服务

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

目标是确认：

  • 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