docs(vps-xray): 定时重启配置说明；uninstall 清理 guard 与状态文件

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

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

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