Inkwell

Appearance

Inkwell 维护交接前最小检查清单 ​

本文档面向准备把当前实例、当前维护状态或当前问题上下文交给下一位维护者的人。

它不是首次部署验收，也不是长期维护手册。

它回答的是：

在你离开之前，最少要留下哪些事实、验证结果与风险提示，才能让下一位维护者接手时不从零开始？

如果你现在需要的是：

  • 记录现场事实：看 docs/maintenance-field-template.md
  • 长期维护节奏：看 docs/long-term-maintenance.md
  • 维护方向判断：看 docs/maintenance-decisions.md
  • 故障排查步骤：看 docs/troubleshooting.md
  • 升级 / 回滚 / 恢复：看 docs/upgrade-and-rollback.md
  • 先确认当前实例是否已经达到 go / no-go：看 docs/first-deployment-checklist.md

1. 什么时候应该做交接检查 ​

适合：

  • 你准备暂停维护一段时间
  • 你准备把实例交给另一位维护者
  • 你刚完成一次恢复、迁移或排障，希望把当前状态稳定交出去
  • 你知道自己之后可能会忘记当前现场信息

不适合：

  • 只是日常随手改了一个小文案
  • 只是查单个命令
  • 还没有完成当前问题的最小验证

2. 交接前最少要确认的 6 类信息 ​

2.1 当前实例事实 ​

至少确认并写下来：

  • 当前部署方式：VPS 宿主机 / Docker Compose
  • 当前访问域名或入口
  • 当前仓库路径 / 服务器路径
  • 当前代码版本 / commit
  • 上一个已知可用版本 / commit

2.2 当前关键入口 ​

至少确认并写下来：

  • 后台真实入口路径（admin_path）
  • 文档站地址
  • 当前 scheduled publish 主要入口：CLI / internal API
  • 反向代理方式：Nginx / Caddy / 其他

2.3 当前健康快照 ​

至少确认：

  • 首页是否正常
  • GET /api/health 是否正常
  • 后台登录是否正常
  • 搜索是否正常
  • 备份导出是否正常
  • 若近期做过恢复，恢复后 smoke 是否正常

2.4 当前风险与未决事项 ​

至少确认：

  • 还有哪些风险未验证
  • 还有哪些问题虽然不阻塞，但值得下一位维护者继续盯
  • 是否存在“暂时绕过去了，但根因没彻底处理”的情况

2.5 当前关键材料位置 ​

至少确认：

  • .env / 环境注入位置
  • 备份目录位置
  • 日志查看方式
  • 重启服务的方式
  • 反向代理配置位置

2.6 当前应该继续看的文档 ​

至少指给下一位维护者：

  • 当前最相关的 1~3 份文档
  • 为什么是这几份，而不是把整个 docs 目录都丢给对方

3. 最小交接清单 ​

下面这份清单建议在交接前至少走一遍：

  • [ ] 已记录当前部署方式与访问入口
  • [ ] 已记录当前代码版本 / commit
  • [ ] 已记录当前后台真实入口路径
  • [ ] 已记录 scheduled publish 主要入口
  • [ ] 已记录 .env / 环境注入位置
  • [ ] 已记录备份目录或快照位置
  • [ ] 已确认首页 / api/health / 后台登录 / 搜索 的当前状态
  • [ ] 已记录最近一次关键动作（排障 / 恢复 / 迁移 / 升级）做到了哪一步
  • [ ] 已记录未解决问题与未验证风险
  • [ ] 已给出下一位维护者最先该读的文档与建议顺序

4. 最小交接模板 ​

markdown
## 交接记录

### 1. 当前实例
- 部署方式：
- 域名 / 访问入口：
- 仓库路径 / 服务器路径：
- 当前 commit：
- 上一个已知可用 commit：

### 2. 关键入口
- 后台真实入口路径（admin_path）：
- 文档站地址：
- scheduled publish 主要入口：CLI / internal API
- 反向代理方式：

### 3. 当前健康状态
- 首页：正常 / 异常
- `GET /api/health`：正常 / 异常
- 后台登录：正常 / 异常
- 搜索：正常 / 异常
- 备份导出：正常 / 异常 / 未验证
- 最近一次恢复后 smoke：正常 / 异常 / 未验证

### 4. 当前已知风险
- 未解决问题：
- 尚未验证项：
- 下一位维护者最该警惕的风险：

### 5. 关键材料位置
- `.env` / 环境注入位置：
- 备份目录位置：
- 日志查看方式：
- 服务重启方式：
- 反向代理配置位置：

### 6. 最近一次关键动作
- 场景：排障 / 升级 / 恢复 / 迁移 / 重新接手
- 已做到哪一步：
- 已执行的关键命令：
- 已排除的方向：

### 7. 建议下一步
- 下一位维护者先看哪 1~3 份文档：
- 建议先执行的动作：
- 什么时候可以认为当前交接完成：

5. 如果你时间很少，至少留下这 8 项 ​

如果来不及完整交接，至少别漏掉：

  1. 当前部署方式
  2. 当前域名 / 入口
  3. 当前后台真实入口路径
  4. 当前 commit
  5. 首页 / api/health / 后台登录 / 搜索 的当前状态
  6. 当前 scheduled publish 主要入口
  7. 当前未解决风险
  8. 下一位维护者最先该看的文档

6. 交接时最常见的错误 ​

  • 只说“已经恢复好了”，不写恢复后哪些链路已验证
  • 只留代码版本，不留部署方式和入口信息
  • 不写 admin_path，导致下一个人连后台入口都找不到
  • 不写 scheduled publish 主要依赖 CLI 还是 internal API
  • 只留一堆命令，不留当前状态与未决风险
  • 明明还有高风险未验证，却没有显式写出来

7. 推荐搭配阅读 ​

  • 现场信息模板：docs/maintenance-field-template.md
  • 长期维护：docs/long-term-maintenance.md
  • 维护决策：docs/maintenance-decisions.md
  • 运维入口：docs/operations-reference.md
  • 运行态巡检：docs/monitoring-and-logs.md
  • 故障排查：docs/troubleshooting.md
  • 升级 / 回滚 / 恢复：docs/upgrade-and-rollback.md