project-admin 设计说明

目标与非目标

project-admin 的目标是为仓库所有者提供一个低成本的本地内容管理界面，直接读取和更新博客仓库中的 Markdown、JSON、图片及构建任务。

它明确不承担以下职责：

• 不作为公网或局域网共享服务部署。
• 不提供登录、会话、角色、权限和多用户并发编辑。
• 不把本地文件操作抽象成通用文件管理 API。
• 不保证生产模式具备长期托管所需的隔离、审计和运维能力。

运行架构

本机浏览器
    |
    | http://127.0.0.1:8888
    v
Express API + Vite 开发中间件
    |             |
    |             +-- 开发模式界面与 HMR
    |
    +-- pages/posts、data、public 及本地任务
    |
    +-- 受限制的公网 HTTP/HTTPS 抓取

服务地址由 server/serverConfig.js 固定为 127.0.0.1:8888。开发模式是主要工作流；生产模式仅加载已构建的 dist，用于构建产物验收。Express 5 fallback 已使用命名通配符路由修复，但该路径按 P3/非主要目标维护。

组件职责

组件	职责
src/	管理界面、路由和交互状态
server/routes/	HTTP API 边界和请求分发
server/lib/	文章、广播、回忆、设置等领域读写与校验
server/tasks/	构建、上传、友链抓取等长任务
data/	后台覆盖项、设置和任务辅助数据
scripts/dev.js	本地开发进程和界面监听

代码风格

项目 JavaScript/JSX 函数统一使用 const name = (...) => 或 export const name = (...) =>。箭头函数转换只适用于不依赖函数自身 this、arguments、生成器或构造器语义的函数；对象方法、回调和第三方接口要求的动态 this 保持原有语义。

信任模型

唯一受信任主体是正在本机操作仓库的用户。未受信任输入主要来自：

• 导入或编辑的 Markdown、RSS 和富文本内容。
• 友链中的页面、头像 URL 及其重定向目标。
• 上传的图片文件、元数据和解码后的像素尺寸。
• API 中代表文章路径的编码 ID。

缺少认证不是漏洞，而是单用户、仅回环监听模型下的设计选择。这个结论以服务不被代理、转发或改成非回环监听为前提；一旦运行边界变化，就必须重新设计认证、授权、CSRF、防滥用和审计机制。

安全与可靠性决策

边界	实施措施	目的
文章文件路径	解码后限制在 pages/posts，只接受 .md；同时用 path.relative 和 realpath 校验	防止目录越界和符号链接逃逸导致误读、误改或误删
富文本输出	Markdown 只清洗用户提供的原始 HTML token，保留受信渲染器生成的 MathJax、Mermaid 和 MarkMap；电台 RSS 描述和覆盖描述使用最终 HTML 允许列表	阻止脚本和事件处理器，同时保留既有预览语法
外部 URL	只接受 HTTP/HTTPS，拒绝凭据、localhost、回环、私网、链路本地和其他非公网地址；实际套接字使用已验证地址，重定向逐跳复验	限制友链抓取访问本机或内网资源并避免 DNS 重绑定
友链页面	Chromium 使用默认沙箱，页面的 HTTP/HTTPS 请求由受控下载器响应，不允许浏览器直连；最多 200 个请求、单资源 10 MB、页面总计 50 MB	限制不受信页面的网络与资源消耗
外部图片	设置超时、重定向次数和 10 MB 响应上限；Sharp 使用有限像素解码	避免异常远端响应消耗过多内存或处理时间
回忆上传	单文件、20 MB、最多 8 个字段、图片 MIME；真实格式允许列表和 6000 万像素上限	控制临时磁盘、内存和图片解码资源
上传清理	无论成功失败都删除 Multer 临时文件，大小超限返回 413	避免失败上传持续占用磁盘
前端 fallback	Express 5 使用 /{*path} 命名通配符	保留构建产物冒烟能力，不将其提升为部署承诺

已接受限制

• 本机其他进程可以访问回环端口；系统账户和浏览器环境仍属于部署者的安全边界。
• API 可以修改仓库内容，这是工具的核心用途；提交前仍应通过 Git diff 审核和版本控制恢复误操作。
• 外部网站可能很慢、不可达或拒绝自动访问；友链更新采用失败降级，不承诺所有截图和头像都能生成。
• 生产模式仅做兼容性冒烟，不代表后台适合长期运行或远程暴露。

变更记录

2026-08-23

• 明确本地单用户威胁模型和非部署目标。
• 修复 Express 5 静态 fallback 路由。
• 增加文章目录边界、富文本清洗、外部 URL 公网限制和上传资源限制。
• 友链任务统一复用解码后的仓库根路径，兼容包含中文等非 ASCII 字符的本地目录。
• 增加对应安全回归测试和后台开发模式 E2E 说明。
• 测试用例统一归档到仓库根目录 test/admin/；project-admin/ 只保留后台实现代码。

2026-08-23 - 统一箭头函数风格

• 将 project-admin/server、project-admin/src 和 project-admin/scripts 中可安全转换的函数声明统一为箭头函数。
• 保留需要动态上下文或特殊语言语义的函数形式，并通过构建、单元测试和 E2E 验证行为未变。