前几天晚上在家里那台上开 Claude CLI，聊到一半我才反应过来——它什么都不记得。。。那些”这个坑我们上个月踩过””这个方案试过不行”的结论，全都留在公司那台上了。我这边还得从头解释一遍。

于是花了个把小时把这事儿彻底解决掉。方案本身不复杂，但中间挖出来的几个东西挺有意思，值得写一篇，分享给需要有需要的朋友。

先搞清楚：记忆到底存在哪？

Claude Code 的记忆不是存在云端的，就是本地文件：

~/.claude/projects/<路径slug>/memory/*.md      # 每个项目的记忆，一条一个文件
~/.claude/projects/<路径slug>/memory/MEMORY.md # 该项目的记忆索引
~/.claude/CLAUDE.md                            # 全局偏好

关键在那个 slug。它是项目绝对路径转义出来的，规则很简单粗暴——非字母数字的字符统统换成短横线：

re.sub(r'[^a-zA-Z0-9]', '-', path)

所以我的 /Users/luyang.li/dev/notchy 就变成了 -Users-luyang-li-dev-notchy。注意用户名里那个点也被转成了横线，@、_ 同理，全都一视同仁。

统计了一下，我这边一共有 111 条记忆。数量不算多，但都是真金白银试出来的结论，重新攒一遍的成本可不低。

哪些能同步，哪些碰都别碰

第一反应可能是”把整个 ~/.claude 丢进 iCloud 不就完了”。千万别。

我扫了一遍那个目录，能同步的其实就这么几样：

1. projects/*/memory/ —— 各项目记忆
2. skills/ —— 自定义 skills
3. CLAUDE.md —— 全局偏好
4. settings.json —— 全局设置
5. mcp.json —— MCP 配置

其余的全是本机运行时状态，同步过去只会互相打架：history.jsonl、sessions/、各项目下的 *.jsonl 会话记录（我这边光这项就 364M）、file-history/（30M）、shell-snapshots/、plugins/ 缓存、telemetry/、还有 daemon 的认证文件。

更要命的是 ~/.claude.json——注意是家目录根下那个，不是 .claude/ 里面的。我打开一看，好家伙，某个 MCP server 的明文 access token 就躺在里面。这玩意儿要是跟着仓库推上去，那可就热闹了！

顺带一提，插件不用同步。settings.json 里的 enabledPlugins 和 extraKnownMarketplaces 已经完整描述了装了哪些插件、从哪个 marketplace 拉，换台机器它自己会去下。我这边 plugins/ 目录 14M，绝大部分是缓存和 marketplace 的 clone，同步纯属浪费。

目录用软链接，单文件用拷贝

方案就是建个私有 git 仓库 ~/dev/claude-config，把要同步的东西搬进去，原地留软链接。

REPO=~/dev/claude-config
mkdir -p $REPO && git -C $REPO init

# 以 skills 为例
mv ~/.claude/skills $REPO/skills
ln -s $REPO/skills ~/.claude/skills

但这里有个分野，我一开始没想到：目录可以软链接，单个文件不行。

原因是 Claude Code 自己会重写 settings.json（你 /model 切一次它就重写一遍）。而很多程序的”原子写”是先写临时文件再 rename——那一 rename，你的软链接就被替换成实体文件了，链接直接断掉，后面的改动再也进不了仓库。目录被这样整个替换的概率极低，所以目录安全。

于是最终是混合方案：

skills/                     -> 软链接，改动实时进仓库
projects/*/memory/          -> 软链接，同上
CLAUDE.md / settings.json / mcp.json
                            -> 拷贝，按 mtime 双向同步，每次跑脚本时自愈

还有个细节让我挺满意的：我那 39 个 skills 里有 20 个本身就是指向另一个仓库的软链接。git 会把符号链接以 mode 120000 原样存下来（存的是目标路径，不是内容），clone 到另一台机器上它还是软链接。推完我特意查了一下远端：

gh api 'repos/bones7456/<repo名>/git/trees/main?recursive=1' \
  | python3 -c "import json,sys; t=json.load(sys.stdin)['tree']; \
    b=[x for x in t if x['type']=='blob']; \
    print(len(b), '个 blob,', len([x for x in b if x['mode']=='120000']), '个符号链接')"

548 个 blob, 20 个符号链接

两台机器用户名不一样怎么办

还记得前面那个 slug 规则吗，坑来了。

我这台的用户名是 luyang.li，另一台是 lly。同一个项目 ~/dev/notchy，在两台机器上算出来的 slug 完全不同：

-Users-luyang-li-dev-notchy    # 这台
-Users-lly-dev-notchy          # 那台

直接把仓库里的目录名照搬过去，记忆就对不上了。而且反过来从 slug 推路径也不行——横线可能对应 /，也可能对应 .、@，甚至本来就是横线，信息已经丢了。

解决办法是在仓库里存一份 origins.tsv，记录每份记忆对应的原始绝对路径：

-Users-luyang-li-dev-notchy	/Users/luyang.li/dev/notchy
-Users-luyang-li-dev-shi	/Users/luyang.li/dev/shi

安装脚本读这个文件，把路径里的 home 前缀换成本机的，再重算一遍 slug 建软链接。这样只要 home 之后的路径一致，两边就能对上同一份记忆。

（生成这个映射表也有讲究：我没去反推，而是拿 ~/.claude.json 里 projects 字典的 key——那些本来就是绝对路径——正向算 slug 建的对照，14 个全中。）

挂上 hooks，让它自己跑

同步脚本写好了，接下来是自动化。Claude Code 的 hooks 正好有两个合适的事件：

"hooks": {
  "SessionStart": [
    { "hooks": [{ "type": "command", "command": "\"$HOME/dev/claude-config/sync.sh\" pull", "timeout": 30 }] }
  ],
  "SessionEnd": [
    { "hooks": [{ "type": "command", "command": "\"$HOME/dev/claude-config/sync.sh\" push", "timeout": 30 }] }
  ]
}

这里用 $HOME 而不是绝对路径，因为 settings.json 这个文件本身也会被同步到另一台机器上去，写死路径那边就废了。

SessionEnd 到底什么时候触发？

配完我就犯嘀咕：SessionEnd 具体什么时候跑？关终端算不算？

翻了下 settings 的 schema，它只在事件名枚举里出现，没有说明。与其猜，不如直接从本机的 CLI 二进制里找。我这个版本是 2.1.247：

F=~/.local/share/claude/versions/2.1.247
grep -a -o -E '.{130}prompt_input_exit.{130}' "$F" | head -5

第一条就中了：

Vs=["clear","resume","logout","prompt_input_exit","other"],Qs=s(()=>a(Vs)),Zs=s(()=>h().and(t({hook_event_name:n("SessionEnd"),reason:Qs()})))

紧挨着 hook_event_name:"SessionEnd" 的就是 reason 的枚举，一共五个值：

1. clear —— 执行 /clear
2. resume —— 切走去别的会话
3. logout —— 执行 /logout
4. prompt_input_exit —— 从输入框正常退出
5. other —— 兜底

最意外的是 /clear 也算 SessionEnd。这意味着我的 push 不是”一天一次”，而是每次清上下文都会提交推送一遍，同步粒度比预想的细多了，挺好。

再往下挖，找到了执行时机：

async shutdown(e=0,t="other",n){
  if(this.shutdownInProgress)return;
  this.shutdownInProgress=!0, process.exitCode=e, ...
  let{executeSessionEndHooks:r,getSessionEndHookTimeoutMs:o}=await import("...");
  let s=o();
  this.armShutdownFailsafe(Math.max(5000,s+5000),e);

hooks 跑在 process.exitCode 设定之后、进程真正退出之前，而且有个失效保险：超过 max(5秒, 超时+5秒) 就强制退出。所以 SessionEnd hook 里别干重活，我这个只在本地 commit，真正的 git push 甩到后台跑。

那硬退出呢？我找到这么一行：

process.on("SIGTERM", () => process.exit())

裸的 process.exit()，不走 shutdown()，也就不跑 hook。SIGKILL 就更不用说了。（CLI 里 SIGTERM/SIGINT/SIGHUP 有好几处注册，分属不同上下文，我没法干净地判断直接关终端窗口走的是哪条路径，所以这条只能算”很可能”，不算证实。）

所以 pull 也得先 commit

上面这个结论直接推翻了我原本的脚本设计。

原来 pull 是这么写的：

git pull --rebase --autostash

--autostash 会把未提交的改动 stash 起来、rebase 完再放回来——但放回来之后它还是未提交状态。万一某次 SessionEnd 没跑成（进程被硬杀了），那批记忆就一直悬在工作区里，没提交更没推送，另一台机器永远看不到。

改法很简单：pull 开头先 commit 一次。

pull)
    link_dirs
    sync_files
    commit_local "recovered"          # 先落袋为安
    if has_remote; then
        git -C "$REPO" pull --rebase --autostash -q || echo "pull 失败，请手工查看"
        n=$(unpushed_count)
        [ "$n" -gt 0 ] && echo "  ↑ 补推 $n 个未推送的提交"
        push_background
    fi
    sync_files                        # 把刚拉下来的内容拷出去
    exit 0
    ;;

这样只要还能开一次会话，上次漏掉的东西就一定会被补上。提交信息前缀用 recovered，跟正常退出的 sync 区分开，翻 log 时一眼能看出这批改动是怎么进来的。

最后

整套跑下来，仓库 548 个文件、.git 才 2.9M，所有项目的记忆全接管了。现在的循环是这样：会话开始 pull，中间的改动经软链接实时落到仓库，会话结束（或者 /clear）commit 加后台 push。

顺带说一句，为什么不用 iCloud 或者 Dropbox——它俩当然也能跑，把仓库路径换成云盘目录、软链接照建就行，还省掉 hooks。但记忆这东西天然就是”一句话一个文件”，太适合版本化了；万一两台机器同时改了同一条，git 会明明白白报冲突让你处理，云盘则是悄悄给你生成一个”冲突副本”，你可能几个月都发现不了。。。

不说了，我去家里那台上 clone 一遍试试。要是 origins.tsv 那套换算真能对上，那 111 条记忆就算是彻底安全了——毕竟这里头有不少是当初排查内存泄露那种熬了半天才熬出来的结论，再丢一次我可真要哭了！

The post Claude Code 的记忆同步大法 first appeared on I am LAZY bones?.

这种”整夜监测只录到一半”的问题最难受的地方在于：它不报错、不崩溃、不留任何痕迹。App 就是在某个时刻悄无声息地没了，第二天你只看到一条被截断的记录。

这篇写的就是把这件事查清楚的全过程——从设备里的 JetsamEvent 报告，到 Instruments 的 Generation 快照，最后落到一行 SwiftUI 代码上。中间还有一段完整的、被自己推翻的错误推断，作为教训一并写了进来。

第一步：先确认它是”被杀的”还是”自己停的”

这两种情况的修法完全不同，不能靠猜。

我的 App 在监测过程中每 5 分钟往 UserDefaults 写一次检查点，进程要是被强杀，下次启动时会拿检查点的时间去补 endTime（不然历史里就是一条 endTime 为空的孤儿记录）。所以判据现成的：

开始 00:01:36
结束 02:06:36
差值 7500 秒 = 25 × 300

正好是检查点间隔的整数倍。如果是正常停止，endTime 会是任意时刻；只有走孤儿恢复才会精确落在检查点节拍上。 结论：进程在 02:06:36 到 02:11:36 之间没走正常的停止流程就没了。

顺带说个同一晚的另一个 bug，跟主线无关但挺典型的：

>>> import struct; struct.pack('>I', 2003329396)
b'what'

CoreAudio 的错误码经常是四字符码，2003329396 就是 'what'。触发路径是：点开始 → 5 秒预备倒计时 → 我顺手按了锁屏键 → 倒计时在后台结束 → 这时才去开麦。而 UIBackgroundModes: audio 这个豁免只保”已经在录的继续录”，不保”后台新开麦”，系统直接拒了。改法很简单：把开麦挪到倒计时之前，会话在麦克风激活之后，锁屏就管不着了。

JetsamEvent 报告怎么读

iOS 上的查看路径是 设置 → 隐私与安全性 → 分析与改进 → 分析数据，往下翻找 JetsamEvent-年-月-日-时分秒.ips。这个文件是两段 JSON 拼起来的：第一行是头，剩下是正文。

import json
raw = open("JetsamEvent-2026-08-16-020855.ips").read()
d = json.loads(raw.split("\n", 1)[1])
PS = d["memoryStatus"]["pageSize"]          # 16384
for p in sorted(d["processes"], key=lambda x: -x["rpages"])[:5]:
    print(f'{p["name"]:24} {p["rpages"] * PS / 1048576:8.1f} MB  prio={p["priority"]}')

几个关键字段：

1. rpages × pageSize 是各进程占的内存，注意 pageSize 现在是 16 KB 不是 4 KB。
2. physicalPages.internal 是 [clean, dirty]，脏页才是真正赖着不走的那部分。
3. age 单位是纳秒，用报告时间减一下就能反推每个进程什么时候启动的。
4. 带 reason 字段的那几条才是这次事件里被杀的，其余是快照。
5. largestProcess 直接告诉你当时谁最胖。

我这份 02:08:55 的报告里，NightSnore 压根不在进程列表里——说明它在这次事件之前就已经被杀了。当时整机也确实在雪崩：可用内存 162 MB、compressor 涨到 1.87 GB、最后三分钟有 172 个进程被杀了重启，连 SpringBoard 自己都撞了 per-process 上限。

真正的实锤在另一份 ips 文件里，因为我发现还有一份六天前的：

NightSnore   rss = 1814.3 MB   dirty = 1734 MB   purgeable = 0
             prio = 100   states = [active]   age = 29.5 分钟
largestProcess: NightSnore

监测跑了 29.5 分钟，进程涨到 1.8 GB，其中 1.73 GB 是脏内存。 全机最大。那次系统没杀它，而是把 180 多个闲置进程 idle-exit 掉给它让路。

到这儿性质就清楚了：不是什么玄学的后台调度问题，就是漏内存漏到撑爆。

证据不够的时候，别急着改代码

这一节是我这次最大的教训。

拿到 1.8 GB 这个数之后，我去读音频管线的代码，很快”找到”了三处无上界结构：波形显示每来一个音频 buffer 就起一个 Task { @MainActor } 把整块样本捕获进去；两级 DispatchQueue 都是无条件 async，处理端一慢就会无限堆积。三处加起来的量级估算下来跟观测值挺接近。

于是我给队列加了背压、给波形加了节流。改完确实好了一些——但这是推断，不是证据，这里其实浪费了很多时间。

Instruments 的 Generation 快照发现根因

Xcode 的 Memory Report 只能告诉你”在涨”：

(可以发现，除了内存一直涨，CPU也很高这个后面也一起修复了）

要知道”谁在涨”，得用 Instruments 的 Allocations，核心功能是 Mark Generation：

1. Product → Profile（⌘I），选 Allocations
2. Recorder Settings 里面的 Recording mode 要选 Immediate
3. 跑一分钟，点一下 Mark Generation
4. 再跑三分钟，再点一次
5. 展开第二个 Generation，看 Growth 列

Growth 只列”两次快照之间新增、且到现在仍然存活”的对象——这就是内存泄漏的定义。别的视图都会被大量正常的临时分配淹没，只有这个视图干净。

结果一眼就能看出问题：

UnknownObjectType                        5.71 MiB   25,584
_ContiguousArrayStorage<AnyViewTrait>    2.16 MiB    5,904
ImageProviderBox<NamedImageProvider>   553.50 KiB    5,904
LocalizedTextStorage                   461.25 KiB    5,904
AnyViewStorag<Label<Text, Image>>     369.00 KiB    5,904
TagIndexProjection<Int>                184.50 KiB    1,968
_TtCC5UIKit12_UITabButton…              96.00 KiB        6

跟音频、跟 CoreML、跟我改了半天的那些队列，一点关系都没有。全是 SwiftUI，而且全是 TabView 标签栏的零件：Label<Text, Image> 是三个 tab 项，NamedImageProvider 是 tab 图标，LocalizedTextStorage 是 tab 标题，TagIndexProjection<Int> 是 .tag()，最后还有 UITabButton 本体。

UnknownObjectType：

AnyViewTrait：

真正把结论钉死的是数字本身：

5,904 = 3 × 1,968     （三个 tab）
1,968 ÷ 180 秒 = 10.9 次/秒

10.9 次每秒——正好是音频 buffer 的到达频率。

根因：根视图订阅了高频 @Published

顺着这个频率回去看代码，一行就找到了：

struct ContentView: View {
    @ObservedObject private var monitoringService = MonitoringService.shared
    // ...
    TabView(selection: $selectedTab) {
        MonitoringView().tabItem { Label("监测", systemImage: "waveform.circle.fill") }.tag(0)
        SessionListView().tabItem { Label("历史", systemImage: "clock.fill") }.tag(1)
        SettingsView().tabItem { Label("设置", systemImage: "gearshape.fill") }.tag(2)
    }
}

MonitoringService 里有个 @Published var audioSamples: [Float]，监测时每秒更新约 11 次给波形图用。链条是这样的：

audioSamples 每秒发布 11 次
  → ContentView.body 每秒重算 11 次
    → 整个 TabView 连同三个 .tabItem { Label(...) } 重建
      → SwiftUI 把标签项的内部存储泄漏掉

一小时约 200 MB，整夜下来就是 GB 级。而且这跟屏幕亮不亮无关——锁屏后 SwiftUI 不渲染了，但 body 该重算还是重算。

根视图的 body 其实根本不依赖任何监测状态，它只是需要在两个字段变化时做点事而已。那就别观察整个对象，改成订阅具体的 publisher：

private let monitoringService = MonitoringService.shared   // 不再是 @ObservedObject

// ...
.onReceive(monitoringService.$finishedSessionForSummary) { _ in presentSummaryAfterPublish() }
.onReceive(monitoringService.$audioError)                { _ in presentSummaryAfterPublish() }

同样口径复测：

修之前              修之后
Growth       10.81 MiB          581 KiB
存活对象      61,631            609

字节数降了 19 倍，对象数降了 101 倍。后者才是关键信号——”每帧泄一批”的模式没有了。剩下那 581 KiB 里 80% 是 4 个 CALayer 后备存储和 1 次 SQLite 页缓存增长，都是一次性的。

支持，内存泄露的问题算是解决了，再去看CPU使用率，也从 75% 降到了 5% 不到。

几个坑

1. @Published 是在 willSet 时发布的。 换成 .onReceive 之后，闭包跑在属性真正写入之前，这时候回读那个属性拿到的还是旧值——比如 audioError 明明马上要变成 nil，读出来仍然非 nil，判断就全反了。要么用闭包参数带过来的新值，要么推到下一个主队列 turn 再处理。

2. 本进程不在 JetsamEvent 列表里，不代表这份报告没用。 它恰恰说明进程在这次事件之前就已经被杀了，应该去找更早的那份。iOS 不会为每次 kill 都写报告，也会轮转，所以未必找得到。

3. Xcode Organizer 的 Terminations / Memory 面板需要足够用户量。 我的 App 用户少，那儿一直显示 Insufficient usage data。真要在生产环境拿这个数据，得自己接 MetricKit——MXAppExitMetric.backgroundExitData 会把后台退出按原因分桶（memoryResourceLimit / memoryPressure / cpuResourceLimit / appWatchdog / normal），MXMemoryMetric.peakMemoryUsage 给峰值内存，而且不依赖样本量。注意 payload 是按天生成、日终才交付的，今天出的事明天才读得到。

4. 有界即可控，无论多大。 我中途一度去调小音频缓冲的上限、给队列加背压丢帧——那是让泄漏变慢，不是修泄漏，而且丢帧会漏掉真实的鼾声事件。判据应该是”有没有上界”，不是”占了多少”：有上限封顶的缓冲填到 80 MB 是可控的，无上界的队列涨到 10 MB 才是 bug。根因定位之后，那些基于错误推断做的改动我全部还原了。

5. 别给泄漏加兜底。 我还写过”剩余内存不足就自动结束监测”的保护，听起来很负责，实际上根因修掉之后它只剩下误停正常会话的风险。也删了。

回头看

整件事的证据链是这样一条：endTime 落在检查点整倍数上（判定被杀）→ JetsamEvent 报告（拿到 1.8 GB 这个量级）→ git log（作废错误推断）→ Instruments Generation（点名到具体对象）→ 对象个数 = 3 × body 重算次数（锁定根因）。

前面几步都是旁证，只有 Generation 快照那一步是真正指名道姓的。我在拿到它之前写的所有”修复”，事后看全是在给一个不存在的病开药。读代码能产生假设，但假设需要被证据杀死或者证实，中间那一段自己觉得”应该就是这个了”的笃定，最不可信。

不说了，我赶紧发新版本去了，这APP之前是下载就收费，刚改成免费试用+一次性买断的模式，结果免费用户就遇到了内存泄露，异常退出的大问题，实在是很不应该。。。对我的打击也实在是有点大！

The post 一个iOS APP内存泄露排查案例 first appeared on I am LAZY bones?.

而读书，也是这个道理。

虽然你不是亲自去某个地方，但通过文字，你就能感受到笔者所描述的世界，而且这个成本更低。不仅成本低，你还可以进入到“非现实的世界”，比如你读历史，可以进入“过去的世界”；你读玄幻类的，可以进入“虚拟的世界”。在某种意义上，这些都是超越旅行的存在。

当然，我最近读的《阿勒泰的角落》进入的倒是一个“真实的世界”，而且这个世界，说起来我还去过，2022年我来新加坡之前，曾经开着房车游过新疆。我花了半个月时间，在北疆转了一圈，但新疆真的太大了，即使半个月对打工的牛马来说，已经很奢侈了，但我肯定不能说对阿勒泰很熟了。我只是禾木、阿勒泰这样转了几个景点。

而本书的作者，虽然不是新疆人，但却感觉是土生土长在新疆的，而且体感上，应该比我大不了几岁（这个后来我查资料证实了）。从她自己的描述来看，她的学历应该不算高，但文笔却出奇地好，文字看着很舒服，不堆砌辞藻，但却很有画面感，就像你的邻居在给你讲述生活细节一样。呈现给读者的绝大部分是朴实到有点朴素的文字，偶尔镶嵌了恰到好处的“高光”。

内容是关于她在新疆生活的方方面面，包括开店经商的种种经历、谈恋爱又分手的经历、多次搬家的经历以及日常生活的一些细节，但因为那种生活是绝大部分读者所不会经历的，所以读起来就会很有意思。她们一家子人，虽然不是逐水草而居的游牧民族，但不同时期也住在阿勒泰的不同角落，因此也发生了很多不同的故事。

这里就不剧透太多细节的内容了，总之这是一本读起来很轻松的书，就像一次旅行，所以推荐给大家。

The post 《阿勒泰的角落》读书笔记 first appeared on I am LAZY bones?.

原因可能有三个：主要原因我觉得还是因为我太懒了，哈哈！其次就是市面上也确实已经有蛮多性价比挺高的API中转站了！最后一个原因是担心被封号，总觉得不太好。

说到这里，这里再给不知道Sub2API是什么的读者来一句话科普一下，这就是一个把你在 OpenAI、Anthropic 包月订的pro/plus/max等套餐，转成API调用的一个开源软件。有了它就可以不用再花真金白银按量买token了，市面上大部分token中转站也是用了这个项目的原理甚至是代码。

然后，我最近有一个订阅账号要取消订阅了，但离到期还有十天半个月的，这种状态反正也不怕被封了，就打算尝试了一下。

我选择的是Docker Compose的方式跑，安装官方教程，几个命令就能跑起来了。毕竟是成熟项目，已经是非常傻瓜化的操作方式了。

安装完后，本地的端口就可以直接打开后台页面了，挂到nginx，配个子域名和证书啥的，给自己用就绰绰有余了。

对了，如果你也用docker起来的，并且找不到 admin@sub2api.local 这个默认用户的密码的话，可以执行 docker compose logs sub2api | grep -i "admin password" 这个命令，就可以看到类似 sub2api | Generated admin password (one-time): xxxxxx 这串随机生成的默认密码了。

然后，如果有什么概念，需要介绍一下的话，可能就是 Group（分组）了！这个分组，可以说连接各种概念的核心了。比如上游账号、下游用户、订阅还是按量计费 等实体，都要通过分组来实现相互的关联，包括是否运行“生图模型”的调用等，也都属于分组的一个属性。

其他的，如果是自用的话，似乎也没啥可以介绍的了。如果要拿来对外服务，我想更多也是怎么获取用户、怎么营销等的事情。哦，可能还要考虑怎么接各种支付系统和客服系统吧！就不能像我一样，给自己直接充1万刀了，哈哈！

我还发现：按它后台的计费方式，生图API是真赚钱啊！难怪市面上的中转站对生图API的折扣都能做到很低！

跑了不少图出来，对这个账号也算是物尽其用了吧！

The post Sub2API first appeared on I am LAZY bones?.

[2026-07-28 06:48:02] || Server: Loaded 7 pinned rooms
[2026-07-28 06:48:02] || Server: Starting server at wss://0.0.0.0:8765

重启就重启吧，本来没当回事。结果顺手打开本博客——打不开。又试了下这台机器上跑的其他站，也全打不开。好家伙，整台机器的 nginx 全躺了，而且看时间已经躺了三个多小时。

先看现场

第一件事是确认机器有没有重启过。uptime 一看，没有，机器好好的。那就是 nginx 单独出事了。systemctl restart nginx 下去，唰一下全恢复了。

服务是回来了，但这更让人不安：能 restart 成功，说明磁盘上的配置本来就是好的，那它三个小时前到底为什么起不来？翻 unit 日志：

$ sudo journalctl -u nginx.service --since "6 hour ago" --no-pager
Jul 28 06:48:02 s systemd[1]: Stopping nginx.service - A high performance web server and a reverse proxy server...
Jul 28 06:48:02 s systemd[1]: nginx.service: Deactivated successfully.
Jul 28 06:48:02 s systemd[1]: Stopped nginx.service - A high performance web server and a reverse proxy server.
Jul 28 06:48:02 s systemd[1]: nginx.service: Consumed 19min 12.963s CPU time, 117.6M memory peak, 0B memory swap peak.
Jul 28 06:48:02 s systemd[1]: Starting nginx.service - A high performance web server and a reverse proxy server...
Jul 28 06:48:02 s nginx[2766192]: 2026/07/28 06:48:02 [emerg] 2766192#2766192: host not found in upstream "bones7456.github.io" in /etc/nginx/sites-enabled/luy:75
Jul 28 10:00:10 s systemd[1]: Starting nginx.service - A high performance web server and a reverse proxy server...
Jul 28 10:00:10 s systemd[1]: Started nginx.service - A high performance web server and a reverse proxy server.

host not found in upstream。我博客有几个路径(比如这个)是反代到 GitHub Pages 的，nginx 起来的时候要解析 bones7456.github.io，那一刻没解析出来，直接 emerg 拒绝启动。

再一看，06:48 这个时间点太像 Debian 系的 cron.daily 窗口了（/etc/crontab 里是 6:25，加上 anacron 的随机延迟，另外 cron.weekly 是 6:47，更像），我当时第一反应是 certbot 续期把 nginx 重启崩了。结果把那五分钟的全量日志拉出来一看，跟 certbot 半毛钱关系没有。所以还是那句话：别猜，看日志。

1 秒的竞速

把 journalctl --since "06:45" --until "06:50" 全量捞出来，真凶一目了然：

06:47:50  Starting apt-daily-upgrade.service       <== unattended-upgrades 开跑
06:47:57  systemd[1]: Reexecuting requested from client PID ... (unit apt-daily-upgrade.service)
          systemd 255.4-1ubuntu8.16 running in system mode  <== systemd 自己被升级了

06:48:02  ★ 满机器的服务被批量重启（needrestart 干的）
          Stopping named...  <== named 被停掉，不再监听 127.0.0.1#53
          Stopping nginx...  <== nginx 被停掉
          Starting nginx...  (PID 2766192) <== nginx 再次启动
             └─ [emerg] host not found in upstream "bones7456.github.io" <== nginx 报错失败了
                nginx.service: Control process exited, code=exited, status=1/FAILURE

06:48:03  Starting named...  (PID 2766508)
          named: listening on IPv4 interface lo, 127.0.0.1#53   <== named 启动，DNS 回来了

看明白了：systemd 被 apt 自动升级，触发 needrestart 把机器上几乎所有服务全重启一遍。我这台机器上跑着 BIND 做内网 DNS，于是 named 和 nginx 一起被拖下水。

nginx 在 06:48:02 查 DNS，named 在 06:48:03 才恢复监听。就差 1 秒，nginx 输了这场竞速，代价是三个多小时的全站宕机。

最扎心的是同一批重启里的对比：php-fpm、redis、mariadb，还有我自己那几个 Flask 服务，全都 Started 成功了。唯独 nginx 死了。为什么？因为只有 nginx 在启动阶段需要解析外部域名，别的服务都不需要。

为什么 After=nss-lookup.target 没救下它

这才是这次最值得说的地方。翻开 Ubuntu 自带的 nginx unit：

[Unit]
Description=A high performance web server and a reverse proxy server
After=network-online.target remote-fs.target nss-lookup.target
Wants=network-online.target

nss-lookup.target 是 systemd 专门用来表示”域名解析已就绪”的标准锚点，DNS 服务一般会用 Before=nss-lookup.target 把自己挂上去。也就是说，nginx 早就声明过”我要等 DNS 就绪再启动”——然而它还是死在了 DNS 上。

原因在于After= 的语义被普遍误解了：

它只在同一个 systemd job transaction 内部编排启动先后，并不检查目标服务的实时健康状态。

needrestart 是逐个执行 systemctl restart <unit> 的，nginx 和 named 属于两个互相独立的 transaction，彼此之间没有任何排序约束。更要命的是，nss-lookup.target 是个 passive target，named 停止时它并不会跟着 deactivate，全程保持 active——于是 nginx 一查”依赖满足了吗”，满足，启动，然后一头撞死。

所以结论挺反直觉的：在 restart 场景下，After= 基本等于安慰剂。指望靠加一行 After=named.service 来防这类问题，是防不住的。

两道防线

既然顺序编排靠不住，那就换思路：一道事后自愈，一道事前免疫。

防线一：让它自己重试

Ubuntu 的 nginx.service 默认没有 Restart=，意味着启动失败一次就永久 failed，没有任何重试。而这次 named 只用了 1 秒就恢复——只要能重试一次，整件事根本不会发生。

sudo mkdir -p /etc/systemd/system/nginx.service.d
sudo tee /etc/systemd/system/nginx.service.d/override.conf <<EOF
[Unit]
StartLimitIntervalSec=600
StartLimitBurst=20

[Service]
Restart=on-failure
RestartSec=10
EOF
sudo systemctl daemon-reload

StartLimit 那两行不是可选的：systemd 全局默认是 10 秒内最多 5 次，配上 RestartSec=10 会立刻撞上限流然后彻底放弃。改成 10 分钟内 20 次，才扛得住像样的 DNS 故障。

这里补一个 drop-in 的合并规则，很多人会搞混：

1. 标量指令（Restart=、RestartSec=、Type=、PIDFile=…）是覆盖。
2. 列表指令（After=、Wants=、Environment=、ExecStartPre=…）是追加，不是覆盖。想清空得先写一行空赋值 After= 再写新值 Update：After=还不能被清空，详见下方评论。
3. ExecStart= 是重灾区：Type=forking 下只允许一条，直接在 drop-in 里写会报错，必须先 ExecStart= 清空再写。

想看合并后到底生效了什么，别看文件，看这个：

systemctl cat nginx                      # 看拼了哪些文件
systemctl show nginx -p After -p Restart -p RestartUSec   # 看最终生效值，配置项是 RestartSec 对应的生效值是 RestartSec

还有个细节值得确认：这次失败的其实是 ExecStartPre 里的 nginx -t -q（日志里那句 Control process exited, code=exited, status=1/FAILURE，result 是 exit-code）。Restart=on-failure 是覆盖这种情况的，不用担心它管不到。

防线二：别让 nginx 在启动期解析域名

自愈只是兜底，根上的毛病是：一个 location 的 upstream 解析不了，整个 nginx 拒绝启动，机器上所有站点陪葬。nginx 的配置校验是 all-or-nothing 的，一个小站点的临时故障被放大成了全局故障。

解法是给 proxy_pass 用变量——只要 proxy_pass 里含变量，nginx 就不再在启动期做一次性解析，改成运行时按需查 resolver。这样 DNS 挂了 nginx 照样能起来，最坏只是那一个 location 返回 502。

但这里有个大坑，下面单独说。

变量化 proxy_pass 的那个坑

我原来的配置是这样的，注意 proxy_pass 后面带了路径：

location ^~ /data/shi/ {
    proxy_pass https://bones7456.github.io/china-dynasty-timeline/;
    proxy_ssl_server_name on;
    proxy_set_header Host bones7456.github.io;
    ...
}

如果你天真地把域名换成变量，写成 proxy_pass https://$gh_pages/china-dynasty-timeline/;，就掉坑里了。nginx 的规则是：

1. proxy_pass 不含变量且带 URI → nginx 做前缀替换，把 location 匹配掉的 /data/shi/ 换成 /china-dynasty-timeline/。
2. proxy_pass 含变量 → 前缀替换机制彻底失效，URI 被固定成你写的那个。

后果是这样的：

请求 /data/shi/              原配置 → /china-dynasty-timeline/               ✓
                             变量版 → /china-dynasty-timeline/               ✓
请求 /data/shi/assets/app.js  原配置 → /china-dynasty-timeline/assets/app.js  ✓
                             变量版 → /china-dynasty-timeline/               ✗

首页看着还挺正常，所有子资源全部错位——CSS、JS、图片全挂。这种”打开一看好像没事”的故障最恶心。

正解是用 rewrite ... break 手动接管路径映射，配一个不带 URI 的 proxy_pass。nginx 文档明确写了：proxy_pass 不带 URI 时，若 URI 已被 rewrite 改写，传递的就是改写后的 URI——正是我们要的。

先在 server 块里放解析器和变量：

resolver 127.0.0.1 1.1.1.1 8.8.8.8 valid=300s ipv6=off;
resolver_timeout 5s;
set $gh_pages "bones7456.github.io";

然后 location 改成：

location ^~ /data/shi/ {
    rewrite ^/data/shi/(.*)$ /china-dynasty-timeline/$1 break;
    proxy_pass https://$gh_pages;

    proxy_ssl_server_name on;
    proxy_ssl_name bones7456.github.io;
    proxy_set_header Host bones7456.github.io;

    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # 避免 GitHub Pages 返回的跳转暴露 github.io 域名
    proxy_redirect https://bones7456.github.io/china-dynasty-timeline/ /data/shi/;
    proxy_redirect https://bones7456.github.io/ /data/shi/;
}

实际只动了三处：加 rewrite ... break、proxy_pass 去掉路径换成变量、显式加 proxy_ssl_name（它默认取 $proxy_host，变量化后写死更稳）。proxy_redirect 是字面量匹配，不受影响。查询串也会自动带过去，/data/shi/a?b=1 照常工作。

几个坑

1. resolver 里写多个地址是轮询，不是主备。我这里反代的是公网域名，两个 DNS 都能解析，正好互为冗余；但如果你要反代本机 named 里那些内网 zone，就绝不能这么写——轮询到 1.1.1.1 直接解析失败。那种 location 得单独配 resolver 127.0.0.1;。
2. ipv6=off 是刻意加的。变量化之后每次请求都要重新解析，家宽 IPv6 到 GitHub 的连通性又不一定稳，少一个变数是一个。确认 IPv6 走得通再打开。
3. 别指望 After= 能防住 restart 场景，前面说透了。它在正常开机时有用，成本为零可以留着，但不能当防线。
4. nginx -t 通过不代表这次改对了。它只校验语法，rewrite 的路径映射对不对，它一个字都不会告诉你。

怎么验证真的修好了

改完一定要实测，光看配置”觉得对”没用。先验路径映射——必须测子路径，别只测首页：

curl -sI https://luy.li/data/shi/ | head -3
# 从页面里抓个真实静态资源来测，期望 200 而不是 404
curl -s https://luy.li/data/shi/ | grep -oE '(src|href)="[^"]+\.(js|css)"' | head -3

说点本质的

复盘下来，这次事故里有三个独立的问题，任意修掉一个都不会出事：nginx 没有真正可靠的 DNS 就绪依赖、配置在启动期硬依赖 DNS、失败之后没有任何重试。三个凑齐了，一次 1 秒的 DNS 抖动才放大成 3 小时的全站宕机。

而我最想留下的一条经验是：别把系统的健壮性寄托在”顺序”上。After=、Before=、network-online.target 这些东西给人一种”我已经处理好依赖了”的错觉，但它们描述的是编排意图，不是运行时的真实状态。真正靠得住的只有两种东西——失败了能自己重试（自愈），和压根不依赖那个东西（免疫）。分布式系统里讲了很多年的道理，放在单机 systemd 上一样成立。

最后再补一句题外话：这次是我早上”顺手看了眼日志”才发现的，不然还得挂更久。所以监控该上还是得上，healthchecks.io、UptimeRobot 之类的免费额度足够个人站用了。再优雅的配置优化，也不如有人（或者有个机器人）在你睡觉的时候盯着。

全文完。

The post 记一例 nginx 故障分析 first appeared on I am LAZY bones?.