Files

T

miaomiao 4d0ad9da68 docs: 添加 AGENTS.md 与 v2 重构计划文档

2026-08-06 21:22:04 +08:00

11 KiB

Raw Blame History

RainWeb v2 全面升级计划

v1（原生 HTML/CSS/JS + PJAX）→ v2（React 前后台分离 + 后端改造）。用户确认的选型全部定案，本计划为唯一执行依据。旧 docs/refactor-plan.md 的后端部分（P0/P1/P2 中安全与数据库项）并入本计划；其前端路由项（P1-14 方案 A、P2-19 方案 B）作废——由 React Router 取代。本计划未开始任何代码改动，待用户确认后按阶段执行。

0. 选型定案（已确认，不再变更）

项	决定
前端框架	React + Vite（TS 可选，见 §4.1）
前台 UI	不引 UI 库，手写组件 + 复用 `public/css/style.css`，UI 100% 还原
后台	独立应用（独立入口 `/admin`），引入 MUI
工程组织	单 Vite 项目多入口（前台 + 后台两个 HTML 入口）
SEO	保留 ssr.js 双轨（/blog/:id、/forum/:id、sitemap.xml 不变）
数据库	better-sqlite3 + Node 22 LTS（替换 sql.js）
后端改造	原 P0 止损 + P1 安全加固照旧执行

1. 目标架构

浏览器
 ├── 前台 SPA（/）            React + React Router，构建产物 + style.css，占位符机制保留
 │     └── 导航「管理后台」按钮 → 整页跳转 /admin（浏览器级导航，非 SPA 路由、非 iframe）
 ├── 后台 SPA（/admin）       React + MUI，完全独立入口/独立路由/独立登录态，外部面板嵌入保留
 └── SEO 直链（/blog/:id 等） ssr.js 服务端渲染（不变）
          ↓
Express 4（server.js）
 ├── /api/* 15 个路由模块（契约不变，前端重写以现有 API 为基）
 ├── 静态：构建产物 + uploads/ + public/wallpaper/
 └── SPA fallback：/ → 前台 index.html；/admin* → 后台 index.html
          ↓
better-sqlite3（data/rainweb.db，零迁移直接打开）

前后台关系：两个独立 React 入口（单 Vite 多入口构建），互相之间仅通过整页跳转连接。前台无后台路由、后台无前台路由；登录态共用（同一 JWT，localStorage）。

2. v1 → v2 保留 / 废弃清单

保留：后端全部（routes/、middleware/、db.js 逻辑、ssr.js、cli.js 改造后）、public/css/style.css（搬入前台）、public/wallpaper/、uploads/、API 契约。

废弃：public/index.html 等全部页面 HTML（改 React 组件）、public/js/ 全部（api/nav/router/theme/captcha/render/music-embed/main/blog/forum/admin/passwords → 拆成 React 模块）、PJAX 机制（router.js）、public/js/main.js 等死代码。

保留功能点（迁移时必须覆盖）：博客瀑布流、论坛多分类/子分类/发帖回复、密码管理器（PIN + AES-256-GCM，见 §4.4）、管理面板聚合（iframe 嵌入 + proxy 代理）、壁纸/磨砂玻璃/深浅色主题、音乐嵌入（自动隐藏）、验证码（内置/recaptcha）、邮箱验证注册、公告、附件上传（[image:]/[file:] 标签渲染）。

3. 阶段划分（每阶段验证 + commit，可随时暂停）

Phase 0 后端止损（≈半天，独立）

P0-1 删除 Web 更新链路（server.js /api/update/check + /api/update/run、admin.js 前端引用、cli.js zip 分支）→ 消除 RCE 面 + .git 覆盖风险
P0-2 JWT_SECRET 启动生成随机值写入 .env.json（消除 R4 硬编码密钥）
P0-3 /api/setup/complete 加 adminOnly；/setup/status 移除 default_password（消除 R5 接管）
P0-4 /api/proxy/fetch 加 adminOnly + 私网地址过滤（消除 R3 SSRF）
P0-5 邮件验证码不回显 + 修复 pending 重建 bug（消除 R7）
验证：curl 逐项（未登录 401、内网 URL 拒绝、响应无 code）

Phase 1 后端安全加固（≈1-1.5 天）

P1-1 上传白名单 + /uploads 防护头（R1）
P1-2 内容净化：ssr.js + 后端出口统一 DOMPurify/转义（R2 服务端侧；前端侧随 v2 组件实现）
P1-3 登录/发帖限流 + 服务端验证码校验（R8，express-rate-limit）
P1-4 密码箱解锁限流 + PBKDF2 600k（M1）
P1-5 adminOnly 查库复查、草稿权限、错误信息收敛、rejectUnauthorized 收敛、avatar 白名单（M2-M7 中后端项）
P1-6 cli.js 统一到 db.js（消除双封装 + data.db 路径分裂）
P1-7 schema_version 迁移框架（幂等补列 + PRAGMA user_version）
验证：curl 安全用例 + node cli.js status/config/password 正常

Phase 2 数据层换轨 better-sqlite3（≈1 天，依赖 P1-6/P1-7）

前置：Node 升 22 LTS（宝塔 Node 版本管理器）；README/Docker 示例同步
db.js：new Database(DB_PATH) 同步初始化；run/get/all 重写（prepare + info.lastInsertRowid）；删 saveDb/export；initTables 保留幂等补列
routes/import.js：上传文件落临时路径只读打开
数据零迁移：现有 data/rainweb.db 直接打开；PRAGMA integrity_check 预检
验证：备份 → 启动 → CRUD 走查 → cli 命令 → sqlite3 命令行直查

Phase 3 前端工程化搭建（≈1 天）

项目根新建 frontend/（Vite + React + React Router；多入口：index.html（前台）+ admin.html（后台））
共享层：api 客户端（封装现有 /api/*，token 仍 localStorage，错误处理统一）、工具（escapeHtml/日期/分页）、主题（深浅色状态管理）
style.css 迁入前台入口；${site_name} 等占位符保留在构建模板中（serveIndex 运行时替换机制不变）
Vite 配置：构建产物输出到 public/dist/；base: '/'；多入口 rollupOptions
package.json scripts：dev（vite）、build（vite build）、start（server.js）
验证：dev server 起得来、两个入口都能打开、HMR 正常

Phase 4 前台页面迁移（≈3-4 天，核心工作量）

按页面迁移为 React 组件，视觉逐页对照还原：

布局壳（导航栏/主题切换/壁纸/磨砂玻璃）+ React Router 路由表（/、/blog、/forum、/passwords、/login、/register、/profile、/write、/forum-manage、/embed、/setup）；导航栏「管理后台」按钮 = 整页跳转 /admin（<a href="/admin">，不走 SPA 路由）
首页（瀑布流、侧栏头像/简介、最新文章）→ 原 HOMEPAGE 逻辑
博客（列表/详情/编辑，markdown + [image:]/[file:] 渲染 → 组件化 DOMPurify 净化）
论坛（分类/子分类/发帖/回复/详情）
密码管理器（PIN 解锁、加密交互，见 §4.4）
登录/注册（验证码、邮箱验证流程）
个人中心（头像上传、资料编辑）
音乐嵌入、公告、其他全局组件

验证：逐页对照 v1 截图/行为走查；无控制台报错

Phase 5 后台独立应用（≈2 天）

MUI 后台（/admin）：完全独立入口与路由；入口方式 = 前台导航「管理后台」按钮整页跳转（Phase 4 已建）；后台内可返回前台（跳转 /）
登录态守卫（未登录跳转 /login，JWT 与前台共用）；布局（侧栏导航 + 顶栏）
页面：仪表盘、站点设置（含主题/壁纸/玻璃参数）、博客管理、论坛管理、用户管理、公告、面板链接（嵌入 + proxy 代理保留）、验证码/邮件配置、上传管理、密码箱（admin 视角）、更新检查入口移除（P0-1 已删）
原 admin.js 600 行的逻辑按 MUI 组件重写
验证：后台全功能走查 + 前台联动（改设置 → 前台生效）

Phase 6 集成上线（≈1 天）

server.js：静态服务指向构建产物；SPA fallback 分流（/admin* → 后台入口，其余 → 前台入口）；serveIndex 占位符对构建产物生效
旧 public/*.html 与 public/js/ 全部退役删除（ssr.js 引用除外——核对 ssr.js 是否引用 style.css/占位符，保留所需）
SEO 双轨验证：/blog/:id、/forum/:id、sitemap.xml、robots.txt 行为不变
部署流程更新：宝塔 = npm install → npm run build → npm start
README/AGENTS.md 全量更新（v2 架构、命令、构建链说明）

4. 关键技术决策

4.1 TypeScript？

默认不用 TS（v1 全 JS，单人无测试，减少迁移摩擦）；如用户要 TS 可启用（React + Vite TS 模板），代价是迁移工作量 +20%。→ 计划默认 JS，待确认。

4.2 构建产物与占位符

Vite 构建产物 index.html 保留 ${site_name}/${site_description}/${site_favicon} 文本，serveIndex 运行时替换机制不变（构建模板中写占位符即可）。后台入口同理。

4.3 路由与 fallback

前台：React Router（history 模式），server.js app.get('*') 回前台入口
后台：/admin 前缀路由，server.js 增加 /admin* → 后台入口（注意在 SPA catch-all 前）
SSR 路由（/blog/:id、/forum/:id）优先级高于 SPA fallback（现状已如此，保持）

4.4 密码管理器加密

v1 为"服务端保管密钥"模型（PIN 明文到服务端派生）。v2 前台重写时默认保持行为不变（服务端派生 + PBKDF2 600k，Phase 1 已加固）。真正 E2E（WebCrypto 客户端派生）列为 v2 后续可选项，不在本次范围。

4.5 音乐嵌入

v1 的 music-embed（自动隐藏、位置、超时）迁移为 React 全局组件，行为参数从 site_settings 读取，逻辑照搬。

4.6 验证码

captcha.js 前端逻辑（内置 SVG 验证码 + recaptcha）React 化；服务端校验在 Phase 1 已接通（P1-3）。

5. 验证策略（无测试环境）

每阶段：curl API 用例 + 浏览器手动走查 + node cli.js 命令
Phase 4/5：逐页对照 v1 行为清单（§2 保留功能点逐项打勾）
上线前：完整回归清单（登录/发帖/上传/密码箱/主题/面板嵌入/SEO 直链）
可选：引入 Vitest + React Testing Library 对共享层（api 客户端、渲染函数）补少量单测——默认不做，待确认

6. 风险与回滚

风险	缓解
前端重写回归（11 页功能面广）	阶段化推进、§2 功能清单逐项走查；v1 代码保留到 Phase 6 验收通过再删
密码管理器迁移出错	加密逻辑独立模块化迁移，Phase 4 单独验收
better-sqlite3 换轨	数据零迁移 + 备份 + PRAGMA 预检；失败可随时回滚 db.js（v1 代码在 git 历史）
构建链引入部署变化	Phase 6 单独验收部署流程；dev（vite dev）+ prod（build）双路径文档化
SEO 回归	ssr.js 双轨不变，Phase 6 专门验证直链

7. 工时总览

阶段	内容	工时
Phase 0	后端止损	0.5 天
Phase 1	后端安全加固 + cli 统一 + 迁移框架	1-1.5 天
Phase 2	better-sqlite3 换轨	1 天
Phase 3	前端工程化搭建	1 天
Phase 4	前台页面迁移	3-4 天
Phase 5	后台独立应用（MUI）	2 天
Phase 6	集成上线 + 文档	1 天
合计		9.5-11.5 天

每阶段结束：验证清单通过 → git commit → 可暂停验收。

11 KiB Raw Blame History Unescape Escape