docs: SPA 管理凭据 trust-root 同步(README/zh-CN/reference 三处措辞 + 锚点修正)

承接 800d6e0(SPA 凭据改用 CONFIG_ENCRYPTION_KEY):

- README.md §5、README.zh-CN.md §5:trust-root 段落补齐「配置密钥即管理密钥」
  的事实陈述,消除「Redis ACL 密码」的残留耦合叙述。
- docs/reference.md §3 Trust root:1:1 重写为配置密钥派生路径,移除不存在的
  "refresh loop" 叙述(实际为 refresh_business_config 单次调用 + guard)。
- docs/reference.md §3 锚点修正:expires_in 引用 notify.rs:700→:787
  (refresh_business_config 现位于 :717,expires_in 在 :787)。

交付方:文件规划助手(任务 01a0e379)。文档校验器 0 error,负向对照 4/4。
This commit is contained in:
anonsaber 2026-09-28 15:08:04 +08:00
parent afa6cec8ef
commit e502c40a9e
3 changed files with 22 additions and 13 deletions

View File

@ -81,9 +81,11 @@ that must stay cheap should watch the gateway's aggregated `/healthz`.
> All state lives in Redis; the process reads only two environment variables and writes > All state lives in Redis; the process reads only two environment variables and writes
> nothing to disk. > nothing to disk.
One corollary matters for setup: the bootstrap one-shot token is the **password component of One corollary matters for setup: the SPA admin credential — and therefore the bootstrap
`REDIS_URL`**. The Redis ACL credential is therefore both the application connection trust root — is `CONFIG_ENCRYPTION_KEY` itself, the single 32-byte hex value you supply at
credential and the trust root for bootstrap — keep it private and rotate it as one value. startup. It is only compared in constant time, and is never echoed, logged, or stored. The
Redis ACL password, if you have one, authenticates the Redis connection alone and is not
the credential for any HTTP endpoint.
## 5. Where to read more ## 5. Where to read more

View File

@ -74,8 +74,7 @@ docker run --env-file .env -p 8080:8080 messageweave:latest
> 所有状态都在 Redis 里;进程只读两个环境变量,不写任何磁盘。 > 所有状态都在 Redis 里;进程只读两个环境变量,不写任何磁盘。
有一条推论与部署直接相关:bootstrap 的一次性 token 就是 **`REDIS_URL` 的密码分量**。因此 有一条推论与部署直接相关:SPA 管理凭据——也就是 bootstrap 的信任根——就是 `CONFIG_ENCRYPTION_KEY` 本身,即启动时提供的那个 32 字节 hex 值。它只做常数时间比较,绝不回显、记录或落盘。Redis ACL 密码(如有)只认证 Redis 连接本身,不是任何 HTTP 端点的认证凭据。
Redis ACL 凭据同时是应用连接凭据与 bootstrap 信任根——请单独保管并按单一值轮换。
## 5. 去哪读更多 ## 5. 去哪读更多

View File

@ -34,13 +34,14 @@ Conventions used throughout:
Notes: Notes:
- `config:business:revision` is an **atomic Redis `INCR`**, not a read-modify-write. Hot reload - `config:business:revision` is an **atomic Redis `INCR`**, not a read-modify-write. Every
compares it: the refresh loop only rebuilds the worker when the remote revision exceeds the request-bearing entry point calls `refresh_business_config` (notify.rs:717), which only
cached local value, which is what keeps a single bad poll from turning into a hot retry loop rebuilds the worker when the remote revision exceeds the cached local value
(notify.rs:627-650). (notify.rs:722-724) — that guard is what keeps a stale or malformed snapshot from turning
into a rebuild loop.
- `config:admin_session` carries no TTL metadata beyond the literal `EX 900` passed at write - `config:admin_session` carries no TTL metadata beyond the literal `EX 900` passed at write
time; the handler reports the same window in its response body as `expires_in: 900` time; the handler reports the same window in its response body as `expires_in: 900`
(notify.rs:700). (notify.rs:787).
- `config:enabled` is consulted as a gate; missing or `false` keeps business processing off. - `config:enabled` is consulted as a gate; missing or `false` keeps business processing off.
### 1.2 AI consent ### 1.2 AI consent
@ -310,9 +311,16 @@ compatibility. Recognised names, unprefixed unless noted:
The single prefixed name is `TELEGRAM_CHAT_ID`. Anything else documented as The single prefixed name is `TELEGRAM_CHAT_ID`. Anything else documented as
`TELEGRAM_BOT_TOKEN` or similar is a documentation error, not a supported variable. `TELEGRAM_BOT_TOKEN` or similar is a documentation error, not a supported variable.
**Trust root.** The bootstrap one-shot token is the password component of `REDIS_URL` **Trust root.** The SPA admin credential is `CONFIG_ENCRYPTION_KEY` itself: read at startup
(main.rs:87-91). The Redis ACL credential is therefore simultaneously the application (main.rs:49) and held as `admin_token` (main.rs:95), it is checked in constant time by
connection credential and the trust root for bootstrap. `worker_authorized` (notify.rs:445; compare at notify.rs:1135) at the top of both
`POST /api/bootstrap` (notify.rs:604) and `POST /api/admin/session` (notify.rs:774). It is
only compared against the request bearer — never echoed, logged, or stored. The session
issued by `/api/admin/session` is a freshly generated random 32-byte hex token
(notify.rs:778-787), never the credential; only its digest is retained in Redis under
`config:admin_session`. `REDIS_URL` is the Redis connection string alone: an ACL password in
it, if any, authenticates the Redis connection and is not the credential for any HTTP
endpoint.
--- ---