rainblogweb/docs/refactor-plan.md

RainWeb 优化重构实施计划（P0 / P1 / P2）

依据：数据库优化师（better-sqlite3 选型调研）、后端架构师（架构评审）、应用安全工程师（安全审计）、前端路由专项深挖 四份报告合并。 数据库路线已定：better-sqlite3 + Node 22 LTS（放弃 sql.js 与 PostgreSQL）。 前端路由：用户确认问题很大 → 按「方案 A 止血 → 方案 B 协议收编」两步走（见 P1-14 / P2-19）。 本计划仅执行顺序与细节，未开始任何代码改动。

全局前提（每阶段执行前）

1. 备份：cp -r data data.bak-<日期>（data/rainweb.db 是唯一数据文件）
2. 每阶段一个 git commit，commit message 中文，如 P0: 删除 Web 更新链路，修复鉴权漏洞
3. 无测试环境，验证方式 = curl 接口 + 浏览器刷新 + node cli.js 命令

---

P0 紧急止损（独立项，可并行，约半天）

P0-1 删除 Web 更新链路（消除 R6 + .git 覆盖风险）

• server.js：删除 84-165 行 /api/update/check + /api/update/run，保留 /api/version（81-82 行）
• public/js/admin.js：删除 checkUpdate/runUpdate 函数及更新按钮 UI（约 692-731 行区域）
• cli.js：cmdUpgrade 保留 git pull 分支（走本地 Gitea origin），删除非 git 仓库的 zip 下载分支（266-346 行区域）
• 理由：用户即上游，zip 覆盖式更新是错误范式；/api/update/run 无鉴权=RCE 面，且 exclude 未排除 .git 会冲掉 git 历史
• 风险：低。注意前端引用一并删除，避免 404
• 验证：curl /api/update/check → 404；admin 面板打开控制台无报错；node cli.js upgrade 走 git pull 分支正常

P0-2 JWT_SECRET 随机化（消除 R4）

• middleware/auth.js：改为 process.env.JWT_SECRET 必须存在（长度 ≥32），否则启动失败；删除硬编码回退
• server.js start()：首次启动若无 JWT_SECRET，用 crypto.randomBytes(48).toString('hex') 生成并写入 .env.json
• 风险：低；已签发旧 token 全部失效（自部署可接受）
• 验证：删 .env.json 重启 → 自动生成 secret；登录 → curl /api/auth/me 200

P0-3 setup 接管漏洞（消除 R5）

• routes/setup.js：POST /complete 加 authMiddleware, adminOnly；GET /setup/status 响应移除 default_password 字段（只保留 setup_complete）
• 风险：低
• 验证：未登录 curl -X POST /api/setup/complete → 401；登录后正常

P0-4 proxy SSRF 最小防护（消除 R3 的 SSRF 部分）

• routes/proxy.js：GET /fetch 加 authMiddleware, adminOnly；new URL(target) 后校验 hostname 非 127.0.0.1/::1/localhost/10./192.168./172.16-31./169.254./fc00:/fe80:
• 风险：低（本功能只服务于 admin_links 面板嵌入）
• 验证：未登录请求 → 401；/api/proxy/fetch?url=http://127.0.0.1:3001/ → 拒绝

P0-5 邮件验证码回显与滥用（消除 R7）

• routes/email.js：send-verify 响应删除 code 回显；验证码生成改 crypto.randomInt(10000000, 100000000)；补回"删除 pending 后重建"的 bug（或废弃该接口由 register 内联重发）
• 风险：低
• 验证：调 send-verify → 响应无 code 字段；邮件仍能收到验证码

---

P1 安全加固 + 数据层统一（依赖顺序：11 → 12，其余独立）

P1-6 上传白名单 + /uploads 防护头（消除 R1）

• routes/upload.js：shaFileUpload 内校验 path.extname(...).toLowerCase() 在 ALLOWED_EXT = ['.png','.jpg','.jpeg','.gif','.webp','.pdf','.zip','.txt','.md'] 内，否则报"不支持的文件类型"；图片额外校验 file.mimetype 以 image/ 开头
• server.js:63：/uploads 静态服务加 X-Content-Type-Options: nosniff + Content-Security-Policy: sandbox; default-src 'none'；非白名单扩展名强制 Content-Disposition: attachment
• 风险：低；已有历史上传文件不受影响（仅新上传受限）
• 验证：登录后上传 x.html → 400；上传 png → 200；访问 /uploads/<hash>.png 响应头含 nosniff

P1-7 内容净化双端统一（消除 R2）

• ssr.js：引入 dompurify + jsdom（服务端），renderSSR 中 marked.parse 结果过 DOMPurify.sanitize；ssrPage 中 title/siteName/ogDesc 全部 HTML 转义，JSON-LD 用 JSON.stringify 序列化
• public/js/render.js：引入 DOMPurify（本地化到 public/js/vendor/ 或 CDN + SRI），marked.parse 结果同样过 sanitize
• 风险：中（渲染路径改动，需走查博客/论坛/SEO 页）
• 验证：发帖内容含 <img src=x onerror=alert(1)> → SSR 页与 SPA 页均不弹窗、标签被剥；正常 markdown 渲染不变

P1-8 登录限流 + 服务端验证码（消除 R8）

• 新增 express-rate-limit 依赖：/api/auth/login 15 分钟 10 次；/api/email/send-verify 60s/次
• routes/auth.js：login/register 按 captcha_login/captcha_register 设置服务端校验 captcha token（与 captcha.js 的 verify 存储联动，token 与 username 绑定）；routes/forum.js 发帖同理（captcha_forum）
• 删除 verifyCaptchaToken 桩函数（auth.js:39-52）
• 风险：中（验证码链路前后端要同步改）
• 验证：连错密码 11 次 → 429；开启 captcha_login 后登录需先过验证码

P1-9 密码箱解锁限流 + KDF 加固（消除 M1）

• routes/passwords.js：/unlock 加失败计数（3 次/5 分钟，指数退避）；解锁会话滑动过期替换一次性 setTimeout
• PBKDF2 迭代 100k → 600k（OWASP 2023 建议）；注意同步执行阻塞事件循环，可接受（单用户站）
• 风险：低
• 验证：连续输错 PIN 3 次 → 锁定提示；正确解锁正常；旧 PIN 密文在 KDF 迭代变更后需重设（set-pin 已存在）

P1-10 鉴权与信息收敛（消除 M2-M7）

• middleware/auth.js：adminOnly 增加 db.get('SELECT role FROM users WHERE id=?') 复查（M2）
• routes/blog.js：?all=1 加 authMiddleware, adminOnly；GET /posts/:id 未发布仅 admin/作者可见（M3）
• 错误信息收敛：routes/forum.js:21,35、server.js:163、routes/email.js:54,93 对外统一 { error: '操作失败' }，详情仅 console.error（M4）
• routes/email.js:17、auth.js:93、profile.js:25、proxy.js:22 的 rejectUnauthorized:false 收敛为配置项（默认关闭校验仅当 SMTP 自签时开启）（M5）
• public/js/passwords.js:113、forum.js:76：内联 onclick 字符串插值改 data-id + addEventListener 委托（M6）
• S3-3 escapeHtml 引号问题：escapeHtml 不转义 '/"，用于属性/JS 字符串上下文可注入断链（forum.js:76、passwords.js:113、admin.js:74/402-404）——新增 escapeAttr（全转义）用于属性上下文，或随 M6 的 data-id 改造一并消除；帖子标题/分类为他人可见，属存储型 XSS 面
• routes/profile.js：avatar 仅接受 /uploads/avatars/ 站内路径（M7）
• 风险：中；验证：逐项 curl 测试（未登录 401/403、草稿对匿名 404、报错无堆栈详情）

P1-11 cli.js 统一数据层（ora-2 P1-1）

• cli.js：删除 9-51 行重复封装（DB_PATH/getDb/dbRun/dbGet/dbAll），改为 const db = require('./db')；cmdStatus/cmdPassword/cmdCaptcha/cmdConfig 改用 db.get/db.all；各命令 await getDb()
• data.db 旧路径彻底退役（server.js 启动迁移逻辑保留，把旧文件搬进 data/）
• 风险：中低；验证：备份后依次跑 node cli.js status/config/password/captcha 全部成功且落库

P1-12 schema_version 迁移框架（ora-2 P1-2，依赖 P1-11）

• db.js：initTables() 收敛——"确保列存在"函数（幂等补列，逻辑同现有 try/catch）+ PRAGMA user_version 记录迁移版本；未来迁移写成 { version, up() } 数组顺序执行
• 风险：中；验证：旧库启动自动补列无报错；连续启动两次幂等

P1-13 deploy 脚本处置（ora-2 P1-3）

• 删除 deploy.sh + deploy.bat（指向 GitHub 旧仓库，对自托管用户无意义）；README 相关段落同步清理
• 风险：低；验证：ls 确认删除；README 无残留引用

P1-14 前端路由止血（方案 A，约 0.5 天）

专项深挖结论：PJAX 只替换 <main>、目标页 <script> 从不执行，而 5 个 PJAX 壳页各自加载不同共享脚本子集 → 从某些页面进入时目标页依赖缺失（结构性缺陷 S1-3）。已确认 bug：S1-1 首页空白、S1-2 个人中心空白、S1-3 脚本依赖矩阵、S2-1 监听器重复累积、S2-2 论坛详情后退进 SSR 页、S2-4 滚动不恢复、S2-5 登录态/设置变化后导航不刷新、S2-6 login/register 白跳。

• A1 PJAX_PATHS 收敛：router.js 只保留 5 个有 _pageConfig 的页面（/、/blog.html、/forum.html、/admin.html、/passwords.html）；移除 login.html/register.html/profile.html（整页导航约定，根治 S1-2、S2-6）
• A2 统一共享脚本集：5 个 PJAX 壳页 html 全部加载完整共享集（marked + render + captcha + music-embed + theme + api + nav + router），消除 S1-3 全部矩阵缺口
• A3 首页逻辑外部化：public/index.html:54-96 内联 HOMEPAGE 抽为 public/js/homepage.js 并注册进 _pageConfig（修 S1-1；顺带合并 S3-4 与 blog.js 的 loadSidebar 重复）
• A4 _loadScript 判重：router.js:91-99 加已加载检测，修 S2-1 监听器累积
• A5 popstate 分支 + 滚动：popstate 识别 e.state.forumPostId 直接还原论坛详情（修 S2-2 不再 reload 进 SSR 页）；navigate 时 scrollTo(0,0)（修 S2-4）
• A6 导航重渲染钩子：loadPage 完成后调 NAV.render?.()（修 S2-5）
• 风险：低（login/register/profile 当前本就走整页兜底，无回归面）；A2 可能触发 S3-2 重复定义，但各文件实现相同无碍
• 验证：passwords.html 整页进入 → PJAX 依次进博客（markdown 正常）/论坛（发帖弹验证码、详情正常）/首页；论坛详情后退回 SPA 列表无 reload；循环 PJAX 5 次 forum.js 只加载一次

---

P2 数据库换轨 + 工程卫生（依赖 P1-11/P1-12）

P2-15 better-sqlite3 迁移（lib-1 调研结论）

• 前置：Node 升 22 LTS（宝塔 Node 版本管理器 / nvm）；README 与 Docker 示例同步（node:20 → node:22）
• 依赖：npm install better-sqlite3（v13，预编译随包，宝塔 glibc x64 免编译）
• db.js：initSqlJs() 异步初始化 → new Database(DB_PATH) 同步；run/get/all 重写：
  • run → db.prepare(sql).run(...params) + info.lastInsertRowid
  • get → stmt.get(...params)；all → stmt.all(...params)
  • 删除 saveDb()/db.export()（SQLite 事务原生落盘）；返回签名不变，40+ 业务调用点零改动
  • initTables() 的 CREATE TABLE IF NOT EXISTS 与幂等补列原样保留（兼容旧库）
• cli.js：同套改写（P1-11 统一后只需改 db.js 一处）
• routes/import.js：上传文件先落临时路径再 new Database(tmpPath) 只读打开，exec 数组结果改对象结果，用后 close
• 数据迁移：零迁移——现有 data/rainweb.db 是标准 SQLite 文件，直接打开
• 风险：中；验证：备份 data/ 后启动 → 管理后台 CRUD 走一遍 → node cli.js status/password → sqlite3 data/rainweb.db "PRAGMA integrity_check;"

P2-16 死代码 + 前端重复清理

• 删除 routes/links.js（引用不存在的 links 表，挂载即崩）、public/js/main.js（无引用）、public/js/passwords.js 内重复的 deleteFromDetail
• S3-1：register.html:85 与 :92 重复调用 CAPTCHA.checkRequired('register')，删一行
• S3-2：escapeHtml/closeDialog/openDialog/showSnackbar 在 nav/render/blog/forum/admin/passwords/index/profile 各定义一份 → 收敛到 nav.js（或公共 util）单份定义；admin.js 同文件内 6 个函数重复定义（setNavStyle/setCardStyle/previewWallpaperUrl/removeWallpaper/loadWallpaperList/selectUploadedWallpaper/uploadWallpaper，admin.js:179/263 等）删后一份
• 风险：低；验证：全站走查控制台无 404、无重复定义报错

P2-17 版本单源 + 文档同步

• VERSION 文件为唯一源（server.js:81 已读它）；cli.js HELP 版本改读 VERSION；package.json version 与 VERSION 同步
• README.md：Node 要求改 >= 22 LTS；删除更新/部署章节中 GitHub 引用
• AGENTS.md：数据层章节重写（better-sqlite3、无 saveDb、单文件直写、cli.js 已统一）
• 风险：低；验证：node cli.js help 与 /api/version 显示一致

P2-18 可选加固（H 系列，按需确认）

• H1：helmet() + 收紧 CSP（CDN 引入 marked 的 5 个页面加 SRI）——建议做
• H3：验证码 Math.random() → crypto.randomInt（auth.js:80、email.js:63、profile.js:68）——建议做，改动极小
• H9：bcrypt cost 10 → 12；注册用户名格式校验——建议做
• H2：JWT 从 localStorage 改 HttpOnly cookie——改动大（前端 api.js 全量），默认不做，列入后续
• H4：首启随机管理员密码——与 setup 向导冲突，默认不做（P0-3 已封堵接管面）

P2-19 前端路由协议收编（方案 B，约 1.5-2 天，依赖 P1-14）

方案 A 修完当前全部可复现 bug；方案 B 是防复发投资——解决"下一次加页面还会不会踩坑"。

• B1 单一注册表：PAGES 配置对象 path → { pjax, title, scripts, global, init }，PJAX_PATHS/_pageConfig/脚本依赖全部由它派生；命中且 pjax:true 才拦截，其余整页导航（无兜底分支）
• B2 页面结构规范：每个 PJAX 页 <main data-page="blog">，router 读 data-page 查注册表，不再硬编码路径数组；共享依赖在注册表声明，_loadScript 按"已加载集合"增量补齐
• B3 页面逻辑全外部化：HOMEPAGE（P1-14 A3 已抽）、profile 逻辑（profile.html:43-180）抽为独立 js；内联 <script> 仅保留极少量数据初始化；统一 window[global].init() 协议
• B4 pushState/popstate 统一由 router 管理：页面不再自行 pushState 非标准 state；论坛/博客详情作为"子路由"由注册表定义，popstate 由 router 解析还原（根治 S2-2/S2-3）
• B5 生命周期钩子：注册表条目可选 destroy()，音乐嵌入/定时器/事件解绑在此处理（根治 S2-1 结构性累积）
• 整页应用（login/register/write/embed/forum-manage/setup）标记 pjax:false 不参与 PJAX，保留内联脚本
• 风险：中（popstate 语义变化与音乐嵌入销毁/重建是重点回归面；11 个 html 全动，必须全导航路径走查）
• 验证：全导航路径走查（每页进出、后退/前进、刷新直链、登录/退出、音乐嵌入显示与自动隐藏）；控制台零报错
• 明确不做（方案 C）：引入构建链/框架——违反无构建约定，对单人无测试项目负收益

---

P0-1..P0-5  （独立，并行）          ≈ 半天
P1-6..P1-10 （安全加固，独立并行）   
P1-11 cli统一 → P1-12 schema_version  ≈ 1-2 天
P1-13 / P1-14（路由止血，独立）      ≈ 0.5 天
P2-15 better-sqlite3（依赖 P1-11/12）≈ 1 天
P2-16 / P2-17 / P2-18（独立）
P2-19 路由协议收编（依赖 P1-14）    ≈ 1.5-2 天

若时间有限：P0 + P1 全部完成后项目即处于"安全 + 可正常使用"状态（路由 8 个 bug 全修）；P2-19 是防复发投资，可最后做或延后。

交付节奏

每个 P 阶段结束：跑通验证清单 → git commit → 可随时暂停（数据文件备份在手，sql.js→better-sqlite3 前任何时刻可回滚）。