# CT124 故障復原報告 — Docker / Tailscale 全面當機

> 日期：2026-05-29　|　主機：CT124（192.168.42.124，Ubuntu 24.04 LXC）
> 誘因：**非正常關機（硬斷電）**　|　結果：38/38 容器恢復，零資料遺失

---

## 一、摘要

CT124 在一次非正常關機（reboot 後 uptime 僅 6 分鐘）後，Docker daemon 陷入 crash-loop，連帶導致這台上約 30 個 compose stack 全數停擺，其中包含對外提供 Headscale 反向代理的 Nginx Proxy Manager（NPM）。最初的症狀是 **Tailscale（Headscale client）連不上 control server**，往下追才發現是整條相依鏈崩潰。

最終全部修復，且 Orthanc PACS 的醫療影像 SQLite 索引損毀也以非破壞性方式完整復原（零資料遺失）。

| 項目 | 修復後狀態 |
|---|---|
| 容器 | 38 / 38 running，0 not-running |
| docker.service | active |
| Tailscale | `100.64.0.28`，已登入 Headscale |
| Orthanc PACS | 11 patients / 18 studies / 7616 instances / 3.2GB，資料完整 |

---

## 二、根因與相依鏈

這是一次 reboot 引發的**連鎖故障**，共六層：

| # | 問題 | 根因 |
|---|---|---|
| 1 | Docker daemon crash-loop（exit 2） | libnetwork 的 `local-kv.db`（bbolt）損毀，dockerd 還原網路 sandbox 時 panic：`assertion failed: write: circular dependency occurred` |
| 2 | **Tailscale 連不上 Headscale**（原始症狀） | 對外 443 由 CT124 上的 **NPM 容器**反代到 Headscale；NPM 隨 docker 崩潰掛掉，443 無人監聽（`connection refused`） |
| 3 | 約 30 個 compose stack 全停 | reboot + docker 崩潰，非 host-network 的容器全部 Exited（只有 host-network 的 tailscale/netbird + jellyfin 活著） |
| 4 | 後半 stack 重建時 `all predefined address pools have been fully subnetted` | 移除 `local-kv.db` 後，kernel 殘留 21 個孤兒 `br-*` bridge，仍佔著 `172.18–31.x` 與 `192.168.0/48/.../128` 子網，Docker 判定位址池全被佔用 |
| 5 | prometheus crash-loop | 資料目錄 `/opt/ai-proxy-hub/prometheus_data` 屬 root，但容器以 `nobody`(65534) 執行 → `permission denied`（pre-existing，非本次新問題） |
| 6 | orthanc-pacs crash-loop | SQLite 索引 `/opt/ohif-docker/orthanc-db/index` 損毀（`SQLITE_CORRUPT`，code 11），硬斷電寫入中斷所致 |

### 關鍵非顯性拓撲

```
外部 → headscale.lotimmy.com:443
        │  (DNS → 125.229.110.50 = CT124 自己的 WAN IP，hairpin 繞回內網)
        ▼
   CT124：Nginx Proxy Manager 容器 (443 反代)
        │
        ▼
   Headscale 本體（內網監聽 :8080，/health 回 {"status":"pass"}）
        ▲
        │  /opt/tailscale 容器 (network_mode: host) 作為 client 連回
```

> 相依鏈：**docker daemon → NPM 容器 → Headscale**。NPM 一掛，Tailscale 就 logged out。排查 Tailscale 斷線時務必先確認這條鏈，別誤判成 Tailscale 本身問題。

---

## 三、修復步驟（依序）

### 1. 修復 Docker daemon（移除損毀的網路 DB）
```bash
systemctl stop docker.socket docker.service
pkill -9 docker-proxy; pkill -9 dockerd
mv /var/lib/docker/network/files/local-kv.db \
   /var/lib/docker/network/files/local-kv.db.bak.$(date +%s)
systemctl reset-failed docker.service
systemctl start docker.service
```
> host-network 的 tailscale/netbird/jellyfin 會自動回來；自訂網路的容器仍會 Exited（見步驟 3、4）。

### 2. 重建 NPM（恢復對外 443 → Tailscale 即可連線）
```bash
cd /opt/nginx-proxy-manager
docker compose down          # 清掉殘留 container 對已死網路 ID 的參照
docker rm -f nginxproxymanager
docker compose up -d
# 驗證：curl -m10 https://headscale.lotimmy.com/health  → HTTP 200 {"status":"pass"}
docker restart tailscale     # 讓 client 重新登入
docker exec tailscale tailscale status   # 應取得 100.64.0.x
```

### 3. 清除孤兒 bridge（釋放 Docker 位址池）
移除 `local-kv.db` 後，kernel 殘留的 `br-*` 介面不屬於任何現存 docker 網路，卻佔住子網。只刪「非當前網路」的 bridge：
```bash
keep="docker0"
for id in $(docker network ls -q); do keep="$keep br-$id"; done
for br in $(ip -o link show | awk -F': ' '{print $2}' | sed 's/@.*//' | grep '^br-'); do
  echo "$keep" | grep -qw "$br" || { ip link set "$br" down; ip link delete "$br"; }
done
```
> 本次刪除 21 個孤兒 bridge。

### 4. 重建所有停掉的 compose stack
```bash
for d in /opt/<each-stack>; do
  (cd "$d" && docker compose down >/dev/null 2>&1; docker compose up -d)
done
```
> 注意：偵測 compose 檔不要用 `ls a.yml b.yml`（多重 glob 只要一個沒中就回非零會誤判）；直接 `cd` 進目錄讓 `docker compose` 自動辨識 `docker-compose.yml` / `compose.yaml`。

### 5. 修 prometheus 權限
```bash
chown -R 65534:65534 /opt/ai-proxy-hub/prometheus_data
docker restart prometheus
```

### 6. 復原 Orthanc 損毀的 SQLite 索引（非破壞性）
實體影像（`00`–`ff` content-addressed 目錄）完好，只有索引檔損毀。`PRAGMA integrity_check` 顯示為孤立 page + 重複 page 引用：
```bash
cd /opt/ohif-docker/orthanc-db
docker stop orthanc-pacs
cp -a index index.corrupt.bak.$(date +%s)        # 先備份
apt-get install -y sqlite3                         # 需 3.45+（Ubuntu 24.04 內建）
sqlite3 index ".dump" > dump.sql                   # .recover 在此環境 dbpage vtab 失效，改用 .dump
# .dump 因損毀 page 結尾會是 "ROLLBACK; -- due to errors"，但資料其實都已 dump 出來：
sed -i 's/^ROLLBACK; -- due to errors/COMMIT;/' dump.sql
sqlite3 index.rebuilt < dump.sql
sqlite3 index.rebuilt "PRAGMA integrity_check;"    # → ok
# 比對列數確認零遺失後換上：
mv index index.corrupt.old; mv index.rebuilt index; chown root:root index
docker start orthanc-pacs
```
復原前後列數比對（完全吻合）：

| 表 | 原損毀檔 | 重建後 |
|---|---|---|
| Resources | 7775 | 7775 |
| Metadata | 83382 | 83382 |
| AttachedFiles（實體影像）| 7746 | 7746 |
| MainDicomTags | 50834 | 50834 |
| Changes | 8124 | 8124 |
| DicomIdentifiers | 7897 | 7897 |
| GlobalProperties | 4（其中 1 列為損毀讀不出）| 3（乾淨，含 `DatabaseSchemaVersion=6`）|

> 索引檔從 23.5MB 縮為 11.6MB（損毀膨脹被清除）。

---

## 四、留下的備份（確認運作正常後可刪）

```
/var/lib/docker/network/files/local-kv.db.bak.<ts>     損毀的 docker 網路 DB
/opt/ohif-docker/orthanc-db/index.corrupt.bak.<ts>     損毀的 orthanc 索引
/opt/ohif-docker/orthanc-db/index.corrupt.old          同上（另一份）
```

---

## 五、預防建議

1. **務必走正常 shutdown**：本次 1（docker 網路 DB）與 6（orthanc SQLite）兩處損毀都源於硬斷電。LXC 裡的 Docker 對非正常關機特別脆弱。可參考 `PVECluster_Architecture.md` 的「停電復電 SOP」。
2. **UPS / 自動關機**：若停電風險高，建議掛 UPS 並設定 NUT 在斷電時對 CT124 觸發 graceful shutdown。
3. **Orthanc 改用 PostgreSQL 後端**（選配）：SQLite 在 LXC + 突發斷電下較易損毀；改用 PostgreSQL plugin 可顯著降低索引損毀風險。
4. **PBS 備份涵蓋 CT124**：確認 `/opt` 下各 stack 的資料卷有納入 Proxmox Backup Server 排程，作為索引復原失敗時的最後保險。