rpki/deploy/README.md

# Deploy Layout

`deploy/` 目录按角色拆分为四套部署与测试入口：

- `server/`: 本仓库 RTR Server（`src/main.rs`）容器化部署
- `client/`: 本仓库 `rtr_debug_client` 容器化部署
- `frr/`: FRR 作为黑盒 RTR Client 的配置与 compose

---

## 0) Build and Run Scripts

`deploy/server/build-run.sh` 只管理 server，`deploy/client/build-run.sh` 只管理 debug client。两个脚本默认 action 都是 `up`，默认 mode 都是 `tcp`。

常用命令：

以下命令默认从仓库根目录执行。

```bash
chmod +x deploy/server/build-run.sh deploy/client/build-run.sh
./deploy/server/build-run.sh up --mode tcp
./deploy/client/build-run.sh up --mode tcp
./deploy/client/build-run.sh up --clients multi
./deploy/client/build-run.sh down
./deploy/server/build-run.sh down
```

常用参数：

| 参数/变量 | server | client | 说明 |
| --- | --- | --- | --- |
| `--mode base\|tcp\|tls\|ssh`, `MODE` | yes | yes | 选择 compose 模式，默认 `tcp`。 |
| `--clients single\|multi`, `CLIENTS` | no | yes | 单 client 或 5 client，默认 `single`。 |
| `--no-build`, `BUILD=0` | yes | yes | 只运行已有镜像，不执行 compose build。 |
| `--server-image TAG`, `SERVER_IMAGE` | yes | no | server 镜像名；会传给 compose 的 `RPKI_RTR_SERVER_IMAGE`。 |
| `--client-image TAG`, `CLIENT_IMAGE` | no | yes | client 镜像名；会传给 compose 的 `RPKI_RTR_CLIENT_IMAGE`。 |
| `--platform VALUE`, `TARGET_PLATFORM` | yes | yes | `buildx` 目标平台，默认 `linux/arm64`。 |
| `--push`, `BUILDX_PUSH=1` | yes | yes | `buildx` 构建后推送到 registry；不设置时加载到本地 Docker。 |
| `--skip-base-pull`, `SKIP_BASE_IMAGE_PULL=1` | yes | yes | 跳过 buildx 前的基础镜像预拉取。 |

支持的 action 包括 `up`、`build`、`buildx`、`rebuild`、`down`/`stop`、`restart`、`logs`、`ps`。完整帮助见：

```bash
./deploy/server/build-run.sh --help
./deploy/client/build-run.sh --help
```

### x86 Build, ARM Deploy

x86 开发机上用 Docker Buildx 分别构建 ARM server/client 镜像。不加 `--push` 时，脚本会把单平台镜像加载到本地 Docker，随后可用 `docker save` 打包传到 ARM 机器。buildx 前会自动按目标平台预拉取 `rust:1.89-bookworm` 和 `debian:bookworm-slim`。

```bash
docker buildx create --use --name rpki-builder
docker buildx inspect --bootstrap

./deploy/server/build-run.sh buildx \
  --platform linux/arm64 \
  --server-image rpki-rtr:arm64

./deploy/client/build-run.sh buildx \
  --platform linux/arm64 \
  --client-image rpki-rtr-debug-client:arm64

mkdir -p dist/images
docker save rpki-rtr:arm64 -o dist/images/rpki-rtr-arm64.tar
docker save rpki-rtr-debug-client:arm64 -o dist/images/rpki-rtr-debug-client-arm64.tar
```

把 tar 包传到 ARM 部署机：

```bash
scp dist/images/*.tar user@arm-host:/tmp/
```

ARM 部署机上加载镜像并运行，不再本地构建：

```bash
docker load -i /tmp/rpki-rtr-arm64.tar
docker load -i /tmp/rpki-rtr-debug-client-arm64.tar

SERVER_IMAGE=rpki-rtr:arm64 \
BUILD=0 ./deploy/server/build-run.sh up --mode tcp

CLIENT_IMAGE=rpki-rtr-debug-client:arm64 \
BUILD=0 ./deploy/client/build-run.sh up --mode tcp
```

如果不使用脚本，也可以通过 compose 环境变量指定镜像：

```bash
export RPKI_RTR_SERVER_IMAGE=rpki-rtr:arm64
docker compose --env-file deploy/server/.env \
  -f deploy/server/docker-compose.tcp.yml up -d --no-build
```

---

## 1) Server

路径：
- `deploy/server/Dockerfile`
- `deploy/server/docker-compose.yml`
- `deploy/server/DEPLOYMENT.md`

单独 build 镜像：

```bash
docker build -f deploy/server/Dockerfile -t rpki-rtr:latest .
```

启动：

```bash
docker compose -f deploy/server/docker-compose.yml up -d --build
```

停止：

```bash
docker compose -f deploy/server/docker-compose.yml down
```

日志：

```bash
docker compose -f deploy/server/docker-compose.yml logs -f rpki-rtr
```

报告文件：

- `report/rtr-source-*.json`：CCR/SLURM source、fingerprint、refresh 状态、数据质量、cache snapshot/delta 统计。
- `report/rtr-clients-*.json`：client 连接数和连接方式统计，启动时和连接变化时写入。
- `report/rtr-runtime-*.json`：进程 RSS、服务状态、当前生效 runtime configuration，启动时和周期性写入。

Admin config 接口默认关闭。需要运行中动态修改 `max_delta`、delta 裁剪策略、refresh/report interval、timezone 或 RTR timing 时，设置：

```env
RPKI_RTR_ADMIN_ADDR=127.0.0.1:8323
RPKI_RTR_ADMIN_TOKEN=change-me
```

调用示例：

```bash
curl -X POST http://127.0.0.1:8323/admin/rtr/config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer change-me" \
  -d '{"max_delta": 6, "prune_delta_by_snapshot_size": true}'
```

完整 API 说明见 `docs/rtr-admin-api.md`，更完整的 server 配置见 `deploy/server/DEPLOYMENT.md`。

---

## 2) Debug Client

路径：
- `deploy/client/Dockerfile`
- `deploy/client/docker-compose.yml`
- `deploy/client/docker-compose.clients.yml`

单独 build 镜像：

```bash
docker build -f deploy/client/Dockerfile -t rpki-rtr-debug-client:latest .
```

单实例启动（交互调试）：

```bash
docker compose -f deploy/client/docker-compose.yml up --build
```

单实例停止：

```bash
docker compose -f deploy/client/docker-compose.yml down
```

单实例日志：

```bash
docker compose -f deploy/client/docker-compose.yml logs -f rtr-debug-client
```

多实例启动（5 个并发 client）：

```bash
docker compose -f deploy/client/docker-compose.clients.yml up -d
```

多实例停止：

```bash
docker compose -f deploy/client/docker-compose.clients.yml down
```

多实例日志：

```bash
docker compose -f deploy/client/docker-compose.clients.yml logs -f
```

---

## 3) FRR Client

路径：
- `deploy/frr/docker-compose.yml`
- `deploy/frr/daemons.example`
- `deploy/frr/frr.conf.example`
- `deploy/frr/README.md`
- `deploy/frr/README.zh.md`

启动：

```bash
docker compose -f deploy/frr/docker-compose.yml up -d
```

检查连接：

```bash
docker exec -it frr-rpki-client vtysh -c "show rpki cache-connection"
docker exec -it frr-rpki-client vtysh -c "show rpki prefix-table"
```

停止：

```bash
docker compose -f deploy/frr/docker-compose.yml down
```

日志：

```bash
docker compose -f deploy/frr/docker-compose.yml logs -f frr-rpki-client
```

---

## 4) BIRD Client

路径:
- `deploy/bird/Dockerfile`
- `deploy/bird/docker-compose.yml`
- `deploy/bird/docker-compose.tls.yml`
- `deploy/bird/bird.conf.example`
- `deploy/bird/bird.conf.tls.example`
- `deploy/bird/README.md`
- `deploy/bird/README.zh.md`

启动:
```bash
docker compose -f deploy/bird/docker-compose.yml up --build
```

观察活动:

```bash
docker logs -f bird-rpki-client
```

停止:
```bash
docker compose -f deploy/bird/docker-compose.yml down
```

日志:
```bash
docker compose -f deploy/bird/docker-compose.yml logs -f bird-rpki-client
```

TLS/mTLS:
```bash
docker compose -f deploy/bird/docker-compose.yml -f deploy/bird/docker-compose.tls.yml up --build
docker logs -f bird-rpki-client
```