20260627 完成ARM64完整安装包和运维脚本

deploy/arm64-installer/docs/README.en.md

@@ -0,0 +1,94 @@
+# ours RP ARM64 Installer Guide
+
+## Goal
+
+This package deploys ours RP on a `linux/arm64` server with Docker Compose and continuously runs all five RIR validation.
+
+The package includes the ARM64 runtime image. Runtime state, run artifacts, logs, Prometheus data and Grafana data are persisted through host bind mounts.
+
+## Quick Start
+
+```bash
+tar -xzf ours-rp-arm64-installer-*.tar.gz
+cd ours-rp-arm64-installer-*
+
+./install.sh
+cp .env.example .env   # install.sh creates .env automatically if missing
+vim .env
+./start.sh
+./status.sh
+```
+
+Defaults:
+
+- `RIRS=afrinic,apnic,arin,lacnic,ripe`
+- `MAX_RUNS=-1`
+- `INTERVAL_SECS=600`
+- `TAL_INPUT_MODE=file-live-ta`
+- `LIVE_TA_REFRESH_BEFORE_SNAPSHOT=1`
+- `HOST_DATA_DIR=/var/lib/ours-rp-arm64`
+- `SOAK_RESTART_POLICY=unless-stopped`
+
+## First Start Semantics
+
+If there is no successful run under `HOST_DATA_DIR/runs`, `start.sh` starts the core `ours-rp-soak` service first and waits for the first snapshot to succeed before starting metrics, Prometheus and Grafana.
+
+The first snapshot refreshes live TA certificates before starting the RP process.
+
+## Ports
+
+Default ports:
+
+- metrics: `http://<host>:9556/metrics`
+- Prometheus: `http://<host>:9090`
+- Grafana: `http://<host>:3000`
+
+Grafana credentials come from `.env`:
+
+```bash
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=admin
+```
+
+Change the password and restrict public access for production deployments.
+
+## Data Directory
+
+Default host directory:
+
+```text
+/var/lib/ours-rp-arm64/
+  state/
+  runs/
+  logs/
+  tmp/
+  prometheus/
+  grafana/
+```
+
+Each `runs/run_XXXX/` directory contains `report.json`, `result.ccr`, `input.cir`, `vrps.csv`, `vaps.csv`, `stage-timing.json`, logs and metadata.
+
+## Common Commands
+
+```bash
+./status.sh
+./logs.sh ours-rp-soak --tail 200
+./restart.sh
+./stop.sh
+./cleanup.sh --keep-runs 100 --execute
+./uninstall.sh
+```
+
+`uninstall.sh` keeps data by default. Use the following only when you really want to delete `HOST_DATA_DIR`:
+
+```bash
+./uninstall.sh --purge-data
+```
+
+For finite acceptance tests, for example `MAX_RUNS=3`, also set:
+
+```bash
+SOAK_RESTART_POLICY=no
+```
+
+Otherwise Compose `unless-stopped` will restart the container after it exits successfully.

deploy/arm64-installer/docs/README.zh-CN.md

@@ -0,0 +1,96 @@
+# ours RP ARM64 安装包使用说明
+
+## 目标
+
+本安装包用于在 `linux/arm64` 服务器上通过 Docker Compose 部署 ours RP，并持续运行 all5 RIR 同步验证任务。
+
+安装包内置 ours RP ARM64 runtime 镜像，运行产物、状态数据库、日志、Prometheus 和 Grafana 数据均通过宿主机目录挂载保存。
+
+## 快速开始
+
+```bash
+tar -xzf ours-rp-arm64-installer-*.tar.gz
+cd ours-rp-arm64-installer-*
+
+./install.sh
+cp .env.example .env   # 如 install.sh 已自动创建，可直接编辑现有 .env
+vim .env
+./start.sh
+./status.sh
+```
+
+默认配置：
+
+- `RIRS=afrinic,apnic,arin,lacnic,ripe`
+- `MAX_RUNS=-1`
+- `INTERVAL_SECS=600`
+- `TAL_INPUT_MODE=file-live-ta`
+- `LIVE_TA_REFRESH_BEFORE_SNAPSHOT=1`
+- `HOST_DATA_DIR=/var/lib/ours-rp-arm64`
+- `SOAK_RESTART_POLICY=unless-stopped`
+
+## 首次启动语义
+
+如果 `HOST_DATA_DIR/runs` 下没有成功 run，`start.sh` 会先启动核心 `ours-rp-soak`，等待第一轮 snapshot 成功后再启动 metrics、Prometheus 和 Grafana。
+
+第一轮 snapshot 会先拉取 live TA，避免 clean state 使用旧 fixture TA。
+
+## 访问端口
+
+默认端口：
+
+- 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
+/var/lib/ours-rp-arm64/
+  state/
+  runs/
+  logs/
+  tmp/
+  prometheus/
+  grafana/
+```
+
+`runs/run_XXXX/` 中包含每轮 `report.json`、`result.ccr`、`input.cir`、`vrps.csv`、`vaps.csv`、`stage-timing.json`、日志和元数据。
+
+## 常用命令
+
+```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`。

deploy/arm64-installer/docs/operations.en.md

@@ -0,0 +1,68 @@
+# Operations Guide
+
+## Install
+
+```bash
+./install.sh
+```
+
+The installer is idempotent:
+
+- existing `.env` is kept;
+- existing Docker/Compose installation is reused;
+- repeated image loading is safe;
+- existing data directory is reused.
+
+## Start
+
+```bash
+./start.sh
+```
+
+Start without waiting for the first snapshot:
+
+```bash
+./start.sh --no-wait-first-run
+```
+
+## Stop and Restart
+
+```bash
+./stop.sh
+./restart.sh
+```
+
+## Status Checks
+
+```bash
+./status.sh
+./self-check.sh
+```
+
+Important checks:
+
+- Docker/Compose availability;
+- runtime image exists;
+- `HOST_DATA_DIR` is writable;
+- Compose config is valid;
+- latest run status;
+- metrics, Prometheus and Grafana endpoints.
+
+## Upgrade
+
+Extract the new package, reuse the existing `.env` and `HOST_DATA_DIR`, then run:
+
+```bash
+./upgrade.sh
+```
+
+Upgrade does not delete runtime data.
+
+## Cleanup
+
+```bash
+./cleanup.sh --keep-runs 100
+./cleanup.sh --keep-runs 100 --execute
+```
+
+Cleanup is dry-run by default. Add `--execute` after reviewing the output.

deploy/arm64-installer/docs/operations.zh-CN.md

@@ -0,0 +1,68 @@
+# 运维手册
+
+## 安装
+
+```bash
+./install.sh
+```
+
+安装脚本是幂等的：
+
+- 已有 `.env` 不覆盖；
+- 已安装 Docker/Compose 则跳过；
+- 镜像重复加载是安全的；
+- 数据目录已存在则复用。
+
+## 启动
+
+```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 镜像存在；
+- `HOST_DATA_DIR` 可写；
+- Compose 配置合法；
+- 最新 run 状态；
+- metrics、Prometheus、Grafana endpoint。
+
+## 升级
+
+把新安装包解压到新目录后，可以复用旧 `.env` 和 `HOST_DATA_DIR`。执行：
+
+```bash
+./upgrade.sh
+```
+
+升级不会删除运行数据。
+
+## 清理
+
+```bash
+./cleanup.sh --keep-runs 100
+./cleanup.sh --keep-runs 100 --execute
+```
+
+默认 dry-run，确认后加 `--execute`。

deploy/arm64-installer/docs/troubleshooting.en.md

@@ -0,0 +1,68 @@
+# Troubleshooting
+
+## Docker or Compose Is Unavailable
+
+Run:
+
+```bash
+docker version
+docker compose version
+```
+
+If missing, run:
+
+```bash
+./install.sh
+```
+
+## ARM64 Image Cannot Run
+
+Running ARM64 images on x86_64 requires binfmt/qemu:
+
+```bash
+docker run --rm --privileged tonistiigi/binfmt --install arm64
+docker run --rm --platform linux/arm64 debian:bookworm-slim uname -m
+```
+
+Expected output: `aarch64`.
+
+## First Snapshot Times Out
+
+All-five snapshot can be slow, especially under QEMU. Increase timeout:
+
+```bash
+./start.sh --timeout-secs 14400
+```
+
+## Output Counts Are Too Low
+
+Check:
+
+```bash
+grep LIVE_TA_REFRESH_BEFORE_SNAPSHOT .env
+ls -l /var/lib/ours-rp-arm64/state/live-ta
+tail -100 /var/lib/ours-rp-arm64/logs/live-ta-refresh-*.log
+```
+
+In `file-live-ta` mode, snapshot should wait until live TA refresh succeeds.
+
+## Grafana Login Fails
+
+Check `.env`:
+
+```bash
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=admin
+```
+
+If Grafana has already started, changing `.env` may not reset the existing Grafana database. Stop services and back up/clean `${HOST_DATA_DIR}/grafana` if needed.
+
+## A Finite Acceptance Test Starts an Extra Run
+
+If `.env` sets a finite `MAX_RUNS=3` while `SOAK_RESTART_POLICY=unless-stopped`, Docker Compose restarts the soak container after it exits successfully.
+
+For finite tests, set:
+
+```bash
+SOAK_RESTART_POLICY=no
+```

deploy/arm64-installer/docs/troubleshooting.zh-CN.md

@@ -0,0 +1,68 @@
+# 故障排查
+
+## Docker 或 Compose 不可用
+
+执行：
+
+```bash
+docker version
+docker compose version
+```
+
+如果缺失，重新执行：
+
+```bash
+./install.sh
+```
+
+## ARM64 镜像无法运行
+
+在 x86_64 机器上运行 ARM64 镜像需要 binfmt/qemu：
+
+```bash
+docker run --rm --privileged tonistiigi/binfmt --install arm64
+docker run --rm --platform linux/arm64 debian:bookworm-slim uname -m
+```
+
+预期输出 `aarch64`。
+
+## 首轮 snapshot 超时
+
+all5 snapshot 可能很慢，尤其在 QEMU 环境。可以提高超时：
+
+```bash
+./start.sh --timeout-secs 14400
+```
+
+## 产物数量异常偏低
+
+检查：
+
+```bash
+grep LIVE_TA_REFRESH_BEFORE_SNAPSHOT .env
+ls -l /var/lib/ours-rp-arm64/state/live-ta
+tail -100 /var/lib/ours-rp-arm64/logs/live-ta-refresh-*.log
+```
+
+`file-live-ta` 模式下，snapshot 应等待 live TA 成功刷新。
+
+## Grafana 无法登录
+
+确认 `.env` 中：
+
+```bash
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=admin
+```
+
+如果曾经启动过 Grafana，修改 `.env` 不一定重置已有 Grafana 数据库账号。可以停止服务后按需备份并清理 `${HOST_DATA_DIR}/grafana`。
+
+## 有限轮次验收后又多跑了一轮
+
+如果 `.env` 中设置了 `MAX_RUNS=3` 这类有限轮次，同时 `SOAK_RESTART_POLICY=unless-stopped`，Docker Compose 会在 soak 容器正常退出后重新启动容器。
+
+有限验收建议设置：
+
+```bash
+SOAK_RESTART_POLICY=no
+```