# 运维手册

## 安装

```bash
./install.sh
```

安装脚本是幂等的：

- 已有 `.env` 不覆盖；
- 已安装 Docker/Compose 则跳过；
- 包内 ours RP、Prometheus、Grafana ARM64 镜像重复加载是安全的；
- 数据目录已存在则复用。

## 启动

```bash
./start.sh
```

如需后台启动后不等待首轮 snapshot：

```bash
./start.sh --no-wait-first-run
```

## 停止和重启

```bash
./stop.sh
./restart.sh
```

## 状态检查

```bash
./status.sh
./self-check.sh
```

重点检查项：

- Docker/Compose 可用；
- runtime、Prometheus、Grafana 镜像存在；
- `HOST_DATA_DIR` 可写；
- Compose 配置合法；
- 最新 run 状态；
- metrics、Prometheus、Grafana endpoint。

`status.sh` 还会显示：

- `periodic_snapshot_reset`
- `periodic_snapshot_max_deltas`

## 升级

把新安装包解压到新目录后，推荐通过升级脚本显式复用旧 `.env`：

```bash
./upgrade.sh --reuse-env-from /path/to/old-installer/.env
```

如果新目录已经存在 `.env`，升级脚本会保留它，不覆盖。

升级不会删除以下数据：

- `runs/`
- `logs/`
- `state/rsync-mirror`
- `.env` 对应的运行配置
- Prometheus / Grafana 数据

验证定期 forced snapshot 时，可临时设置：

```bash
PERIODIC_SNAPSHOT_RESET=1
PERIODIC_SNAPSHOT_MAX_DELTAS=2
```

然后检查最新 `run-meta.json` 应出现：

```bash
snapshot_reason=periodic_snapshot_delta_limit
```

验证完成后恢复：

```bash
PERIODIC_SNAPSHOT_MAX_DELTAS=100
```

## 清理

```bash
./cleanup.sh --keep-runs 100
./cleanup.sh --keep-runs 100 --execute
```

默认 dry-run，确认后加 `--execute`。