From 4c40169ee0cb0b188287219cca790a83f2e017ba Mon Sep 17 00:00:00 2001
From: shazhou-ww <shazhou.ww@gmail.com>
Date: Sat, 28 Mar 2026 14:28:53 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20systemd=20Restart=3Dalways=20=E7=AD=96?=
 =?UTF-8?q?=E7=95=A5=E7=BB=8F=E9=AA=8C=EF=BC=88=E4=BF=AE=E5=A4=8D=20LiteLL?=
 =?UTF-8?q?M=20=E4=B8=8D=E8=87=AA=E5=90=AF=E9=97=AE=E9=A2=98=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/shared/systemd-service-restart-policy.md | 52 +++++++++++++++++++
 mkdocs.yml                                    |  1 +
 2 files changed, 53 insertions(+)
 create mode 100644 docs/shared/systemd-service-restart-policy.md

diff --git a/docs/shared/systemd-service-restart-policy.md b/docs/shared/systemd-service-restart-policy.md
new file mode 100644
index 0000000..71b50c3
--- /dev/null
+++ b/docs/shared/systemd-service-restart-policy.md
@@ -0,0 +1,52 @@
+# systemd user service 的 Restart 策略陷阱
+
+## 问题描述
+
+LiteLLM 等服务使用 `Restart=on-failure` 配置，看似有自动重启能力，但实际上存在盲区：
+
+- 当进程收到 SIGTERM（正常终止信号）时，systemd 认为是"正常退出"（exit code 0）
+- `Restart=on-failure` 只在进程异常退出时重启，**不会在正常退出时重启**
+- 服务器重启、手动 stop、或某些维护操作都会发 SIGTERM，导致服务停止后不会自动恢复
+
+## 真实案例
+
+2026-03-28，NEKO 小队的 LiteLLM 在 3/27 收到 SIGTERM 后停止，由于 `Restart=on-failure`，systemd 没有自动重启它。导致小橘和其他 agent 全部无法工作（"LLM request failed: network connection error"），直到人工介入修复。
+
+同时发现 KUMA 小队的 LiteLLM 和 copilot-api 也存在同样的隐患。
+
+## 解决方案
+
+对于需要持续运行的关键服务，使用 `Restart=always`：
+
+```ini
+[Service]
+Restart=always
+RestartSec=5
+```
+
+## Restart 策略对比
+
+| 策略 | 正常退出(0) | 异常退出(非0) | SIGTERM | SIGKILL |
+|------|------------|-------------|---------|---------|
+| `on-failure` | ❌ 不重启 | ✅ 重启 | ❌ 不重启 | ✅ 重启 |
+| `always` | ✅ 重启 | ✅ 重启 | ✅ 重启 | ✅ 重启 |
+| `on-abnormal` | ❌ 不重启 | ❌ 不重启 | ✅ 重启 | ✅ 重启 |
+
+## 检查清单
+
+1. `grep "^Restart=" ~/.config/systemd/user/*.service` — 检查所有服务
+2. 关键服务（LiteLLM、copilot-api、openclaw-gateway）都应该是 `Restart=always`
+3. 确认 `loginctl show-user <user> | grep Linger` 是 `Linger=yes`（否则用户退出登录后 user service 全停）
+
+## 相关命令
+
+```bash
+# 修改后重载
+systemctl --user daemon-reload
+
+# 检查当前状态
+systemctl --user list-units --type=service
+
+# 手动测试重启
+systemctl --user restart litellm
+```
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 959e89a..f683d12 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -94,6 +94,7 @@ nav:
       - Memex 知识管理: shared/memex-knowledge-base.md
       - TTS 语音功能: shared/tts-guide.md
       - Agent 三层分工模型: shared/agent-division-of-labor.md
+      - systemd 重启策略: shared/systemd-service-restart-policy.md
 
 extra:
   social: