From 745b8ea78679ac0ef6a1f954e0e4a3c4beb2ea18 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Thu, 22 Oct 2026 23:29:43 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E4=BB=A4=E7=89=8C=E9=BB=98?= =?UTF-8?q?=E8=AE=A4=E5=80=BC=E8=AF=AD=E4=B9=89=E6=94=B9=E4=B8=BA=20fail-c?= =?UTF-8?q?losed=EF=BC=8C=E7=99=BB=E8=AE=B0=E4=B8=A4=E4=B8=AA=E6=9C=AC?= =?UTF-8?q?=E5=9C=B0=E8=B0=83=E8=AF=95=E5=BC=80=E5=85=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 第 1 步把 history-server 的鉴权改成 fail-closed 后，README 的环境变量表 还写着「空（不鉴权）」—— 文档与代码相反，照它「不配也行」去部署的实例 升级后会全站 401。这正是 fail-closed 想要的结果，但必须说清楚， 否则第一个撞上的人会以为是我们改坏了。 改动（只动这两处，没有重写 README）： 1. 环境变量表（README:156-157）： - `NAVI_SYNC_TOKEN` / `NAVI_ADMIN_TOKEN` 的默认值列改为 「空 → 拒绝所有请求（fail-closed），生产必须配置」，并说明未配置时 哪些接口会拒绝（不是笼统写「必填」）。 - 新增 `NAVI_ADMIN_ALLOW_UNAUTHENTICATED` 与 `NAVI_HISTORY_ALLOW_UNAUTHENTICATED` 两行，并补一段注意事项： 默认关闭、只在没配 token 时才起作用、仅限本机调试、 **两者不要混用**（前者只放开 admin-server，后者只放开 history-server）。 - 明确写出升级提示：「从旧版本升级且此前未配 token 的实例，升级后必须 补上这两个变量，否则会撞上 401」。 2. 「实现参考」段（原 README:1080-1081）核对后已不准确，改为按服务分别写清： - history-server：/sync 与列表读校验 NAVI_SYNC_TOKEN；清空（DELETE /）、 /item 逐条删除、/rebuild 校验 NAVI_ADMIN_TOKEN（未配 admin token 时 接受 NAVI_SYNC_TOKEN 作为等价凭据，兼容旧部署）； - admin-server：所有管理 API（含 /admin/api/history*）一律校验 NAVI_ADMIN_TOKEN； - 并点明「任一服务未配置对应 token 时拒绝所有请求（401），不再有 『不配就放行』的旁路」。 刻意未写进文档的（本轮不扩大范围，已在任务里确认不动）： - `/stats`、`/nav-visit` 仍未鉴权 —— 因此文档里描述的是「哪些接口会拒绝」， 而不是笼统的「历史接口全拒绝」，避免再次写出与代码不符的文档。 - `NAVI_HISTORY_ALLOW_UNAUTHENTICATED` 没有写进 deploy/zd-host.sh 的 env 继承白名单（默认就该不设）。 核对方式：逐个变量 grep 非测试源码，确认 4 个变量都真实存在且引用位置与 文档描述一致（NAVI_HISTORY_ALLOW_UNAUTHENTICATED 只在 history-server 生效， NAVI_ADMIN_ALLOW_UNAUTHENTICATED 只在 admin-server 生效）。 --- README.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 36ccca8..162699f 100644 --- a/README.md +++ b/README.md @@ -153,12 +153,26 @@ icon: fas fa-star # Font Awesome | 变量 | 说明 | 默认 | |------|------|------| -| `NAVI_SYNC_TOKEN` | 浏览器扩展同步历史令牌 | 空（不鉴权） | -| `NAVI_ADMIN_TOKEN` | 管理后台/API 写操作令牌 | 空（不鉴权） | +| `NAVI_SYNC_TOKEN` | 浏览器扩展同步历史令牌；未配置时历史读写接口（`/sync`、列表、清空、逐条删除、`/rebuild`）**拒绝所有请求** | 空 → 拒绝所有请求（fail-closed），**生产必须配置** | +| `NAVI_ADMIN_TOKEN` | 管理后台/API 写操作令牌；未配置时管理接口**拒绝所有请求** | 空 → 拒绝所有请求（fail-closed），**生产必须配置** | +| `NAVI_ADMIN_ALLOW_UNAUTHENTICATED` | 仅本机调试：允许**未配置 token** 时访问管理 API。默认关闭，绝不要用在线上 | 关 | +| `NAVI_HISTORY_ALLOW_UNAUTHENTICATED` | 仅本机调试：允许**未配置 token** 时访问历史接口（`/sync`、列表、清空、逐条删除、`/rebuild`）。默认关闭，绝不要用在线上 | 关 | | `SEARXNG_BASE_URL` | 对外访问地址，影响搜索结果链接 | `http://localhost:3003` | | `NAVI_PORT` | compose 对外端口 | `3003` | | `NAVI_FAVICON_PROXY` | 抓历史图标用的代理；留空自动复用 `searxng-settings.yml` 的 `outgoing.proxies` | 空 | +> ⚠️ **两个 token 的默认值语义是「拒绝」而不是「不鉴权」**（fail-closed）。 +> 两个变量都留空时，管理接口与历史接口会返回 **401**（JSON 体里带 `error` 与修复指引）， +> 表现为「全站 401 / 管理页打不开」。这是刻意设计：没配凭据就不该放行。 +> 从旧版本升级且此前未配 token 的实例，升级后必须补上这两个变量，否则会撞上 401。 +> +> 两个 `*_ALLOW_UNAUTHENTICATED` 开关**不要混用**： +> - `NAVI_ADMIN_ALLOW_UNAUTHENTICATED` 只放开 **admin-server** 的管理 API； +> - `NAVI_HISTORY_ALLOW_UNAUTHENTICATED` 只放开 **history-server**（历史接口）。 +> +> 两者都**只在对应服务没配 token 时才起作用**；一旦配了 token，就必须带对 `Authorization: Bearer`。 +> 它们只为「本机直接跑 handler / 调试」存在，部署时不要设置。 + ## 浏览器扩展 ### 安装（两种方式） @@ -1077,8 +1091,15 @@ curl -H "Authorization: Bearer " \ http://:3003/admin/api/item ``` -> 实现参考：`history-server` 的 `/sync` 校验 `NAVI_SYNC_TOKEN`， -> `admin-server` 的写操作校验 `NAVI_ADMIN_TOKEN`。 +> 实现参考（鉴权是**默认拒绝**的，两个服务各自校验）： +> - `history-server`：`/sync` 与历史列表读接口校验 `NAVI_SYNC_TOKEN`； +> 清空（`DELETE /`）、`/item` 逐条删除、`/rebuild` 校验 `NAVI_ADMIN_TOKEN` +> （未配置 admin token 时接受 `NAVI_SYNC_TOKEN` 作为等价凭据，兼容旧部署）。 +> - `admin-server`：所有管理 API（含 `/admin/api/history*`、路由表、站点信息、门户口令） +> 一律校验 `NAVI_ADMIN_TOKEN`。 +> +> 任一服务**未配置对应 token 时拒绝所有请求（401）**，不再有「不配就放行」的旁路； +> 本机调试需要放行时，用上表的 `NAVI_*_ALLOW_UNAUTHENTICATED`（默认关闭，勿用于部署）。 ## 数据备份