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:
29
README.md
29
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 <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`(默认关闭,勿用于部署)。
|
||||
|
||||
## 数据备份
|
||||
|
||||
|
||||
Reference in New Issue
Block a user