ChuBlog/docs/API.md

后端 API

返回项目首页

请求约定

• 全部正文使用 JSON。
• 同源 Origin 必须等于 PUBLIC_ORIGIN，例如 https://blog.example.com。
• 响应含 Cache-Control: no-store。
• 登录 Cookie 为 HttpOnly; SameSite=Strict; Secure，仅 localhost HTTP 开发场景省略 Secure。

接口一览

方法	路径	权限 / 请求
GET	/api/health	公共，API 存活，不代表数据库或发布同步健康
GET	/api/posts	公共，{commit,posts:[metadata]}，仅已发布，日期倒序
GET	/api/posts/:slug	公共，{meta,markdown,format,author,article_id,assets:[{name,url}]}，草稿及不存在均 404
GET	/api/assets/:slug/:name	公共，仅已发布文章的已验证图片
GET	/api/stats	公共，文章数、标签数、正文源字节数、启动以来文章请求数
POST	/api/auth/register	公共 + Origin；{username,password}，创建 reader；可配置关闭
POST	/api/auth/login	公共 + Origin；{username,password}，返回 {username,role,csrf} 及 Cookie
POST	/api/auth/logout	登录 + Origin + CSRF；使会话失效并清除 Cookie
GET	/api/account	登录；返回自己的 {username,permissions,csrf}，不含口令哈希
PUT	/api/account/ssh-key	登录 + Origin + CSRF；{public_key}，替换自己的唯一 Ed25519 或 RSA 公钥（RSA 2048–8192 位）
PUT	/api/account/password	登录 + Origin + CSRF；{old_password,new_password}，成功后全部会话失效
GET	/api/admin/users	管理员；返回用户启用状态、角色、前缀及公钥，不含哈希
PATCH	/api/admin/users/:username	管理员 + Origin + CSRF；{enabled,role}；兼容可选的旧 prefixes 字段
GET	/api/admin/status	管理员；{commit,total_posts,drafts,indexed_commit}

权限与账户

• 角色：reader | publisher | admin。
• 网站管理员与数据库账号、OS 用户不是同一个系统。
• 发布角色仍需已登记公钥才能使用 SSH。
• 每个账户使用自己的仓库，旧前缀字段不再承担授权作用。
• 网站登录不产生 Git 访问凭证。

用户名：3–32 位小写字母、数字、短横线，以字母开头；口令：12–1024 字节。旧前缀字段仅兼容接收，若传入仍按原格式校验。注册不接受 role 等额外字段。公钥不能与别的用户重复。

修改请求

• 修改请求的头为 Origin: https://blog.example.com 和 X-CSRF-Token: <登录返回的 csrf>，并携带 Cookie。
• 没有配置跨域 CORS，也没有浏览器本地持久存储令牌的要求。
• 授权或停用用户会使该用户既有会话失效；再次登录后才能继续使用自己的账户接口。

错误响应

• 普通业务错误返回 { "error": "可读说明" }；401 未登录/口令错误，403 Origin/CSRF/权限错误，404 不存在或非公开内容，409 用户名冲突，429 超过限流。
• Axum 的无效 JSON/字段结构错误使用框架的 400/415/422 响应，超过请求体上限返回 413。
• 服务器内部错误不返回路径、凭据或数据库详情。

文章发布边界

文章写入、上传、在线预览、后台发布/删除接口当前都不存在。文章修改和权限审批分开：管理员只能通过账号 API 批准身份与发布资格；文章在作者本机编辑，通过 SSH Git 发布。

文章与资源

• 文章以作者仓库的 index.txt 为登记依据，每行三列：文章ID posts/文件夹 正文文件名。
• 站内 :slug 为 作者名~文章ID，例如 alice~first；索引 ID 不随文件夹或文件名变化。
• markdown 保留现有正文源字段（含 Frontmatter）；format 为 markdown 或 text，纯文本不得当作 HTML 渲染。
• 未登记内容及草稿不通过公共文章/资源接口返回；删除索引项会自动撤回阅读内容并同步删除派生数据库记录。

同步状态

• /api/admin/status 的 commit 和 indexed_commit 为整个作者集合的版本摘要，不是单个作者的 Git HEAD。
• 作者各自的源提交记录在数据库 blog_articles.git_commit 和私有集合快照中。
• 数据库失败时 Git 接收与阅读仍可继续，索引在恢复后自动重建；站长审核暂未启用。