From 34f698e5fb6543589833bf23c3b5755026e098e8 Mon Sep 17 00:00:00 2001
From: Joywayer <joywayer@163.com>
Date: Thu, 6 Aug 2026 17:13:12 +0800
Subject: [PATCH] =?UTF-8?q?docs(vps-xray):=20=E5=AE=9A=E6=97=B6=E9=87=8D?=
 =?UTF-8?q?=E5=90=AF=E9=85=8D=E7=BD=AE=E8=AF=B4=E6=98=8E=EF=BC=9Buninstall?=
 =?UTF-8?q?=20=E6=B8=85=E7=90=86=20guard=20=E4=B8=8E=E7=8A=B6=E6=80=81?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 vps-xray/.env.example | 19 ++++++++++++++-----
 vps-xray/README.md    | 36 ++++++++++++++++++++++++++++++++++++
 vps-xray/uninstall.sh |  7 +++++--
 3 files changed, 55 insertions(+), 7 deletions(-)

diff --git a/vps-xray/.env.example b/vps-xray/.env.example
index 6d5a06c..088d69c 100644
--- a/vps-xray/.env.example
+++ b/vps-xray/.env.example
@@ -21,11 +21,20 @@
 # REALITY_DEST=www.apple.com
 # REALITY_SNI=www.apple.com
 
-# 每日 04:00 自动重启 Xray（默认 false）
-# 崩溃恢复已由 systemd 的 Restart=always 覆盖（秒级响应），
-# 而每日硬重启会切断全部活动连接（跨夜下载、备份、CI 都会中断）。
-# 仅在确实观察到长期运行后性能退化时才改为 true。
-# XRAY_DAILY_RESTART=false
+# ===== 定时重启 =====
+# 0 = 关闭（默认）；N = 每 N 天重启一次 Xray。
+# 崩溃恢复已由 systemd 的 Restart=always 覆盖（秒级响应），而硬重启会切断
+# 全部活动连接。仅在确实观察到长期运行后性能退化时才启用。
+# XRAY_RESTART_EVERY_DAYS=0
+# XRAY_RESTART_TIME=04:00
+# XRAY_RESTART_TIMEZONE=Asia/Shanghai
+#
+# 改这几项无需完整重新部署，用轻量入口即可（不影响 vless 链接）：
+#   bash deploy.sh --restart 7 04:00
+#   bash deploy.sh --restart 0
+#
+# 旧字段 XRAY_DAILY_RESTART 已废弃，仅在上面三项都没设时作为兼容回退：
+# true → 每 1 天，其它 → 关闭。重跑部署后会自动换写成新字段。
 
 # 备份目录
 # BACKUP_DIR=/var/backups/xray
diff --git a/vps-xray/README.md b/vps-xray/README.md
index 6b393f2..4594268 100644
--- a/vps-xray/README.md
+++ b/vps-xray/README.md
@@ -193,6 +193,42 @@ xray tls ping www.apple.com     # 只看「Pinging with SNI」那一段
 
 脚本的候选列表因此只保留 Apple 系域名。
 
+### 定时重启
+
+默认**关闭**。崩溃恢复已由 systemd 的 `Restart=always` + `RestartSec=3` 覆盖（秒级响应），而硬重启会切断全部活动连接——跨夜下载、备份、CI 都会中断。仅在确实观察到长期运行后性能退化时才启用。
+
+需要时用轻量入口调整，**不会重装 Xray、不会重写配置、不会重启服务，现有 vless 链接完全不受影响**：
+
+```bash
+bash deploy.sh --restart 7 04:00   # 每 7 天 04:00 重启
+bash deploy.sh --restart 3         # 每 3 天，时间沿用 .env
+bash deploy.sh --restart 0         # 关闭
+bash deploy.sh --restart           # 按 .env 现有值重建 timer
+```
+
+对应 `.env` 三个字段：
+
+| 字段 | 含义 | 默认 |
+|---|---|---|
+| `XRAY_RESTART_EVERY_DAYS` | 0 = 关闭；N = 每 N 天 | `0` |
+| `XRAY_RESTART_TIME` | 24 小时制 `HH:MM` | `04:00` |
+| `XRAY_RESTART_TIMEZONE` | 时区 | `Asia/Shanghai` |
+
+#### 为什么不是纯 systemd timer
+
+`OnCalendar` 表达不了任意 N 天：`*-*-1/7 04:00:00` 是「每月 1、8、15、22、29 号」，**跨月会重置**——29 号到下月 1 号只隔 2~3 天。
+
+所以实现是 timer 每天到点唤醒，由 `/usr/local/bin/xray-restart-guard` 读 `/var/lib/xray/last-restart`，满 N 天才真正重启。间隔因此是「距上次实际重启」的真实天数，`N=3` 与 `N=7` 同样准确。
+
+查看下次触发时间与执行记录：
+
+```bash
+systemctl list-timers xray-restart.timer
+journalctl -u xray-restart.service -n 20
+```
+
+> 旧字段 `XRAY_DAILY_RESTART` 已废弃。三个新字段都未设置时它仍作为兼容回退（`true` → 每 1 天，其它 → 关闭），重跑部署后 `.env` 会自动换写成新字段。
+
 ### 查看状态 / 日志
 
 ```bash
diff --git a/vps-xray/uninstall.sh b/vps-xray/uninstall.sh
index 10bdc2a..f8f373b 100644
--- a/vps-xray/uninstall.sh
+++ b/vps-xray/uninstall.sh
@@ -84,10 +84,13 @@ fi
 systemctl disable xray 2>/dev/null || true
 
 # 每日重启 timer（旧版部署可能残留）
-if [ -f /etc/systemd/system/xray-restart.timer ]; then
+if [ -f /etc/systemd/system/xray-restart.timer ] \
+   || [ -f /usr/local/bin/xray-restart-guard ]; then
     systemctl disable --now xray-restart.timer 2>/dev/null || true
     rm -f /etc/systemd/system/xray-restart.timer \
-          /etc/systemd/system/xray-restart.service
+          /etc/systemd/system/xray-restart.service \
+          /usr/local/bin/xray-restart-guard \
+          /var/lib/xray/last-restart
     log "已移除每日重启 timer"
 fi