配置参考

English · 简体中文

标准部署无需 .env：启动 Compose 后按 Nginx 模板转发即可。应用和服务器高级设置在网页“设置”中管理；下表环境变量仅用于首次初始化及部署引导。

变量	默认与用途
`FEEDLANTERN_VERSION`	Compose 镜像标签，默认 `latest`；跟随通过全部 CI 的 `main`，可按需覆盖
`PUBLIC_ORIGIN`	`http://127.0.0.1:4321`；本机反代请求自动使用转发域名，无需配置
`HOST` / `PORT`	源码 `127.0.0.1` / `4321`；容器内监听 `0.0.0.0:4321`
`DATA_DIR`	源码 `data/`；容器 `/app/data`
`COOKIE_SECURE`	HTTPS 反代请求自动启用；可显式强制开启
`TRUSTED_PROXIES`	默认空，不信任转发 IP；允许明确 IP/CIDR，逗号分隔。仅首次初始化时导入，且 Compose 不会把它传进容器；Docker 部署请在「设置 → 服务器与网络」里填写，步骤见 Nginx
`ALLOWED_TARGET_HOSTS`	默认空；确有需求时精确放行内网 `host:port`，逗号分隔。同样适用于网络配置中的代理地址，例如局域网代理 `192.168.1.10:1080`
`DNS_OVER_HTTPS`	默认 false，Fake-IP DNS 环境可显式 true，查询仍执行地址安全校验；使用网络配置代理的订阅经同一代理查询
`BACKGROUND_CONCURRENCY`	默认 1，允许整数 1–4；刷新与批量识别共享容量。同一来源 hostname（跨协议、端口）串行，编辑会话独立
`BROWSER_EXECUTABLE_PATH`	默认使用随 Playwright 安装的 Chromium
`PLAYWRIGHT_BROWSERS_PATH`	Docker 固定 `/ms-playwright`；源码测试与安装必须使用同一值
`DEFAULT_LOCALE`	默认 `en`，可设 `zh-CN`；兜底语言，见界面语言

网页加载默认等待 1000 毫秒，允许 0–10000；刷新间隔 5–1440 分钟，默认 60。保存的规则用于预览与后台刷新。每个订阅默认输出 100 条，可在订阅设置中调整为 10–500 条；网页订阅保留 max(200, 输出条数) 条历史，RSS 翻译订阅保留 max(100, 输出条数) 条。条目过滤的正则每条不超过 200 个字符、每类最多 30 条，单个订阅运行超过 100 毫秒会被中断。日志、翻译事件和缓存同样有上限，数据库体积保持稳定，见升级维护。

Cookie 明文仅在输入和服务端实际抓取时使用，查询接口仅返回元数据。本机 master.key 与数据库必须一起保管；丢失密钥无法读取原数据库中的 Cookie 和 RSS 密钥。跨服务器优先使用网页加密备份恢复。

默认阻止私网、回环、链路本地及云元数据抓取地址，并校验 DNS、重定向与浏览器请求。订阅的网络配置使用代理时，代理地址按同样规则校验，目标网址仍在本机解析和校验，代理只收到已校验的 IP。放行一个局域网代理意味着经它访问的流量不再受本机内网拦截约束，只放行可信的代理。不要为了一个网站而放开整个网络。运行目录、Cookie、备份和 .env 均不提交到 Git。

反代域名仅接受回环地址或私有网络中的直接代理（含 Docker 网桥）发来的 X-Forwarded-Host 和 X-Forwarded-Proto。Nginx 必须覆盖这两个头，容器端口保持绑定 127.0.0.1；客户端 IP 的信任仍由 TRUSTED_PROXIES 单独控制，默认登录限速按代理连接来源共享：检测到转发请求但未设置时，日志会提示一次，此时 8 次失败会锁定所有人 15 分钟，请按Nginx 指南填写代理地址。

资源较弱或订阅集中在同一站点时保留默认 1；有多个独立站点且内存有余量时，可在 .env 设置 BACKGROUND_CONCURRENCY=2 并重启。4 仅用于资源充足且已测量的环境；并发减少排队，不保证单个抓取更快。测试方法与测量结果见性能验证。

界面语言

界面、服务端错误提示、存储的日志文案和通知支持 English（en）与简体中文（zh-CN）。

界面：每个账号在“设置 → 账号与密码”或顶栏选择的语言保存在服务端，各设备一致；未选择时按浏览器偏好语言显示。登录和初始化页按浏览器语言显示，并提供语言切换。
接口：错误返回稳定的 code（见 Agent CLI 与 MCP）和本地化的 message，语言按账号偏好，其次按请求的 Accept-Language。响应还带有文案键 messageKey，网页界面据此按自己的语言渲染。
离线产生的文案：抓取日志、批量结果、翻译进度和通知（Bark、Webhook、ntfy、Telegram）按订阅所有者的语言写入：用户的选择，其次是其最近一次登录时浏览器请求的语言。
DEFAULT_LOCALE：以上都无法确定时的兜底语言，例如没有可用 Accept-Language 的脚本请求、既未选择语言也未在升级后登录过的账号、其他语言访问者看到的订阅预览页。未设置时为 en。中文实例可在 .env（或 Compose 环境变量）设置 DEFAULT_LOCALE=zh-CN 后重启。
升级：升级前已有的账号自动设为简体中文，界面不会因为升级变成英文；旧版本的完整备份恢复后同样为简体中文。
订阅内容不受影响：RSS、Atom、JSON 输出保持原有语言，翻译订阅按目标语言输出（<language> 随之），其他订阅按来源内容输出；只有 FeedLantern 为未翻译订阅生成的频道描述按所有者语言书写。
服务端日志统一为英文。pnpm admin:reset 按终端语言（LANG、LC_ALL）显示。

网页管理应用与服务器设置

管理员打开“设置 → 日志与显示”，可以配置订阅视图、日志保留天数（1–365，默认 30）和每个订阅保留的日志条数（10–1000，默认 100）；翻译服务和服务器与网络设置分别在“设置 → 翻译服务”“设置 → 服务器与网络”中，各组单独保存；每个用户在“通知”中配置自己的通知渠道（Bark、Webhook、ntfy、Telegram）和告警策略（失败阈值、推送超时、最大尝试次数、重试间隔、冷却时间及是否推送规则失效预警）。

“翻译服务”选择默认翻译服务（Google 免费翻译、DeepL、OpenAI 兼容接口），配置 DeepL API Key 与套餐、OpenAI 兼容接口的地址、模型、API Key 与可选系统提示词，以及每个服务各自的并发数（1–16）和请求启动间隔（0–5000 毫秒）。默认服务必须已配置才能保存。API Key 加密保存且不回显；使用本机或局域网模型需把精确的 host:port 加入网络白名单。详见使用指南。

“PubMed（NCBI）”配置 PubMed 检索订阅和检索预览所用的 NCBI E-utilities：可选的 NCBI API Key（加密保存、不回显，把限额从每秒 3 个请求提高到 10 个）和可选的联系邮箱（随请求发送给 NCBI，留空则不发送）。详见使用指南。

“服务器与网络”提供后台并发（1–4）、精确网络白名单、DNS over HTTPS、可信代理 IP/CIDR、公开访问地址、安全 Cookie、登录会话有效期及监听地址和端口。保存后，通知与抓取配置立即生效；网络或并发设置变化会关闭旧网页编辑会话。监听地址和端口需重启服务生效；容器端口映射仍需与部署配置匹配。

已有环境变量只在首次建立网页设置时导入，后续以网页保存值为准。删除旧的 BARK_URL 不会丢失已迁移的 Bark 配置。数据卷目录、浏览器安装路径和容器端口映射属于部署环境，不能通过应用配置移动数据库或安装浏览器。

故障告警与通知渠道

每个用户在“设置 → 通知”管理自己的告警：上方是渠道列表（Bark、Webhook、ntfy、Telegram），下方是对所有渠道生效的“告警策略”。可同时启用多个渠道，每个渠道单独启用／停用、保存和“发送测试通知”。测试使用当前填写的值发送一次，不保存设置，也不要求先启用；保存和导入本身不会发送通知。

抓取失败和 RSS 翻译失败告警都会发到告警产生时所有已启用的渠道。每个渠道分别重试并记录结果，抓取日志显示为“通知：Bark 已发送 · Webhook 发送失败（…）”。只要有一个渠道送达，这次故障就算已通知，不再重复推送；全部渠道都失败时，冷却期过后的新失败会重新告警。

告警策略

“连续失败多少次后列入需要检查”默认 3 次，每个用户可设置为 1–1000 的整数。达到次数后，该用户的订阅才因抓取失败进入“需要检查”；保存后列表、侧栏、仪表盘与用户管理按新阈值统计。未达到时仍能查看失败原因和日志，启用中的订阅显示“等待重试”。不必启用推送渠道；核心规则失效预警使用自己的判断规则，不受这个次数限制。字段为 bark.attentionFailureThreshold，旧配置和备份缺少时默认使用 3。

推送通知的阈值单独设置，默认 10 次，可在“连续抓取失败告警阈值（次）”中设置为 1–1000 的整数，设置为 1 即首次失败通知。定时、手动及编辑触发的实际抓取失败均计入同一订阅的连续次数，成功一次即清零；服务重启造成的中断不计为失败，重启和清理日志保留计数。调整推送阈值后在下一次失败时判断，不因保存配置补发通知。此阈值针对抓取失败，RSS 翻译故障仍使用独立的去重告警。

默认每次发送超时 10 秒、每个渠道最多 3 次，首次失败后等待 60 秒、后续等待 300 秒；次数耗尽后，后续抓取失败可在至少 30 分钟冷却后重新尝试。同一故障成功告警后不重复推送，抓取成功重置故障，不发送恢复消息。这些参数沿用原 Bark 设置的字段（bark.failureThreshold、bark.timeoutSeconds 等），升级后无需重新配置，并随配置导入导出和备份迁移；旧配置缺少阈值时默认使用 10。

“规则可能失效时通知”（ruleHealthAlerts，默认开启）控制条目数、标题或链接异常的规则失效预警；仅日期、图片或摘要缺失不推送通知。规则失效预警发到所有已启用的渠道，每次出现只推送一次，不使用失败阈值，与抓取失败告警分开去重；推送失败沿用上面的发送次数、重试间隔和冷却时间，冷却时间内重复出现的预警不再推送。旧配置和备份缺少此字段时视为开启。判断规则见使用指南。

启用、停用渠道或更换推送目标会取消此账号尚未发出的旧通知并重置推送去重状态，保留实际连续失败次数和“需要检查”状态；下一次实际抓取失败按新设置判断是否推送，保存本身不会补发。不影响其他用户。已经被接收的推送无法撤回；异常响应丢失或重启窗口可能重复推送。

Bark

在“Bark 推送地址”填写 Bark App 提供的设备 URL，打开“启用 Bark 告警”并保存，无需修改环境变量或重启服务。地址为包含设备密钥的 HTTPS URL，也支持带路径前缀的自托管服务。发送使用 Bark API V2 的 JSON POST /push。

Webhook

向你填写的 HTTP(S) 地址发送 POST，请求体为 JSON：

json

{
  "event": "fetch.failed",
  "title": "订阅灯：订阅抓取失败",
  "message": "示例订阅\n目标：example.com\n…\n原因：HTTP 503",
  "feedId": "…",
  "feedName": "示例订阅",
  "error": "HTTP 503",
  "time": "2026-10-22T08:00:00.000Z",
  "panelUrl": "https://feeds.example.com/#/feed/…/logs"
}

event 为 fetch.failed、translation.failed、rules.warning 或 test（测试通知的 feedId、feedName、error 为 null），同时放在 X-FeedLantern-Event 请求头中。title 和 message 按订阅所有者的语言书写，集成应按 event 判断。panelUrl 是订阅面板链接，基于“公开访问地址”生成。返回 2xx 视为成功，不跟随重定向。

可选“自定义请求头”每行一个 名称: 值，最多 10 个，例如 Authorization: Bearer …；Host、Content-Type、Content-Length 等由系统设置的请求头不能自定义。填写“签名密钥”后，请求带 X-FeedLantern-Signature-256: sha256=<hex>，值为以密钥对原始请求体计算的 HMAC-SHA256。接收端校验示例（Node.js）：

const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(request.headers['x-feedlantern-signature-256'] ?? ''));

ntfy

填写服务器地址（默认 https://ntfy.sh/，可填自建服务器，支持路径前缀）和主题；受保护的主题再填写访问令牌（以 Authorization: Bearer 发送）。通知以 JSON 方式发布到服务器根地址，点击通知打开订阅面板。公共服务器上的主题名相当于密码，请使用不易猜到的名称。

用 @BotFather 创建机器人获得 Bot Token，Chat ID 填数字 ID（群组通常为负数）或公开频道的 @频道名；机器人需要先能给对方发消息（私聊先向机器人发送 /start，群组和频道需加入机器人）。通知通过 https://api.telegram.org 的 sendMessage 发送，正文附订阅面板链接。

网络安全与密钥保存

所有渠道（包括 Bark）的出站请求都经过与网页抓取相同的网络安全策略：解析目标地址后拒绝内网、回环、链路本地和云元数据地址，并固定连接到检查过的 IP，不跟随重定向。确需推送到内网服务（例如自建的 ntfy 或 Webhook 接收端）时，由管理员把精确的 主机:端口 加入“服务器与网络 → 网络白名单”（或 ALLOWED_TARGET_HOSTS）。被拦截时测试通知会直接提示，抓取日志显示“地址被网络安全策略阻止”。

Bark 地址、Webhook 地址、签名密钥、自定义请求头、ntfy 访问令牌和 Telegram Bot Token 在数据库中使用本机 master.key 加密，个人设置接口按用户隔离，管理员可通过目标工作台管理。接口只返回配置状态、脱敏地址和请求头名称，不回显这些值；网页输入框留空表示保留原值，使用“清除配置”或“移除签名密钥／移除自定义请求头”后保存才会删除。ntfy 服务器、主题和 Telegram Chat ID 不属于密钥，会正常显示。错误信息和日志只记录固定文案，不包含地址或令牌。

仅管理员可导出轻量配置，其中携带该管理员自己的 Bark 设置和其他通知渠道（含密钥明文），以便完整迁移，请私密保管；完整备份使用备份密码加密，恢复时重新用目标服务器密钥加密。

升级至 v0.5.1 时，原全局 Bark 配置迁移给原管理员，其他账号默认关闭通知。抓取和翻译故障只通知订阅所有者；没有配置时不回退。测试按钮明确显示接收账号，保存本身不触发推送。

配置参考 ​

界面语言 ​

网页管理应用与服务器设置 ​

故障告警与通知渠道 ​

告警策略 ​

Bark ​

Webhook ​

ntfy ​

Telegram ​

网络安全与密钥保存 ​