# domainCheck Web/Linux 改造总体方案

## 一、目标结论

本项目建议采用“双轨过渡”方案：

- `现阶段`：保持当前 `Windows 桌面版` 不变，继续测试、验收、修正业务规则
- `目标形态`：新增一套 `轻量 Web 管理后台 + Linux 后端 API + Linux 检测 Worker`
- `过渡策略`：桌面版与 Web 版共用同一套数据库、Redis、检测规则与任务模型，逐步把控制面迁移到 Web

本方案的核心原则：

- 不推倒重做现有检测核心
- 不在当前大型 `admin` 项目里硬改主线
- 新建一套轻量 Web 管理后台，只覆盖 `domainCheck` 真实需要的页面
- 将桌面端中的“配置、任务控制、日志查询、导入导出”逐步抽为后端 API
- 将检测执行从 GUI 进程迁移为 Linux 常驻 Worker

---

## 二、为什么采用这条路线

### 1. 当前桌面版的价值仍然存在

当前桌面版已经完成了以下高价值资产：

- 域名导入、待检测任务创建、检测结果写库
- 免费检测链路与付费检测链路
- Wayback 优化策略
- 代理池、多线程、命中即停、缓存
- 域名筛选、导出、批量更新
- 现有数据库结构与状态体系

这些能力不应废弃，后续 Web 化应尽量复用。

### 2. Linux 长期最优形态不是桌面打包工具

Linux 更适合：

- 跑 PostgreSQL / Redis
- 跑 API 服务
- 跑常驻 Worker
- 跑定时任务与日志分析

Linux 不适合长期承载 PySide6 桌面 GUI 作为运营入口。

### 3. 轻量 Web 后台比继续清理现有 admin 更可控

当前 `admin` 项目本质上是一个成熟后台壳，但它：

- 带有原业务的大量历史模块
- 接口风格偏向既有 ThinkPHP 体系
- 动态菜单、权限、接口命名、Token 机制均带旧耦合

因此更适合“参考其基础能力”，而不是作为 `domainCheck` 的长期主线代码仓。

---

## 三、目标架构

建议拆成 4 层：

### 1. Web 管理后台

技术建议：

- `Vue 3`
- `Vite`
- `Element Plus`
- `Pinia`
- `Vue Router`

职责：

- 登录
- 系统设置
- 域名导入
- 检测控制
- 域名筛选
- 导出
- 日志诊断

说明：

- Web 端只做“控制面”和“展示面”
- 不直接承担检测执行

### 2. 后端 API 服务

技术建议：

- 延续当前 Python 技术栈，优先考虑 `FastAPI`

职责：

- 用户登录鉴权
- 配置读写
- 导入任务接口
- 检测控制接口
- 域名筛选查询接口
- 导出任务接口
- 日志诊断接口
- Worker 状态汇总接口

### 3. Linux 检测 Worker

技术建议：

- Python 常驻服务
- 无 GUI
- systemd 托管

职责：

- 从数据库或任务表领取待检测域名
- 按配置顺序执行免费检测与付费检测
- 写回检测结果与黑名单信息
- 汇报运行状态、进度、异常、代理池状态

### 4. 数据与基础设施层

- `PostgreSQL`
- `Redis`
- 日志文件
- 可选对象存储或文件目录用于导出文件

---

## 四、推荐的总体模块划分

### 1. `domain-web`

前端项目，负责：

- 登录页
- 仪表盘
- 系统设置
- 域名管理
- 检测控制台
- 日志诊断页

### 2. `domain-api`

后端 API 服务，负责：

- `auth`
- `settings`
- `domains`
- `detect`
- `exports`
- `logs`
- `diagnostics`

### 3. `domain-worker`

检测 Worker，负责：

- 检测任务轮询
- 并发检测
- 代理使用
- 日志写入
- 运行状态上报

### 4. `domain-core`

可复用核心库，负责：

- 数据库访问
- 状态码定义
- 检测器封装
- 导入、筛选、导出服务
- 配置对象
- 公共异常与日志工具

说明：

- 当前 `domainCheck` 的大部分核心逻辑，后续应逐步沉淀到这一层
- 这是兼容桌面版与 Web/Linux 双模式的关键

---

## 五、页面范围

第一期轻量 Web 后台建议只做以下页面：

### 1. 登录

- 用户登录
- Token 持久化
- 退出登录

### 2. 系统设置

- 数据库连接信息只读或隐藏
- 检测选项配置
- 检测顺序调整
- 代理池配置
- 允许直连开关
- 线程数配置
- 聚名 / 聚查 Cookie 管理
- 敏感词配置管理

### 3. 域名导入

- 上传 TXT
- 导入结果反馈
- 导入失败明细
- 自动建待检测任务

### 4. 检测控制

- 启动检测
- 停止检测
- Worker 在线状态
- 当前线程数
- 当前代理状态
- 当前任务进度

### 5. 域名筛选

- 注册状态
- 检测状态
- 使用状态
- 是否备案
- 备案年份
- 快照年份
- backlink > 10
- 关键词、域名、首页网址
- 分页列表

### 6. 导出

- 导出 TXT
- 导出 CSV/Excel
- 导出当前页 / 指定页数 / 全部
- 导出任务记录

### 7. 日志诊断

- Worker 运行日志
- API 错误日志
- 最近异常摘要
- 一键诊断分析

---

## 六、后端拆分建议

后端改动不是重写业务，而是“服务化”。

### 1. 可直接复用的部分

- 检测器逻辑
- 状态码与状态映射
- 域名导入核心逻辑
- 筛选 SQL 逻辑
- 导出逻辑
- Wayback 优化逻辑
- 代理池逻辑
- 数据库表结构

### 2. 需要抽离成 service 的部分

- 系统设置读写
- 检测选项配置读写
- 线程数配置读写
- 代理配置读写
- Cookie 配置读写
- 域名导入服务
- 域名筛选服务
- 导出服务
- 日志读取与诊断服务

### 3. 需要从 GUI 中搬出的部分

- 检测启动/停止逻辑
- 运行状态展示逻辑
- 配置变更监听
- GUI 信号槽驱动的线程控制

### 4. 需要新增的部分

- API 鉴权
- API 返回结构统一
- Worker 心跳机制
- 导出任务记录
- 日志分析接口
- 远程诊断接口

---

## 七、并发架构建议

当前并发能力可以复用，但调度外壳要改。

### 1. 保留的能力

- 域名级多线程检测
- 检测顺序控制
- Wayback 小并发与命中即停
- 代理池共享
- 失败重试
- 结果落库

### 2. 要调整的实现方式

从：

- `QThread + GUI 信号 + 本地窗口状态`

迁移为：

- `Worker 线程池 + 服务状态上报 + API 查询`

### 3. 推荐并发模型

- 单 Worker 实例维护一个检测线程池
- Worker 从 `detect_tasks` 拉取待处理任务
- 每个域名仍按当前检测顺序串行执行单域名步骤
- 多域名并行执行
- Wayback 继续保留单域名内部的小并发与缓存机制

### 4. 推荐的任务状态流转

- `待检测`
- `检测中`
- `检测完成`
- `检测失败`
- `已拉黑`

同时保留任务表：

- `status = pending`
- `status = running`
- `status = completed`
- `status = failed`

---

## 八、免费与付费检测执行策略

这部分建议沿用当前已确认规则：

- 先跑免费项
- 免费项全部跑完且仍非黑名单，才跑付费项
- 付费项默认为：
- 聚查
- 桔子

检测顺序默认建议：

1. 检查注册
2. 百度 site
3. 360 site
4. 站长之家
5. 爱站
6. 时光机
7. 聚查
8. 桔子

说明：

- Web 后台允许运营勾选与调整顺序
- 但后端执行器应保留“付费项后置”的保护规则

---

## 九、代理架构建议

### 1. 保留现有能力

- 多代理池 URL
- 允许直连开关
- 抽样代理测试
- 可用代理数展示

### 2. Linux 后端建议新增

- 代理池刷新冷却时间
- 空池失败退避
- 低水位自动补池
- 按检测步骤控制是否优先直连
- 代理池健康状态缓存

### 3. 建议策略

- 生产环境：优先代理，谨慎直连
- 测试环境：允许直连兜底，减少空转
- 国内服务器：优先使用国内代理池

---

## 十、日志与诊断架构建议

### 1. 日志来源

- API 服务日志
- Worker 日志
- 导入日志
- 导出日志
- 代理池测试日志

### 2. 日志能力

- Web 页面查看最近日志
- 关键词过滤
- 失败任务聚合
- 一键下载诊断包

### 3. 诊断接口

建议后续提供：

- `POST /diagnostics/analyze`
- `GET /diagnostics/latest`
- `GET /logs/worker`
- `GET /logs/api`

### 4. 上传分析内容建议

- 最近 300 到 500 行日志
- 当前系统配置快照
- Worker 状态快照
- 数据库统计摘要

---

## 十一、认证与权限建议

第一期建议做轻量权限：

- `admin`
- `operator`

说明：

- `admin` 可修改系统配置、代理、Cookie、敏感词
- `operator` 只能导入、查看、筛选、导出、启动检测

建议使用：

- JWT 或简单 Token
- Redis 存储会话

不建议第一期就上过重 RBAC。

---

## 十二、数据库策略建议

当前数据库可继续使用，不建议第一期大改表结构。

建议新增或补强的表可以是：

- `sys_users`
- `sys_login_logs`
- `export_tasks`
- `worker_heartbeats`
- `diagnostic_reports`

现有核心表继续复用：

- `domains`
- `detect_tasks`
- `domain_detections`
- `domain_blacklist`
- `sensitive_words`

---

## 十三、兼容双模式方案

目标是兼容：

- `模式 A`：Windows 桌面版
- `模式 B`：Web 后台 + Linux Worker

兼容方式：

- 共用同一套数据库
- 共用同一套 Redis
- 共用同一套状态码与检测规则
- 共用同一套导入、筛选、导出核心服务

建议：

- 桌面版在过渡期继续可用
- Web 版逐步接管日常运营
- 最终桌面版只保留给管理员或完全退役

---

## 十四、实施阶段建议

### 第一阶段：方案冻结

周期建议：`2-3 天`

产出：

- 页面清单
- API 清单
- 数据模型确认
- 迁移边界确认

### 第二阶段：后端服务化

周期建议：`7-12 天`

产出：

- 登录鉴权
- 配置接口
- 域名查询接口
- 导入接口
- 导出接口
- 检测控制接口
- 日志接口

### 第三阶段：Worker Linux 化

周期建议：`5-8 天`

产出：

- 无 GUI Worker
- systemd 启动方案
- 心跳上报
- 任务轮询
- 并发检测

### 第四阶段：Web 后台一期

周期建议：`7-10 天`

产出：

- 登录
- 系统设置
- 域名导入
- 检测控制
- 域名筛选
- 导出
- 日志诊断

### 第五阶段：联调与回归

周期建议：`5-7 天`

产出：

- API 联调
- Worker 联调
- 真实域名回归
- 性能参数调整

---

## 十五、周期评估

如果基于当前项目逐步演进：

- `较顺利`：`3-4 周`
- `稳妥完整`：`4-6 周`

前提：

- 当前桌面版继续测试，不同时大规模重构
- Web 后台走轻量方案，不做额外复杂业务
- 检测核心尽量复用，不重写规则

---

## 十六、风险点

### 1. GUI 与业务逻辑仍有部分耦合

需要持续把 GUI 里的逻辑搬到 service 层。

### 2. 代理池资源仍是实际瓶颈

Linux 化不会自动解决代理池不足问题，只能让调度更稳。

### 3. 第三方站点反爬与返回结构变动

百度、360、站长、爱站、聚查、桔子都可能发生变化，需要留维护预算。

### 4. Wayback 首次大域名扫描仍可能耗时较高

虽然当前已优化很多，但超大域名首次拉 CDX 列表仍是客观成本。

---

## 十七、最终建议

建议现在就按以下路径推进：

1. 当前桌面版继续测试，不做大方向替换
2. 新建轻量 Web 后台项目，不在现有 `admin` 大仓上继续主线开发
3. 新建 API 服务层，承接配置、任务、导入、筛选、导出、日志能力
4. 将检测端逐步改造成 Linux 常驻 Worker
5. 保持桌面版与 Web/Linux 双模式并行一段时间

这是当前成本、风险、可维护性三者之间最平衡的方案。