# 07 domainCheck Web/Linux 发布验收清单

## 一、文档定位

本文档用于回答两个问题：

1. 当前这套 Web/Linux 方案，到底哪些项已经验过
2. 发布前还需要按什么维度再核一遍

阅读建议：

- 想看测试服真实联调结果，优先看 `docs/13_domainCheck_Linux测试服交接文档.md`
- 想看正式上线前最后一次操作顺序，优先看 `docs/14_domainCheck_正式上线前最终检查单.md`

本文档更适合作为“发布验收维度总表”。

## 二、基础连通验收

以下项目应视为发布验收的第一层：

- `domaincheck-api` 已启动
- `domaincheck-worker` 已启动
- `http://127.0.0.1:8100/health` 返回 `status=ok`
- `/health` 返回 `worker_mode=linux-systemd`
- `/api/v1/runtime/preflight` 返回 `ok=true`
- `/api/v1/runtime/status` 返回 `worker.running=true`

当前测试服状态：

- 已验证通过

## 三、Web 后台验收

### 1. 运行与展示

- 登录正常
- 顶部状态可展示 `API / Worker / 运行模式`
- 概览页可正常读取统计
- 运行中心可正常读取：
  - API 版本
  - API 前缀
  - PID
  - Worker 进程数
  - 自检结果

### 2. 配置能力

- 系统设置可正常读取
- 线程数可修改并保存
- 检测顺序可调整并保存
- 代理池列表可编辑并保存
- `worker_mode / worker_service_name / api_service_name` 可保存
- 可手动创建配置备份
- 可下载配置备份
- 可导出配置快照
- 可导入配置快照
- 导入配置时会自动生成导入前备份

当前测试服状态：

- 核心接口与配置链路已验证通过

## 四、业务能力验收

发布前建议至少覆盖下面 5 类能力：

- 导入
- 列表筛选
- 批量更新
- 导出
- 日志与诊断

### 1. 导入链路

- 导入任务可创建
- 导入任务列表可刷新
- 导入结果统计正确
- 导入成功后会写入 `domains`
- 导入成功后会自动创建 `detect_tasks`

当前测试服状态：

- 已使用样本 TXT 实际验证通过
- 当前已确认：
  - 总数 `5`
  - 有效 `3`
  - 新增 `3`
  - 无效 `2`

### 2. 列表与筛选

- 域名列表可查询
- 筛选项接口正常返回
- 页面结果与数据库记录一致

当前测试服状态：

- 已验证通过

### 3. 批量更新

- 批量更新接口可执行
- 页面展示与数据库字段一致
- 关联检测字段会同步更新

当前测试服状态：

- 已验证通过
- 已确认 `backlink_count_gt_10` 可随批量更新同步生效

### 4. 导出链路

- 导出任务可创建
- 导出记录可查看
- 导出文件可下载
- TXT / CSV 至少一种格式已回归

当前测试服状态：

- TXT、CSV 均已验证通过

### 5. 日志与诊断

- 日志接口可正常读取
- 诊断包可正常导出

当前测试服状态：

- 已验证通过
- 当前已生成正式服务态诊断包：
  - `/opt/domaincheck/diagnostics/diag_20260416_134923.tar.gz`

## 五、Linux 特有项验收

以下项目是 Web/Linux 交付里最容易在正式环境出问题的部分：

- `domaincheck-api.service` 可正常启动/停止
- `domaincheck-worker.service` 可正常启动/停止
- `journalctl` 可查看两边日志
- 运行中心可调用 `start_worker / stop_worker / restart_api`
- Worker 以 `QT_QPA_PLATFORM=offscreen` 正常运行
- API 自重启不会再因为同步等待自身停机而误报 `500`

当前测试服状态：

- 已验证通过

## 六、数据库与权限验收

Linux 新环境发布前，下面两项必须显式确认：

### 1. 数据库初始化

如果 PostgreSQL 使用的是新库，必须先执行：

```bash
cd /opt/domaincheck/domainCheck
python3 init_database.py
```

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

- `/api/v1/dashboard/overview`
- `/api/v1/detect/status`
- `/api/v1/imports/summary`

### 2. 服务用户写权限

正式 `systemd` 服务用户必须可写：

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

否则可能出现：

- `/api/v1/imports/upload` 返回 `500`
- Worker 循环重启

当前测试服状态：

- 两项都已实际踩坑并修复

## 七、发布前建议命令

### 1. 健康检查

```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
```

### 2. systemd 状态

```bash
systemctl status domaincheck-api --no-pager -l
systemctl status domaincheck-worker --no-pager -l
```

### 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
```

### 4. 诊断包导出

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

## 八、当前发布验收结论

结合当前 Linux 测试服已经完成的联调结果，可以给出下面的结论：

- Web 管理后台已达到可交付状态
- Linux 正式 `systemd` 服务态已验证通过
- 核心业务链路已完成最小闭环回归
- 当前剩余工作主要是正式环境发布、灰度观察和持续稳定性观察

一句话结论：

> 当前项目已经通过 Web/Linux 发布所需的核心验收项，后续重点不再是功能开发，而是正式环境收口与上线后观察。