# 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
- 如有异常，基于诊断包继续排障
- 最终完成上线前收口