Note Whitebook

站点交接白皮书 · 2026-11-11 全天改造

记录一次对个人站点的五项改造：去考研化、登录态共享修复、笔记公私与授权、白皮书板块上线、版本方向与差异同屏。涵盖环境速查、鉴权链路、权限模型、白皮书体系、版本溯源、部署铁律与遗留事项，供后续维护者快速接手。

这是一篇打了白皮书标记的笔记：按笔记管理（版本、权限都在笔记体系里），但用白皮书版式阅读与编辑。

笔记型来自笔记 · 公开笔记 v1

查看

站点交接白皮书 · 2026-11-11 全天改造

给下一个 AI 会话与未来维护者的一页纸。先结论：今天完成五项改造——站点去考研化、登录态全站共享修复、笔记公私与按人授权、白皮书板块上线、版本方向与差异同屏。全部已上线并回归通过。

一、环境与服务速查

项	值
项目根	`C:\Users\cag\WorkBuddy\2026-10-11-06-00-16`
门户	静态页 + `server.js`（计划任务 KaoyanPortal，端口 3000），公网 cag.quest
词汇站	`kaoyan-vocab`（KaoyanNextServer，next start 生产模式）
笔记站	`notes`（KaoyanNotes，端口 3102，经门户 `/notes/` 反代）
隧道	KaoyanTunnel → cag.quest
Node	`.workbuddy/binaries/node/versions/22.22.2-6/node.exe`
门户用户库	`portal/data/portal.db`（node:sqlite），会话 Cookie `pf_sid`
笔记站库	`notes/prisma/notes.db`，Prisma client 输出 `notes/generated/db`
共享密钥	`portal/data/portal-secret.txt`，门户与笔记站两侧热感知

二、鉴权链路（今天修过，别再踩）

门户验证 pf_sid 后会剥掉客户端自带的 X-User-* 头，验证通过才注入真实身份转发给笔记站。裸带身份头测试必然拿到匿名，这不是 bug。
笔记站 lib/identity.ts 校验 x-portal-secret，再从 X-User-* 还原 Viewer。
历史事故：门户进程内存缓存旧密钥，密钥文件轮换后笔记站把一切经门户的请求判为匿名。现已改为每次请求比对密钥文件 mtime，热生效，重启不再必要。
测试会话规矩：往 portal.db 插 ua='test' 的会话做验证，用完必删。

三、权限模型（笔记站）

操作	规则
读公开	任何人
读私密	所有者 / 管理员 / `read`、`write` 授权者 / 检索 `@用户名` 命中
写公开	登录用户（匿名只读）
写私密	所有者 / 管理员 / `write` 授权者
改公开状态、管理授权	仅所有者 / 管理员
子笔记	授权不继承；私密父下生成的子笔记自动继承私密

核心判定入口：lib/visibility.ts（纯规则）+ lib/grants.ts（查 NoteGrant 的包装）。API 一律走这两个入口，不要自己写 if。

四、白皮书体系（今天的重心）

三类：meta 元白皮书（进 AI 提示词，无父级）/ guide 引导型（分场景分类）/ note 笔记型（笔记打 isWhitebook 标记聚合，仍按笔记管理）。
板块 /notes/whitebook，暖纸色系（--paper* 变量；.wb-page 内把冷蓝语义变量整体重定向，复用组件自动变暖）。
只迭代版本，不删除：DELETE 返回 405；编辑与入库仅管理员。
入库评判：四维（结构/可执行/覆盖/冗余）0–100，高分在前；超 2600 字或 complexity=high 自动按二级标题切子白皮书挂原文。
元白皮书守门：新版与稳定版 AI 对比，判 wrong → 不切换、标 isUsable=false 回滚；提示词改从数据库取 notes-core 当前版，改版即同步全站提示词。
生成时可选白皮书：引导型→格式引导，笔记型→风格引导；抽屉（桌面 62% 宽）内可改后运行，改动可存为新版并记录修改人。

五、版本与溯源

笔记版本永不覆盖；NoteVersion 新增 direction / keywordHints / whitebookRefs / editedBy。
版本方向三要素：关键词（作为必须覆盖的写作要点，同时进关键词字典）、白皮书引导、自由方向文本。
详情页有行级 LCS 差异同屏（左右版本可切、可互换）与「本版溯源」条。

六、部署铁律

ops/launch.ps1 必须带 UTF-8 BOM。无 BOM 时 PowerShell 5.1 按 GBK 解析中文注释，直接语法错，计划任务起不来（今天踩过，lastResult=1）。
改 prisma schema 后：直接重启 KaoyanNotes 即可，launch.ps1 的 notes 分支启动前自动 prisma generate。
词汇站/笔记站改代码要 next build 再重启计划任务；门户是静态文件改完即生效（server.js 除外，需重启）。
Stop-ScheduledTask 不带走子进程，孤儿进程会锁 Prisma 引擎 DLL——client 已输出到独立目录 generated/db 规避，launch.ps1 重启前也会按端口清理。

七、遗留事项

早前「共享密钥不一致导致登录态失效」这一错误，归档到哪份白皮书仍未定（笔记站 whitebook.md 全文进 AI 提示词，归档需权衡）。
词汇站的元白皮书改版后需手动点「同步到站点」写回 kaoyan-vocab/whitebook.md。
目录名 kaoyan-vocab 与服务器注释等历史痕迹仍在，按「不大修大改」约定保留。