getDomain/docs/04_domainCheck_WebLinux改造总体方案.md

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 双模式并行一段时间

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