1187 lines
42 KiB
Markdown
1187 lines
42 KiB
Markdown
# Xray 定时重启计划 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 让 `vps-xray/deploy.sh` 支持「每 N 天在固定时间点重启 Xray」，并提供一个不触碰 vless 链接的轻量命令行入口 `--restart`。
|
||
|
||
**Architecture:** systemd timer 每天到点唤醒一个 oneshot service，service 调用守卫脚本 `xray-restart-guard`；守卫读取状态文件里的上次重启时间戳，满 N 天才真正执行 `systemctl restart xray`。这样绕开了 `OnCalendar` 无法表达任意 N 天间隔（`*-*-1/7` 会跨月重置）的限制。timer / service / guard 三个文件的生成逻辑收敛在一个函数里，完整部署与 `--restart` 共用。
|
||
|
||
**Tech Stack:** Bash 4+、systemd、Debian/Ubuntu。无测试框架——本计划新增一个自包含的 bash 断言脚本 `vps-xray/tests/test-restart-schedule.sh`，可在 Windows 的 Git Bash 或 Linux 上直接跑，不需要 root、不接触真实 systemd。
|
||
|
||
## Global Constraints
|
||
|
||
- 规格文档：`docs/superpowers/specs/2026-08-06-xray-restart-schedule-design.md`，本计划的所有行为以它为准
|
||
- 默认关闭：首次部署 `XRAY_RESTART_EVERY_DAYS=0`，与当前行为一致
|
||
- 旧字段 `XRAY_DAILY_RESTART` 仅在新字段**完全未设置**时才回退读取：`true|yes|on|1`（大小写不敏感）→ `1`，其它 → `0`
|
||
- 时间接受 `4:00` 与 `04:00`，落盘前一律归一化为两位小时 `HH:MM`
|
||
- 参数不合法一律报错退出，**不得静默回退默认值**
|
||
- 守卫脚本必须**先写时间戳再重启**
|
||
- 守卫脚本间隔判断使用 **300 秒容差**：`(now - last) < DAYS*86400 - 300` 才跳过
|
||
- 状态文件 `/var/lib/xray/last-restart`；关闭定时重启时**保留**该文件
|
||
- `--restart` 路径禁止：装依赖、升级 Xray、生成密钥、选伪装目标、重写 `config.json`、改防火墙与 sysctl、重启 xray
|
||
- 所有可写路径通过可覆盖变量暴露，便于测试：`SYSTEMD_DIR`、`GUARD_BIN`、`RESTART_STATE_FILE`
|
||
- 提交信息用中文，与仓库现有风格一致
|
||
- **每个中间提交都必须是可部署的。** 本工作直接在 `master` 上进行，而 `master` 随时可能被 `upload.sh` 推到生产服务器。`deploy.sh` 开头是 `set -euo pipefail`，删除某个变量的赋值处而下游仍在引用，会让部署在中途崩溃（Task 1 已踩过一次）。拆任务时若某处的清理要延后，必须留过渡兼容代码，并在做清理的那个任务里显式删除。
|
||
- `set -u` 推论：**任何返回非 0 的函数都必须在条件位置调用**（`if f; then` / `f || x` / `f && x`），裸调用会让整个脚本退出
|
||
|
||
## File Structure
|
||
|
||
| 文件 | 职责 |
|
||
|---|---|
|
||
| `vps-xray/deploy.sh` | 配置解析与迁移、单元文件生成、`--restart` 入口。改动集中在三处：顶部参数与配置解析、新增的一组 `*_restart_*` 函数、`main()` 早退分支 |
|
||
| `vps-xray/tests/test-restart-schedule.sh` | 新建。抽取 `deploy.sh` 的函数定义做断言，覆盖归一化、迁移、校验、`.env` 改写、单元文件渲染、守卫脚本行为 |
|
||
| `vps-xray/.env.example` | 三个新字段与说明 |
|
||
| `vps-xray/uninstall.sh` | 补充清理 guard 脚本与状态文件 |
|
||
| `vps-xray/README.md` | 定时重启一节 |
|
||
|
||
---
|
||
|
||
### Task 1: 时间归一化与配置解析
|
||
|
||
**Files:**
|
||
- Create: `vps-xray/tests/test-restart-schedule.sh`
|
||
- Modify: `vps-xray/deploy.sh`（替换第 78~82 行附近的 `XRAY_DAILY_RESTART` case 块）
|
||
|
||
**Interfaces:**
|
||
- Produces: `normalize_restart_time <str>` → stdout 输出 `HH:MM`，不合法返回 1
|
||
- Produces: `resolve_restart_config` → 读环境变量 `XRAY_RESTART_EVERY_DAYS` / `XRAY_RESTART_TIME` / `XRAY_RESTART_TIMEZONE` / `XRAY_DAILY_RESTART`，设置全局 `RESTART_EVERY_DAYS`（整数）、`RESTART_TIME`（`HH:MM`）、`RESTART_TZ`（字符串）；任一不合法则 `error` 后返回 1
|
||
|
||
- [ ] **Step 1: 写测试脚手架与失败测试**
|
||
|
||
创建 `vps-xray/tests/test-restart-schedule.sh`：
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
# deploy.sh 中重启计划相关逻辑的单元测试
|
||
#
|
||
# 用法: bash vps-xray/tests/test-restart-schedule.sh
|
||
#
|
||
# 不需要 root，不接触真实 systemd：所有写入路径都被重定向到临时目录，
|
||
# systemctl 用 PATH 打桩拦截。
|
||
#
|
||
# 加载方式说明：deploy.sh 结尾会直接调用 main，且顶层有 root 检查与参数解析，
|
||
# 不能整份 source。这里只抽取「多行函数定义」（形如 `name() {` 开头、`}` 结尾）。
|
||
# 单行函数（log/warn/error/step）抽不到，正好由下面的桩覆盖。
|
||
|
||
set -u
|
||
|
||
TEST_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||
DEPLOY="${TEST_DIR}/../deploy.sh"
|
||
|
||
if [ ! -f "$DEPLOY" ]; then
|
||
echo "找不到 $DEPLOY" >&2
|
||
exit 1
|
||
fi
|
||
|
||
eval "$(sed -n '/^[a-z_][a-z_]*() {$/,/^}$/p' "$DEPLOY")"
|
||
|
||
# 日志桩：error 保留输出便于断言，其余静音
|
||
log() { :; }
|
||
warn() { :; }
|
||
step() { :; }
|
||
error() { echo "ERROR: $*" >&2; }
|
||
|
||
PASS=0
|
||
FAIL=0
|
||
ok() { PASS=$((PASS + 1)); echo " ok - $1"; }
|
||
bad() { FAIL=$((FAIL + 1)); echo " FAIL - $1"; echo " 期望: $2"; echo " 实际: $3"; }
|
||
# is <描述> <实际值> <期望值>
|
||
is() { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1" "$3" "$2"; fi; }
|
||
|
||
echo "== normalize_restart_time =="
|
||
is "04:00 原样通过" "$(normalize_restart_time 04:00)" "04:00"
|
||
is "4:00 补零" "$(normalize_restart_time 4:00)" "04:00"
|
||
is "08:30 不被当八进制" "$(normalize_restart_time 08:30)" "08:30"
|
||
is "23:59 边界" "$(normalize_restart_time 23:59)" "23:59"
|
||
is "00:00 边界" "$(normalize_restart_time 00:00)" "00:00"
|
||
|
||
normalize_restart_time "24:00" >/dev/null 2>&1
|
||
is "24:00 被拒" "$?" "1"
|
||
normalize_restart_time "04:60" >/dev/null 2>&1
|
||
is "04:60 被拒" "$?" "1"
|
||
normalize_restart_time "abc" >/dev/null 2>&1
|
||
is "abc 被拒" "$?" "1"
|
||
normalize_restart_time "" >/dev/null 2>&1
|
||
is "空串被拒" "$?" "1"
|
||
|
||
echo "== resolve_restart_config =="
|
||
|
||
reset_env() {
|
||
unset XRAY_RESTART_EVERY_DAYS XRAY_RESTART_TIME XRAY_RESTART_TIMEZONE XRAY_DAILY_RESTART
|
||
RESTART_EVERY_DAYS=""; RESTART_TIME=""; RESTART_TZ=""
|
||
}
|
||
|
||
reset_env
|
||
resolve_restart_config
|
||
is "全空时天数默认 0" "$RESTART_EVERY_DAYS" "0"
|
||
is "全空时时间默认" "$RESTART_TIME" "04:00"
|
||
is "全空时时区默认" "$RESTART_TZ" "Asia/Shanghai"
|
||
|
||
reset_env; XRAY_RESTART_EVERY_DAYS=7; XRAY_RESTART_TIME=5:30
|
||
resolve_restart_config
|
||
is "读取新字段天数" "$RESTART_EVERY_DAYS" "7"
|
||
is "读取新字段时间并补零" "$RESTART_TIME" "05:30"
|
||
|
||
reset_env; XRAY_DAILY_RESTART=true
|
||
resolve_restart_config
|
||
is "迁移 true → 1" "$RESTART_EVERY_DAYS" "1"
|
||
|
||
reset_env; XRAY_DAILY_RESTART=TRUE
|
||
resolve_restart_config
|
||
is "迁移 TRUE → 1" "$RESTART_EVERY_DAYS" "1"
|
||
|
||
reset_env; XRAY_DAILY_RESTART=false
|
||
resolve_restart_config
|
||
is "迁移 false → 0" "$RESTART_EVERY_DAYS" "0"
|
||
|
||
reset_env; XRAY_DAILY_RESTART=true; XRAY_RESTART_EVERY_DAYS=3
|
||
resolve_restart_config
|
||
is "新字段优先于旧字段" "$RESTART_EVERY_DAYS" "3"
|
||
|
||
reset_env; XRAY_DAILY_RESTART=true; XRAY_RESTART_EVERY_DAYS=0
|
||
resolve_restart_config
|
||
is "新字段显式 0 覆盖旧 true" "$RESTART_EVERY_DAYS" "0"
|
||
|
||
reset_env; XRAY_RESTART_EVERY_DAYS=abc
|
||
resolve_restart_config 2>/dev/null
|
||
is "天数非数字报错" "$?" "1"
|
||
|
||
reset_env; XRAY_RESTART_EVERY_DAYS=-1
|
||
resolve_restart_config 2>/dev/null
|
||
is "天数负数报错" "$?" "1"
|
||
|
||
reset_env; XRAY_RESTART_TIME=25:00
|
||
resolve_restart_config 2>/dev/null
|
||
is "时间非法报错" "$?" "1"
|
||
|
||
reset_env; XRAY_RESTART_TIMEZONE=""
|
||
resolve_restart_config 2>/dev/null
|
||
is "时区空串报错" "$?" "1"
|
||
|
||
echo ""
|
||
echo "通过 ${PASS}，失败 ${FAIL}"
|
||
[ "$FAIL" -eq 0 ]
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试确认失败**
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: 大量 `FAIL`，并伴随 `normalize_restart_time: command not found` —— 因为函数尚未存在。
|
||
|
||
- [ ] **Step 3: 实现两个函数**
|
||
|
||
在 `vps-xray/deploy.sh` 中，把现有的这段：
|
||
|
||
```bash
|
||
# 布尔开关归一化：容忍 true/TRUE/True/yes/on/1 等写法，
|
||
# 避免用户按直觉写了 TRUE 却被静默当成关闭
|
||
case "$(printf '%s' "${XRAY_DAILY_RESTART:-false}" | tr '[:upper:]' '[:lower:]')" in
|
||
true|yes|on|1) DAILY_RESTART=1 ;;
|
||
*) DAILY_RESTART=0 ;;
|
||
esac
|
||
```
|
||
|
||
整段替换为：
|
||
|
||
```bash
|
||
# ===== 定时重启配置 =====
|
||
# 可覆盖路径，测试时指向临时目录
|
||
SYSTEMD_DIR="${SYSTEMD_DIR:-/etc/systemd/system}"
|
||
GUARD_BIN="${GUARD_BIN:-/usr/local/bin/xray-restart-guard}"
|
||
RESTART_STATE_FILE="${RESTART_STATE_FILE:-/var/lib/xray/last-restart}"
|
||
|
||
RESTART_EVERY_DAYS=0
|
||
RESTART_TIME="04:00"
|
||
RESTART_TZ="Asia/Shanghai"
|
||
|
||
# 把 4:00 / 04:00 统一成两位小时的 HH:MM，不合法返回 1。
|
||
# 归一化的意义：OnCalendar 字符串格式统一，.env 内容可预测。
|
||
normalize_restart_time() {
|
||
local t="${1:-}"
|
||
[[ "$t" =~ ^([01]?[0-9]|2[0-3]):([0-5][0-9])$ ]] || return 1
|
||
# 10# 前缀避免 08/09 被当成八进制
|
||
printf '%02d:%s' "$((10#${BASH_REMATCH[1]}))" "${BASH_REMATCH[2]}"
|
||
}
|
||
|
||
resolve_restart_config() {
|
||
local days="${XRAY_RESTART_EVERY_DAYS:-}"
|
||
|
||
# 旧字段迁移：仅当新字段完全未设置时才回退去读，
|
||
# 这样 .env 里显式写 0 能覆盖遗留的 XRAY_DAILY_RESTART=true
|
||
if [ -z "$days" ]; then
|
||
case "$(printf '%s' "${XRAY_DAILY_RESTART:-false}" | tr '[:upper:]' '[:lower:]')" in
|
||
true|yes|on|1) days=1 ;;
|
||
*) days=0 ;;
|
||
esac
|
||
fi
|
||
|
||
if ! [[ "$days" =~ ^[0-9]+$ ]]; then
|
||
error "XRAY_RESTART_EVERY_DAYS 必须是非负整数，当前为 '${days}'"
|
||
return 1
|
||
fi
|
||
RESTART_EVERY_DAYS="$days"
|
||
|
||
local t
|
||
if ! t=$(normalize_restart_time "${XRAY_RESTART_TIME:-04:00}"); then
|
||
error "XRAY_RESTART_TIME 必须是 HH:MM（00:00~23:59），当前为 '${XRAY_RESTART_TIME:-}'"
|
||
return 1
|
||
fi
|
||
RESTART_TIME="$t"
|
||
|
||
RESTART_TZ="${XRAY_RESTART_TIMEZONE-Asia/Shanghai}"
|
||
if [ -z "$RESTART_TZ" ]; then
|
||
error "XRAY_RESTART_TIMEZONE 不能为空"
|
||
return 1
|
||
fi
|
||
|
||
return 0
|
||
}
|
||
|
||
resolve_restart_config || exit 1
|
||
|
||
# 过渡兼容：harden_system / start_service / save_env 仍引用 DAILY_RESTART，
|
||
# 要到 Task 5 才清理。在那之前必须保证 master 上的脚本能完整跑完——
|
||
# deploy.sh 开头是 set -euo pipefail，缺这个变量会在部署中途崩溃。
|
||
DAILY_RESTART=$([ "$RESTART_EVERY_DAYS" -ne 0 ] && echo 1 || echo 0)
|
||
```
|
||
|
||
注意 `${XRAY_RESTART_TIMEZONE-Asia/Shanghai}` 用的是 `-` 而非 `:-`——显式设成空串时要报错，不能被默认值悄悄补上。
|
||
|
||
**为什么需要那行过渡兼容赋值：** 被替换掉的 case 块是 `DAILY_RESTART` 的唯一赋值处，而下游三处引用要到 Task 5 才删。`set -u` 下变量缺失会让 `harden_system` 直接 `unbound variable` 退出——那时 Xray 已装好、config.json 已写入，但服务不会启动、`.env` 不会更新。每个中间提交都必须是可部署的。
|
||
|
||
- [ ] **Step 4: 运行测试确认通过**
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: `通过 23，失败 0`（normalize 9 项 + resolve 14 项）
|
||
|
||
Run: `bash -n vps-xray/deploy.sh`
|
||
Expected: 无输出
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add vps-xray/deploy.sh vps-xray/tests/test-restart-schedule.sh
|
||
git commit -m "feat(vps-xray): 重启计划配置解析与旧字段迁移
|
||
|
||
新增 normalize_restart_time / resolve_restart_config，
|
||
XRAY_RESTART_EVERY_DAYS 缺失时才回退读 XRAY_DAILY_RESTART。
|
||
附单元测试，不需要 root 与 systemd。"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: `.env` 字段就地更新
|
||
|
||
**Files:**
|
||
- Modify: `vps-xray/deploy.sh`（在 `resolve_restart_config` 之后新增函数）
|
||
- Modify: `vps-xray/tests/test-restart-schedule.sh`
|
||
|
||
**Interfaces:**
|
||
- Consumes: 无
|
||
- Produces: `update_env_field <file> <key> <value>` → 文件中存在 `^key=` 则替换该行，否则追加一行；文件不存在返回 1
|
||
|
||
- [ ] **Step 1: 追加失败测试**
|
||
|
||
在 `vps-xray/tests/test-restart-schedule.sh` 的 `echo ""` 汇总行**之前**插入：
|
||
|
||
```bash
|
||
echo "== update_env_field =="
|
||
|
||
TMP="$(mktemp -d)"
|
||
trap 'rm -rf "$TMP"' EXIT
|
||
|
||
cat > "${TMP}/.env" << 'ENVEOF'
|
||
# 这是用户自己加的注释
|
||
XRAY_PORT=443
|
||
XRAY_RESTART_EVERY_DAYS=0
|
||
# 尾部注释
|
||
ENVEOF
|
||
|
||
update_env_field "${TMP}/.env" XRAY_RESTART_EVERY_DAYS 7
|
||
is "替换已有字段" "$(grep '^XRAY_RESTART_EVERY_DAYS=' "${TMP}/.env")" "XRAY_RESTART_EVERY_DAYS=7"
|
||
is "保留用户注释" "$(grep -c '这是用户自己加的注释' "${TMP}/.env")" "1"
|
||
is "保留尾部注释" "$(grep -c '尾部注释' "${TMP}/.env")" "1"
|
||
is "不影响其它字段" "$(grep '^XRAY_PORT=' "${TMP}/.env")" "XRAY_PORT=443"
|
||
|
||
update_env_field "${TMP}/.env" XRAY_RESTART_TIME 05:30
|
||
is "追加缺失字段" "$(grep '^XRAY_RESTART_TIME=' "${TMP}/.env")" "XRAY_RESTART_TIME=05:30"
|
||
|
||
update_env_field "${TMP}/.env" XRAY_RESTART_TIMEZONE Asia/Shanghai
|
||
is "含斜杠的值不被 sed 分隔符干扰" \
|
||
"$(grep '^XRAY_RESTART_TIMEZONE=' "${TMP}/.env")" "XRAY_RESTART_TIMEZONE=Asia/Shanghai"
|
||
|
||
update_env_field "${TMP}/.env" XRAY_RESTART_TIMEZONE Europe/Berlin
|
||
is "含斜杠的值可被再次替换" \
|
||
"$(grep '^XRAY_RESTART_TIMEZONE=' "${TMP}/.env")" "XRAY_RESTART_TIMEZONE=Europe/Berlin"
|
||
|
||
is "字段总行数正确" "$(grep -c '^XRAY_RESTART_TIMEZONE=' "${TMP}/.env")" "1"
|
||
|
||
update_env_field "${TMP}/nonexistent" FOO bar 2>/dev/null
|
||
is "文件不存在返回 1" "$?" "1"
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试确认失败**
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: `update_env_field: command not found`，新增断言全部 FAIL
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
在 `vps-xray/deploy.sh` 中 `resolve_restart_config` 函数定义之后、`resolve_restart_config || exit 1` 调用之前，插入：
|
||
|
||
```bash
|
||
# 就地更新 .env 中的单个字段：存在则替换，不存在则追加。
|
||
# 刻意不复用 save_env——后者是 cat > 全量重写，会抹掉用户自己加的注释与字段；
|
||
# 轻量入口只该改自己那一行。
|
||
update_env_field() {
|
||
local file="$1" key="$2" value="$3" esc
|
||
[ -f "$file" ] || return 1
|
||
|
||
if grep -q "^${key}=" "$file"; then
|
||
# 用 | 作分隔符，并转义 value 中的 | & \，避免值里的 / 破坏 sed
|
||
esc=$(printf '%s' "$value" | sed 's/[|&\\]/\\&/g')
|
||
sed -i "s|^${key}=.*|${key}=${esc}|" "$file"
|
||
else
|
||
printf '%s=%s\n' "$key" "$value" >> "$file"
|
||
fi
|
||
return 0
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 运行测试确认通过**
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: `通过 34，失败 0`（新增 9 项 + 复审补的 2 项缺尾换行断言）
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add vps-xray/deploy.sh vps-xray/tests/test-restart-schedule.sh
|
||
git commit -m "feat(vps-xray): 新增 update_env_field 就地更新 .env 单个字段"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: 渲染 timer / service / guard 三个文件
|
||
|
||
**Files:**
|
||
- Modify: `vps-xray/deploy.sh`
|
||
- Modify: `vps-xray/tests/test-restart-schedule.sh`
|
||
|
||
**Interfaces:**
|
||
- Consumes: 全局 `SYSTEMD_DIR`、`GUARD_BIN`、`RESTART_STATE_FILE`
|
||
- Produces: `render_restart_units <days> <time> <tz>` → 写出 `${SYSTEMD_DIR}/xray-restart.timer`、`${SYSTEMD_DIR}/xray-restart.service`、`${GUARD_BIN}`（可执行）
|
||
- Produces: `remove_restart_units` → 删除上述三个文件并 disable timer；原本存在返回 0，本就不存在返回 1
|
||
|
||
- [ ] **Step 1: 追加失败测试**
|
||
|
||
在汇总行之前插入：
|
||
|
||
```bash
|
||
echo "== render_restart_units =="
|
||
|
||
SYSTEMD_DIR="${TMP}/systemd"
|
||
GUARD_BIN="${TMP}/bin/xray-restart-guard"
|
||
RESTART_STATE_FILE="${TMP}/state/last-restart"
|
||
mkdir -p "${TMP}/systemd" "${TMP}/bin" "${TMP}/state"
|
||
|
||
# systemctl 打桩：记录被调用的参数，避免碰真实 systemd
|
||
STUB="${TMP}/stub"
|
||
mkdir -p "$STUB"
|
||
cat > "${STUB}/systemctl" << 'STUBEOF'
|
||
#!/bin/sh
|
||
echo "systemctl $*" >> "${SYSTEMCTL_LOG}"
|
||
STUBEOF
|
||
chmod 755 "${STUB}/systemctl"
|
||
export SYSTEMCTL_LOG="${TMP}/systemctl.log"
|
||
: > "$SYSTEMCTL_LOG"
|
||
export PATH="${STUB}:${PATH}"
|
||
|
||
render_restart_units 7 04:00 Asia/Shanghai
|
||
|
||
is "timer 文件存在" "$([ -f "${SYSTEMD_DIR}/xray-restart.timer" ] && echo yes)" "yes"
|
||
is "service 文件存在" "$([ -f "${SYSTEMD_DIR}/xray-restart.service" ] && echo yes)" "yes"
|
||
is "guard 可执行" "$([ -x "$GUARD_BIN" ] && echo yes)" "yes"
|
||
|
||
is "OnCalendar 每天触发" \
|
||
"$(grep -c '^OnCalendar=\*-\*-\* 04:00:00$' "${SYSTEMD_DIR}/xray-restart.timer")" "1"
|
||
is "TimeZone 写入" \
|
||
"$(grep -c '^TimeZone=Asia/Shanghai$' "${SYSTEMD_DIR}/xray-restart.timer")" "1"
|
||
is "Persistent 开启" \
|
||
"$(grep -c '^Persistent=true$' "${SYSTEMD_DIR}/xray-restart.timer")" "1"
|
||
is "service 指向 guard" \
|
||
"$(grep -c "^ExecStart=${GUARD_BIN}\$" "${SYSTEMD_DIR}/xray-restart.service")" "1"
|
||
is "guard 里天数正确" \
|
||
"$(grep -c '^DAYS=7$' "$GUARD_BIN")" "1"
|
||
is "guard 里状态文件路径正确" \
|
||
"$(grep -c "^STATE=\"${RESTART_STATE_FILE}\"\$" "$GUARD_BIN")" "1"
|
||
is "guard 用 PATH 查找 systemctl 而非绝对路径" \
|
||
"$(grep -c '^exec systemctl restart xray$' "$GUARD_BIN")" "1"
|
||
|
||
render_restart_units 3 23:05 Europe/Berlin
|
||
is "重复渲染覆盖天数" "$(grep -c '^DAYS=3$' "$GUARD_BIN")" "1"
|
||
is "重复渲染覆盖时间" \
|
||
"$(grep -c '^OnCalendar=\*-\*-\* 23:05:00$' "${SYSTEMD_DIR}/xray-restart.timer")" "1"
|
||
|
||
remove_restart_units
|
||
is "remove 后 timer 消失" "$([ -f "${SYSTEMD_DIR}/xray-restart.timer" ] && echo yes || echo no)" "no"
|
||
is "remove 后 service 消失" "$([ -f "${SYSTEMD_DIR}/xray-restart.service" ] && echo yes || echo no)" "no"
|
||
is "remove 后 guard 消失" "$([ -f "$GUARD_BIN" ] && echo yes || echo no)" "no"
|
||
|
||
remove_restart_units
|
||
is "重复 remove 返回 1" "$?" "1"
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试确认失败**
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: `render_restart_units: command not found`，新增断言 FAIL
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
在 `vps-xray/deploy.sh` 中 `update_env_field` 之后插入：
|
||
|
||
```bash
|
||
# 生成 timer / service / guard 三个文件。
|
||
# 完整部署与 --restart 共用本函数，避免两条路径各写一份实现后漂移。
|
||
render_restart_units() {
|
||
local days="$1" time="$2" tz="$3"
|
||
|
||
mkdir -p "$SYSTEMD_DIR" "$(dirname "$GUARD_BIN")"
|
||
|
||
# 守卫脚本：systemd 的 OnCalendar 表达不了「每 N 天」——
|
||
# *-*-1/7 是「每月 1/8/15/22/29 号」，跨月会重置成 2~3 天。
|
||
# 所以 timer 只负责每天到点唤醒，间隔判断放到这里。
|
||
cat > "$GUARD_BIN" << EOF
|
||
#!/bin/bash
|
||
# 由 deploy.sh 生成，请勿手工编辑
|
||
STATE="${RESTART_STATE_FILE}"
|
||
DAYS=${days}
|
||
|
||
now=\$(date +%s)
|
||
last=0
|
||
if [ -f "\$STATE" ]; then
|
||
last=\$(cat "\$STATE" 2>/dev/null || echo 0)
|
||
# 内容被写坏时按 0 处理，即允许立即重启
|
||
[[ "\$last" =~ ^[0-9]+\$ ]] || last=0
|
||
fi
|
||
|
||
# 300 秒容差：systemd timer 默认 AccuracySec=1min，第 N 次触发的实际间隔
|
||
# 可能是 N*86400-30s。严格比较会判「不满」从而顺延整整一天，且误差会累积。
|
||
if [ "\$last" -gt 0 ] && [ \$(( now - last )) -lt \$(( DAYS * 86400 - 300 )) ]; then
|
||
echo "距上次重启不足 \${DAYS} 天（已过 \$(( (now - last) / 86400 )) 天），跳过"
|
||
exit 0
|
||
fi
|
||
|
||
mkdir -p "\$(dirname "\$STATE")"
|
||
# 必须先写时间戳：restart 会中断本脚本所在的 systemd 事务，
|
||
# 顺序反了会丢记录，退化成每天都重启。
|
||
# 代价是重启失败时本轮仍被记为已执行——这比陷入每日重启循环可接受。
|
||
echo "\$now" > "\$STATE"
|
||
echo "距上次重启已满 \${DAYS} 天，执行重启"
|
||
exec systemctl restart xray
|
||
EOF
|
||
chmod 755 "$GUARD_BIN"
|
||
|
||
cat > "${SYSTEMD_DIR}/xray-restart.service" << EOF
|
||
[Unit]
|
||
Description=Scheduled restart of Xray (every ${days} day(s))
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=oneshot
|
||
Environment=PATH=/usr/sbin:/usr/bin:/sbin:/bin
|
||
ExecStart=${GUARD_BIN}
|
||
EOF
|
||
|
||
cat > "${SYSTEMD_DIR}/xray-restart.timer" << EOF
|
||
[Unit]
|
||
Description=Wake xray-restart daily at ${time} ${tz}; the guard enforces the ${days}-day interval
|
||
|
||
[Timer]
|
||
OnCalendar=*-*-* ${time}:00
|
||
TimeZone=${tz}
|
||
Persistent=true
|
||
|
||
[Install]
|
||
WantedBy=timers.target
|
||
EOF
|
||
}
|
||
|
||
# 删除 timer / service / guard。状态文件刻意保留：
|
||
# 以后重新启用时，距上次已超 N 天则首次触发即重启，符合直觉。
|
||
remove_restart_units() {
|
||
if [ ! -f "${SYSTEMD_DIR}/xray-restart.timer" ] && [ ! -f "$GUARD_BIN" ]; then
|
||
return 1
|
||
fi
|
||
systemctl disable --now xray-restart.timer >/dev/null 2>&1 || true
|
||
rm -f "${SYSTEMD_DIR}/xray-restart.timer" \
|
||
"${SYSTEMD_DIR}/xray-restart.service" \
|
||
"$GUARD_BIN"
|
||
return 0
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 运行测试确认通过**
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: `通过 50，失败 0`（34 基线 + 新增 16）
|
||
|
||
Run: `bash -n vps-xray/deploy.sh`
|
||
Expected: 无输出
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add vps-xray/deploy.sh vps-xray/tests/test-restart-schedule.sh
|
||
git commit -m "feat(vps-xray): 生成 timer/service/guard 三个单元文件
|
||
|
||
timer 每天唤醒，N 天间隔判断交给 guard 脚本，
|
||
绕开 OnCalendar 无法表达任意 N 天间隔的限制。"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: 守卫脚本行为
|
||
|
||
**Files:**
|
||
- Modify: `vps-xray/tests/test-restart-schedule.sh`
|
||
|
||
**Interfaces:**
|
||
- Consumes: Task 3 的 `render_restart_units`
|
||
|
||
本任务只加测试——被测对象是 Task 3 已生成的 guard 脚本。若测试暴露缺陷，回到 Task 3 的实现修改。
|
||
|
||
- [ ] **Step 1: 追加行为测试**
|
||
|
||
在汇总行之前插入：
|
||
|
||
```bash
|
||
echo "== guard 脚本行为 =="
|
||
|
||
render_restart_units 7 04:00 Asia/Shanghai
|
||
rm -f "$RESTART_STATE_FILE"
|
||
: > "$SYSTEMCTL_LOG"
|
||
|
||
# 无状态文件 → 首次必须执行
|
||
out=$("$GUARD_BIN" 2>&1)
|
||
is "首次执行重启" "$(grep -c 'systemctl restart xray' "$SYSTEMCTL_LOG")" "1"
|
||
is "首次写入时间戳" "$([ -f "$RESTART_STATE_FILE" ] && echo yes)" "yes"
|
||
|
||
# 刚重启过 → 必须跳过
|
||
: > "$SYSTEMCTL_LOG"
|
||
out=$("$GUARD_BIN" 2>&1)
|
||
is "刚重启过则跳过" "$(grep -c 'systemctl restart xray' "$SYSTEMCTL_LOG")" "0"
|
||
is "跳过时有提示" "$(echo "$out" | grep -c '跳过')" "1"
|
||
|
||
# 距上次 6 天 → 仍未满 7 天，跳过
|
||
echo "$(( $(date +%s) - 6 * 86400 ))" > "$RESTART_STATE_FILE"
|
||
: > "$SYSTEMCTL_LOG"
|
||
"$GUARD_BIN" > /dev/null 2>&1
|
||
is "6 天不足 7 天则跳过" "$(grep -c 'systemctl restart xray' "$SYSTEMCTL_LOG")" "0"
|
||
|
||
# 距上次 7 天差 100 秒 → 300 秒容差内，必须执行
|
||
echo "$(( $(date +%s) - 7 * 86400 + 100 ))" > "$RESTART_STATE_FILE"
|
||
: > "$SYSTEMCTL_LOG"
|
||
"$GUARD_BIN" > /dev/null 2>&1
|
||
is "容差内视为已满 7 天" "$(grep -c 'systemctl restart xray' "$SYSTEMCTL_LOG")" "1"
|
||
|
||
# 距上次 7 天差 600 秒 → 超出容差，跳过
|
||
echo "$(( $(date +%s) - 7 * 86400 + 600 ))" > "$RESTART_STATE_FILE"
|
||
: > "$SYSTEMCTL_LOG"
|
||
"$GUARD_BIN" > /dev/null 2>&1
|
||
is "超出容差仍判不足" "$(grep -c 'systemctl restart xray' "$SYSTEMCTL_LOG")" "0"
|
||
|
||
# 状态文件内容被写坏 → 按 0 处理，立即执行
|
||
echo "garbage" > "$RESTART_STATE_FILE"
|
||
: > "$SYSTEMCTL_LOG"
|
||
"$GUARD_BIN" > /dev/null 2>&1
|
||
is "状态文件非法时立即执行" "$(grep -c 'systemctl restart xray' "$SYSTEMCTL_LOG")" "1"
|
||
is "非法内容被覆盖为数字" \
|
||
"$(grep -cE '^[0-9]+$' "$RESTART_STATE_FILE")" "1"
|
||
|
||
# 每日模式：距上次 1 天即执行
|
||
render_restart_units 1 04:00 Asia/Shanghai
|
||
echo "$(( $(date +%s) - 86400 ))" > "$RESTART_STATE_FILE"
|
||
: > "$SYSTEMCTL_LOG"
|
||
"$GUARD_BIN" > /dev/null 2>&1
|
||
is "N=1 时满一天即执行" "$(grep -c 'systemctl restart xray' "$SYSTEMCTL_LOG")" "1"
|
||
|
||
# 时间戳先于重启写入：用一个必定失败的 systemctl 桩验证
|
||
cat > "${STUB}/systemctl" << 'STUBEOF'
|
||
#!/bin/sh
|
||
echo "systemctl $*" >> "${SYSTEMCTL_LOG}"
|
||
exit 1
|
||
STUBEOF
|
||
chmod 755 "${STUB}/systemctl"
|
||
rm -f "$RESTART_STATE_FILE"
|
||
: > "$SYSTEMCTL_LOG"
|
||
"$GUARD_BIN" > /dev/null 2>&1
|
||
is "重启失败时时间戳仍已写入" "$([ -s "$RESTART_STATE_FILE" ] && echo yes)" "yes"
|
||
|
||
# 恢复正常桩，避免影响后续
|
||
cat > "${STUB}/systemctl" << 'STUBEOF'
|
||
#!/bin/sh
|
||
echo "systemctl $*" >> "${SYSTEMCTL_LOG}"
|
||
STUBEOF
|
||
chmod 755 "${STUB}/systemctl"
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试**
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: `通过 61，失败 0`（50 基线 + 新增 11）。若有 FAIL，说明 Task 3 生成的 guard 逻辑有缺陷——回到 Task 3 的 `render_restart_units` 修改后重跑。
|
||
|
||
- [ ] **Step 3: 提交**
|
||
|
||
```bash
|
||
git add vps-xray/tests/test-restart-schedule.sh
|
||
git commit -m "test(vps-xray): 覆盖 guard 脚本的间隔判断、容差与状态文件容错"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: 接线进完整部署流程
|
||
|
||
**Files:**
|
||
- Modify: `vps-xray/deploy.sh`（`harden_system`、`start_service`、`save_env`）
|
||
|
||
**Interfaces:**
|
||
- Consumes: `resolve_restart_config`、`render_restart_units`、`remove_restart_units`
|
||
- Produces: `configure_restart_timer` → 依据全局 `RESTART_EVERY_DAYS` / `RESTART_TIME` / `RESTART_TZ` 建立或移除定时重启，并完成 `daemon-reload` 与 enable/disable
|
||
|
||
- [ ] **Step 1: 新增 configure_restart_timer**
|
||
|
||
在 `vps-xray/deploy.sh` 中 `remove_restart_units` 之后插入：
|
||
|
||
```bash
|
||
configure_restart_timer() {
|
||
if [ "$RESTART_EVERY_DAYS" -eq 0 ]; then
|
||
if remove_restart_units; then
|
||
warn "已移除定时重启（XRAY_RESTART_EVERY_DAYS=0）"
|
||
fi
|
||
systemctl daemon-reload
|
||
log "定时重启: 关闭（崩溃恢复已由 Restart=always 秒级覆盖）"
|
||
return
|
||
fi
|
||
|
||
render_restart_units "$RESTART_EVERY_DAYS" "$RESTART_TIME" "$RESTART_TZ"
|
||
systemctl daemon-reload
|
||
systemctl enable --now xray-restart.timer >/dev/null 2>&1
|
||
log "定时重启: 每 ${RESTART_EVERY_DAYS} 天 ${RESTART_TIME} (${RESTART_TZ})"
|
||
warn "重启会切断所有活动连接；崩溃恢复本已由 Restart=always 覆盖，按需启用"
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 替换 harden_system 里的旧逻辑**
|
||
|
||
在 `harden_system()` 中，把从 `# ===== 每日重启 timer：默认关闭 =====` 注释开始、到函数结尾 `warn "该操作会切断所有活动连接，如无必要建议设 XRAY_DAILY_RESTART=false"` 为止的**全部内容**（含 `if [ "$DAILY_RESTART" -ne 1 ]` 分支、两处 `cat > /etc/systemd/system/xray-restart.*` 生成块）删除，替换为单行：
|
||
|
||
```bash
|
||
configure_restart_timer
|
||
```
|
||
|
||
保留其上方的文件描述符上限与 `xray.service.d/override.conf` 生成逻辑，不要动。
|
||
|
||
- [ ] **Step 3: 清理 start_service 中的重复 enable**
|
||
|
||
在 `start_service()` 中删除这三行——timer 的 enable 已由 `configure_restart_timer` 负责，且 `harden_system` 在 `start_service` 之前执行：
|
||
|
||
```bash
|
||
if [ "$DAILY_RESTART" -eq 1 ]; then
|
||
systemctl enable --now xray-restart.timer
|
||
fi
|
||
```
|
||
|
||
- [ ] **Step 4: 更新 save_env**
|
||
|
||
在 `save_env()` 中，把这一段：
|
||
|
||
```bash
|
||
# 每日 04:00 自动重启 Xray。默认 false。
|
||
# 崩溃恢复已由 systemd 的 Restart=always 覆盖（秒级），而每日硬重启会
|
||
# 切断全部活动连接。仅在确实观察到长期运行后性能退化时才改为 true。
|
||
XRAY_DAILY_RESTART=$([ "$DAILY_RESTART" -eq 1 ] && echo true || echo false)
|
||
```
|
||
|
||
替换为：
|
||
|
||
```bash
|
||
# 定时重启。0 = 关闭（默认）；N = 每 N 天在 XRAY_RESTART_TIME 重启一次。
|
||
# 崩溃恢复已由 systemd 的 Restart=always 覆盖（秒级），而硬重启会切断
|
||
# 全部活动连接。仅在确实观察到长期运行后性能退化时才启用。
|
||
# 改这两项无需完整重新部署: bash deploy.sh --restart 7 04:00
|
||
XRAY_RESTART_EVERY_DAYS=${RESTART_EVERY_DAYS}
|
||
XRAY_RESTART_TIME=${RESTART_TIME}
|
||
XRAY_RESTART_TIMEZONE=${RESTART_TZ}
|
||
```
|
||
|
||
- [ ] **Step 5: 删除 Task 1 留下的过渡兼容赋值**
|
||
|
||
下游三处引用已在 Step 2~4 全部清理，Task 1 加的这行兼容赋值到此完成使命，删掉：
|
||
|
||
```bash
|
||
# 过渡兼容：harden_system / start_service / save_env 仍引用 DAILY_RESTART，
|
||
# 要到 Task 5 才清理。在那之前必须保证 master 上的脚本能完整跑完——
|
||
# deploy.sh 开头是 set -euo pipefail，缺这个变量会在部署中途崩溃。
|
||
DAILY_RESTART=$([ "$RESTART_EVERY_DAYS" -ne 0 ] && echo 1 || echo 0)
|
||
```
|
||
|
||
留着它就是僵尸代码——没有任何读取方，却会让下一个读代码的人以为还有别处在用。
|
||
|
||
- [ ] **Step 6: 确认没有遗留引用**
|
||
|
||
Run: `grep -n "DAILY_RESTART" vps-xray/deploy.sh`
|
||
Expected: 只剩 `resolve_restart_config` 里那处向后兼容的 `${XRAY_DAILY_RESTART:-false}`，共 1 行。
|
||
|
||
Run: `bash -n vps-xray/deploy.sh`
|
||
Expected: 无输出
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: `通过 61，失败 0`
|
||
|
||
- [ ] **Step 7: 提交**
|
||
|
||
```bash
|
||
git add vps-xray/deploy.sh
|
||
git commit -m "refactor(vps-xray): 完整部署改用 configure_restart_timer
|
||
|
||
harden_system 与 start_service 里的旧 DAILY_RESTART 分支删除，
|
||
save_env 改写三个新字段。"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: `--restart` 轻量入口
|
||
|
||
**Files:**
|
||
- Modify: `vps-xray/deploy.sh`（`usage`、参数解析、`main`，新增 `apply_restart_only`）
|
||
|
||
**Interfaces:**
|
||
- Consumes: `resolve_restart_config`、`update_env_field`、`configure_restart_timer`
|
||
- Produces: 全局 `RESTART_ONLY`、`RESTART_ARG_DAYS`、`RESTART_ARG_TIME`；函数 `apply_restart_only`
|
||
|
||
- [ ] **Step 1: 更新 usage**
|
||
|
||
在 `usage()` 中 `--redetect` 那两行之后、`-h, --help` 之前插入：
|
||
|
||
```bash
|
||
echo " --restart [N] [HH:MM]"
|
||
echo " 只修改定时重启计划并立即生效。N=0 关闭。"
|
||
echo " 不重装 Xray、不重写配置、不重启服务，"
|
||
echo " 现有 vless 链接完全不受影响。"
|
||
echo " 例: bash deploy.sh --restart 7 04:00"
|
||
```
|
||
|
||
- [ ] **Step 2: 扩展参数解析**
|
||
|
||
在参数解析区，把：
|
||
|
||
```bash
|
||
MODE=""
|
||
MODE_EXPLICIT=0
|
||
SHOW_ONLY=0
|
||
REDETECT=0
|
||
```
|
||
|
||
改为：
|
||
|
||
```bash
|
||
MODE=""
|
||
MODE_EXPLICIT=0
|
||
SHOW_ONLY=0
|
||
REDETECT=0
|
||
RESTART_ONLY=0
|
||
RESTART_ARG_DAYS=""
|
||
RESTART_ARG_TIME=""
|
||
```
|
||
|
||
在 `while` 循环的 `case` 中，`--redetect) REDETECT=1; shift ;;` 之后插入：
|
||
|
||
```bash
|
||
--restart)
|
||
RESTART_ONLY=1
|
||
shift
|
||
# 后面可跟 0~2 个位置参数，按形态判断，不会误吞后续选项
|
||
if [[ "${1:-}" =~ ^[0-9]+$ ]]; then
|
||
RESTART_ARG_DAYS="$1"
|
||
shift
|
||
if [[ "${1:-}" =~ ^([01]?[0-9]|2[0-3]):[0-5][0-9]$ ]]; then
|
||
RESTART_ARG_TIME="$1"
|
||
shift
|
||
fi
|
||
fi
|
||
;;
|
||
```
|
||
|
||
在 `while` 循环结束后、root 检查之前插入互斥校验：
|
||
|
||
```bash
|
||
# --restart 是「只改重启计划」的轻量入口，与会改动服务的选项互斥，
|
||
# 避免用户以为只调了 timer、实际却顺带重装了 Xray
|
||
if [ "$RESTART_ONLY" -eq 1 ] \
|
||
&& { [ "$MODE_EXPLICIT" -eq 1 ] || [ "$SHOW_ONLY" -eq 1 ] || [ "$REDETECT" -eq 1 ]; }; then
|
||
error "--restart 不能与 --mode / --show / --redetect 同时使用"
|
||
exit 1
|
||
fi
|
||
```
|
||
|
||
- [ ] **Step 3: 实现 apply_restart_only**
|
||
|
||
在 `configure_restart_timer` 之后插入：
|
||
|
||
```bash
|
||
# ===== --restart：只改重启计划 =====
|
||
# 明确不做：装依赖、升级 Xray、生成密钥、选伪装目标、重写 config.json、
|
||
# 改防火墙与 sysctl、重启 xray。因此 vless 链接与现有连接均不受影响。
|
||
apply_restart_only() {
|
||
local env_file="$SCRIPT_DIR/.env"
|
||
|
||
if [ ! -f "$env_file" ]; then
|
||
error "未找到 ${env_file}，无法确认这是一台已部署的机器"
|
||
error "请先执行完整部署: bash deploy.sh"
|
||
exit 1
|
||
fi
|
||
if ! systemctl cat xray >/dev/null 2>&1; then
|
||
error "未找到 xray.service，请先执行完整部署: bash deploy.sh"
|
||
exit 1
|
||
fi
|
||
|
||
# 命令行给了值就覆盖 .env 载入的值，没给则沿用
|
||
if [ -n "$RESTART_ARG_DAYS" ]; then
|
||
XRAY_RESTART_EVERY_DAYS="$RESTART_ARG_DAYS"
|
||
fi
|
||
if [ -n "$RESTART_ARG_TIME" ]; then
|
||
XRAY_RESTART_TIME="$RESTART_ARG_TIME"
|
||
fi
|
||
resolve_restart_config || exit 1
|
||
|
||
# 只把命令行显式给过的字段落盘，没给的不动 .env
|
||
if [ -n "$RESTART_ARG_DAYS" ]; then
|
||
update_env_field "$env_file" XRAY_RESTART_EVERY_DAYS "$RESTART_EVERY_DAYS"
|
||
fi
|
||
if [ -n "$RESTART_ARG_TIME" ]; then
|
||
update_env_field "$env_file" XRAY_RESTART_TIME "$RESTART_TIME"
|
||
fi
|
||
|
||
configure_restart_timer
|
||
|
||
echo ""
|
||
echo "=========================================================="
|
||
if [ "$RESTART_EVERY_DAYS" -eq 0 ]; then
|
||
echo " 定时重启: 已关闭"
|
||
else
|
||
echo " 定时重启: 每 ${RESTART_EVERY_DAYS} 天 ${RESTART_TIME} (${RESTART_TZ})"
|
||
fi
|
||
echo " xray 服务未重启，vless 链接与现有连接均未受影响。"
|
||
echo "=========================================================="
|
||
if [ "$RESTART_EVERY_DAYS" -ne 0 ]; then
|
||
echo ""
|
||
systemctl list-timers xray-restart.timer --no-pager 2>/dev/null || true
|
||
fi
|
||
}
|
||
```
|
||
|
||
注意 `resolve_restart_config` 在脚本顶层已经跑过一次，这里再跑一次是为了让命令行传入的值参与校验与归一化。
|
||
|
||
- [ ] **Step 4: 在 main 中早退**
|
||
|
||
在 `main()` 里，紧跟现有的 `--show` 分支之后插入：
|
||
|
||
```bash
|
||
if [ "$RESTART_ONLY" -eq 1 ]; then
|
||
apply_restart_only
|
||
exit 0
|
||
fi
|
||
```
|
||
|
||
- [ ] **Step 5: 修正非法参数的退出码**
|
||
|
||
现状：`usage()` 结尾是 `exit 0`，而参数解析的兜底分支是 `*) error "未知参数: $1"; usage ;;`——非法参数会以**退出码 0** 结束。`--restart 7 25:00` 中的 `25:00` 不匹配时间形态、不被 `--restart` 消费，正会落进这个分支，于是「时间写错」表现为「成功退出」。这违反本计划的全局约束。
|
||
|
||
把 `usage()` 的结尾：
|
||
|
||
```bash
|
||
exit 0
|
||
}
|
||
```
|
||
|
||
改为：
|
||
|
||
```bash
|
||
exit "${1:-0}"
|
||
}
|
||
```
|
||
|
||
并把参数解析的兜底分支：
|
||
|
||
```bash
|
||
*) error "未知参数: $1"; usage ;;
|
||
```
|
||
|
||
改为：
|
||
|
||
```bash
|
||
*) error "未知参数: $1"; usage 1 ;;
|
||
```
|
||
|
||
`-h|--help) usage ;;` 保持不变，仍以 0 退出。
|
||
|
||
- [ ] **Step 6: 本地校验**
|
||
|
||
Run: `bash -n vps-xray/deploy.sh`
|
||
Expected: 无输出
|
||
|
||
Run: `bash vps-xray/deploy.sh --badarg > /dev/null 2>&1; echo $?`
|
||
Expected: `1`
|
||
|
||
Run: `bash vps-xray/deploy.sh --help > /dev/null 2>&1; echo $?`
|
||
Expected: `0`
|
||
|
||
Run: `bash vps-xray/tests/test-restart-schedule.sh`
|
||
Expected: `通过 61，失败 0`
|
||
|
||
Run: `bash vps-xray/deploy.sh --help`
|
||
Expected: 帮助里出现 `--restart [N] [HH:MM]` 说明，退出码 0
|
||
|
||
- [ ] **Step 7: 提交**
|
||
|
||
```bash
|
||
git add vps-xray/deploy.sh
|
||
git commit -m "feat(vps-xray): 新增 --restart 轻量入口
|
||
|
||
只改定时重启计划并立即生效，不重装 Xray、不重写配置、不重启服务，
|
||
与 --mode/--show/--redetect 互斥。
|
||
顺带修正非法参数以退出码 0 结束的问题。"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 7: 文档与卸载清理
|
||
|
||
**Files:**
|
||
- Modify: `vps-xray/.env.example`
|
||
- Modify: `vps-xray/uninstall.sh`
|
||
- Modify: `vps-xray/README.md`
|
||
|
||
- [ ] **Step 1: 更新 .env.example**
|
||
|
||
把现有这段：
|
||
|
||
```bash
|
||
# 每日 04:00 自动重启 Xray。默认 false。
|
||
# 崩溃恢复已由 systemd 的 Restart=always 覆盖（秒级），而每日硬重启会
|
||
# 切断全部活动连接。仅在确实观察到长期运行后性能退化时才改为 true。
|
||
# XRAY_DAILY_RESTART=false
|
||
```
|
||
|
||
替换为：
|
||
|
||
```bash
|
||
# ===== 定时重启 =====
|
||
# 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 天，其它 → 关闭。重跑部署后会自动换写成新字段。
|
||
```
|
||
|
||
- [ ] **Step 2: 更新 uninstall.sh**
|
||
|
||
把现有这段：
|
||
|
||
```bash
|
||
if [ -f /etc/systemd/system/xray-restart.timer ]; 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
|
||
```
|
||
|
||
替换为：
|
||
|
||
```bash
|
||
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 \
|
||
/usr/local/bin/xray-restart-guard \
|
||
/var/lib/xray/last-restart
|
||
```
|
||
|
||
卸载与「关闭定时重启」不同，卸载要连状态文件一起清掉。
|
||
|
||
- [ ] **Step 3: 更新 README**
|
||
|
||
在 `README.md` 的「查看状态 / 日志」一节之前插入：
|
||
|
||
```markdown
|
||
### 定时重启
|
||
|
||
默认**关闭**。崩溃恢复已由 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` 会自动换写成新字段。
|
||
```
|
||
|
||
- [ ] **Step 4: 校验**
|
||
|
||
Run: `bash -n vps-xray/uninstall.sh`
|
||
Expected: 无输出
|
||
|
||
Run: `grep -c "XRAY_DAILY_RESTART" vps-xray/README.md`
|
||
Expected: `1`（只剩兼容说明那处）
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add vps-xray/.env.example vps-xray/uninstall.sh vps-xray/README.md
|
||
git commit -m "docs(vps-xray): 定时重启配置说明；uninstall 清理 guard 与状态文件"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 8: VPS 端到端验证
|
||
|
||
**Files:** 无改动。本任务在真实服务器上执行 spec 的验证方案。
|
||
|
||
**前置：** 目标机器已用旧版脚本部署过，`.env` 存在。先记下当前 vless 链接以便比对。
|
||
|
||
- [ ] **Step 1: 上传**
|
||
|
||
```bash
|
||
bash vps-xray/upload.sh <VPS_IP>
|
||
```
|
||
|
||
- [ ] **Step 2: 启用并确认服务未被重启**
|
||
|
||
在 VPS 上：
|
||
|
||
```bash
|
||
cd /opt/vps-xray
|
||
systemctl show xray -p ActiveEnterTimestamp # 记下改动前的值
|
||
bash deploy.sh --restart 7 04:00
|
||
systemctl show xray -p ActiveEnterTimestamp # 必须与上面完全相同
|
||
grep -E '^XRAY_RESTART_' .env
|
||
systemctl list-timers xray-restart.timer --no-pager
|
||
```
|
||
|
||
Expected：`ActiveEnterTimestamp` 前后一致（证明没重启 xray）；`.env` 含 `XRAY_RESTART_EVERY_DAYS=7` 与 `XRAY_RESTART_TIME=04:00`；`list-timers` 显示 `NEXT` 为次日 04:00。
|
||
|
||
- [ ] **Step 3: 守卫行为**
|
||
|
||
```bash
|
||
rm -f /var/lib/xray/last-restart
|
||
/usr/local/bin/xray-restart-guard # 应输出「执行重启」
|
||
/usr/local/bin/xray-restart-guard # 应输出「跳过」
|
||
cat /var/lib/xray/last-restart
|
||
```
|
||
|
||
Expected：第一次重启并写入时间戳，第二次跳过。
|
||
|
||
- [ ] **Step 4: 关闭**
|
||
|
||
```bash
|
||
bash deploy.sh --restart 0
|
||
ls -l /etc/systemd/system/xray-restart.* /usr/local/bin/xray-restart-guard 2>&1
|
||
ls -l /var/lib/xray/last-restart
|
||
```
|
||
|
||
Expected：三个单元/脚本文件均报 `No such file`；状态文件仍在。
|
||
|
||
- [ ] **Step 5: 参数校验与互斥**
|
||
|
||
```bash
|
||
bash deploy.sh --restart 7 25:00 ; echo "exit=$?"
|
||
bash deploy.sh --restart abc ; echo "exit=$?"
|
||
bash deploy.sh --restart 7 --redetect ; echo "exit=$?"
|
||
bash deploy.sh --restart 4:00 ; echo "exit=$?"
|
||
ls /etc/systemd/system/xray-restart.timer 2>&1
|
||
```
|
||
|
||
逐条预期（形态解析的既定行为，都不是缺陷）：
|
||
|
||
| 命令 | 行为 | 退出码 |
|
||
|---|---|---|
|
||
| `--restart 7 25:00` | `25:00` 不匹配时间形态、不被消费，落到兜底分支报「未知参数: 25:00」并打印帮助 | `1` |
|
||
| `--restart abc` | 同上，报「未知参数: abc」 | `1` |
|
||
| `--restart 7 --redetect` | `--redetect` 不被消费，正常置位，循环后互斥校验拦下，报「--restart 不能与 --mode / --show / --redetect 同时使用」 | `1` |
|
||
| `--restart 4:00` | `4:00` 不匹配数字形态，不作 N 用；落到兜底分支报「未知参数: 4:00」。**时间必须跟在天数之后**，这是位置参数的固有约束，帮助文本已写明 `--restart [N] [HH:MM]` | `1` |
|
||
|
||
最后 `ls` 应报 `No such file`——四条命令都不该留下任何 timer 文件。
|
||
|
||
- [ ] **Step 6: 旧字段迁移**
|
||
|
||
```bash
|
||
cp .env /tmp/env.bak
|
||
sed -i '/^XRAY_RESTART_/d' .env
|
||
echo 'XRAY_DAILY_RESTART=true' >> .env
|
||
bash deploy.sh
|
||
grep -E '^XRAY_RESTART_|^XRAY_DAILY' .env
|
||
systemctl list-timers xray-restart.timer --no-pager
|
||
```
|
||
|
||
Expected：`.env` 中出现 `XRAY_RESTART_EVERY_DAYS=1`，不再有 `XRAY_DAILY_RESTART`；timer 已建立。
|
||
|
||
- [ ] **Step 7: 恢复并确认链接未变**
|
||
|
||
```bash
|
||
cp /tmp/env.bak .env
|
||
bash deploy.sh --restart 0
|
||
bash deploy.sh --show
|
||
```
|
||
|
||
Expected：`--show` 输出的 vless 链接与 Step 1 之前记录的完全一致。
|
||
|
||
- [ ] **Step 8: 记录结果并提交**
|
||
|
||
把实测输出补进 `docs/superpowers/plans/2026-08-06-xray-restart-schedule.md` 末尾的「验证记录」小节，然后：
|
||
|
||
```bash
|
||
git add docs/superpowers/plans/2026-08-06-xray-restart-schedule.md
|
||
git commit -m "docs: 补充定时重启功能的 VPS 端到端验证记录"
|
||
```
|
||
|
||
---
|
||
|
||
## 验证记录
|
||
|
||
（Task 8 执行后填写实测输出）
|