118 lines
3.0 KiB
Markdown
118 lines
3.0 KiB
Markdown
# 故障排查（`__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`。
|
||
|
||
## 首轮 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"
|
||
```
|