一本小型 VPN 运行手册该回答什么

接手凌晨 02:00 值班的人说不出服务是否健康，因为文档只解释了设计，从没说过该运行什么。把文件交给别人、然后离开房间，是唯一真正有效的测试。大多数小型 VPN 笔记在第二页就通不过它。下面的形状能通过这项测试，而且哪一部分都不必写长。

从一张疲惫的人也能扫一眼的地图开始

写下一时急着要查的东西：客户端连接的名字、守护进程监听的端口、它分发的地址池、客户端名字如何解析，以及隧道后面哪些网络本该可达。加上你实际运行的构建号，并写出每个活动部件的归属组件，因为路由、包过滤和客户端配置常常分在三处。外部依赖也要记下：托管账号、上联链路、身份提供方，以及远端私有网络。表格或手绘图比段落更能承载这些，因为读者是在扫，而不是在读。

然后写下谁有权批准紧急变更，以及一条不依赖隧道是否在线的联系路径。没有备用方案的升级链，恰恰在最需要它的那次事故里是死路。两个名字和一个电话号码就够了；地图不是员工名录。

每项检查都要给出那个算作健康的答案

为每项服务，把命令和足以证明它成功的那一行并排放好，读者就不必在慌忙中由一行推出另一行。进程状态和端到端可达性处在不同层次：一个说明守护进程接受了配置，另一个说明客户端能用上隧道提供的东西。两行都要写，并说明各自能抓住哪种故障，因为没有写明结果的检查，最后会变成一场关于输出看起来是否正常的争论。

systemctl status openvpn-server@lab
ss -lntu | grep 1194

两条都跑，并且把它们当作两份独立的证据，而不是一个序列。绿色的单元可能就挨着一条谁都连不上的隧道，反过来也会发生：监听还在，路由已坏。写明每一行观察的是哪一层，两者不一致时，读者就知道该信哪一个。

三种故障覆盖了大多数深夜

端点不可达、身份被拒，以及 连上了却没有可用流量，几乎解释了所有把人叫醒的情况。每一种都列出前两项检查和该上报给谁，这样 02:00 不必有人临时发明诊断顺序。不可达通常指向路径或监听端，身份被拒指向证书、凭据库或时钟，空连接则指向路由、转发或名字解析。这三条分支读的是不同的日志，所以必须先选分支，再打开日志。

链接上游文档，而不是粘贴你在这台主机上没跑过的命令。从别的环境抄来、没验证过的命令比一个指引更糟，因为它看起来权威，却会悄悄失败。

把变更写成顺序，而不是段落

任何变更都要按顺序记下：可以退回的检查点、确认成功的检查，以及触发回滚的条件。要包含一条不经过隧道的回程路径，因为你正在做的变更，恰恰可能把它关掉。记下当前的吊销如何恢复，而不是用更早的快照，因为过期的名单会悄悄重新接纳当天早上已经退役的凭据。编号的命令式步骤扛得住压力；散文会变成解释。

在真正需要之前演练那条回程路径，只要这项变更大到值得。凭记忆写下的回滚，是带日期的猜测。

凭据住在别处

引用密码管理器、保险库或密封信封，并说明谁可以打开，而不是在文件里摘录任何材料。私钥、一次性恢复码和嵌入了秘密的配置文件属于受保护的存储，页面应当说明有权限的维护者在 02:00 如何取得它们。绝不要把真实秘密当作示例，因为示例会被粘进工单和聊天串里。一个指引加一份权限清单，就是文档需要的全部。

在一次真实变更或恢复演练之后复查文件，删掉已不存在的路径，并注明下一次维护决策归谁。末尾保留三列变更记录：日期、改了什么、谁验证的。正是这一页告诉下一位读者其余部分是否最新，而 systemd 的 systemctl 文档 比转述会走样的服务命令更值得链接。