故障排查
| 症状 | 检查与处理 |
|---|---|
| Docker 无法连接 | 执行 docker info；CLI 存在不代表引擎已启动 |
| 镜像 manifest unknown | latest 要等 main 的 CI 里 publish 作业成功后才存在；固定了版本号时检查对应 Release 是否发布；开发版本使用源码构建 |
| Nginx 502 | docker compose ps 检查健康状态；确认代理在宿主机运行且指向 127.0.0.1:4321 |
| 请求来源/主机不允许 | 按 Nginx 模板覆盖 Host、X-Forwarded-Host 和 X-Forwarded-Proto；无需配置 PUBLIC_ORIGIN |
| HTTPS 后无法登录 | 确认 Nginx 转发 X-Forwarded-Proto 为 https，浏览器 Cookie 为 Secure |
| 日志提示未设置 TRUSTED_PROXIES，或所有人同时提示“登录尝试过于频繁” | 反代后默认把所有用户视为同一来源，8 次失败会锁定所有人 15 分钟。在“设置 → 服务器与网络”或 .env 的 TRUSTED_PROXIES 中填写直接代理的 IP（Docker 网桥可用 docker network inspect 查看网关地址），并让 Nginx 传递 X-Forwarded-For |
| 提示“未找到 Chromium 浏览器” | 源码运行时在项目目录执行 pnpm browser:install；若 .env 设置了 PLAYWRIGHT_BROWSERS_PATH=0，浏览器装在 node_modules 里，重装依赖后需要再装一次（PLAYWRIGHT_BROWSERS_PATH=0 pnpm browser:install） |
| 提示“网页操作失败，请检查目标页面和等待条件” | 这是原始错误无法完整显示时的通用提示；服务端日志会记录“打开网页失败：…”等原始错误（已隐藏网址参数和凭据） |
| 识别超时 | 检查目标可达性、等待设置、Cookie；Nginx 等待时间不能短于实际排队与抓取时间 |
| 没有列表或歧义 | 使用候选预览和调整匹配；页面改版需修复已保存规则 |
| Cookie 无效 | 从已登录浏览器重新导入，检查域名、路径及过期时间 |
| 提示“通过代理访问失败”或“无法连接代理服务器” | 在“设置 → 网络配置”中用“测试连接”检查：连接被拒绝或超时说明代理地址、端口不对或代理未运行；“代理认证失败（HTTP 407）”请重新填写用户名和密码；“没有返回有效的 … 响应”通常是代理类型选错（例如把 SOCKS5 代理填成了 http://） |
| 保存网络配置提示“已被安全策略阻止” | 代理指向本机或局域网地址。确需使用时由管理员把代理的 host:port 加入允许访问的主机 |
| Fake-IP DNS 导致拒绝 | 明确需要时设置 DNS_OVER_HTTPS=true；不要关闭私网校验 |
| 提示“加密 DNS 查询失败” | 本机直连不到加密 DNS 服务（cloudflare-dns.com）。如果只有代理软件能出网，给订阅配置网络代理：配置了代理的订阅，加密 DNS 查询也经该代理发出。仍失败或不需要时，在“设置 → 服务器与网络”关闭 DNS over HTTPS |
| 提示“经代理 … 的加密 DNS 查询失败” | 加密 DNS 查询经订阅的代理也失败了：用“测试连接”检查代理是否可用；代理规则需要允许访问 cloudflare-dns.com:443 |
| 抓取提示“连接 … 超时（20 秒未响应）” | 目标网站在规定时间内没有响应。如果本机浏览器能打开但 FeedLantern 超时，通常是代理软件只接管了系统代理（FeedLantern 不读取系统代理）：开启 TUN／增强模式并在“设置 → 服务器与网络”打开 DNS over HTTPS，或在“设置 → 网络配置”中为该订阅配置代理。已配置代理仍超时，用“测试连接”检查代理 |
| 恢复完整备份后提示“请求来源不被允许”或端口变了 | 恢复时勾选了“同时恢复备份中的服务器与网络设置”，备份里的公开访问地址、端口等替换了本机设置。默认不勾选时不会发生。已经发生时，.env 不会覆盖已保存的设置：请通过与备份中“公开访问地址”一致的地址访问（例如临时在 hosts 中把该域名指向本机，端口用重启后的监听端口），登录后在“设置 → 服务器与网络”改回本机地址；或用这份备份不勾选该选项重新恢复 |
| 导出备份提示「备份数据校验失败」 | 提示里的路径指出不合规的表和字段（如 tables.settings.0），按路径检查该表数据；只显示路径，不含内容。反馈问题时附上路径即可，不要贴数据 |
| 导出备份提示「服务器内部错误」 | 查看 docker compose logs --tail=100 feedlantern，未预期的错误会记录类型、消息和简短堆栈 |
| 数据库文件很大 | 先确认版本不低于含数据保留上限的版本。旧数据库清理后不会自动变小，停机运行 scripts/compact-db.ts，见升级维护 |
| 备份上传 413 | 检查 Nginx client_max_body_size 与应用上限；更大数据使用停机卷备份 |
| 忘记管理员密码 | docker compose exec -it feedlantern pnpm admin:reset，按提示操作，旧会话会撤销 |
| 数据目录权限失败 | 数据目录需由容器用户 UID 1000 读写，数据库和 master.key 不能丢失 |
| Chromium 沙箱无法启动 | 检查 Compose seccomp 文件、宿主机用户命名空间和 AppArmor 策略；不要以 privileged 或 no-sandbox 绕过 |
RSS 地址携带访问密钥，排错时不要贴完整地址、Cookie、备份密码或 setup-token。默认 Nginx 示例不记录可能带密钥的请求日志。
Ubuntu 24.04 等主机可能对无特权用户命名空间施加额外 AppArmor 限制。应按主机安全策略配置针对容器运行时的例外，或使用已验证的兼容主机；项目不自动修改宿主机全局安全策略。
订阅抓取失败与故障通知
RSS 来源返回的不是订阅内容时，FeedLantern 在解析 XML 之前先判断原因，抓取日志、订阅列表和告警中会显示：
- “来源返回的是反爬验证页而不是 RSS/Atom（HTTP 203，页面含 cookies-required 标记）”：对方用验证页（验证码、工作量证明、Cookie 校验等）拦截了程序访问，括号里是识别出的标记。FeedLantern 不会尝试绕过这类验证，请改用对方的官方接口或其他订阅地址。PubMed 期刊 RSS 会显示专门的说明“NCBI 用验证页拦截了这个 PubMed 期刊 RSS 地址”：请在订阅面板中转换为 PubMed 检索订阅，或改用检索式 RSS，见使用指南。
- “来源返回的是网页而不是 RSS/Atom（HTTP 200）”：地址指向普通网页、登录页或错误页，请确认填写的是订阅源地址，而不是网站首页；需要从网页生成订阅时请改用网页抓取订阅。
- “来源返回 HTTP 203，不是正常的订阅响应”：200 以外的 2xx 状态，常见于中间代理改写或对方的拦截机制。
- “RSS XML 无效或包含不支持的实体声明”：内容确实是 XML，但格式错误或带有 DTD／实体声明。出于安全考虑这类 XML 一律拒绝，这一点没有变化。
- “NCBI E-utilities …”开头的错误来自 PubMed 检索订阅：429 表示请求过于频繁（可填写 NCBI API Key 提高限额），“NCBI 拒绝了 API Key”请在设置中检查或删除 Key，“返回错误：…”是 NCBI 对查询式的说明，可在构建器里打开预览核对查询式。
先打开订阅详情的“运行日志”，在抓取记录中筛选“失败”，对照时间、触发来源和失败原因排查。HTTP 401/403 通常需要检查 Cookie 或访问权限；没有有效条目时，检查页面结构、匹配规则、登录状态和渲染等待。仅没有新文章不属于故障。失败不会清空已有文章。
日志显示“通知：未启用”时检查“设置 → 通知”是否至少启用了一个渠道；其余情况逐个渠道显示状态，例如“Bark 已发送 · Webhook 待重试（…）”。“待发送／待重试”表示仍在重试；“发送失败”时先在对应渠道点“发送测试通知”，检查服务到推送服务的网络、地址和令牌（Bark 设备密钥、Webhook 接收端是否返回 2xx、ntfy 主题和令牌、Telegram 机器人能否给该 Chat ID 发消息）。提示“地址被网络安全策略阻止”说明目标解析到内网、回环或云元数据地址，确需使用时请管理员把精确的 主机:端口 加入网络白名单。原始响应、地址、令牌和认证头不会出现在日志里。持续失败在成功告警后不会重复推送，抓取恢复成功后会重新允许下一次故障告警。
“中断”表示服务重启前抓取未完成，不代表已验证目标网站失效，因此不单独触发告警；下一次实际抓取失败才会告警。升级前的历史不可回溯，超过网页配置保留天数的日志自动清理。