![\"golang](\"/images/2025/golang-extension/press-ctrl.png\")
\n\n語音開發這塊領域的術語確實很硬，因為它跨接了通訊協定和音訊工程。這篇文章把整個問題鏈拆解成白話文，帶你從根本理解：一個「聲音失真」的 Bug 背後，藏了多少層細節。
\n
SDP（Session Description Protocol，會話描述協定） 就像是兩支電話要接通前的「規格合約書」。
\n根據 RFC 4566 的定義，SDP 本身不傳輸任何媒體，它只負責在兩端之間協商：
\n實際流程依照 RFC 3264 定義的 Offer/Answer 模型：
\n手機（Offerer） FreeSWITCH（Answerer）\n | |\n | ── SDP Offer ────────> | 「我支援 PCMU(0) 和 PCMA(8)」\n | |\n | <── SDP Answer ─────── | 「好，我選 PCMU(0)」\n | |\n | ═══ 語音串流 (RTP) ══ | 雙方用同一個 Codec 通話\n\n合約類比： 手機開出條件清單，後端選一個接受，通話才正式開始。
\n
PCMU 和 PCMA 都是 G.711 標準的成員（ITU-T Recommendation G.711），但編碼演算法完全不同：
\n| \n | PCMU（μ-law） | \nPCMA（A-law） | \n
|---|---|---|
| SDP Payload Type | \n0 | \n8 | \n
| 主要使用地區 | \n北美、日本、台灣 | \n歐洲、部分亞洲 | \n
| 壓縮曲線 | \nμ-law 對數壓縮 | \nA-law 對數壓縮 | \n
| 取樣率 | \n8000 Hz | \n8000 Hz | \n
| 位元深度 | \n8-bit | \n8-bit | \n
兩者的 壓縮轉換表（量化映射）完全不同。同樣一個 8-bit 數值，用 μ-law 解出來是 A，用 A-law 解出來是 B——差異可以高達幾倍的振幅。
\nSDP 提供： PCMU (0) + PCMA (8)\n手機選擇： PCMA（A-law）\n後端解碼： 永遠用 μ-law 硬解\n結果： A-law 資料被當成 μ-law 解 → 完全錯誤的 PCM → 機器雜音 / 爆音這就像把德文稿子交給只看英文的翻譯機——讀出來的「意思」完全亂掉。映射錯誤導致波形振幅異常噴發，聽起來就是刺耳的雜音加上音量爆炸。
\n在 answer_service.go 修改 SDP 回應，只列出 PCMU：
// Before（提供兩種 Codec，讓對方選）\nm=audio 10000 RTP/AVP 0 8\n\n// After（只提供 PCMU，對方沒得選）\nm=audio 10000 RTP/AVP 0手機端收到 Answer 後，只能用 PCMU 發送。後端解碼對了，聲音立刻清晰。
\n修好之後你可能會發現：聲音變小了。
\n這其實是「正常」。之前的「大聲」是解碼錯誤造成的異常振幅（雜訊）；現在的 PCMU 正確解碼後，原始語音的振幅才是它本來的大小。
\n\n\n振幅（Amplitude）： 音訊波形的高度，直接對應聲音大小。高度越高，能量越強，聲音越大。
\n
ASR（自動語音辨識）就像人耳，聲音太小會聽不清楚，辨識準確率會下降。
\n解法：在輸入 ASR 前加一層音訊處理元件 VolumeAdjustedAudioProcessor，對每個音訊 frame 做增益放大：
輸入音訊 → VolumeAdjustedAudioProcessor (gain: 3.0) → ASR Engine\n └─ 每個 sample × 3.0 → 振幅放大 3 倍Gain（增益） 就是那個倍數：
\n1.0 = 原始音量（不變）2.0 = 音量翻倍3.0 ~ 4.0 = 進一步放大，提升 ASR 辨識率\n\n⚠️ Gain 不能無限調高，過大會讓波形「削頂（clipping）」，反而產生新的失真。
\n
| 名詞 | \n白話解釋 | \n結果 | \n
|---|---|---|
| SDP | \n通話前的規格合約 | \n已修正，強制統一 PCMU | \n
| PCMU | \nG.711 μ-law，北美/台灣標準編碼 | \n現在唯一使用的 Codec | \n
| Codec Mismatch | \n說不同語言導致的解碼錯誤 | \n已解決，根本原因修除 | \n
| 失真 / 爆音 | \n解碼錯誤造成的波形異常 | \n已消除 | \n
| Gain | \n音量放大倍率 | \n從 2.0 調高，提升 ASR 辨識率 | \n
開發時，已經習慣長按 ctrl+類名或函式名稱，讓編輯器自動跳轉到該類別或函式的定義位置來快速查看程式碼的實作細節
\n
由於我改用 mise 來管理 golang 版本，導致 vscode golang extension 無法正確辨識 golang 的執行檔位置，長按 ctrl + 點擊類名或函式名稱時就沒反應
\nctrl + , 快速打開設定頁面，搜尋 go.alternateTools 並點擊在 settings.json 中編輯
![\"alter](\"/images/2025/golang-extension/alternate-tool.png\")
直接在 settings.json 中加入以下設定
\n....\n\"go.alternateTools\": {\n \"go\": \"/Users/young/.local/share/mise/shims/go\"\n}在 reload window 後，重新長按 ctrl + 點擊類名或函式名稱，就可以順利跳轉到該定義位置了
\n", "tags": [ "Golang" ] }, { "id": "https://akebee.com/process-thread-coroutine/", "url": "https://akebee.com/process-thread-coroutine/", "title": "Process, Thread, Coroutine，A Hands-on Experiment to Conquer Concurrency in Python and Golang", "date_published": "2025-12-12T08:52:26.000Z", "content_html": "\n\n引言： 為了真正理解現代程式設計中的 Concurrency（併發）概念，稍微複習了 Process, Thread, Coroutine 之間的關係，並透過程式碼徹底比較 Python 與 Golang 在處理 CPU-bound 和 I/O-bound 任務時的效能差異。結果非常驚人，清晰地揭示了 Python GIL 的限制與 Golang Runtime 的優勢。
\n
從資源開銷和獨立性的角度來看，併發執行單元的層次結構由大到小排序如下：
\n| 概念 | \n資源開銷 / 獨立性 | \n核心特性 | \n適用場景 | \n
|---|---|---|---|
| External Service / Daemon | \n系統級最大 (完全獨立) | \n完全獨立的執行環境，透過網路或 IPC 進行通訊。 | \n微服務架構、背景常駐服務、系統資源隔離。 | \n
| Process (行程/進程) | \n最大（獨立記憶體） | \nOS 調度，可繞過 GIL 實現 Parallelism (並行)。 | \nCPU-Bound 任務 | \n
| Thread (執行緒/線程) | \n較小（共享記憶體） | \nOS 調度，受 Python GIL 限制，無法並行運算。 | \nI/O-Bound 任務 (等待時釋放 GIL) | \n
| Coroutine (協程/Goroutine) | \n最小（單 Thread 內切換） | \n程式控制，開銷極低，實現 Non-blocking (非阻塞) Concurrency。 | \n高併發 I/O | \n
| 特性 | \nCPU-bound (CPU 密集型) | \nI/O-bound (I/O 密集型) | \n
|---|---|---|
| 主要工作 | \n計算、邏輯處理 | \n等待外部資源 (硬碟/網路) | \n
| 效能瓶頸 | \nCPU 速度、核心數量 | \nI/O 設備速度、網路延遲 | \n
| CPU 使用率 | \n高 (接近 100%) | \n低 (CPU 經常閒置) | \n
| 優化策略 | \n多行程 (Multi-processing) | \n多執行緒 (Multi-threading) 或 非同步 I/O | \n
| Python 考量 | \n受到 GIL 限制，需用多行程 | \nGIL 在 I/O 等待時釋放，適合多執行緒/非同步 | \n
本次測試透過兩種典型的工作負載，看看 Python GIL 與 Golang 的高效能併發機制對比
\n情景 A：CPU-Bound 任務 (cpu_bound_task):
情景 B：I/O-Bound 任務 (io_bound_task / async_io_bound_task):
time.sleep(DELAY_IO) 模擬網路延遲或檔案讀寫等待（0.5 秒）。設置了 8 個並發任務 (NWORKERS=8)，並將其以三種不同的方式運行：
\n| 測試機制 | \n邏輯目標 | \n測試目的 | \n預期結果 | \n
|---|---|---|---|
| Process | \nCPU-Bound | \n驗證並行： 能否利用 8 個核心。 | \n總時間 ≈0.1s (單核時間 ÷8) | \n
| Thread / Asyncio | \nCPU-Bound | \n驗證 GIL 限制： 是否會因 GIL 而變成串行。 | \n總時間 ≈0.4s (所有任務時間相加) | \n
| Asyncio / Goroutine | \nI/O-Bound | \n驗證切換效率： 能否在 0.5s 內完成 8 個任務。 | \n總時間 ≈0.5s (最長任務時間) | \n
multiprocessing.Process: 啟動獨立行程，這是 Python 唯一能繞過 GIL 實現 CPU 並行的方法。asyncio.to_thread: 處理 Asyncio CPU 任務的標準做法，結果將揭示其後台執行緒池仍受 GIL 限制。通過比較 Process (並行) 與 Thread/Asyncio (串行) 在 CPU 任務上的時間差異，可直接測量 GIL 導致的效能差距。
\nimport time\nimport os\nfrom multiprocessing import Process\nfrom threading import Thread\nimport asyncio\n\n# --- 參數設定 ---\n# 測試執行緒/行程/協程的數量\nNUM_WORKERS = 8\n# CPU 密集型任務的強度 (數值越大，運算時間越久，請根據您的電腦性能調整)\nN_CPU = 2\n# I/O 密集型任務的模擬等待時間\nDELAY_IO = 0.5\n\n# --- 任務定義 ---\n\n# 1. CPU 密集型任務：耗時的計算\ndef cpu_bound_task(n):\n \"\"\"佔用 CPU 的運算任務\"\"\"\n i = 0\n while i < n * 500000:\n i += 1\n # 進行簡單的數學運算以佔用 CPU\n x = 51000**0.5 \n print(f\"[{os.getpid()}] CPU-Bound Task finished.\")\n\n# 2. I/O 密集型任務：模擬網路等待\ndef io_bound_task(delay):\n \"\"\"模擬網路請求，等待指定時間\"\"\"\n time.sleep(delay) \n print(f\"[{os.getpid()}] I/O-Bound Task finished after {delay}s.\")\n\n# 3. I/O 密集型任務的協程版本\nasync def async_io_bound_task(delay):\n \"\"\"模擬網路請求，使用 await 非阻塞等待\"\"\"\n await asyncio.sleep(delay) \n print(f\"[Asyncio] I/O-Bound Task finished after {delay}s.\")\n\n# 4. CPU 密集型任務的協程版本 (修復：使用 to_thread 將阻塞任務拋給執行緒池)\nasync def async_cpu_bound_task(n):\n \"\"\"將 CPU 運算拋給後台執行緒池，避免阻塞事件循環\"\"\"\n # 使用 asyncio.to_thread 將同步函數 cpu_bound_task 在單獨的執行緒中運行\n # 這是 Asyncio 處理 CPU 密集型任務的標準做法。\n await asyncio.to_thread(cpu_bound_task, n) \n print(f\"[Asyncio] CPU-Bound Task finished.\")\n\n# --- 運行函數 ---\n\n# A. 行程 (Process) 執行\ndef run_processes(task, *args):\n start_time = time.time()\n processes = []\n for _ in range(NUM_WORKERS):\n p = Process(target=task, args=args)\n processes.append(p)\n p.start()\n for p in processes:\n p.join()\n end_time = time.time()\n return end_time - start_time\n\n# B. 執行緒 (Thread) 執行\ndef run_threads(task, *args):\n start_time = time.time()\n threads = []\n for _ in range(NUM_WORKERS):\n t = Thread(target=task, args=args)\n threads.append(t)\n t.start()\n for t in threads:\n t.join()\n end_time = time.time()\n return end_time - start_time\n\n\n# C. 協程 (Asyncio) 執行\ndef run_asyncio(task, *args):\n start_time = time.time()\n \n # 1. 創建協程列表 (它們是協程對象)\n tasks = [task(*args) for _ in range(NUM_WORKERS)]\n \n # 2. 定義一個頂層協程，用來等待所有任務完成\n async def main_runner():\n # await 必須在 async 函數內，用於等待 Future 完成\n await asyncio.gather(*tasks)\n\n # 3. 運行事件循環，傳遞頂層協程 (main_runner() 返回 Coroutine Object)\n asyncio.run(main_runner())\n \n end_time = time.time()\n return end_time - start_time\n\n# --- 主程式執行區 ---\nif __name__ == \"__main__\":\n print(f\"--- Python 併發機制測試 (N={NUM_WORKERS}, CPU_N={N_CPU}, IO_D={DELAY_IO}) ---\")\n\n # 1. CPU 密集型任務比較 (應比較 Process vs Thread vs Asyncio)\n print(\"\\n[--- CPU 密集型測試 (計算運算) ---]\")\n \n # 【Python 1】Process：**最適用**，應最快，因繞過 GIL\n time_p_cpu = run_processes(cpu_bound_task, N_CPU)\n print(f\"Process (CPU) Total Time: {time_p_cpu:.4f}s\\n\")\n \n # 【Python 2】Thread：**不適用**，應最慢，因受 GIL 限制\n time_t_cpu = run_threads(cpu_bound_task, N_CPU)\n print(f\"Thread (CPU) Total Time: {time_t_cpu:.4f}s\\n\")\n \n # 【Python 3】Asyncio：**不適用**，應與 Thread 接近，因單執行緒阻塞\n time_a_cpu = run_asyncio(async_cpu_bound_task, N_CPU)\n print(f\"Asyncio (CPU) Total Time: {time_a_cpu:.4f}s\\n\")\n\n # 2. I/O 密集型任務比較 (應比較 Thread vs Asyncio)\n print(\"\\n[--- I/O 密集型測試 (網路等待) ---]\")\n \n # 【Python 4】Thread：適用，因 I/O 等待時能釋放 GIL\n time_t_io = run_threads(io_bound_task, DELAY_IO)\n print(f\"Thread (I/O) Total Time: {time_t_io:.4f}s\\n\")\n \n # 【Python 5】Asyncio：**最適用**，應最快，因切換開銷最小\n time_a_io = run_asyncio(async_io_bound_task, DELAY_IO)\n print(f\"Asyncio (I/O) Total Time: {time_a_io:.4f}s\\n\")\n \n # Process 處理 I/O 任務通常開銷較大，一般不使用，故不列入主要比較。輸出結果：
\n--- Python 併發機制測試 (N=8, CPU_N=2, IO_D=0.5) ---\n\n[--- CPU 密集型測試 (計算運算) ---]\n[41883] CPU-Bound Task finished.\n[41884] CPU-Bound Task finished.\n[41886] CPU-Bound Task finished.\n[41888] CPU-Bound Task finished.\n[41885] CPU-Bound Task finished.\n[41887] CPU-Bound Task finished.\n[41889] CPU-Bound Task finished.\n[41890] CPU-Bound Task finished.\nProcess (CPU) Total Time: 0.1576s\n\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\nThread (CPU) Total Time: 0.4108s\n\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[Asyncio] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[Asyncio] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[41879] CPU-Bound Task finished.\n[Asyncio] CPU-Bound Task finished.\n[Asyncio] CPU-Bound Task finished.\n[Asyncio] CPU-Bound Task finished.\n[Asyncio] CPU-Bound Task finished.\n[Asyncio] CPU-Bound Task finished.\n[Asyncio] CPU-Bound Task finished.\nAsyncio (CPU) Total Time: 0.4211s\n\n\n[--- I/O 密集型測試 (網路等待) ---]\n[41879] I/O-Bound Task finished after 0.5s.\n[41879] I/O-Bound Task finished after 0.5s.\n[41879] I/O-Bound Task finished after 0.5s.\n[41879] I/O-Bound Task finished after 0.5s.\n[41879] I/O-Bound Task finished after 0.5s.\n[41879] I/O-Bound Task finished after 0.5s.\n[41879] I/O-Bound Task finished after 0.5s.\n[41879] I/O-Bound Task finished after 0.5s.\nThread (I/O) Total Time: 0.5069s\n\n[Asyncio] I/O-Bound Task finished after 0.5s.\n[Asyncio] I/O-Bound Task finished after 0.5s.\n[Asyncio] I/O-Bound Task finished after 0.5s.\n[Asyncio] I/O-Bound Task finished after 0.5s.\n[Asyncio] I/O-Bound Task finished after 0.5s.\n[Asyncio] I/O-Bound Task finished after 0.5s.\n[Asyncio] I/O-Bound Task finished after 0.5s.\n[Asyncio] I/O-Bound Task finished after 0.5s.\nAsyncio (I/O) Total Time: 0.5020spackage main\n\nimport (\n \"fmt\"\n \"time\"\n \"runtime\"\n \"sync\" \n)\n\n// --- 參數設定 (應與 Python 保持一致) ---\nconst NUM_WORKERS = 8\nconst N_CPU = 2 \nconst DELAY_IO = 0.5\n\n// --- 任務定義 ---\n\n// 1. CPU 密集型任務 (Goroutine)\nfunc cpuBoundTask(n int, id int, wg *sync.WaitGroup) {\n defer wg.Done()\n i := 0\n for i < n * 500000 {\n i++\n _ = 51000.0 * 51000.0 / 0.5 \n }\n fmt.Printf(\"[%d] CPU-Bound Goroutine %d finished.\\n\", id, id)\n}\n\n// 2. I/O 密集型任務 (Goroutine)\n// 參數 delay_ms 必須是 int 類型，代表毫秒\nfunc ioBoundTask(delay_ms int, id int, wg *sync.WaitGroup) {\n defer wg.Done()\n \n // 傳入的 delay_ms 是毫秒，使用 time.Millisecond 進行休眠\n time.Sleep(time.Duration(delay_ms) * time.Millisecond) \n \n // 輸出時，將毫秒轉換回秒\n fmt.Printf(\"[%d] I/O-Bound Goroutine %d finished after %.1fs.\\n\", id, id, float64(delay_ms)/1000.0)\n}\n\n// --- 運行函數 ---\nfunc runGoroutines(task func(int, int, *sync.WaitGroup), task_param int) float64 {\n start := time.Now()\n var wg sync.WaitGroup\n \n for i := 1; i <= NUM_WORKERS; i++ {\n wg.Add(1) \n go task(task_param, i, &wg) \n }\n wg.Wait() \n \n elapsed := time.Since(start)\n return elapsed.Seconds()\n}\n\n// --- 主程式執行區 ---\nfunc main() {\n fmt.Printf(\"--- Golang Goroutine 測試 (CPUs: %d, N=%d) ---\\n\", runtime.NumCPU(), NUM_WORKERS)\n \n // 1. CPU 密集型任務比較\n fmt.Println(\"\\n[--- CPU 密集型測試 (計算運算) ---]\")\n \n // 【Go 1】Goroutine (CPU)：**適用**，應與 Python Process 接近，因能利用多核\n time_g_cpu := runGoroutines(cpuBoundTask, N_CPU)\n fmt.Printf(\"Goroutine (CPU) Total Time: %.4f seconds.\\n\", time_g_cpu)\n\n // 2. I/O 密集型任務比較\n fmt.Println(\"\\n[--- I/O 密集型測試 (網路等待) ---]\")\n \n //【Go 2】Goroutine (I/O)：**最適用**，應與 Python Asyncio 接近，因切換極快，Goroutine (I/O)：輕量級併發\n // 修正點：將 DELAY_IO (0.5) 乘以 1000 轉為毫秒 (500)，並強制轉換為 int\n time_g_io := runGoroutines(ioBoundTask, int(DELAY_IO * 1000))\n fmt.Printf(\"Goroutine (I/O) Total Time: %.4f seconds.\\n\", time_g_io)\n}輸出結果：
\n--- Golang Goroutine 測試 (CPUs: 10, N=8) ---\n\n[--- CPU 密集型測試 (計算運算) ---]\n[8] CPU-Bound Goroutine 8 finished.\n[4] CPU-Bound Goroutine 4 finished.\n[2] CPU-Bound Goroutine 2 finished.\n[1] CPU-Bound Goroutine 1 finished.\n[3] CPU-Bound Goroutine 3 finished.\n[6] CPU-Bound Goroutine 6 finished.\n[5] CPU-Bound Goroutine 5 finished.\n[7] CPU-Bound Goroutine 7 finished.\nGoroutine (CPU) Total Time: 0.0008 seconds.\n\n[--- I/O 密集型測試 (網路等待) ---]\n[1] I/O-Bound Goroutine 1 finished after 0.5s.\n[3] I/O-Bound Goroutine 3 finished after 0.5s.\n[8] I/O-Bound Goroutine 8 finished after 0.5s.\n[5] I/O-Bound Goroutine 5 finished after 0.5s.\n[6] I/O-Bound Goroutine 6 finished after 0.5s.\n[2] I/O-Bound Goroutine 2 finished after 0.5s.\n[4] I/O-Bound Goroutine 4 finished after 0.5s.\n[7] I/O-Bound Goroutine 7 finished after 0.5s.\nGoroutine (I/O) Total Time: 0.5024 seconds.Python 輸出分散且量多，源於其 I/O 模型的特性：
\nprint() 預設是行緩衝，輸出一旦遇到換行符 (\\n)，會立即送往作業系統。總結： Python 的輸出是分散的，因為它會即時顯示每個執行單元的完成狀態。
\nGolang 輸出集中且量少，體現了 Go Runtime 的設計優化：
\n總結： Golang 的輸出是集中的，是 Go Runtime 為了提高效率而進行的 I/O 批次處理。
\n| 機制 | \n總時間 (Total Time) | \n效能比 (相對於 Goroutine) | \n結論 | \n
|---|---|---|---|
| Golang Goroutine | \n0.0007s∼0.0008s | \n基線 (1.0x) | \n極致並行： Goroutine 展現了 Go Runtime M:N 排程器的超低延遲和高效能核心利用。 | \n
| Python Process | \n0.1576s | \n≈200x 慢 | \n高開銷並行： 雖然實現並行，但 Process 啟動和資源隔離的成本導致總耗時遠高於 Goroutine。 | \n
| Python Thread/Asyncio | \n≈0.41s | \n≈500x 慢 | \nGIL 懲罰： 總時間鎖定在單核運算時間，證明 GIL 成功地將 8 核心系統的效能退化為串行。 | \n
| 機制 | \n總時間 (Total Time) | \n總結分析 | \n
|---|---|---|
| Golang Goroutine | \n≈0.501s | \n基準： 高效且穩定，切換開銷可忽略。 | \n
| Python Asyncio | \n≈0.502s | \n極致對標： 證明 Python 協程在 I/O 任務上的效率與 Goroutine 處於同一量級。 | \n
| Python Thread | \n≈0.506s | \n微小開銷： 證實傳統 OS 執行緒的 Context Switching 成本高於用戶級協程。 | \n
Go 和 Python 在終端機輸出上的顯著差異，體現了各自語言對 I/O 策略的選擇：
\n本次量化測試提供了選擇語言架構的最終依據：
\n建立 Rust 資料夾
\nmkdir my_rust_lib\ncd my_rust_lib建立 Cargo.toml（Rust 的設定檔
\nCargo.toml 內容：\n[package]\nname = \"my_rust_lib\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[lib]\nname = \"my_rust_lib\"\ncrate-type = [\"cdylib\"] # ← 關鍵！編譯成動態庫供 \nPython 使用\n\n[dependencies]\npyo3 = { version = \"0.26\", features =[\"extension-module\"] } # ← PyO3 橋接建立 pyproject.toml（Python 的設定檔）
\n[build-system]\nrequires = [\"maturin>=1.8,<2.0\"]\nbuild-backend = \"maturin\"\n\n[project]\nname = \"my_rust_lib\" \nversion = \"0.1.0\"\ndescription = \"A Python extension module written in Rust using PyO3\"\nrequires-python = \">=3.11,<3.15\"\n\n[tool.maturin]\nfeatures = [\"pyo3/extension-module\"]\ninclude = [\"my_rust_lib/**/*\"]features = ["pyo3/extension-module"] 就是告訴編譯器靶crate 打包成可被 python import 的模組
如果沒加，編譯後的 .so 會是「一般動態函式庫」而不是「Python extension module」。在 Python 直接 import your_module 時可能會失敗，因為缺少 PyO3 預期的初始化符號。
\n\n\n如果只是做一個純 Rust 套件，然後透過 FFI (cffi, ctypes) 去 call .so，那就不需要 pyo3/extension-module。
\n
src/lib.rs 結構：\nuse pyo3::prelude::*; // ← 導入 PyO3\n\n....編譯並輸出 wheel 套件檔案，會在 target/wheels/ 產生 .whl 安裝包。
\nmaturin build --release -m my_rust_lib/Cargo.toml![\"target\"](\"/images/2025/rust-compile/target.png\")
把你剛編譯出來的 Rust-Python 模組 wheel，強制安裝到當前 Python 環境。
\nuv pip install --force-reinstall my_rust_lib/target/wheels/my_rust_lib-*.whl直接點 import 的類，或是直接去 .venv/lib/python3.13/site-packages/ 應就能看到編譯好的模組檔
![\"lib\"](\"/images/2025/rust-compile/lib.png\")
就可以在 Python 中直接調用 Rust 編譯好的模組
\nimport my_rust_lib # ← 直接導入，就像普通 Python 模組┌─────────────────────────────────────────────────┐\n│ Python 程式 │\n│ import my_rust_lib │\n│ my_rust_lib.correct_text(...) │\n└──────────────────┬──────────────────────────────┘\n │ (Python C API)\n ↓\n┌─────────────────────────────────────────────────┐\n│ PyO3 橋接層 │\n│ - 型別轉換 │\n│ - 錯誤處理 │\n│ - GIL 管理 │\n└──────────────────┬──────────────────────────────┘\n ↓\n┌─────────────────────────────────────────────────┐\n│ Rust 編譯的機器碼 │\n│ my_rust_lib.so │\n│ - correct_text() [native code] │\n│ - pinyin 轉換 [native code] │\n│ - edit_distance [native code] │\n└─────────────────────────────────────────────────┘所以走一次流程大概就是
\n.venv/lib/python3.13/site-packages/my_rust_lib/Rust 快的原因：
\nPython 慢的原因：
\n比如：
\n# Python 要判斷 int/float/str，甚至要拋錯\nresult = a + b Rust 編譯期就知道 a 和 b 是什麼型別，直接生成對應的機器碼
\n// Rust 在編譯期就確定型別，CPU 直接執行加法\nlet result = a + b;即使有 4 個 CPU 核心，同一時間只能有 1 個線程執行 Python 程式碼
\nPython：
\n\n\nThread 1: 執行中 🟢
\n
\nThread 2: 等待 GIL 🔴
\nThread 3: 等待 GIL 🔴
\nThread 4: 等待 GIL 🔴
Rust 無 GIL： 可以真正利用多核 CPU
\n\n\nThread 1: 執行中 🟢
\n
\nThread 2: 執行中 🟢
\nThread 3: 執行中 🟢
\nThread 4: 執行中 🟢
但 Python 的優勢是開發速度快！ 所以我們用 Rust 重寫需要盡可能增加速度的部分，其他部分就保留 Python 👍
\n\n\n「Rust for speed, Python for productivity」
\n
結論:Rust 靠「靜態型別 + 編譯最佳化 + 真正並行 + 記憶體安全」贏在效能；Python 靠「動態型別 + 解譯執行 + GIL」輸在速度，但贏在生態系和開發速度。兩者搭配常常是最好的解法。
\n", "tags": [ "Python", "Rust", "PyO3" ] }, { "id": "https://akebee.com/docker-init-db-tables/", "url": "https://akebee.com/docker-init-db-tables/", "title": "docker compose 啟動服務時，自動初始化(init)資料庫跟資料(seed) - PostgreSQL", "date_published": "2025-10-03T09:00:15.000Z", "content_html": "以往在用 docker compose 快速啟動服務，常常會遇到：
\n比如在某專案中，固定會有個 products 的資料表，並且每次部署到新主機第一次啟動時，去打端點都一定會跳sqlalchemy.exc.ProgrammingError: (psycopg2.errors.UndefinedTable) relation "table_name" does not exist 資料表不存在的錯誤，都得透過手動執行 Python 腳本 create_db_data.py + SQLAlchemy 語法來建表與插入資料
PostgreSQL 官方 image 內建的 docker-entrypoint.sh 會在容器初始化（第一次建立資料 volume）時，自動執行 /docker-entrypoint-initdb.d/ 目錄底下的 .sql 或 .sh 檔案。
只要是在 /docker-entrypoint-initdb.d/ 的 .sql 或 .sh 檔案，Postgres 會在 第一次啟動資料庫 時自動執行
創建 init-scripts 資料夾並在底下建立了三個 SQL 檔
project/\n├─ docker-compose.yaml\n├─ init-scripts/\n│ ├─ 001_enable_extensions.sql\n│ ├─ 002_create_table.sql\n│ └─ 003_seed_data.sql\n...在001_enable_extensions.sql中，確保 pgcrypto 可用（因為用了 gen_random_uuid()）產生 UUID
CREATE EXTENSION IF NOT EXISTS \"pgcrypto\";在002_create_table.sql，寫建立資料表的 SQL
CREATE TABLE IF NOT EXISTS products (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n name VARCHAR(100) UNIQUE NOT NULL,\n description TEXT,\n price NUMERIC(10,2) NOT NULL,\n in_stock BOOLEAN NOT NULL DEFAULT TRUE,\n created_at TIMESTAMP NOT NULL DEFAULT now(),\n updated_at TIMESTAMP NOT NULL DEFAULT now()\n);插入固定資料
\nINSERT INTO products (name, description, price, in_stock)\nVALUES\n('iPhone 15', '最新款智慧型手機', 32900.00, TRUE),\n('MacBook Air', '輕薄筆電', 42900.00, TRUE),\n('AirPods Pro', '主動降噪無線耳機', 7990.00, FALSE);最後在 docker-compose.yaml 中掛載 init-scripts 目錄
services:\n db:\n image: postgres:16\n container_name: my_postgres\n restart: always\n environment:\n POSTGRES_USER: myuser\n POSTGRES_PASSWORD: mypassword\n POSTGRES_DB: mydb\n volumes:\n - ./init-scripts:/docker-entrypoint-initdb.d\n - postgres_data:/var/lib/postgresql/data\n ports:\n - \"5432:5432\"\n\nvolumes:\n postgres_data:這樣每次啟動時容器時，Postgres 容器就會：
\n啟動後，我們可以進容器查詢資料：
\ndocker exec -it my_postgres psql -U myuser -d mydb -c \"SELECT * FROM products;\"應就能看到類似結果：
\nid | name | description | price | in_stock | created_at | updated_at \n--------------------------------------+-------------+---------------------+---------+----------+--------------------------\n 5a32cda3-28a4-4f4f-8df6-41d4a8e2f01d | iPhone 15 | 最新款智慧型手機 | 32900.0 | t | 2025-10-07 13:00:00+00 | 2025-10-07 13:00:00+00\n 182d9cb5-4e43-44c6-9e35-9a933b292c21 | MacBook Air | 輕薄筆電 | 42900.0 | t | 2025-10-07 13:00:00+00 | 2025-10-07 13:00:00+00\n 3efcd124-46b9-4c02-850b-0f991a216af8 | AirPods Pro | 主動降噪無線耳機 | 7990.0 | f | 2025-10-07 13:00:00+00 | 2025-10-07 13:00:00+00只顯示正在執行的容器
\ndocker ps顯示所有容器（包含執行中、已停止、已退出）
\ndocker ps -a \n# or\ndocker ps --all顯示最近建立的容器
\ndocker ps -l顯示最近建立的 N 個容器（例：docker ps -n 3）
docker ps -n <數字>查看目前有哪些 volume，很常會有需要清理一些沒在使用的、或只是暫時創建來測試用的一些 data，這些 data = docker 的 volume
\ndocker volume ls\n\nDRIVER VOLUME NAME\nlocal a88a3848877ac88f427aa5cefe20fc3b154f9fc6c8f8a91233ec33ec83ea497f\nlocal f91f8d6e293f00bd830e5773f6ecbb14c0e2a8898dfbe39a7db06df2dff20f58\nlocal xxx_my_logs\nlocal xxx_postgres_data\nlocal xxx_redis_data\nlocal yyy_backend_media\nlocal yyy_backend_static\nlocal yyy_postgres_data比如說 xxx_postgres_data 這個 postgres 的 data 是舊的，有新的 db schema 要重新建一個新的 volume，這時候就可以執行
docker volume rm <VOLUME NAME>一次刪除多個 volumes
\ndocker volume rm volume1 volume2 volume3如果 container 移除時想一併刪除匿名的 volumes：
\ndocker rm -v <CONTAINER ID or NAME>docker volume prune預設會檢查 image 是否存在，如果不存在就會自動 build（等於 up --build）。如果 image 已存在，不會重新 build，直接用現成的 image 起 container
\ndocker compose up明確要求重新 build image，根據 Dockerfile 與 context，不會啟動容器，只是建好新的 image。常搭配 docker compose up -d 一起用：
比如剛剛修改了 Dockerfile / 套件依賴，要確保 image 更新
\ndocker compose build # 只做 build，不會啟動容器\ndocker compose build --no-cache # 確保不使用快取\ndocker compose up -d --build # build 完後啟動容器並在背景執行| 指令 | \n是否會建新 image | \n是否啟動 container | \n適合環境 | \n
|---|---|---|---|
docker compose up | \n如果 image 不存在才建 | \n✅ | \n開發快速啟動 | \n
docker compose up -d | \n如果 image 不存在才建 | \n✅ | \n開發快速啟動（背景執行） | \n
docker compose up --build | \n強制重建 | \n✅ | \n開發測試，確保 image 更新 | \n
docker compose build | \n✅ 強制重建 | \n❌ | \nProduction 準備、CI/CD pipeline | \n
# 清除「未被任何容器使用」的鏡像 (dangling images)\ndocker system prune\n\n# -a = all，不只 dangling，會清掉所有目前沒被用到的 image\ndocker system prune -a# 查看指定容器的全部日誌\ndocker logs <container_name_or_id>\n\n# 查看容器即時日誌（持續輸出）\ndocker logs -f <container_name_or_id>\n\n# 查看最新的 100 行日誌\ndocker logs --tail 100 <container_name_or_id>\n\n# 查看日誌並附帶時間戳\ndocker logs -t <container_name_or_id>\n\n# 實時查看，並只輸出最新 50 行\ndocker logs -f --tail 50 <container_name_or_id>這指令還蠻常用的，要完全搞清楚 docker 的運作原理跟模式，就很常會親自進入 container 裡面查看實際情況，看 container 內的 logs、跑了什麼進程、檔案系統長怎樣、環境變數、網路設定如何..等等。
\n參數說明：
\n-i：互動式（interactive），保持標準輸入(stdin)開啟-t：分配一個虛擬終端（tty），讓你可以像在終端機一樣操作# 進入容器的互動式終端\ndocker exec -it <container_name_or_id> bash| 特性 | \nFastAPI (REST) | \ngRPC | \n
|---|---|---|
| 通訊協定 | \nHTTP/1.1 | \nHTTP/2 | \n
| 資料格式 | \nJSON | \nProtocol Buffers (二進位) | \n
| API 定義 | \nOpenAPI/Swagger | \nProto 檔案 | \n
| 效能 | \n較慢 | \n較快 | \n
| 瀏覽器支援 | \n原生支援 | \n需要額外工具 | \n
| 串流 | \n有限支援 | \n原生支援雙向串流 | \n
\n\n目標：當遷移歷史混亂或想用現有模型重新建立「乾淨」的初始遷移時，安全地重置 Alembic 狀態並升到最新。
\n
alembic revision --autogenerate -m \"initial migration\"alembic upgrade headrm -f alembic/versions/*.py\nrm -rf alembic/versions/__pycache__docker exec my_app-postgres-1 psql -U username -d my_app -c \"DELETE FROM alembic_version;\"\n\n非 Docker 版本可用：
\n
\npsql -h 127.0.0.1 -U username -d my_app -c "DELETE FROM alembic_version;"
alembic -c alembic.ini current\n# 預期：沒有版本記錄（空白）alembic revision --autogenerate -m \"initial migration\"alembic upgrade headalembic history確定 migrations/env.py（或 alembic/env.py）內的：
# 要指向你的 SQLAlchemy Declarative Base\ntarget_metadata = Base.metadata已設定正確，並能偵測到模型差異。alembic upgrade head 會將 DB 升到最新。
清空 alembic/versions/，避免舊遷移歷史干擾（務必先備份或在版本控制中操作）。
alembic_version 通常僅有一列紀錄目前版本。用 DELETE 清空即可。
\n\n如果這張表不存在，代表 DB 未受 Alembic 管理，可跳過或稍後用
\nalembic stamp對齊。
alembic current 應無輸出（表示 DB 目前未標記任何遷移版本）。
--autogenerate 會根據 target_metadata 與資料庫現況比對產生遷移腳本。請務必審閱遷移檔（欄位型別、索引、約束），再 upgrade head。
alembic history 應只顯示你的「初始遷移」與後續新增的遷移（若有）。
先備份：清遷移與改 DB 前，請先 pg_dump（或備份資料卷），避免不可逆損失。
autogenerate 不是全能：對 trigger、部分複雜 constraint 或 server_default 等，可能無法自動偵測，需手動補上。
SQLite 例外多：欄位變更常走「建新表 → 搬資料 → 刪舊表」策略；Alembic 會用 batch mode 協助但仍需審閱。
\n版本標記 vs. 真正遷移：若 DB schema 已手動對齊，只想「告訴 Alembic 目前是最新」，可改用：
\nalembic stamp head這不會執行任何 SQL，只會寫入版本表。
\n多人開發分支：若 alembic heads 顯示多個 head，需先 alembic merge -m "merge heads" <revA> <revB> 合併，再 upgrade head。
設定檔路徑：多環境時可用 -c path/to/alembic.ini 指定；多 DB 則可用 -n <section> 選擇命名段落。
傳遞自訂參數：alembic -x key=value ... 可在 env.py 用 context.get_x_argument(as_dictionary=True) 讀取（例如 -x schema=public）。
顯示詳細歷史：
\nalembic history --verbose顯示指定版本資訊：
\nalembic show <rev>只產出 SQL（不執行）：
\nalembic upgrade head --sql > upgrade.sql\nalembic downgrade -1 --sql > downgrade.sql以上流程親測適用：Docker + PostgreSQL（容器名 my_app-postgres-1、DB my_app、使用者 username）。依你的環境調整容器名、帳號與資料庫名稱即可。
給定一個單向 Linked List，反轉該鏈表並返回反轉後的頭節點。
\n\nExample:
\nInput: head = [1,2,3,4,5]\nOutput: [5,4,3,2,1]反正就記得，反轉一條鏈表，就是把每個節點的 next 指標指向前一個節點
| 特性 | \nPython list ([]) | \nLinked List | \n
|---|---|---|
| 底層結構 | \n動態陣列 (連續記憶體) | \n節點 (物件) + 指標 | \n
| 存取第 i 個元素 | \nO(1) | \nO(n) (要走訪) | \n
| 插入 / 刪除 | \nO(n) (中間要搬移) | \nO(1) (只改指標) | \n
| 記憶體配置 | \n連續 | \n不連續 | \n
| 適合情境 | \n頻繁隨機存取 | \n頻繁插入 / 刪除 | \n
| 5 | \n5 → 4 → 3 → 2 → 1 → None | \n5 的 next 指向 4，curr 變 None | \n
class Solution:\n def reverseList(head: ListNode) -> ListNode:\n prev, curr = None, head\n while curr:\n temp = curr.next # 先暫存下一個節點，避免斷鏈 #\n curr.next = prev # 把 curr 的 next 指向 prev，完成反轉，變 None <- 1 <- ...\n prev = curr # 把目前的節點 curr 指向 prev\n curr = temp # curr 指向下一個節點\n return prev 逐步拆解執行流程：
\n| Step | \ncurr | \ntemp = curr.next | \n執行 curr.next = prev 後 | \nprev = curr | \ncurr = temp | \nprev 指向的鏈表 | \n
|---|---|---|---|---|---|---|
| 0 (初始) | \n1 | \n- | \n- | \nNone | \n1 | \nNone | \n
| 1 | \n1 | \n2 | \n1 → None | \n1 | \n2 | \n1 → None | \n
| 2 | \n2 | \n3 | \n2 → 1 → None | \n2 | \n3 | \n2 → 1 → None | \n
| 3 | \n3 | \n4 | \n3 → 2 → 1 → None | \n3 | \n4 | \n3 → 2 → 1 → None | \n
| 4 | \n4 | \n5 | \n4 → 3 → 2 → 1 → None | \n4 | \n5 | \n4 → 3 → 2 → 1 → None | \n
| 5 | \n5 | \nNone | \n5 → 4 → 3 → 2 → 1 → None | \n5 | \nNone | \n5 → 4 → 3 → 2 → 1 → None | \n
O(n)O(1)初次學 Linked List 可能會有點抽象，這邊分享當初看到一個非常淺顯易懂的 yt 教學
\n\n", "tags": [ "Python", "LeetCode", "Linked List", "Easy" ] }, { "id": "https://akebee.com/leetcode-LongestSubstringWithoutRepeatingCharacters/", "url": "https://akebee.com/leetcode-LongestSubstringWithoutRepeatingCharacters/", "title": "LeetCode 獨自升級紀 - [Sliding Window] Longest Substring Without Repeating Characters (Medium)", "date_published": "2025-08-27T07:54:09.000Z", "content_html": "輸入一個字串 s，要找出最長的不含重複字元的子字串長度。
\n例子：
\nabcabcbb" → 答案是 3 ("abc")bbbbb" → 答案是 1 ("b")pwwkew" → 答案是 3 ("wke")![\"window-1\"](\"/images/2025/leetcode-LongestSubstringWithoutRepeatingCharacters/window-1.png\")
上圖是大概的 Sliding Window 概念，用 set() 去重，並且用兩個指標 l 和 r 來表示目前的子字串範圍，然後不斷地擴展 r 直到遇到重複字元，就移動 l 指標來縮小子字串範圍，將重複字元去除
class Solution:\n def lengthOfLongestSubstring(self, s: str) -> int:\n res = 0\n charSet = set()\n l = 0\n\n for r in range(len(s)):\n while s[r] in charSet:\n charSet.remove(s[l])\n l += 1 # 縮減左邊界\n charSet.add(s[r]) # 新增右邊界\n # res = max(res, r - l + 1)\n res = max(res, len(charSet))\n return rescharSet 表示「從 i 到 j 之間，沒有重複字元的子字串」，其實也就是 = r - l + 1，相同意思，只是我用 len(charSet) 我自己認為更直觀點
O(n)O(m)如果 s[j] 的字串已出現過在 charSet 裡面，就跳出 for j in range 迴圈，回到 for i in range 迴圈，重新創建 charSet
並記錄目前 charSet 的最大長度，每輪更新 max_unique_str_length
class Solution:\n def lengthOfLongestSubstring(self, s: str) -> int:\n max_unique_str_length = 0\n for i in range(len(s)):\n charset = set() # charSet 永遠表示「從 i 到 j 之間，沒有重複字元的子字串」\n for j in range(i,len(s)):\n if s[j] in charset:\n break\n charset.add(s[j])\n max_unique_str_length = max(max_unique_str_length ,len(charset))\n return max_unique_str_lengthO(n * m)O(m)Example:
\nclass Solution:\n def searchMatrix(self, matrix: list[list[int]], target: int) -> bool:\n # double Binary Search\n # matrix = [[1,3,5,7],[10,11,16,20],[23,30,34,60]], target = 3\n # 先從 rows 開始找\n rows = len(matrix)\n\n top, down = 0, rows - 1 # rows 的頭尾\n while top <= down:\n middle_row = (top + down) // 2\n if (\n target > matrix[middle_row][-1]\n ): # ，# 如果 target比mid的最右邊最大數字還要大，代表要往下，繼續去更大的 rows 中找\n top = middle_row + 1\n elif target < matrix[middle_row][0]: # 比這個 rows 的最小數字還要小\n down = middle_row - 1\n else:\n break # 找到了 數字就在現在的 matrix[middle_row]\n\n if not (top <= down):\n # 代表 target 在矩陣的範圍外，直接回傳 False\n # 為何還要判斷 if not (top <= bot)，不直接 return False？如果沒有這個判斷，程式會繼續往下跑\n # 可能誤用 row 變數做第二次在 cols 中找，因為這時候根本沒有任何合法的 row 可以搜尋。\n return False\n\n l, r = 0, len(matrix[0]) - 1 # matrix[0] = cols 的長度 [[1,3,5,7],[...]]\n\n while l <= r:\n mid = (l + r) // 2\n if target > matrix[middle_row][mid]: # 要更大，左邊的不要\n l = mid + 1\n elif target < matrix[middle_row][mid]: # 要更小，右邊的不要\n r = mid - 1\n else:\n return True\n\n return False時間與空間複雜度：
\nfor i in range(len(matrix)):\n for c in matrix[i]:\n if c == target:\n return True\nreturn False時間與空間複雜度：
\n輸入一個只包含 ()[]{} 的字串，判斷它是否為「有效括號」。
input string 只有在以上狀況才視為 valid:
\nExample:
\ns = \"()\" # True\ns = \"()[]{}\" # True\ns = \"(]\" # False\ns = \"([)]\" # False\ns = \"{[]}\" # Trueclass Solution:\n def isValid(self, s: str) -> bool:\n stack = []\n close_bracket_key_hashmap = {\")\": \"(\", \"]\": \"[\", \"}\": \"{\"}\n\n for c in s:\n if c in close_bracket_key_hashmap: # 如果 c 在 closeToOpen 中，代表他就是 closing bracket，如果不在就先存到 stack，等之後可能遇到的右括號來配對\n if stack and stack[-1] == close_bracket_key_hashmap[c]: # 如果 stack 內有東西，且 stack 最後一個元素是對應的 open bracket\n stack.pop() # 如果是對的就把 stack 最後一個元素 pop 掉，\n else:\n return False # 如果第一個就是 closing bracket } 那就不用比了，因為順序一定錯誤，直接 return false\n else:\n stack.append(c) # (，if c in closeToOpen: 不成立，把 ( append 到 stack 內，那如果一開始遇到 closing bracket } 那就不用比了，因為順序一定錯誤\n # print(stack) # ['(', '[', '{']\n return True if not stack else False # 如果 stack 內沒有東西，代表全部都配對成功，回傳 True，否則回傳 False大概的具體執行流程，用 pseudo code 解釋，以 input ([]) 為例：
\n# 第一個 c '(' 不在 close_bracket_key_hashmap 中，代表是 opening bracket，就直接把他 append 到 stack 中\nif c in close_bracket_key_hashmap:\n ...\n\nelse:\n stack.append()\n \n# 此時的 stack = [ '(' ]\n\n# 再來第二個 c '[' 也不在 close_bracket_key_hashmap 中，代表是 opening bracket，就直接把他 append 到 stack 中\n# 此時的 stack = [ '(', '[' ]\n\n# 再來第三個 c ')' 在 close_bracket_key_hashmap 中，代表是 closing bracket，接下來要檢查 stack 最後一個元素是否是對應的 opening bracket\n\n# 如果 stack 不是空的，且最後一個 append 進 stack 的元素 [ == 對應的元素 [ 的話\nif stack and stack[-1] == close_bracket_key_hashmap[c]:\n stack.pop() # 就把最後一個元素 pop 掉\nelse:\n return False # 如果不是對應的元素，就直接 return False\n\n# 此時的 stack = [ '(' ]\n...\n\n# 重複以上流程，直到 s 的所有元素都被處理完時間與空間複雜度：
\nclass Solution:\n def isValid(self, s: str) -> bool:\n # Brute Force 判斷 s 是否為空字串\n while \"()\" in s or \"[]\" in s or \"{}\" in s:\n s = s.replace(\"()\", \"\").replace(\"[]\", \"\").replace(\"{}\", \"\") # 刪除所有配對的括號\n return s == \"\"時間與空間複雜度：
\n給定一個整數數組 nums，判斷是否存在三個元素 a，b，c，使得 a + b + c = 0？找出所有滿足條件且不重複的三元組。
\nclass Solution:\n def threeSum(self, nums: list[int]) -> list[list[int]]: # type: ignore\n result = []\n nums.sort() # 先排序，方便後續處理\n\n for i, a in enumerate(nums):\n\n if a > 0: # 如果 a > 0，後面都不可能有三個數字加起來等於 0\n break\n\n if (\n i > 0 and a == nums[i - 1]\n ): # 跳過重複的「起始值」a，i > 0 是防止出現 nums[0] 跟 nums[-1] 比較，導致比較第一個跟最後一個元素的情況\n # a == nums[i - 1] 是避免 不同 index 但 value 一樣 的情況 ex: [-1,-1,...]\n continue\n\n l, r = i + 1, len(nums) - 1 # 左右指針\n while l < r:\n total = a + nums[l] + nums[r]\n if total > 0: # 因為是 sorted 的，代表 nums[r] 太大了\n r -= 1\n elif total < 0:\n l += 1\n else:\n result.append([a, nums[l], nums[r]])\n # [-2,-2,0,0,2,2]\n l += 1\n # 跳過重複的 left pointer 值\n while l < r and nums[l] == nums[l - 1]:\n l += 1\n\n return result為何一開始要
\nif a > 0:\n break因為 nums 是 sorted 的，所以如果當前的 a 已經大於 0，後面的數字只會更大，就不可能再找到符合條件的組合，例如：
nums = [-4, -1, -1, 0, 1, 2]還有為何除了比較下一個值是否與前一個值相同外 a == nums[i - 1]，還要比較 i > 0 ？
nums = [0,0,0]\nnums.sort()\nresult = []\n\nfor i, a in enumerate(nums):\n if nums[i] == nums[i-1]: # ❌ 沒有 i>0 保護\n continue\n\n l, r = i+1, len(nums)-1\n while l < r:\n total = a + nums[l] + nums[r]\n if total == 0:\n result.append([a, nums[l], nums[r]])\n l += 1\n r -= 1\n\nprint(result)\n假設 i 為 0，則 nums[i - 1] 會變成 nums[-1]，這樣就會比較當第一個元素與最後一個元素
執行流程
\ni = 0
\nnums[0] == nums[-1] → 0 == 0 → 成立！i = 1
\nnums[1] == nums[0] → 0 == 0 → 成立，再跳過。i = 2
\nnums[2] == nums[1] → 0 == 0 → 成立，再跳過。結果變成 result = []，沒找到解，但其實 [0,0,0] 是正解。
class Solution:\n def threeSum(self, nums: list[int]) -> list[list[int]]:\n n = len(nums)\n results = set() # 用 set 避免重複\n\n for i in range(n):\n for j in range(i + 1, n):\n for k in range(j + 1, n):\n if nums[i] + nums[j] + nums[k] == 0:\n three_num = tuple(sorted([nums[i], nums[j], nums[k]])) # set 內的元素必須要是能 Hashable的\n results.add(three_num)\n\n # set 轉回 list[list]\n return [list(t) for t in results]Example 1:
\nInput: strs = ["eat","tea","tan","ate","nat","bat"]
\nOutput: [["bat"],["nat","tan"],["ate","eat","tea"]]
\n給定一個字串陣列 strs，請將所有「anagram」字串分在同一組。
anagram：相同字母異序詞，指由相同字母組成、順序不同的單字"eat", "tea", "ate" 是一組。"eat" → "aet""tea" → "aet""ate" → "aet"key，原始字串加進 value 的 list 裡。from collections import defaultdict\nfrom typing import List\n\nclass Solution:\n def groupAnagrams(self, strs: List[str]) -> List[List[str]]:\n anagrams_map = defaultdict(list)\n # 先遍歷每個單字，然後去 sorted 他\n for word in strs:\n single_sorted_word = sorted(word) # sorted 是回傳單個單字的陣列：['a', 'e', 't']...\n key = ''.join(single_sorted_word) # aet,ant...\n # if key not in anagrams_map: # 用 defaultdict 就不用先檢查 key 是否存在了，不存在會直接幫你預測創建預設值\n # anagrams_map[key] = []\n anagrams_map[key].append(word)\n return list(anagrams_map.values())處理過程：
\n| 原始字串 | \n排序後的 key | \n儲存狀態 | \n
|---|---|---|
| eat | \n('a', 'e', 't') | \n{'aet': ['eat']} | \n
| tea | \n('a', 'e', 't') | \n{'aet': ['eat', 'tea']} | \n
| tan | \n('a', 'n', 't') | \n{'ant': ['tan']} | \n
| ate | \n('a', 'e', 't') | \n{'aet': ['eat', 'tea', 'ate']} | \n
| nat | \n('a', 'n', 't') | \n{'ant': ['tan', 'nat']} | \n
| bat | \n('a', 'b', 't') | \n{'abt': ['bat']} | \n
Time Complexity: O(n * k log k)
Space Complexity: O(n * k)
n 個不同的 keyn 個長度為 k 的字串O(n * k)from collections import defaultdict\nanagrams_map = defaultdict(list)當某個 key 不存在時，自動建立對應的空 list。
\n不用每次都需要去判斷 HashMap 中是否已經有這個 key，簡化程式碼。
\nif key not in hashmap:\n hashmap[key] = []給定一個整數陣列 numbers 和一個目標數字 target，請找出 numbers 中兩個數字的和等於 target，並返回它們的索引。假設每個輸入只會有一個解，並且你可以假設每個輸入的數字都是唯一的。
這題跟 Two Sum 最大的差別是，這邊 INPUT: 的 numbers 陣列是 sorted 的，所以題目會提示我們用更有效率的解法
| 類型 | \n移動方式 (關鍵邏輯) | \n核心目的 (解決的問題) | \n範例題 | \n
|---|---|---|---|
| Opposite Direction | \n兩端向中間收斂，每次依條件只動一邊。 | \n在有序數組中，高效尋找配對或縮小搜索空間。 | \nTwo Sum II、Valid Palindrome | \n
| Fast-Slow | \n不同步推進（快慢速度），用於拉開距離。 | \n檢測鏈表/數組中的循環、尋找中點，或原地去重。 | \nLinked List Cycle、Remove Duplicates from Sorted Array | \n
| Sliding Window | \n擴展右邊界，收縮左邊界，維持窗口內的條件。 | \n搜尋滿足特定條件的子範圍（子數組/子字串）的最大/最小問題。 | \nLongest Substring Without Repeating Characters、Minimum Size Subarray Sum | \n
| Two Sequences Sync | \n兩個指標獨立或同步地推進，同時比較兩個序列。 | \n合併或比對差異兩個有序的序列。 | \nMerge Two Sorted Lists、Compare Version Numbers | \n
| K-Distance Window | \n右指標擴展，左指標受限於 K 距離內。 | \n判斷有限距離內元素是否滿足特定條件。 | \nContains Duplicate II、Longest Repeating Character Replacement | \n
這邊是用 Two Pointer 的對撞指標 (Opposite Direction)，時間複雜度為 O(n)。該方法的思路是將 numbers 陣列排序後，使用兩個指針分別指向陣列的開頭和結尾，然後不斷根據當前指針所指的數字來調整指針的位置。
# Two Pointer\nleft, right = 0, len(numbers) - 1\nwhile left < right:\n total = numbers[left] + numbers[right]\n if total < target:\n left += 1\n elif total > target:\n right -= 1\n else:\n return [left + 1, right + 1]\nreturn [] # 沒有結果\n時間與空間複雜度：
\n# O(n^2) Brute Force\nfor i in range(len(numbers)):\n for j in range(i + 1, len(numbers)):\n if numbers[j] == target - numbers[i]:\n return [i + 1, j + 1]時間與空間複雜度：
\n跟 Two Sum 一樣，使用 Hash Map 儲存已經遍歷過的數字和它們的索引。
\n# O(n), SC: O(n) Hash map\nhash_m = {}\nfor i, num in enumerate(numbers, start=1):\n diff = target - num\n if diff in hash_m:\n return [hash_m[diff], i]\n hash_m[num] = i時間與空間複雜度：
\n給定一個非遞減排序（non-decreasing order）的整數 nums 陣列 nums，請 in-place 原地修改原陣列移除所有重複的元素，使每個元素只出現一次，並返回移除重複元素後的陣列長度。
重點 in-place 就是不能回傳一個新的 List
此題已有三個要素
\n題目要求：
\n從上述能看出這題目標就是想讓我們達到 O(n) 的時間複雜度和 O(1) 的空間複雜度。
\n順便複習一下 python set 的特點
\n那為何這題不能直接使用 set 去重，因為題目要求是 in-place 修改原陣列，list(set(nums)) 會建立一個新的 list 物件，並沒有改動原本的 nums。
題目也希望使用常數額外空間（O(1) space complexity），而 set(nums) 和 list(...) 都會額外建立新的資料結構，額外空間是 O(n)。
\n# 錯誤寫法\nclass Solution:\n def removeDuplicates(self, nums: List[int]) -> int:\n unique_list = list(set(nums))題目要求的是在原陣列上直接修改（in-place），讓前 k 個位置變成去重後的內容。
\nCustom Judge:
\nThe judge will test your solution with the following code:
\nint[] nums = [...]; // Input array\nint[] expectedNums = [...]; // The expected answer with correct length\n\nint k = removeDuplicates(nums); // Calls your implementation\n\nassert k == expectedNums.length;\nfor (int i = 0; i < k; i++) {\n assert nums[i] == expectedNums[i];\n}所以假設還要硬要用 set 來解的話就是，用 set 去重後再排序，然後將結果放回原陣列。
class Solution:\n def removeDuplicates(self, nums: List[int]) -> int:\n unique_set = sorted(set(nums))\n nums[:len(unique_set)] = unique_set # 將 nums 中前 len(unique_num) 長度的陣列替換成 unique_num\n return len(unique_set)但這樣的
\nO(n log n)，因為排序的時間複雜度是 O(n log n)，不符合題目要求的 O(n)。\nO(n)，因為建立了新的集合和列表用 Two Pointer 可以 原地修改（in-place）
class Solution:\n def removeDuplicates(self, nums: List[int]) -> int:\n slow = 1\n\n for fast in range(1,len(nums)): # 從 index 1 開始往右找\n if nums[fast] != nums[fast-1]: # 跟上一個數字比，若不一樣就 update 給 slow pointer\n nums[slow] = nums[fast]\n slow +=1\n return slow # 不重複元素的數量因為 INPUT 的陣列是排好序的，所以相同的數字一定會排在一起。第一個數字 nums[0] 前面沒有任何數字可以跟它重複，所以它一定是唯一的。
\n所以可以直接保留它，從第二個數字開始檢查，看看有沒有新的不同數字。
\nO(n)，因為只需要遍歷一次陣列。O(1)，因為只使用了常數額外空間。pip install line-bot-sdk python-decouple python-dotenv記得更新 requirements.txt，在正式主機上部署時記得下載，別像我很笨的卡在回傳 502 error，結果 systemctl 一看才發現是 No module named 'linebot'
pip freeze > requirements.txt前往 LINE Developers Console 建立新的 Provider 或使用現有的
\n![\"create_provider\"](\"/images/2025/django-linebot-2025/create_provider.png\")
Provider 新增完畢後，現在要用 LINE Messaging API，要先去 LINE Official Account Manager 建立官方帳號然後啟用 Messaging API，已經無法在 LINE Developers Console 直接啟用 Messaging API 了
\n![\"manager_setting\"](\"/images/2025/django-linebot-2025/manager_setting.png\")
![\"manager_message_api\"](\"/images/2025/django-linebot-2025/manager_message_api.png\")
然後回到 LINE Developers Console，記錄以下資訊：
\n這邊是等等會再後端的 urls.py自己命名的 url，我的是 https://yourdomain.com/api/line-bot/webhook/
建立 line_bot apps
\ncd backend/\npython manage.py startapp line_bot新增 LINE Bot App 到 INSTALLED_APPS
\n# backend/crm_backend/settings.py\nINSTALLED_APPS = [\n 'django.contrib.admin',\n ...\n # Local apps\n 'customers',\n\n 'line_bot', # 新增 LINE Bot app\n]# backend/crm_backend/settings.py\nALLOWED_HOSTS = ['yourdomain.com', 'localhost', '127.0.0.1']apps.py# backend/line_bot/apps.py\nfrom django.apps import AppConfig\n\nclass LineBotConfig(AppConfig):\n default_auto_field = 'django.db.models.BigAutoField'\n name = 'line_bot'# backend/line_bot/views.py\n...\n\n# 載入專案根目錄的 .env 檔案\nPROJECT_ROOT = Path(__file__).resolve().parent.parent.parent\nENV_FILE = PROJECT_ROOT / '.env'\nload_dotenv(ENV_FILE)\n\nfrom linebot import LineBotApi, WebhookHandler\nfrom linebot.exceptions import InvalidSignatureError, LineBotApiError\nfrom linebot.models import MessageEvent, TextMessage, TextSendMessage\n\n# 設置日誌\nlogger = logging.getLogger(__name__)\n\n# LINE Bot 設定 - 從環境變數讀取\nLINE_CHANNEL_SECRET = os.getenv('LINE_CHANNEL_SECRET')\nLINE_CHANNEL_ACCESS_TOKEN = os.getenv('LINE_CHANNEL_ACCESS_TOKEN')\n\n# 驗證環境變數是否存在\nif not LINE_CHANNEL_SECRET or not LINE_CHANNEL_ACCESS_TOKEN:\n logger.error(\"LINE Bot 環境變數未設置！請檢查 .env 檔案\")\n raise ValueError(\"LINE Bot 環境變數未設置\")\n\nline_bot_api = LineBotApi(LINE_CHANNEL_ACCESS_TOKEN)\nhandler = WebhookHandler(LINE_CHANNEL_SECRET)\n\n\n@csrf_exempt\n@require_POST\ndef webhook(request):\n \"\"\"LINE Bot Webhook 處理器\"\"\"\n\n # 獲取請求內容\n body = request.body.decode('utf-8')\n signature = request.META.get('HTTP_X_LINE_SIGNATURE', '')\n\n # 記錄接收到的請求\n logger.info(f\"收到 LINE Webhook 請求: {body}\")\n logger.info(f\"Signature: {signature}\")\n\n try:\n # 驗證簽名並處理事件\n handler.handle(body, signature)\n except InvalidSignatureError:\n logger.error(\"無效的簽名\")\n return HttpResponseBadRequest(\"Invalid signature\")\n except Exception as e:\n logger.error(f\"處理 Webhook 時發生錯誤: {str(e)}\")\n return HttpResponseBadRequest(f\"Error: {str(e)}\")\n\n return HttpResponse(\"OK\")\n\n\n@handler.add(MessageEvent, message=TextMessage)\ndef handle_text_message(event):\n \"\"\"處理文字訊息\"\"\"\n user_id = event.source.user_id\n user_message = event.message.text\n\n # 記錄收到的訊息\n logger.info(f\"收到使用者 {user_id} 的訊息: {user_message}\")\n # 簡單的回應邏輯\n reply_message = f\"您好！我收到了您的訊息：「{user_message}」\"\n\n try:\n # 回覆訊息\n line_bot_api.reply_message(\n event.reply_token,\n TextSendMessage(text=reply_message)\n )\n logger.info(f\"成功回覆訊息給使用者 {user_id}\")\n\n except LineBotApiError as e:\n logger.error(f\"回覆訊息時發生錯誤: {e.message}\")\n\n\ndef test_connection(request):\n \"\"\"測試連接的簡單端點\"\"\"\n return HttpResponse(\"LINE Bot 服務運行中！\")LINE_CHANNEL_SECRET 跟 LINE_CHANNEL_ACCESS_TOKEN 可直接在 LINE Developers Console 的 Basic settings 跟 Messaging API 頁面找到
\n![\"token\"](\"/images/2025/django-linebot-2025/token.png\")
# backend/line_bot/urls.py\nfrom django.urls import path\nfrom . import views\n\napp_name = 'line_bot'\n\nurlpatterns = [\n path('webhook/', views.webhook, name='webhook'), # LINE Bot Webhook 處理器\n path('test/', views.test_connection, name='test'), # 最基本的連接測試\n]# backend/crm_backend/urls.py\n\n...\n\nurlpatterns = [\n path('admin/', admin.site.urls),\n ...\n path('api/line-bot/', include('line_bot.urls')), # 新增 LINE Bot 路由\n]\n接下來可以直接去 Terminal 測試以下 API，若成功的話，應會在 Terminal 中看到：「LINE Bot 服務運行中！」 的回應
\n# 測試基本連接\ncurl https://yourdomain.com/api/line-bot/test/基本的測試過了，接下來就可以測帶有 body 跟 signature 的 Webhook 處理器測試，最後部署至正式環境再用真實的 webhook url 測試，基本上正式的過了，就可以直接到 LINE 去傳訊息看看是否有成功回覆 handle_text_message 的 reply_message：
\n成功畫面：
\n![\"reply_success\"](\"/images/2025/django-linebot-2025/reply_success.png\")
urls.py 會將請求路由到 webhook 函數問題: HTTP 請求被重定向到 HTTPS
\n解決: 確保使用 HTTPS URL 進行所有請求
問題: Channel Secret 不正確或環境變數未正確載入
\n解決:
.env 檔案路徑問題: Webhook 設定錯誤或程式碼異常
\n解決:
/api/line-bot/test/ 端點問題: Django CSRF 保護阻擋 LINE Webhook
\n解決: 使用 @csrf_exempt 裝飾器（已包含在範例中）
直接先看問題，原本照下方程式碼這樣子去調用 fetchCustomerData() 的話，會出現 React Hook useEffect has a missing dependency: 'fetchCustomerData'. Either include it or remove the dependency array. 的警告訊息
![\"useffect-error\"](\"/images/2025/react-usecallback/useffect-error.png\")
...\n useEffect(() => {\n fetchCustomerData();\n }, [customerId]);\n\n const fetchCustomerData = async () => {\n try {\n setLoading(true);\n const [customerResponse, ordersResponse, transactionsResponse] = await Promise.all([\n api.get<Customer>(`/customers/${customerId}/`),\n api.get<Order[]>(`/customers/${customerId}/orders/`),\n api.get<Transaction[]>(`/customers/${customerId}/transactions/`)\n ]);\n\n setCustomer(customerResponse.data);\n setOrders(ordersResponse.data);\n setTransactions(transactionsResponse.data);\n } catch (err: unknown) {\n setError('無法取得客戶資料');\n console.error('Error fetching customer:', err);\n } finally {\n setLoading(false);\n }\n };\n...如果不去理解的話，就會以為只要單純把 fetchCustomerData 放進 useEffect 的依賴陣列，並且將 fetchCustomerData 函數放在 useEffect 之前定義就可以解決問題
const fetchCustomerData = async () => {\n console.log(\"fetchCustomerData called\");\n ...\n };\n\n useEffect(() => {\n fetchCustomerData();\n }, [customerId, fetchCustomerData]);當然很快的你就會發現 IDE 就會直接警告你會觸發無限 re-render 了，因為每次 fetchCustomerData 被調用時都會重新創建一個新的函式，又會觸發 useEffect 的依賴檢查，導致 useEffect 無限循環
![\"unlimit-rerender\"](\"/images/2025/react-usecallback/unlimit-rerender.png\")
原因：
\nfetchCustomerData 函數 (函數引用 = function#1)fetchCustomerData 函數 (函數引用 = function#2)使用 useCallback 包裝 fetchCustomerData 函數，並且指定 customerId 為依賴，這樣可以確保只有當 customerId 改變時才會重新創建函數，從而避免無限循環的問題。
const fetchCustomerData = useCallback(async () => {\n ...\n }, [customerId]); // 只有當 customerId 改變時才重新建立函數\n\n useEffect(() => {\n fetchCustomerData();\n }, [customerId, fetchCustomerData]);這也是技術面試中常會遇到的問題，比如會問 React 是如何判斷何時該重新渲染組件的，或是應該如何避免不必要的渲染等問題
\n這是就要好好複習基本觀念也就是 React 並不會深度比較物件或陣列的內容，而是只檢查它們的「記憶體位置」（也就是參考位址）有沒有改變。如果兩個物件內容一樣，但記憶體位置不同，React 會認為它們不一樣；反之，如果直接修改原本的物件內容而沒創造新物件，React 則會以為資料沒變，導致畫面不更新。
\n這也是為什麼在 React 中強調 「不可變資料（immutable data）」的原則 —— 只要資料變更，就應該建立一個新物件或新陣列，這樣 React 才能正確判斷有變化並重新渲染畫面。
\n// 每次渲染\nconst func1 = () => {};\nconst func2 = () => {};\n\nconsole.log(func1 === func2); // false! 即使函數內容相同\nconsole.log(123 === 123); // true (customerId同樣概念也適用 useEffect 或 useCallback 等 Hook 的 依賴陣列中。如果你在每次渲染時都產生一個新的函式或物件，React 就會認為依賴變了，進而導致 effect 重新執行或元件重新渲染。因此正確管理依賴與避免不必要的重新建立，是提升效能的關鍵。
\n", "tags": [ "React", "TypeScript" ] }, { "id": "https://akebee.com/gitops-image-automation/", "url": "https://akebee.com/gitops-image-automation/", "title": "(二) GitOps 實戰：FluxCD Image Automation 實戰", "date_published": "2025-05-13T12:30:00.000Z", "content_html": "\n\nGitOps 實戰系列 (二)
\n
\n接續 (一) GitOps 實戰：用 Kustomize + FluxCD 管 GPU K8s 叢集。
\n上一篇講「Git 是真相、Flux 自動同步」這個大框架；這篇專講其中最不直覺、最容易踩坑的一塊：Image 自動更新——也就是「我 push 一個新 image 到 Harbor，cluster 自己升版」這件事，背後到底有哪些 Controller、哪些 yaml、會在哪些時間點出問題。
ImageRepository（掃 Harbor）→ ImagePolicy（算最新 tag）→ ImageUpdateAutomation（改 Git）→ 一般 Flux 流程（再從 Git 套回 cluster）。{"$imagepolicy": "..."} 註解才是 Flux 改寫位置的「錨點」。沒這行 Flux 不會動 yaml。filterTags.pattern 是用來「先濾掉雜訊、再算 semver」，否則 streamlit-0.12.1 這種 prefix tag 會被當成非 semver 丟掉。git describe --tags --abbrev=0——如果你 git tag 0.13.3 推出去後沒推 branch，或 tag 指錯 commit，build 出來的 image tag 就會錯。GitOps 的核心信念是「Git 是 cluster 的鏡像」。但 image tag 是個尷尬例外：
\nreplicas、改 env、改 resources——這些是開發者的意圖，當然要 commit。0.13.2 到 0.13.3——這完全是機械化的事，CI build 出新 image、k8s 要拉新版，中間哪有什麼「意圖」需要人類在 PR 上 review？如果不自動化，流程會變成：
\n1. 工程師 PR merge 進 staging\n2. CI 跑 push-to-harbor、image 0.13.3 進 Harbor\n3. 工程師「再開一個 PR」改 gpu-k8s-devops 上的 deployment.yaml 的 :0.13.2 → :0.13.3\n4. review、approve、merge\n5. Flux 同步、pod 更新第 3-4 步是純粹的 toil。Image Automation 把這兩步交給 Flux 自己。
\n1. 工程師 PR merge 進 staging\n2. CI push image 0.13.3 進 Harbor\n3. Flux 看到新 image → 自動改 deployment.yaml → 自動 commit → 自動 apply\n4. Pod 滾動更新\n\n(工程師沒做任何手動操作)![\"End-to-End](\"../images/2026/gitops-fluxcd-pipeline.jpg\")
整條 pipeline 由四個 CRD 接起來，每一個對應一件具體的事：
\n┌────────────────────────────────────────────────────────────────────────┐\n│ │\n│ Harbor (image registry) │\n│ │ │\n│ │ 「Harbor 上有哪些 tag？」 │\n│ ↓ │\n│ ┌──────────────────┐ │\n│ │ ImageRepository │ 每 5 分鐘掃 Harbor │\n│ │ │ → 把 tag 列表存在 status │\n│ └─────────┬────────┘ │\n│ │ │\n│ │ 「這堆 tag 裡哪個是最新？」 │\n│ ↓ │\n│ ┌──────────────────┐ │\n│ │ ImagePolicy │ 套 semver/filter 規則 │\n│ │ │ → 算出 latestRef.tag │\n│ └─────────┬────────┘ │\n│ │ │\n│ │ 「最新版跟 deployment.yaml 上寫的不一樣，改它」 │\n│ ↓ │\n│ ┌────────────────────┐ │\n│ │ ImageUpdate │ 每 1 分鐘輪詢 │\n│ │ Automation │ → 改 yaml、commit、push 回 Git │\n│ └─────────┬──────────┘ │\n│ │ │\n│ │ 「Git 上 yaml 改了」 │\n│ ↓ │\n│ ┌──────────────────┐ │\n│ │ GitRepository + │ (上一篇講過的) │\n│ │ Kustomization │ 每 5/10 分鐘 reconcile │\n│ └─────────┬────────┘ │\n│ │ │\n│ ↓ │\n│ Deployment │\n│ 滾動更新 │\n│ │\n└────────────────────────────────────────────────────────────────────────┘注意 GitRepository / Kustomization 不是 Image Automation 的一部分，是上一篇講過的「Flux 把 Git 同步進 cluster」的基本流程，這裡只是接受了 Image Automation 改完的 commit。
\n也就是說：Image Automation 沒有「直接改 cluster」這條路，它一定走 Git。這個設計刻意保留了「所有變更都有 git commit 可追」的 audit 性質。
\n最簡單的一塊。
\n# clusters/stage/flux/registry.yaml\napiVersion: image.toolkit.fluxcd.io/v1\nkind: ImageRepository\nmetadata:\n name: keyword-correction\n namespace: flux-system\nspec:\n image: harbor.thebarkingdog.tw/tbd/keyword_correction\n interval: 5m0s\n secretRef:\n name: harbor-credentials要點：
\nimage 是 registry 路徑（不含 tag）——這物件存在的目的就是去 list 這個 repo 下的所有 tag。interval: 5m 是輪詢間隔。為什麼是 5 分鐘？因為頻率太高 Harbor 會被打爆，太低又延遲——5 分鐘是 Flux 文件建議的合理預設。secretRef 指向 Harbor 拉取認證（讀權限即可，不需要寫權限）。Harbor 推完 image 後也可以打 webhook 通知 Flux 立刻去 re-scan，不用等 5 分鐘輪詢：
\n# clusters/stage/flux/receiver.yaml\napiVersion: notification.toolkit.fluxcd.io/v1\nkind: Receiver\nmetadata:\n name: harbor-receiver\n namespace: flux-system\nspec:\n type: generic\n secretRef:\n name: webhook-token\n resources:\n - kind: ImageRepository\n name: keyword-correction\n # ... 其他 ImageRepositoryNotification controller 會給你一個 webhook URL（/hook/<hash>），在 Harbor 那邊設成 push notification target 即可。但 webhook 路徑常常被防火牆/Ingress 設定卡到——這時候 5 分鐘輪詢就是 fallback。
$ kubectl -n flux-system get imagerepository keyword-correction -o yaml\n...\nstatus:\n lastScanResult:\n tagCount: 7\n scanTime: \"2026-05-13T07:06:14Z\"\n ...tagCount 跟 Harbor 上的數字對得起來就 OK。看不到？檢查 secretRef 的權限。
這是整套裡最容易設定錯的一個。ImageRepository 給你一堆 tag，ImagePolicy 的工作是「從這堆 tag 裡，按某種規則算出唯一的『最新』」。
apiVersion: image.toolkit.fluxcd.io/v1\nkind: ImagePolicy\nmetadata:\n name: realtime-asr\n namespace: flux-system\nspec:\n imageRepositoryRef:\n name: realtime-asr\n policy:\n semver:\n range: \">=0.0.0\">=0.0.0 的意思是「所有合法的 semver tag 我都接受，從裡面挑最大的」。tag 列表 1.2.0, 1.2.1, 1.3.0 → latestRef = 1.3.0。
但前提是 tag 全部都是純 semver。一旦你有 latest、main-abc123、api-0.12.4 這種非標準 tag，Flux 會直接忽略它們（不報錯，只是當沒看到）。
實務上專案常有 prefix tag：
\nHarbor 上 keyword_correction 的 tag：\n 0.13.3 (新格式：合一 image)\n 0.13.2\n api-0.13.0 (舊格式：分開兩個 image)\n streamlit-0.13.0\n api-0.12.4直接用 >=0.0.0 的話，api-0.13.0 不是合法 semver 會被丟掉。要納入考量得用 filterTags：
apiVersion: image.toolkit.fluxcd.io/v1\nkind: ImagePolicy\nmetadata:\n name: keyword-correction\n namespace: flux-system\nspec:\n imageRepositoryRef:\n name: keyword-correction\n filterTags:\n # 過渡期相容舊 tag（api-X.Y.Z, streamlit-X.Y.Z），穩定後可移除\n pattern: \"^(?:api-|streamlit-)?(?P<version>\\\\d+\\\\.\\\\d+\\\\.\\\\d+.*)$\"\n extract: \"$version\"\n policy:\n semver:\n range: \">=0.0.0\"兩個欄位的意義：
\npattern：先用 regex 過濾。匹配不到的 tag 完全丟掉（例如 latest、sha-abc123）。extract：從匹配到的 tag 提取「可以拿去比 semver 的字串」。(?P<version>...) 是 named group，$version 就是拿那個 group。於是：
\n| 原始 tag | \n匹配？ | \nextract 結果 | \n套進 semver | \n
|---|---|---|---|
0.13.3 | \n✅ | \n0.13.3 | \n0.13.3 | \n
api-0.12.4 | \n✅ | \n0.12.4 | \n0.12.4 | \n
streamlit-0.13.0 | \n✅ | \n0.13.0 | \n0.13.0 | \n
latest | \n❌ | \n(略過) | \n- | \n
dev-abc | \n❌ | \n(略過) | \n- | \n
最後算出 latestRef = 0.13.3。
Gotcha 1：regex 跳脫
\nyaml 字串裡 \\d 要寫成 \\\\d，否則 YAML parser 會吃掉一個 backslash。看到 pattern: "^\\d+" 不工作不用懷疑，就是這個。
Gotcha 2：相容舊 tag 的責任
\n「過渡期相容」很容易變「永遠相容」。一旦 Harbor 還有舊格式 api-X.Y.Z 沒清掉，pattern 就要一直留 (?:api-|streamlit-)? 這個 optional group——多一個歷史包袱。
Gotcha 3：semver range 寫法
>=0.0.0 ← 全部接受^1.0.0 ← 接受 1.x.x，但不要 2.0.0（minor / patch 自動升、major 不自動升）~1.2.0 ← 只接受 1.2.x生產環境如果不想被 minor 突然推大改動，建議用 ^x.y.z 鎖住 major。我們現在開發階段每個 service 都還在 0.x，所以圖方便都用 >=0.0.0。
$ kubectl -n flux-system get imagepolicy keyword-correction -o yaml\n...\nstatus:\n conditions:\n - message: |\n Latest image tag for harbor.thebarkingdog.tw/tbd/keyword_correction\n resolved to 0.13.3 (previously harbor.thebarkingdog.tw/tbd/keyword_correction:0.13.1)\n reason: Succeeded\n status: \"True\"\n type: Ready\n latestRef:\n tag: 0.13.3latestRef.tag 就是 Flux 認定的「最新」。下一步把它寫進 deployment.yaml 是 ImageUpdateAutomation 的工作。
這是唯一會「動 Git」的 Flux 物件。
\n# clusters/stage/flux/automation.yaml\napiVersion: image.toolkit.fluxcd.io/v1\nkind: ImageUpdateAutomation\nmetadata:\n name: flux-system\n namespace: flux-system\nspec:\n interval: 1m0s\n sourceRef:\n kind: GitRepository\n name: flux-system\n git:\n checkout:\n ref:\n branch: main\n commit:\n author:\n email: bot@gitea.com\n name: gitea-bot\n messageTemplate: |\n Automated image update\n\n Automation name: <!--swig0-->\n\n Files:\n <!--swig1-->\n - <!--swig2-->\n <!--swig3-->\n\n Objects:\n <!--swig4-->\n - <!--swig5--> <!--swig6-->\n <!--swig7-->\n push:\n branch: main\n update:\n path: ./apps/stage\n strategy: Setters幾個關鍵點：
\nupdate.path —— 「只掃這個資料夾」update:\n path: ./apps/stage\n strategy: SettersFlux 不會掃整個 repo，只在 ./apps/stage 底下找可改的 yaml。
如果你有 apps/prod 但目前 prod 不想自動升版，就不要設定到那邊（這也是我們的現況）。
strategy: Setters —— 改寫機制是「標記法」Setters 策略表示 Flux 不會自己猜哪個 yaml 該改，而是只改 yaml 上有特殊註解標記的位置：
# apps/stage/services/keyword-correction/deployment.yaml\ncontainers:\n - name: api\n image: harbor.thebarkingdog.tw/tbd/keyword_correction:0.13.3 # {\"$imagepolicy\": \"flux-system:keyword-correction\"}注意行尾的 # {"$imagepolicy": "flux-system:keyword-correction"} 註解——這就是 setter marker，意思是：
\n\n「這一行的 image tag，要套用名為
\nkeyword-correction（在flux-systemnamespace）的 ImagePolicy 算出的最新版」。
Flux 看到這行就知道：「啊，我要把這個 :0.13.3 改成 keyword-correction policy 的 latestRef.tag」。
沒這行註解 = Flux 不動這個 image。這是個刻意設計：讓 yaml 自己宣告「我要被自動更新」，避免 Flux 亂改其他 image（例如 sidecar、init container）。
\ngit.push.branch —— 改完 push 回哪push:\n branch: main直接 push 進 main。所以這個 branch 不能 protect 到不准 bot push——不然 Flux 一直失敗。
\nGitea 上實際看到的 commit 長這樣：
\nAuthor: gitea-bot <bot@gitea.com>\nDate: Wed May 13 15:06:14 2026 +0800\n\n Automated image update\n\n Automation name: flux-system/flux-system\n\n Files:\n - apps/stage/services/keyword-correction/deployment.yaml\n\n Objects:\n - Deployment keyword-correctioninterval: 1m —— Automation 自己的輪詢注意這個 1 分鐘跟 ImagePolicy 的 5 分鐘是分開的。完整鏈：
\nImageRepository.interval = 5m ← 掃 Harbor\nImagePolicy = 派生 ← 看 ImageRepository status 算\nImageUpdateAutomation.interval = 1m ← 比對 ImagePolicy 跟 yaml 內容\nGitRepository.interval = 5m ← 拉 Git（Image Automation 改完的 commit 也要靠它拉）\nKustomization.interval = 10m ← apply Git 進 cluster理論最壞情況：5 + 1 + 5 + 10 ≈ 21 分鐘才能滾完。實務上 Harbor webhook 觸發後通常 1-3 分鐘可滾。
\n把上面拆開的東西組起來，就是一個完整 bump 流程。我用我們前陣子真的踩過的 0.13.3 bump 來重現（同時呈現踩到的坑）。
# 工程師\ngit checkout -b bump/0.13.3\n# 改 pyproject.toml 0.13.2 → 0.13.3\ngit commit -am \"🔖 bump: version 0.13.2 → 0.13.3\"\ngit push origin bump/0.13.3\n# 開 PR bump/0.13.3 → staging, force mergemerge 之後 staging branch HEAD 在 commit 4a84856。
.gitea/workflows/push-to-harbor.yml 觸發 build。內部 CI 的 tag 決定邏輯：
IMAGE_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"latest\")git describe --tags --abbrev=0 的意思是「從當前 commit 往回追溯，最近一個可達的 tag」。
🪤 第一個踩到的坑：我用 cz bump 在本地先打了 0.13.3 tag、推上去——但這個 tag 指向本地 commit 919ed8c。後來 staging 被 force merge，產生了全新的 commit 4a84856（Gitea force merge 會重新打 commit hash）。所以從 4a84856 往回追溯時：
4a84856 (staging) ← 沒有 tag 指這裡\n ↓ parent\n1aba89c ← 沒有\n ↓ parent\n026d938 ← tag: 0.13.2 ✅ 找到了CI 算出 IMAGE_TAG = 0.13.2，於是 build 出來的 image 是 keyword_correction:0.13.2，把 Harbor 上原本的 0.13.2 image 覆蓋掉了。
修法：把 tag 重打到正確的 commit。
\ngit tag -d 0.13.3 # 刪本地舊 tag\ngit push origin :refs/tags/0.13.3 # 刪遠端舊 tag\ngit tag 0.13.3 origin/staging # 重打到 4a84856\ngit push origin 0.13.3然後 rerun CI workflow，這次才 build 出 0.13.3 image。
教訓：如果 CI 要靠 tag 決定 image version，tag 跟 branch HEAD 一定要對齊。cz bump 假設 dev 可以直接 push，但 protected branch + PR 流會把這個假設打破。
5 分鐘內 image-reflector-controller 輪詢 Harbor、看到 0.13.3：
$ kubectl -n flux-system describe imagerepository keyword-correction\n...\nStatus:\n Last Scan Result:\n Tag Count: 8 # ← 從 7 變成 8$ kubectl -n flux-system get imagepolicy keyword-correction -o yaml\n...\nstatus:\n conditions:\n - message: |\n Latest image tag ... resolved to 0.13.3 (previously ...:0.13.1)\n latestRef:\n tag: 0.13.3 # ← 升上來了1 分鐘內，automation 比對 ImagePolicy.latestRef vs deployment.yaml：
\n# apps/stage/services/keyword-correction/deployment.yaml\n containers:\n - name: api\n- image: harbor.thebarkingdog.tw/tbd/keyword_correction:0.13.2 # {\"$imagepolicy\": \"flux-system:keyword-correction\"}\n+ image: harbor.thebarkingdog.tw/tbd/keyword_correction:0.13.3 # {\"$imagepolicy\": \"flux-system:keyword-correction\"}\n - name: streamlit\n- image: harbor.thebarkingdog.tw/tbd/keyword_correction:0.13.2 # {\"$imagepolicy\": \"flux-system:keyword-correction\"}\n+ image: harbor.thebarkingdog.tw/tbd/keyword_correction:0.13.3 # {\"$imagepolicy\": \"flux-system:keyword-correction\"}由 gitea-bot commit + push 進 main：
$ git log apps/stage/services/keyword-correction/deployment.yaml --oneline | head -3\nf15b4e7 Automated image update\ne6df15b ♻️ refactor(keyword-correction): 改用合一 image (api + streamlit)\ndd31385 Automated image update$ kubectl -n flux-system get gitrepository flux-system \\\n -o jsonpath='{.status.artifact.revision}'\nmain@sha1:f15b4e7cb16d276a1d3aae250c2c5e9f85a6050f🪤 第二個踩到的坑：Image Automation 把 commit push 進 Git 後自己不會立刻拉。GitRepository 預設 5 分鐘輪詢——所以 commit push 後可能要等 5 分鐘 cluster 才同步。
\n要快可以手動戳：
\nkubectl -n flux-system annotate gitrepository flux-system \\\n reconcile.fluxcd.io/requestedAt=\"$(date +%s)\" --overwrite這個 annotation 不是「設定一個值」，是「觸發一次 reconcile」——Flux controller 看到這個 annotation 改變就知道「該重新跑了」。
\nGitRepository 拉到新 commit 後，kustomize-controller 比對 git vs cluster、發現 deployment.yaml 變了、執行 apply。
\n$ kubectl get pod -l app=keyword-correction\nNAME READY STATUS RESTARTS AGE\nkeyword-correction-54c65f7cbc-fddts 0/2 ContainerCreating 0 5s\nkeyword-correction-d59d875c5-mp8ms 2/2 Running 1 4d11h# 30 秒後\n$ kubectl get pod -l app=keyword-correction\nNAME READY STATUS RESTARTS AGE\nkeyword-correction-54c65f7cbc-fddts 2/2 Running 0 31s舊 pod 被殺、新 pod 跑 0.13.3、bug 修了 ✅
放這裡當未來自己 cheat sheet：
\n# 1. Harbor 有哪些 tag (Flux 看到的)\nkubectl -n flux-system describe imagerepository keyword-correction \\\n | grep \"Tag Count\\|Latest Scan\"\n\n# 2. ImagePolicy 算出哪個是最新版\nkubectl -n flux-system get imagepolicy keyword-correction \\\n -o jsonpath='{.status.latestRef.tag}'; echo\n\n# 3. ImageUpdateAutomation 上次成功 push 哪個 commit\nkubectl -n flux-system get imageupdateautomation flux-system \\\n -o jsonpath='{.status.lastPushCommit}'; echo\nkubectl -n flux-system get imageupdateautomation flux-system \\\n -o jsonpath='{.status.lastPushTime}'; echo\n\n# 4. GitRepository 目前拉到哪個 commit\nkubectl -n flux-system get gitrepository flux-system \\\n -o jsonpath='{.status.artifact.revision}'; echo\n\n# 5. Kustomization 套用狀態\nkubectl -n flux-system get kustomization apps \\\n -o jsonpath='{.status.lastAppliedRevision}'; echo\n\n# 6. 強制 GitRepository 立刻 reconcile\nkubectl -n flux-system annotate gitrepository flux-system \\\n reconcile.fluxcd.io/requestedAt=\"$(date +%s)\" --overwrite\n\n# 7. 強制 ImageRepository 立刻 scan\nkubectl -n flux-system annotate imagerepository keyword-correction \\\n reconcile.fluxcd.io/requestedAt=\"$(date +%s)\" --overwrite\n\n# 8. 看 controller logs（debug 用）\nkubectl -n flux-system logs deploy/image-automation-controller --tail=50\nkubectl -n flux-system logs deploy/source-controller --tail=50第一次看 Image Automation 的人常問：「Flux 都裝在 cluster 裡了，為什麼不直接 kubectl set image 改 Deployment？」
答案是 Git 的 audit 功能：
\ngit log apps/stage/.../deployment.yaml 直接看時間軸而且 disaster recovery：cluster 整個壞掉重建，從 Git 一拉就回到上次最新狀態——前提是 Git 真的有最新狀態。
\n兩者責任不同：
\n分開的好處：同一個 ImagePolicy 可以被多個 deployment.yaml 同時引用。flux-system:keyword-correction 這個 policy 同時被 api container 跟 streamlit container 引用（marker 寫一樣的），兩個位置都會被改。
理論上 Harbor → Flux webhook 可以做到 0 延遲，但實務上：
\n所以 Flux 採取輪詢為 baseline、webhook 為加速器的設計。
\n整理一些常踩的坑：
\n| 症狀 | \n大概率原因 | \n怎麼查 | \n
|---|---|---|
| Harbor 有新 image，cluster 沒滾 | \nImagePolicy 還沒算出新 latestRef | \nkubectl get imagepolicy -o yaml 看 latestRef.tag | \n
| ImagePolicy 算出來不是預期的版本 | \nfilterTags.pattern regex 錯了 | \n手動 echo "tag" \\| grep -E "pattern" 試 | \n
| ImagePolicy OK 但 yaml 沒被改 | \n忘記在 yaml 加 # {"$imagepolicy": ...} marker | \ngrep 那個 yaml 檔有沒有 $imagepolicy 字串 | \n
| yaml 被改了但 cluster 沒套 | \nGitRepository 還沒 reconcile | \n戳 annotate 強制 reconcile | \n
Automated image update commit 一直失敗 | \nbot 對 main branch 沒寫權限 / branch protect 擋 | \n看 image-automation-controller log | \n
| CI build 出來 image tag 是錯的 | \ngit describe --tags 找不到正確 tag，或 tag 指錯 commit | \n確認 staging HEAD 上有 tag | \n
Image Automation 是 Flux 最有「魔法感」的功能，但拆開看就是四件清楚的事：
\n關鍵是「Flux 不繞過 Git」——這保留了所有變更的 audit trail，也讓 disaster recovery 變得簡單。
\n下次 push image 看 5 分鐘內 cluster 自己升版，再也不用手動改 yaml 了 🚀
\n\n\n", "tags": [ "GitOps", "DevOps", "Kubernetes", "FluxCD" ] } ] }GitOps 實戰系列
\n\n
\n- (一) GitOps 實戰：用 Kustomize + FluxCD 管 GPU K8s 叢集（架構總覽、Kustomize 分層、SOPS/age bootstrap）
\n- (二) GitOps 實戰：FluxCD Image Automation 實戰（4 CRD 詳解、filterTags、bump 踩坑全記錄）
\n