Inkwell 现场信息记录模板

本文档面向维护者，用于在这些场景里快速记录关键信息：

• 线上排障
• 部署迁移
• 备份恢复
• 长时间搁置后重新接手
• 交接给下一位维护者

它不是排障手册，也不是命令索引。

它要解决的问题是：

当你已经在现场处理问题时，哪些信息必须先记录下来，才能避免后续判断反复走回头路？

如果你现在需要的是：

• 看日志与运行态排查顺序：看 docs/monitoring-and-logs.md
• 选维护方向：看 docs/maintenance-decisions.md
• 升级与回滚：看 docs/upgrade-and-rollback.md
• 首次上线验收：看 docs/first-deployment-checklist.md
• 长期维护节奏：看 docs/long-term-maintenance.md
• 交接前最少要留下什么：看 docs/handoff-checklist.md

1. 什么时候应该使用这份模板

适合：

• 你正在处理线上异常
• 你准备迁移、恢复或升级实例
• 你接手了一个很久没动过的项目
• 你准备把当前维护状态交给下一个人
• 你不想把关键事实只留在聊天记录、脑子里或零散命令历史里

不适合：

• 只是查单个命令
• 只是阅读项目概览
• 只做一次很小的文档改动

2. 最小原则

2.1 先记录事实，再下判断

优先记录：

• 当前版本
• 当前部署方式
• 当前症状
• 当前验证结果

不要一开始就只写结论，例如：

• “像是数据库问题”
• “可能是 Nginx”
• “大概是配置错了”

2.2 把“当前已知可用状态”记下来

排障或恢复时，最有价值的信息之一是：

• 上一个已知正常的版本是什么
• 上一个已知正常的部署方式是什么
• 上一个已知正常的入口与链路是什么

2.3 记录“你已经试过什么”

否则下一个维护者很容易重复：

• 重跑同一条命令
• 重复确认同一条日志
• 重复走一遍已经排除的方向

3. 最小现场信息模板

下面这份模板不需要每次全部填满，但至少建议先把前 6 部分补齐。

## 现场记录

### 1. 基本背景
- 日期：
- 场景：排障 / 迁移 / 恢复 / 重新接手 / 交接
- 维护者：
- 当前目标：

### 2. 当前实例事实
- 部署方式：VPS 宿主机 / Docker Compose
- 域名或访问入口：
- 文档站地址：
- 仓库路径或服务器路径：
- 当前代码版本 / commit：
- 上一个已知可用版本 / commit：

### 3. 关键配置事实
- 后台真实入口路径（admin_path）：
- scheduled publish 主要入口：CLI / internal API
- HTTPS / 证书方式：
- 反向代理：Nginx / Caddy / 其他
- `.env` 或环境注入位置：
- 备份目录位置：

### 4. 当前症状
- 用户可见现象：
- 最早发现时间：
- 影响范围：首页 / 后台 / 搜索 / 备份恢复 / 定时发布 / 全站
- 是否稳定复现：是 / 否
- 当前最像哪一类问题：部署 / 配置 / 数据 / 搜索 / 代理 / 未确定

### 5. 已确认的事实
- `GET /api/health`：正常 / 异常
- 首页：正常 / 异常
- 后台登录：正常 / 异常
- 搜索：正常 / 异常
- 备份导出：正常 / 异常
- 备份恢复：正常 / 异常 / 未验证
- scheduled publish：正常 / 异常 / 未验证

### 6. 已执行的动作
- 已看过的文档：
- 已执行的命令：
- 已检查的日志：
- 已排除的方向：
- 尚未检查的方向：

### 7. 关键输出 / 证据
- 错误信息：
- 关键日志片段：
- 关键 HTTP 返回：
- 关键命令输出：

### 8. 当前判断
- 当前最可疑原因：
- 为什么这样判断：
- 当前不建议做的动作：

### 9. 下一步建议
- 立刻要做：
- 如果失败，下一条分支：
- 需要他人补充的信息：

### 10. 关闭条件
- 什么情况下可以认为这次问题已解决：
- 解决后需要同步哪些文档：
- 解决后是否要补长期维护记录：

4. 哪些字段最不能留空

如果你来不及完整记录，至少别漏掉这些：

• 当前代码版本 / commit
• 部署方式（VPS / Compose）
• 当前后台真实入口路径
• 当前症状与影响范围
• GET /api/health、首页、后台登录、搜索 这几项状态
• 已经执行过的关键命令
• 已经看过的关键日志
• 下一步准备做什么

5. 各场景下最值得先补的字段

5.1 线上排障

优先补：

• 当前症状
• 影响范围
• 健康检查 / 首页 / 后台登录 / 搜索状态
• 已看过的日志
• 已排除的方向

搭配阅读：

• docs/monitoring-and-logs.md
• docs/troubleshooting.md

5.2 升级或迁移

优先补：

• 当前版本 / 上一个已知可用版本
• 部署方式
• 备份是否已完成
• migration 是否已执行
• 回退点是什么

搭配阅读：

• docs/upgrade-and-rollback.md
• docs/release-checklist.md

5.3 备份恢复

优先补：

• 备份目录位置
• 备份对应版本
• 恢复命令与参数
• 恢复后 smoke 结果
• 搜索是否已重建

搭配阅读：

• docs/upgrade-and-rollback.md
• docs/operations-reference.md
• docs/troubleshooting.md

5.4 长时间搁置后重新接手

优先补：

• 当前部署方式
• 当前可访问入口
• 当前后台真实入口路径
• 当前 scheduled publish 依赖 CLI 还是 internal API
• 当前备份与证书续期方式
• 当前已知风险与未验证项

搭配阅读：

• docs/long-term-maintenance.md
• docs/maintenance-decisions.md

5.5 交接给下一位维护者

优先补：

• 当前已知可用版本
• 当前部署结构
• 当前最重要的 3 个入口
• 当前未解决的问题
• 当前绝对不要忘的风险点

6. 现场记录时最常见的错误

• 只写结论，不写证据
• 只记“已经坏了”，不记影响范围
• 只记错误，不记当前仍正常的链路
• 只记做了什么，不记为什么做
• 没记版本、路径、入口，导致别人无法复现上下文
• 问题解决后不补“关闭条件”和文档同步项

7. 推荐搭配阅读

• 维护入口总览：docs/README.md
• 运维入口速查：docs/operations-reference.md
• 运行态排查：docs/monitoring-and-logs.md
• 故障排查：docs/troubleshooting.md
• 升级与回滚：docs/upgrade-and-rollback.md
• 长期维护：docs/long-term-maintenance.md
• 维护决策：docs/maintenance-decisions.md