经验

什么时候看这一节：出现了从没见过的故障，或者刚刚花了几小时排掉一个坑，想知道别人是不是踩过。

一、这一节放什么

一个坑一篇，放真实发生过、并且已经查清原因的问题。

和技术类页面里的「常见问题」分开：

• 参考页的常见问题 = 已知的、有标准答案的现象（「连不上怎么办」）。
• 经验 = 当时不知道怎么办、花了不少时间才查清的问题。价值在为什么当初没想到。

二、跨案例的通用判断

下面的判断不针对某一次故障，动手前对照一遍。具体案例见各篇复盘。

排查

• 先确认现象，再动手改。 现象要能写成一句别人看得懂的话，写出这句话的过程往往就排除大半猜测。
• 一次只改一个变量。 同时改三处，好了不知道哪处起的作用，坏了也不知道哪处导致的。
• 从最近的变化开始怀疑。 「昨天还好、今天不行」多半和最近一次部署、配置变更、证书到期、磁盘写满有关。
• 报错贴原文。 Connection refused 与 Connection timed out 是两种故障，转述会丢掉关键字。

改动

• 提交小而完整。 一次提交只做一件事，出问题时能精确回退。
• 提交信息写「为什么」。 代码本身说明「做了什么」，半年后看得懂的是动机。
• 配置进版本库。 只在自己机器上能跑的配置等于不存在。
• 改动要能回滚。 做不到回滚的改动要么拆小，要么等到有维护窗口再做。
• 别在真实服务上直接试。 拿不准的操作先在测试环境或副本上做。

日志

• 日志在故障之前写好。 出事之后才加日志，这次故障注定查不清。
• 日志要能回答谁、在哪、做了什么、结果如何。 缺一项就只能证明「出过事」。
• 不记敏感信息。 凭据、token、内网地址不进日志，公开仓库尤其严格。
• 区分预期内的失败与异常失败。 用户输错密码记普通日志，数据库连不上才告警。

工具

• 重复超过三次的操作写成脚本。 手做的代价是慢，且每次做得都不完全一样。
• 让错误做法变得不方便。 与其在文档里写「记得备份」，不如让流程默认备份。
• 先跑起来，再跑对，最后跑快。 没有测量数据的优化会把结构改复杂。
• 正则查着写、用小样本验。 优先用明确量词，避免 .* 与嵌套量词；换语言要重验一遍。

三、为什么值得写

一个部门最贵的成本，是同一个问题被不同的人各踩一次。

坑的经验有个特性：它天然只存在当事人脑子里。文档有人写，坑没人愿意写——写坑等于承认自己卡住过，过程往往也不体面（试了一堆错方向）。

所以这一节的写作要求里有一条：必须写「当时试过什么、为什么不对」。这两点才是别人真正用得上的东西。只写「最后加了个互斥锁」没有任何教育意义。

四、全部经验

名称	一句话	难度	状态	更新
WebDAV 同步失败误判为 WAF 拦截	用剪贴板工具 TieZ 的 WebDAV 同步做跨设备剪贴板，其他方法都正常，只有 MOVE …	—	可用	2026-10-14
双启动器竞争导致服务卡死	共享知识库服务在 13:20 突然不可用。去看机器：	—	可用	2026-10-09
服务进程脱离任务托管	一个常驻服务，手动在终端里启动之后运行正常，当天下午突然消失。	—	可用	2026-10-09
端口占用导致同域名本机访问 404	一个已经通过组网暴露的内部 Web 服务，出现了本机访问不到、但别的设备访问正常的怪现象：	—	可用	2026-10-09

五、写一篇的要求

每篇按「现象 / 环境 / 原因 / 解决 / 验证 / 经验」六节写，其中三条是硬要求：

1. 现象要能被人认出来：写症状，不写结论，并贴出可以原样搜索的报错原文。转述过的报错搜不到。
2. 原因要写到根因：连着问三次「为什么」。只写到第二层，结论就会是「下次小心点」；写到第三层，才能变成「加一把锁」。
3. 经验要能迁移：写判断规则，让读者遇到长得完全不一样的新问题时也能用上。

六、外部材料

系统补工程基础的公开材料，另见 补工程基础可以从这些公开材料开始。