226 lines
14 KiB
Markdown
Executable File
226 lines
14 KiB
Markdown
Executable File
# ChuBlog — 项目规划
|
||
|
||
> 状态：规划草案 v1.0 · 2026-10-15
|
||
> 定位：自托管个人技术博客；Markdown 文件是内容源，Git 管理版本，ChuSQL 提供可重建的内容索引。
|
||
|
||
## 1. 目标与原则
|
||
|
||
- 面向个人作者，支持公开阅读、文章归档、标签、代码高亮、目录、SEO、RSS 和深色模式。
|
||
- 管理员可在经过认证的后台上传 Markdown、预览、修改元数据、发布、撤回与删除文章；也支持本地 Git 工作流。
|
||
- **Git 仓库内的 Markdown 与资源文件是唯一权威内容源**；ChuSQL 不保存唯一一份正文，只维护可重建索引。
|
||
- 未授权用户不得发布页面、提交到内容仓库或触发任意服务器 Git 命令。
|
||
- 保持 MVP 小而可靠；不引入公共用户注册、评论、插件市场、队列/微服务或复杂角色系统。
|
||
- ChuSQL 暂不视为已通过生产验证的数据库；博客即使索引丢失，也能从 Git 恢复文章。
|
||
|
||
## 2. 技术栈
|
||
|
||
| 层 | 选型 | 职责 |
|
||
| --- | --- | --- |
|
||
| 站点 | Astro + TypeScript | 内容页面、按需服务端渲染、SEO、RSS |
|
||
| 样式 | Tailwind CSS | 响应式设计、暗色模式 |
|
||
| Markdown | Astro Markdown 管线（remark/rehype、Shiki） | Markdown/Frontmatter 解析、代码高亮 |
|
||
| 后端 | Rust + Axum + Tokio + Serde | 管理员接口、认证、上传校验、Git 操作、索引同步 |
|
||
| 数据库 | ChuSQL | 已发布文章元数据、标签、搜索索引（按当前能力逐步实现） |
|
||
| DB 客户端 | `chusql-rs`（独立 crate） | ChuSQL 网络协议连接、查询、错误处理 |
|
||
| 反向代理 | Caddy | HTTPS、请求体限制、路由 |
|
||
| 运行 | Debian + Docker Compose | 管理服务与持久卷 |
|
||
| 版本控制 | Git | 文章与图片的版本记录、审计与恢复 |
|
||
|
||
不自行编写 Markdown 语法解释器。MVP 禁止文章中的原始 HTML 或采用严格清理策略；默认不启用任意 MDX/JS 组件，因为上传文档不能成为服务器执行代码的入口。
|
||
|
||
## 3. 系统架构
|
||
|
||
```text
|
||
读者浏览器 ── HTTPS ── Caddy ── Astro（公共页面）
|
||
│
|
||
├─ 只读文章文件 / content（挂载）
|
||
└─ Axum 只读 API（必要时）── ChuSQL（索引）
|
||
|
||
管理员浏览器 ── HTTPS ── Caddy ── Axum（后台 API）
|
||
│
|
||
├─ 管理员认证 / CSRF / 限流
|
||
├─ Markdown 校验及暂存
|
||
├─ 受控 Git 内容仓库
|
||
└─ 索引同步 ── chusql-rs ── ChuSQL
|
||
|
||
管理员本地编辑器 ── Git 受保护分支 / 仓库同步流程 ── 内容仓库
|
||
```
|
||
|
||
- 只暴露 80/443 TCP；Axum、Astro 与 ChuSQL 使用私有 Docker 网络。
|
||
- 现有 P2P 服务可独立继续使用 UDP 7001，互不影响。
|
||
- **不允许用户请求决定任意磁盘路径、Git 仓库地址、Git 参数或 shell 命令。**
|
||
- Astro 若需上传后立即生效，使用按需 SSR 读取受控的内容快照；不要依赖仅构建时扫描的静态内容集合。若改用纯静态生成，则明确采用“提交后重新构建并原子部署”的发布策略。MVP 选择 **SSR + 已发布内容快照**。
|
||
|
||
## 4. 内容模型与存储布局
|
||
|
||
```text
|
||
chublog/
|
||
├── apps/
|
||
│ ├── web/ # Astro 站点
|
||
│ └── api/ # Axum 后台与只读 API
|
||
├── crates/
|
||
│ └── chusql-rs/ # 若尚无独立仓库，可先工作区开发再拆分
|
||
├── content/ # 独立 Git 仓库或子目录（受控工作树）
|
||
│ ├── posts/
|
||
│ │ └── haskell-monad/
|
||
│ │ ├── index.md
|
||
│ │ └── cover.webp
|
||
│ └── .gitignore
|
||
├── deploy/
|
||
│ ├── compose.yaml
|
||
│ └── Caddyfile
|
||
└── PLAN.md
|
||
```
|
||
|
||
文章 Frontmatter 规范示例：
|
||
|
||
```md
|
||
---
|
||
title: "Haskell Monad 入门"
|
||
slug: "haskell-monad"
|
||
date: "2026-10-15"
|
||
updated: "2026-10-15"
|
||
status: "published"
|
||
tags: ["Haskell", "Functional Programming"]
|
||
description: "Monad 的基础概念"
|
||
---
|
||
|
||
# Haskell Monad 入门
|
||
|
||
正文……
|
||
```
|
||
|
||
- `slug` 是唯一的 URL 标识，仅允许小写英文字母、数字、短横线，校验长度和保留名称。
|
||
- 文件路径由服务端基于已校验 slug 固定计算；禁止 `../`、绝对路径、符号链接和路径穿越。
|
||
- `status` 取 `draft | published`；草稿不可被未授权访问或从公开索引枚举。
|
||
- 图片仅允许必要类型（如 PNG/JPEG/WebP），按真实文件内容与尺寸校验，限制单文件和文章总大小。SVG 暂不开放后台上传。
|
||
- 内容文件和 Frontmatter 是权威信息；ChuSQL 中的记录可由全量扫描重新建立。
|
||
|
||
## 5. Git 内容管理工作流
|
||
|
||
### 5.1 后台上传与发布
|
||
|
||
1. 管理员登录，上传 `.md` 与附属图片；后端检查会话、CSRF 与限流。
|
||
2. 在隔离的暂存目录校验文件、解析 Frontmatter、检查重复 slug、限制大小和 Markdown 语法范围。
|
||
3. 展示预览；管理员明确点击“发布”。预览默认不公开。
|
||
4. 服务端通过受控文件操作写入仓库指定目录，创建 Git commit（提交者为固定服务身份，日志可附管理员操作 ID）。
|
||
5. 提交成功后生成/切换已发布内容快照，并更新 ChuSQL 索引；公开页面仅读取已发布快照。
|
||
6. 若索引更新失败，保留 Git 提交和待同步状态，由可重复执行的扫描任务恢复，不得静默显示“全部成功”。
|
||
|
||
### 5.2 本地 Git 编写
|
||
|
||
- 管理员可以在本地仓库编辑 Markdown，向受保护的主分支推送，或通过 PR 合并。
|
||
- 推荐在 CI 检查 Frontmatter、路径、大小、图片、链接及危险内容；只有已认证维护者可合并。
|
||
- 服务器采用**只读拉取/受控部署**，不接受互联网匿名推送；可使用带最小权限的部署凭证。
|
||
- **双入口写入存在冲突风险**：MVP 应只开放一个写入主入口。建议首先采用“后台上传写入本地 Git 仓库”，后续引入远端同步时再明确由 CI 部署作为唯一发布入口；或者反过来完全让后台创建 PR。禁止两个入口不加协调地向同一工作树写入。
|
||
|
||
### 5.3 更新、撤回、删除
|
||
|
||
- 更新是新的 Git commit；保留文章稳定 slug，必要时配置显式重定向。
|
||
- 撤回把 `status` 改为 `draft`，新快照不可公开访问。
|
||
- 删除从当前版本移除，但 Git 历史可能仍含内容；对于秘密泄露需要额外执行历史清理与凭证轮换，不能认为删除 commit 就彻底清除。
|
||
- 上传的草稿与私有资源必须与公开静态目录隔离，避免直链泄露。
|
||
|
||
## 6. 身份认证与抗垃圾页面
|
||
|
||
**MVP 采用单管理员、无公开注册、无公开投稿。** 未登录者没有任何创建、编辑、上传或 Git 写权限。这比单纯依靠验证码或限流更能从根源上避免垃圾页面泛滥。
|
||
|
||
安全控制：
|
||
|
||
1. 管理员账户配置在受保护的服务端环境或安全存储中；口令以 Argon2id 等成熟密码哈希存储，绝不保留明文。
|
||
2. 登录成功后发放服务端会话；Cookie 使用 `HttpOnly`、`Secure`、`SameSite`，设置到期时间和退出失效机制。生产建议支持 TOTP 2FA 或使用成熟身份代理实现 MFA。
|
||
3. 所有状态变更接口强制验证身份与 CSRF（包括上传、提交、发布和删除）；校验 `Origin`，设置合理 CORS 策略。
|
||
4. 登录端点按 IP 与账户维度限流、失败退避和审计；上传限制文件大小、数量、总磁盘配额、请求频率、并发和执行耗时。
|
||
5. 反向代理和 API 分层限制请求体大小；服务仅接受预期 MIME 与文件结构；禁止 HTML/脚本执行、可疑链接协议与不受控资源嵌入。
|
||
6. Git 命令通过固定参数的进程 API 执行，**不用拼接 shell 字符串**；Git 工作树不允许访问任意仓库 hook，服务运行身份权限最小化。
|
||
7. 公开内容启用合理 CSP、HTML 清理、链接安全属性；后台不暴露到不必要的外部域名。
|
||
8. 采用日志审计：谁在什么时候上传、预览、发布、撤回、删除，以及对应 commit hash；不要记录口令或会话令牌。
|
||
|
||
若以后支持访客投稿：所有投稿必须进入**待审核区**，经管理员人工批准后才能进入正式 Git 分支；不得让访客直接触发公开发布。
|
||
|
||
## 7. API 草案
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/admin/login` | 公共、限流 | 管理员登录 |
|
||
| `POST` | `/api/admin/logout` | 管理员 + CSRF | 注销会话 |
|
||
| `GET` | `/api/posts` | 公共 | 查询已发布文章元数据 |
|
||
| `GET` | `/api/posts/:slug` | 公共 | 已发布文章信息（或由 Astro 直接读取文件） |
|
||
| `POST` | `/api/admin/uploads` | 管理员 + CSRF | 上传临时文件、验证 |
|
||
| `POST` | `/api/admin/posts/preview` | 管理员 + CSRF | 安全预览 |
|
||
| `POST` | `/api/admin/posts/publish` | 管理员 + CSRF | 固定目录落盘并 Git 提交 |
|
||
| `PATCH` | `/api/admin/posts/:slug` | 管理员 + CSRF | 更新元数据/内容 |
|
||
| `POST` | `/api/admin/posts/:slug/unpublish` | 管理员 + CSRF | 撤回文章 |
|
||
| `DELETE` | `/api/admin/posts/:slug` | 管理员 + CSRF | 删除当前版本 |
|
||
| `POST` | `/api/admin/index/rebuild` | 管理员 + CSRF | 从 Git 内容重建 ChuSQL 索引 |
|
||
|
||
API 路由仅为计划，后续以实现的最小接口为准；对发布、更新、删除操作加互斥与幂等处理，防止并发提交损坏仓库状态。
|
||
|
||
## 8. ChuSQL 集成与一致性
|
||
|
||
MVP 仅需要 `posts` 元数据与 `tags`，字段例如 `slug, title, description, status, published_at, updated_at, path, git_commit`。字段类型、DDL、过滤和分页查询应按现有 ChuSQL 协议确定，不能预设兼容 PostgreSQL 或 SQLx。
|
||
|
||
- `chusql-rs` 第一版支持：连接、超时、查询/执行、结果与类型映射、错误处理、断线识别、集成测试。
|
||
- 不依赖目前未实现或未经验证的 ChuSQL 多语句事务；应用端以 Git 快照为权威，数据库仅做派生索引。
|
||
- 每次发布记录 Git commit hash，索引带对应内容版本号。建立独立的 `rebuild-index` 命令与定期一致性检查。
|
||
- ChuSQL 不可用时，已生成的公开内容快照仍能被读取；列表、标签等可从文件快照构建简易只读索引。禁止在数据库错误时覆盖或删除文章文件。
|
||
- 上传发布时采用严格顺序和可恢复状态：校验 → 暂存 → Git commit → 更新已发布快照 → 尝试索引同步；出错后可依据 commit 重新同步。
|
||
- 文章页面不要因 ChuSQL 宕机而泄露内部错误或凭证。
|
||
|
||
## 9. 实施阶段与验收
|
||
|
||
### Phase 0 — 先验证接口
|
||
|
||
- [ ] 检查 ChuSQL 服务端网络协议、查询语法和持久化行为。
|
||
- [ ] 决定 Astro SSR 在容器内读取哪个受控内容目录。
|
||
- [ ] 确定 Git 仓库部署路径、最小权限和快照切换方式。
|
||
|
||
### Phase 1 — 纯文件博客 MVP
|
||
|
||
- [ ] Astro 页面：首页、文章详情、标签、归档、404、暗色模式。
|
||
- [ ] Markdown + Frontmatter 校验、Shiki 代码高亮、文章目录。
|
||
- [ ] Astro SSR 读取已发布内容快照；提供 RSS、sitemap 和 SEO 元信息。
|
||
- [ ] 测试异常文件、超大文件和 XSS 内容不会被执行。
|
||
|
||
### Phase 2 — 后台 + Git 发布
|
||
|
||
- [ ] 单管理员认证、会话与 CSRF。
|
||
- [ ] 上传、预览、发布、编辑、撤回、删除。
|
||
- [ ] 每次发布产生可追踪的 Git commit；冲突与重复提交有明确错误反馈。
|
||
- [ ] 通过限流、文件配额、路径校验和无公开注册测试。
|
||
|
||
### Phase 3 — ChuSQL 驱动与索引
|
||
|
||
- [ ] 开发 `chusql-rs` 最小客户端及协议测试。
|
||
- [ ] 建立文章元数据表、查询接口与索引同步。
|
||
- [ ] 完成从 Git 仓库重建索引的命令与故障注入测试。
|
||
- [ ] 验证 ChuSQL 故障期间公开阅读不中断、恢复后索引一致。
|
||
|
||
### Phase 4 — 部署与运维
|
||
|
||
- [ ] Docker Compose、Caddy TLS、仅开放必要公网端口。
|
||
- [ ] 持久化 Git 内容与资源；数据库卷、日志独立管理。
|
||
- [ ] 备份 Git 仓库（含远端镜像）与上传资源；定期进行真实恢复演练。
|
||
- [ ] 监测磁盘、接口错误、登录失败、索引同步延迟。
|
||
- [ ] 更新依赖、最小容器权限、限制容器挂载与网络访问。
|
||
|
||
**MVP 完成判定**：未经认证无法写入或发布；管理员可上传并发布一篇 Markdown，页面即刻可读，Git 中有对应提交；重启容器后内容存在；故意停止 ChuSQL 后仍可浏览已发布文章；重新建立数据库后可重建索引；恶意路径、超大文件和脚本注入测试均不能成功。
|
||
|
||
## 10. 生产就绪与风险边界
|
||
|
||
- **文章内容生产可用性**来自 Git、可恢复的文件快照、访问控制、备份及恢复演练，不取决于 ChuSQL 当前成熟度。
|
||
- **ChuSQL 仍按实验性组件管理**：在事务原子性、并发控制、进程崩溃恢复、备份/恢复、认证与长时间稳定性未经验证前，不作为任何不可重建数据的唯一存储。
|
||
- 文件与数据库之间不追求假想的跨系统原子事务，而采用幂等同步和可回放 Git 提交恢复一致性。
|
||
- 不把管理员凭证、Git 写入凭证或 ChuSQL 密码写入 Git 仓库、镜像层和日志。
|
||
|
||
## 11. 暂不纳入 MVP
|
||
|
||
- 访客注册、公开投稿、评论、点赞与复杂权限角色。
|
||
- 前端在线富文本编辑器、协同编辑和复杂草稿工作流。
|
||
- 全文搜索引擎、消息队列、分布式部署、对象存储、多租户。
|
||
- 自建 Markdown 解释器、通用插件机制和 ChuSQL ORM/SQLx 适配。
|
||
|
||
## 12. 近期第一步
|
||
|
||
优先确认 ChuSQL 现有协议，同时创建 Astro 静态界面与 Axum 认证/上传原型。先跑通**管理员上传 → 校验 → Git 提交 → 公开页面读取文件**，之后再接入 ChuSQL 元数据索引。这样即使数据库研发推迟，博客仍可独立推进。
|