文档新增说明restart

vps-xray/README.md

@@ -220,22 +220,76 @@ bash deploy.sh --restart           # 按 .env 现有值重建 timer
 | `XRAY_RESTART_TIME` | 24 小时制 `HH:MM` | `04:00` |
 | `XRAY_RESTART_TIMEZONE` | 时区 | `Asia/Shanghai` |
 
+#### 查看当前配置与重启记录
+
+**一条命令看全** —— 不带参数的 `--restart` 只按 `.env` 现值重建 timer，不改配置、不重启服务：
+
+```bash
+bash deploy.sh --restart
+```
+
+输出里包含当前间隔与时间、**上次实际重启**、**下次实际重启**。
+
+分项查看：
+
+```bash
+# 1. 配置值
+grep '^XRAY_RESTART_' /opt/vps-xray/.env
+
+# 2. timer 是否启用、下次唤醒时间
+systemctl list-timers xray-restart.timer
+
+# 3. 确认时区真的生效（最容易出错的一项）
+systemctl show xray-restart.timer -p TimersCalendar
+
+# 4. 上次实际重启的时间戳
+cat /var/lib/xray/last-restart                       # Unix 时间戳
+date -d "@$(cat /var/lib/xray/last-restart)"         # 可读格式
+
+# 5. 守卫每次唤醒后的判断记录（跳过还是执行）
+journalctl -u xray-restart.service --no-pager -n 50
+
+# 6. xray 进程最近一次启动的时刻
+systemctl show xray -p ActiveEnterTimestamp --value
+```
+
+第 3 条的输出应形如：
+
+```
+{ OnCalendar=*-*-* 04:00:00 Asia/Shanghai ; next_elapse=Fri 2026-08-07 20:00:00 UTC }
+```
+
+**里面必须看得到时区。** 若只有 `OnCalendar=*-*-* 04:00:00` 而没有时区，说明时区没生效，systemd 会按服务器的系统时区解析——多数 VPS 是 UTC，那样设的「04:00 北京时间」实际会在**中午 12 点**触发，偏移 8 小时且没有任何提示。
+
+> 早期实现把时区写成 `[Timer]` 段的 `TimeZone=`，而 `systemd.timer` 根本没有这个 key——写了只会在 journal 里留一行 `Unknown key name 'TimeZone' in section 'Timer', ignoring.` 然后按本地时区解析。排查时可以顺手确认一下：
+>
+> ```bash
+> journalctl -b | grep -i "unknown key name"
+> systemd-analyze verify /etc/systemd/system/xray-restart.timer
+> ```
+
+第 5 条的日志长这样：
+
+```
+xray-restart-guard[1234]: 距上次重启不足 7 天（已过 3 天），跳过
+xray-restart-guard[5678]: 距上次重启已满 7 天，执行重启
+```
+
+出现下面这行说明状态文件写不进去（磁盘满或只读挂载），守卫会主动跳过本轮——宁可不重启，也不让保护失效后退化成每天硬重启：
+
+```
+xray-restart-guard[...]: 无法写入 /var/lib/xray/last-restart，跳过本轮重启以免退化成每日重启
+```
+
+> ⚠️ `list-timers` 的 `NEXT` 是 **timer 下次「唤醒」的时间，不是下次重启的时间**。timer 每天唤醒一次，NEXT 因此恒为次日的 `XRAY_RESTART_TIME`；是否真的重启由守卫按间隔判断。设了「每 7 天」且 5 天前刚重启过时，NEXT 显示明天凌晨，实际还要再等 2 天。想看真实的下次重启时间，用上面那条不带参数的 `bash deploy.sh --restart`。
+
 #### 为什么不是纯 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
-```
-
-> ⚠️ `list-timers` 的 `NEXT` 是 **timer 下次「唤醒」的时间**，不是下次重启的时间。timer 每天唤醒一次，NEXT 因此恒为次日的 `XRAY_RESTART_TIME`；是否真的重启由守卫按间隔判断。设了「每 7 天」且 5 天前刚重启过时，NEXT 显示明天凌晨，但实际还要再等 2 天。
->
-> 想直接看「下次实际重启时间」，跑一次不带参数的 `bash deploy.sh --restart`（不改任何配置、不重启服务），输出里会算好打印出来。
+具体怎么查看配置与执行记录，见上面的「查看当前配置与重启记录」。
 
 #### 已知取舍