Docker 在 Windows 上的部署、運行與故障排除
此技能源自將 Docker Compose 應用程式完整部署到 Windows 11 桌面（中國大陸網路環境）並實現「無人值守、重啟後持續運行」的實際操作知識。下列錯誤看似玄妙，修復方法亦非直觀——正因如此，才值得記錄下來。寧可依循此處解法，也不要胡亂猜測；每一項修復都耗費了真實的除錯時間。
此處內容並未綁定特定應用——範例為 Python/FastAPI + pgvector 堆疊，但常見陷阱（Docker Desktop Socket、網路封鎖、自動啟動、PowerShell 編碼）會影響任何在 Windows 上的 Docker 化專案。
首先，先確認狀況再行動
以下快速檢查可決定你需要參考哪個檔案：
- Docker 是否正在執行？
docker version(客戶端+伺服器)、docker compose ps。若伺服器錯誤通常表示 Docker Desktop 啟動時崩潰 → 參考crash-recovery.md。 - WSL2 後端正常？
wsl -l -v— 發行版 (例如docker-desktop) 應顯示為Running。 - 是否為中國大陸網路？ 若映像拉取或下載逾時或 TLS 失敗，假設網路被封鎖，並在重試前先前往
china-network.md。 - 是否需要重啟後無人值守執行？ 這不是單一設定能解決，而是一整套流程 →
unattended-operation.md。
症狀 → 參考文件對照表
| 症狀 | 參考文件 |
|---|---|
Docker Desktop 無法啟動、崩潰循環、或記錄 Inference manager / Secrets Engine / listening on unix://… / the file cannot be accessed by the system / syntax is incorrect | references/crash-recovery.md |
docker pull 出現 EOF/TLS handshake timeout；建構時 pip/apt 失敗；wsl --install 卡住；winget 0x8a15000f；HuggingFace/模型下載 302 轉向到被封鎖的主機 | references/china-network.md |
| 必須在重啟後無人值守執行（自動登入、自動啟動、鎖定螢幕、重新啟動原則），或「我登入時能運作，但開機後卻無法」 | references/unattended-operation.md |
.ps1 腳本亂碼、出現 Missing closing '}'、殺死自身程序、或每個原生指令都輸出紅色錯誤文字 | references/windows-scripting.md |
| 部署到新 Windows 機器、還原資料庫磁碟區、或「我編輯了程式碼但容器沒有變更」 | references/deploy-workflow.md |
可通用的原則（即使不閱讀參考文件，也請略讀此處）
-
Docker Desktop 在 Windows 上最嚴重的故障是孤立的 AF_UNIX socket，而非設定錯誤。 硬停止（崩潰/強制退出/斷電）會留下無法刪除的 reparse-point socket 檔案，位於
%LOCALAPPDATA%\Docker\run\和%LOCALAPPDATA%\docker-secrets-engine\下。Docker 下次啟動時嘗試移除並重新建立它們，因而陷入崩潰循環。你無法刪除它們（Remove-Item/.NETDelete都會失敗）——但你可以重新命名父目錄（這是一個中繼資料操作，能繞過存取錯誤）。重新命名後，Docker 會乾淨重建。切換EnableInference/EnableDockerAI無法解決此問題。詳見crash-recovery.md。 -
在中國大陸網路環境下，優先使用鏡像，其次才是直接連線。 Docker Hub、
winget、線上wsl --install、deb.debian.org和 HuggingFace 大型權重檔案會被封鎖或不穩定。註冊表鏡像、清華 pip/apt、離線 WSL MSI、以及 ModelScope 用於模型權重，才是可靠路徑。desktop.docker.com和 GitHub Releases 可以直接連線。詳見china-network.md。 -
在 Windows 自動登入下，
HKCU\...\Run自動啟動項目會默默地不觸發**。** 應改用「登入時」觸發的工作排程器任務。這是無人值守設定中最容易踩的坑。詳見unattended-operation.md。 -
撰寫
.ps1檔案時請僅使用 ASCII 字元。 PowerShell 5.1 將無 BOM 的 UTF-8 檔案視為 GBK；任何非 ASCII 字元（例如中文註解）都會破壞大括號配對 →Missing closing '}'→ 腳本立即死亡，不留任何記錄。請保持腳本純 ASCII；記錄日誌使用英文。詳見windows-scripting.md。 -
掛載的程式碼 = 重啟，而非重建。 若
docker-compose.yml使用 bind mount 掛載原始碼 (./:/app)，編輯程式碼後執行docker compose restart <svc>即可生效——不需要重建映像。僅在依賴項目或 Dockerfile 變更時才需重建。在讓實際排程觸發之前，先用一次性的docker compose exec <svc> python …進行乾運行驗證邏輯變更，這樣你就不會透過發送測試資料到正式輸出通道來測試。詳見deploy-workflow.md。 -
尊重單寫入者限制。 若應用程式按排程將資料推送到外部通道，同一時間只能有一台機器執行排程器——兩份副本會導致重複傳送。在啟動新機器之前，請先關閉舊機器 (
docker compose down)。 -
Claude 無法靜默取得管理員權限。 任何需要權限提升的系統變更都必須由使用者在 UAC 提示中確認 (
Start-Process -Verb RunAs會觸發該提示)。請將此類步驟清楚標記為 「需手動操作 / manual step」——操作者為中文使用者且基礎架構較少，需要逐步指引並明確標出需手動介入的時機。自動權限模式也會封鎖ExecutionPolicy Bypass + elevation，因此請不要繞過提示。
如何擴充此技能
當遇到新的非顯而易見的 Windows/Docker 故障並解決後，請將其加入對應的參考檔案（症狀 → 根因 → 確實有效的修復方法，以及無效的方法）。「無效的方法」這一行通常最具價值——它能阻止下一個人重試死胡同。