現象描述：
點擊切換為深色模式（或由深色轉淺色）的瞬間，頁面上的超連結（<a>）或文字區塊背景會先短暫閃出一塊白色（#ffffff），接著在約 0.5 秒的時間內才緩慢漸變過渡為黑色（#000000 / #16181d）。

這並非 JavaScript 執行延遲，而是 CSS 過渡動畫（Transitions）與瀏覽器補間運算相互作用產生的典型副作用。本文將完整記錄該問題的根本成因與最佳實踐解法。

一、問題根本原因分析

這個問題主要由兩個 CSS 特性疊加造成：

1. 原生主題的 transition: all 0.5s ease; 廣泛繼承

在許多 WordPress 主題（包括 Gutenshop）的樣式表（style.css）中，為了讓按鈕與部分互動元素具備平滑動畫，常常撰寫了如下規則：

transition: all 0.5s ease;

當使用 JavaScript 動態在 <body> 或 <html> 上新增/切換 .theme-dark 類別時，瀏覽器會監測到樣式變更。由於設定了 transition: all，頁面上所有繼承或套用了該規則的屬性（包含 background-color、color、border-color）都會進入 0.5 秒的漸變過渡狀態。

2. 顏色插值運算（Color Interpolation）與透明背景缺失

• 預設情況下，常規文字超連結 <a> 的 background-color 通常是 transparent（透明）或繼承父容器。
• 當深淺模式切換時，如果某些元件或祖先元素設定了背景色變換，瀏覽器在計算 transparent（實質為 rgba(0,0,0,0) 或 rgba(255,255,255,0)）至目標色（如 #16181d）的中間過渡幀時，容易將未明定背景的元素以白色底（#fff）作為基底進行過渡插值。
• 結果就形成了：超連結背景突然變白，並耗時 0.5 秒慢慢過渡到黑色的突兀閃爍。

3. 首次造訪無 Cookie 時，未即時寫入使用者系統偏好

• 若使用者尚未手動點擊切換過，瀏覽器中就沒有 gutenshop_theme 的 Cookie。
• 每次重新整理或跳轉頁面時，若僅依賴延遲載入的腳本偵測 prefers-color-scheme: dark，頁面在 HTML 解析初期無法從 Cookie 取得狀態，導致從預設的淺色（白）重新被腳本動態判定改為深色（黑），觸發二次切換閃爍。
• 最佳解法： 在初次載入（Page Load）偵測到無 Cookie 時，立即將使用者的 System Theme 寫入 Cookie，並在 <head> 的 Anti-flicker 行內腳本同步寫入，確保下一個畫面與未來所有子頁面在 DOM 渲染前就能以 Cookie 命中深色模式，徹底杜絕閃爍。

二、解決方案

要徹底杜絕這個現象，最佳做法是「雙管齊下」：

1. 切換當下全域靜音過渡（Disable Transitions during Toggle）：切換主題時暫時鎖死所有 transition，讓深淺色瞬間套用，不觸發任何補間動畫。
2. 約束超連結的 transition 範圍：明確鎖定 <a> 的背景為透明，並限制僅有 color（文字顏色）允許 hover 漸變，禁止背景參與 transition。

步驟 1：在 CSS 中加入停用過渡與連結約束規則

在你的獨立深色模式樣式檔（如 css/dark-theme.css）加入以下規則：

/* ==========================================================================
   1. 暫停過渡工具類：切換主題瞬間徹底消除 0.5 秒的顏色補間閃爍
   ========================================================================== */
.disable-transitions,
.disable-transitions *,
.disable-transitions *::before,
.disable-transitions *::after {
  -webkit-transition: none !important;
  -moz-transition: none !important;
  -o-transition: none !important;
  -ms-transition: none !important;
  transition: none !important;
}

/* ==========================================================================
   2. 超連結背景與過渡約束：
      明確限制常規連結背景為透明，且過渡僅限文字顏色 (color)，防止背景補間
   ========================================================================== */
a:not(.button):not(.added_to_cart):not(.theme-switch-link) {
  background-color: transparent;
  transition-property: color;
  transition-duration: 0.2s;
}

/* 深色模式下連結文字配色 */
body.theme-dark a {
  color: #60a5fa;
}

body.theme-dark a:hover,
body.theme-dark a:focus {
  color: #93c5fd;
}

步驟 2：在切換 JavaScript 中包裝過渡阻斷邏輯

在處理主題切換的 JavaScript（如 js/theme-switch.js）的 applyTheme 函數中：

• 切換前先在根節點 <html> 加上 .disable-transitions。
• 透過存取 window.getComputedStyle().opacity 強制觸發瀏覽器重繪（Force Reflow），保證類別立即生效且不會被瀏覽器批次合併渲染。
• 完成類別切換後，使用 requestAnimationFrame 在下一個畫面幀將 .disable-transitions 移除，確保按鈕後續正常的滑鼠 hover 動畫不受影響。

/**
 * 套用深淺主題類別
 * @param {string} theme 'dark' 或 'light'
 */
function applyTheme(theme) {
  var isDark = (theme === 'dark');

  // 1. 立即停止當前所有 CSS 過渡動畫，防止 0.5s 白黑殘影閃爍
  document.documentElement.classList.add('disable-transitions');

  // 2. 切換深淺模式類別
  document.body.classList.toggle('theme-dark', isDark);
  document.body.classList.toggle('theme-light', !isDark);
  document.documentElement.classList.toggle('theme-dark', isDark);
  document.documentElement.classList.toggle('theme-light', !isDark);

  // 3. 強制觸發重繪 (Reflow)，確保樣式變更在 transition 被關閉的狀態下生效
  window.getComputedStyle(document.documentElement).opacity;

  // 4. 下一個渲染週期恢復原本的 CSS 過渡效果（按鈕 hover 等仍維持流暢動畫）
  requestAnimationFrame(function () {
    document.documentElement.classList.remove('disable-transitions');
  });

  // 5. 同步切換按鈕的 aria 屬性與提示文字
  var links = document.querySelectorAll('.theme-switch-link');
  links.forEach(function (el) {
    el.title = isDark ? '切換至淺色模式' : '切換至深色模式';
    el.setAttribute('aria-pressed', isDark ? 'true' : 'false');
  });
}

/**
 * 頁面初始化：當無 Cookie 時，立即將使用者的系統主題 (OS Theme) 寫入 Cookie
 */
function init() {
  var saved = getCookie(COOKIE_NAME);
  var currentTheme;

  if (saved === 'dark' || saved === 'light') {
    currentTheme = saved;
  } else {
    // 首次造訪無 cookie：抓取系統主題並立即寫入 cookie，避免二次載入或跳轉時重複判斷而閃爍
    currentTheme = getSystemTheme();
    setCookie(COOKIE_NAME, currentTheme, COOKIE_DAYS);
  }

  var isDark = (currentTheme === 'dark');
  applyTheme(currentTheme);
  injectDesktopToggle(isDark);
  injectMobileToggle(isDark);
  document.addEventListener('click', handleClick);
  watchOSTheme();
}

步驟 3：在 Head 注入極速防閃爍腳本並更新版本號

在 functions.php 的 wp_enqueue_scripts 中：

1. 注入極速 Inline 腳本：若初次無 Cookie，亦立即將系統主題寫入 Cookie 並先加上 theme-dark 類別，在 HTML 剛載入時就完成判定。
2. 推進樣式表與腳本版本號（例如 1.0.1 / 1.0.3），避免瀏覽器快取舊檔案：

// functions.php
wp_register_style( 
    'gutenshop-dark-theme', 
    get_template_directory_uri() . '/css/dark-theme.css', 
    array( 'gutenshop-style' ), 
    '1.0.1' 
);
wp_enqueue_style( 'gutenshop-dark-theme' );

// 防閃爍腳本：搶先注入 <html>，若無 cookie 則同步寫入系統主題 cookie
$anti_flicker_js = "(function(){try{var m=document.cookie.match(/(^|;\\s*)gutenshop_theme=([^;]+)/);var t=m?decodeURIComponent(m[2]):null;var d=(window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches)?'dark':'light';var theme=t||d;if(!t){var exp=new Date();exp.setTime(exp.getTime()+(365*24*60*60*1000));document.cookie='gutenshop_theme='+encodeURIComponent(d)+'; expires='+exp.toUTCString()+'; path=/; SameSite=Lax';}if(theme==='dark'){document.documentElement.classList.add('theme-dark');}}catch(e){}})();";
wp_add_inline_script( 'gutenshop-navigation', $anti_flicker_js, 'before' );

wp_register_script( 
    'gutenshop-theme-switch', 
    get_template_directory_uri() . '/js/theme-switch.js', 
    array( 'gutenshop-custom-js-jquery' ), 
    '1.0.3', 
    true 
);
wp_enqueue_script( 'gutenshop-theme-switch' );

三、成果驗證

套用此修改後：

1. 點擊深淺模式切換按鈕：背景與所有文字立刻無縫切換，完全不再出現 0.5 秒的白色閃爍與變色殘影。
2. 一般互動不受影響：一般的按鈕 hover、下拉選單滑動等原有動畫依然正常流暢運作。
3. 效能優化：利用強制 Reflow 配合 requestAnimationFrame，不會造成頁面重載或多餘運算開銷。

在現代網頁設計中，深色模式（Dark Mode / Dark Theme）已經是用戶體驗（UX）的基本標配。除了降低在暗處閱讀時的眼部疲勞，也能延長 OLED 螢幕的電池續航力。

本篇技術筆記以開源主題 Guntenbee 為例，完整記錄如何架構一個具備「系統主題偏好自動偵測 + Cookie 記憶 + 切換按鈕 + 防閃爍 (Anti-flicker)」的深色模式方案。同時針對日後「原作者主題升級」時如何以零成本（Git Patch / Child Theme）或極低 Token 的 AI 提示詞無痛重新套用進行深度解析。

一、核心需求與架構設計

一個健全的深色模式切換機制需要具備以下要點：

1. 使用者優先權階層：
   • 若使用者曾在站上點擊切換過，以 Cookie 儲存的偏好 為最優先。
   • 若為首次造訪或未設定 Cookie，自動偵測使用者的系統外觀模式（prefers-color-scheme: dark）。
2. 避免白光閃爍（Anti-flicker / FOUC）：
   • 瀏覽器解析 HTML 時，如果等到完整腳本下載並在 DOMContentLoaded 才執行加 class，畫面上會出現短暫的白光閃爍。因此需在 <head> 注入極輕量的行內（Inline）腳本提早設定 class。
3. 直覺易用的開關位置：
   • 將切換開關置入 Header 頂部導覽列（<div class="head-mast-inner">），確保各裝置與版型都能一致顯示。

二、功能實作步驟

1. 樣式實作：獨立樣式表 (css/dark-theme.css)

將所有深色模式樣式統一抽離至獨立檔案，避免直接污染原作者的 style.css，大幅降低後續維護與合併時的衝突風險。

/* ==========================================================================
   Dark Theme Styles
   ========================================================================== */

/* 全域背景與文字 */
body.theme-dark {
  background-color: #121417;
  color: #c9d1d9;
}

body.theme-dark h1,
body.theme-dark h2,
body.theme-dark h3,
body.theme-dark h4,
body.theme-dark h5,
body.theme-dark h6 {
  color: #f0f6fc;
}

/* 頂部導覽、底欄與行動端選單 */
body.theme-dark .head-mast,
body.theme-dark .head-outro,
body.theme-dark .navigation-mobile-wrap {
  background-color: #181b20;
  color: #c9d1d9;
}

/* 下拉選單 */
body.theme-dark .navigation-main ul {
  background-color: #1a1e24;
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.45);
  border: 1px solid #2b3036;
}

/* 輸入框與表單元件 */
body.theme-dark input[type="text"],
body.theme-dark input[type="search"],
body.theme-dark select,
body.theme-dark textarea {
  background-color: #1a1e24;
  color: #e6edf3;
  border-color: #343a42;
}

/* 主題切換按鈕與 SVG 圖示切換 */
.theme-switch-toggle {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 32px;
  height: 32px;
  border-radius: 50%;
  background: transparent;
  border: 0;
  cursor: pointer;
  color: inherit;
  transition: color 0.18s ease, background-color 0.18s ease;
}

.theme-switch-icon svg {
  width: 18px;
  height: 18px;
  fill: currentColor;
}

/* 淺色模式顯示月亮，深色模式顯示太陽 */
.theme-switch-icon .icon-sun { display: none; }
.theme-switch-icon .icon-moon { display: inline-block; }
body.theme-dark .theme-switch-icon .icon-sun { display: inline-block; }
body.theme-dark .theme-switch-icon .icon-moon { display: none; }

2. 行為邏輯：偵測與持久化 (js/theme-switch.js)

透過原生 JavaScript 實現無相依性（Vanilla JS）的偵測與 Cookie 儲存：

(function () {
  'use strict';

  var COOKIE_NAME = 'guntenbee_theme';
  var COOKIE_DAYS = 365;

  function getCookie(name) {
    var match = document.cookie.match(new RegExp('(^|;\\s*)' + name + '=([^;]+)'));
    return match ? decodeURIComponent(match[2]) : null;
  }

  function setCookie(name, value, days) {
    var expires = '';
    if (days) {
      var date = new Date();
      date.setTime(date.getTime() + (days * 24 * 60 * 60 * 1000));
      expires = '; expires=' + date.toUTCString();
    }
    document.cookie = name + '=' + encodeURIComponent(value) + expires + '; path=/; SameSite=Lax';
  }

  function getSystemTheme() {
    return (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches)
      ? 'dark'
      : 'light';
  }

  function getPreferredTheme() {
    var savedTheme = getCookie(COOKIE_NAME);
    return (savedTheme === 'dark' || savedTheme === 'light') ? savedTheme : getSystemTheme();
  }

  function applyTheme(theme) {
    var isDark = (theme === 'dark');
    document.body.classList.toggle('theme-dark', isDark);
    document.body.classList.toggle('theme-light', !isDark);
    document.documentElement.classList.toggle('theme-dark', isDark);
    document.documentElement.classList.toggle('theme-light', !isDark);

    var toggles = document.querySelectorAll('.theme-switch-toggle');
    toggles.forEach(function (btn) {
      btn.setAttribute('aria-pressed', isDark ? 'true' : 'false');
      btn.setAttribute('title', isDark ? '切換至淺色模式' : '切換至深色模式');
    });
  }

  function init() {
    applyTheme(getPreferredTheme());

    document.addEventListener('click', function (e) {
      var toggle = e.target.closest('.theme-switch-toggle');
      if (toggle) {
        e.preventDefault();
        var currentTheme = document.body.classList.contains('theme-dark') ? 'dark' : 'light';
        var nextTheme = (currentTheme === 'dark') ? 'light' : 'dark';
        setCookie(COOKIE_NAME, nextTheme, COOKIE_DAYS);
        applyTheme(nextTheme);
      }
    });

    // 監聽作業系統外觀模式動態變化
    if (window.matchMedia) {
      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function () {
        if (!getCookie(COOKIE_NAME)) {
          applyTheme(getSystemTheme());
        }
      });
    }
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', init);
  } else {
    init();
  }
})();

3. WordPress 資源載入與防閃爍 (inc/scripts-styles.php)

在 wp_enqueue_scripts 鉤子中註冊資源，並加入極速 Inline 腳本：

// Enqueue 樣式與腳本
wp_register_style( 'gutenbee-dark-theme', get_theme_file_uri( '/css/dark-theme.css' ), array( 'gutenbee-style' ), gutenbee_asset_version() );
wp_enqueue_style( 'gutenbee-dark-theme' );

// 防閃爍腳本：在頁面剛開始解析 DOM 時搶先將 theme-dark 注入 <html>
$anti_flicker_js = "(function(){try{var m=document.cookie.match(/(^|;\\s*)guntenbee_theme=([^;]+)/);var t=m?decodeURIComponent(m[2]):null;var d=(window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches)?'dark':'light';if((t||d)==='dark'){document.documentElement.classList.add('theme-dark');}}catch(e){}})();";
wp_add_inline_script( 'gutenbee-dependencies', $anti_flicker_js, 'before' );

wp_register_script( 'gutenbee-theme-switch', get_theme_file_uri( '/js/theme-switch.js' ), array(), gutenbee_asset_version(), true );
wp_enqueue_script( 'gutenbee-theme-switch' );

4. 範本標籤與按鈕輸出 (inc/template-tags.php & Header Templates)

1. 定義輔助函數：function gutenbee_the_theme_switch_button() { ?> <button type="button" class="theme-switch-toggle" aria-label="切換深淺模式"> <span class="theme-switch-icon" aria-hidden="true"> <svg class="icon-moon" viewBox="0 0 24 24"><path d="M12.3 2a10 10 0 0 0-.19 14 10 10 0 0 0 11.63 4A10 10 0 1 1 12.3 2z"/></svg> <svg class="icon-sun" viewBox="0 0 24 24"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><line x1="12" y1="21" x2="12" y2="23" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><line x1="1" y1="12" x2="3" y2="12" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><line x1="21" y1="12" x2="23" y2="12" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg> </span> </button> <?php }
2. 在 template-parts/header/header-full.php、header-split.php、header-navbar.php 的 <div class="head-mast-inner"> 內部直接呼叫 gutenbee_the_theme_switch_button() 即可完美呈現。

三、未來原作者升級主題時的處理策略

當原主題作者發布新版本更新時，若直接覆蓋整個主題資料夾，客製化代碼將會遺失。以下提供三種不同維護情境的應對方式：

策略 A：建立子主題（Child Theme）—— 永遠不被覆蓋（推薦最佳實踐）

WordPress 的標準升級防禦機制是子主題。只需將新寫好的 dark-theme.css、theme-switch.js 及對應 template parts 放進子主題資料夾，日後父主題無論升級幾次，客製化邏輯都不會被覆蓋。

策略 B：利用 Git Patch 自動打補丁（零 Token 快速升級）

若習慣直接於主題目錄工作，建議在功能完成時立即產生 patch 檔案備份：

# 產出補丁檔
git diff > dark-theme.patch

當日後原作者有新版發布時：

# 下載並解壓縮覆蓋原主題後，執行一鍵套用
git apply --reject --whitespace=fix dark-theme.patch

git apply 具備自動比對行號上下文與建立新檔案的能力，速度快且完全不花費任何 AI token。

策略 C：低 Token 的精準 AI 提示詞（AI Prompt Template）

若在遠端或未配備 Git 的環境，需請 AI 助理重新在原作者新版主題植入 Dark Theme 功能時，千萬不要使用模糊指令（例如「幫我在這個主題加深色模式」，這會讓 AI 花費數萬 Token 去探索全文結構與測試選擇器）。

直接複製使用以下經結構化優化的 精準 Prompt：

請為 @guntenbee 主題實作 Dark Theme 功能。請直接依照以下規格建立檔案與注入代碼，不需漫遊搜尋其他檔案：

1. 新增樣式與腳本：
   - 建立 `css/dark-theme.css`：定義 `body.theme-dark` 樣式（深色底色 #121417、文字 #c9d1d9、容器/選單 #181b20）與 `.theme-switch-toggle` 按鈕 SVG 切換動態。
   - 建立 `js/theme-switch.js`：讀取/寫入 Cookie `guntenbee_theme`（效期 365 天）；若無 Cookie 則以 `prefers-color-scheme: dark` 為準，並監聽 OS 主題變化與按鈕點擊事件。

2. 註冊與防閃爍（修改 `inc/scripts-styles.php`）：
   - 在 `gutenbee_enqueue_scripts` 中以 `wp_enqueue_style` 載入 `dark-theme.css`。
   - 注入 Inline Script 到 `<head>`：若 Cookie 或系統偏好為 dark，即時加上 `document.documentElement.classList.add('theme-dark')` 以防止白光閃爍。
   - 以 `wp_enqueue_script` 載入 `theme-switch.js`。

3. 按鈕與鉤子整合：
   - 在 `inc/template-tags.php` 新增 `gutenbee_the_theme_switch_button()` 輸出太陽/月亮按鈕 HTML。
   - 在 `template-parts/header/header-*.php` 各樣板的 `<div class="head-mast-inner">` 的 `head-content-slot` 中呼叫該按鈕函式。
   - 在 `inc/default-hooks.php` 的 `gutenbee_body_class` 過濾器中檢查 `$_COOKIE['guntenbee_theme']`，有 dark 值即附加 `theme-dark` class。

為什麼這個 Prompt 具備高性價比（Low Token Usage）？

1. 消除探勘步驟：精確指出檔案名稱（如 inc/scripts-styles.php、template-parts/header/header-*.php），AI 不需調用目錄搜尋工具消耗大量 Context Window。
2. 精準函式命名：直接給予目標鉤子（gutenbee_body_class、gutenbee_enqueue_scripts），AI 思考路徑縮短，輸出 token 減少 70% 以上。
3. 成果可預測且易於維護：模組化規範使每一次生成的樣式結構一致，日後維護與問題排查極為單純。

核心架構與技術特點

這個模型基於七十億參數的視覺生成架構，採用三十二層的 Single-Stream DiT 設計。與需要二十五到四十步推理的標準基礎模型不同，Turbo 版本透過特殊的加速機制與預存取樣時程，將去噪步驟大幅縮短至八步。它的預設無分類器引導係數固定為一，省去了額外的前向計算過程，因此能以極快的速度完成推理。

主要功能

模型支援文字生成圖片，能夠產出高達 2K 解析度的畫面。除了文生圖之外，它也具備強大的圖片編輯能力。使用者可以透過自然語言指令、參考圖、塗繪標註或蒙版，對既有圖像進行局部修改、更換背景、增加配件或調整場景，同時保留主體與商品的身份特徵。此外，它也支援原生透明度處理。

應用場景

由於其八步快速出圖的特性，這個模型非常適合需要頻繁反覆修改、快速產出草稿或進行電商商品圖批次處理的工作流程。開發者通常會透過 Hugging Face 的 Diffusers 套件以及 ComfyUI 等介面來載入與部署這款模型。

兩者的核心差異

Qwen/Qwen-Image-2.1-Turbo 是 Qwen/Qwen-Image-2.1 的蒸餾加速版本。兩者在底層使用了相同的七十億參數 Single-Stream DiT 視覺生成架構，但推理機制與速度上有顯著不同：

Turbo 可以完全覆蓋原版的所有功能嗎

答案是：在功能支援上可以完全覆蓋，但在極限品質與控制力上無法完全取代原版。

功能範疇完全重疊：

Turbo 版本完全繼承了原版的所有核心功能，包括文字生成圖片、透明背景 RGBA 圖層生成、多圖參考編輯、塗繪與蒙版局部修改、以及人物與商品特徵保留。在 Diffusers 程式庫中，兩者也是使用同一個管道載入。

無法完全取代原版的特定場景：

• 極複雜提示詞：Turbo 版本透過蒸餾技術將引導資訊固化在權重中。當提示詞包含非常長且繁複的多層次指令時，標準原版在 40 步與高 CFG 下的細節表現仍會比 Turbo 更精準。
• 自由調整參數：原版允許使用者自由調整係數與微調取樣步數，以在創造力與文字貼合度之間找到最佳平衡。Turbo 版本的排程與係數已被鎖定與最佳化，調參彈性較低。

使用建議

• 如果需要高效率生產、電商批次處理、即時互動生成或快速草稿設計，應優先選擇 Turbo。
• 如果需要處理非常精細的藝術設計、極度複雜的邏輯指令，或是追求極致細節的最終成品，建議保留原版。

Q: 顯示卡 RTX 4050 Laptop 6GB VRAM 可以跑的動?

以預設的標準精度（BF16 或 FP16）來看，Qwen-Image-2.1 系列模型大約需要十六到二十九 GB 以上的顯示記憶體，因此 RTX 4050 Laptop 的六 GB 顯示記憶體無法直接流暢運行原生日誌與完整精度。

不過，如果你透過以下幾種優化方式，這張顯示卡還是有機會可以嘗試本地端運行：

• 降低精度與量化：透過 GGUF 量化版本或 INT4、INT8 壓縮權重，將模型體積縮小，讓記憶體需求降至六 GB 甚至更低，但這會犧牲部分生成畫質。
• 善用系統記憶體（RAM）：如果筆電的共用記憶體與主記憶體足夠大，部分運行框架支援將部分運算卸載到 CPU 或系統記憶體，只是生成速度會變得很慢。
• 雲端算力替代：如果本地運行經常遇到顯示記憶體不足（Out of Memory）的錯誤，建議改用 Google Colab 或雲端 GPU 服務來執行。

Q: 如何找到降低精度與量化的版本?

在 Hugging Face 或開源社群尋找像 Qwen-Image-2.1 系列這種大型 DiT 模型的量化（Quantized）或降低精度版本時，主要有以下幾條途徑與搜尋方法：

一、 直接在 Hugging Face 搜尋對應的量化庫

量化版本通常不會放在官方原版的 repo 中，而是由社群創作者（如 Unsloth、city96、leejet 等）轉換後發布。你可以直接在 Hugging Face 的搜尋列輸入以下關鍵字：

• GGUF 版本（最適合 6GB VRAM 使用）：
  • 搜尋：Qwen-Image-2.1 GGUF 或 Qwen-Image-2.1-Turbo GGUF
  • 核心量化層級選擇：
    • Q4_K_M（約 4.2 GB）：最推薦 RTX 4050 6GB 使用，模型可以直接完全載入顯示記憶體。
    • Q5_0 / Q5_K_M（約 5.0 – 5.3 GB）：細節稍微提升，但可能會用到少許系統記憶體（RAM）做緩衝。
• INT8 / NF4 版本（Comfy-Org 官方或社群微調）：
  • 搜尋：Qwen-Image-2.1-Turbo-INT8 或 qwen_image_2.1_turbo_int8_convrot
  • 這是直接將權重壓成 INT8 格式的 safetensors 檔案，適合傳統 ComfyUI 流程。

二、 搭配 ComfyUI 運行 GGUF 量化版（最建議的做法）

若要在 RTX 4050 上順利運行 GGUF 模型，單靠預設的 ComfyUI 節點可能會遇到「不支援架構」的錯誤。推薦使用支援該模型架構的擴充元件與組件：

1. 安裝自訂節點：使用 leejet 維護的 ComfyUI-GGUF 套件（比舊版 city96 能更完善支援 Qwen 2.1 架構）。
2. 下載配套檔案：
   • UNet / Diffusion 模型： 放至 ComfyUI/models/unet/，選擇下載好的 .gguf 檔案（例如 qwen-image-2.1-Q4_K_M.gguf）。
   • Text Encoder（文本編碼器）：Qwen-Image 2.1 搭配的是 8B 的文本編碼器。為了省記憶體，同樣建議尋找量化過的文字編碼器，如 qwen3vl_8b_w4a8.safetensors 或 qwen3vl_8b_int8 並放入 models/text_encoders/。
3. 替換節點：在 ComfyUI 工作流中，將原本的 Load Diffusion Model 替換為 Unet Loader (GGUF) 即可載入。

三、 使用整合型工具（如 Ollama / LM Studio 等，若支援）

如果不想手動設定 ComfyUI 工作流，也可以關注像是 Draw Things（Mac/iOS 支援，部分 Windows 框架亦有移植）或 Civitai 網站上是否有創作者上傳整理好的單一打包模型，通常搜尋欄位輸入 Qwen-Image-2.1 Turbo Quantized 即可找到相關資源。

https://huggingface.co/unsloth/Qwen-Image-2.1-Turbo-GGUF

which version best for my RTX 4050 Laptop 6GB RAM?

▋ 最推薦的版本：Q4_K_M (4.2 GB)

對於 RTX 4050 Laptop 6GB 顯示記憶體來說，Q4_K_M 是兼顧品質與運行成功率的最佳首選。

▋ 各版本在 6GB 顯示記憶體下的實測建議與分析

在生成圖片時，顯示記憶體（VRAM）除了要存放主要的 DiT 模型權重之外，還必須留出空間給：

1. Text Encoder（文本編碼器，如 Qwen3-VL 8B）： 需額外佔用約 0.7 – 2 GB 顯示記憶體。
2. VAE 解碼器與 CUDA 計算緩衝區（Compute Buffers）： 約需 1.0 – 1.5 GB。

因此，模型的檔案大小不能剛好等於 6 GB，必須留出至少 1.5 – 2 GB 的動態開銷空間。

• Q4_K_M (4.2 GB) —— 最平衡首選
  • 分析：模型本身佔用約 4.2 GB。搭配 ComfyUI 的模型卸載（CPU Offloading）機制，可以在 6GB VRAM 內剛好塞下，避免發生 OOM（Out of Memory）記憶體溢位崩潰。
  • 畫質損耗： Unsloth 的 Dynamic 4-bit 量化對畫面細節與文字遵循能力保留得相當完整，幾乎感受不出明顯品質下降。
• Q4_K_S (3.91 GB) —— 備用方案（記憶體不夠時使用）
  • 分析： 檔案更小，如果你的系統背景程式佔用了較多 VRAM（例如開著 Chrome 或多個螢幕），導致 Q4_K_M 報錯，請改用此版本。
• Q5_K_S / Q5_K_M (4.5 GB – 5.39 GB) —— 邊緣臨界，易爆 VRAM
  • 分析：4.5 GB 以上的檔案加上 VAE 與編碼器開銷後，非常容易超過 6GB 限制。若要硬跑，系統會被迫將部分模型卸載到電腦的主記憶體（RAM），導致生成速度變得很慢。
• Q6_K / Q6_K_XL (6.27 GB – 6.72 GB) —— 完全不建議
  • 分析：單模型檔案大小就已超過你的顯示記憶體上限。

▋ 6GB VRAM 順暢運行的關鍵設定

1. 圖形解析度：請先從 1024×1024 開始生成。切勿一開始就設為 2048×2048。
2. Text Encoder (文本編碼器)：建議下載量化過的文字編碼器（如 qwen3vl_8b_w4a8 或 int8），或者在 ComfyUI 中開啟 CPU Text Encoder 模式，把文字處理丟給電腦主記憶體。
3. VAE 設定：在 ComfyUI 的 VAE Loader 設定中開啟 Tiled VAE（區塊解碼），可以大幅節省生成最後階段的 VRAM 峰值用量。

Q: 如何串接 AI agent CLI 生圖

要把文字互動介面與本地端生圖模型串接起來，主要有兩個常見且可行的解法。

第一種是透過 ComfyUI 內建的 API 伺服器來串接。ComfyUI 啟動後會在背景提供一套完整的網頁伺服器與 API 功能。你可以在終端機裡寫一個簡單的 Python 程式或是用 curl 指令，把提示詞打包成 JSON 格式發送到 ComfyUI 的連接埠，讓它在背景自動生成圖片並回傳檔案路徑。驗證這個步驟是否成功的方法是，打開瀏覽器確認網頁伺服器有正常回應。

第二種是自己寫一個輕量化的轉接層。有些 agent cli 工具預設只能對接類似 OpenAI 的文字或圖片生成 API。你可以用 Python 的 FastAPI 寫一個簡單的伺服器，對外提供標準的 API 介面，當收到終端機傳來的生圖請求時，程式再自動去呼叫底層的生圖工具。驗證這個步驟是否成功的方法是，用終端機發送一筆測試請求，確認伺服器能夠正確接收並處理。

give me solution for my RTX 4050 Laptop 6GB VRAM

你的顯示記憶體只有 6GB ，直接執行官方的原始程式碼一定會立刻跳出記憶體不足的錯誤。為了讓程式碼能在你的電腦上順利跑完，我們必須修改幾個關鍵設定，包含大幅降低圖片解析度以及開啟 CPU 記憶體卸載功能。

這是一份修改過後的 Python 程式碼，可以讓你在 RTX 4050 上面嘗試執行：

Python

import torch
from diffusers import QwenImage21Pipeline

pipe = QwenImage21Pipeline.from_pretrained(
    "Qwen/Qwen-Image-2.1-Turbo",
    torch_dtype=torch.float16,
)

pipe.enable_model_cpu_offload()

prompt = "A vertically oriented educational chemistry study poster fills the frame, designed like a hand-drawn classroom notes page with a clean white background, thick dark navy-blue outer border, and thin inner navy rectangular border lines. The overall aesthetic is colorful, high-contrast, and hand-lettered in a signature Topper style using marker and watercolor effects. At the top left, a small header in black handwriting reads \"Topper’s Notes\", accented by short decorative navy strokes radiating from it. Centered across the top is the main lesson heading in large stylized black-and-yellow bold lettering: \"Science – Chapter 1:\" followed below by the much larger title \"Chemical Reactions and Equations\". The title has energetic yellow highlighter strokes underneath and small sparkle doodles nearby. At the top right, inside a small outlined page-number box, the label reads \"Page X\". Below the header, a wide rounded rectangle framed in dark navy contains a pink brush-stroke highlight banner with the subheading \"IMPORTANT CHEMICAL EQUATION:\" in black. Inside the same equation panel, the reaction is written very large as \"Fe + CuSO₄ → FeSO₄ + Cu\". The symbol \"Fe\" is highlighted in bright orange with an underline, \"CuSO₄\" is vivid blue and underlined, \"FeSO₄\" is bright green and underlined, and \"Cu\" is metallic bronze and underlined. Beneath the left side of the equation is a lavender rounded label connected by a leader line to the iron component; it says \"Reactants\" and below it \"(before the reaction)\", with \"Reactants\" colored purple and underlined. Beneath the right side is a matching pale-green rounded label connected by a leader line to the products; it says \"Products\" and below it \"(after the reaction)\", with \"Products\" colored green and underlined. Along the lower part of this equation box are stylized ball-and-stick molecule models and atomic orbital drawings: a silver-gray sphere labeled \"Fe\" sits left of center, another cluster shows gray, red, and white spheres representing sulfate groups around blue and green atoms, and a copper-colored sphere appears near the right. Small atom-and-orbit icons sit along the bottom edge of the panel in blue, green, and brown outline styles. The middle portion is enclosed by a large dashed green rounded rectangle titled \"REACTIVITY CONCEPT\" in green uppercase letters with decorative rays. On the left side of this section, a stepped vertical reactivity-series ladder is drawn with alternating colored horizontal blocks. From top to bottom it lists \"K\", \"Na\", \"Ca\", \"Mg\", \"Al\", \"Zn\", \"Fe\" with a green oval callout reading \"(More reactive)\", then continues downward with \"Cu\", \"Ag\", \"Hg\", \"Pt\", \"Au\" with an orange oval callout reading \"(Less reactive)\". Each step is marked by a dark upward-pointing triangular arrow, showing decreasing reactivity downward. In the central-right area, full body text as follows: \"Iron (Fe) is higher in the reactivity series than Copper (Cu). This makes Iron more reactive.\" Below this definition is a visual arrow sequence of overlapping circles: orange \"Fe\" overlaps blue \"Cu\", followed by a red arrow pointing toward the phrase \"→ More displacement ↓ less reactivity\". Under it, a prominent statement in dark handwriting reads \"More reactive element displaces less reactive element\", emphasized with a bright pink marker underline. On the right, a shield-like badge with a navy outline and light interior contains the bold contrasting font label \"DISPLACEMENT REACTION\". Below the badge, full body text as follows: \"A more reactive element displaces a less reactive element from its compound.\" The badge includes an internal miniature illustration of circular electron shells and colored particles, reinforcing the chemistry theme. Directly below the reactivity concept box, a smaller rounded rectangular table titled \"PROPERTY COMPARISON\" compares Iron and Copper. The table has three columns: \"IRON (Fe)\", \"COPPER (Cu)\", and a central property column. Row one reads \"Reactivity series position\" with Iron shown as \"Higher (more reactive)\" and Copper shown as \"Lower (less reactive)\". Row two reads \"Displaces hydrogen from acids\" with Iron marked \"Yes\" and Copper marked \"No\". Row three reads \"Displaced by other metals\" with Iron shown as \"Displaced by Zn, Mg, Al, etc.\" and Copper shown as \"Displaced by Fe, Zn, Mg, etc.\". Row four reads \"Oxidation tendency\" with Iron shown as \"Gets oxidized easily\" and Copper shown as \"Does not get oxidized easily\". Row five reads \"Useful property\" with Iron described as \"Used where strength & corrosion resistance needed\" and Copper described as \"Used where conductivity & corrosion resistance needed\". The table uses thin navy grid lines, orange tinting for the iron column, pale blue tinting for the copper column, black condensed handwriting, and green checkmarks next to positive traits and red crosses next to limitations. The lower half introduces a large illustrated experiment section with a cream highlight behind the title \"BEFORE/AFTER IRON NAIL EXPERIMENT\" in bold dark navy uppercase letters. The section is split visually into a left \"Before\" state and a right \"After\" state. On the left, a beaker filled with bright blue solution contains a shiny silver iron nail standing diagonally. The beaker label reads \"CuSO₄(aq)\" in blue, and the bottom label near the nail reads \"Fe(s)\". A rounded annotation box beside the beaker says \"Initial State: Blue Solution & Silver Nail\". Two glass test tubes stand to the right of this beaker: the upper test tube is filled with blue solution and labeled \"CuSO₄(aq)\", while the lower one contains a pale green liquid. Red and blue directional arrows connect these visual elements to explanations: one red arrow points toward the nail with the text \"Copper gets deposited\", and one blue arrow points toward the liquid with the text \"Solution turns pale green\". On the right side of the experiment section, another beaker shows the after state with the iron nail now coated in brown copper deposits. Its solution is faded to a pale greenish-blue, and the beaker label reads \"FeSO₄(aq)\" in green. A nearby rounded annotation box says \"Final State: Pale Green Solution & Brown Coated Nail\". To the far right are additional test tubes and ion symbols: a test tube containing blue liquid labeled \"CuSO₄(aq)\" with the note \"Blue colour due to Cu²⁺ ions\", and a lower test tube containing pale green liquid labeled \"FeSO₄(aq)\" with the note \"Pale green due to Fe²⁺ ions\". Beside them are ion diagrams labeled \"Cu²⁺(aq)\" and \"Fe²⁺(aq)\", shown as colored charged particles encircled by simple electron-shell rings; the copper ion uses blue particles and the iron ion uses green particles. Small sparkles, arrows, and dashed guide lines emphasize the transformation from blue copper sulfate solution to pale green iron sulfate solution. Near the bottom, a horizontal summary strip has a blue star icon followed by the heading \"SUMMARY\". Full body text as follows: \"In this reaction, Iron (Fe) displaces Copper (Cu) from Copper Sulphate (CuSO₄) solution to form Iron(II) Sulphate (FeSO₄) solution and Copper (Cu).\" To the lower left, a bordered key-points box titled \"KEY POINTS\" lists three starred bullet statements: \"Iron is above copper in the reactivity series.\", \"Fe displaces Cu from CuSO₄ solution.\", and \"Result: Blue solution turns pale green; copper metal deposits on iron nail.\" At the very bottom, inside the footer border, spaced text reads \"CHEMISTRY • CHANGE IS EVERYWHERE • TOPPER’S NOTES\", flanked by small leaf-like ornaments and thin horizontal divider lines. The entire page uses dark navy borders and headings, bright highlighter strokes, watercolor shading, realistic glassware illustrations, and playful scientific doodles to present a chemistry lesson clearly and attractively."

image = pipe(
    prompt=prompt,
    width=512,
    height=768,
    use_kv_cache=True,
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]

image.save("t2i.png")

這段程式碼做了三個重要的調整。第一是把圖片解析度從原本極大的尺寸縮小成 512 乘以 768 像素，因為原本的尺寸需要十六 GB 以上的顯示記憶體才能運作。第二是加入了記憶體卸載指令，當顯示記憶體快滿時，會自動把運算暫存搬到電腦的主記憶體。第三是把資料型態改成了 float16 ，這樣可以省下一半的記憶體空間。

因為這張顯示卡的記憶體容量有限，啟動記憶體卸載之後，生圖的速度會變得非常慢，需要耐心等待程式執行完畢。如果執行時還是出現記憶體不足的錯誤，可以把解析度再調得更小一點。

Q: 上述範例 512×768 會占用多少記憶體, 我如果下載 5-bit mode: Q5_K_S (4.5 GB), 會造成 OOM ?

在 512x768 解析度下，圖片本身的潛在空間與運算暫存區大約會佔用 1 GB 到 1.5 GB 的顯示記憶體。

如果下載 5-bit 的 Q5_K_S 版本（檔案大小約 4.5 GB），在 RTX 4050 的 6 GB 顯示記憶體上極有可能會發生 OOM 錯誤，或是被迫將大量運算卸載到系統記憶體，導致生圖速度變得極慢。

原因在於 6 GB 顯示記憶體扣掉 4.5 GB 的模型檔案後，只剩下大約 1.5 GB 的空間。然而生圖過程還需要載入文字編碼器與解碼器，這些元件加起來很容易超過 6 GB 的極限。

建議還是選擇檔案更小的 4-bit 版本，例如 Q4_K_M 或 Q4_K_S，才能在 6 GB 顯示記憶體上比較穩定地運行。

改寫範例scrpt 為 resetful api + fastapi, input prompt + output target filepath

I will now generate the FastAPI script for running the Qwen-Image-2.1-Turbo model as a RESTful service.

I have created the FastAPI script qwen_api_server.py.

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field
import torch
from diffusers import QwenImage21Pipeline
import os

app = FastAPI(
    title="Qwen-Image-2.1-Turbo REST API",
    description="A lightweight FastAPI service to generate images via Qwen-Image-2.1-Turbo and save them to a specified target file path.",
    version="1.0.0"
)

# Global pipeline variable to hold the model in memory
pipe = None

@app.on_event("startup")
def load_model():
    global pipe
    print("Loading Qwen-Image-2.1-Turbo model into GPU memory...")
    try:
        pipe = QwenImage21Pipeline.from_pretrained(
            "Qwen/Qwen-Image-2.1-Turbo",
            torch_dtype=torch.bfloat16,
        ).to("cuda")
        # Uncomment the line below if you run into 6GB VRAM OOM issues:
        # pipe.enable_model_cpu_offload()
        print("Model loaded successfully!")
    except Exception as e:
        print(f"Failed to load model: {e}")
        raise e

class GenerateRequest(BaseModel):
    prompt: str = Field(..., description="The text description for image generation.")
    output_path: str = Field(..., description="The target file path where the generated image will be saved.")
    width: int = Field(512, description="Image width (recommended lower for 6GB VRAM, e.g., 512 or 768).")
    height: int = Field(768, description="Image height (recommended lower for 6GB VRAM, e.g., 768 or 1024).")
    seed: int = Field(42, description="Random seed for reproducibility.")

@app.post("/generate", status_code=status.HTTP_200_OK)
def generate_image(req: GenerateRequest):
    global pipe
    if pipe is None:
        raise HTTPException(status_code=500, detail="Model is not loaded yet.")
    
    try:
        # Ensure output directory exists if a subdirectory is provided
        output_dir = os.path.dirname(req.output_path)
        if output_dir and not os.path.exists(output_dir):
            os.makedirs(output_dir, exist_ok=True)

        # Run inference
        image = pipe(
            prompt=req.prompt,
            width=req.width,
            height=req.height,
            use_kv_cache=True,
            generator=torch.Generator("cpu").manual_seed(req.seed),
        ).images[0]

        # Save to target filepath
        image.save(req.output_path)

        return {
            "status": "success",
            "message": f"Image successfully generated and saved.",
            "output_path": req.output_path
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Image generation failed: {str(e)}")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("qwen_api_server:app", host="127.0.0.1", port=8000, reload=False)

How to use it:

1. Run the server using: python qwen_api_server.py
2. You can send a POST request from your CLI agent (like pi agent, agy cli, or curl) to [http://127.0.0.1:8000/generate](http://127.0.0.1:8000/generate) with a JSON body containing your prompt and output_path.

Let me know if you want an example curl command or client script to test this API!

FastAPI script for image editing using the Qwen-Image-2.1-Turbo pipeline, incorporating memory optimizations for your RTX 4050 6GB VRAM.

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field
import torch
from diffusers import QwenImage21Pipeline
from diffusers.utils import load_image
import os

app = FastAPI(
    title="Qwen-Image-2.1-Turbo Image Editing REST API",
    description="A FastAPI service for image-to-image / image editing using Qwen-Image-2.1-Turbo, optimized for 6GB VRAM.",
    version="1.0.0"
)

pipe = None

@app.on_event("startup")
def load_model():
    global pipe
    print("Loading Qwen-Image-2.1-Turbo pipeline for image editing into GPU memory...")
    try:
        pipe = QwenImage21Pipeline.from_pretrained(
            "Qwen/Qwen-Image-2.1-Turbo",
            torch_dtype=torch.float16, # Using float16 to conserve VRAM
        )
        
        pipe.enable_model_cpu_offload()
        print("Model and CPU offload successfully configured!")
    except Exception as e:
        print(f"Failed to load model: {e}")
        raise e

class EditRequest(BaseModel):
    prompt: str = Field(..., description="The editing text prompt describing the transformation.")
    input_image_path_or_url: str = Field(..., description="Local file path or URL of the source image/sketch.")
    output_path: str = Field(..., description="The target file path where the edited image will be saved.")
    width: int = Field(1024, description="Image width (scaled down to 1024 or 512 for 6GB VRAM safety).")
    height: int = Field(1024, description="Image height (scaled down to 1024 or 512 for 6GB VRAM safety).")
    seed: int = Field(20261009, description="Random seed for reproducibility.")

@app.post("/edit-image", status_code=status.HTTP_200_OK)
def edit_image(req: EditRequest):
    global pipe
    if pipe is None:
        raise HTTPException(status_code=500, detail="Model is not loaded yet.")
    
    try:
        if req.input_image_path_or_url.startswith("http://") or req.input_image_path_or_url.startswith("https://"):
            input_image = load_image(req.input_image_path_or_url).convert("RGBA")
        else:
            if not os.path.exists(req.input_image_path_or_url):
                raise HTTPException(status_code=400, detail=f"Input image path not found: {req.input_image_path_or_url}")
            input_image = load_image(req.input_image_path_or_url).convert("RGBA")

        # Ensure output directory exists
        output_dir = os.path.dirname(req.output_path)
        if output_dir and not os.path.exists(output_dir):
            os.makedirs(output_dir, exist_ok=True)

        image = pipe(
            prompt=req.prompt,
            image=input_image,
            width=req.width,
            height=req.height,
            use_kv_cache=True,
            generator=torch.Generator("cpu").manual_seed(req.seed),
        ).images[0]

        # Save to target filepath
        image.save(req.output_path)

        return {
            "status": "success",
            "message": "Image editing completed and saved successfully.",
            "output_path": req.output_path
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Image editing failed: {str(e)}")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("qwen_edit_api:app", host="127.0.0.1", port=8000, reload=False)

Q: /generate api and /edit-image api 怎麼寫會比較好, 如果後續還有其他 API 要增加.

如果要讓 FastAPI 專案未來方便擴充更多 API，建議採用模組化設計與依賴注入的概念。

第一點是使用 APIRouter 來拆分路由。不要把所有端點都寫在 main.py 裡面。可以建立一個 routers 資料夾，把生圖功能放在 routers/generation.py，把圖片編輯放在 routers/editing.py，最後再用 app.include_router 整合進主程式。

第二點是使用依賴注入管理模型實體。因為模型佔用大量顯示記憶體，不適合每次請求都重新載入。可以在程式啟動時初始化一次管線，透過 FastAPI 的 Depends 或全域狀態共用同一個 pipeline 執行個體。

第三點是統一請求與回應格式。未來如果加入文字生成或其他功能，輸入與輸出的結構可以用 Pydantic 模型嚴格定義，這樣 agent 呼叫時才能確保欄位正確。

專案資料夾結構可以這樣規劃：

qwen_img_fastapi/
│
├── main.py
├── services/
│   └── model_loader.py
└── routers/
    ├── generation.py
    └── editing.py

透過這種架構，未來如果需要新增其他 API，只要在 routers 裡面多寫一支檔案，並在 main.py 註冊即可，維護起來會更有條理。

main.py

from fastapi import FastAPI
from routers import generation, editing

app = FastAPI(
    title="Qwen-Image-2.1-Turbo Modular REST API",
    description="A modular FastAPI service for image generation and editing using Qwen-Image-2.1-Turbo, optimized for RTX 4050 6GB VRAM.",
    version="1.0.0"
)

# Include routers for different capabilities
app.include_router(generation.router)
app.include_router(editing.router)

@app.get("/", tags=["Root"])
def root():
    return {
        "status": "online",
        "message": "Welcome to Qwen-Image-2.1-Turbo API. Check /docs for Swagger UI documentation."
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=False)

services/model_loader.py

import torch
from diffusers import QwenImage21Pipeline

# Global container for the shared pipeline
_pipe = None

def get_pipeline() -> QwenImage21Pipeline:
    global _pipe
    if _pipe is None:
        print("Loading Qwen-Image-2.1-Turbo pipeline into memory...")
        try:
            _pipe = QwenImage21Pipeline.from_pretrained(
                "Qwen/Qwen-Image-2.1-Turbo",
                torch_dtype=torch.float16,
            )
            # Enable CPU offloading to prevent OOM errors on 6GB VRAM GPUs
            _pipe.enable_model_cpu_offload()
            print("Pipeline successfully loaded and CPU offload enabled!")
        except Exception as e:
            print(f"Failed to load pipeline: {e}")
            raise e
    return _pipe

routers/generation.py

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, Field
import torch
import os
from services.model_loader import get_pipeline

router = APIRouter(prefix="/generation", tags=["Image Generation"])

class GenerateRequest(BaseModel):
    prompt: str = Field(..., description="The text description for image generation.")
    output_path: str = Field(..., description="The target file path where the generated image will be saved.")
    width: int = Field(512, description="Image width (keep low, e.g. 512 or 768 for 6GB VRAM).")
    height: int = Field(768, description="Image height (keep low, e.g. 768 or 1024 for 6GB VRAM).")
    seed: int = Field(42, description="Random seed for reproducibility.")

@app.post("/text-to-image" if False else "/generate", status_code=status.HTTP_200_OK)
def generate_image(req: GenerateRequest):
    try:
        pipe = get_pipeline()
        
        output_dir = os.path.dirname(req.output_path)
        if output_dir and not os.path.exists(output_dir):
            os.makedirs(output_dir, exist_ok=True)

        image = pipe(
            prompt=req.prompt,
            width=req.width,
            height=req.height,
            use_kv_cache=True,
            generator=torch.Generator("cpu").manual_seed(req.seed),
        ).images[0]

        image.save(req.output_path)

        return {
            "status": "success",
            "message": "Image generated successfully.",
            "output_path": req.output_path
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Generation failed: {str(e)}")

routers/editing.py

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, Field
import torch
import os
from diffusers.utils import load_image
from services.model_loader import get_pipeline

router = APIRouter(prefix="/editing", tags=["Image Editing"])

class EditRequest(BaseModel):
    prompt: str = Field(..., description="The editing text prompt describing the transformation.")
    input_image_path_or_url: str = Field(..., description="Local file path or URL of the source image/sketch.")
    output_path: str = Field(..., description="The target file path where the edited image will be saved.")
    width: int = Field(1024, description="Image width.")
    height: int = Field(1024, description="Image height.")
    seed: int = Field(20261009, description="Random seed for reproducibility.")

@router.post("/edit-image", status_code=status.HTTP_200_OK)
def edit_image(req: EditRequest):
    try:
        pipe = get_pipeline()

        if req.input_image_path_or_url.startswith("http://") or req.input_image_path_or_url.startswith("https://"):
            input_image = load_image(req.input_image_path_or_url).convert("RGBA")
        else:
            if not os.path.exists(req.input_image_path_or_url):
                raise HTTPException(status_code=400, detail=f"Input image not found: {req.input_image_path_or_url}")
            input_image = load_image(req.input_image_path_or_url).convert("RGBA")

        output_dir = os.path.dirname(req.output_path)
        if output_dir and not os.path.exists(output_dir):
            os.makedirs(output_dir, exist_ok=True)

        image = pipe(
            prompt=req.prompt,
            image=input_image,
            width=req.width,
            height=req.height,
            use_kv_cache=True,
            generator=torch.Generator("cpu").manual_seed(req.seed),
        ).images[0]

        image.save(req.output_path)

        return {
            "status": "success",
            "message": "Image editing completed successfully.",
            "output_path": req.output_path
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Image editing failed: {str(e)}")

Q: 為什麼執行 main.py 之後, 畫面顯示還要下載其他檔案?

這是因為一個完整的文生圖 Pipeline（QwenImage21Pipeline）不只有 Transformer 主模型，還包含其他必備元件：

1. 為什麼本機有了 .gguf 還在下載？

在 model_loader.py:35-39 中：

# 1. 這裡載入的是您本機已有的 Transformer 權重 (約 4GB 的 GGUF)
transformer = QwenImage21Transformer2DModel.from_single_file(GGUF_MODEL_PATH, ...)

# 2. 這裡組裝整個 Pipeline：
_pipe = QwenImage21Pipeline.from_pretrained(
    "Qwen/Qwen-Image-2.1-Turbo",
    transformer=transformer,   # <--- Transformer 替換成本地的 GGUF
    torch_dtype=torch.bfloat16,
)

文生圖 Pipeline 除了 Transformer（降噪核心）之外，還需要：

1. Text Encoder（文字編碼器 / Tokenizer）：負責把您的英文 Prompt 轉成模型看得懂的語意向量。
2. VAE（變分自編碼器）：負責將潛空間特徵解碼還原成真實的 PNG/JPEG 像素圖片。
3. Scheduler / Config 設定檔：去噪步數調度器。

因為您的專案目錄目前只有 Qwen/qwen-image-2.1-turbo-Q4_K_M.gguf（只有 Transformer 本身），所以 Hugging Face Diffusers 會自動去 HuggingFace 官方下載其餘的文字編碼器（Text Encoder）與 VAE。
──────

2. 需要下載多少？之後每次都要下載嗎？

• 只需要下載這一次：下載後的檔案會保存在本機快取目錄（C:\Users\max32.cache\huggingface\hub）。下一次再啟動或呼叫 API 時，就會直接讀取快取，不會再次重複下載。
• 檔案大小：主要是 Text Encoder 與 VAE，下載量約數 GB。

等待這次背景下載完畢後，模型就會自動完成組裝並產出圖片！

在 Diffusers 架構中，每個 Pipeline 需要下載哪些元件是由倉庫根目錄的 model_index.json 定義的。
對於 Qwen/Qwen-Image-2.1-Turbo，它需要的資料夾元件如下：
• 官方倉庫頁面：https://huggingface.co/Qwen/Qwen-Image-2.1-Turbo/tree/main
──────

一、您需要手動下載的檔案清單

因為您已經有 transformer（即您本機的 qwen-image-2.1-turbo-Q4_K_M.gguf），不需要 下載倉庫中的 transformer/ 資料夾（這部分就佔了十幾 GB）。
您只需要下載其餘的 4 個元件資料夾 與 根目錄設定檔：

1. 根目錄設定檔

• model_index.json

2. text_encoder/ 資料夾

│ 文字編碼器（Qwen3-VL 文本主幹），主要權重檔比較大：

• config.json
• generation_config.json
• model.safetensors（或是 model.safetensors.index.json 與相關的 .safetensors 分卷）

3. processor/ 資料夾（含 Tokenizer）

• chat_template.json
• preprocessor_config.json
• processor_config.json
• tokenizer_config.json
• vocab.json / merges.txt（或相關的 tokenizer 檔案）

4. vae/ 資料夾

│ 負責把潛向量轉為實際圖片：
• config.json
• diffusion_pytorch_model.safetensors

5. scheduler/ 資料夾

• scheduler_config.json
──────

二、手動下載後如何放置與修改程式碼？

建議在專案中建立一個本地目錄（例如 models/Qwen-Image-2.1-Turbo），並把上述檔案依照相同結構放好：

C:\Users\max32\Downloads\qwen_img_fastapi\
 ├── Qwen\
 │    └── qwen-image-2.1-turbo-Q4_K_M.gguf
 └── models\
      └── Qwen-Image-2.1-Turbo\
           ├── model_index.json
           ├── text_encoder\
           ├── processor\
           ├── vae\
           └── scheduler\

然後在 model_loader.py 將 BASE_MODEL_ID 改成此本機路徑：

BASE_MODEL_ID = os.path.join(
    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
    "models",
    "Qwen-Image-2.1-Turbo"
)

修改後，Pipeline 就不會連網下載任何東西，而是直接從本機硬碟快速載入！
──────

三、推薦的高速下載方式（比瀏覽器手動點一個個檔案快）

如果您使用瀏覽器一個個點比較繁瑣，推薦使用支援多執行緒並發下載的工具：

方式 A：使用 hf-transfer（推薦，通常可跑滿寬頻）

在終端機安裝並開啟加速：

pip install -U hf-transfer huggingface_hub
$env:HF_HUB_ENABLE_HF_TRANSFER = "1"

接著使用指令直接下載排除 transformer 以外的所有檔案至本機資料夾：

huggingface-cli download Qwen/Qwen-Image-2.1-Turbo --exclude "transformer/*" --local-dir models/Qwen-Image-2.1-Turbo

方式 B：使用 IDM / 多線程下載器

如果網路對 Hugging Face 有限制，亦可利用鏡像站（如 hf-mirror.com）：

$env:HF_ENDPOINT = "https://hf-mirror.com"
huggingface-cli download Qwen/Qwen-Image-2.1-Turbo --exclude "transformer/*" --local-dir models/Qwen-Image-2.1-Turbo

驗證與除錯用curl

Minimal curl (omit any optional field to use defaults), linux / macOS:

curl -X POST "http://127.0.0.1:8000/generation/generate" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"a sunset over the ocean\", \"output_path\": \"output/image.png\"}"

for Windows:

curl -X POST "http://127.0.0.1:8000/generation/generate" ^
  -H "Content-Type: application/json" ^
  -d "{\"prompt\": \"a sunset over the ocean\", \"output_path\": \"output/image.png\"}"

With custom values:

curl -X POST "http://127.0.0.1:8000/generation/generate" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"a sunset over the ocean\", \"output_path\": \"output/image.png\", \"width\": 768,

“height”: 1024, “seed”: 123}”

執行失敗

[W1013 21:31:02.000000000 CUDACachingAllocator.cpp:3934] memory allocation failed with OOM on device 0 while trying to allocate 33554432 bytes (free: 0, total: 6438780928).
[W1013 21:31:02.000000000 CUDACachingAllocator.cpp:3934] memory allocation failed with OOM on device 0 while trying to allocate 33554432 bytes (free: 0, total: 6438780928).
INFO: 127.0.0.1:5457 – “POST /generation/generate HTTP/1.1” 500 Internal Server Error

您的 Transformer 確實已經正確載入為 Q4_K_M GGUF，沒有載入到原本數十 GB 的 Transformer。

導致顯存不足（OOM，總共 6GB 卻嘗試分配超出顯存）的真正元兇是：
text_encoder（文字編碼器，即 Qwen3VL）。

1. 體積對比：
   • 您量化後的 Transformer（qwen-image-2.1-turbo-Q4_K_M.gguf）：只有 約 3.9 GB。
   • 官方未量化的 text_encoder/model.safetensors：高達 16.3 GB（BF16/FP16）！
2. 為什麼報錯：
   • 當呼叫 pipe(…) 生成圖片的第一步，Pipeline 會先執行 text_encoder 來解析 prompt。
   • 雖然設定了 enable_model_cpu_offload()，但在執行 text_encoder 時，會嘗試將這 16.3 GB 的整個文字編碼器移進 GPU
   顯存；但您的 RTX 4050 只有 6 GB 顯存，因此在瞬間爆顯存（OOM）。

──────

解決方案

對於 6GB VRAM，有以下兩種解決方案：

方案 1：啟用 enable_sequential_cpu_offload()（最直接，無需下載新模型）

Diffusers 提供了層級依序卸載（Sequential CPU Offload）。它不會把整個 16GB text_encoder 一次性塞入
GPU，而是一層一層搬進 GPU 運算後立刻移出，完美相容 6GB 甚至 4GB 顯存。
• 優點：馬上能跑，不需要額外下載任何量化 text_encoder。
• 缺點：文字編碼階段會稍慢一些。

方案 2：對 text_encoder 使用 bitsandbytes 4-bit 量化（推薦長期使用）

使用 BitsAndBytesConfig(load_in_4bit=True) 載入文字編碼器，將 16GB 的 text_encoder 直接壓縮至約 4GB 甚至更小。

1. 方案 1（enable_sequential_cpu_offload）最簡單、即插即用：
   • 它是 Diffusers 官方內建的顯存極限優化機制。
   • 不需要安裝額外套件（目前您的環境尚未安裝 bitsandbytes，若在 Windows 安裝 bitsandbytes 常有 CUDA
   編譯環境相容性問題）。
   • 它會將模型逐層（Layer-by-layer）調度進 6GB 顯存，執行完立即釋放，16GB 的 text_encoder 也能順利執行，徹底解決
   OOM。
2. 兩者的關係是二選一：
   • 方案 1 是透過「分批搬移權重」來省顯存。
   • 方案 2 是透過「壓縮模型本體體積」來省顯存。
   • 一般來說，直接套用方案 1 就能成功執行。

這兩次測試讓我們看清了兩個關鍵問題與癥結點：

1. 剛剛兩次報錯的真正原因

• 第一次（OOM 爆顯存）：
您載入的確實是 -Q4_K_M.gguf（只有 3.9GB），沒有載入錯。
但文生圖 Pipeline 包含的文字編碼器 text_encoder/model.safetensors（Qwen3-VL-8B）是未量化的 BF16，檔案大小高達 16.3
GB！
當使用 enable_model_cpu_offload() 時，Diffusers 在處理文字時會把整個 16.3GB 的 text_encoder 載入 GPU，而您的 RTX
4050 只有 6GB 顯存，直接瞬間 OOM。
• 第二次（KeyError: None）：
這是 Hugging Face Diffusers 目前官方的一個已知 Bug（Issue #14691 https://github.com/huggingface/diffusers/issues）：
當使用 enable_sequential_cpu_offload() 時，Diffusers 的層級卸載機制與 GGUF 自訂參數格式不相容（在重新包裝 tensor
時丟失了 quant_type 屬性），導致報錯崩潰。

此外，檢查了您的系統記憶體，電腦實體 RAM 為 12 GB（可用約 8 GB）。要把 16.3 GB 的 BF16
文字編碼器同時放在記憶體中本身就非常極限。
──────

2. 根本解法：使用量化版 Text Encoder

Qwen-Image-2.1 之所以顯存要求極高，是因為它採用了 8B 級別的多模態大模型（Qwen3-VL-8B）作為文字編碼器。

要讓 RTX 4050 (6GB VRAM) + 12GB RAM 能夠流暢生成圖片，不能使用原本 16.3GB 的文字編碼器，而必須將 text encoder
也換成量化版（例如 Comfy-Org 或社群提供的 FP8 或 INT8 權重）：

• 原版 BF16 text encoder：16.3 GB （無法塞入 6GB 顯存與 12GB RAM）
• FP8 / INT8 text encoder：約 4~8 GB （可順利載入運算）
──────

3. 建議下一步

目前最推薦的處理解法：

1. 從 Hugging Face 下載輕量化版（FP8 或 INT8，約 4~8GB）的 Qwen3-VL 文字編碼器，替換掉 models/Qwen-Image-2.1-
   Turbo/text_encoder。
2. 同時保留您現有的 qwen-image-2.1-turbo-Q4_K_M.gguf 作為 Transformer。
3. 這樣兩者都能控制在 4~5 GB 內，透過 enable_model_cpu_offload() 就能完美在 RTX 4050 6GB 跑完完整圖片生成流程。

錯誤訊息

curl -X POST “http://127.0.0.1:8000/generation/generate” ^
More? -H “Content-Type: application/json” ^
More? -d “{“prompt”: “a sunset over the ocean”, “output_path”: “output/image.png”}”

{“detail”:”Generation failed: The size of tensor a (4096) must match the size of tensor b (8192) at non-singleton dimension 2″}

Root Cause: Text Encoder Size Mismatch

Component	Hidden Size	Source
Your text_encoder (Qwen/Qwen-Image-2.1-Turbo official)	4096 (Qwen3-VL-4B)	hidden_size: 4096 in config.json
Your GGUF transformer (Unsloth Q4_K_M)	expects 8192	Unsloth trained it against Qwen3-VL-8
transformer/config.json context_in_dim	4096	matches the official 4B text encoder

The contradiction: the official transformer/config.json says context_in_dim: 4096 (correct for 4B TE), but the
Unsloth GGUF you downloaded was quantized from a model that used Qwen3-VL-8B (8192) as its text encoder. So those
two are incompatible.
──────

Should you download the Unsloth GGUF?

No — you don’t need to switch. The better fix is to use the official Qwen transformer weights (not Unsloth’s GGUF),
or use your existing GGUF correctly paired with the right text encoder.

You have 2 paths:

Option A — Ditch the GGUF, load the official model fully (simplest fix)
Use QwenImage21Pipeline.from_pretrained with all local weights. The official models/Qwen-Image-2.1-Turbo has
context_in_dim=4096 matching your 4B text encoder. No GGUF at all.

Option B — Keep the Unsloth GGUF, replace the text encoder with Qwen3-VL-8B
Download Unsloth’s recommended Qwen3-VL-8B-Instruct-UD-Q4_K_XL.gguf text encoder. But this requires significant
additional download (~5GB+) and more complex loading code.

──────
Recommendation: Option A — you already have all the official weights. Let me fix model_loader.py to load the full
pipeline from local files without the mismatched GGUF:
● Ran 1 command, checked 1 task (python -c “import diffusers; print(diffusers.version)” · tas…) (ctrl+o to expand

Good — diffusers 0.41.0.dev0. Now let me fix the model loader to load the official pipeline without the mismatched
Unsloth GGUF:

● Edited 1 file (model_loader.py) (ctrl+o to expand)

Now restart your server and try again:

# Kill any running server first, then:
python -m uvicorn main:app --host 127.0.0.1 --port 8000

Then test:

curl -X POST "http://127.0.0.1:8000/generation/generate" `
  -H "Content-Type: application/json" `
  -d "{\"prompt\": \"a sunset over the ocean\", \"output_path\": \"output/image.png\"}"

──────

Summary

The bug: Your Unsloth GGUF (qwen-image-2.1-turbo-Q4_K_M.gguf) was trained against the Qwen3-VL-8B text encoder
(hidden_size=8192), but your local text_encoder/ is Qwen3-VL-4B (hidden_size=4096). The transformer’s txt_in layer
tried to accept a 4096-wide tensor but had weights sized for 8192.

The fix: Removed the GGUF entirely. The official models/Qwen-Image-2.1-Turbo has matching context_in_dim=4096 in
transformer/config.json — all dimensions align. The full bf16 transformer weights are in the .safetensors shards
already in models/Qwen-Image-2.1-Turbo/transformer/.

Re: Unsloth download — No need to download it. The mismatch would persist unless you also replaced the text encoder
with their 8B GGUF version, adding ~5GB more download and significantly more complex loading code. The official
weights work perfectly as-is.

這是一篇教大家如何把 Azure Storage 從舊時代的金鑰存取，安全升級到託管身分 Managed Identity 的技術指南。

想像一下，你家大門的鑰匙就被你大大方方放在門口的鞋櫃上，任何走過路過的人只要拿到這把鑰匙就能直接進你家搬東西。這就是以前我們使用存取金鑰 Connection String 連線到 Azure Storage 的驚險狀況！

為了不讓駭客當你家是花園，我們強烈建議改用託管身分 Managed Identity。

不過設定上會和 SQL 連線不太一樣。SQL 只要在連線字串加個 useMsi=true 就能解決，但 Blob Storage 必須搭配 Blob SDK 使用 Entra ID Token，並且在 Azure RBAC 權限控管中，給予你的 Container App 相應的權限。

在目前的測試環境中，我們的後端 App 雖然有了系統分配的身分，但只有拿到拉取映像檔的 AcrPull 權限。至於檔案儲存區，依然把金鑰 AZURE_STORAGE_CONNECTION_STRING 硬塞給後端程式碼。

為了達成最高等級的資安防護，以下是推薦的升級改造方向：

1. 打造安全的基礎架構

• 私有化儲存區：Blob Container 絕對不能開啟任何人都能看的公開存取存取權限。
• 後端專屬通道：只有後端 App 可以接觸儲存區，前端完全不拿任何金鑰或 Token。
• 權限最小化原則：給後端 App 的身分授權 Storage Blob Data Contributor 角色，而且範圍只能限定在 demoproject-attachments 這個容器。這樣它就能讀、寫、刪除檔案。（千萬別偷懶給了一般權限，那樣權限太大了！）

2. 後端 Go 程式碼改版

後端改用 DefaultAzureCredential 搭配 Storage Account 的 Blob 端點。這樣做的好處是，你在本機開發時會自動用你電腦 az login 的身分；一旦部署到 Azure Container Apps 時，就會自動無縫切換成 Managed Identity，完全不用改程式碼！

你的專案已經有 azidentity 套件，不需要另外安裝。請把 config.go 中的連線字串改為帳號名稱 AccountName，並修改 internal/storage/blob.go：

// internal/storage/blob.go
import "github.com/Azure/azure-sdk-for-go/sdk/azidentity"

func NewBlobClient(accountName, containerName string) (*BlobClient, error) {
    if accountName == "" {
        return nil, nil // 如果本地環境停用附件功能就跳過
    }
    if containerName == "" {
        return nil, fmt.Errorf("azure storage container name is required")
    }

    credential, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        return nil, fmt.Errorf("create azure credential: %w", err)
    }

    serviceURL := fmt.Sprintf("https://%s.blob.core.windows.net/", accountName)
    client, err := azblob.NewClient(serviceURL, credential, nil)
    if err != nil {
        return nil, fmt.Errorf("create blob client: %w", err)
    }

    return &BlobClient{client: client, container: containerName}, nil
}

(別忘了主程式 main.go 也要改為呼叫 NewBlobClient(cfg.AzureStorage.AccountName, cfg.AzureStorage.ContainerName) )

3. 自動化部署腳本更新

部署時不再傳送一長串的金鑰，改為傳送儲存區名稱：

$STORAGE_ACCOUNT_NAME = "demostorageaccount"
$AZURE_STORAGE_CONTAINER_NAME = "demoproject-attachments"

在取得後端的服務身分 ID 後，加入 RBAC 授權：

$storageAccountId = az storage account show `
  --name $STORAGE_ACCOUNT_NAME `
  --resource-group $STORAGE_RG `
  --query id -o tsv
Assert-Success "storage account show"

$storageContainerScope = "$storageAccountId/blobServices/default/containers/$AZURE_STORAGE_CONTAINER_NAME"

az role assignment create `
  --assignee-object-id $backendPrincipalId `
  --assignee-principal-type ServicePrincipal `
  --role "Storage Blob Data Contributor" `
  --scope $storageContainerScope | Out-Null
Assert-Success "Storage Blob Data Contributor role"

最後更新環境變數設定：

@{ name = "AZURE_STORAGE_ACCOUNT_NAME";   value = $STORAGE_ACCOUNT_NAME }
@{ name = "AZURE_STORAGE_CONTAINER_NAME"; value = $AZURE_STORAGE_CONTAINER_NAME }

(小提醒：正式環境的 deploy-production.ps1、.env.example 等檔案也要同步更新，不然正式環境還會傻傻地跟你要金鑰喔！)

4. 警告！附件下載流程會壞掉！

這是大家升級時最容易踩到的超大陷阱！

Managed Identity 的通行證只有「後端 到 儲存區」有效。一旦我們把儲存區設為私有，以前那種直接把網址丟給前端網頁點擊下載的做法就會直接失效，使用者點開只會看到冷酷的 403 Forbidden 拒絕存取畫面！

該怎麼拯救下載功能？

千萬不要因為下載壞掉就把儲存區重新開放給外面的所有人看！

正確的解法是讓後端當「轉接員」，新增一個需要驗證的下載 API 路線：

GET /api/announcements/{id}/attachments/{attachmentId}/download

流程變成：前端跟後端要檔案，後端憑著自己的 Managed Identity 身份去把檔案拿回來，再傳給使用者。這樣既安全又不會斷功能！

改造總結步驟

1. 建立專屬的容器 Container。
2. 設定後端身分的 RBAC 授權。
3. 修改 Go 語言程式碼改走 DefaultAzureCredential。
4. 更新部署時的環境變數。
5. 把下載機制改為後端轉接模式（最重要的一步）。
6. 開始歡樂測試上傳、下載、刪除，確保一切正常！

Demo 資料說明

本文是一篇教學用範例。Example Company、demoproject、Azure 資源名稱、帳號、網域與 tenant 都是虛構資料，不能直接拿來連線或部署。實際使用時，請替換成自己的環境設定。

先說結論

Example Company 的開發團隊想在 Azure Container Apps 裡快速展示 Backend 功能，但暫時不需要使用既有的 Azure SQL Database，也不需要讀取既有的 demoproject-dev 資料。

這種情況可以在同一個 Container Apps Environment 裡，另外部署一個暫時的 Microsoft SQL Server container，提供一個全新的 Demo database。

這個方案的重點是：

• Demo SQL Server 是獨立的新資料庫。
• Backend 不連既有的 demoproject-dev。
• 不匯入正式或 staging 資料。
• 不使用既有 Azure SQL 的 Managed Identity、contained user 或 database roles。
• Backend、MSSQL 和 Frontend 仍然要正確設定網路、secret、storage、health check 和 CI/CD。

換句話說，這不是把原本的 Azure SQL 搬進 container，而是建立一套隔離、短期、只供 Demo 使用的資料庫環境。

為什麼需要這個方案？

假設目前的開發環境是：

cae-example-dev-001

這個 Environment 主要用來執行開發中的 Container App，但沒有連到既有 Azure SQL Private Endpoint 所需的完整 VNet 路徑。

如果 Backend 直接使用 Azure SQL，可能會遇到：

• SQL network connection timeout。
• Private Endpoint 無法連線。
• Azure SQL firewall 拒絕來源 IP。
• Managed Identity 可以取得 token，但 SQL database 沒有對應的 user 或 roles。

可是，這次 Demo 的需求並不是要存取既有資料，而是希望先讓團隊能夠：

1. 啟動 Backend API。
2. 建立一些測試資料。
3. 展示查詢、新增、修改等基本功能。
4. 讓 Frontend 能呼叫 Backend。

因此，可以把資料庫改成和 Backend 位於同一個 Container Apps Environment 的內部 MSSQL App，讓這次 Demo 不依賴既有 Azure SQL 的 Private Endpoint。

目標架構

Demo 環境可以設計成下面這樣：

Frontend 或測試工具
          │
          ▼
ca-example-backend-dev-001
          │ internal connection
          ▼
ca-example-mssql-demo-dev-001
          │ TCP 1433，僅限 internal ingress
          ▼
demoproject-demo

示範資源如下：

MSSQL 應該是獨立的 Container App，不要和 Backend 放在同一個 container。這樣可以分別更新 Backend 和資料庫，也比較容易在 Demo 結束時清理。

需要怎麼做？

第一步：建立獨立的 MSSQL Container App

使用官方 Microsoft SQL Server Linux container image，並固定版本或 digest，不要長期使用會隨時間變動的 latest tag。

MSSQL App 的基本設定應包含：

App name:    ca-example-mssql-demo-dev-001
Environment: cae-example-dev-001
Port:        TCP 1433
Ingress:     internal only
Database:    demoproject-demo

Container 需要設定：

• ACCEPT_EULA=Y
• MSSQL_PID=Developer
• MSSQL_SA_PASSWORD
• 足夠的 CPU 和 memory
• TCP 1433 target port
• readiness/startup health check

SQL Server container 通常至少需要 2 GiB memory；Demo 建議依實際啟動時間與資料量配置更多資源。

MSSQL_PID=Developer 只適合非正式 Demo，不能當成 production license 或正式 staging database。SA password 不可以寫在 Dockerfile、image、repository 或 workflow 明文中。

第二步：只開放內部網路

MSSQL App 只能使用 internal ingress：

Backend App ── internal DNS ──> MSSQL App:1433

不要把 SQL Server 的 TCP 1433 開成 public ingress，也不要讓測試人員直接從 Internet 連入。

Backend 和 MSSQL App 最簡單的做法是放在同一個 cae-example-dev-001。Backend 使用 MSSQL App 的 internal FQDN 連線，不要自行猜測 FQDN 格式，應從 Azure Container Apps 的 App 設定或 DNS 設定取得實際值。

第三步：建立專用 application login

Backend 不應使用 sa 登入。MSSQL container 第一次啟動後，應執行一次初始化流程：

1. 建立 demoproject-demo database。
2. 建立專用的 Backend application login。
3. 只授予 application login 必要的 read/write 權限。
4. 只有需要執行 schema migration 時，才授予有限的 DDL 權限。
5. 確認 Backend 不會取得 SA password。

這個 Demo SQL Server 是獨立的 SQL container，Backend 通常會使用 SQL login/password，而不是既有 Azure SQL 的 Microsoft Entra Managed Identity flow。

因此，application login 的 username 和 password 必須放在 Container App secret 或 Key Vault secret reference 中，不能放在 source code 或公開設定檔。

第四步：修改 Backend 的 connection string

Backend 原本如果使用 Azure SQL Managed Identity，可能會包含這類設定：

fedauth=ActiveDirectoryManagedIdentity
useMsi=true

切換到 Demo MSSQL 後，Backend 必須改成：

• SQL host：ca-example-mssql-demo-dev-001 的 internal FQDN。
• Port：1433。
• Database：demoproject-demo。
• Username：專用 application login。
• Password：由 secret reference 注入。
• Authentication：使用 SQL login/password。

概念上的設定如下：

sqlserver://<mssql-internal-host>:1433
  ?database=demoproject-demo
  &user=<application-user>
  &password=<secret-reference>

實際格式要依 Backend 使用的 SQL driver 調整。不要把完整 connection string 寫進 GitHub Actions log、Dockerfile 或公開的 frontend configuration。

如果 Demo SQL Server 使用 self-signed certificate，請明確決定測試環境的 TLS 設定。即使是 Demo，也不要把關閉加密或無條件信任憑證當成正式環境的解法。

第五步：建立 schema 和測試資料

全新的 demoproject-demo 不會自動有任何 table，因此需要另外準備：

• schema migration。
• 初始化 seed data。
• Demo 使用者和測試帳號。
• API 所需的 reference data。
• migration 失敗時的處理方式。

建議使用一次性的 bootstrap 或 job 初始化 database，不要讓每一個 Backend revision 在啟動時同時執行完整 migration，否則可能發生 migration race condition。

Demo data 應該是新建或去識別化資料，不要將正式資料直接複製到這個 container。

第六步：處理資料持久化

Container App 的 local filesystem 不適合當成可靠的 database storage。如果沒有持久化 volume，以下情況都可能讓資料消失：

• Container restart。
• Revision replacement。
• App 被重新建立。
• Node 或 host 發生故障。

如果 Demo 只做一次性展示，可以接受資料在環境重建後消失；如果需要保留測試結果，至少要：

• 將 SQL Server data/log 目錄掛到持久化 storage，例如 Azure Files。
• 驗證 SQL Server 在該 storage 上的 lock、I/O 和 recovery 行為。
• 設定 backup，並將 backup 放到獨立的儲存位置。
• 訂定資料保存期限。
• 確認刪除 App 或 volume 時，不會誤刪唯一一份資料。

即使使用 Azure Files，這仍然不等同於 Azure SQL Database 的 HA、backup、patching、SLA 和資料庫服務保證，所以必須把它標示為 temporary demo database。

第七步：把資料庫 bootstrap 和一般 CI/CD 分開

MSSQL App 不應該在每次 Backend push 時被刪除或重建。建議把流程分成兩部分。

一次性的 Demo bootstrap：

• 建立或更新 ca-example-mssql-demo-dev-001。
• 設定 image、secret、storage、internal ingress 和 health check。
• 等待 SQL Server ready。
• 建立 demoproject-demo、application login、schema 和 seed data。

一般 Backend CI/CD：

• 編譯 Backend。
• Push Backend image 到 ACR。
• 更新 ca-example-backend-dev-001。
• 保留 MSSQL App 和 volume，不要重新初始化 database。

Backend runtime 仍然需要自己的 ACR AcrPull。GitHub OIDC Service Principal 只負責 CI/CD 所需的 AcrPush 和 App deployment 權限，不需要 SQL database role。

如果 MSSQL image 直接從 MCR pull，必須確認 Environment 可以連到 MCR。如果團隊將 MSSQL image mirror 到 ACR，則 MSSQL App 的 runtime identity 也要另外授予 ACR AcrPull。

第八步：處理啟動順序和健康檢查

SQL Server container 通常比 API container 更久才會 ready，因此 Backend 不能假設 SQL 在啟動第一秒就能連線。

需要加入：

• MSSQL readiness/health check。
• Backend 的 connection retry 和 backoff。
• 將「SQL 尚未 ready」與「帳號密碼錯誤」分開記錄。
• SQL container restart 後，Backend 自動恢復連線。
• 避免在 logs 印出 password、完整 connection string 或 token。

az containerapp update 成功只代表 Azure 接受了 App 設定，不代表 Backend 一定已經能連到 MSSQL。必須等兩個 App 都 healthy 後，再測試 API。

Frontend 要調整什麼？

Frontend 不需要 SQL 權限，也不應取得 Backend 的 SQL credentials。

Frontend 需要確認：

• 使用正確的 Frontend image。
• 使用新的 Backend API URL。
• Nginx 或其他 web server 沒有寫死舊的 Backend hostname。
• 只有必要的 frontend secrets 被注入。

Frontend 只呼叫 Backend API；SQL connection 由 Backend 負責。

安全設定

這個 Demo 方案至少要符合以下原則：

• MSSQL App 只有 internal ingress。
• 不對 Internet 公開 TCP 1433。
• SA password 和 application password 都放在 secret。
• Backend 使用專用 application login，不使用 SA。
• 不把 SQL credentials 寫入 Git repository。
• 不讓 Frontend 取得 SQL credentials。
• 監控 container restart、CPU、memory、storage 和 backup。
• 為 Demo 設定 owner、用途和到期日。
• Demo 結束後移除 App、secret、volume 和 backup。

驗證清單

部署完成後，依照以下順序驗證：

1. MSSQL App revision 是 Healthy / Running。
2. Backend 可以解析 MSSQL App 的 internal FQDN。
3. Backend 可以建立 TCP 1433 connection。
4. demoproject-demo database 存在。
5. Backend application login 可以登入。
6. schema migration 和 seed data 成功。
7. Backend API 可以正常讀寫 Demo database。
8. Backend 重啟後仍然可以重新連線。
9. MSSQL container 重啟後，volume 和 database recovery 正常。
10. Frontend 使用正確的 Backend URL。
11. 沒有任何元件對 Internet 公開 SQL 1433。

這個方案解決什麼、不解決什麼？

Demo 結束後

這個方案應該被明確記錄為：

temporary isolated demo database

Demo 結束時，依序完成：

1. 匯出真正需要保留的 Demo 結果。
2. 停止不再使用的 Backend 和 Frontend revision。
3. 移除 SQL secrets 和 application credentials。
4. 備份或刪除 Demo database volume。
5. 刪除 MSSQL Container App。
6. 清理 ACR 中不再使用的 Demo image。
7. 確認後續部署不會誤連到 demoproject-demo。

總結

在 cae-example-dev-001 自架 MSSQL container，可以讓 Example Company 快速得到一個不依賴既有 Azure SQL 的隔離 Demo database。這個方法適合短期展示和功能驗證，但不是把正式資料庫搬進 Container App，也不是正式 production database 的替代品。

真正需要完成的工作不只是部署一個 MSSQL image，還包括：

• 建立獨立的 MSSQL App。
• 只開放 internal TCP 1433。
• 建立專用 application login。
• 將 Backend connection string 改成新的 Demo database。
• 初始化 schema 和 seed data。
• 決定是否需要持久化 storage 和 backup。
• 將 database bootstrap 與一般 Backend CI/CD 分開。
• 加入 health check、connection retry 和 logs 保護。
• 在 Demo 結束後完整清理資源。

Demo 資料說明

這是一份可以單獨閱讀的教學用範例。所有專案名稱、公司名稱、GitHub repository、Azure 資源名稱、網域、帳號與 tenant 名稱都是虛構資料，不能直接拿來連線或部署。請依照實際環境替換成自己的設定。

這份文件要解決什麼問題

Example Company 的開發團隊希望使用 GitHub Actions 做 Azure CI/CD，流程如下：

1. GitHub Actions 將程式編譯成 container image。
2. 將 image push 到 Azure Container Registry（ACR）。
3. 更新 Azure Container App，讓 App 使用新的 image。
4. Backend 啟動後，透過 Microsoft Entra Managed Identity 連線到 Azure SQL Database。

目前遇到的問題通常會長這樣：

• GitHub Actions 可以登入 Azure，但 Container App 啟動時無法從 ACR 拉 image。
• Container App 的部署指令顯示成功，但新的 revision 變成 ActivationFailed。
• Backend image 可以啟動，卻因為沒有 SQL contained user 或 database role 而無法登入資料庫。
• App 位於沒有 VNet 路徑的 Container Apps Environment，因此連不到 SQL Private Endpoint。
• Frontend 還在使用舊的 Harbor image 或舊的 Backend hostname。
• 舊的部署系統與 Azure GitHub Actions 同時執行，造成兩邊互相覆蓋部署結果。

這些現象看起來都像「權限問題」，但實際上分屬四個不同層次：

1. GitHub Actions 的 CI 身分能不能登入 Azure、push image、更新 App。
2. Container App 執行時的 Managed Identity 能不能從 ACR pull image。
3. Backend 的 Managed Identity 能不能登入 SQL Database。
4. Container Apps Environment 是否有通往 SQL Private Endpoint 的網路路徑。

Demo 情境與資源

以下名稱全部是示意資料：

• 公司：Example Company
• GitHub organization/repository：example-company/demo-backend
• Subscription：Demo-Subscription
• App/ACR Resource Group：rg-demo-stg-001
• 共用 Container Apps Environment：cae-demo-stg-001
• 共用 CAE 所在 Resource Group：rg-cae-demo-stg-001
• ACR：acrdemostg001.azurecr.io
• SQL Server：sql-demo-stg-001.database.windows.net
• SQL Database：demoproject-dev
• SQL Private Endpoint：pe-sql-demo-stg-001
• VNet：vnet-demo-stg-001

預期使用的兩個 Container App 是：

另外，情境中有一組不建議繼續使用的舊 App：

正確的目標架構

完整的部署與連線路徑應該是：

GitHub Actions
    │ OIDC，取得短期 token
    ▼
GitHub CI Service Principal
    │ AcrPush + Container App update
    ▼
Azure Container Registry
    │ image push
    ▼
Container App（共用 cae-demo-stg-001）
    │ App 自己的 system-assigned Managed Identity
    ├─ ACR AcrPull
    ├─ Key Vault secret get/list（如果 App 使用 Key Vault）
    └─ Azure SQL Entra token
          │
          ▼
    VNet + Private DNS + SQL Private Endpoint
          │
          ▼
    demoproject-dev

最重要的觀念是：

GitHub Actions 的 Service Principal 負責部署，不是執行中的 App。
真正需要 pull image 和連 SQL 的，是各個 Container App 自己的 Managed Identity。

CI/CD 的正確流程

1. GitHub Actions 使用 OIDC 登入 Azure

GitHub Actions 不應把長期的 Azure client secret 放在 repository。建議使用 OIDC：

- name: Login to Azure
  uses: azure/login@v2
  with:
    client-id: ${{ vars.AZURE_CLIENT_ID }}
    tenant-id: ${{ vars.AZURE_TENANT_ID }}
    subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

示範用的 Federated Credential subject 是：

repo:example-company/demo-backend:ref:refs/heads/main

如果 workflow 使用 GitHub Environment，例如 staging，subject 和 variables 的 scope 都要跟 GitHub Environment 的設定一致，不能只改其中一邊。

2. CI 身分將 image push 到 ACR

示範用的 image repository 是：

acrdemostg001.azurecr.io/demo-backend:<github.sha>

GitHub CI Service Principal 需要 AcrPush，但不需要 runtime AcrPull。

AcrPush = GitHub Actions 將 image 推進 ACR
AcrPull = Container App 啟動時從 ACR 拉出 image

demo-backend 在第一次成功 docker push 前可能還不會出現在 ACR repository list 中。ACR 通常會在第一次 push 時建立 repository，這不是權限錯誤。

3. CI 身分更新正確的 Container App

部署 Backend 時，target 應該是位於共用 CAE 的 App：

az containerapp update \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --image acrdemostg001.azurecr.io/demo-backend:${GITHUB_SHA}

這個指令成功只代表 Azure 接受了 App 設定更新，不代表新的 revision 一定能啟動。接下來還要檢查 runtime identity 是否能 pull image。

4. Container App 使用自己的 Managed Identity pull image

Backend 和 Frontend 都要各自完成以下設定：

• 啟用 system-assigned Managed Identity。
• 將該 App 的 identity 在 ACR scope 授予 AcrPull。
• 將 Container App registry authentication 設為 identity: system。

可用以下指令設定 registry identity：

az containerapp registry set \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --server acrdemostg001.azurecr.io \
  --identity system

Frontend App 也要使用相同方式設定，只是 --name 改為 ca-demo-frontend-dev-001。

檢查 App identity、Environment、registry 與 image：

az containerapp show \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --query "{identity:identity,environment:properties.managedEnvironmentId,registries:properties.configuration.registries[].{server:server,identity:identity},images:properties.template.containers[].image}" \
  -o json

檢查 runtime identity 是否有 ACR AcrPull：

az role assignment list \
  --assignee-object-id <BACKEND_APP_PRINCIPAL_ID> \
  --scope "$(az acr show \
    --resource-group rg-demo-stg-001 \
    --name acrdemostg001 \
    --query id -o tsv)" \
  --query "[].{role:roleDefinitionName,scope:scope}" \
  -o table

Frontend 使用自己的 <FRONTEND_APP_PRINCIPAL_ID> 查詢，不要共用 Backend 的 identity。

如果 App 沒有 AcrPull，常見結果是：

• az containerapp update 指令本身成功。
• revision 建立了，但狀態是 ActivationFailed。
• logs 或 revision events 出現 image pull、registry authentication 或 unauthorized 錯誤。

這時應該補在 Container App 的 Managed Identity，不能把 AcrPull 加到 GitHub OIDC Service Principal 代替。

Backend 存取 SQL Database

SQL 身分的分工

Backend 不應把 SQL username/password 寫進 GitHub Secrets 或 container environment。建議使用：

1. Backend App 的 system-assigned Managed Identity 取得 Microsoft Entra token。
2. SQL Entra administrator 在 demoproject-dev 建立對應的 contained user。
3. 只授予 Backend 實際需要的 database roles。

示範用的 database URL 概念如下：

sqlserver://sql-demo-stg-001.database.windows.net:1433
  ?database=demoproject-dev
  &encrypt=true
  &trustservercertificate=false
  &fedauth=ActiveDirectoryManagedIdentity
  &useMsi=true

建立 contained user 與 database roles

以下 SQL 必須由 SQL Microsoft Entra administrator 或有足夠 database 權限的管理者，在 demoproject-dev database 執行：

CREATE USER [ca-demo-backend-dev-001] FROM EXTERNAL PROVIDER;

再依照應用程式需要授予角色：

ALTER ROLE [db_datareader]
ADD MEMBER [ca-demo-backend-dev-001];

ALTER ROLE [db_datawriter]
ADD MEMBER [ca-demo-backend-dev-001];

-- 只有需要由 App 執行 schema migration 時才授予
ALTER ROLE [db_ddladmin]
ADD MEMBER [ca-demo-backend-dev-001];

這些是 SQL Database 裡的 data-plane permissions，不是 Azure Resource Group RBAC。因此 az role assignment list 看不到 db_datareader、db_datawriter 或 db_ddladmin membership。

可以在 SQL 中確認：

SELECT
    dp.name AS database_principal,
    rp.name AS database_role
FROM sys.database_role_members AS drm
JOIN sys.database_principals AS rp
    ON rp.principal_id = drm.role_principal_id
JOIN sys.database_principals AS dp
    ON dp.principal_id = drm.member_principal_id
WHERE dp.name = N'ca-demo-backend-dev-001';

Frontend 不需要 SQL 權限，也不應為 Frontend 建立 SQL contained user。

SQL 網路路徑

即使 SQL user/roles 都正確，網路不通時仍然無法連線。

Demo 情境中的網路設計是：

• pe-sql-demo-stg-001 的狀態為 Approved。
• Private DNS zone privatelink.database.windows.net 連結到 vnet-demo-stg-001。
• 共用 cae-demo-stg-001 有正確的 VNet/infrastructure subnet 路徑。
• App 放在共用 CAE，才能透過 Private Endpoint 解析並連線到 SQL。

舊的 cae-example-dev-001 沒有這條 infrastructure subnet 路徑，因此不適合作為需要存取 Private SQL 的 target。

看到下面的錯誤時，優先檢查 CAE、VNet、Private DNS 和 Private Endpoint：

Client with IP address ... is not allowed to access the server

不要為了繞過問題，直接把 SQL firewall 開成 0.0.0.0。這會把網路問題變成不必要的公開暴露。

看到下面的錯誤時，優先檢查 Managed Identity、contained user 和 database roles：

Login failed

開發者帳號能做什麼

示範開發者帳號是 demo.user@example.com，在 demo tenant 中的 UPN 示意如下：

demo_user_example.com#EXT#@exampletenant.onmicrosoft.com

示範直接授予的 Azure roles：

因此，這個帳號可以：

• 建立或更新 App。
• 將 App 放進共用 cae-demo-stg-001。
• Push image 到 ACR。

但這個帳號不能：

• 建立 Azure RBAC role assignment。
• 替新的 App 授予 ACR AcrPull。
• 修改 SQL Private Endpoint、VNet 或 SQL firewall。
• 在 demoproject-dev 建立 Entra contained user。
• 授予或修改 SQL database roles。

這是刻意的權限邊界：開發者可以部署應用程式，但不能自行擴大 App 的 Azure 權限或資料庫權限。需要新增 AcrPull 或 SQL user/roles 時，應請平台管理者或 SQL Entra administrator 處理。

舊 App 如何切換到共用 CAE

Azure Container Apps 沒有提供用 az containerapp update 直接切換 Environment 的參數。既有 App 不能像更新 image 一樣，直接從：

cae-example-dev-001

搬到：

cae-demo-stg-001

較安全的切換方式是：

1. 在共用 CAE 建立新的 Container App，或使用已準備好的 ca-demo-backend-dev-001 / ca-demo-frontend-dev-001。
2. 逐項複製必要的 environment variables、secrets、ingress、domain、scale 和 traffic 設定。
3. 啟用新 App 的 system-assigned Managed Identity。
4. 由平台管理者授予新 identity ACR AcrPull。
5. 由 SQL Entra administrator 替新的 Backend identity 建立 SQL user/roles。
6. 將 CI/CD 的 target App name 改成新的 App。
7. 驗證 revision、logs、API、Frontend URL、ACR pull 與 SQL 連線。
8. 新 App 穩定後，才考慮移除舊 App。

不要先刪除舊 App 再重建，因為可能遺失 secrets、domain、ingress、traffic 和原本的部署設定。

Frontend 的特別注意事項

Frontend 只需要：

• 從 ACR pull image。
• 連到正確的 Backend URL。
• 必要時讀取自己的 Key Vault secrets。

Frontend 不需要 demoproject-dev 的 SQL roles。

如果 Frontend revision 是 ActivationFailed，但 AcrPull 已經正確，請檢查：

• image 內的 Nginx upstream 設定。
• BACKEND_URL 或其他 Backend endpoint environment variable。
• image 是否仍然包含舊的 backend.legacy.example.invalid hostname。
• 新 image 是否真的已 push 到 ACR，且 App 使用了正確 tag。

這類問題通常是 image/configuration 問題，不是 SQL 權限問題。

建議的執行順序

平台管理者與開發團隊可以依照以下順序處理：

1. 確認 GitHub OIDC Federated Credential 的 repository、branch 和 Environment subject 正確。
2. 確認 CI Service Principal 只有部署所需的 Contributor、AcrPush 等角色。
3. 確認 Backend 和 Frontend 都位於 cae-demo-stg-001。
4. 啟用兩個 App 的 system-assigned identity。
5. 對兩個 App identity 各自授予 ACR AcrPull。
6. 執行 az containerapp registry set --identity system。
7. 由 SQL Entra administrator 建立 Backend contained user 和必要 roles。
8. 確認 CAE、VNet、Private DNS、Private Endpoint 的網路路徑。
9. 只啟用一條正式部署路徑，避免舊 pipeline 和 Azure CI/CD 同時更新同一個 App。
10. 做一次受控部署，逐項檢查 image、revision、logs、API、Frontend 和 SQL。

部署後驗證指令

確認 ACR image tag

az acr repository show-tags \
  --name acrdemostg001 \
  --repository demo-backend \
  --orderby time_desc \
  --top 5 \
  -o table

確認 Backend revision

az containerapp revision list \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --query "[].{name:name,health:properties.healthState,running:properties.runningState,traffic:properties.trafficWeight}" \
  -o table

正常情況應看到 revision 為 Healthy，且 running state 正常。若 revision 建立成功但沒有 running，請查 revision events 和 container logs。

查看 Backend logs

az containerapp logs show \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --type console \
  --tail 100

最後確認的成功條件

• GitHub Actions OIDC login 成功。
• image 成功 push 到 acrdemostg001.azurecr.io。
• Backend 和 Frontend revision 能從 ACR pull image。
• Backend revision 為 Healthy / Running。
• Backend 能以 Managed Identity 取得 SQL token。
• SQL contained user 與必要 roles 存在。
• Backend 能連線到 demoproject-dev。
• Frontend 使用新的 Backend URL。
• 舊的部署系統不會再覆蓋 Azure CI/CD 的結果。

企業或專案引進「新開發團隊」接手部署時，常見的權限混亂、安全風險與網路連線問題。主要包含以下四大核心問題：

• 權限與安全問題：避免為了部署而過度授予高風險權限（例如 Azure Owner 或 SQL 權限），並改用 GitHub Actions OIDC 取代長期保存的明文金鑰（ secrets ）。
• 責任分工不明確：清楚劃分「平台管理者」與「開發團隊」的職責邊界，防止開發團隊誤動基礎架構（如 SQL Firewall、VNet ）。
• 網路連線與架構問題：解決 Container App 因未走正確的 VNet 與 Private Endpoint 導致無法連線至 Azure SQL Database 的問題。
• 新手上手缺乏規範：提供明確的跨團隊開發指南、 CI/CD 自動化流程範本與開通檢查表，縮短團隊上手時間。

demoproject 與 ExampleOrg 只是示範名稱。正式環境使用前，必須由 平台管理者替換所有 <PLACEHOLDER> 與範例資源名稱，並確認權限範圍。

1. 先看結論

新加入的開發團隊平常只需要：

1. 取得 GitHub repository 與必要的 Azure RBAC 權限。
2. 使用平台管理者準備好的共用 Container Apps Environment。
3. 透過 GitHub Actions OIDC 登入 Azure，不使用長期 client secret。
4. Build Docker image、push 到 ACR、更新既有 Container App。
5. 透過 revision 與 logs 查看部署結果。

新加入的開發團隊不需要：

• Azure Owner。
• SQL Resource Group 的 Contributor。
• 直接修改 SQL firewall、Private Endpoint、VNet 或 Private DNS。
• 在 GitHub repository 中存放 SQL 密碼或應用程式 secrets。
• 每次部署都執行完整的基礎資源建立流程。

應用程式連接 SQL 的權限不是由 GitHub Actions Service Principal 提供， 而是由 Backend Container App 自己的 Managed Identity 在資料庫中取得。

2. Azure 服務白話說明

Azure RBAC 與 SQL 權限不是同一件事

• Azure Contributor 可以管理 Azure Resource Manager 資源，不等於可以 查詢 SQL table。
• SQL db_datareader 可以讀資料，不等於可以修改 Azure SQL Server。
• SQL db_datawriter 可以寫資料。
• SQL db_ddladmin 可以執行部分資料庫結構變更，應只授予需要執行 migration 的 Backend identity。
• SQL firewall 與 Private Endpoint 決定「網路能不能到 SQL」；資料庫 roles 只有在網路已連通後才會生效。

3. DemoProject 資源地圖

以下名稱全部是示範值：

3.1 建議的網路路徑

Backend Container App
    |
    |  共用 CAE 的 VNet 網路
    v
vnet-demoproject-stg
    |
    |  Private DNS 將 SQL hostname 解析到私有 IP
    v
SQL Private Endpoint pe-demoproject-sql-stg
    |
    v
sql-demoproject-stg / demoproject-dev

如果 Container App 位於沒有 VNet/private DNS 的獨立 CAE，它可能會透過 公網出口 IP 連線 SQL，並收到：

Client with IP address '...' is not allowed to access the server

遇到這個錯誤時，先確認 App 所在 CAE 與 DNS 路徑，不要立刻把大量公網 IP 加進 SQL firewall。

4. 權限模型

4.1 開發者與 CI 的建議權限

Container Apps Environment Joiner 應只包含：

Microsoft.App/managedEnvironments/join/action

不要為了讓團隊部署而授予共用 CAE Resource Group 的 Contributor。

4.2 平台管理者與開發團隊分工

平台管理者一次性完成：

1. 建立 App Registration 與 Service Principal。
2. 建立指定 repository、branch 或 GitHub Environment 的 Federated Credential。
3. 在 ACR scope 授予 AcrPush。
4. 在既有 Container App scope 授予更新權限。
5. 在共用 CAE scope 授予 Reader 與 Container Apps Environment Joiner。
6. 確認 App runtime Managed Identity 具備 ACR、Key Vault 與 SQL 權限。
7. 確認 App 位於正確的 VNet/private DNS CAE。

開發團隊負責：

1. 維護 GitHub Actions workflow。
2. Build Docker image。
3. Push image 到 ACR。
4. 更新既有 Container App。
5. 查看 revision 與 logs。

開發團隊不應該：

• 建立或刪除 Service Principal。
• 修改 SQL firewall、Private Endpoint、VNet 或 Private DNS。
• 將 App secrets 寫入 repository 或 workflow。
• 執行 SQL CREATE USER。
• 修改共用 CAE 的網路設定。

5. GitHub Actions OIDC

5.1 OIDC 如何運作

GitHub push to main
        |
        | GitHub 發出短期 OIDC token
        v
GitHub Actions
        |
        | azure/login@v2
        v
Microsoft Entra App / Service Principal
        |
        | Federated Credential 比對 repo + branch/environment
        | Azure RBAC 比對允許的 scope
        v
ACR push -> Container App update

OIDC 不等於自動擁有 Azure 權限：

• Federated Credential 決定「哪個 GitHub workflow 可以登入」。
• Azure RBAC 決定「登入後可以做什麼」。

5.2 新團隊專用 Service Principal

建議每個團隊、每個環境使用不同 Service Principal。不要讓所有團隊共用 一個可寫入 Staging 的 identity。

以下是示範值：

SP display name: demoproject-team-a-staging-ci
Client ID:       <APP_CLIENT_ID>
Object ID:       <SERVICE_PRINCIPAL_OBJECT_ID>
Tenant ID:       <TENANT_ID>
Subscription ID: <SUBSCRIPTION_ID>

不需要建立 client secret。

5.3 角色配置範例

以下指令只展示格式，執行前請替換所有 placeholder：

set -euo pipefail

SUB_ID="<SUBSCRIPTION_ID>"
APP_RG="rg-demoproject-stg-app"
CAE_RG="rg-demoproject-stg-cae"
CAE_NAME="cae-demoproject-stg"
ACR_NAME="acr-demoproject-stg"
SP_NAME="demoproject-team-a-staging-ci"

CAE_SCOPE="$(az containerapp env show \
  --subscription "$SUB_ID" \
  --resource-group "$CAE_RG" \
  --name "$CAE_NAME" \
  --query id -o tsv)"

ACR_SCOPE="$(az acr show \
  --subscription "$SUB_ID" \
  --resource-group "$APP_RG" \
  --name "$ACR_NAME" \
  --query id -o tsv)"

APP_ID="$(az ad app create \
  --display-name "$SP_NAME" \
  --query appId -o tsv)"

SP_OBJECT_ID="$(az ad sp create \
  --id "$APP_ID" \
  --query id -o tsv)"

az role assignment create \
  --subscription "$SUB_ID" \
  --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "AcrPush" \
  --scope "$ACR_SCOPE"

az role assignment create \
  --subscription "$SUB_ID" \
  --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Reader" \
  --scope "$CAE_SCOPE"

az role assignment create \
  --subscription "$SUB_ID" \
  --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Container Apps Environment Joiner" \
  --scope "$CAE_SCOPE"

若 CI 只更新既有 App，建議把寫入權限限制在 App resource scope：

BACKEND_SCOPE="$(az containerapp show \
  --subscription "$SUB_ID" \
  --resource-group "$APP_RG" \
  --name "ca-demoproject-backend-stg" \
  --query id -o tsv)"

az role assignment create \
  --subscription "$SUB_ID" \
  --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Contributor" \
  --scope "$BACKEND_SCOPE"

不要把 CI identity 授予：

rg-demoproject-stg-data
rg-demoproject-stg-cae 的 Contributor
demoproject-dev 的 SQL roles

5.4 Federated Credential

方案 A：只允許 main branch

適合單一 staging deploy workflow：

REPO="ExampleOrg/demoproject-backend"
SAFE_NAME="${REPO//\//-}-main"
SUBJECT="repo:${REPO}:ref:refs/heads/main"

PAYLOAD="$(jq -n \
  --arg name "$SAFE_NAME" \
  --arg subject "$SUBJECT" \
  '{
    name: $name,
    issuer: "https://token.actions.githubusercontent.com",
    subject: $subject,
    audiences: ["api://AzureADTokenExchange"]
  }')"

az ad app federated-credential create \
  --id "$APP_ID" \
  --parameters "$PAYLOAD"

方案 B：使用受保護的 GitHub Environment

新團隊建議建立 GitHub Environment staging，設定：

• Required reviewers。
• 只允許 main branch 或指定 tag。
• 將 Azure identifiers 放在 Environment variables。

Federated Credential 的 subject 改為：

repo:ExampleOrg/demoproject-backend:environment:staging

Workflow 的 deploy job 必須包含：

environment: staging

Branch subject 與 Environment subject 不要混用。Azure 會比對完整的 sub claim，字串不完全相同就會登入失敗。

PR 不可取得 write token

以下 subject 不可綁定到具有 Contributor、AcrPush 或 App write 的 identity：

repo:ExampleOrg/demoproject-backend:pull_request

PR 程式碼尚未審核，可能修改 workflow 並呼叫 Azure CLI。PR workflow 應只 執行 lint、test、build；若真的需要查詢 Azure，另建只有 Reader 的 identity。

6. GitHub Actions Workflow 範本

以下範例使用受保護的 staging Environment。若使用 main branch subject， 請移除 environment: staging，或先建立相符的 Environment Federated Credential。

name: Deploy DemoProject Backend

on:
  push:
    branches:
      - main

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Login to Azure with OIDC
        uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

      - name: Login to ACR
        run: az acr login --name acr-demoproject-stg

      - name: Build and push image
        env:
          IMAGE: acr-demoproject-stg.azurecr.io/demoproject-backend:${{ github.sha }}
        run: |
          docker build -t "$IMAGE" .
          docker push "$IMAGE"

      - name: Update existing Container App
        env:
          IMAGE: acr-demoproject-stg.azurecr.io/demoproject-backend:${{ github.sha }}
        run: |
          az containerapp update \
            --resource-group rg-demoproject-stg-app \
            --name ca-demoproject-backend-stg \
            --image "$IMAGE"

Frontend 只需要替換 image repository 與 Container App name。

6.1 PR Workflow

PR workflow 不應取得 Azure write token：

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

PR 可執行 lint、unit test、build 或不涉及 Staging 的 container build， 但不要：

• id-token: write。
• azure/login。
• Push Staging ACR。
• Update 或 delete Container App。

6.2 不要在 CI 執行完整部署腳本

完整部署腳本通常會包含 secrets、Key Vault policy、Managed Identity、 SQL 授權與首次建立資源的流程，不適合直接放進 GitHub Actions。

CI 建議只做：

OIDC login
  -> docker build
  -> ACR push
  -> containerapp update --image

既有的環境變數與 secrets 由平台管理者預先設定；App runtime 使用自己的 Managed Identity 連接 SQL 與 Key Vault。

7. SQL Database 與 Managed Identity

7.1 App runtime 才需要 SQL role

查詢 Backend App 的 Managed Identity：

az containerapp show \
  --subscription "<SUBSCRIPTION_ID>" \
  --resource-group "rg-demoproject-stg-app" \
  --name "ca-demoproject-backend-stg" \
  --query "{type:identity.type,principalId:identity.principalId}" \
  -o json

如果 Container App 被刪除後重新建立，system-assigned identity 可能改變。 管理者需要重新確認 ACR、Key Vault 與 SQL 權限。

7.2 建立 SQL contained user

以下 SQL 應由 SQL Entra administrator 或等效資料庫管理員，在 demoproject-dev 執行。將 App name 替換成實際值：

IF DATABASE_PRINCIPAL_ID(N'ca-demoproject-backend-stg') IS NULL
BEGIN
    CREATE USER [ca-demoproject-backend-stg] FROM EXTERNAL PROVIDER;
END;

ALTER ROLE [db_datareader]
ADD MEMBER [ca-demoproject-backend-stg];

ALTER ROLE [db_datawriter]
ADD MEMBER [ca-demoproject-backend-stg];

-- 只有 Backend migration 確實需要時才授予
ALTER ROLE [db_ddladmin]
ADD MEMBER [ca-demoproject-backend-stg];

CI Service Principal 不需要執行這段 SQL，也不應被加入這三個 database roles。

7.3 人員需要直接查詢資料庫

不要把 Azure Contributor 當成 SQL data access。若確實需要讓人員直接 查詢：

1. 管理者建立 Microsoft Entra security group。
2. 將需要查詢的人員加入該群組。
3. 在 demoproject-dev 建立該群組的 contained user。
4. 優先只授予 db_datareader。
5. 確認使用者有 VNet、VPN 或其他 Private Endpoint 網路路徑。

8. Private Endpoint 與 SQL Firewall

8.1 為什麼不能只新增一個 IP？

獨立的 Container Apps Environment 可能使用公網出口 IP，而且出口 IP 可能有很多個或因環境變更而改變。錯誤訊息中的 IP 只代表當次連線， 不一定是永久 IP。

使用共用 CAE 時，應該走：

Container App
  -> VNet
  -> Private DNS
  -> SQL Private Endpoint
  -> SQL Database

不要用大量公網 IP firewall 規則取代正確的網路拓撲，也不要未經核准就 建立：

start-ip-address = 0.0.0.0
end-ip-address   = 0.0.0.0

這代表允許大範圍 Azure services 存取，不是只允許本團隊。

8.2 確認 App 使用正確 CAE

$expected = "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/rg-demoproject-stg-cae/providers/Microsoft.App/managedEnvironments/cae-demoproject-stg"

az containerapp show `
  --name ca-demoproject-backend-stg `
  --resource-group rg-demoproject-stg-app `
  --query properties.managedEnvironmentId `
  -o tsv

$expected

兩個輸出必須相同。如果 App 位於沒有 VNet/private DNS 的 CAE，先請平台 管理者確認網路路徑，不要先修改 SQL firewall。

8.3 常見錯誤

9. 部署後驗證

9.1 查看 App 所在 CAE 與 revision

az containerapp show `
  --name ca-demoproject-backend-stg `
  --resource-group rg-demoproject-stg-app `
  --query "{environment:properties.managedEnvironmentId,latest:properties.latestRevisionName,ready:properties.latestReadyRevisionName}" `
  -o table

az containerapp revision list `
  --name ca-demoproject-backend-stg `
  --resource-group rg-demoproject-stg-app `
  --query "[].{name:name,health:properties.healthState,running:properties.runningState,traffic:properties.trafficWeight}" `
  -o table

9.2 查看 logs

az containerapp logs show `
  --name ca-demoproject-backend-stg `
  --resource-group rg-demoproject-stg-app `
  --type console `
  --tail 100

9.3 驗證 CI 身分

az ad app federated-credential list \
  --id "$APP_ID" \
  --query "[].{name:name,subject:subject,issuer:issuer,audiences:audiences}" \
  -o table

az role assignment list \
  --assignee-object-id "$SP_OBJECT_ID" \
  --all \
  --query "[].{role:roleDefinitionName,scope:scope}" \
  -o table

應確認：

• issuer 是 https://token.actions.githubusercontent.com。
• audience 是 api://AzureADTokenExchange。
• subject 只有指定 repo 與指定 main/environment。
• 沒有 write identity 的 pull_request subject。
• 沒有 SQL Resource Group 或共用 CAE Resource Group 的 Contributor。

10. 首次 bootstrap 與日常部署

10.1 首次 bootstrap

以下工作由平台管理者完成一次：

• 建立 ACR、CAE、Container App 或確認資源已存在。
• 建立 App Registration、Service Principal 與 Federated Credentials。
• 授予 CI 的 ACR/App/CAE 角色。
• 啟用 App system-assigned Managed Identity。
• 授予 App identity AcrPull、Key Vault get/list 與 SQL roles。
• 設定 Private Endpoint、Private DNS、custom domain 與憑證。

如果共用 CAE 暫時不存在，不要讓腳本建立沒有 VNet/private endpoint 的替代 環境；應停止流程並通知平台管理者。

10.2 日常部署

日常 CI 只需：

main push
  -> GitHub OIDC login
  -> build image
  -> push ACR
  -> update existing Container App
  -> check revision and logs

如果 App 被刪除並重新建立，請重新取得 identity，重新處理 ACR、Key Vault 與 SQL 授權。

11. 撤權與團隊交接

11.1 移除某個 repository 的信任

az ad app federated-credential list \
  --id "$APP_ID" \
  --query "[].{id:id,name:name,subject:subject}" \
  -o table

az ad app federated-credential delete \
  --id "$APP_ID" \
  --federated-credential-id "<FEDERATED_CREDENTIAL_ID>"

11.2 移除 Azure role

az role assignment delete \
  --assignee-object-id "$SP_OBJECT_ID" \
  --role "AcrPush" \
  --scope "$ACR_SCOPE"

團隊撤換時同時確認：

1. GitHub Environment/repository variables 已移除。
2. 該 repository 的 Federated Credentials 已刪除。
3. App、ACR、CAE scope 的 role assignments 已移除。
4. Container App runtime Managed Identity 沒有被誤刪。
5. Audit log 與變更紀錄已保存。

12. 新團隊開通檢查表

平台管理者

• [ ] 所有資源名稱、Subscription、tenant 與 repo 已確認。
• [ ] 每個團隊建立獨立 Service Principal。
• [ ] 只建立 main 或受保護 Environment 的 Federated Credential。
• [ ] 沒有建立 write identity 的 pull_request credential。
• [ ] ACR scope 有 AcrPush。
• [ ] 既有 App scope 有更新權限。
• [ ] 共用 CAE scope 有 Reader + Container Apps Environment Joiner。
• [ ] 沒有授予 SQL Resource Group 或共用 CAE Resource Group Contributor。
• [ ] App runtime Managed Identity 有 SQL、Key Vault、ACR 權限。
• [ ] GitHub Environment 的 reviewers 與 branch restriction 已設定。

開發團隊

• [ ] Workflow 有 permissions: id-token: write。
• [ ] environment 或 branch subject 與 Azure FIC 完全一致。
• [ ] 使用 azure/login@v2，沒有 client secret。
• [ ] Docker image 使用不可變的 commit SHA tag。
• [ ] Push 到正確 ACR repository。
• [ ] 只更新指定 Container App。
• [ ] PR workflow 沒有 Azure write token。
• [ ] 部署後確認 revision、logs 與功能。

13. 示範值替換清單

正式使用前，至少替換以下項目：

替換後請再次搜尋以下字串，確認沒有殘留示範 placeholder 或錯誤環境：

<SUBSCRIPTION_ID>
<TENANT_ID>
ExampleOrg
demoproject

14. 安全規則

1. 不要把 client secret、SQL password、JWT secret 或 storage connection string commit 到 Git。
2. 不要把 secrets 貼到 PR、Issue、聊天工具或 deployment log。
3. 不要為了快速測試把 SQL firewall 設成 0.0.0.0 - 0.0.0.0。
4. 不要把 SQL Resource Group 的 Contributor 當成 SQL data access。
5. 不要把 write-capable Azure identity 授予 pull_request。
6. 不要自行刪除共用 CAE、Private Endpoint、Private DNS 或 SQL Server。
7. 遇到錯誤時，先記錄 repository、workflow run、revision 與錯誤時間， 再請平台管理者檢查權限與網路。

15. 官方參考文件

• GitHub OIDC on Azure： https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-azure
• GitHub OIDC subject reference： https://docs.github.com/en/actions/reference/security/oidc
• Azure Login with OIDC： https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect
• Azure Container Apps with GitHub Actions： https://learn.microsoft.com/en-us/azure/container-apps/github-actions

本文件說明未來新的開發團隊如何在沒有 Azure Owner role 的情況下，使用 GitHub Actions 將 Backend 或 Frontend 部署到專案 Staging。

文件目標是讓接手環境管理工作的同仁能快速回答以下問題：

• 為什麼不需要把 Azure client secret 放進 GitHub？
• 哪些工作必須由平台管理者做一次？
• 開發團隊需要哪些最小 Azure 權限？
• GitHub OIDC、Service Principal、Federated Credential、ACR 與 Container Apps 之間如何串接？
• 為什麼 PR 不可以直接取得可寫入 Staging 的 Azure token？
• SQL 權限應該給誰？

適用環境

本文件適用目前的專案 Staging：

• Subscription： DEMO-PoC
• App/ACR Resource Group： rg-demo-stg-jpe-001
• 共用 Container Apps Environment： cae-stg-jpe-001
• ACR： acrdemostgjpe001.azurecr.io
• SQL Server： sql-stg-jpe-001.database.windows.net
• SQL Database： demoproject-dev

重要

目前的 CI 身分由環境管理者建立，開發團隊只負責維護 GitHub Actions。不要要求開發團隊取得 Owner，也不要把 SQL Resource Group 的 Contributor 給開發團隊。

1. 先看整體流程

GitHub push to main
        |
        | GitHub 發出短期 OIDC token
        v
GitHub Actions
        |
        | azure/login@v2
        v
Microsoft Entra App / Service Principal
        |
        | Federated Credential 比對 repo + branch/environment
        | Azure RBAC 比對允許的 scope
        v
Azure Container Registry (AcrPush)
        |
        | push Docker image
        v
Azure Container App
        |
        | 使用 App 自己的 Managed Identity
        v
SQL Private Endpoint -> demoproject-dev

這裡有兩個不同的身分，聲明如下：

• GitHub Actions Service Principal：用途為 Build、push Image、更新 Container App。是否應有 SQL data access：否。
• Backend Container App Managed Identity：用途為執行中的 Backend 連接 SQL、ACR、Key Vault。是否應有 SQL data access：是，僅限該 App。

GitHub Actions 的 OIDC Service Principal 只負責部署。它不應該被加入 demoproject-dev 的 SQL roles，也不應該讀取應用程式 secrets。

2. 為什麼使用 OIDC

傳統做法是把 AZURE_CLIENT_SECRET 存在 GitHub Actions Secret。這會產生長期憑證管理問題：

• secret 可能被誤印到 log。
• secret 可能忘記輪替。
• 離職或團隊更換時，需要追查 secret 被放在哪裡。

OIDC 的做法是：

1. GitHub Actions 向 GitHub OIDC provider 取得短期 token。
2. Azure 驗證 token 的 issuer、subject 與 audience。
3. 只有符合 Federated Credential 條件的 workflow 才能換取 Azure access token。
4. Azure RBAC 再決定這個 Service Principal 可以操作哪些資源。

因此 OIDC 不等於「自動擁有 Azure 權限」：

• Federated Credential：決定「哪個 GitHub workflow 可以登入」。
• Azure RBAC：決定「登入後可以做什麼」。

3. 本次已建立的 CI 身分

本次已建立以下 CI Service Principal：

Display name: demoproject-staging-ci

Client ID: 188a7d0a-30d5-4a0d-9b04-3e118d3d46e7

Object ID: 33ec7c42-e5b5-443c-aae5-e97e1e056d10

Tenant ID: 7ef65350-5b77-4958-aca5-0ccadb6bd0b7

沒有建立 client secret。

3.1 目前已授予的角色

• Scope: rg-demo-stg-jpe-001 | Role: Contributor | 目的: 目前 CI 更新 App/ACR 的過渡權限
• Scope: acrdemostgjpe001 | Role: AcrPush | 目的: 允許 Docker push 到 ACR
• Scope: cae-stg-jpe-001 | Role: Reader | 目的: 讀取共用 CAE 設定
• Scope: cae-stg-jpe-001 | Role: Container Apps Environment Joiner | 目的: 允許使用共用 CAE；只有 Microsoft.App/managedEnvironments/join/action

目前沒有授予：

• rg-cae-stg-jpe-001 的 Contributor。
• rg-data-stg-jpe-001 的任何角色。
• demoproject-dev 的 SQL role。
• Key Vault data-plane secrets 讀取權限。

rg-demo-stg-jpe-001 的 Contributor 是為了讓現有流程先能運作的過渡方案。未來新增團隊時，建議改成各 App resource scope 的 Contributor 或專用 custom role，不要複製成每個團隊都能管理整個 RG。

3.2 目前已信任的 GitHub repositories

目前只建立以下兩個 main branch Federated Credentials：

repo:NYCUITSC/demoproject-backend:ref:refs/heads/main

repo:NYCUITSC/demoproject-frontend:ref:refs/heads/main

刻意沒有建立：

• pull_request credential。
• NYCUITSC/demoproject-api credential。

demoproject-api 目前是 Frontend 用來產生 SDK 的 dependency，不是 Azure deployment repository。除非它未來真的擁有部署 job，否則不要給它 Azure write identity。

4. 新團隊的責任分工

4.1 平台/環境管理者做一次

平台管理者需要：

1. 建立該團隊專用的 App Registration 與 Service Principal。
2. 建立只允許指定 repo、branch 或 GitHub Environment 的 Federated Credentials。
3. 在正確的 ACR scope 授予 AcrPush。
4. 在指定 Container App scope 授予更新權限。
5. 在共用 CAE 授予 Reader 與 Container Apps Environment Joiner。
6. 確認 Container App 的 Managed Identity 已具備 ACR、Key Vault 與 SQL 權限。
7. 確認 App 位於正確的共用 CAE，而不是沒有 VNet/private DNS 的獨立 CAE。
8. 將 Client ID、Tenant ID、Subscription ID 提供給團隊設定 GitHub Variables。

4.2 開發團隊負責

開發團隊只需要：

1. 維護 GitHub Actions workflow。
2. 在 main 或受保護的 staging Environment 執行 deploy。
3. Build Docker image。
4. Push image 到 ACR。
5. 更新既有 Container App 的 image。
6. 查看 revision 與 logs。

開發團隊不應該：

• 建立或刪除 Service Principal。
• 修改 SQL firewall、Private Endpoint 或 Private DNS。
• 將 App secret 寫進 GitHub workflow。
• 執行 SQL CREATE USER。
• 修改共用 CAE 的 VNet 設定。

5. 未來新增團隊的標準開通流程

以下流程由平台管理者執行。每個團隊建議有自己的 Service Principal，不要讓所有團隊共用一個可寫入 Staging 的 identity。

5.1 設定資源變數

以下是目前資源的範例。新增團隊時，App name 與 repo 名稱應換成新團隊實際值。

set -euo pipefail

SUB_ID=”56b72537-d985-4530-88f3-b6ed07e71c67″

APP_RG=”rg-demo-stg-jpe-001″

CAE_RG=”rg-cae-stg-jpe-001″

CAE_NAME=”cae-stg-jpe-001″

ACR_RG=”rg-demo-stg-jpe-001″

ACR_NAME=”acrdemostgjpe001″

每個團隊使用不同名稱，例如：

demoproject-sdc-team-2027-ci

SP_NAME=”demoproject-new-team-ci”

BACKEND_CA_NAME=”ca-demo-backend-dev-jpe-001″

FRONTEND_CA_NAME=”ca-demo-frontend-dev-jpe-001″

不要把 SQL Resource Group 放進 CI role scope：

rg-data-stg-jpe-001

5.2 建立 App Registration 與 Service Principal

執行者必須具備 Entra App 建立權限。建立 Azure role assignment 另外需要 Owner 或 User Access Administrator；新加入的開發團隊不需要具備這些管理權限。

APP_ID=”$(az ad app create

–display-name “$SP_NAME” \ –query appId -o tsv)” SP_OBJECT_ID=”$(az ad sp create

–id “$APP_ID”

–query id -o tsv)”

echo “clientId: $APP_ID”

echo “servicePrincipalObjectId: $SP_OBJECT_ID”

不要用以下方式反查 App ID：

az ad app list –display-name “$SP_NAME”

因為 display name 可能重複，會拿到錯誤的 App。

5.3 授予 CI 最小必要角色

先取得 resource IDs：

APP_SCOPE=”/subscriptions/${SUB_ID}/resourceGroups/${APP_RG}”

CAE_SCOPE=”$(az containerapp env show

–subscription “$SUB_ID”

–resource-group “$CAE_RG”

–name “$CAE_NAME” \ –query id -o tsv)” ACR_SCOPE=”$(az acr show

–subscription “$SUB_ID”

–resource-group “$ACR_RG”

–name “$ACR_NAME” \ –query id -o tsv)” BACKEND_SCOPE=”$(az containerapp show

–subscription “$SUB_ID”

–resource-group “$APP_RG”

–name “$BACKEND_CA_NAME” \ –query id -o tsv)” FRONTEND_SCOPE=”$(az containerapp show

–subscription “$SUB_ID”

–resource-group “$APP_RG”

–name “$FRONTEND_CA_NAME”

–query id -o tsv)”

長期建議只給既有 App scope 的 Contributor：

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “Contributor”

–scope “$BACKEND_SCOPE”

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “Contributor”

–scope “$FRONTEND_SCOPE”

CI push ACR 需要另外的 data-plane role：

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “AcrPush”

–scope “$ACR_SCOPE”

使用共用 CAE 需要：

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “Reader”

–scope “$CAE_SCOPE”

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “Container Apps Environment Joiner”

–scope “$CAE_SCOPE”

若團隊需要由 CI 建立全新的 Container App，而不是更新既有 App，先由平台管理者評估是否真的需要 RG Contributor。可以先由管理者建立 App，再把後續 CI 限制為既有 App scope。

5.4 建立 Federated Credential

方案 A：只允許 main branch

適合簡單的單一 staging deploy workflow：

REPO=”NEW_ORG/NEW_REPO”

SAFE_NAME=”${REPO//\//-}-main” SUBJECT=”repo:${REPO}:ref:refs/heads/main”

PAYLOAD=”$(jq -n

–arg name “$SAFE_NAME”

–arg subject “$SUBJECT”

‘{name: $name, issuer: “https://token.actions.githubusercontent.com

“, subject: $subject, audiences: [“api://AzureADTokenExchange”] }’)”

az ad app federated-credential create

–id “$APP_ID”

–parameters “$PAYLOAD”

方案 B：使用受保護的 GitHub Environment（推薦新團隊）

在 GitHub repository 建立 staging Environment，設定：

• Required reviewers。
• 只允許 main branch 或指定 tag。
• 將 Azure identifiers 放在 Environment variables。

Federated Credential 的 subject 改為：

repo:NEW_ORG/NEW_REPO:environment:staging

Workflow 的 deploy job 必須設定：

environment: staging

Branch subject 與 Environment subject 不要混用。Azure 會比對完整的 sub claim，字串不完全相同就會登入失敗。

絕對不要把 write credential 給 pull_request

以下 subject 不可綁定到具有 Contributor、AcrPush 或 App write 的 identity：

repo:NEW_ORG/NEW_REPO:pull_request

PR 的程式碼尚未審核，任何可以修改 workflow 的 PR 都可能嘗試呼叫 Azure CLI。PR workflow 應只執行 lint/test/build；如果真的需要查詢 Azure，另建只有 Reader 的 CI identity。

5.5 提供 GitHub Variables

提供給團隊的只有識別資訊：

AZURE_CLIENT_ID =

AZURE_TENANT_ID = 7ef65350-5b77-4958-aca5-0ccadb6bd0b7

AZURE_SUBSCRIPTION_ID = 56b72537-d985-4530-88f3-b6ed07e71c67

不需要也不應該提供：

AZURE_CLIENT_SECRET

Client ID、Tenant ID、Subscription ID 本身不是登入密碼；真正的信任條件由 Azure Federated Credential 與 GitHub workflow permission 控制。

6. GitHub Actions Workflow 範本

以下範例使用「受保護 staging Environment」方案。若使用目前既有的 main branch credential，請移除 environment: staging，或先建立相符的 Environment Federated Credential。

name: Deploy Backend to Azure Staging

on:

push:

branches:

– main

permissions:

contents: read

id-token: write

jobs:

deploy:

runs-on: ubuntu-latest

environment: staging

steps:

– name: Checkout

uses: actions/checkout@v4

– name: Login to Azure with OIDC

uses: azure/login@v2

with:

client-id: ${{ vars.AZURE_CLIENT_ID }}

tenant-id: ${{ vars.AZURE_TENANT_ID }}

subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }} – name: Login to ACR run: az acr login –name acrdemostgjpe001 – name: Build and push image env: IMAGE: acrdemostgjpe001.azurecr.io/demo-dev-backend:${{ github.sha }}

run: |

docker build -t “$IMAGE” .

docker push “$IMAGE” – name: Update existing Container App env: IMAGE: acrdemostgjpe001.azurecr.io/demo-dev-backend:${{ github.sha }}

run: |

az containerapp update

–resource-group rg-demo-stg-jpe-001

–name ca-demo-backend-dev-jpe-001

–image “$IMAGE”

Frontend 只需要替換 Image repository 與 Container App name。

6.1 不要在 CI 直接執行完整 deploy.dev.ps1

deploy.dev.ps1 適合管理者或本機部署流程，不適合直接放入 GitHub Actions，原因包括：

• 會要求 deploy.secrets.ps1。
• 會將應用程式 secrets 套用到 Container App。
• 會包含 Managed Identity、Key Vault policy、SQL 授權等 bootstrap 工作。
• 可能嘗試建立或修改基礎資源。

CI 的正常流程應是：

OIDC login -> docker build -> ACR push -> containerapp update –image

既有的環境變數與 secrets 由平台管理者預先設定；App runtime 使用自己的 Managed Identity 連接 SQL 與 Key Vault。

6.2 PR Workflow

PR workflow 不應取得 Azure write token：

on:

pull_request:

branches:

– main

permissions:

contents: read

PR 可執行 lint、unit test、build 或不涉及 Staging 的 container build，但不要：

• id-token: write。
• azure/login。
• Push Staging ACR。
• Update 或 delete Container App。

7. 目前既有 Workflow 的注意事項

目前 demoproject-backend/.github/workflows/dev.yaml 與 demoproject-frontend/.github/workflows/dev.yaml 的 Dev 流程原本是：

1. Build/test。
2. Push 到 harbor.sdc.nycu.club。
3. 呼叫 n8n deployment webhook。

建立 Azure OIDC identity 不會自動改變這些 workflow。若要切換到 Azure Container Apps：

1. 由團隊決定是否停止 Harbor+n8n deployment。
2. 將 Azure login、ACR push、Container App update 加入新的 deploy job。
3. 確認新 workflow 的 subject 與 Federated Credential 完全一致。
4. 先在 staging Environment 做一次受審核測試。
5. 確認 revision、logs、API version 與 Frontend URL 後，再移除舊流程。

不要讓 Harbor+n8n 與 Azure CI 同時部署同一個功能環境，否則最後一個完成的 pipeline 可能覆蓋前一個結果。

8. SQL 與網路權限不要放到 CI

8.1 CI identity 不需要 SQL role

CI Service Principal 只更新 Container App image。SQL runtime access 由 Backend Container App 的 system-assigned Managed Identity 處理：

GitHub CI identity -> ACR push -> Container App update

Backend App Managed Identity -> Private Endpoint -> demoproject-dev

如果 App 被刪除後重新建立，system-assigned identity 可能改變。平台/DB 管理者需要重新確認：

• AcrPull。
• Key Vault secret get/list。
• demoproject-dev contained user。
• db_datareader、db_datawriter、必要時 db_ddladmin。

8.2 CI identity 不需要修改 SQL firewall

目前 SQL 使用 Private Endpoint 與 Private DNS。應用程式應部署到有正確 VNet 路徑的共用 cae-stg-jpe-001。

遇到以下錯誤時，不要直接把 GitHub Actions Service Principal 加到 SQL 或把 firewall 設成 0.0.0.0：

Client with IP address ‘…’ is not allowed to access the server

這通常代表 Container App 位於沒有 VNet/private DNS 的 CAE，或 hostname 解析走到公網。請先檢查 App 的 managedEnvironmentId。

9. 驗證清單

9.1 管理者驗證 App 與 Federated Credentials

az ad app federated-credential list
--id "$APP_ID"
--query "[].{name:name,subject:subject,issuer:issuer,audiences:audiences}"
-o table

應確認：

• issuer 是 https://token.actions.githubusercontent.com。
• audience 是 api://AzureADTokenExchange。
• subject 只有指定 repo 與指定 main/environment。
• 沒有 write identity 的 pull_request subject。

9.2 驗證 Azure RBAC

az role assignment list
--assignee-object-id "$SP_OBJECT_ID"
--all
--query "[].{role:roleDefinitionName,scope:scope}"
-o table

不應出現：

• Contributor at rg-cae-stg-jpe-001。
• 任何 role at rg-data-stg-jpe-001。
• 不必要的 SQL 或 Key Vault data-plane role。

9.3 團隊驗證 workflow

部署成功後確認：

az acr repository show-tags
--name acrdemostgjpe001
--repository demo-dev-backend
--orderby time_desc
--top 5
-o table

az containerapp revision list
--resource-group rg-demo-stg-jpe-001
--name ca-demo-backend-dev-jpe-001
--query "[].{name:name,health:properties.healthState,running:properties.runningState,traffic:properties.trafficWeight}"
-o table

az containerapp logs show
--resource-group rg-demo-stg-jpe-001
--name ca-demo-backend-dev-jpe-001
--type console
--tail 100

10. 常見錯誤

• AADSTS70021: No matching federated identity record found | 原因：subject、branch/environment、issuer 或 audience 不一致 | 處理方式：對照 GitHub workflow 的 trigger 與 environment，列出 FIC 逐字比較
• AuthorizationFailed | 原因：CI identity 沒有對應 scope 的 role | 處理方式：由平台管理者補上 App scope、ACR 或 CAE join role
• denied: requested access to the resource is denied | 原因：ACR 沒有 AcrPush | 處理方式：在 ACR scope 加 AcrPush，不是只加 Contributor
• Container App cannot join environment | 原因：缺 Microsoft.App/managedEnvironments/join/action | 處理方式：在共用 CAE scope 加 Container Apps Environment Joiner
• SQL Client with IP … not allowed | 原因：App 走公網，沒有走 Private Endpoint | 處理方式：檢查 App 是否位於共用 CAE，不要先加大量 firewall IP
• SQL Login failed | 原因：App Managed Identity 未建立 contained user 或 SQL role | 處理方式：查 App identity，由 DB 管理者處理，不是修改 CI role
• Image push 後沒有新 revision | 原因：workflow push 到錯誤 ACR/tag，或沒有執行 az containerapp update | 處理方式：檢查 image URI、ACR repository、revision list 與 workflow log
• Workflow 使用 tag 觸發但 Azure login 失敗 | 原因：只有 main branch subject，沒有符合 tag/environment 的 FIC | 處理方式：改成只由 main deploy，或由管理者建立精準的 tag/environment FIC

11. 團隊撤換與緊急撤權

OIDC 不使用長期 client secret，因此撤權主要是刪除 Federated Credential 或 Azure role assignment。

移除某個 repo 的信任

先列出 credential ID：

az ad app federated-credential list
--id "$APP_ID"
--query "[].{id:id,name:name,subject:subject}"
-o table

再刪除指定 credential：

az ad app federated-credential delete
--id "$APP_ID"
--federated-credential-id ""

移除 Azure role

az role assignment delete
--assignee-object-id "$SP_OBJECT_ID"
--role "AcrPush"
--scope "$ACR_SCOPE"

撤換整個團隊時，應同時：

1. 移除 GitHub Environment/repository variables。
2. 刪除該 repo 的 Federated Credentials。
3. 移除 App、ACR、CAE scope 的 role assignments。
4. 確認 Container App runtime Managed Identity 不被誤刪。
5. 保留 audit log 與變更紀錄。
6. 新團隊開通檢查表

平台管理者

• 確認目標 repo 與實際部署的 Backend/Frontend。
• 每個團隊建立獨立 Service Principal。
• 只建立 main 或受保護 Environment 的 FIC。
• 不建立 write identity 的 pull_request FIC。
• ACR scope 有 AcrPush。
• 既有 App scope 有更新權限。
• 共用 CAE scope 有 Reader + Container Apps Environment Joiner。
• 沒有授予 SQL Resource Group 或共用 CAE Resource Group Contributor。
• 確認 App runtime Managed Identity 的 SQL/Key Vault/ACR 權限。
• 將三個 Azure identifiers 提供給 GitHub Environment variables。

開發團隊

• Workflow 有 permissions: id-token: write。
• Deploy job 的 environment 或 branch subject 與 Azure FIC 完全一致。
• 使用 azure/login@v2，沒有 client secret。
• Docker image 使用不可變的 commit SHA tag。
• Push 到正確的 ACR repository。
• 只更新指定 Container App，不修改 CAE/VNet/SQL。
• PR workflow 沒有 Azure write token。
• 部署後確認 revision、logs 與功能。

13. 相關文件

• Staging 新手指南： STAGING-ONBOARDING-ZH-TW.md
• Dev 部署腳本： deploy.dev.ps1
• Backend 權限說明： demoproject-backend\docs\dev-deployment-permissions.md

你是否有過這種經歷？

某個平靜的清晨，你正端著咖啡準備開啟美好的一天，突然監報系統傳來刺眼的紅字警告：

[CRITICAL] Server Disk Space Usage: 99.8% !!!

你心裡一驚，打開伺服器一查，罪魁禍首不出所料——又是那些默默囤積、永無止境的 DB 備份檔（.bak）！

為了防止「伺服器暴斃」與「半夜被叫醒維護」的悲劇發生，今天我們就來聊聊怎麼用 Python 寫出一個聰明、安全又省心的 「.bak 檔案自動清理神器」！

備份檔的「膨脹魔咒」：為什麼硬碟總是不夠用？

在 IT 與開發者的日常裡，資料庫備份是我們的生命線。「每天備份一次」是基本常識，甚至有些高頻系統每小時都在備份。

一個每日 1GB 的 DB 備份檔，聽起來好像還好對吧？

• 1 天 = 1 GB
• 1 個月 = 30 GB
• 半年 = 180 GB！
• 1 年 = 365 GB！

如果你有好幾個資料庫，再加上歷史累積，硬碟空間很快就會像連假期間的高速公路一樣——卡到爆！

最可怕的是，許多系統管理者往往都是在硬碟被塞爆、服務掛掉的那一刻，才驚覺原來半年前的備份檔還躺在那裡吸血。

拯救硬碟！「備份檔終結者」腳本上陣

為了避免「手動刪檔刪到手軟」或是「誤刪最新備份直接準備提頭來見」，我們需要一個具備以下特性的自動化腳本：

1. 預設安全機制（Dry-Run）：先預覽「會刪哪些檔」，確認無誤再真的動手，安全感滿分！
2. 彈性門檻設定：預設保留 180 天，但也支援隨時調整成 30 天或 90 天。
3. 明確的視覺回饋：清楚標示每個檔案過期了多久（例如：185.2 天前），不再瞎猜。

靈魂核心程式碼

來看看這個輕巧又強大的 Python 腳本（clean_bak.py）：

import argparse
import sys
import time
from pathlib import Path


def cleanup_bak_files(
    target_dir: str, days: int = 180, execute_delete: bool = False
) -> None:
    target_path = Path(target_dir).resolve()

    if not target_path.exists() or not target_path.is_dir():
        print(f"❌ 錯誤：目標目錄 '{target_path}' 不存在。")
        sys.exit(1)

    now = time.time()
    files_found = 0
    files_matched = 0

    mode_label = (
        "🔥【實際刪除模式】" if execute_delete else "🛡【模擬預覽模式 (Dry-Run)】"
    )
    print(f"🎯 目標目錄: {target_path}")
    print(f"⏳ 保留天數門檻: {days} 天")
    print(f"⚙ 執行模式: {mode_label}\n" + "-" * 60)

    # 搜尋目錄下的所有 .bak 檔案
    for file_path in target_path.glob("*.bak"):
        files_found += 1
        mtime = file_path.stat().st_mtime
        file_age_days = (now - mtime) / 86400

        if file_age_days > days:
            files_matched += 1
            age_formatted = f"{file_age_days:.1f} 天前"

            if execute_delete:
                try:
                    file_path.unlink()
                    print(
                        f"🗑 [已刪除]     {file_path.name} (修改時間: {age_formatted})"
                    )
                except Exception as e:
                    print(f"⚠ [刪除失敗]   無法刪除 {file_path.name}: {e}")
            else:
                print(
                    f"👀 [將會刪除]   {file_path.name} (修改時間: {age_formatted})"
                )

    print("-" * 60)
    if not execute_delete:
        print(
            f"💡 預覽結束：在 {files_found} 個 `.bak` 檔案中，發現 {files_matched} 個超過 {days} 天老舊檔案。"
        )
        if files_matched > 0:
            print("👉 若要真正刪除這些檔案，請加上 `--delete` 參數重新執行！")
    else:
        print(
            f"🎉 清理完成：已成功釋放空間！刪除了 {files_matched} 個過期檔案。"
        )


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="預覽或刪除超過指定天數的 .bak 備份檔案。"
    )
    parser.add_argument(
        "directory",
        nargs="?",
        default=".",
        help="備份檔案所在的目錄路徑（預設為目前目錄）",
    )
    parser.add_argument(
        "--days",
        type=int,
        default=180,
        help="檔案保留天數上限（預設：180 天）",
    )
    parser.add_argument(
        "--delete",
        action="store_true",
        help="加入此參數以進行「實際刪除」操作",
    )

    args = parser.parse_args()
    cleanup_bak_files(args.directory, days=args.days, execute_delete=args.delete)

實戰演練：三步驟教你輕鬆上手

1⃣ 第一步：演習比實戰重要！先來個「預覽演練」

預設狀態下，腳本只會「看」不會「刪」。直接執行腳本，看看有哪些老古董檔案準備該下架：

python clean_bak.py /var/backups/portal

輸出結果超清晰：

🎯 目標目錄: /var/backups/portal
⏳ 保留天數門檻: 180 天
⚙ 執行模式: 🛡【模擬預覽模式 (Dry-Run)】
------------------------------------------------------------
👀 [將會刪除]   portal_backup_2026_01_01_000000.bak (修改時間: 220.4 天前)
------------------------------------------------------------
💡 預覽結束：在 25 個 `.bak` 檔案中，發現 1 個超過 180 天老舊檔案。
👉 若要真正刪除這些檔案，請加上 `--delete` 參數重新執行！

2⃣ 第二步：確定無誤，開火刪除！

確認過清單後，加上 --delete 參數，給過期檔案來個大掃除：

python clean_bak.py /var/backups/portal --delete

瞬間，硬碟空間就回歸綠色健康狀態，空氣都變得新鮮了！

3⃣ 第三步：交給排程工具，一勞永逸！

工程師的終極目標就是「能自動化就絕不手動」。設定好 Linux Crontab 或 Windows 工作排程器，讓伺服器每天半夜自動執行清理：

• Linux (Crontab)：
  0 2 * * * /usr/bin/python3 /path/to/clean_bak.py /var/backups/portal --delete >> /var/log/clean_bak.log 2>&1
每天凌晨 02:00 自動掃描並清理，還會把紀錄寫進 log 檔，安心度 100%！

經驗談：備份維護的黃金法則

1. 離線/異地備份才是真愛：本地端只保留近 30~180 天的快取備份，更久遠的歷史資料請定期同步至 AWS S3、Google Cloud Storage 或冷儲存（Glacier）。
2. 權限控管要做好：確保執行清理腳本的系統帳號只有該目錄的權限，避免權限過大衍生安全風險。
3. 定期測試還原：能還原的備份才叫備份，不能還原的只是佔空間的垃圾！ 記得定期做備份還原演練喔！

結語

別再讓爆掉的硬碟毀了你的週末！快把這套 Python 腳本部署上線，讓伺服器自動保持清爽健康吧！

你平時是用什麼方式管理資料庫備份的呢？歡迎在下方留言交流你的「硬碟省空間妙招」！

直接編輯或用 Gemini 編輯

點選任一處即可直接輸入及編輯，或選取文字，提示 Gemini 進行修改。

在體驗 LLM 驅動的命令列開發工具時，許多人喜歡在本地使用 llama-server.exe 載入 GGUF 模型（如 Qwen 系列），既能節省 API 費用又能保護隱私。

不過，當嘗試將 Pi Coding Agent 連接到本地伺服器時，常會遇到 Server is not running in llama.cpp router mode 或 OpenAI API 401 Incorrect API key 等驗證錯誤。

這篇文章記錄了完整的除錯過程與最終解決方案，幫助你快速完成本地環境設定。

問題解析

為什麼預設情況下會連線失敗？

• 端點路由不符：Pi Agent 預設對接 llama.cpp 時，期待對方開啟多模型路由（Router Mode）。如果本地只是單純啟動單一 GGUF 模型，會無法通過驗證。
• API Key 驗證攔截：如果 llama-server 開啟了 --api-key，Pi Agent 若未帶入對應金鑰，或是被預設路徑引導至 OpenAI 官方伺服器，就會觸發 401 Unauthorized 錯誤。

解決步驟

步驟一：修改 llama-server 啟動批次檔

首先，確保你的 llama-server.exe 啟動時明確設定了 API Key。

在你的批次檔（例如 start-server.bat）中加入 --api-key 參數：

set MODEL=models\Qwen3.8-27B-UD-IQ1_S.gguf
set EXE=llama-server.exe

REM Large context for long code.
set CTX=16384
set BATCH=512
set NP=1

"%EXE%" ^
  -m %MODEL% ^
  -c %CTX% ^
  -np %NP% ^
  -cmoe ^
  -b %BATCH% -ub %BATCH% ^
  -ngl 999 ^
  --port 8080 ^
  --host 127.0.0.1 ^
  --api-key 12345678 ^
  -fa on ^
  -rea off ^
  --reasoning-format none ^
  --temp 0.3 ^
  --top-p 0.8 ^
  --top-k 30 ^
  --repeat-penalty 1.08 ^
  --context-shift

上面參數微調, 參考看看: 「思維鏈坍塌」超低位元量化模型遇到無休止內部思考、自我糾正
https://stackoverflow.max-everyday.com/2026/08/chain-of-thought-collapse/

啟動後，可以使用 CMD 的 curl 測試 OpenAI 相容端點是否正常運作：

curl http://127.0.0.1:8080/v1/models -H "Authorization: Bearer 12345678"

若有正確返回 JSON 格式的模型清單，代表伺服器端設定完成。

步驟二：配置 Pi Agent 的自訂 Provider

Pi Agent 允許透過設定檔擴充自訂的 Provider。

在 CMD 中建立並開啟設定檔：

if not exist "%USERPROFILE%\.pi\agent" mkdir "%USERPROFILE%\.pi\agent"
notepad "%USERPROFILE%\.pi\agent\models.json"

貼上以下 JSON 設定。重點在於要明確指定 "api": "openai-completions"，否則 Pi 會因為缺少通訊協定設定而報錯：

{
  "providers": {
    "local-llama": {
      "baseUrl": "http://127.0.0.1:8080/v1",
      "apiKey": "12345678",
      "api": "openai-completions",
      "models": [
        {
          "id": "models\\Qwen3.8-27B-UD-IQ1_S.gguf",
          "name": "Qwen3.8-Local",
          "contextWindow": 16384,
          "maxTokens": 4096
        },
        {
          "id": "models\\gemma-4-12B-it-qat-UD-Q4_K_XL.gguf",
          "name": "Gemma-4-12B-Local",
          "contextWindow": 16384,
          "maxTokens": 4096
        }
      ]
    }
  }
}

實際測試，模型名稱寫錯，還是可以正常執行，滿神奇的。

步驟三：驗證並啟動 Pi Agent

設定完成後，在 CMD 執行模型清單檢視指令：

pi --list-models

確認列表中出現了 local-llama 相關模型。

接著建立一個專用的啟動批次檔 run-pi-qwen3.8.bat：

@echo off
pi --model "local-llama/models\Qwen3.8-27B-UD-IQ1_S.gguf"

執行 run-pi.bat 即可順利在 Pi Agent 中與本地模型進行對話！

總結

解決此問題的核心在於：

1. 本地伺服器需顯式指定 API Key 並提供 OpenAI 相容端點。
2. Pi Agent 的 models.json 必須完整填寫 api: "openai-completions" 規範。

透過自訂 Provider 機制，不僅能繞過官方 API 限制，還能靈活切換各種在地端運行的 GGUF 大語言模型！

選 llama.cpp 比較好的感覺, 可以設定的參數比較多.

ollama 與 llama.cpp 底層皆基於 C/C++ 的推論引擎，但兩者的定位、使用對象與專案目標有著本質上的不同：

關鍵差異解析

1. llama.cpp：極致效能與底層控制

• 核心價值：由 Georgi Gerganov 開發，旨在讓大型語言模型能在無 GPU 或硬體受限的普通消費級設備（如 Mac Apple Silicon、普通 PC）上高效運行。
• 優勢：
  • 細粒度控制：可直接調整 KV 快取、GPU 層數分流 (-ngl)、Context 長度、Sampler 參數等。
  • 高擴充性：身為基礎架構，被無數上層工具（如 Python 庫 llama-cpp-python、text-generation-webui 等）整合。
• 劣勢：設定繁瑣，下載的模型需要手動管理檔案路徑與參數設定。

2. Ollama：極簡體驗與模型生態

• 核心價值：將 llama.cpp 包裝成極簡化的桌面/伺服器工具，核心體驗借鑑了 Docker。
• 優勢：
  • 開箱即用：只需執行 ollama run llama3，就會自動下載模型並直接啟動對話。
  • 模型庫管理：擁有官方模型庫 (library)，下載與更新非常方便。
  • 標準化 API：預設提供開箱即用的 REST API，能 seamlessly 介接 Open WebUI、AnythingLLM 或各類本地插件。
• 劣勢：預設封裝隱藏了許多底層參數，若要高度客製化推論細節，需要透過編輯 Modelfile 完成。

該如何選擇？

• 選 Ollama：如果你想要快速在本地端跑起 LLM、連結現成的 Web UI，或是為自己的應用程式快速接上本地 API。
• 選 llama.cpp：如果你是 C/C++ 開發者、需要整合嵌入式系統、或者需要對硬體推論細節進行極致優化與自訂。