ChuBlog/docs/operations.md

运维与迁移

返回项目首页

持久化、故障和恢复

持久卷	内容
content	私有 Git 缓存 authors/<用户名>/content.git、collection.json、users.json、公开 published.json
authorization	发布授权与公钥
ingress	作者接收仓库 authors/<用户名>.git
ssh-host-keys	SSH 服务器身份
database / db-logs	数据库数据 / 数据库日志

应用日志输出 stdout，由 Docker 分卷轮换，不记录口令、会话或私钥。

数据库故障与索引重建

• 数据库索引失败不会修改作者 Git 或阻塞已导入文章的 HTTP 阅读；新集合会触发同步，失败至少间隔 30 秒重试，并定期检查索引是否丢失。
• blog_articles 保存全部有效登记文章（含草稿）的作者、本地 ID、正文路径、格式、源提交和元信息；blog_posts/blog_tags 保留公开检索索引。
• 恢复数据库后可自动重建；离线命令为 chublog-api rebuild-index（必须停止同一数据卷上的 API 进程后运行，防止并发），或等待在线自动重试。
• indexed_commit:null 表示尚无已确认可用的索引，旧值表示尚未追平当前内容。
• 重建上述派生表使用 ChuSQL 事务；数据库不可用时保留阅读快照，恢复后重建。

备份与恢复

• 备份必须同时包含正式 Git、用户文件、授权卷、SSH 主机密钥；备份包含密码哈希，须加密并限制权限。
• 接收 Git 可额外镜像备份。
• 恢复时先停止写入，从同一备份恢复各卷，再启动；不要只恢复 ChuSQL，也不要直接向正式仓库推送。
• 应用启动加载私有集合快照，并继续从各作者 Git 校验导入。
• 丢失派生快照时，可在停机并保留备份后移走损坏的 collection.json，由各作者接收仓库重新导入；不要丢失作者仓库或账户授权。
• 进程重启会注销所有会话。

本实现对文件写入执行原子替换与 fsync，Git 引用采用受控更新；磁盘故障、主机断电和备份恢复仍需真实环境演练。不要对含正式数据的项目执行 docker compose down -v。

从旧共享仓库迁移

这是不兼容的存储与 URL 变更，不能直接把旧共享 Git 历史提供给新的个人仓库。先停机并加密备份全部卷，再完成以下操作：

1. 从旧共享仓库导出各作者最新的文章文件（含草稿），按原发布前缀及管理员确认的所有权分给作者；不要复制 .git 或旧提交历史。
2. 管理员离线将 /auth/publishers.json 的 repository 改为 /srv/ingress/authors（或自定义 INGRESS_DIR），保留用户和公钥授权。新版本 init 服务会创建该根目录。
3. 将旧 API 数据卷根目录的 content.git 移入只对管理员可见的备份位置；旧 published.json 同样备份。旧 SSH 共享仓库不再供服务使用，应移出接收卷离线保管。不要删除备份或清空用户数据。
4. 启动新服务。每位作者重新 clone 自己的空仓库，复制自己的导出文件，创建三列 index.txt，整理成一个首次提交并推送。旧 slug 如保留，须与索引 ID 一致。
5. 核对草稿隔离、所有文章、数据库索引和新的 作者名~ID URL 后再恢复对外服务。旧版本已被其他人克隆的内容无法收回。

• 已有授权配置仍指向旧仓库时，新版本拒绝启动；不会自动重新分发旧历史。
• 原链接到新 ID 的重定向尚未实现，迁移时需另行安排。
• 若自定义 INGRESS_DIR，需同步调整镜像内 deploy/gitconfig 的受信目录范围；默认仅信任 /srv/ingress/authors/*，不使用全局 safe.directory=*。