XSearch 项目总览

XSearch/                             # 仓库根
├── README.md                        # 项目自述：功能/结构/快速开始/API 表/发布清单
├── AI升级说明.md                    # 技术栈升级记录：移除了什么、为什么、合规立场
├── Dockerfile                       # 后端镜像：python:3.12-slim + Playwright + gunicorn
├── frontend.Dockerfile              # 前端镜像：node:20 构建产物交给 nginx:alpine
├── docker-compose.yml               # 开发部署：ES/Redis 只绑 127.0.0.1，四容器
├── docker-compose.prod.yml          # 生产部署（NAS）：仅前端暴露 127.0.0.1:5600，bind mount 状态
├── .env.example                     # 环境变量模板（22 项，含注释）
├── ruff.toml                        # lint 配置：仅 E9 + F，line-length 120
├── .github/workflows/ci.yml         # CI：后端 lint+测试 / 前端类型检查+构建+体积守门
├── deploy/
│   ├── es-ik.Dockerfile             # ES 8.15.3 + analysis-ik 插件定制镜像
│   ├── es.elasticsearch.yml         # ES 配置：path.repo=/snapshots（快照备份依赖）
│   ├── nginx.conf                   # 前端 nginx：SPA 兜底 + /api/ 反代 + SEO 路径转发
│   └── backup.sh                    # 每日备份：状态文件 + ES _snapshot + 14 天保留
└── frontend/                        # Vue 3 前端工程
    ├── index.html                   # SPA 入口（含兜底 meta description / og 标签）
    ├── package.json                 # 脚本：dev / build（vue-tsc + vite）/ type-check
    ├── vite.config.ts               # 端口 5173/4173，/api 代理到 8000
    ├── tsconfig.json                # strict 全套 + noUnusedLocals/Parameters
    └── src/
        ├── main.ts                  # 入口：10 条路由（懒加载）+ 守卫 + meta 管理 + chunk 自救
        ├── App.vue                  # 根组件：导航/登录弹窗/退出登录
        ├── api.ts                   # 类型化 API 客户端：34 个接口封装 + ApiError + 高亮渲染
        ├── auth.ts                  # 登录态：localStorage token + ADMIN_PATHS 路由清单
        ├── style.css                # 全局样式
        ├── components/LoginForm.vue # 登录表单（弹窗与登录页共用）
        └── views/                   # 9 个页面组件
            ├── HomeView.vue         # 首页：检索入口 + 今日要闻混排
            ├── SearchView.vue       # 搜索：URL 即状态、分面/排序/纠错/分页
            ├── NewsView.vue         # 新闻列表（三源 Tab）
            ├── AiView.vue           # AI 讯息（精选/日报/热点榜三 Tab，日报前端解析渲染）
            ├── AiDetailView.vue     # AI 条目详情（按 _id 取文）
            ├── RankingsView.vue     # 抖音榜单
            ├── StatsView.vue        # 数据概览
            ├── CrawlView.vue        # 采集管理（启动/状态/定时任务/统计/历史）
            ├── DbAdminView.vue      # 数据管理（浏览/编辑/删除/清理）
            └── LoginView.vue        # 独立登录页
└── XSearch/                         # Django 后端 + Scrapy 爬虫（合并后统一项目）
    ├── manage.py                    # Django 管理入口
    ├── scrapy.cfg                   # Scrapy 配置（指向 xsearch.settings 模块）
    ├── requirements.txt             # 依赖范围（开发用）
    ├── requirements-lock.txt        # 依赖锁定（Docker/CI 共用，保证可复现）
    ├── local_settings.py.example    # 私有配置模板（管理员账号/告警邮箱，本体已 gitignore）
    ├── db.sqlite3                   # SQLite（Django 会话等框架数据）
    ├── schedules.json               # 定时任务持久化（ScheduleManager 写）
    ├── crawl_history.json           # 采集历史持久化（CrawlManager 写，上限 200 条）
    ├── logs/                        # 爬虫 stdout/stderr 日志（crawl_<时间戳>.log）
    ├── jobs/                        # Scrapy JOBDIR 断点目录（支持中断恢复）
    ├── cache/images/                # 图片代理磁盘缓存（MD5 文件名）
    ├── static/                      # 旧版服务端渲染遗留静态资源（现前端已独立）
    ├── xsearch/                     # Django 项目配置包
    │   ├── settings.py              # 全局配置：安全 fail-closed / ES / Redis / 告警 / 日志
    │   ├── urls.py                  # 路由表：29 条 path（API + admin + robots/sitemap）
    │   ├── middleware.py            # 白名单式 CORS 中间件（CorsMiddleware）
    │   └── wsgi.py                  # WSGI 入口（gunicorn 指向它）
    ├── search/                      # 搜索 + 采集管理 Django app
    │   ├── apps.py                  # SearchConfig.ready：启动调度器 + 弱配置告警
    │   ├── api_views.py             # 全部 JSON API（约 1150 行，25 个视图函数）
    │   ├── crawl_manager.py         # CrawlManager（子进程爬虫）+ ScheduleManager（cron）
    │   ├── seo_views.py             # robots.txt / sitemap.xml
    │   ├── notify.py                # 邮件告警（后台线程 + 30 分钟冷却）
    │   ├── models.py                # 已迁移：mapping 统一由 crawler/pipelines.py 维护
    │   ├── admin.py                 # 空（未注册模型）
    │   └── tests.py                 # 22 个测试类 / 110 个测试方法（全 mock，不依赖 ES/Redis）
    └── crawler/                     # Scrapy 爬虫包（原 ArticleSpider，已合并）
        ├── settings.py              # Scrapy 配置：robots 合规 / 限速 / 中间件 / playwright
        ├── middlewares.py           # 指纹头 / 住宅代理 / Playwright 降级三个中间件
        ├── pipelines.py             # QuoteDocument（索引 mapping）+ EsArticlePipeline
        ├── ai/fingerprint.py        # browserforge 指纹头生成（含降级模板）
        └── spiders/                 # 5 个爬虫
            ├── news_rss.py          # 新闻 RSS 聚合（中新网/IT之家/Solidot）
            ├── news_backfill.py     # 中新网历史存档回填（默认 180 天，幂等）
            ├── aihot_news.py        # AI 精选动态 + AI 日报（AIHOT 官方 API）
            ├── aihot_hot.py         # AI 热点榜 Top10（含跌榜清理）
            └── douyin_hot.py        # 抖音热点榜 50 条（Playwright 渲染 + 文本解析）

docker compose up -d elasticsearch redis

cd XSearch
pip install -r requirements-lock.txt   # 与 Docker 构建一致
playwright install chromium            # 仅采集抖音榜需要
python manage.py migrate               # 初始化 SQLite（会话表）
python manage.py runserver 127.0.0.1:8000

cd frontend
npm install
npm run dev          # http://localhost:5173，Vite 已把 /api 代理到 8000

cd XSearch
scrapy crawl news_rss                      # 新闻 RSS 聚合（3 源）
scrapy crawl aihot_news                    # AI 精选 + 当日 AI 日报
scrapy crawl aihot_hot                     # AI 热点榜
scrapy crawl news_backfill -a days=180     # 中新网历史回填（幂等）
scrapy crawl douyin_hot                    # 抖音热点榜（需 playwright）

cd XSearch
python manage.py test search   # 110 个测试方法，全部 mock 依赖，本机无需 ES/Redis