從第一個 API 呼叫到正式環境

0. 開始前

先確認 Docker Desktop Windows 系統需求與授權條款。Windows Server 不是本指南的支援路徑。

1. 驗證 Source Kit

供應方必須從已認證管道提供 archive、64 字元 SHA-256 與 revision。替換下列值；不一致就停止，不要解壓縮或執行。

$Kit = Resolve-Path "$HOME\Downloads\Sentinel-Monitor-source-kit.zip"
$ExpectedSha256 = "paste-the-supplied-64-character-sha256-here"
$ActualSha256 = (Get-FileHash -LiteralPath $Kit -Algorithm SHA256).Hash.ToLowerInvariant()
if ($ActualSha256 -ne $ExpectedSha256.ToLowerInvariant()) {
  throw "Source-kit SHA-256 mismatch. Do not run this archive."
}

解壓後再比較 release manifest 或 git rev-parse HEAD。沒有 out-of-band checksum/revision 的 archive 無法獨立驗證，應要求補齊。

2. 啟用 WSL 2 backend

以系統管理員身分開啟 PowerShell：

wsl --install --no-distribution

重新開機，再回到系統管理員 PowerShell。原生 PowerShell Quickstart 不需要安裝 Linux distro；只有稍後选择 POSIX 路徑才安裝 Ubuntu。

wsl --update
wsl --set-default-version 2
wsl --version
wsl --status

若目前 Windows build 不支援 --no-distribution，先依 Microsoft 指南完成 WSL 更新；安装 Ubuntu 也可继续，但不是原生路徑的必要条件。完整例外處理請看 Microsoft WSL 安裝指南.

3. 安裝並啟動 Docker Desktop

1. 只從 Docker 官方 Windows 安裝頁.
2. 一般使用者選擇 per-user 與 WSL 2 backend。
3. 從開始功能表開啟 Docker Desktop；安裝完成不代表 Engine 已啟動。
4. 等待 Engine running，並確認 General → Use the WSL 2 based engine。
5. 只有要在 Ubuntu 內執行 POSIX 腳本時，才到 Resources → WSL Integration 啟用該 distro，再 Apply & restart；原生 PowerShell 路徑跳過。

若看不到 WSL Integration，從 Docker tray 切換為 Linux containers。不要在 Ubuntu 另裝第二套 Docker Engine；官方說明衝突風險.

docker version
docker compose version
docker info --format '{{.OSType}}'

docker version 要有 Client 與 Server，OSType 必須是 linux。Compose 是 docker compose（中間有空格），不需另裝舊版 docker-compose。

4. 原生 PowerShell Quickstart

把已驗證 kit 解壓到 C:\Users\you\Sentinel-Monitor 之類的個人目錄。避免 Program Files、OneDrive、網路磁碟，並確認 backend、frontend、deploy 與 docs 都存在。

Set-Location "$HOME\Sentinel-Monitor\deploy\api"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\quickstart.ps1

它會驗證 Linux Docker Engine、建立只限目前使用者的 .env、只啟動 api + mock-model、等待 readiness，再執行不依賴 Python 的完整第一則 Event 與 SHA-256 驗證。

API readiness passed.
PASS: evt_... -> ...sentinel-first-event-powershell.jpg (... bytes)
Quickstart complete. The API node remains running at http://127.0.0.1:8000.

只做 configuration preflight，不啟動容器（若缺少 .env，會安全建立它）：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\quickstart.ps1 -PreflightOnly

5. 驗收

docker compose ps
curl.exe --fail http://127.0.0.1:8000/healthz
curl.exe --fail http://127.0.0.1:8000/readyz

兩者必須是 HTTP 200。接著開啟 http://127.0.0.1:8000/v1/docs.

6. 繼續整合，不把 key 放進指令列

Quickstart 的子程序不會修改父層 PowerShell。後續呼叫時，從 ACL 限制的 .env 只載入目前 shell，以 PowerShell HTTP client 送出，再立即移除環境變數：

$ApiKeyLine = Get-Content -LiteralPath .\.env |
  Where-Object { $_.StartsWith("SENTINEL_API_KEY=") } |
  Select-Object -First 1
if (-not $ApiKeyLine) { throw "SENTINEL_API_KEY is missing from .env" }

$env:SENTINEL_API_KEY = $ApiKeyLine.Substring("SENTINEL_API_KEY=".Length)
try {
  $Headers = @{ Authorization = "Bearer $env:SENTINEL_API_KEY" }
  Invoke-RestMethod -Uri "http://127.0.0.1:8000/v1/system" -Headers $Headers
} finally {
  Remove-Item Env:SENTINEL_API_KEY -ErrorAction SilentlyContinue
  Clear-Variable Headers, ApiKeyLine -ErrorAction SilentlyContinue
}

POSIX 腳本：只在 Ubuntu/WSL

直接操作 shell scripts 時，把另一個 checkout 放到 ~/Sentinel-Monitor（不要用 /mnt/c），在 Ubuntu 安裝 Python 3，再執行：

cd ~/Sentinel-Monitor
chmod +x deploy/api/*.sh deploy/api/recovery/*.sh
cd deploy/api
./quickstart.sh

不要用 PowerShell、Command Prompt、Git Bash 或按兩下方式執行這條路徑。

常見問題

GPU 事實，不做模糊承諾

mock 首跑不需要 GPU。deploy/api 的 local_* 是 NVIDIA/vLLM 容器路徑；Windows 上需要 WSL 2、支援的 NVIDIA GPU、最新版 WSL kernel 與支援 WSL 的 NVIDIA Windows driver。

Docker 目前只支援 WSL2 + NVIDIA GPU-PV. AMD/Intel 與原生 DirectML 不是這個 Docker vLLM profile。NVIDIA 也要求不要在 WSL 裝 Linux display driver；安裝 Windows driver.

LAN、TLS 與 Windows Firewall

停止、開機恢復與解除安裝

docker compose stop

stop 會保留 named volumes。不要加 --volumes/-v，也不要使用 docker system prune --volumes。

restart: unless-stopped 不能啟動 Docker Desktop。Windows 重新開機後，只有 Docker Desktop 在登入後啟動，容器才會恢復。可開啟 Start Docker Desktop when you sign in，再用真實 reboot + readyz 驗收；這不等於無人登入前恢復。

乾淨 Windows 的完成標準