项目：XSearch ｜ 版本：v1.1 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析
本篇汇总全仓库扫描中发现的 ⚠️ 项与债务：每条给出位置 / 证据 / 影响 / 建议，按"运行中风险 > 文档漂移 > 死代码 > 结构性约束"排序。评价基准要先说清：这是一个已完成一轮安全收口、CI 门禁齐备的个人项目，债务总量不大，且多数已被作者自己在注释里诚实记录——本篇的价值是把散落的"已知道"收拢成一张可勾销的清单。
这一节的六条是"现在就生效"的风险：它们不依赖未来变更才会爆发，任何一天都可能以故障形式现身。读表的方法：先看"证据"列确认自己部署形态是否命中，再看"建议"列评估偿还成本——#1 与 #2 涉及部署变更需要在维护窗口做，#3/#4 是小改动但需要回归测试护住，#5 是产品决策而非代码改动，#6 是一处中等规模的改造。与后三节的一个判断差异值得点明：后三节的条目"改了只会更好"，本节的条目"改错会当场坏"——比如 #2 若在没同步客户端凭证的情况下给 Redis 加了 requirepass，整个站会瞬间失去缓存与热搜词。因此本节的每一项偿还都应遵循同一个小流程：先在开发态复现风险（证明自己理解了它）、再在开发态验证修复、最后按《06-部署运行》的发布清单走变更，不要在生产上直接试。
| # | 位置 | 证据 | 影响 | 建议 |
|---|---|---|---|---|
| 1 | 生产链路：frp 服务端（frps）与 VPS Nginx 站点配置 | docker-compose.prod.yml 注释提到隧道名 xsearch-web 与"VPS nginx + Certbot"，具体配置不在仓库（《06-部署运行》4.4 已标 ⚠️ 待确认） | 公网入口是整条链路唯一无法随仓库审计/回滚/复现的环节；HSTS、HTTPS 强制、限流都依赖它 | 把 frps 的 toml 与 VPS 站点配置（脱敏后）收进 deploy/vps/ 或至少在 README 记录关键指令；HSTS 在该层启用并回填 settings.py 57-61 行的注释态 |
| 2 | ES/Redis 无认证 | compose xpack.security.enabled=false、Redis 无 requirepass（《08-安全与权限设计》第九节第 1 条） | 网络隔离是唯一防线，任何能进 bridge 网络的进程可任意读写索引 | ES 启用 basic 认证（xpack 内置免费档）或至少 Redis requirepass + 客户端三处同步（api_views.redis_cli、排查脚本、backup.sh 的 es_curl） |
| 3 | crawler/settings.py 的 ES_HOSTS 与 ES_URL 双源 | 66-67 行：ES_HOSTS 优先于 ES_URL，而 Django 侧只读 ES_URL | 只设 ES_HOSTS 会出现"爬虫写 A 库、站点读 B 库"的静默分叉，无任何报错 | 删除 ES_HOSTS 兼容（注释标了它是旧写法），或至少在两值不一致时打告警日志 |
| 4 | 索引名双源：QuoteDocument.Index.name = "quotes" 硬编码 + ES_INDEX env | pipelines.py 88-89 行硬编码；open_spider 靠 QuoteDocument._index._name = self.index 运行时覆盖；aihot_hot._prune_stale 另自读 settings | 改 ES_INDEX 时行为正确但机制隐蔽（依赖 _index._name 这个私有属性）；_prune_stale 若在 open_spider 之前跑会用错索引名 | Index.name 改为读 env 的模块级常量，删掉 _index._name 覆盖这步"暗操作" |
| 5 | 抖音源的合规张力 | AI升级说明.md 第七节自述：该站对常规 UA 返回 444，取数依赖 Playwright + 指纹伪装 | 公开仓库携带针对特定站点伪装指纹的代码，与"默认自报身份"的立场冲突（作者已诚实记录） | 按文档自给出的两条路择一：下线该源，或改用不依赖伪装的公开接口；至少在 README 爬虫表加显式声明 |
| 6 | 管理员口令明文 | ADMIN_PASSWORD 环境变量/local_settings 明文；backup.sh 原样拷 .env | 配置或备份盘泄露 = 口令泄露 | 改存哈希（PBKDF2/argon2），登录时比对哈希；local_settings.py.example 同步给出生成命令 |
文档漂移是这类项目最常见的债务形态：代码动了、注释和 README 没跟上。XSearch 的特殊性在于它没有 docs 目录、没有文档测试，README 与模块 docstring 全靠手写维护，因此每轮迭代都会积累少量滞后。下表七条全部可以在一个下午内勾销，且互不依赖——适合作为接触这个仓库的第一个 PR，改文档的过程本身就是最好的代码熟悉练习。
| # | 位置 | 证据 | 影响 | 建议 |
|---|---|---|---|---|
| 7 | README.md 测试数字 | 第 278 行写"85 条"，tests.py 实为 22 类 110 方法 | 读者按 85 核对会误判测试丢失 | 改为"110 个测试方法（22 类）"，或改成不写死数字、指向《09-测试与质量保障》 |
| 8 | README.md 鉴权段落 | 161-163 行两句话叠写残缺："鉴权方式：公开 / 管理员（…携带）/ 鉴权只有一层：公开…" | 表述混乱，且是 README 门面段落 | 重写为单句："鉴权只有一层：管理员 token（X-Admin-Token）；公开接口无需鉴权" |
| 9 | search/api_views.py 模块 docstring | 第 11 行仍列"GET /api/ai/item AI 条目详情"，该端点已删除（DocDetailTests.test_title_guessing_endpoint_is_gone 断言 api_ai_item 不存在） | 文件头是新人读代码的第一站，列着不存在的接口 | docstring 同步当前 29 条路由；顺带核对 xsearch/urls.py ServiceInfo 的 endpoints 样例（现仅 6 条，且含 /api/crawl/start 这类管理员端点，作为"服务自描述"对外暴露信息略有不一致） |
| 10 | search/api_views.py 565-566 行 | @require_http_methods(["GET"]) 叠了两个相同装饰器（api_doc） | 无功能影响，笔误级冗余 | 删一个 |
| 11 | xsearch/middleware.py 第 25 行 | Access-Control-Allow-Headers 仍含已废弃的 X-API-Token | 与"第二层鉴权已整体移除"的安全叙事不一致（无实际漏洞，只是允许头） | 从允许头清单移除，或留注释说明兼容期 |
| 12 | README.md 环境变量表与 .env.example 口径 | README 表 16 行（ADMIN 合并为一行），.env.example 实为 17 个变量；两处均未提 VITE_API_TARGET/VITE_API_BASE/ES_HOSTS/TZ | 前端开发者在 frontend/vite.config.ts 与 api.ts 里各会发现一个 README 没讲的变量 | README 表补齐或加"另见《14-配置与环境详解》"引用 |
| 13 | search/api_views.py 558 行 | 两条注释被并到同一行（"新闻来源…"与"人民网已停用…"挤在一行） | 可读性 | 拆两行 |
死代码的判定标准本篇统一为：无运行时引用且不在任何入口链路上。删除前一律执行一次引用扫描（grep 符号名 + 检查模板/配置引用），删除后跑全量测试与一次完整采集冒烟。#14（static 目录）是其中体量最大的一项，删除时注意它牵动三个配置点（settings 的 STATIC 声明、ruff 的 exclude、Dockerfile 的 COPY 范围会随之自然缩小），属于"牵一发动三处"的清理，宜单独成 PR。
顺带说明 #16 这一条的判级理由：运行时产物出现在工作区本身是正常现象（爬虫日志、JOBDIR、图片缓存都是系统的合法排泄物），所以它不算死代码也不算风险，列在这里只是因为 .gitignore 对 .tmp 后缀的遗漏构成了唯一的提交风险敞口——一行修复，与死代码清理放同一个 PR 顺手完成即可。类似的"搭车项"还有 #21（compose 的废弃 version 字段），单看每条都值不到一个独立 PR，攒在一起正好凑成第一阶段的批量勾销。
| # | 位置 | 证据 | 影响 | 建议 |
|---|---|---|---|---|
| 14 | XSearch/static/ 整目录 | 旧版服务端渲染时代的 css/result.css、js/jquery.js、global.js、pagination.js、旧版 img；SPA 已完全替代页面层；nginx 不转发后端静态 | 纯死重：被 COPY XSearch/ . 打进后端镜像；ruff.toml 还为它留了 exclude | 整目录删除，同步删 settings.py 的 STATIC_URL/STATICFILES_DIRS 与 ruff exclude；删前 grep 确认无引用（Django admin 静态走 collectstatic，与此目录无关） |
| 15 | XSearch/static/img/logo-bak.png 等 3 个备份图 | 文件名 -bak/-bak2 后缀 | 死资产（与 #14 同目录，单列以防 #14 只清代码不清备份图） | 随 #14 一并删除 |
| 16 | 工作区运行时产物 | XSearch/db.sqlite3、XSearch/crawl_history.json、crawl_history.json.tmp、logs/*.log、jobs/*、cache/images/* 均在工作区；.gitignore 收录了大部分但漏了 crawl_history.json.tmp | .tmp 有被提交风险；镜像构建上下文有 .dockerignore 兜底（已挡） | .gitignore 补 XSearch/*.tmp（或精确补 crawl_history.json.tmp）；工作区产物属正常运行痕迹，无需删 |
| 17 | frontend/scripts/mobile-audit.py | 不在构建链路、不在 CI、无引用 | 不算死代码（一次性审计工具），但处于"无人知道还能不能跑"状态 | 移入 scripts/README 一行说明用途与用法，或删除 |
| 18 | frontend.Dockerfile 首行注释 | 写着"# LcvSearch 前端 Dockerfile"——旧项目名残留 | 观感问题，且暴露复制粘贴来源 | 改为 XSearch |
| 19 | frontend.Dockerfile 用 npm install 而非 npm ci | builder 阶段（CI 用 npm ci） | 镜像内依赖可能比 lock 漂移，与"CI 通过 ≈ 镜像里也是这套版本"的后端纪律不对齐 | 改 npm ci（lock 已在 COPY 列表里，零成本） |
| 20 | requirements-lock.txt 含 pytest==9.0.3 | 注释归在"开发/测试"段，但 Dockerfile 全量安装 | 生产镜像带入无用测试依赖（体积小，纯洁癖） | 可接受；较真则 Dockerfile 分层安装或移出 lock |
| 21 | docker-compose.yml version: "3.8" | compose v2 已废弃该字段（每次 up 打 warning） | 噪音 | 删该行（prod compose 已无此字段，两份不一致） |
这些不是"做错了"，是作者明说的代价，列出是为了让未来的扩展者知道欠条在哪儿。它们与前三节的本质区别在于：前三节的清偿动作是"删掉/改对"，本节的清偿动作是"换一种架构"——在触发条件出现之前，任何偿还尝试都是负收益（引入迁移风险却换不来可感知收益）。判断"现在动不动"的量化信号见第五节：
Dockerfile CMD 注释、《08-安全与权限设计》第九节第 3 条）。演进路径已写在注释里——"先把任务状态外置到 Redis/DB，再增加 worker"。具体拆解：token/限速 → Redis hash+TTL；互斥 → Redis SETNX 锁；调度 → 独立进程或 Celery beat。这是所有后续横向扩容的总闸门。_write_json_atomic 用".tmp+fsync+原地覆盖"绕开 os.replace 在单文件 bind mount 上的 EBUSY（注释记录 2026-09-28 线上实测）。这是对部署形态的精准补丁，但把"普通文件操作"变成了需要测试守护的定制逻辑（3 个测试用例守护它）。长期解法是把三个状态文件挪进一个目录挂载（./data/state/），恢复 os.replace 常规语义——需要一次带数据迁移的部署变更。doc.save() 入库：pipelines.py 注释自认"大规模生产建议改批量写入"（《10-性能设计与优化》第六节第 2 条）。ruff.toml 注释明说"要收紧再逐条加"——这是欠条也是纪律：每次收紧应单独成 PR，不与功能改动混合。三阶段的排序逻辑：第一阶段全是"改了不会坏"的清理，应在一个独立 PR 里一次勾销（清单即验收标准）；第二阶段每项独立成 PR、各自带测试，其中 B1 涉及部署变更需按《06-部署运行》的发布清单走；第三阶段由真实需求触发——访问量涨到单 worker 扛不住才做 C1，语料涨到入库成瓶颈才做 C2，不需要为想象中的规模预付复杂度。这与项目一贯的取向一致：ruff.toml "要收紧再逐条加"、爬虫白名单"新增条目 = 扩大风险面"——债务清单本身也应当按需勾销，而不是一次性重构冲动。
对第三阶段再补两个触发条件的量化参考：C1 值得启动的信号是"公开接口 P95 延迟持续超过 1 秒"或"需要第二个管理员常驻在线"——前者说明单进程的串行处理成为瓶颈，后者说明 token 全失效的重登成本已不可接受；C2 的启动信号是 crawl_history.json 里单轮采集的 ended_at - started_at 普遍超过定时任务间隔的一半。没有这些信号之前，第二阶段做完就是当前形态的最优解。
把全部 21 条债务放在一起看，能归纳出这个项目（也是多数个人全栈项目）债务产生的四个典型模式，识别模式比记住条目更有长期价值。
模式一：外部边界不可版本化。#1（frp/VPS Nginx）与 #2（ES/Redis 无认证依赖网络隔离）的共同点是关键决策落在仓库之外——配置不在 git 里，就没有 diff、没有 review、没有回滚点。这类债务的通用解法不是"把配置搬进仓库"这么简单（VPS 上还有 Certbot 续期等动态状态），而是在仓库里为仓库外的世界写契约文档：一份记录隧道名、证书路径、server 块关键指令的 deploy/vps/README，让仓库外配置的变更也有迹可循。识别这类债务的信号是"排障时发现关键链路有一段谁也说不清配置在哪"——它出现的那天就该补文档，而不是等出事。
模式二：双源真相。#3（ES_HOSTS vs ES_URL）、#4（Index.name 硬编码 vs ES_INDEX）、#12（README 表与 .env.example 口径）的共性是同一个事实存在两处描述，靠纪律而非机制保持同步。双源的隐患不在"今天不一致"（今天是一致的），而在未来的某次单边修改：只改了一处、测试恰好没覆盖另一处，分叉就静默发生。项目里其实已有反例可借鉴：CrawlerComplianceTests.test_dead_people_feed_removed_everywhere 用测试强制"爬虫 FEEDS 与后端 NEWS_SOURCES 集合一致"——把双源变成单源加断言。凡再遇到双源，优先考虑照此办理（ES_HOSTS 直接删掉即是最彻底的"单源化"；不方便删的，写一个一致性断言的成本是十分钟）。
模式三：历史地层。#18（LcvSearch 项目名）、#14（旧服务端渲染静态资源）、索引名 quotes（慕课课程遗留命名）、DB_DOC_EDITABLE_FIELDS 里兼容豆瓣时代的字段——这些是从老课程项目一路升级演化留下的地层。它们无害但持续消耗新人的理解成本（"quotes 是什么？为什么叫这个？"）。处理原则：能安全删的删（static、项目名注释），不能删的加一行注释说明来历（索引名已在多处注释解释，属已处理），不要为"看起来更专业"去重命名核心标识——quotes 改名的迁移成本远大于它的观感收益。
模式四：文档滞后于代码。#7/#8/#9/#12 全是这个模式。根因是项目的文档（README、模块 docstring、本套 16 篇）与代码没有机制性关联，全靠作者自觉。可行的低成本缓解：把"数字型断言"（测试条数、变量个数、端点数）从文档里改成指向源码的描述（"见 tests.py"而非"85 条"）；把本篇清单的勾销动作写进 PR 模板。彻底解法（文档即代码、自动生成）对这个规模是过度工程。
四个模式之外还想补一句公道话：这套代码库的注释密度与诚实度显著高于平均水平——几乎每条债务旁边都站着一条记录了原因的注释（EBUSY 的日期、412 的成因、misfire 的解释）。这意味着债务的"发现成本"在这个项目里已经接近于零，剩下的只是"偿还意愿与时机"的排序问题。相比之下，多数债务清单的第一栏"这是什么、怎么发生的"在这里是现成的，本篇大量直接引用注释原文，正是为了把这个优势固化下来：注释会随重构漂移，收进文档的债务记录才是持久的那份。
最后一个观察：这份债务清单里没有一个"未知 bug"，全部是已知且多被注释记录的取舍或漂移——这正是一轮认真收口之后仓库该有的样子。维护者的日常工作因此可以简化为两条：新改动别新增第六节四个模式之外的欠条；勾销清单条目时同步更新本篇表格（保留勾销记录也是文档的一部分）。