197 lines
6.9 KiB
Markdown
197 lines
6.9 KiB
Markdown
# ours RP Docker 安装包使用说明（`__PACKAGE_ARCH__` / `__PACKAGE_PLATFORM__`）
|
||
|
||
## 目标
|
||
|
||
本安装包用于在目标架构与包元数据匹配的 Linux 服务器上，通过 Docker Compose 部署 ours RP，并持续运行 all5 RIR 同步验证任务。
|
||
|
||
安装包内置与包架构一致的四类镜像：ours RP runtime、artifact metrics、Prometheus、Grafana。部署时不需要现场拉取应用镜像。运行产物、状态数据库、日志、Prometheus 和 Grafana 数据均通过宿主机目录挂载保存。
|
||
|
||
每次构建安装包都会重新构建 ours RP runtime 与 artifact metrics 镜像。交付包命名为 `ours-rp-installer-{arch}-{git8}-{YYYYMMDDTHHMMSSZ}.tar.gz`，两类 ours RP 镜像分别使用当前源码 commit 的 tag。完整 commit、UTC 构建时间、dirty 状态和镜像归档 hash 保存在 `PACKAGE-MANIFEST.env`，可通过 `./scripts/status.sh --brief` 查看。
|
||
|
||
默认情况下，宿主架构必须与 `PACKAGE-MANIFEST.env` 中的 `PACKAGE_ARCH` 匹配；若确需在异构主机上通过 QEMU/binfmt 运行，必须显式设置：
|
||
|
||
```bash
|
||
ALLOW_CROSS_ARCH=1
|
||
```
|
||
|
||
## Compose 模板来源
|
||
|
||
`compose/` 是唯一的生产 Docker Compose 模板来源，Docker 安装包构建脚本会直接复制该目录。不要在其他目录维护第二份 compose、Prometheus 或 Grafana dashboard 文件。
|
||
|
||
旧的直接 Compose 部署入口已经移除。需要部署 amd64 或 arm64 时，统一先用 `scripts/docker/build_docker_installer_package.sh` 构建对应架构安装包，再按本说明执行 `scripts/install.sh`、`scripts/start.sh` 和 `scripts/status.sh`。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
tar -xzf ours-rp-installer-__PACKAGE_ARCH__-*.tar.gz
|
||
cd ours-rp-installer-__PACKAGE_ARCH__-*
|
||
|
||
./scripts/install.sh
|
||
cp .env.example .env # 如 install.sh 已自动创建，可直接编辑现有 .env
|
||
vim .env
|
||
./scripts/start.sh
|
||
./scripts/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`
|
||
- `RESOURCE_VALIDATION_MODE=validation-update-03`
|
||
- `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`
|
||
- `RPKI_IMAGE=__RUNTIME_IMAGE__`
|
||
- `METRICS_IMAGE=__METRICS_IMAGE__`
|
||
- `METRICS_PLATFORM=__PACKAGE_PLATFORM__`
|
||
- `MONITOR_PLATFORM=__PACKAGE_PLATFORM__`
|
||
- `ALLOW_CROSS_ARCH=0`
|
||
- `RTR_REPORT_DIR=__HOST_DATA_DIR__/empty-rtr-report`，默认挂载空目录；独立 RTR 服务部署完成后，使用 `scripts/register_rtr_monitor.sh` 注册同机 report 目录
|
||
|
||
## 首次启动语义
|
||
|
||
如果 `HOST_DATA_DIR/runs` 下没有成功 run，`start.sh` 会先启动核心 `ours-rp-soak`，等待第一轮 snapshot 成功后再启动 metrics、Prometheus 和 Grafana。
|
||
|
||
容器镜像分工：
|
||
|
||
- `ours-rp-soak` 使用 `RPKI_IMAGE`
|
||
- `artifact-metrics` 使用 `METRICS_IMAGE`
|
||
- `prometheus` / `grafana` 使用各自 monitor image
|
||
|
||
第一轮 snapshot 会先拉取 live TA，避免 clean state 使用旧 fixture TA。
|
||
|
||
## 资源验证模式
|
||
|
||
新增配置：
|
||
|
||
```bash
|
||
RESOURCE_VALIDATION_MODE=validation-update-03
|
||
```
|
||
|
||
可选值：
|
||
|
||
- `validation-update-03`：默认，按当前 validation update draft 语义运行；
|
||
- `rfc6487`：切换为 RFC 6487 原始资源包含判定语义。
|
||
|
||
installer / soak runner 每次启动 `rpki` 子进程时都会显式传入 `--resource-validation-mode`。
|
||
如果升级时复用旧 `.env` 且缺少该变量，新包 `.env.example` 中的默认值 `validation-update-03` 会保留在最终 `.env` 中；最终值为空时升级会在 Docker 操作前失败。
|
||
|
||
## 架构检查
|
||
|
||
关键脚本会读取：
|
||
|
||
- `.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
|
||
```
|
||
|
||
生产部署时应修改密码并限制外部访问。
|
||
|
||
## 可选 RTR report 监控接入
|
||
|
||
如果同一台机器上已经有独立部署的 RTR 服务，并且它持续输出 `rtr-source-*`、`rtr-runtime-*`、`rtr-clients-*` JSON report，执行：
|
||
|
||
```bash
|
||
./scripts/register_rtr_monitor.sh --report-dir /root/rpki/report
|
||
```
|
||
|
||
该命令只接受本机绝对路径，会先校验候选 Compose 挂载，再原子更新 `.env`。随后只重建 `artifact-metrics`、Prometheus 和 Grafana，不重启或重建 `ours-rp-soak`。`artifact-metrics` 以只读方式挂载该目录，并通过 `RPKI_METRICS_RTR_REPORT_DIR` 读取 report，输出 `ours_rp_rtr_*` 指标。默认 `RTR_REPORT_DIR` 指向安装包数据目录下的空 fallback 目录，因此未接入 RTR 服务时 metrics 容器也能稳定启动。
|
||
|
||
## 数据目录
|
||
|
||
默认宿主机目录：
|
||
|
||
```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
|
||
./scripts/status.sh
|
||
./scripts/logs.sh ours-rp-soak --tail 200
|
||
./scripts/restart.sh
|
||
./scripts/stop.sh
|
||
./scripts/cleanup.sh --keep-runs 100 --execute
|
||
./scripts/uninstall.sh
|
||
```
|
||
|
||
如果做有限轮次验收，例如 `MAX_RUNS=3`，建议同时设置：
|
||
|
||
```bash
|
||
SOAK_RESTART_POLICY=no
|
||
```
|
||
|
||
否则 Compose 的 `unless-stopped` 策略会在容器正常退出后再次拉起下一轮。
|
||
|
||
`uninstall.sh` 默认不删除数据。只有显式执行：
|
||
|
||
```bash
|
||
./scripts/uninstall.sh --purge-data
|
||
```
|
||
|
||
才会删除 `HOST_DATA_DIR`。
|