docs: add linux handoff and wayback env example
This commit is contained in:
Your Name
376
docs/13_domainCheck_Linux测试服交接文档.md
Normal file
376
docs/13_domainCheck_Linux测试服交接文档.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# 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 测试服执行：
|
||||
|
||||
```bash
|
||||
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` 结果：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
这个规则已经同步补入：
|
||||
|
||||
- [05_domainCheck_Linux部署清单.md](./05_domainCheck_Linux部署清单.md)
|
||||
- [domain-api/deploy/linux/README.md](../domain-api/deploy/linux/README.md)
|
||||
|
||||
## 六、当前已完成项清单
|
||||
|
||||
以下内容可以视为“已经完成”：
|
||||
|
||||
### 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 目录落地
|
||||
|
||||
需要确认正式部署目录结构为：
|
||||
|
||||
```text
|
||||
/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 进程跑通就结束，还要在正式服务态下再跑一次：
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
### 第二步：确认数据库结构
|
||||
|
||||
如果是新库，先执行：
|
||||
|
||||
```bash
|
||||
cd /opt/domaincheck/domainCheck
|
||||
python3 init_database.py
|
||||
```
|
||||
|
||||
然后确认：
|
||||
|
||||
```sql
|
||||
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`
|
||||
|
||||
### 第四步：启动正式服务
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable domaincheck-api
|
||||
sudo systemctl enable domaincheck-worker
|
||||
sudo systemctl start domaincheck-api
|
||||
sudo systemctl start domaincheck-worker
|
||||
```
|
||||
|
||||
### 第五步：检查服务状态
|
||||
|
||||
```bash
|
||||
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 状态
|
||||
|
||||
```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/status
|
||||
```
|
||||
|
||||
目标是确认：
|
||||
|
||||
- `status = ok`
|
||||
- `worker_mode = linux-systemd`
|
||||
|
||||
### 第七步：运行 smoke test
|
||||
|
||||
```bash
|
||||
cd /opt/domaincheck/domain-api/deploy/linux
|
||||
python3 smoke_test.py --base-url http://127.0.0.1:8100
|
||||
```
|
||||
|
||||
### 第八步：如异常则导出诊断包
|
||||
|
||||
```bash
|
||||
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. 必看文档
|
||||
|
||||
- [12_domainCheck_导航索引.md](./12_domainCheck_导航索引.md)
|
||||
- [11_domainCheck_Linux联调输入清单.md](./11_domainCheck_Linux联调输入清单.md)
|
||||
- [05_domainCheck_Linux部署清单.md](./05_domainCheck_Linux部署清单.md)
|
||||
- [08_domainCheck_交付说明.md](./08_domainCheck_交付说明.md)
|
||||
|
||||
## 十、最终交接结论
|
||||
|
||||
当前项目不再是“开发未完成”，而是：
|
||||
|
||||
> 开发已完成，Linux 测试服联调已完成第一轮关键打通，剩余工作集中在正式服务化部署与上线前最后复测。
|
||||
|
||||
因此，对下一位接手者的要求不是“继续开发功能”，而是：
|
||||
|
||||
- 完成正式 Linux 服务落地
|
||||
- 跑正式服务态 smoke test
|
||||
- 如有异常，基于诊断包继续排障
|
||||
- 最终完成上线前收口
|
||||
Reference in New Issue
Block a user