常見的斷網情境：政府或軍事機密網路（實體隔離）、工控與 OT 環境（工廠、電廠、SCADA）、金融交易系統的高安全隔離區、醫療設備網路、以及地端機房裡刻意不開 internet access 的 private zone。

這個模組是橫切約束——它影響模組一（IaC 選型）到模組七（PR 流程）的每一個操作步驟。每篇文章處理一個被斷網影響的主要面向。

章節文章

跟其他模組的關係

• → 模組一：最小可行 IaC：斷網時 IaC 工具選型和 state backend 的替代做法
• → 模組五：核心服務上 IaC：容器映像和套件依賴的離線管理
• → 模組六：可觀測性：斷網環境的監控不能 phone home
• → 模組七：PR 流程：CI/CD 在內網怎麼跑
• → 接手維運：接手斷網環境的額外約束

內容搬運模式（Content Ferry）

斷網環境裡的所有外部依賴（套件、映像、工具、更新）都要經過一條可控的搬運路徑進入。這條路徑的設計決定了環境的安全性和維護效率。

搬運路徑的三種形態

離線媒介搬運：用 USB 隨身碟、外接硬碟或光碟把檔案從有網路的工作站搬進隔離網路。適合高安全環境（軍事、政府機密網路），搬運頻率通常是週或月級。每次搬運的內容要經過掃毒和完整性驗證。

1# 外部工作站：準備搬運包
2mkdir -p ferry/$(date +%Y%m%d)
3# 把需要的套件、映像、工具複製進去
4cp -r packages/ images/ tools/ ferry/$(date +%Y%m%d)/
5# 產生 checksum
6find ferry/$(date +%Y%m%d) -type f -exec sha256sum {} \; > ferry/$(date +%Y%m%d)/manifest.sha256

1# 隔離網路內：驗證搬運包完整性
2cd /mnt/usb/ferry/20260626
3sha256sum -c manifest.sha256

跨網段閘道搬運：在隔離網路的邊界放一台 staging gateway（跳板機），它有兩張網卡——一張連外部網路（或 DMZ）、一張連內部隔離網路。外部的內容先傳到閘道、經過掃描和審查後再推進內部。適合金融和工控環境，搬運頻率可以是日級。

閘道的安全約束：只允許特定的檔案類型通過、所有傳入的檔案經過掃毒、傳輸記錄要保留 audit log、閘道本身定期更新安全軟體。

單向資料二極體（Data Diode）：硬體層面只允許資料單向流動（外 → 內），物理上無法從內部網路傳資料出去。用在最高安全等級的環境。搬運頻率和內容由二極體的設定決定。

搬運的操作紀律

每次搬運都要記錄：日期、搬運者、搬運內容清單（檔名 + 版本 + checksum）、搬運理由。這份紀錄存在內部網路的版本控制裡，讓「這個套件是誰、什麼時候、為什麼帶進來的」事後可追溯。

搬運內容的安全審查至少包含：掃毒（ClamAV 或商業掃毒）、checksum 驗證（確認搬運過程沒有被竄改）、版本確認（確認搬進來的版本跟預期的一致、不是被降級的舊版）。

時程參考：建立搬運流程（含閘道設定、掃描工具安裝、紀錄模板）約需 2-3 天。之後每次搬運操作約 1-2 小時（含準備、掃描、驗證、紀錄）。

離線套件管理

連網環境的 apt install、yum install、npm install 背後都在連線到公開的套件倉庫。斷網環境需要在內部建立這些倉庫的離線鏡像。

作業系統套件

Debian/Ubuntu：用 apt-mirror 或 aptly 在有網路的環境建立 mirror，把整個 mirror 搬進內部網路，內部機器的 /etc/apt/sources.list 指向內部 mirror。

1# 外部：建立 mirror（首次約 50-200GB，後續增量）
2apt-mirror /etc/apt/mirror.list
3
4# 內部：設定 sources.list 指向內部 mirror
5echo "deb http://internal-mirror.local/ubuntu jammy main restricted" > /etc/apt/sources.list
6apt update

RHEL/CentOS：用 reposync 把 yum repo 同步到本地，搬進內部後用 createrepo 建立 repo metadata。

1# 外部：同步 repo
2reposync --repoid=baseos --download-metadata -p /path/to/mirror/
3
4# 內部：建立 repo 並設定
5createrepo /path/to/mirror/baseos

應用層套件

Node.js（npm）：npm pack 把每個依賴打包成 .tgz，搬進內部後用 npm install --offline 或建立 Verdaccio private registry。

1# 外部：打包所有依賴
2npm pack --pack-destination ./offline-packages/
3# 或用 npm-offline-mirror
4npm install --prefer-offline --cache ./npm-cache

Python（pip）：pip download 把依賴下載成 wheel 或 tarball，搬進內部後 pip install --no-index --find-links=./packages/。

PHP（Composer）：composer install 後整個 vendor/ 目錄打包搬進去。或建立 Satis 作為 private Packagist mirror。

套件鏡像的維護節奏

離線 mirror 需要定期更新——安全補丁、版本升級都要透過搬運流程進入。更新頻率取決於安全需求：高安全環境至少月更（安全補丁）、一般環境季更可接受。每次更新都是一次搬運操作，要走完整的審查流程。

多格式統一：Nexus Repository

上面的做法是每個套件生態各自建 mirror（apt-mirror + Verdaccio + Satis + pip local index）。Nexus Repository 是多格式統一的 artifact proxy，同時支援 apt / yum / npm / Maven / PyPI / Docker / Helm——在企業級斷網環境裡，用一個 Nexus 實例取代多個獨立的離線 repo mirror，維護成本較低。代價是 Nexus 本身的安裝和維運（Java 應用、需要磁碟空間和記憶體），小團隊各自建 mirror 可能反而更簡單。

離線 Configuration Management：Ansible

斷網環境的 OS 設定、套件安裝、服務啟動等 configuration management 需求，Ansible 是運作良好的工具——它不需要在目標機器安裝 agent、透過 SSH 推送 playbook 執行，playbook 本身是 YAML 可版本控制。在沒有雲端 IaC（Terraform 管的是雲端資源 API）的地端斷網環境裡，Ansible 負責 configuration management 層。Ansible 自身的安裝只需要 Python，控制端安裝後即可透過 SSH 管理內部所有機器。

變更追蹤：沒有 GitHub 怎麼辦

斷網環境不能 push 到 GitHub、不能開 PR、不能用 GitHub Actions。但 git 本身是離線工具——git 的所有操作（commit、branch、merge、log、diff）都不需要網路。

內部 Git Server

在隔離網路內架設 git server：Gitea（輕量、單一二進位、適合小團隊）、GitLab CE（功能完整、含 CI/CD runner、適合中大團隊）、或最簡單的 bare repo on NFS。

1# 最簡單的方式：bare repo on 共用檔案系統
2git init --bare /shared/repos/infra.git
3
4# 開發者 clone
5git clone /shared/repos/infra.git

Git Bundle 跨網段傳遞

如果需要在有網路的環境開發、完成後搬進隔離網路，用 git bundle 把 commit 打包成單一檔案：

1# 外部：把 main branch 的所有 commit 打包
2git bundle create infra-$(date +%Y%m%d).bundle main
3
4# 搬運後，在內部 clone 或 pull
5git clone infra-20260626.bundle infra-repo
6# 或增量更新
7git pull infra-20260626.bundle main

bundle 檔案可以用 git bundle verify 驗證完整性。增量 bundle（只包含某個 tag 之後的 commit）可以減少搬運的資料量：

1git bundle create incremental.bundle last-imported-tag..main

Code Review 的替代方案

沒有 GitHub PR，code review 可以用：

• GitLab CE / Gitea 的內建 merge request（如果架了內部 git server）
• git format-patch 產出 patch 檔 + email review（傳統做法、不需要 web UI）
• git diff main..feature | less 直接在終端機 review（最簡陋但可行）

Staging Gateway 的設計

staging gateway 是搬運路徑的關鍵節點——它決定了什麼能進、什麼不能進。設計要點：

最小安裝：閘道上只裝搬運需要的工具（scp、rsync、掃毒軟體、checksum 工具），不裝開發工具、不跑應用服務。攻擊面越小越好。

雙網卡隔離：一張網卡連外部（或 DMZ）、一張連內部。兩張網卡之間沒有自動路由——檔案必須經過人工或腳本從外部目錄搬到內部目錄，中間經過掃描。

審計紀錄：閘道上的所有檔案操作（建立、複製、刪除）都要記錄。auditd 或等價工具提供核心層級的操作追蹤。

定期輪替：閘道本身的 OS 和掃毒軟體需要更新。這是一個遞迴問題（用什麼搬運閘道的更新？）——通常用離線媒介搬運閘道自身的更新，或用另一台更上游的閘道。

時程參考：閘道的初次設定（含 OS 安裝、雙網卡配置、掃描工具、審計設定）約需 1-2 天。搬運流程文件化約需半天。

安全審查：什麼能跨越隔離邊界

每一筆跨越隔離邊界的內容都是潛在的攻擊向量。審查的原則是：預設拒絕，逐項允許。

審查清單：

對決策者的重點：斷網環境的安全不是「隔離就安全」——搬運路徑是唯一的攻擊面，這條路徑的安全審查品質決定了整個隔離環境的安全水位。

跨分類引用

• → 斷網環境的 IaC：Terraform provider 和 module 的離線管理
• → 斷網環境的容器管理：映像搬運用的是本篇的 content ferry 模式
• → 模組八：治理好習慣：斷網環境的搬運紀錄是治理的一部分

三種處理方式

靜默隱藏

把不可用的功能從 UI 上移除 — 按鈕消失、選單項目隱藏。使用者看不到這些功能，自然不會嘗試使用。

靜默隱藏的風險是使用者困惑。經常使用的功能突然消失，使用者會以為是 bug 或 app 更新移除了功能。如果功能在恢復後重新出現，使用者的困惑加劇。

靜默隱藏只適合使用者從未使用過的功能（新使用者尚未配對時隱藏連線按鈕）。已經使用過的功能突然隱藏會破壞使用者的心理模型。

明確標示

功能的 UI 元素保留在畫面上，但加上不可用的視覺標示 — 灰色按鈕、「離線不可用」標籤、禁用狀態。使用者能看到功能存在，也知道目前暫時無法使用。

明確標示的設計要點：

說明原因。「搜尋功能需要網路連線」比單純的灰色按鈕提供更多資訊。使用者知道原因後能自行判斷要等還是離開。

說明恢復條件。「連上網路後自動恢復」讓使用者知道什麼時候功能會回來。「重新啟動 app 後可用」讓使用者知道需要採取行動。

避免只靠顏色傳達狀態。灰色按鈕對色盲使用者可能不明顯。搭配文字標籤或圖示。

替代方案

提供不需要失敗依賴的替代功能。線上搜尋不可用時提供離線搜尋（本地快取的資料）。即時同步不可用時提供本地儲存（恢復連線後自動同步）。

替代方案的 UX 需要讓使用者知道目前使用的是替代版本。「離線模式 — 搜尋結果可能不是最新的」讓使用者對結果的準確度有正確預期。

全域 vs 功能級降級

全域降級

整個 app 進入降級模式 — 頂部顯示「離線模式」橫幅，所有需要網路的功能統一標示為不可用。適合網路連線是 app 核心依賴的場景。

全域降級的 UI 實作簡單（一個全域狀態控制所有功能的可用性），但可能過度限制 — 部分功能不依賴網路也能運作。

功能級降級

每個功能獨立判斷自己的可用狀態。搜尋需要網路但筆記不需要 — 網路斷線時搜尋不可用，筆記正常。

功能級降級更精確但實作更複雜 — 每個功能需要宣告自己的依賴，並在依賴不可用時提供對應的 UI 狀態。

降級狀態的進入和退出

進入

依賴不可用時自動進入降級狀態。進入時通知使用者（Snackbar、橫幅、狀態變更）。

避免頻繁切換 — 網路訊號不穩定時，每秒在正常和降級之間切換會讓 UI 閃爍。加入穩定性判斷（連續 N 秒不可用才進入降級，連續 N 秒可用才退出降級）。

退出

依賴恢復後自動退出降級狀態。退出時通知使用者（「已恢復連線」），並自動執行待完成的操作（同步、補發事件）。

下一步路由

• 錯誤訊息的撰寫 → 錯誤訊息撰寫原則
• 重試循環的逃生口 → error → retry → error 循環的逃生口
• 網路 gate 的 UX 處理 → ux-design 模組二 網路斷線 UX 模式

三種處理策略

Offline-first

功能的核心操作在本地完成，網路用於同步。斷線時使用者仍可操作，重新連線後自動同步差異。

Offline-first 適合的前提是資料可以本地存儲且衝突可以解決。筆記 app、待辦事項、表單填寫 — 使用者的操作產生本地資料，網路只負責把資料同步到 server。

Offline-first 的 UX 設計重點是讓使用者知道同步狀態：已同步、待同步、同步失敗。不需要 gate — 網路狀態不阻擋使用者操作。

Retry with feedback

功能需要網路但可以等待。斷線時顯示狀態和重試選項，使用者決定要等還是離開。

app_tunnel 的 terminal 連線屬於這個模式。WebSocket 連線需要網路，斷線時使用者無法操作終端機。error 和 disconnected 狀態提供重連按鈕讓使用者手動重試。

Retry 策略的 UX 設計重點：

• 告知使用者發生什麼（「連線中斷」而非空白畫面）
• 提供手動重試（重連按鈕）
• 提供退出路徑（返回首頁 — app_tunnel 原本缺少這個）
• 自動重試要有上限和間隔遞增（避免無限重試消耗電量）

Degraded mode

功能部分依賴網路。核心功能離線可用，進階功能需要網路。斷線時自動切換到降級模式，不阻擋使用者操作但功能受限。

降級模式的 UX 設計重點是清楚標示哪些功能可用、哪些不可用。「離線模式 — 搜尋功能暫時不可用」比靜默隱藏搜尋按鈕更透明。

網路狀態的 UI 呈現

全域指示器

在 app 頂部或狀態列顯示「離線」標示。適合網路狀態影響全域功能的 app。

功能級指示器

在需要網路的功能旁邊顯示不可用狀態。適合只有部分功能依賴網路的 app。

非侵入式通知

用 Snackbar 或 Toast 短暫顯示「已恢復連線」或「網路中斷」。適合網路狀態偶爾變化的場景。不適合頻繁斷開重連的場景（通知太多會干擾使用者）。

連線但品質差的場景

網路存在但延遲高或頻繁斷開，比完全離線更難處理。完全離線時 app 可以立即切換到離線模式；連線不穩定時，每次請求可能成功也可能逾時，使用者體驗是「有時候行有時候不行」。

處理策略：

• 設定合理的逾時時間（太短會把慢回應判定為失敗，太長讓使用者等太久）
• 逾時後顯示狀態和重試選項，不自動重試（避免在不穩定網路上累積重試）
• 在 loading 狀態提供取消選項，讓使用者可以中斷等待

下一步路由

• Gate 設計的通用方法論 → Gate 分類與三問設計法
• 權限請求的 UX 設計 → Permission 請求時機與措辭
• 畫面狀態矩陣中的網路狀態 → ux-design 模組一 畫面狀態機
• Server 端背壓如何影響 client UX → DevOps 背壓機制

三種策略

FIFO 丟棄（最簡單）

Buffer 滿時丟棄最舊的事件，保留最新的。整個 buffer 在記憶體中，不做本地 persistence。

優點：實作最簡單（array + 容量檢查），不需要檔案系統存取，不增加磁碟 I/O。

代價：離線超過 buffer 容量時，較舊的事件永久遺失。如果離線 30 分鐘、buffer 容量 200 筆、事件產生速率每分鐘 10 筆，前 100 筆（前 10 分鐘）的事件被丟棄。

適合場景：自用工具（離線場景少、遺失部分事件影響低）、SDK 初期版本（先用最簡單的策略上線）。

本地 persistence（最完整）

Buffer 滿時把事件寫入本地檔案（SQLite、JSONL 檔案、SharedPreferences / UserDefaults）。網路恢復後從本地檔案讀取並補發。

優點：離線期間的事件不會遺失（在本地儲存容量內）。

代價：實作複雜度高 — 需要處理檔案讀寫、並發存取（多執行緒安全）、本地儲存容量管理（磁碟空間上限）、補發時的去重（同一筆事件可能已在記憶體 buffer 中被 flush 過）。

適合場景：商業產品（使用者在地鐵、電梯、飛航模式下使用）、離線時間長且事件不可遺失的需求。

混合策略

記憶體 buffer 處理正常情況和短暫離線。離線超過記憶體 buffer 容量時，溢出的事件寫入本地檔案。網路恢復後先 flush 記憶體 buffer（最新事件），再補發本地檔案中的事件（較舊事件）。

混合策略的實作複雜度介於兩者之間。本地檔案只在溢出時使用，正常情況下不產生磁碟 I/O。

恢復後補發

網路恢復後補發離線期間累積的事件，需要處理三個問題：

補發順序

離線事件按 timestamp 順序補發，保持事件的時間順序。Collector 端收到的事件 timestamp 可能比當前時間早數小時 — 這是正常的離線補發，collector 應該根據事件的 timestamp 處理，不依賴收到時間。

補發速率

一次送出大量離線事件可能讓 collector 過載。分批補發（每批 50-100 筆，間隔 1-2 秒），讓 collector 有時間處理。

去重

同一筆事件可能同時存在於記憶體 buffer 和本地檔案中（寫入本地檔案時 buffer 中也有一份）。Collector 端用事件的唯一識別（timestamp + session_id + name 的組合，或 SDK 產生的 event_id UUID）做去重。

本地儲存容量管理

本地 persistence 需要設定磁碟使用上限。上限取決於事件大小和保留時間。

以平均每筆事件 500 bytes 估算：

自用工具 1 MB 足夠（離線場景少）。行動 app 10-50 MB 合理（使用者可能整天離線）。超過上限時用 FIFO 丟棄最舊的本地檔案。

各平台的本地儲存路徑

本地 persistence 的檔案路徑和格式因平台而異。MVP 階段全用記憶體 FIFO（最簡單策略），本地 persistence 標為第二階段。

App 被強制終止時（iOS 的 kill、Android 的 process death），記憶體 buffer 中未 flush 的事件會遺失。Flutter 的 AppLifecycleState.detached 不保證有時間執行 flush。接受這個遺失 — 強制終止是極端情境，下次啟動時 SDK 重新開始收集。

下一步路由

• 攢批送出策略 → 攢批送出策略
• SDK 端的資料脫敏 → SDK redaction helper
• Collector 端如何處理補發事件 → 模組四 Collector 設計
• 從 SDK 到 storage 的端到端資料損失地圖 → 端到端資料完整性