適合對象：剛接觸 Azure SQL Database 的開發者、需要協作管理資料庫權限的團隊

前言：「我只是要查資料，為什麼要給我 Admin？」

在 Azure SQL Database 的世界裡，常常會遇到這樣的情境：

• 同事 Alice 是團隊的 SQL Entra Admin（系統管理員）
• 你只是要對某個測試資料庫跑幾個 SQL 腳本
• 有人建議「直接把你也設成 Entra Admin 就好」

等等！這個做法雖然快，卻是個大地雷。本篇文章將說明正確做法，讓你在不動到管理員權限的前提下，順利取得資料庫存取能力。

問題核心：SQL Entra Admin 的影響範圍

Azure SQL Server 的 Entra Admin（Azure AD 管理員） 是 整個 SQL Server 實例層級 的最高管理員，每個 SQL Server 只能設定一個（可以是使用者或群組）。

如果把你也加入成為 Entra Admin，會發生什麼事？

1. 原本的 Admin（Alice）的權限會被覆蓋，她可能因此失去管理員身份。
2. 你拿到的是遠超出需求的全站最高權限，違反資安最小授權原則（Principle of Least Privilege）。
3. 未來權限管理會更混亂。

正確解法：請 Entra Admin 幫你在資料庫內建立使用者

最標準、最安全的做法是：請擁有 Admin 的 Alice，在目標資料庫內幫你建立一個 資料庫層級的使用者（Database User），並只賦予你實際需要的權限。

步驟一：Alice 執行 SQL 腳本建立你的帳號

請 Alice 登入 Azure Portal → SQL Server → 目標資料庫（例如：myapp-staging）→ 查詢編輯器（Query Editor），執行以下指令：

-- 步驟 1：為開發者的 Entra ID 帳號建立資料庫使用者
CREATE USER [developer@example.onmicrosoft.com] FROM EXTERNAL PROVIDER;
GO

-- 步驟 2：依需求選擇一種方案賦予權限

-- ✅ 方案 A：唯讀（只查資料，不修改）
ALTER ROLE db_datareader ADD MEMBER [developer@example.onmicrosoft.com];
GO

-- ✅ 方案 B：讀寫（查詢、新增、修改、刪除資料）
ALTER ROLE db_datareader ADD MEMBER [developer@example.onmicrosoft.com];
ALTER ROLE db_datawriter ADD MEMBER [developer@example.onmicrosoft.com];
GO

-- ⚠ 方案 C：資料庫擁有者（可改 Schema、建刪資料表，謹慎使用）
-- ALTER ROLE db_owner ADD MEMBER [developer@example.onmicrosoft.com];
-- GO

提醒：developer@example.onmicrosoft.com 請替換為實際的 Azure Entra ID（Azure AD）帳號 Email。

步驟二：你自己登入資料庫下指令

Alice 執行完畢後，你就可以用自己的帳號操作資料庫，完全不需要 Admin 權限：

1. 前往 Azure Portal → SQL Server → 目標資料庫
2. 點選左側選單的「查詢編輯器 (預覽)」
3. 驗證方式選擇「以您的目前使用者身份繼續」（Entra ID 整合驗證）
4. 登入後，即可在瀏覽器內直接執行 SQL 指令

資料庫角色權限對照表

建議：日常開發大多使用 db_datareader + db_datawriter 的組合，已足夠執行絕大多數的 SQL 操作。db_owner 應僅在確實需要異動資料庫結構時才賦予。

整體架構示意

Azure SQL Server（myapp-sqlsvr）
│
├── Entra Admin：alice@example.com（整個 SQL Server 的管理員）
│
└── myapp-staging 資料庫
    ├── Database User：alice@example.com（繼承 Admin 權限）
    └── Database User：developer@example.com（db_datareader + db_datawriter）
                                              ↑
                                    這才是你應該有的層級！

小結

做法	安全性	對現有 Admin 的影響
把開發者也設為 SQL Entra Admin	危險，權限過大	可能覆蓋現有 Admin
在資料庫內建立使用者並賦予角色	安全，符合最小授權	完全不影響

只要讓 擁有 Admin 的人執行一次 CREATE USER 腳本，你就能以最小、最安全的權限獨立作業，也不會干擾到其他管理員的設定。

這才是 Azure SQL 資料庫多人協作的標準做法。

Tags: Azure SQL Database Entra ID Azure AD 資料庫權限 db_owner db_datareader

如果有需要搶走 Entra Admin 可以使用這個 power shell script:

# set-sql-entra-admin.ps1
# Usage: .\set-sql-entra-admin.ps1 -UserEmail lisa@example.onmicrosoft.com

param(
    [Parameter(Mandatory=$true)]
    [string]$UserEmail
)

$ResourceGroup = "rg-data-stg-jpe-001"
$ServerName    = "your-sqlsvr-name"

Write-Host "Looking up Object ID for: $UserEmail ..."
$ObjectId = az ad user show --id $UserEmail --query id -o tsv 2>&1

if ($LASTEXITCODE -ne 0) {
    Write-Error "User not found: $UserEmail"
    exit 1
}

Write-Host "Setting Entra admin to: $UserEmail (OID: $ObjectId)"
az sql server ad-admin create `
    --resource-group $ResourceGroup `
    --server $ServerName `
    --display-name $UserEmail `
    --object-id $ObjectId

if ($LASTEXITCODE -eq 0) {
    Write-Host "Done! Entra admin is now: $UserEmail"
} else {
    Write-Error "Failed to set Entra admin."
    exit 1
}

標籤：Azure、Container Apps、Go、React、DevOps、部署驗證

前言

你有沒有遇過這種狀況：

1. 修了一個 bug，git push，手動觸發部署。
2. 等了三分鐘，部署顯示「成功」。
3. 開瀏覽器一看…… bug 還在。
4. 狐疑地 docker logs 看一下，發現 container 跑的根本是上個版本的 image。

這就是我們踩過的坑。本文記錄我們如何系統性地解決這個問題——在 build 時把 git commit SHA 嵌入程式，透過 HTTP endpoint 暴露出來，讓部署後的驗證變成一行 curl 指令。

問題根源：三個隱形的快取陷阱

陷阱 1：Go binary 沒有重新編譯

我們的 Dockerfile 長這樣：

# backend/Dockerfile
FROM alpine:3.19
COPY bin/backend /app/backend
ENTRYPOINT ["/app/backend"]

Dockerfile 直接把 預先編譯好的 binary 複製進 image。
如果 go build 沒有在 docker build 之前執行，那麼：

修改 Go 原始碼 → docker build → 推送 image → 部署
                ↑ bin/backend 是舊的！

image 裡永遠是舊的 binary，source code 的修改完全無效。

陷阱 2：React dist/ 沒有重新 build

前端的 Dockerfile 同理：

# frontend/Dockerfile
FROM nginx:alpine
COPY dist/ /usr/share/nginx/html

如果 npm run build 沒有在 docker build 之前執行，dist/ 是舊的，React 改動不生效。

陷阱 3：Docker layer cache

即使你真的重新執行了 go build 和 npm run build，Docker build cache 也可能讓你以為 image 更新了，實際上卻是沿用舊 layer。

解法：嵌入 Git Commit SHA

概念

build 時 ──► git rev-parse --short HEAD ──► 嵌入 binary
                                              └─► /api/version 回傳
                                                    │
部署後 ─────────────────────────────────────────────► curl /api/version
                                                       └─► 比對 commit SHA ✅ 或 ⚠

只要 /api/version 回傳的 commit hash 和 git rev-parse --short HEAD 一致，就能 100% 確認 Azure 上跑的是最新程式碼。

實作步驟

Step 1：在 Go 主程式宣告版本變數

cmd/main.go：

package main

// 這些變數在 go build 時由 -ldflags 注入
// 預設值為 "dev"，方便本地開發
var (
    AppName    = "my-backend"
    Version    = "no-version"
    BuildTime  = "no-build-time"
    CommitHash = "no-commit-hash"
)

為什麼用 var 不用 const？
-ldflags "-X package.VarName=value" 只能注入 var，無法注入 const。

Step 2：註冊 /api/version endpoint

在 cmd/main.go 的路由設定區塊加入：

import (
    "encoding/json"
    "net/http"
    "time"
)

// 放在其他路由旁邊，不需要 auth middleware
mux.HandleFunc("GET /api/version", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]string{
        "app":      AppName,
        "version":  Version,
        "commit":   CommitHash,
        "built_at": BuildTime,
    })
})

本地測試：

go run ./cmd/main.go &
curl http://localhost:8080/api/version
# {"app":"my-backend","built_at":"no-build-time","commit":"no-commit-hash","version":"no-version"}

Step 3：在 deploy 腳本加入 go build -ldflags

deploy 腳本（PowerShell 範例）裡，Build-Backend 函式改成：

function Build-Backend {
    # 1. 取得目前 commit SHA（若不在 git repo 則 fallback）
    $GIT_SHA = git rev-parse --short HEAD 2>$null
    if (-not $GIT_SHA) { $GIT_SHA = "unknown" }

    $BUILD_TIME = Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ"

    Write-Host "  [Backend] 編譯 Go binary (commit=$GIT_SHA)..."

    # 2. 交叉編譯 for Linux/amd64（Azure Container Apps 執行環境）
    $env:GOOS       = "linux"
    $env:GOARCH     = "amd64"
    $env:CGO_ENABLED = "0"

    Push-Location $BACKEND_DIR
    go build `
        -ldflags "-X main.CommitHash=$GIT_SHA -X main.BuildTime=$BUILD_TIME -X main.Version=$IMAGE_TAG" `
        -o "bin\backend" `
        "./cmd/main.go"
    Pop-Location

    Remove-Item Env:\GOOS, Env:\GOARCH, Env:\CGO_ENABLED -ErrorAction SilentlyContinue

    # 3. 接著才 docker build（此時 bin/backend 已是最新）
    Write-Host "  [Backend] 建立 Docker Image ($IMAGE_TAG)..."
    docker build -t "$ACR_LOGIN_SERVER/backend:$IMAGE_TAG" $BACKEND_DIR
    docker push "$ACR_LOGIN_SERVER/backend:$IMAGE_TAG"
}

關鍵順序：go build → docker build → docker push → ACA update，缺一不可。

Step 4：部署後自動驗證版本

同樣在 deploy 腳本，更新 ACA 之後加入：

# 更新 Azure Container Apps
az containerapp update `
    --name $BACKEND_APP_NAME `
    --resource-group $RESOURCE_GROUP `
    --image "$ACR_LOGIN_SERVER/backend:$IMAGE_TAG"

# 等候新 revision 啟動
Write-Host "  ⏳ 等待後端啟動後驗證版本..."
Start-Sleep -Seconds 30

# 驗證
try {
    $deployed = (Invoke-RestMethod "https://your-app.example.com/api/version").commit
    if ($deployed -eq $GIT_SHA) {
        Write-Host "  ✅ 版本驗證通過: commit=$deployed" -ForegroundColor Green
    } else {
        Write-Host "  ⚠  版本不符: deployed=$deployed, local=$GIT_SHA" -ForegroundColor Yellow
        Write-Host "     可能原因：ACA revision 還沒切換完成，稍後再手動確認" -ForegroundColor Yellow
    }
} catch {
    Write-Host "  ⚠  無法連線驗證 /api/version: $_" -ForegroundColor Yellow
}

Step 5：在前端 footer 顯示 commit SHA（選用）

前端也可以在 build 時嵌入 SHA，讓使用者（或開發者）能目視確認前端版本。

deploy.ps1 Build-Frontend 函式：

function Build-Frontend {
    $GIT_SHA = git rev-parse --short HEAD 2>$null
    if (-not $GIT_SHA) { $GIT_SHA = "unknown" }

    # 寫入 .env.production（只在 build 時使用，不會 commit 進 git）
    Set-Content -Path "$FRONTEND_DIR\.env.production" -Value @"
VITE_API_BASE_URL=https://your-app.example.com
VITE_APP_GIT_SHA=$GIT_SHA
VITE_APP_BUILD_TIME=$(Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ")
"@

    Push-Location $FRONTEND_DIR
    npm run build
    Pop-Location

    docker build -t "$ACR_LOGIN_SERVER/frontend:$IMAGE_TAG" $FRONTEND_DIR
    docker push "$ACR_LOGIN_SERVER/frontend:$IMAGE_TAG"
}

vite-env.d.ts（型別宣告）：

interface ImportMeta {
    readonly env: ImportMetaEnv
}

interface ImportMetaEnv {
    readonly VITE_API_BASE_URL: string
    readonly VITE_APP_GIT_SHA?: string
    readonly VITE_APP_BUILD_TIME?: string
}

React footer 元件：

const gitSha = import.meta.env.VITE_APP_GIT_SHA

// 在 footer 顯示
{gitSha && (
    <Text size="xs" c="dimmed">
        v{gitSha}
    </Text>
)}

驗證流程總結

部署完成後，只需一行：

curl https://your-app.example.com/api/version

回傳範例：

{
  "app": "my-backend",
  "version": "dev-20250519153000",
  "commit": "a1b2c3d",
  "built_at": "2025-05-19T15:30:00Z"
}

再對照本地：

git rev-parse --short HEAD
# a1b2c3d  ← 一致 ✅

常見問題

Q：commit=unknown 是什麼意思？

A：git rev-parse --short HEAD 找不到 git repo（例如 CI/CD 環境沒有 clone，或是在 zip 解壓的目錄執行），fallback 值為 "unknown"。
解法：確保 deploy 腳本執行時，工作目錄是 git repository 根目錄，或在 CI pipeline 裡先執行 git fetch --unshallow。

Q：-ldflags 可以注入任何值嗎？

A：只能注入 string 型別的套件層級 var。格式為 -X 完整套件路徑.變數名稱=值。
例如 main.go 裡的 var CommitHash → -X main.CommitHash=abc1234。
如果變數在子套件（如 internal/version），則為 -X github.com/your-org/your-app/internal/version.GitCommit=abc1234。

Q：Docker layer cache 怎麼辦？

A：每次 go build/npm run build 都會改變 bin/backend 或 dist/ 的內容，讓 COPY 指令的 layer hash 改變，Docker 就不會沿用舊 cache。所以只要確保每次 docker build 前都有重新 build，cache 問題自然消除。

Q：前後端版本不一致怎麼辦？

A：目前前後端各自有獨立的 SHA，若同時部署則 SHA 相同；若分開部署則可能不同。可以考慮：

1. 永遠同時部署前後端（最簡單）
2. 在 /api/version 加入 frontend_commit 欄位（由前端在打 API 時傳入）

小結

整套機制只需要三個地方的修改：Go 主程式加幾行、deploy 腳本加 go build -ldflags 和驗證邏輯、前端加一個環境變數。成本很低，但讓部署的可信度大幅提升。

附錄：完整 deploy.ps1 骨架

param(
    [switch]$UpdateOnly,
    [string]$Target = "All"   # Backend | Frontend | All
)

# ── 設定區 ────────────────────────────────────────────────────────────
$RESOURCE_GROUP      = "your-resource-group"
$BACKEND_APP_NAME    = "your-backend-container-app"
$FRONTEND_APP_NAME   = "your-frontend-container-app"
$ACR_LOGIN_SERVER    = "your-acr.azurecr.io"
$PUBLIC_URL          = "https://your-app.example.com"
$BACKEND_DIR         = ".\your-backend"
$FRONTEND_DIR        = ".\your-frontend"

$IMAGE_TAG = "dev-$(Get-Date -Format 'yyyyMMddHHmmss')"
$GIT_SHA   = git rev-parse --short HEAD 2>$null; if (-not $GIT_SHA) { $GIT_SHA = "unknown" }

# ── 函式區 ────────────────────────────────────────────────────────────
function Build-Backend {
    Write-Host "--- 重建並部署 Backend ---"
    Write-Host "  [Backend] 編譯 Go binary (commit=$GIT_SHA)..."

    $env:GOOS = "linux"; $env:GOARCH = "amd64"; $env:CGO_ENABLED = "0"
    Push-Location $BACKEND_DIR
    go build -ldflags "-X main.CommitHash=$GIT_SHA -X main.Version=$IMAGE_TAG" `
             -o "bin\backend" "./cmd/main.go"
    Pop-Location
    Remove-Item Env:\GOOS, Env:\GOARCH, Env:\CGO_ENABLED -ErrorAction SilentlyContinue

    Write-Host "  [Backend] 建立 Docker Image..."
    docker build -t "$ACR_LOGIN_SERVER/backend:$IMAGE_TAG" $BACKEND_DIR
    docker push  "$ACR_LOGIN_SERVER/backend:$IMAGE_TAG"

    Write-Host "  [Backend] 更新 Container App..."
    az containerapp update --name $BACKEND_APP_NAME `
                           --resource-group $RESOURCE_GROUP `
                           --image "$ACR_LOGIN_SERVER/backend:$IMAGE_TAG"

    # 驗證
    Start-Sleep -Seconds 30
    try {
        $deployed = (Invoke-RestMethod "$PUBLIC_URL/api/version").commit
        if ($deployed -eq $GIT_SHA) {
            Write-Host "  ✅ 版本驗證通過: commit=$deployed" -ForegroundColor Green
        } else {
            Write-Host "  ⚠  版本不符: deployed=$deployed, local=$GIT_SHA" -ForegroundColor Yellow
        }
    } catch {
        Write-Host "  ⚠  無法連線驗證: $_" -ForegroundColor Yellow
    }
}

function Build-Frontend {
    Write-Host "--- 重建並部署 Frontend ---"

    Set-Content "$FRONTEND_DIR\.env.production" @"
VITE_API_BASE_URL=$PUBLIC_URL
VITE_APP_GIT_SHA=$GIT_SHA
"@

    Push-Location $FRONTEND_DIR
    npm run build
    Pop-Location

    docker build -t "$ACR_LOGIN_SERVER/frontend:$IMAGE_TAG" $FRONTEND_DIR
    docker push  "$ACR_LOGIN_SERVER/frontend:$IMAGE_TAG"

    az containerapp update --name $FRONTEND_APP_NAME `
                           --resource-group $RESOURCE_GROUP `
                           --image "$ACR_LOGIN_SERVER/frontend:$IMAGE_TAG"

    Write-Host "  ✅ Frontend 部署完成" -ForegroundColor Green
}

# ── 執行 ─────────────────────────────────────────────────────────────
az acr login --name ($ACR_LOGIN_SERVER -replace "\.azurecr\.io","")

if ($Target -in @("Backend","All")) { Build-Backend }
if ($Target -in @("Frontend","All")) { Build-Frontend }

以下為您整理這兩種最常用的操作方法：

方法一：直接從 Microsoft Teams 邀請（最直覺、最推薦）

如果你只是想讓對方加入某個特定的小組聊天、存取檔案或開會，直接在 Teams 軟體中操作最快。

1. 開啟 Teams： 找到你想邀請對方的團隊（Team），點選團隊名稱旁邊的 「…」（更多選項）。
2. 新增成員： 選擇 「新增成員」 (Add member)。
3. 輸入 Email： 輸入該外部人員的完整電子郵件地址（例如 example@gmail.com）。
4. 新增為來賓： 系統會顯示「將 [Email] 新增為來賓」，點擊它，然後按一下 「新增」 (Add)。
5. 完成： 對方的信箱會收到一封邀請函，點擊信中的連結並按照提示驗證，就能加入你的 Teams 團隊了。

注意： 如果系統提示「找不到相符項目」或無法新增，代表你們公司的 IT 管理員把「允許外部來賓」的功能關閉了，這時需要請管理員參考方法二的設定。

方法二：從 Azure 入口網站邀請（IT 管理員適用）

如果你是 Azure 管理員，希望將外部人員正式加入組織的目錄（Microsoft Entra ID）中，方便後續指派多個群組或雲端資源：

1. 登入後台： 登入 Azure Portal 或 Microsoft Entra admin center。
2. 前往使用者： 導覽至 Microsoft Entra ID -> 使用者 (Users) -> 所有使用者 (All users)。
3. 邀請外部使用者： 點選上方的 「新使用者」 (New user)，然後選擇 「邀請外部使用者」 (Invite external user)。
4. 填寫資料：
   • 身分識別： 輸入對方的電子郵件地址（必填）和姓名。
   • 群組和角色（選填）： 你可以直接在這裡將他加入對應的 Teams 背後的 M365 群組。
5. 發送邀請： 填寫完畢後點選 「邀請」 (Invite)。

常見問題與排查

• 為什麼對方收不到信？請請對方檢查「垃圾信件匣（Spam）」，邀請函通常是由 invites@microsoft.com 發出。
• 外部人員需要付費授權嗎？不用。微軟的外部來賓（B2B）通常享有非常寬鬆的免費額度（通常是前 50,000 名每月活躍使用者免費），不需要為他們購買額外的授權。
• 無法新增外部人員？這通常是組織原則限制。管理員需要到 Microsoft Entra ID -> 外部身分識別 (External Identities) -> 外部協同作業設定 (External collaboration settings) 中，將來賓權限調整為 「任何使用者都可以邀請來賓」 或 「成員和指派特定管理員角色的使用者可以邀請來賓」。

看來您已經在 Azure 中成功建立了外部使用者（杜甫），目前停留在該使用者的設定畫面。

如果您已經為這個使用者建立了一個 資源群組 (Resource Group, 簡稱 RG)，並希望讓他能夠存取、管理該 RG，接下來的關鍵步驟是賦予他該資源群組的存取權限（也就是設定 IAM 角色指派）。

請依照以下步驟操作：

下一步：將資源群組 (RG) 的權限指派給該外部使用者

不要在目前這個「指派的角色」畫面操作（這裡是設定全域管理員等目錄角色的）。請改到您建立的 資源群組 頁面進行設定：

1. 尋找您的資源群組： 在 Azure 頂端的搜尋列輸入您建立的資源群組名稱，或是從左側選單點選 「資源群組」 (Resource groups)，並點進該 RG。
2. 進入權限設定： 在該資源群組的左側選單中，點選 「存取控制 (IAM)」 (Access control (IAM))。
3. 新增角色指派： 點選上方的 「+ 新增」 (Add) -> 選擇 「新增角色指派」 (Add role assignment)。
4. 選擇角色 (Role)： 根據您想給對方的權限大小，選擇一個角色（常用的三個基礎角色）：
   • 擁有者 (Owner)： 權限最大，可管理資源並能把權限再分給別人。
   • 參與者 (Contributor)： 可以建立、修改、刪除 RG 內的所有資源（例如建立虛擬機、資料庫），但不能更改權限。(最常指派給外部開發者的角色)
   • 讀取者 (Reader)： 只能看，不能做任何變更。
   選好後點選 「下一步」。
5. 選取成員 (Members)： * 在「將存取權指派給」維持選擇 「使用者、群組或服務主體」。
   • 點選 「+ 選取成員」 (Select members)。
   • 在右側搜尋欄輸入 杜晟甫 或他的 Email，點擊他讓他出現在下方清單中，然後點選 「選取」。
6. 審查並提交： 點選 「檢閱 + 指派」 (Review + assign)，再次確認後點擊按鈕送出。

這樣就完成了嗎？外部使用者該如何登入？

當您完成上述指派後，外部使用者（杜甫）需要透過特定的方式登入才能看到您分給他的資源：

• 接受邀請： 他的 Email 會收到一封來自 Microsoft 的邀請函（如果之前沒收過），他必須點擊信中的 「Accept invitation」 接受加入您的租戶 (Tenant)。
• 專屬登入連結： 外部來賓登入 Azure 時，有時直接進 portal.azure.com 會切換不到您的公司目錄。最保險的做法是提供他帶有您租戶網域名稱或租戶 ID 的專屬連結：https://portal.azure.com/您的公司網域名稱.onmicrosoft.com(例如：https://portal.azure.com/mycompany.onmicrosoft.com)

當他透過該連結登入後，就能在您的 Azure 環境中，看到並操作您指定給他的那個資源群組（RG）了！

沒錯，您的直覺非常準確！這確實是因為您的帳號權限不夠，所以清單中才沒有出現最核心的「擁有者 (Owner)」或「參與者 (Contributor)」選項。

您目前在搜尋列輸入了「擁有者」，系統篩選出來的都是一些特定服務的次級角色（例如：儲存體 Blob 資料擁有者、圖表擁有者等），而不是整個資源群組的基礎管理角色。

要解決這個問題，您有以下兩種解決方案：

方案一：聯絡公司的 Azure 系統管理員（最快）

您需要請你們公司內部權限最高的人（通常是 IT 部門、雲端架構師或當初建立這個 Azure 訂閱的人），幫您進行以下調整：

1. 請管理員幫忙指派： 直接把這張截圖發給管理員，跟他說：「我想把外部人員加入 rg-pr-stg-jpe-001 這個資源群組，但我沒有這個 RG 的 Owner 權限，可以請你幫我把【杜晟甫】加進去，並給他【參與者 (Contributor)】角色嗎？」
2. 請管理員提升您的權限： 或者，請管理員將您在這個資源群組（或整個訂閱）的角色提升為 「使用者存取系統管理員 (User Access Administrator)」 或 「擁有者 (Owner)」，這樣您以後就能自己指派權限給別人了。

方案二：選擇目前選單中「退而求其次」的角色（視對方的需求而定）

如果您現在急著先讓「杜晟甫」能進來看資源，且管理員暫時聯絡不上，您可以先清除搜尋欄的「擁有者」，改搜尋並指派 「讀取者 (Reader)」。

• 讀取者 (Reader) 角色通常不需要太高的管理權限就能指派。
• 缺點： 杜晟甫登入後只能看、不能動（無法建立任何東西）。但至少能先確認他進得來這個資源群組，等您權限拿到後，再幫他升級成參與者即可。

架構圖

                        ┌─────────────────────────────────────────────┐
外部使用者                │  Virtual Network (vnet-ag-example-001)        │
  │                     │  ┌──────────────────────────────────────┐   │
  │ HTTPS               │  │  Application Gateway (agw-example)   │   │
  ▼                     │  │                                      │   │
[app-a.example.com]─────┼──►  Listener: app-a.example.com        │   │
[app-b.example.com]─────┼──►  Listener: app-b.example.com        │   │
                        │  └───────────┬──────────────┬───────────┘   │
                        └─────────────┼──────────────┼───────────────┘
                                      │ VNet Peering │
                        ┌─────────────┼──────────────┼───────────────┐
                        │  Virtual Network (vnet-example-001)         │
                        │             │              │                │
                        │  ┌──────────▼──────────────▼───────────┐   │
                        │  │  Container Apps Environment (CAE)   │   │
                        │  │  (Internal, Consumption)            │   │
                        │  │                                      │   │
                        │  │  ca-app-a  (port 80,  nginx)        │   │
                        │  │  ca-app-b  (port 8080, api)         │   │
                        │  └─────────────────────────────────────┘   │
                        │                                             │
                        └─────────────────────────────────────────────┘

前置條件

一、Private DNS Zone 設定

CAE 建立後，Azure 會自動在同一資源群組建立一個 Private DNS Zone，
格式為：<隨機字串>.<region>.azurecontainerapps.io
例如：abcd1234efgh.japaneast.azurecontainerapps.io

此 DNS Zone 需與 AGW 所在的 VNet 連結，AGW 才能解析 CA 的 FQDN。

az network private-dns link vnet create \
  --resource-group <cae-resource-group> \
  --zone-name "abcd1234efgh.japaneast.azurecontainerapps.io" \
  --name "link-to-agw-vnet" \
  --virtual-network <agw-vnet-id> \
  --registration-enabled false

Wildcard DNS 記錄

Private DNS Zone 中有一筆 Wildcard A 記錄：

此 Wildcard 只能匹配單層子網域（如 ca-app-a.abcd1234efgh...），
無法匹配 ca-app-a.internal.abcd1234efgh...（雙層）。

注意：若使用 --ingress internal 建立 CA，其 FQDN 會包含 .internal.，
不會被 Wildcard 記錄匹配，AGW 將無法解析。
請一律使用 --ingress external（在 Internal CAE 內，external 仍為 VNet 私有，並非真正對外）。

二、建立 Container App

每個應用程式建立時指定 --ingress external，對應的 FQDN 格式為：
<app-name>.<env-domain>

# 建立 App A（前端，nginx on port 80）
az containerapp create \
  --name ca-app-a \
  --resource-group <resource-group> \
  --environment <cae-name> \
  --image <registry>.azurecr.io/app-a:latest \
  --target-port 80 \
  --ingress external \
  --registry-server <registry>.azurecr.io

# 建立 App B（後端 API，on port 8080）
az containerapp create \
  --name ca-app-b \
  --resource-group <resource-group> \
  --environment <cae-name> \
  --image <registry>.azurecr.io/app-b:latest \
  --target-port 8080 \
  --ingress external \
  --registry-server <registry>.azurecr.io

建立後，各 CA 的 FQDN 例如：

• ca-app-a.abcd1234efgh.japaneast.azurecontainerapps.io
• ca-app-b.abcd1234efgh.japaneast.azurecontainerapps.io

允許 HTTP（不強制重新導向 HTTPS）

ACA 預設會將 HTTP 請求 301 重新導向至 HTTPS。
若 AGW 以 HTTP 協定連至 CA（通常如此，因為 TLS 已在 AGW 終止），
需對每個 CA 啟用 --allow-insecure：

az containerapp ingress update \
  --name ca-app-a \
  --resource-group <resource-group> \
  --allow-insecure

三、Application Gateway 設定

同一個 AGW 可以透過多組 Listener + Rule + Backend Pool 路由不同網域。

3-1 Backend Pool

每個應用程式建立一個 Backend Pool，目標為 CA 的 FQDN：

az network application-gateway address-pool create \
  --gateway-name <agw-name> \
  --resource-group <agw-resource-group> \
  --name pool-app-a \
  --servers ca-app-a.abcd1234efgh.japaneast.azurecontainerapps.io

3-2 Backend HTTP Settings

指定協定為 HTTP（因為 TLS 在 AGW 終止）、Port 80，
並固定 Host Header 為 CA 的 FQDN，使 ACA Ingress 能正確路由：

az network application-gateway http-settings create \
  --gateway-name <agw-name> \
  --resource-group <agw-resource-group> \
  --name set-app-a \
  --protocol Http \
  --port 80 \
  --host-name "ca-app-a.abcd1234efgh.japaneast.azurecontainerapps.io"

--host-name 設定會讓 AGW 傳送正確的 Host Header 給 ACA，
若不設定，ACA Ingress 收到的 Host 可能是原始網域（如 app-a.example.com），
導致路由失敗（HTTP 404）。

3-3 HTTPS Listener

每個自訂網域需要一個 Listener：

# 先上傳 SSL 憑證
az network application-gateway ssl-cert create \
  --gateway-name <agw-name> \
  --resource-group <agw-resource-group> \
  --name cert-app-a \
  --cert-file app-a.pfx \
  --cert-password <password>

# 建立 Listener
az network application-gateway http-listener create \
  --gateway-name <agw-name> \
  --resource-group <agw-resource-group> \
  --name lsn-app-a-https \
  --frontend-port <https-port-name> \
  --frontend-ip <frontend-ip-config-name> \
  --host-name "app-a.example.com" \
  --ssl-cert cert-app-a

3-4 Routing Rule

將 Listener 連接至 Backend Pool + HTTP Settings：

az network application-gateway rule create \
  --gateway-name <agw-name> \
  --resource-group <agw-resource-group> \
  --name rule-app-a \
  --http-listener lsn-app-a-https \
  --address-pool pool-app-a \
  --http-settings set-app-a \
  --rule-type Basic \
  --priority 200

重複 3-1 至 3-4 步驟，為 app-b.example.com 建立對應的資源。

四、新增應用程式到現有環境

只需重複以下步驟，無需修改 DNS Zone 或 CAE 設定：

1. 建立 Container App（--ingress external）
2. 啟用 --allow-insecure
3. AGW 新增 Backend Pool（目標為新 CA 的 FQDN）
4. AGW 新增 HTTP Settings（Host Header 設為新 CA 的 FQDN）
5. AGW 新增 Listener（綁定新網域的 SSL 憑證）
6. AGW 新增 Routing Rule（連接上述三者）

五、CA 間互相呼叫

在同一個 Internal CAE 中，Container App 可透過 FQDN 直接呼叫彼此，
不需經過 AGW：

http://ca-app-b.abcd1234efgh.japaneast.azurecontainerapps.io/api/endpoint

例如前端 nginx 的 proxy_pass 設定：

location /api/ {
    proxy_pass http://ca-app-b.abcd1234efgh.japaneast.azurecontainerapps.io/api/;
}

建議將後端 FQDN 透過環境變數注入（例如 BACKEND_URL），
搭配 nginx 的 envsubst 機制於容器啟動時替換：

# nginx.conf.template
location /api/ {
    proxy_pass ${BACKEND_URL}/api/;
}

# Dockerfile：放在 /etc/nginx/templates/ 會在啟動時自動替換
COPY .deploy/nginx.conf.template /etc/nginx/templates/default.conf.template

六、常見問題

AGW Backend Health 顯示 Unknown 或 502

1. DNS 無法解析 CA FQDN：確認 Private DNS Zone 已連結至 AGW 所在的 VNet。
2. 使用了 .internal. FQDN：CA 建立時使用了 --ingress internal，改為 --ingress external。
3. HTTP 重新導向：CA 收到 HTTP 請求回傳 301，對該 CA 執行 az containerapp ingress update --allow-insecure。
4. Host Header 不符：AGW 的 HTTP Settings 未設定 --host-name，導致 ACA Ingress 無法識別目標應用程式。

CA 啟動失敗：open .: no such file or directory

應用程式嘗試讀取相對路徑的檔案（如資料庫 Migration 檔），
但工作目錄與預期不符。
解法：透過環境變數指定絕對路徑，例如：

az containerapp update \
  --name ca-app-b \
  --resource-group <resource-group> \
  --set-env-vars "MIGRATION_SOURCE=file:///app/migrations"

CA 中的環境變數包含 & 字元

在 Windows 環境下使用 az CLI（.cmd 包裝器）時，& 會被 cmd.exe 解析為命令分隔符，
導致參數被截斷。解法：改用 az rest --method PATCH 搭配 JSON 檔案傳遞：

{
  "properties": {
    "template": {
      "containers": [{
        "name": "ca-app-b",
        "env": [
          { "name": "DATABASE_URL", "value": "sqlserver://host?db=mydb&param=value" }
        ]
      }]
    }
  }
}

az rest --method PATCH \
  --url "https://management.azure.com/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.App/containerApps/<name>?api-version=2024-03-01" \
  --body @patch.json

問題現象：連線超時與網路阻斷

當 App Service 發出請求卻一直收到 TLS timeout 或 http_status=0 時，這代表請求根本沒有成功建立連線。這通常有兩個主要原因：

1. IP 白名單限制：宏達科技的伺服器可能設有防火牆，只允許特定的 IP 區段進入，而 Azure App Service 的預設公用輸出 IP 並不在允許清單內。
2. 網路區域限制：位在 Japan East 的測試用虛擬機器（ VM ）可以成功連通，是因為該區域的網路已經與宏達科技建立了信任通道（ 或者是固定的白名單 IP ），但 Taiwan North 的流量則是走公用網路出去，因此被對方防火牆攔截。

關鍵解決策略：虛擬網路整合

要讓 App Service 像虛擬機器一樣擁有受控的網路路徑，必須執行 VNet Integration （ 虛擬網路整合 ）。但當 App Service 與目標 VNet 跨區域時，我們會遇到一些硬性限制。

實戰步驟一：檢查現有網路狀態

首先，我們需要確認 Taiwan North 當地的網路環境。你可以使用 Azure CLI 檢查該區域的 VNet 清單：

az network vnet list –query “[?location==’northtaiwan’].{name:name,rg:resourceGroup}” -o table

在我們的案例中，發現 Taiwan North 只有一個名為 vnet-proxy-agent 的虛擬網路。

實戰步驟二：處理子網域委派問題

若要讓 App Service 加入 VNet ，該子網域（ Subnet ）必須委派給 Microsoft.Web/serverFarms 。

注意：如果該子網域已經有其他虛擬機器在使用，你無法直接更新委派設定。

這時正確的做法是在 vnet-proxy-agent 中，為 App Service 建立一個專屬且乾淨的子網域。

實戰步驟三：跨區域網路串接（ Peering ）

由於宏達科技只認可 Japan East 網路出口的 IP ，我們必須確認 Taiwan North 的 VNet 是否已經與 Japan East 的 Hub VNet 建立 Peering （ 虛擬網路對等互連 ）。

當 Peering 建立後， Taiwan North 的流量就能透過 Azure 骨幹網路導向 Japan East ，再經由那邊的白名單管道存取宏達科技的伺服器。

最終檢查清單

1. 新增專屬子網域：在 Taiwan North 的 VNet 中切分出一塊新的 IP 區段。
2. 設定委派：將該子網域委派給 Web App 使用。
3. 啟用路由設定：在 App Service 的環境變數中，務必設定 WEBSITE_VNET_ROUTE_ALL=1 ，以確保所有對外流量都強制經過 VNet ，而不是走預設的 Azure 公用出口。
4. 重新部署：更改環境變數與網路整合設定後，務必重新啟動或部署應用程式，確保新的網路路徑生效。

結語

解決雲端連線問題時， 視覺化你的網路路徑 非常重要。當公用網路不通時，善用 Azure 的區域性 VNet 與跨區域對等互連技術，能有效解決 IP 阻擋與連線超時的困擾。如果你也遇到類似的跨區域連線問題，不妨檢查一下你的 VNet 委派與路由路徑！

背景

將 Go 後端容器成功推送至 Container Registry 並部署至 Azure Web App 後，雖然映像已可正常拉取，容器卻在啟動階段反覆 crash。從 Log stream 可看到四個連環錯誤，每修一個就出現下一個。本文逐一記錄症狀、根本原因與修復方式。

Bug 1 — 資料庫連線失敗：Login failed for user ''

症狀

{"level":"fatal","msg":"Failed to run database migration",
 "error":"failed to open database: mssql: login error: Login failed for user ''."}

容器一啟動就立即退出，完全沒有執行任何 migration。

根本原因

DATABASE_URL 中設定了 fedauth=ActiveDirectoryMSI，預期使用 Azure AD Managed Identity 認證，但 main.go 中匯入的是基礎 driver：

import _ "github.com/microsoft/go-mssqldb"

這個 driver 只支援 SQL 帳號密碼認證，完全忽略 fedauth= 參數，導致它以空白使用者名稱嘗試登入，SQL Server 因而拒絕連線。

Azure AD 認證有兩種正確做法：

本次採用第二種做法，同時也修改 initDatabasePool 以 ADAL token provider 建立 database/sql 連線：

修復方式

1. 修改連線字串（環境變數）

# 錯誤（會被 base driver 靜默忽略）
DATABASE_URL=sqlserver://db.example.com?database=mydb&fedauth=ActiveDirectoryMSI&...

# 正確
DATABASE_URL=sqlserver://db.example.com?database=mydb&useMsi=true&encrypt=true&TrustServerCertificate=false

2. 修改 Go 程式碼，用 ADAL 取得 MSI token

import (
    "database/sql"
    "net/url"
    mssql "github.com/microsoft/go-mssqldb"
    adal  "github.com/Azure/go-autorest/autorest/adal"
)

func getMSITokenProvider(resource string) func() (string, error) {
    return func() (string, error) {
        spt, err := adal.NewServicePrincipalTokenFromManagedIdentity(resource, nil)
        if err != nil {
            return "", err
        }
        if err = spt.Refresh(); err != nil {
            return "", err
        }
        return spt.Token().AccessToken, nil
    }
}

func initDatabasePool(databaseURL string) (*sqlx.DB, error) {
    u, err := url.Parse(databaseURL)
    if err != nil {
        return nil, err
    }

    useMsi := u.Query().Get("useMsi") == "true"
    if useMsi {
        tokenProvider := getMSITokenProvider("https://database.windows.net/")
        connector, err := mssql.NewAccessTokenConnector(databaseURL, tokenProvider)
        if err != nil {
            return nil, err
        }
        return sqlx.NewDb(sql.OpenDB(connector), "sqlserver"), nil
    }

    return sqlx.Connect("sqlserver", databaseURL)
}

重點： Azure SQL 的 MSI resource URL 為 https://database.windows.net/，結尾斜線不可省略。

Bug 2 — Migration 反覆失敗：Invalid column name 'xxx'

症狀

{"level":"fatal","msg":"Failed to run database migration",
 "error":"migration failed: Invalid column name 'old_column_name'. in line 15: MERGE INTO some_table ..."}

Migration 從第 1 版開始跑，跑到中途某個 seed SQL 時因欄位不存在而失敗，schema_migrations 被標記為 dirty=true，下次啟動仍繼續失敗。

根本原因

部署流程分兩個階段：

1. 在 Azure SQL Query Editor 執行 init.sql（一次性初始化腳本）
2. 後端啟動時由 golang-migrate 執行 migration

init.sql 為了方便，直接包含了所有 migration 的最終狀態（含後期的欄位更名，例如 old_column_name → new_column_name）。執行完 init.sql 後，資料庫已是最新 schema，但 schema_migrations 追蹤表完全是空的。

後端啟動時，golang-migrate 看不到任何已完成的 migration，從第 1 版開始執行。早期的 migration（如 seed 測試資料）引用了舊欄位名稱，而 init.sql 已把那個欄位改名，導致 SQL 執行失敗。

init.sql 執行後：  schema 已是最終狀態，但 schema_migrations = 空
golang-migrate：   以為從未 migrate 過，從頭執行 → 欄位衝突 → dirty

修復方式

短期（已壞掉的環境）： 直接以 SQL 強制將版本設為最新

-- 將版本號改為你的最新 migration 編號
DELETE FROM schema_migrations;
INSERT INTO schema_migrations (version, dirty) VALUES (最新版本號, 0);

長期（防止再次發生）： 在 init.sql 結尾加入 schema_migrations 初始化

-- ============================================================
--  schema_migrations 版本追蹤（與 golang-migrate 同步）
--  init.sql 已套用所有 migration，在此設定版本號，
--  避免後端啟動時重跑 migration 造成欄位衝突。
-- ============================================================
IF OBJECT_ID(N'dbo.schema_migrations', N'U') IS NULL
BEGIN
    CREATE TABLE schema_migrations (
        version BIGINT NOT NULL PRIMARY KEY,
        dirty   BIT    NOT NULL
    );
END

DELETE FROM schema_migrations;
INSERT INTO schema_migrations (version, dirty) VALUES (最新版本號, 0);

版本號維護： 每新增一個 migration 檔案時，記得同步更新 init.sql 裡的版本號。

Bug 3 — 環境變數設定錯誤：invalid mode "xxx"

症狀

{"level":"fatal","msg":"Failed to create External API client",
 "error":"some-client: invalid mode \"prod\", must be 'mock' or 'http'"}

根本原因

部署腳本的預設值沿用了自訂的命名慣例（"prod"），但程式碼實際接受的值只有：

• "http" — 呼叫真實的外部 API
• "mock" — 使用 mock 資料（本地開發用）

部署腳本撰寫時沒有對照程式碼確認合法值，造成一個完全不必要的啟動錯誤。

修復方式

# deploy.ps1 — 修改前
$SOME_CLIENT_MODE = "prod"   # ❌ 程式碼不接受這個值

# deploy.ps1 — 修改後
$SOME_CLIENT_MODE = "http"   # ✅ 正確：正式環境使用真實 API

若已部署，可直接更新 App Settings，不需重新部署映像：

az webapp config appsettings set \
  --name my-backend-app \
  --resource-group my-resource-group \
  --settings SOME_CLIENT_MODE=http

小提醒： az webapp config appsettings set 只更新指定的 key，不會覆蓋其他設定，比 az rest PUT /config/appsettings 安全。

Bug 4 — 冷啟動時資料庫連線瞬斷：Read: EOF

症狀

{"level":"fatal","msg":"Failed to run database migration",
 "error":"failed to open database: Read: EOF"}

容器啟動後約 5–7 秒閃退，exit code 1。每次重啟都重現，沒有任何 retry 訊息。Log 顯示 migration 剛要開始就立刻失敗。

根本原因

Azure Web App for Containers 採用邊車（sidecar）架構：主容器與 MSI sidecar（負責核發 Managed Identity token）幾乎同時啟動。MSI sidecar 需要幾秒鐘才能就緒。

在這個短暫的空窗期（約 1–7 秒），golang-migrate 試圖開啟 TCP 連線，經過 TLS handshake 時遭遇 TCP RST 或連線中斷，因而回傳 Read: EOF。

golang-migrate 的 MigrationUp 不具備內建的 retry 機制——第一次連線失敗就直接回傳錯誤，由呼叫端負責處理。Go 程式在沒有 retry 保護的情況下直接呼叫 logger.Fatal，容器立即退出。

容器啟動
  ├─ MSI sidecar：正在初始化（尚未就緒）
  └─ Go 程式：立刻呼叫 MigrationUp
       └─ golang-migrate 開啟 TCP 連線 → Read: EOF
            └─ main.go 呼叫 logger.Fatal → 容器退出（exit 1）

修復方式

在呼叫 MigrationUp 前，加一層帶有指數退避（exponential backoff）的 retry 包裝：

// retryDB 以指數退避重試資料庫操作，最多重試 maxAttempts 次。
// 等待時間：2s → 4s → 8s → 16s（每次左移一位）
func retryDB(logger *zap.Logger, maxAttempts int, fn func() error) error {
    var err error
    for attempt := 0; attempt < maxAttempts; attempt++ {
        err = fn()
        if err == nil {
            return nil
        }
        if attempt < maxAttempts-1 {
            wait := time.Duration(1<<(attempt+1)) * time.Second
            logger.Warn("Database operation failed, retrying",
                zap.Int("attempt", attempt+1),
                zap.Duration("wait", wait),
                zap.Error(err),
            )
            time.Sleep(wait)
        }
    }
    return err
}

// 使用範例
err = retryDB(logger, 5, func() error {
    return databaseutil.MigrationUp(cfg.MigrationSource, cfg.DatabaseURL, logger)
})
if err != nil {
    logger.Fatal("Failed to run database migration", zap.Error(err))
}

這樣即使第一次連線遇到 EOF，程式會等待 2 秒後重試，最多嘗試 5 次（共可等待 30 秒），足以涵蓋 MSI sidecar 的啟動時間。

驗證

修復後重新建置映像並強制 Azure 拉取新版：

# 強制 Azure 拉取新映像（az webapp restart 只重啟，不重拉映像）
az webapp config container set \
  --name my-backend-app \
  --resource-group my-resource-group \
  --container-image-name "my-registry.azurecr.io/my-backend:latest"

若 retry 有發生，Log 會出現以下 warn 訊息，並最終成功啟動：

{"level":"warn","msg":"Database operation failed, retrying","attempt":1,"wait":"2s","error":"failed to open database: Read: EOF"}
{"level":"info","msg":"Current migration version","version":9,"dirty":false}
{"level":"info","msg":"Database schema is up to date, no migration required"}

若 MSI sidecar 已就緒，第一次連線即可成功，不會有 warn 訊息，容器直接順利啟動。

注意： az webapp restart 會使用本地快取的映像，不會拉取最新版本。若需強制更新，請使用 az webapp config container set 重新設定映像名稱。

偵錯流程回顧

四個 bug 必須依序排除——前一個 bug 掩蓋了後一個：

啟動失敗
  └─ Bug 1: Login failed for user ''
       └─ 修復後 → 繼續啟動
            └─ Bug 2: Invalid column name 'xxx' (migration dirty)
                 └─ 修復後 → 繼續啟動
                      └─ Bug 3: invalid mode "prod"
                           └─ 修復後 → 繼續啟動
                                └─ Bug 4: Read: EOF (MSI sidecar not ready)
                                     └─ 修復後 → 啟動成功 ✅

每次改一個問題就要重新部署或重啟容器，並等待 30–60 秒的 cold start 時間，再從 Log stream 確認下一個錯誤。

取得最新 container log 的方式（Azure CLI）：

# 快速方式（Kudu VFS API，不需解壓縮）
TOKEN=$(az account get-access-token --query accessToken -o tsv)
curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: text/plain" \
  "https://my-backend-app.scm.azurewebsites.net/api/vfs/LogFiles/YYYY_MM_DD_<instanceId>_default_docker.log" \
  | tail -30

# 完整下載方式
az webapp log download \
  --name my-backend-app \
  --resource-group my-resource-group \
  --log-file backend-logs.zip

最終確認

後端正常啟動後，Log 應呈現以下模式：

{"msg":"Database schema is up to date, no migration required"}
{"msg":"External API HTTP client initialized","base_url":"https://api.example.com"}
{"msg":"Application initialization","host":"0.0.0.0","port":"8080"}
{"msg":"Starting listening request","host":"0.0.0.0","port":"8080"}

以 HTTP 呼叫受保護的 API 端點，應回傳 401 Unauthorized（JSON 格式），而非 Azure 的 HTML 錯誤頁面：

curl https://my-backend-app.azurewebsites.net/api/some-protected-endpoint
# 預期回應：{"title":"Unauthorized","status":401,...}

重點整理

問題描述

將 Docker 容器部署至 Azure Web App 時，Log stream 出現以下錯誤：

Pulling image: my-frontend:latest
DockerApiException: Docker API responded with status code=InternalServerError,
  response={"message":"Head \"https://registry-1.docker.io/v2/library/my-frontend/manifests/latest\":
  unauthorized: incorrect username or password"}
Pulling docker image my-frontend:latest failed.
DockerApiException: Docker API responded with status code=NotFound,
  response={"message":"pull access denied for my-frontend, repository does not exist
  or may require 'docker login': denied: requested access to the resource is denied"}
Image pull failed. Defaulting to local copy if present.
Stopping site my-frontend-app because it failed during startup.

明明映像已成功推送至 Azure Container Registry（ACR），Azure 卻跑去 Docker Hub 拉取，導致 Web App 無法啟動。

根本原因

Azure Web App for Containers 透過 linuxFxVersion 這個設定決定要拉取哪個映像。可用以下指令查看：

az webapp show \
  --name my-frontend-app \
  --resource-group my-resource-group \
  --query "siteConfig.linuxFxVersion" -o tsv

問題環境的輸出：

DOCKER|my-frontend:latest

這個值缺少 Registry 前綴，Azure 因此回退至預設的 Docker Hub（registry-1.docker.io）。

正確值應為：

DOCKER|myacr.azurecr.io/my-frontend:latest

為何會產生這個問題？

使用 az webapp create 建立容器 Web App 時，若 --container-image-name 只傳入 IMAGE:TAG（不含 Registry 網址），Azure 會將 linuxFxVersion 設為不含 Registry 前綴的值：

# ❌ 這樣建立後，linuxFxVersion 只有 DOCKER|my-frontend:latest
az webapp create \
  --name my-frontend-app \
  --resource-group my-resource-group \
  --plan my-app-plan \
  --container-image-name "my-frontend:latest" \          # 沒有 registry 前綴
  --container-registry-url "https://myacr.azurecr.io" \
  --container-registry-user myacr \
  --container-registry-password "<password>"

此時，--container-registry-url 只用來設定驗證憑證，不會自動補入映像名稱的 Registry 前綴。

反之，若在 --container-image-name 傳入完整 URL，搭配 --container-registry-url 時又會導致另一個問題：Registry 網址被重複拼接：

DOCKER|myacr.azurecr.io/myacr.azurecr.io/my-frontend:latest  # ❌ 雙重前綴

診斷步驟

1. 確認 linuxFxVersion

az webapp show \
  --name my-frontend-app \
  --resource-group my-resource-group \
  --query "{linuxFxVersion:siteConfig.linuxFxVersion, state:state}" \
  -o table

2. 確認容器設定

az webapp config container show \
  --name my-frontend-app \
  --resource-group my-resource-group \
  --query "[?name=='DOCKER_CUSTOM_IMAGE_NAME']" \
  -o table

3. 確認 App Settings 中的 Docker 憑證

az webapp config appsettings list \
  --name my-frontend-app \
  --resource-group my-resource-group \
  --query "[?name=='DOCKER_REGISTRY_SERVER_URL' || name=='DOCKER_REGISTRY_SERVER_USERNAME' || name=='DOCKER_REGISTRY_SERVER_PASSWORD']" \
  -o table

若 DOCKER_REGISTRY_SERVER_PASSWORD 顯示為 null，即是憑證遺失的警訊。

修復方法

方法一：立即修復（手動執行）

Step 1：用完整 ACR URL 更新容器設定

ACR_PASSWORD=$(az acr credential show --name myacr --query "passwords[0].value" -o tsv)

az webapp config container set \
  --name my-frontend-app \
  --resource-group my-resource-group \
  --container-image-name "myacr.azurecr.io/my-frontend:latest" \
  --container-registry-url "https://myacr.azurecr.io" \
  --container-registry-user myacr \
  --container-registry-password "$ACR_PASSWORD"

執行後確認 linuxFxVersion 已變為 DOCKER|myacr.azurecr.io/my-frontend:latest。

Step 2：確保 App Settings 中的密碼不為 null

az webapp config container set 在某些情況下 CLI 顯示密碼為 null（實際上可能已儲存，但保險起見建議明確寫入）。使用 az rest 繞過 Windows 的 cmd.exe & 字元解析問題：

# PowerShell
$sub = "<your-subscription-id>"
$rg  = "my-resource-group"
$app = "my-frontend-app"
$ACR_PASSWORD = (az acr credential show --name myacr --query "passwords[0].value" -o tsv)

# 取出現有 App Settings 再合併
$existing = az webapp config appsettings list --name $app --resource-group $rg | ConvertFrom-Json
$props = @{}
foreach ($s in $existing) {
    if ($s.value -ne $null) { $props[$s.name] = $s.value }
}

# 覆寫 Docker 相關設定
$props["DOCKER_REGISTRY_SERVER_URL"]      = "https://myacr.azurecr.io"
$props["DOCKER_REGISTRY_SERVER_USERNAME"] = "myacr"
$props["DOCKER_REGISTRY_SERVER_PASSWORD"] = $ACR_PASSWORD
$props["DOCKER_CUSTOM_IMAGE_NAME"]        = "myacr.azurecr.io/my-frontend:latest"

$tmpFile = "$env:TEMP\appsettings_fix.json"
@{ properties = $props } | ConvertTo-Json -Depth 3 | Set-Content -Path $tmpFile -Encoding UTF8

az rest --method PUT `
  --url "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.Web/sites/$app/config/appsettings?api-version=2022-03-01" `
  --body "@$tmpFile"

Remove-Item $tmpFile

Step 3：重啟 Web App

az webapp restart --name my-frontend-app --resource-group my-resource-group

等待 30–60 秒（Docker 容器冷啟動需要時間），再測試 HTTP 回應：

curl -o /dev/null -s -w "%{http_code}" https://my-frontend-app.azurewebsites.net
# 預期：200

方法二：從根本修正 CI/CD 部署腳本

在 az webapp create 之後，立即執行 az webapp config container set 以確保 linuxFxVersion 包含完整 Registry 路徑：

# PowerShell deploy script 範例

$ACR          = "myacr"
$ACR_SERVER   = "myacr.azurecr.io"
$ACR_PASSWORD = (az acr credential show --name $ACR --query "passwords[0].value" -o tsv)
$IMAGE        = "my-frontend"
$TAG          = "latest"
$APP          = "my-frontend-app"
$RG           = "my-resource-group"
$PLAN         = "my-app-plan"

# Step 1: 建立 Web App（用短名稱避免雙重前綴問題）
az webapp create `
  --name $APP `
  --resource-group $RG `
  --plan $PLAN `
  --container-image-name "${IMAGE}:${TAG}" `
  --container-registry-url "https://$ACR_SERVER" `
  --container-registry-user $ACR `
  --container-registry-password $ACR_PASSWORD

# Step 2: 立即修正 linuxFxVersion，補入完整 Registry 前綴
az webapp config container set `
  --name $APP `
  --resource-group $RG `
  --container-image-name "$ACR_SERVER/${IMAGE}:${TAG}" `
  --container-registry-url "https://$ACR_SERVER" `
  --container-registry-user $ACR `
  --container-registry-password $ACR_PASSWORD | Out-Null

# Step 3: 透過 az rest 確保 App Settings 中密碼明確寫入
$props = @{
    DOCKER_REGISTRY_SERVER_URL      = "https://$ACR_SERVER"
    DOCKER_REGISTRY_SERVER_USERNAME = $ACR
    DOCKER_REGISTRY_SERVER_PASSWORD = $ACR_PASSWORD
    DOCKER_CUSTOM_IMAGE_NAME        = "$ACR_SERVER/${IMAGE}:${TAG}"
    WEBSITES_PORT                   = "80"
}
$tmpFile = "$env:TEMP\appsettings.json"
@{ properties = $props } | ConvertTo-Json -Depth 3 | Set-Content $tmpFile -Encoding UTF8
az rest --method PUT `
  --url "https://management.azure.com/subscriptions/<sub-id>/resourceGroups/$RG/providers/Microsoft.Web/sites/$APP/config/appsettings?api-version=2022-03-01" `
  --body "@$tmpFile"
Remove-Item $tmpFile

重點整理

關鍵原則：
linuxFxVersion（即容器設定 DOCKER_CUSTOM_IMAGE_NAME）是 Azure Web App 決定拉取哪個映像的最終依據，
其優先級高於 App Settings 中的 DOCKER_CUSTOM_IMAGE_NAME。
因此，務必使用 az webapp config container set 確保此值包含完整的 Registry URL。

常見陷阱

1. az webapp create + 短映像名稱 → linuxFxVersion 無 Registry 前綴 → 拉 Docker Hub
2. az webapp create + 完整 URL + --container-registry-url → linuxFxVersion Registry 前綴重複
3. az webapp config container set 後 CLI 顯示密碼為 null → 實際可能空值；建議以 az rest PUT /config/appsettings 補強
4. Windows 上 DATABASE_URL 含 & → az 呼叫走 cmd.exe，& 被解析為命令分隔符 → 改用 az rest 搭配 JSON 檔案

參考資料

• Azure App Service — Configure a custom container
• az webapp config container set — Azure CLI
• az rest — Azure CLI
• Troubleshoot Docker container pull failures in Azure App Service

適用情境：需要將 Azure SQL Server 的 Microsoft Entra 系統管理員（前稱 Azure AD 管理員）移交給其他人員時。

前置條件

• 已安裝 Azure CLI
• 具備目標訂用帳戶的 Owner 或 Contributor 權限
• 已執行 az login 並切換至正確的訂用帳戶

az login
az account set --subscription "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

環境資訊

步驟一：查詢新管理員的 Object ID

在設定 Entra 管理員之前，必須先取得目標使用者在 Entra ID 中的 Object ID。

az ad user show --id newadmin@example.onmicrosoft.com --query id -o tsv

範例輸出：

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee：設定新的 Entra 系統管理員

使用 az sql server ad-admin create 指令覆蓋現有的 Entra 管理員設定。

az sql server ad-admin create `
  --resource-group rg-example-prod-001 `
  --server demo-sqlsvr `
  --display-name newadmin@example.onmicrosoft.com `
  --object-id aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

成功後回傳範例：

json

{
  "administratorType": "ActiveDirectory",
  "azureAdOnlyAuthentication": true,
  "login": "newadmin@example.onmicrosoft.com",
  "sid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "tenantId": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj"
}

使用批次腳本（推薦）

為方便日後移交，可使用以下 PowerShell 腳本快速切換管理員：

set-sql-entra-admin.ps1

param(
    [Parameter(Mandatory=$true)]
    [string]$UserEmail
)

$ResourceGroup = "rg-example-prod-001"
$ServerName    = "demo-sqlsvr"

Write-Host "Looking up Object ID for: $UserEmail ..."
$ObjectId = az ad user show --id $UserEmail --query id -o tsv

if ($LASTEXITCODE -ne 0) {
    Write-Error "找不到使用者：$UserEmail"
    exit 1
}

Write-Host "設定 Entra 管理員為：$UserEmail (OID: $ObjectId)"
az sql server ad-admin create `
    --resource-group $ResourceGroup `
    --server $ServerName `
    --display-name $UserEmail `
    --object-id $ObjectId

if ($LASTEXITCODE -eq 0) {
    Write-Host "完成！Entra 管理員現為：$UserEmail"
} else {
    Write-Error "設定失敗，請確認帳號與權限。"
    exit 1
}

執行方式：

# 指派給舊管理員
.\set-sql-entra-admin.ps1 -UserEmail oldadmin@example.onmicrosoft.com

# 指派給新管理員
.\set-sql-entra-admin.ps1 -UserEmail newadmin@example.onmicrosoft.com

若遇到執行原則限制，請先執行：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

驗證結果

執行以下指令確認管理員已成功更新：

az sql server ad-admin list `
  --resource-group rg-example-prod-001 `
  --server demo-sqlsvr `
  -o table

常見問題

Q：執行後提示權限不足？

確認執行帳號在該訂用帳戶具備 Contributor 以上角色，且在 Entra ID 中具備讀取使用者資訊的權限。

Q：找不到使用者（User not found）？

請確認該帳號確實存在於同一個 Entra 租用戶（Tenant）中，可用以下指令確認：

az ad user list --filter "mail eq 'oldadmin@example.onmicrosoft.com'" -o table

Q：變更後原管理員立即失去存取權嗎？

是的，Entra 管理員每個伺服器只能設定一位，覆蓋後舊管理員將立即失去 Entra 管理員身份。

參考資料

• Microsoft 文件：設定 Azure SQL 的 Azure AD 管理員
• az sql server ad-admin 指令參考

要實現這個功能，你需要完成三個步驟：啟用身份識別、資料庫授權、以及修改 Python 連線字串。

第一步：在 Azure 資源上啟用受控識別

在你運行 Python 程式碼的資源（例如 Azure VM, App Service 或 Function）的頁面：

1. 點選左側選單的 「身分識別」(Identity)。
2. 在 「系統指派」 頁籤下，將狀態改為 「開啟」 並儲存。
3. 系統會產生一個 物件識別碼 (Object ID)，請記住這個資源的名稱。

上面的截圖來看，你目前是在 「Azure SQL Database」 的介面裡。

受控識別（Managed Identity）不是在資料庫（Database）上開啟的，而是在「跑 Python 程式碼的那個東西」上面開啟的。

請想像：

• SQL Database 是「銀行」。
• 你的 Python 程式碼（跑在 VM、App Service 或 Function 上）是「進去辦事的人」。

你現在需要在「辦事的人」身上發一張身分證（啟用受控識別），然後再去「銀行」告訴櫃檯（資料庫）說：「看到拿這張身分證的人就讓他進來」。

接下來你該怎麼做：

1. 找到「發身分證」的地方

請在 Azure Portal 最上方的搜尋框，搜尋你跑 Python 程式碼的資源名稱。

• 如果你是在 Azure VM 跑：去該 VM 的頁面，找左側選單的「身分識別」。
• 如果你是在 App Service 跑：去該 App Service 的頁面，找左側選單的「身分識別」。
• 如果你是在 Azure Function 跑：去該 Function 的頁面，找左側選單的「身分識別」。

進入後，你就會看到我上一個回覆說的「系統指派」狀態，將它改為 「開啟」。

2. 在資料庫（也就是你截圖的這個地方）授權

當你在上面的資源開啟受控識別後，回到你截圖的這個 SQL Database 介面：

1. 點擊左側選單的 「查詢編輯器 (預覽)」(Query editor)。
2. 用你的管理員帳號登入。
3. 執行以下指令（假設你的 VM 或 App Service 名字叫 my-python-app）：

SQL

CREATE USER [my-python-app] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-python-app];
ALTER ROLE db_datawriter ADD MEMBER [my-python-app];

補充：截圖中的發現

從你的截圖中可以看到，在 「安全性」 區塊下，有一行：

• 系統指派的身分識別：已啟用

這指的是 「SQL Server 自己」 的身分，通常是用來讓 SQL 去讀取 Key Vault 等其他資源用的。這不是給你的 Python 程式連線用的。 總結： 請去尋找你運行 Python 的那個 Azure 資源（VM / App Service），在那裡開啟身分識別。

了解更多: 利用客戶自控金鑰支援透明資料加密的受控識別
https://learn.microsoft.com/zh-tw/azure/azure-sql/database/transparent-data-encryption-byok-identity?view=azuresql&WT.mc_id=Portal-SqlAzureExtension

▋ 數據安全的大門與那把遺失的鑰匙

在數位世界裡，我們使用「透明資料加密」技術，這就像是在資料庫門口裝了一道自動感應門，資料進出時會自動上鎖或解鎖。傳統做法是讓雲端平台幫你管理這把鑰匙，這對大多數人來說很方便。然而，對於需要極高掌控權的管理者來說，這就像是把身家財產的進出權限完全交給外人，一旦發生資安爭議，你可能無法第一時間主動切換鎖頭。

▋ 拿回屬於你的主權鑰匙

為了解決這個信任缺口，現在有一種「客戶管理金鑰」的機制。簡單來說，這就是讓你自備鎖頭與鑰匙。當你的資料庫要啟動加密功能時，系統不再使用預設的鑰匙，而是去你的私密保險庫中讀取你指定的「身份證明」。這確保了只有經過你授權的特定身份，才能啟動那把開啟資料的鑰匙。

▋ 建立你的專屬數位防線

如果你希望全面掌控數據的安全命運，可以嘗試以下步驟：

• 在雲端環境中建立一個專屬的「身份識別」，這就像是為你的資料庫申請一張專屬的身分證。
• 設定嚴格的存取權限，確保只有這個「身份」能接觸到你的加密鑰匙。
• 定期檢查這把鑰匙的使用紀錄，確保沒有任何未經授權的嘗試。

第二步：在 SQL Database 中授權

SQL Server 預設不認識這個受控識別，你必須進到資料庫裡幫它「開門」：

1. 使用 Active Directory 管理員 帳號登入 SQL Database（可用 Azure Portal 的 Query Editor）。
2. 執行以下 SQL 指令（將 <identity-name> 替換為你的 Azure 資源名稱）：

SQL

-- 建立資料庫使用者
CREATE USER [<identity-name>] FROM EXTERNAL PROVIDER;

-- 授予讀取/寫入權限 (視需求調整角色)
ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];

如果你是在 Azure App Service 或 Azure VM 上啟用的受控識別，該「顯示名稱」通常就是你的 資源名稱。

• 錯誤做法：CREATE USER [1234-1234-1234-1234-1234] ... (不可使用 ID)
• 正確做法：CREATE USER [你的AppService名稱] FROM EXTERNAL PROVIDER;

如果你不確定名稱，或者名稱有特殊字元，你可以直接使用 SID (這對應到你看到的物件識別碼) 來建立，這樣最準確：

-- 請將 '1234-1234-1234-1234-1234' 替換為你在身分識別頁面看到的 Object ID
CREATE USER [MyManagedIdentityName] 
WITH OBJECT_ID = '1234-1234-1234-1234-1234';

-- 接著再授權
ALTER ROLE db_datareader ADD MEMBER [MyManagedIdentityName];

第三步：修改 Python 連線字串

使用受控識別時，連線字串不需要 UID 和 PWD，而是改用 Authentication=ActiveDirectoryMsi。

Python

import pyodbc

# 設定基礎參數
server = 'your-server.database.windows.net'
database = 'your-database'
driver = '{ODBC Driver 18 for SQL Server}'

# 系統指派受控識別的連線字串
connection_string = (
    f"Driver={driver};"
    f"Server={server};"
    f"Database={database};"
    "Authentication=ActiveDirectoryMsi;"  # 關鍵設定
    "Encrypt=yes;"
    "TrustServerCertificate=no;"
    "Connection Timeout=30;"
)

def connect_and_query():
    try:
        print(f"Connecting to {server} using Managed Identity...")
        conn = pyodbc.connect(connection_string)
        print("連線成功！")
        return conn
    except Exception as e:
        print(f"連線失敗: {e}")

# 執行連線
conn = connect_and_query()

關鍵筆記：

• 環境限制：Authentication=ActiveDirectoryMsi 只能在 Azure 環境內 運行（例如在 Azure VM 上跑）。如果你在自己的電腦（在地端）跑這段程式碼會報錯，因為地端環境沒有 Managed Identity 憑證。
• 驅動程式：請確保你的環境中安裝了 ODBC Driver 17 或 18，舊版驅動程式可能不支援 ActiveDirectoryMsi 參數。
• 優點：即使你更換了密碼，或者這台機器被刪除了，都不需要去改程式碼，這就是「無密碼連線」的強大之處。

執行以下 SQL 指令時遇到 Error:

A connection was successfully established with the server, but then an error occurred during the pre-login handshake. (provider: TCP Provider, error: 0 – An existing connection was forcibly closed by the remote host.)

Failed to execute the query

這個錯誤「An existing connection was forcibly closed by the remote host」發生在 Pre-login handshake (預先登錄握手) 階段，通常不是程式碼邏輯問題，而是 網路層 或 防火牆 的攔截。

這代表你的 Python 程式已經碰到了 SQL Server 的大門，但 SQL Server 因為某些安全規則直接把連線「踢掉」了。

請檢查以下三個最常見的原因：

1. Azure SQL 防火牆未允許你的 IP

這是最常見的原因。即便你使用受控識別，網路還是要通。

• 如果你在 Azure 資源內執行：請到 SQL Server 的「網路 (Networking)」設定，確保 「允許 Azure 服務和資源存取此伺服器 (Allow Azure services and resources to access this server)」 有被勾選。
• 如果你在公司內網執行：請確認你的公用 IP 已加入 SQL Server 的防火牆白名單。

2. 強制使用 TLS 1.2

Azure SQL 預設要求 TLS 1.2。如果你的 Python 環境或 ODBC 驅動程式版本太舊，握手時會因為加密協定不匹配而被中斷。

• 解決方法：確保你的連線字串中有 Encrypt=yes;（你已經有了）。
• 檢查驅動：確認你安裝的是 ODBC Driver 18 for SQL Server。注意：Driver 18 預設會強制驗證證書，如果你沒有設定憑證，請試著在連線字串加上 TrustServerCertificate=yes; 測試看看。

3. ODBC Driver 18 的「預設加密」改變

如果你是從 Driver 17 升級到 18，Driver 18 的預設行為變更了。請嘗試將連線字串稍微修改如下：

Python

connection_string = (
    f"DRIVER={driver};"
    f"SERVER={server};"
    f"DATABASE={database};"
    "Authentication=ActiveDirectoryMsi;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # 先暫時改成 yes 測試是否為證書握手失敗
    "Connection Timeout=30;"
)

關鍵排除步驟（Debug Check）

1. 測試工具連線：你在 Azure Portal 上的 「查詢編輯器 (Query Editor)」 現在能正常進去嗎？
   • 如果連 Query Editor 都進不去，那是資料庫本身的網路/防火牆設定問題。
2. 確認受控識別是否已成功建立 User：
   • 你剛才在嘗試 CREATE USER 時失敗了，這代表受控識別的身分還沒進到資料庫。
   • 重要：如果 CREATE USER 沒成功，Authentication=ActiveDirectoryMsi 就絕對連不上。

目前的卡點建議：

先解決 CREATE USER 的問題。請確認你是用 「Microsoft Entra 管理員」 的帳號登入 Query Editor。只有管理員有權限執行 FROM EXTERNAL PROVIDER 的指令。

在 Windows 虛擬機器（VM）環境中使用 Zed 編輯器時，由於 Zed 依賴 GPU 進行介面渲染，而 VM 通常使用模擬顯卡，會導致編輯器跳出警告或效能不佳。

要關閉這個警告並強制編輯器執行，你可以透過設定 環境變數 來達成。

解決方法：設定環境變數

請在 Windows 系統中新增以下環境變數，這會告訴 Zed 忽略 GPU 限制並允許使用模擬驅動：

1. 按下鍵盤的 Win + R，輸入 sysdm.cpl 並按回車。
2. 切換到 進階 頁籤，點擊下方的 環境變數。
3. 在 使用者變數 區塊中，點擊 新增：
   • 變數名稱：ZED_ALLOW_EMULATED_GPU
   • 變數值：1
4. 點擊 確定 儲存。
5. 重新啟動 Zed（或重新登入 Windows）使設定生效。

進階優化建議

如果在 VM 中運行依然感覺非常延遲，可以嘗試以下操作來提升流暢度：

• 啟用硬體加速： 如果你使用的是 VMware，請進入虛擬機設定，在 顯示器（Display） 項目勾選 加速 3D 圖形（Accelerate 3D graphics）。
• 調整電源計畫： 在 VM 內的 Windows 設定中，將電源模式調整為 高效能。
• 使用 CLI 啟動： 雖然環境變數已設定，但在某些情況下透過終端機啟動可以強制套用變數：PowerShell$env:ZED_ALLOW_EMULATED_GPU=1 zed .

[!TIP]

由於 Zed 使用 DirectX 11 進行渲染，若 VM 的虛擬顯卡完全不支援 DirectX 11，即便忽略警告，畫面仍可能出現閃爍或空白。在這種極端情況下，建議檢查 VM 軟體是否已更新到最新版本，並安裝對應的 Guest Additions 或 VMware Tools。其介面渲染直接使用 GPU 完成。在 VM 環境中，由於缺乏實體顯卡支援，系統會退而求其次使用 CPU 來模擬顯卡運算，這會消耗大量處理器資源並導致畫面撕裂。設定 ZED_ALLOW_EMULATED_GPU=1 的本質是告訴 Zed：「我知曉這會造成效能損耗，但請繼續執行」。