# ours RP Docker 安装包使用说明（`__PACKAGE_ARCH__` / `__PACKAGE_PLATFORM__`）

## 目标

本安装包用于在目标架构与包元数据匹配的 Linux 服务器上，通过 Docker Compose 部署 ours RP，并持续运行 all5 RIR 同步验证任务。

安装包内置与包架构一致的 ours RP runtime、Prometheus、Grafana 镜像，部署时不需要现场拉取应用镜像。运行产物、状态数据库、日志、Prometheus 和 Grafana 数据均通过宿主机目录挂载保存。

默认情况下，宿主架构必须与 `PACKAGE-MANIFEST.env` 中的 `PACKAGE_ARCH` 匹配；若确需在异构主机上通过 QEMU/binfmt 运行，必须显式设置：

```bash
ALLOW_CROSS_ARCH=1
```

## 快速开始

```bash
tar -xzf ours-rp-docker-installer-__PACKAGE_ARCH__-*.tar.gz
cd ours-rp-docker-installer-__PACKAGE_ARCH__-*

./install.sh
cp .env.example .env   # 如 install.sh 已自动创建，可直接编辑现有 .env
vim .env
./start.sh
./status.sh
```

默认配置：

- `PACKAGE_ARCH=__PACKAGE_ARCH__`
- `PACKAGE_PLATFORM=__PACKAGE_PLATFORM__`
- `RIRS=afrinic,apnic,arin,lacnic,ripe`
- `MAX_RUNS=-1`
- `INTERVAL_SECS=600`
- `TAL_INPUT_MODE=file-live-ta`
- `LIVE_TA_REFRESH_BEFORE_SNAPSHOT=1`
- `PERIODIC_SNAPSHOT_RESET=0`
- `PERIODIC_SNAPSHOT_MAX_DELTAS=100`
- `HOST_DATA_DIR=__HOST_DATA_DIR__`
- `SOAK_RESTART_POLICY=unless-stopped`
- `MONITOR_PLATFORM=__PACKAGE_PLATFORM__`
- `ALLOW_CROSS_ARCH=0`

## 首次启动语义

如果 `HOST_DATA_DIR/runs` 下没有成功 run，`start.sh` 会先启动核心 `ours-rp-soak`，等待第一轮 snapshot 成功后再启动 metrics、Prometheus 和 Grafana。

第一轮 snapshot 会先拉取 live TA，避免 clean state 使用旧 fixture TA。

## 架构检查

关键脚本会读取：

- `.env` 中的 `PACKAGE_ARCH` / `PACKAGE_PLATFORM`
- `PACKAGE-MANIFEST.env`
- 当前宿主 `uname -m`

默认行为：

1. 宿主与包架构匹配：直接运行；
2. 宿主与包架构不匹配：明确报错并停止；
3. 仅当 `ALLOW_CROSS_ARCH=1` 时，脚本才会尝试启用对应架构的 `binfmt/qemu`。

因此在 `x86_64` 主机上运行 `arm64` 包，不会默认静默进入模拟执行。

## 访问端口

默认端口：

- metrics: `http://<host>:9556/metrics`
- Prometheus: `http://<host>:9090`
- Grafana: `http://<host>:3000`

Grafana 默认账号密码来自 `.env`：

```bash
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=admin
```

生产部署时应修改密码并限制外部访问。

## 数据目录

默认宿主机目录：

```text
__HOST_DATA_DIR__/
  state/
  runs/
  logs/
  tmp/
  prometheus/
  grafana/
```

`runs/run_XXXX/` 中包含每轮 `report.json`、`result.ccr`、`input.cir`、`vrps.csv`、`vaps.csv`、`stage-timing.json`、日志和元数据。

## 定期 snapshot reset

新增配置：

```bash
PERIODIC_SNAPSHOT_RESET=0
PERIODIC_SNAPSHOT_MAX_DELTAS=100
```

语义：

- 默认关闭，行为与旧版本一致；
- 开启后，一次成功 snapshot 后最多连续执行 `N` 个成功 delta；
- 达到阈值后，下一轮强制跑 snapshot；
- 强制 snapshot 前只重置 active `state/db`，保留 `runs/`、`logs/`、`state/rsync-mirror`、`.env`、Prometheus/Grafana 数据；
- 周期计数保存在独立 lifecycle 文件 `HOST_DATA_DIR/state/run-lifecycle-state.json`，不依赖 `runs/` 保留窗口；
- lifecycle 文件损坏时会先备份为 `run-lifecycle-state.json.corrupt.<timestamp>.<pid>`，再从当前保留 run 尽力 bootstrap；
- 强制 snapshot 成功后旧 DB staging 会被删除，避免磁盘只是换目录继续增长。

可通过最新 `run-meta.json` 中的以下字段确认：

- `sync_mode`
- `snapshot_reason`
- `periodic_snapshot_delta_count`
- `periodic_snapshot_forced`
- `reset_db_cleanup_status`

## 常用命令

```bash
./status.sh
./logs.sh ours-rp-soak --tail 200
./restart.sh
./stop.sh
./cleanup.sh --keep-runs 100 --execute
./uninstall.sh
```

如果做有限轮次验收，例如 `MAX_RUNS=3`，建议同时设置：

```bash
SOAK_RESTART_POLICY=no
```

否则 Compose 的 `unless-stopped` 策略会在容器正常退出后再次拉起下一轮。

`uninstall.sh` 默认不删除数据。只有显式执行：

```bash
./uninstall.sh --purge-data
```

才会删除 `HOST_DATA_DIR`。