ChuBlog/TODO.md

# ChuBlog — 后续待办计划

更新：2026-10-16。本文依据最新需求划分后续工作；`PLAN.md` 保留原始总体规划。已提供简单 Astro 前端与后端，Git 是唯一文章写入入口。以下未勾选项均为待办，不代表已经实现。

## 当前已实现

- [x] Rust/Axum API：公开文章列表、详情、图片、基础统计、健康接口。
- [x] 用户注册、登录、退出、修改密码；Argon2id、服务端会话、Cookie、Origin/CSRF 校验。
- [x] reader / publisher / admin 权限；注册不能自选权限，管理员单独审批发布权、停用用户，修改权限使已有会话失效。
- [x] 用户上传/轮换自己的 Ed25519/RSA 公钥，公钥存在与具有发布权分别检查。
- [x] OpenSSH 强制命令：仅固定仓库的 Git push/clone；禁用 shell、SFTP/SCP、TTY、代理/端口转发、隧道与用户环境。
- [x] 每位作者独立 SSH 文章仓库与 Git 对象历史，公钥身份映射固定仓库别名，无法读取或改写他人仓库。
- [x] pre-receive 校验 Git quarantine 内的候选提交：单次一个线性提交、仅 main、禁止删除分支、强推、标签及其他分支。
- [x] TOML 元信息、路径、文件模式、大小配额、图片类型/内容/尺寸与链接安全校验；拒绝原始 HTML、隐藏控制符、符号链接、可执行文件及额外文件。
- [x] 按作者隔离 SSH 接收仓库与 API 私有 Git 缓存；`index.toml` 登记文章 ID、目录、六项作者元信息与默认 `main.md` 的入口；支持可达多页、索引错误暂存、入口缺失自动撤回和系统生成作者/时间，增删条目自动同步阅读快照和 ChuSQL 元信息；未登记文件不导入，草稿不出现在公开接口。
- [x] 外部 `ChuSQL`/`ChuSQL-RustDriver` 子模块配置、GitHub HTTPS 默认来源及授权设备 SSH 优先/HTTPS 回退；ChuSQL 文章登记元信息、公开元数据/标签索引及失败自动重建，数据库不承担唯一内容或账户存储。
- [x] Docker Compose、Caddy 反向代理、独立持久卷、容器资源限制、最小进程身份与网络隔离。
- [x] 后端/驱动自动测试、真实容器 SSH 联调脚本、运行/API/架构说明。

## 第一优先级：部署环境验收

- [ ] 配置真实域名、DNS、服务器防火墙与 Caddy 公网证书，确认只有所需 80/443/文章 SSH 端口对外开放。
- [ ] 从真实作者电脑验证 SSH 主机指纹、注册、公钥登记、管理员授权、首次推送和多人并发冲突处理。
- [ ] 给 Docker 数据目录设置文件系统硬配额；用压缩炸弹、大量失败推送和连接洪泛验证空间、CPU、内存、超时及进程数边界。
- [ ] 对正式 Git、用户哈希、授权文件、SSH 主机密钥制定加密备份与保留策略，执行完整恢复演练。
- [ ] 验证断电/磁盘满时 Git 引用、快照、账户及权限文件的一致性；故障恢复后不保留过期发布权。
- [ ] 在实际 ChuSQL 版本执行长期并发、进程崩溃恢复及索引故障注入验证；文章索引保持可重建，后续账户、评论及互动数据作为独立持久数据备份恢复。
- [ ] 固定经过验证的镜像 digest，建立 Git/OpenSSH/Rust 依赖和基础系统安全更新流程。

验收：有完整恢复记录；恶意推送不能影响正式内容；撤权后不能再次推送；数据库宕机仍可阅读公开文章，恢复后索引 commit 与内容一致。新增数据库权限系统后，身份或权限无法确认时拒绝受保护访问，不得降级为公开访问。

## 第二优先级：账户与权限完善

### 数据库用户系统与角色

- [ ] 将用户、密码哈希、角色及发布授权迁入 ChuSQL；当前文件账户和 reader / publisher / admin 角色需提供迁移方案。文章正文仍由 Git 管理，账户数据不能作为可丢弃的派生索引。
- [ ] 保持密码使用 Argon2id 等慢哈希及每个密码独立的随机盐，保存算法与参数，支持参数升级；禁止保存明文密码或使用普通快速摘要代替密码哈希。
- [ ] 预留可扩展权限属性，评估 ChuSQL 自定义 ENUM 类型及驱动兼容性，落实以下角色与继承关系：

| 角色 | 权限 |
| --- | --- |
| `BANNED` | 被封禁，无法登录；已有会话和 SSH 发布授权同步失效。 |
| `MEMBER` | 正常用户，可以阅读权限范围内的文章、点赞、收藏和评论。 |
| `AUTHOR` | 具有 MEMBER 权限，并可发布、管理自己的文章和改变自己文章的可见性。 |
| `MASTER` | 具有 AUTHOR 权限，并可改变他人文章可见性、设置或取消精华、删除他人文章、将他人文章设为内部文章，以及给他人赋权。 |

- [ ] 所有角色与文章所有权检查在服务端执行；注册不能自选高权限，撤权立即影响会话与 Git 发布。SSH 公钥身份验证与站内发布授权继续分别检查。
- [ ] 明确 Git 内容与数据库中站长管理状态的优先级，防止作者再次推送覆盖站长的隐藏、内部化、删除或精华决定；记录权限及管理操作审计。

### 内部文章与查阅口令

- [ ] 支持公开文章与内部文章；内部文章默认要求登录，草稿继续按独立发布状态处理。
- [ ] 部分内部文章可配置查阅口令，游客验证口令后可访问对应文章；口令以加盐慢哈希保存，限制尝试频率，授权限定文章及有效期，口令变更后可撤销授权。
- [ ] 作者可调整自己文章可见性，MASTER 可调整他人文章；口令和访问凭据不得以明文写入 Git 或日志。
- [ ] 正文、图片、附件、列表摘要、搜索、RSS、缓存和统计接口统一执行访问控制，避免直链或缓存泄露内部内容。明确 Git 作者可读取仓库历史的边界，不能仅靠阅读 API 权限保证作者之间保密。

### 评论与存储限制

- [ ] 评论内容及其作者关联、文章关联、时间和管理状态保存于 ChuSQL，支持分页读取和必要索引。
- [ ] 明确文章及评论的字数上限、UTF-8 字节上限、请求体上限和累计存储配额，并在服务端写入前强制验证；现有文章大小限制继续生效。
- [ ] 支持已登录用户与游客评论；落实匿名身份、限流、防刷、重复提交处理及评论管理规则，评论输出转义或清理，防止脚本注入。

### 互动统计、热度与精华

- [ ] 支持任何人（包括游客）点赞、收藏、评论；设计匿名身份和去重规则，并与 MEMBER 的账户关联互动统一，防止重复刷量。
- [ ] 持久化每篇文章的浏览量、点赞数、收藏数、评论数；明确浏览计数、取消点赞/收藏、评论删除及并发更新的一致性口径。
- [ ] 提供汇总统计和分页文章列表，支持按点赞数等指标降序排列；只返回请求者可见的文章及相应统计。
- [ ] 设计综合浏览、点赞、收藏、评论及发布时间的热度算法，明确权重、时间衰减、防刷和重算策略，用于优化首页推荐。
- [ ] 增加文章精华状态，由 MASTER 设置或取消；首页推荐优先展示精华，再结合热度排序，始终遵守文章可见性限制。
- [ ] 为互动数据与统计制定存储预算、聚合及保留策略；现有内存请求计数重启清零，不能作为持久浏览量使用。

### 后期 HTML 富文本

- [ ] 后期评估 HTML 富文本支持；启用前设计允许的标签、属性和链接协议，清理危险 HTML、事件属性及嵌入内容，补充 XSS 验证与 CSP。当前继续拒绝原始 HTML/MDX，不能执行作者提交的脚本。

### 账户安全与发布授权补强

- [ ] 管理员 MFA（成熟身份代理或 TOTP），敏感授权操作二次验证。
- [ ] 安全的管理员离线恢复/重置流程；用户密码找回需要先决定可信邮件或邀请渠道，禁止不验证身份的重置接口。
- [ ] 每用户多把公钥、指纹展示、单钥撤销、最后使用时间；保留每钥身份绑定。
- [ ] 在全局限流之上增加可信代理来源的 IP 与账户维度限制、失败退避，减轻公共认证桶被恶意占满的问题。
- [ ] 注册开放策略、邀请注册或邮件验证；保留注册与发布审批的权限分离。
- [ ] 持久化结构化审计，明确记录每次接受的 commit 对应站内用户与公钥指纹，并设置保留周期。当前 SSH 接收日志已有身份与 commit，API 导入日志只有 commit，尚无统一审计查询。
- [ ] 为旧共享仓库迁移执行所有权核对、只导出最新文件的个人仓库重建及链接重定向；不得向作者分发旧共享历史。
- [ ] 在索引导入与公开发布之间加入站长审核：新增文章及后续修改先成为待审核版本，MASTER 决定通过或驳回；未通过内容不得公开，修改审核期间保留上一已通过版本，明确索引删除/撤回语义、审计与作者状态查询。本轮只保留该待办，不启用审核。

## 第三优先级：前端完善

- [x] Astro + TypeScript SSR：全部居中的施工首页，文章列表、元信息搜索、标签筛选、分页、文章详情、多页链接、图片和 404，适配手机。
- [x] 注册、登录、账户、公钥设置、密码修改、退出和管理员发布授权页面，不增加在线文章写入口。
- [x] Markdown 原始 HTML 禁用及输出清理，元信息转义、相对页面/图片链接映射、CSP、Cookie/CSRF 与错误状态。
- [x] 前端 Docker 镜像、Caddy 页面/API 同源分流；ChuSQL 仅运行数据库，不启用其 Web 管理端。
- [ ] 归档、暗色模式、完整 SEO、canonical、Open Graph、RSS、sitemap、robots。
- [ ] 代码语法高亮、更丰富的文章目录及阅读导航。
- [ ] 扩展可访问性与跨浏览器检查，持续执行浏览器 XSS 回归验证。

验收：作者在本地编辑并 push 后阅读端可自动获取更新；草稿及资源无法由公共接口读取。首页展示的完成状态需随实际功能更新。

## 第四优先级：发布和运维体验

- [ ] 发布状态查询：区分 Git 已接受、内容已导入、索引已同步，向作者提供 commit 级诊断。
- [ ] 支持有上限的多次线性提交推送，逐个验证新增历史；保留对 merge/force push 的明确策略。
- [ ] 目录配额预警、安全 GC 与维护窗口；禁止在 SSH 请求里运行任意维护命令。
- [ ] 扩充现有 commit/行数对账为完整字段与标签对账；增加磁盘/登录失败/索引延迟/导入失败告警，以及受控恢复工具。
- [ ] API 分页与条件缓存：保留撤回后不可继续公开访问的语义。
- [ ] 配合第二优先级的互动统计，落实访问口径、隐私策略、每日聚合和统计故障恢复。
- [ ] 外部资源链接检查、slug 重定向与图片元数据清理；不能因此在服务器执行作者提供的命令。

## 后续再评估

在线编辑/上传/预览、全文检索和多副本。评论、四级角色和精华功能已列入明确待办；HTML 富文本按上述后期计划评估。若引入在线编辑，应先明确其如何经过同一授权、校验与发布协调流程，不能在现有 Git 仓库上新增未经协调的第二个写入口。