1.8 KiB
1.8 KiB
ADR-005：Astro 阅读前端与同源部署
状态与日期
已接受，2026-10-16。按维护者要求增加简单前端，不改变 Git 唯一文章写入口。
决定
使用 Astro、TypeScript 与 Node 适配器进行服务端渲染，不增加 React 或浏览器状态框架。首页全部居中，展示施工标题、已完成和未完成部分及导航。文章列表和正文在服务端读取现有公开 API，筛选和分页状态保存在 URL。
注册、登录、公钥、密码与站长授权使用浏览器同源请求。会话继续由后端 Cookie 管理，CSRF 仅保存在当前页面内存。前端不获得数据库口令，不承担权限校验，也不提供在线文章编辑。
Markdown 禁止原始 HTML 并清理渲染结果。相对文档链接和图片只映射到同文章已导入的资源。前端设置 CSP 与禁用缓存，错误时展示真实故障或空状态，不填充示例文章。
Docker Compose 增加独立 Node 前端服务，Caddy 将页面转发到前端，将 /api/* 转发到 Rust。前端、API 与数据库只连接内部网络，不暴露宿主端口。ChuSQL 仅运行数据库服务，不启动其 Web 管理端。
通过 REGISTRY_PREFIX 选择容器镜像前缀，示例配置采用腾讯云内网镜像。非腾讯云环境需清空或调整该配置，项目不修改宿主 Docker 守护进程。
取舍
服务端渲染增加一个轻量 Node 服务，但避免静态构建后文章更新不同步。首页不依赖数据库或文章服务，仍能在服务故障时提供导航。单独运行生产 Node 服务不代理 /api，完整部署使用 Caddy；开发模式由 Vite 代理 API。
系统字体保持浏览器本地渲染，不引入外部字体与跟踪请求。评论、互动、内部文章阅读、审核、暗色模式和完整 SEO 继续列入 TODO。