docs(readme): 令牌默认值语义改为 fail-closed,登记两个本地调试开关

第 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 生效)。
This commit is contained in:
JianFeeeee
2026-10-22 23:29:43 +08:00
parent cd108f8093
commit 745b8ea786

View File

@ -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 <NAVI_ADMIN_TOKEN>" \
http://<ip>: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`(默认关闭,勿用于部署)。
## 数据备份