NASP/rpki
84
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

20260707 通用化Docker安装包模板命名

Browse Source
This commit is contained in:
yuyr
2026-07-07 11:10:21 +08:00
parent c00d9390dc
commit b0f76738e5
34 changed files with 37 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
deploy/docker-installer/docs/README.en.md Normal file
View File

@@ -0,0 +1,187 @@
# ours RP Docker Installer Guide (`__PACKAGE_ARCH__` / `__PACKAGE_PLATFORM__`)
## Goal
This package deploys ours RP on Linux servers whose host architecture matches the packaged installer metadata, using Docker Compose and continuous all-five RIR validation.
The package includes four architecture-matched images: ours RP runtime, artifact metrics, Prometheus, and Grafana. Deployment does not need to pull application images on the target host. Runtime state, run artifacts, logs, Prometheus data and Grafana data are persisted through host bind mounts.
By default the host architecture must match `PACKAGE_ARCH` from `PACKAGE-MANIFEST.env`. If you intentionally want to run this package on a different host architecture through QEMU/binfmt, set:
```bash
ALLOW_CROSS_ARCH=1
```
## Quick Start
```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 creates .env automatically if missing
vim .env
./start.sh
./status.sh
```
Defaults:
- `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=ours-rp-runtime-__PACKAGE_ARCH__:dev`
- `METRICS_IMAGE=ours-rp-metrics-__PACKAGE_ARCH__:dev`
- `METRICS_PLATFORM=__PACKAGE_PLATFORM__`
- `MONITOR_PLATFORM=__PACKAGE_PLATFORM__`
- `ALLOW_CROSS_ARCH=0`
- `RTR_REPORT_DIR=__HOST_DATA_DIR__/empty-rtr-report`, which mounts an empty fallback directory by default; set it to a real host directory such as `/root/rpki/report` to ingest reports from a separately deployed RTR service
## 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.
Container/image mapping:
- `ours-rp-soak` uses `RPKI_IMAGE`
- `artifact-metrics` uses `METRICS_IMAGE`
- `prometheus` / `grafana` use their monitor images
The first snapshot refreshes live TA certificates before starting the RP process.
## Resource Validation Mode
New knob:
```bash
RESOURCE_VALIDATION_MODE=validation-update-03
```
Supported values:
- `validation-update-03`: default behavior, using the current validation-update draft semantics;
- `rfc6487`: switch back to the original RFC 6487 resource containment behavior.
The installer / soak runner passes `--resource-validation-mode` to every `rpki` child start.
When an upgraded deployment reuses an older `.env` that does not contain this key, the installer appends the new default `validation-update-03` automatically.
## Architecture Guardrails
The key scripts read:
- `PACKAGE_ARCH` / `PACKAGE_PLATFORM` from `.env`
- `PACKAGE-MANIFEST.env`
- the current host `uname -m`
Default behavior:
1. matching host and package architectures: run natively;
2. mismatched host and package architectures: fail with an explicit error;
3. only when `ALLOW_CROSS_ARCH=1` is set do the scripts attempt to enable matching `binfmt/qemu`.
That means an `arm64` package on an `x86_64` host does not silently switch to emulation by default.
## 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.
## Optional RTR report metrics input
If a separately deployed RTR service on the same host continuously writes `rtr-source-*`, `rtr-runtime-*`, and `rtr-clients-*` JSON reports, configure:
```bash
RTR_REPORT_DIR=/root/rpki/report
RTR_REPORT_CONTAINER_DIR=/var/lib/ours-rp/rtr-report
```
The `artifact-metrics` container mounts the host directory read-only and reads it through `RPKI_METRICS_RTR_REPORT_DIR`, producing `ours_rp_rtr_*` metrics. By default, `RTR_REPORT_DIR` points at an empty fallback directory under the installer data root, so the metrics container also starts cleanly without an RTR service.
## Data Directory
Default host directory:
```text
__HOST_DATA_DIR__/
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.
## Periodic Snapshot Reset
New knobs:
```bash
PERIODIC_SNAPSHOT_RESET=0
PERIODIC_SNAPSHOT_MAX_DELTAS=100
```
Semantics:
- disabled by default, keeping previous behavior unchanged;
- when enabled, one successful snapshot is followed by at most `N` successful delta runs;
- after the threshold is reached, the next run is forced to snapshot;
- before that forced snapshot, only the active `state/db` is reset, while `runs/`, `logs/`, `state/rsync-mirror`, `.env`, and Prometheus/Grafana data are preserved;
- the counter is persisted independently in `HOST_DATA_DIR/state/run-lifecycle-state.json`, so it does not depend on retained `runs/` history;
- if that lifecycle file is corrupt, it is backed up as `run-lifecycle-state.json.corrupt.<timestamp>.<pid>` before best-effort bootstrap from retained runs;
- after a successful forced snapshot, the old DB staging is deleted so disk usage does not keep growing elsewhere.
Check the latest `run-meta.json` for:
- `sync_mode`
- `snapshot_reason`
- `periodic_snapshot_delta_count`
- `periodic_snapshot_forced`
- `reset_db_cleanup_status`
## Common Commands
```bash
./status.sh
./logs.sh ours-rp-soak --tail 200
./restart.sh
./stop.sh
./cleanup.sh --keep-runs 100 --execute
./uninstall.sh
```
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.
`uninstall.sh` keeps data by default. Use the following only when you really want to delete `HOST_DATA_DIR`:
```bash
./uninstall.sh --purge-data
```

189
deploy/docker-installer/docs/README.zh-CN.md Normal file
View File

@@ -0,0 +1,189 @@
# ours RP Docker 安装包使用说明（`__PACKAGE_ARCH__` / `__PACKAGE_PLATFORM__`）
## 目标
本安装包用于在目标架构与包元数据匹配的 Linux 服务器上，通过 Docker Compose 部署 ours RP，并持续运行 all5 RIR 同步验证任务。
安装包内置与包架构一致的四类镜像：ours RP runtime、artifact metrics、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`
- `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=ours-rp-runtime-__PACKAGE_ARCH__:dev`
- `METRICS_IMAGE=ours-rp-metrics-__PACKAGE_ARCH__:dev`
- `METRICS_PLATFORM=__PACKAGE_PLATFORM__`
- `MONITOR_PLATFORM=__PACKAGE_PLATFORM__`
- `ALLOW_CROSS_ARCH=0`
- `RTR_REPORT_DIR=__HOST_DATA_DIR__/empty-rtr-report`，默认挂载空目录；如需接入独立 RTR 服务 report，可设置为宿主机真实目录，例如 `/root/rpki/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` 且缺少该变量，installer 会自动补入默认值 `validation-update-03`，不会破坏旧 `.env` 复用流程。
## 架构检查
关键脚本会读取：
- `.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，可在 `.env` 中配置：
```bash
RTR_REPORT_DIR=/root/rpki/report
RTR_REPORT_CONTAINER_DIR=/var/lib/ours-rp/rtr-report
```
`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
./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`。

132
deploy/docker-installer/docs/operations.en.md Normal file
View File

@@ -0,0 +1,132 @@
# Operations Guide (`__PACKAGE_ARCH__`)
## Install
```bash
./install.sh
```
The installer is idempotent:
- existing `.env` is kept;
- existing Docker/Compose installation is reused;
- repeated loading of packaged runtime, metrics, Prometheus and Grafana images for the package architecture is safe;
- existing data directory is reused;
- matching host/package architecture is required by default.
## Start
```bash
./start.sh
```
Start without waiting for the first snapshot:
```bash
./start.sh --no-wait-first-run
```
If you intentionally want to run this package on a different host architecture through QEMU/binfmt, first set:
```bash
ALLOW_CROSS_ARCH=1
```
Then rerun `./install.sh` or `./self-check.sh`, and only then will the scripts attempt to enable the matching binfmt handler.
## Stop and Restart
```bash
./stop.sh
./restart.sh
```
## Status Checks
```bash
./status.sh
./self-check.sh
```
Important checks:
- Docker/Compose availability;
- runtime, metrics, Prometheus and Grafana images exist;
- `HOST_DATA_DIR` is writable;
- Compose config is valid;
- latest run status;
- metrics, Prometheus and Grafana endpoints;
- whether `host_arch`, `package_arch`, and `arch_mode` match expectations.
`status.sh` also prints:
- `package_arch`
- `package_platform`
- `runtime_image`
- `metrics_image`
- `allow_cross_arch`
- `periodic_snapshot_reset`
- `periodic_snapshot_max_deltas`
- `rtr_report_dir`
- `rtr_report_container_dir`
To verify RTR report ingestion:
```bash
curl -s "http://127.0.0.1:${METRICS_PORT:-9556}/metrics" | grep '^ours_rp_rtr_' | head
```
## Upgrade
Extract the new package into a new directory and explicitly reuse the existing `.env` through the upgrade script:
```bash
./upgrade.sh --reuse-env-from /path/to/old-installer/.env
```
If the new package directory already has a `.env`, the upgrade script keeps it.
If an older `.env` does not contain `METRICS_IMAGE` or `METRICS_PLATFORM`, the install/upgrade flow backfills package-matched defaults automatically.
Upgrade does not delete:
- `runs/`
- `logs/`
- `state/rsync-mirror`
- runtime configuration referenced by `.env`
- Prometheus / Grafana data
To validate periodic forced snapshot behavior, temporarily set:
```bash
PERIODIC_SNAPSHOT_RESET=1
PERIODIC_SNAPSHOT_MAX_DELTAS=2
```
Then confirm the latest `run-meta.json` contains:
```bash
snapshot_reason=periodic_snapshot_delta_limit
```
And inspect the independent lifecycle state:
```bash
jq '{last_run,last_success_snapshot,successful_deltas_since_snapshot,state_health}' \
"${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```
After validation, restore:
```bash
PERIODIC_SNAPSHOT_MAX_DELTAS=100
```
## 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.

132
deploy/docker-installer/docs/operations.zh-CN.md Normal file
View File

@@ -0,0 +1,132 @@
# 运维手册（`__PACKAGE_ARCH__`）
## 安装
```bash
./install.sh
```
安装脚本是幂等的：
- 已有 `.env` 不覆盖；
- 已安装 Docker/Compose 则跳过；
- 包内 runtime、metrics、Prometheus、Grafana 对应架构镜像重复加载是安全的；
- 数据目录已存在则复用；
- 默认要求宿主与包架构匹配。
## 启动
```bash
./start.sh
```
如需后台启动后不等待首轮 snapshot：
```bash
./start.sh --no-wait-first-run
```
如需显式允许异构主机通过 QEMU/binfmt 跑包，先在 `.env` 中设置：
```bash
ALLOW_CROSS_ARCH=1
```
然后重新执行 `./install.sh` 或 `./self-check.sh`，脚本才会尝试启用对应 binfmt。
## 停止和重启
```bash
./stop.sh
./restart.sh
```
## 状态检查
```bash
./status.sh
./self-check.sh
```
重点检查项：
- Docker/Compose 可用；
- runtime、metrics、Prometheus、Grafana 镜像存在；
- `HOST_DATA_DIR` 可写；
- Compose 配置合法；
- 最新 run 状态；
- metrics、Prometheus、Grafana endpoint；
- `host_arch`、`package_arch`、`arch_mode` 是否符合预期。
`status.sh` 还会显示：
- `package_arch`
- `package_platform`
- `runtime_image`
- `metrics_image`
- `allow_cross_arch`
- `periodic_snapshot_reset`
- `periodic_snapshot_max_deltas`
- `rtr_report_dir`
- `rtr_report_container_dir`
如需确认 RTR report 已接入：
```bash
curl -s "http://127.0.0.1:${METRICS_PORT:-9556}/metrics" | grep '^ours_rp_rtr_' | head
```
## 升级
把新安装包解压到新目录后，推荐通过升级脚本显式复用旧 `.env`：
```bash
./upgrade.sh --reuse-env-from /path/to/old-installer/.env
```
如果新目录已经存在 `.env`，升级脚本会保留它，不覆盖。
如果旧 `.env` 缺失 `METRICS_IMAGE` 或 `METRICS_PLATFORM`，升级/安装链路会按当前包架构自动补齐默认值。
升级不会删除以下数据：
- `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
```
并检查独立 lifecycle 状态：
```bash
jq '{last_run,last_success_snapshot,successful_deltas_since_snapshot,state_health}' \
"${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```
验证完成后恢复：
```bash
PERIODIC_SNAPSHOT_MAX_DELTAS=100
```
## 清理
```bash
./cleanup.sh --keep-runs 100
./cleanup.sh --keep-runs 100 --execute
```
默认 dry-run，确认后加 `--execute`。

142
deploy/docker-installer/docs/troubleshooting.en.md Normal file
View File

@@ -0,0 +1,142 @@
# Troubleshooting (`__PACKAGE_ARCH__` / `__PACKAGE_PLATFORM__`)
## Docker or Compose Is Unavailable
Run:
```bash
docker version
docker compose version
```
If missing, run:
```bash
./install.sh
```
## Package Architecture Mismatch
If `status.sh`, `install.sh`, or `self-check.sh` reports:
```text
package architecture mismatch
```
the host `uname -m` does not match the packaged `PACKAGE_ARCH=__PACKAGE_ARCH__`. The default behavior is to fail clearly rather than silently switching to emulation.
Only if you intentionally accept QEMU/binfmt cross-architecture execution should you set:
```bash
ALLOW_CROSS_ARCH=1
```
Then rerun install or self-check.
## `__PACKAGE_ARCH__` Image Cannot Run
Running `__PACKAGE_PLATFORM__` images on a different host architecture requires binfmt/qemu. The installer only attempts this automatically when `ALLOW_CROSS_ARCH=1`; you can also enable it manually:
```bash
docker run --rm --privileged tonistiigi/binfmt --install __PACKAGE_ARCH__
docker run --rm --platform __PACKAGE_PLATFORM__ debian:bookworm-slim uname -m
```
For `arm64` packages the expected output is `aarch64`; for `amd64` packages the expected output is `x86_64`.
To confirm the metrics image is also loaded correctly:
```bash
docker image inspect "$(grep '^METRICS_IMAGE=' .env | cut -d= -f2-)"
docker run --rm --platform __PACKAGE_PLATFORM__ \
"$(grep '^METRICS_IMAGE=' .env | cut -d= -f2-)" \
/opt/ours-rp/bin/rpki_artifact_metrics --help
```
## RTR report metrics are empty
Check `.env`:
```bash
grep '^RTR_REPORT_DIR=' .env
test -d "$(grep '^RTR_REPORT_DIR=' .env | cut -d= -f2-)" && echo ok
```
Check the metrics container mount:
```bash
docker inspect "$(grep '^COMPOSE_PROJECT_NAME=' .env | cut -d= -f2-)-artifact-metrics" \
| jq '.[0].Mounts[] | select(.Destination=="/var/lib/ours-rp/rtr-report")'
```
## 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 __HOST_DATA_DIR__/state/live-ta
tail -100 __HOST_DATA_DIR__/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
```
## How to Confirm a Periodic Forced Snapshot
Check the latest run metadata:
```bash
latest="$(find ${HOST_DATA_DIR}/runs -maxdepth 1 -type d -name 'run_*' | sort | tail -1)"
jq '{run_id,sync_mode,snapshot_reason,periodic_snapshot_delta_count,periodic_snapshot_forced,reset_db_cleanup_status}' "$latest/run-meta.json"
```
For a threshold-triggered reset you should see:
- `sync_mode: "snapshot"`
- `snapshot_reason: "periodic_snapshot_delta_limit"`
- `periodic_snapshot_forced: true`
To confirm delta counting still advances after retained runs are pruned, also inspect:
```bash
jq '{last_success_snapshot,successful_deltas_since_snapshot,recent_runs_count:(.recent_runs|length)}' \
"${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```
## Lifecycle State File Is Corrupt
The script backs up the corrupt file before best-effort bootstrap from retained runs:
```bash
ls -1 "${HOST_DATA_DIR}/state"/run-lifecycle-state.json.corrupt.*
jq . "${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```

142
deploy/docker-installer/docs/troubleshooting.zh-CN.md Normal file
View File

@@ -0,0 +1,142 @@
# 故障排查（`__PACKAGE_ARCH__` / `__PACKAGE_PLATFORM__`）
## Docker 或 Compose 不可用
执行：
```bash
docker version
docker compose version
```
如果缺失，重新执行：
```bash
./install.sh
```
## 架构不匹配报错
当 `status.sh` / `install.sh` / `self-check.sh` 报出：
```text
package architecture mismatch
```
说明宿主 `uname -m` 与包的 `PACKAGE_ARCH=__PACKAGE_ARCH__` 不一致。默认行为就是失败而不是静默模拟运行。
只有在你明确接受 QEMU/binfmt 跨架构运行时，才设置：
```bash
ALLOW_CROSS_ARCH=1
```
然后重新执行安装或自检。
## `__PACKAGE_ARCH__` 镜像无法运行
在异构主机上运行 `__PACKAGE_PLATFORM__` 镜像需要 binfmt/qemu。安装脚本只有在 `ALLOW_CROSS_ARCH=1` 时才会自动尝试启用；也可以手动执行：
```bash
docker run --rm --privileged tonistiigi/binfmt --install __PACKAGE_ARCH__
docker run --rm --platform __PACKAGE_PLATFORM__ debian:bookworm-slim uname -m
```
对于 `arm64` 包，预期输出 `aarch64`；对于 `amd64` 包，预期输出 `x86_64`。
如需进一步确认 metrics 镜像也已正确加载：
```bash
docker image inspect "$(grep '^METRICS_IMAGE=' .env | cut -d= -f2-)"
docker run --rm --platform __PACKAGE_PLATFORM__ \
"$(grep '^METRICS_IMAGE=' .env | cut -d= -f2-)" \
/opt/ours-rp/bin/rpki_artifact_metrics --help
```
## RTR report 指标为空
检查 `.env`：
```bash
grep '^RTR_REPORT_DIR=' .env
test -d "$(grep '^RTR_REPORT_DIR=' .env | cut -d= -f2-)" && echo ok
```
检查 metrics 容器是否挂载该目录：
```bash
docker inspect "$(grep '^COMPOSE_PROJECT_NAME=' .env | cut -d= -f2-)-artifact-metrics" \
| jq '.[0].Mounts[] | select(.Destination=="/var/lib/ours-rp/rtr-report")'
```
## 首轮 snapshot 超时
all5 snapshot 可能很慢，尤其在 QEMU 环境。可以提高超时：
```bash
./start.sh --timeout-secs 14400
```
## 产物数量异常偏低
检查：
```bash
grep LIVE_TA_REFRESH_BEFORE_SNAPSHOT .env
ls -l __HOST_DATA_DIR__/state/live-ta
tail -100 __HOST_DATA_DIR__/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
```
## 如何确认触发了定期 forced snapshot
检查最新 run metadata：
```bash
latest="$(find ${HOST_DATA_DIR}/runs -maxdepth 1 -type d -name 'run_*' | sort | tail -1)"
jq '{run_id,sync_mode,snapshot_reason,periodic_snapshot_delta_count,periodic_snapshot_forced,reset_db_cleanup_status}' "$latest/run-meta.json"
```
阈值触发时应看到：
- `sync_mode: "snapshot"`
- `snapshot_reason: "periodic_snapshot_delta_limit"`
- `periodic_snapshot_forced: true`
如需确认 retain 裁剪后仍在累计 delta，可继续检查：
```bash
jq '{last_success_snapshot,successful_deltas_since_snapshot,recent_runs_count:(.recent_runs|length)}' \
"${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```
## Lifecycle 状态文件损坏
脚本会先备份损坏文件，再从当前保留的 `runs/` 尽力 bootstrap：
```bash
ls -1 "${HOST_DATA_DIR}/state"/run-lifecycle-state.json.corrupt.*
jq . "${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```