DEV Community: Jimmy

Bitnami 映像搬家後：漏改 exporter 的坑，以及用原映像加上 pgvector

Jimmy — Thu, 05 Nov 2026 08:58:19 +0000

一句話結論：映像來源搬家時，先盤點 chart 裡每個容器；後來自己 build，也要分清楚「加了功能」和「有人持續維護底層」是兩件事。

當初怎麼做

用 Helm 裝 PostgreSQL、Redis，最方便的就是沿用 chart 預設映像。資料庫、metrics exporter、必要時調整目錄權限的初始化容器，都幫你接好了。

直到上游調整映像目錄，原本 chart 指向的來源不再適用。當時先把映像 repository 換成 bitnamilegacy，讓既有版本繼續跑。

以為已經改完，後來卻還要補一個修正：PostgreSQL 和 Redis 的 metrics exporter 沒有一起改來源。

為什麼只改主映像不夠

Bitnami 官方公告說明，歷史映像搬到 docker.io/bitnamilegacy，Legacy 不再獲得更新或支援，只適合作為過渡。這是當時的遷移背景，不代表現在應該把新部署都指向 Legacy。

一個 chart 通常不只一個 image.repository。主容器改完，metrics sidecar 或 init container 仍可能沿用原來的預設值。

翻回 Git，補修的內容其實只有兩個設定：

# 各自放在 PostgreSQL 與 Redis chart 的 values 裡
# PostgreSQL
metrics:
  image:
    repository: bitnamilegacy/postgres-exporter

# Redis 請放另一份 values，不能把兩個 metrics 合併貼到同一份
# metrics:
#   image:
#     repository: bitnamilegacy/redis-exporter

教訓很直接：values 看起來改了，不代表最後產生的每個容器都改了。

手把手：先看渲染結果

這次用本機保存的 PostgreSQL chart 16.4.1 與 Redis chart 20.6.2 重做檢查。以下版本是歷史案例的重現條件，不是新部署的版本建議。

1. 把用到的 image 分開列出

下面是 PostgreSQL 單獨 chart 的 values 節錄，檔名設為 image-migration.yaml：

global:
  security:
    allowInsecureImages: true

image:
  repository: bitnamilegacy/postgresql
  tag: 17.2.0-debian-12-r5

metrics:
  enabled: true
  image:
    repository: bitnamilegacy/postgres-exporter
    tag: 0.16.0-debian-12-r2

volumePermissions:
  enabled: true
  image:
    repository: bitnamilegacy/os-shell
    tag: 12-debian-12-r34

這裡特意開啟 volumePermissions，是為了讓初始化容器出現在渲染結果，不表示每個部署都需要開它。

allowInsecureImages 也要講清楚：這版 chart 會拒絕不認得的替代映像，這個設定讓它跳過來源識別檢查；它沒有替映像做安全認證，也不是修復漏洞。官方說明有這個參數的範圍。

2. 渲染後逐一核對

假設你已經有對應的 chart 壓縮檔，在該檔案所在資料夾執行：

helm template demo ./postgresql-16.4.1.tgz \
  -f image-migration.yaml > rendered.yaml
rg '^ *image:' rendered.yaml

這次對照結果如下。tag 沒變，變的是 repository：

容器	只改主映像	補齊設定後
PostgreSQL	`bitnamilegacy/postgresql`	`bitnamilegacy/postgresql`
metrics exporter	`bitnami/postgres-exporter`	`bitnamilegacy/postgres-exporter`
權限初始化	`bitnami/os-shell`	`bitnamilegacy/os-shell`

Redis 同樣要看主容器、exporter 與初始化容器。這次也用相同方式渲染確認，但沒有啟動 Redis 或 exporter 做執行期測試。

先維持原 chart 與映像 tag，只調整來源，比同時升 chart、換資料庫版本更容易確認問題在哪。至於 tag 在遠端是否還能拉取，要另外驗證；本次使用本機已存在的基底映像，沒有重做從 Docker Hub 冷拉的測試。

後來為什麼又自己 build

之後需要 PostgreSQL 的 pgvector 擴充。這跟映像目錄搬家是兩個不同需求，只是都碰到同一個映像。

直接換另一個 PostgreSQL 發行映像，還要一起確認 entrypoint、環境變數、資料目錄和執行使用者是否符合原 chart 的期待。當時選擇在原本同一個 Bitnami PostgreSQL 基底上加擴充，把變動縮小。

Dockerfile 可以拆成兩個階段：前面編譯，後面從乾淨的同一基底開始，只拿編譯產物。

ARG BASE=docker.io/bitnamilegacy/postgresql:17.2.0-debian-12-r5
FROM ${BASE} AS build
ARG PGVECTOR_VERSION=v0.8.6
USER root
RUN apt-get update \
    && apt-get install -y --no-install-recommends build-essential git ca-certificates \
    && git clone --depth 1 --branch "${PGVECTOR_VERSION}" https://github.com/pgvector/pgvector.git /tmp/pgvector \
    && cd /tmp/pgvector \
    && make PG_CONFIG=/opt/bitnami/postgresql/bin/pg_config OPTFLAGS="" \
    && make PG_CONFIG=/opt/bitnami/postgresql/bin/pg_config OPTFLAGS="" install

FROM ${BASE}
COPY --from=build /opt/bitnami/postgresql/lib/vector.so /opt/bitnami/postgresql/lib/vector.so
COPY --from=build /opt/bitnami/postgresql/share/extension/ /opt/bitnami/postgresql/share/extension/
USER 1001

存成 Dockerfile 後，可以在該資料夾建置：

docker build -t local-postgresql-vector:17.2.0-0.8.6 .

PG_CONFIG 要指向這個 PostgreSQL 安裝，避免編到另一套版本。OPTFLAGS="" 則避免預設的 -march=native 把建置機特有的 CPU 指令帶進擴充；這是 pgvector 官方提供的可攜性做法，不等於可以跨 CPU 架構直接使用。

第二個 FROM 很重要：編譯階段安裝的套件不會自動進入最終映像。Docker multi-stage build 文件說明了這種選擇性複製的方式。

怎麼確認相容

這次重新 build 後，以斷開外部網路的隔離容器和全新的測試 volume 驗證：

用原始 PostgreSQL 映像啟動，建立一筆純測試資料。
停止並移除舊容器，讓自建映像掛上同一個測試 volume。
讀回資料，確認 SHOW data_directory 的結果沒變。
建立擴充並執行向量運算。

SQL 驗證的核心是：

CREATE EXTENSION vector;
SELECT extversion FROM pg_extension WHERE extname = 'vector';
SELECT round(('[1,0,0]'::vector <=> '[0,1,0]'::vector)::numeric, 3);

原始映像沒有可用的 vector 擴充；自建映像回報版本 0.8.6，兩個正交向量的 cosine distance 是 1.000。原先的測試資料仍讀得到，映像的 entrypoint、啟動命令與使用者也維持一致，最終映像內沒有額外留下 gcc。

這驗證的是同一個 PostgreSQL 基底加上擴充，沒有測跨大版本資料格式遷移，也沒有碰正式資料。不能把這個結果延伸成「任意 PostgreSQL 映像都能直接互換」。

換了之後的代價

自建映像沒有讓舊基底恢復更新。編譯階段即使跑了 apt-get update，最終階段仍從原本的 Legacy 基底開始；它增加的是擴充功能，不是替整個執行環境補齊安全更新。

後續仍要維護基底與擴充版本、確認新映像符合 chart 的啟動慣例，並處理映像保存與版本固定。若要更嚴格重現建置，還要進一步固定基底 digest、原始碼 commit 與建置依賴；只固定 tag 不代表完全可重現。

當時先換來源，再沿用原基底加功能，是為了減少同時變動的地方。長期要換到持續維護的映像，仍然是一項獨立工作，不能因為現在能成功啟動就當作已經完成。

把 AI CLI 包成 OpenAI 相容 API：從 stdin、JSON 輸出到逾時處理（附可跑範例）

Jimmy — Thu, 05 Nov 2026 06:33:29 +0000

一句話結論：把 CLI 接上 HTTP，核心是輸入、程序生命週期和輸出格式；路徑叫 /v1/chat/completions，不代表已經支援整份協定。

遇到的問題

終端機裡已經有一個能回答問題的 AI CLI，但想接的程式只會送 HTTP 請求，兩邊講的是不同語言。

最先想到的是收到問題後跑一次 CLI，再把答案回傳。真的開始接才發現，容易出錯的地方全在中間：長 prompt 要怎麼傳？CLI 印出的 JSON 哪一段才是答案？指令卡住時，HTTP 要等多久？

這篇把實際包裝服務用到的做法縮成一個能在本機跑的範例。先用假的 CLI 驗證程序與協定，不需要模型金鑰，也不會消耗模型用量。

有實測的是 Python 包裝流程，沒有在這次測試中呼叫真實模型。 換成真實 CLI 時，登入、旗標與輸出格式仍要另外核對。

先決定相容到哪裡

範例只接受一則文字 user 訊息，回傳一次完整 JSON。model 固定用 cli-demo，只是這個服務的識別名稱。

串流、工具呼叫、圖片、多輪歷史與其他參數，都明確拒絕。這樣呼叫端才不會以為參數已生效，實際卻被悄悄忽略。

OpenAI 的 Chat Completions 文件定義了請求與回應欄位；這裡只實作其中一小部分，目的是讓需要「送一段文字、拿一段答案」的 HTTP 客戶端能接進來。

手把手步驟

1. 先準備一支假 CLI

把下面存成 demo_cli.py。它從 stdin 讀文字，回一個含 result 的 JSON，讓我們能檢查收到多少字元。

import json
import sys

prompt = sys.stdin.read()
print(json.dumps({"result": f"收到 {len(prompt)} 個字元：{prompt[:20]}"}, ensure_ascii=False))

這個 result 是假 CLI 的格式，跟 HTTP 回應裡的 choices 是兩層不同的東西。包裝服務要負責轉換。

2. 加上 HTTP 包裝

把下面存成同一個資料夾裡的 gateway.py：

import json
import os
import subprocess
import sys
import time
import uuid
from http.server import BaseHTTPRequestHandler, HTTPServer

COMMAND = json.loads(os.environ.get("CLI_COMMAND_JSON", json.dumps([sys.executable, "demo_cli.py"])))
TIMEOUT = float(os.environ.get("CLI_TIMEOUT", "30"))


class Handler(BaseHTTPRequestHandler):
    def reply(self, status, body):
        data = json.dumps(body, ensure_ascii=False).encode()
        self.send_response(status)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(data)))
        self.end_headers()
        self.wfile.write(data)

    def error(self, status, message):
        self.reply(status, {"error": {"message": message, "type": "wrapper_error"}})

    def do_POST(self):
        if self.path != "/v1/chat/completions":
            return self.error(404, "Unknown endpoint")
        try:
            size = int(self.headers.get("Content-Length", "0"))
            if not 0 < size <= 1024 * 1024:
                return self.error(413, "Body must be between 1 byte and 1 MiB")
            body = json.loads(self.rfile.read(size))
            if not isinstance(body, dict):
                raise ValueError()
            if set(body) - {"model", "messages", "stream"}:
                return self.error(400, "Only model, messages and stream are supported")
            if body.get("model") != "cli-demo" or body.get("stream", False) is not False:
                return self.error(400, "Use model=cli-demo and stream=false")
            messages = body.get("messages")
            if not isinstance(messages, list) or len(messages) != 1:
                raise ValueError()
            message = messages[0]
            if not isinstance(message, dict) or set(message) != {"role", "content"}:
                raise ValueError()
            if message["role"] != "user" or not isinstance(message["content"], str):
                raise ValueError()
        except (ValueError, UnicodeError):
            return self.error(400, "Expected one user message with string content")
        try:
            process = subprocess.run(
                COMMAND, input=message["content"], capture_output=True,
                text=True, encoding="utf-8", timeout=TIMEOUT, check=True,
            )
            output = json.loads(process.stdout)
            if not isinstance(output, dict) or output.get("is_error"):
                raise ValueError()
            answer = output.get("result")
            if not isinstance(answer, str) or not answer.strip():
                raise ValueError()
        except subprocess.TimeoutExpired:
            return self.error(504, "CLI timed out")
        except (OSError, subprocess.CalledProcessError):
            return self.error(502, "CLI failed")
        except (ValueError, UnicodeError):
            return self.error(502, "CLI returned invalid output")
        self.reply(200, {
            "id": "chatcmpl-" + uuid.uuid4().hex,
            "object": "chat.completion", "created": int(time.time()),
            "model": "cli-demo",
            "choices": [{"index": 0, "message": {"role": "assistant", "content": answer},
                         "finish_reason": "stop"}],
        })

    def log_message(self, *args):
        pass


if __name__ == "__main__":
    HTTPServer(("127.0.0.1", 8080), Handler).serve_forever()

流程很直接：檢查請求，將文字送進 CLI 的 stdin，確認程序成功退出，再解析 result，最後包進 choices[0].message.content。

這裡刻意把幾種失敗分開：

狀況	HTTP 回應
請求格式錯誤或要求未支援功能	400
宣告的 request body 超過上限	413
CLI 無法啟動、非零退出，或輸出格式錯誤	502
CLI 執行逾時	504

不把 CLI 的完整 stderr 直接回傳，避免把本機路徑或診斷細節送給呼叫端。實際服務可在受控的伺服器日誌記錄錯誤種類與耗時，不必把 prompt 全文一起記下來。

3. 啟動並送一個請求

在放這兩個檔案的資料夾執行：

python3 gateway.py

再開一個終端機：

curl -sS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"cli-demo","messages":[{"role":"user","content":"你好"}],"stream":false}'

回傳的 ID 與時間每次不同，答案應該在這裡：

{
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "收到 2 個字元：你好"},
    "finish_reason": "stop"
  }]
}

上面是回應節錄。完整回應還有 id、object、created 與 model。沒有模型用量資料，就不捏造 usage。

踩到的坑

長 prompt 不要塞在命令列參數裡

原本的服務曾把很長的上下文塞進 argv，碰到 Argument list too long。命令列有系統限制，不適合拿來搬大量文字。

範例用的是：

subprocess.run(COMMAND, input=message["content"], capture_output=True,
               text=True, encoding="utf-8", timeout=TIMEOUT, check=True)

input 透過 stdin 傳入，命令本身用參數陣列，也沒有開 shell=True。所以文字中的 $() 或反引號會當成普通內容傳給 CLI，不會先被包裝層當 shell 指令執行。這不代表 CLI 本身不能使用工具，兩者要分開看。Python subprocess 文件有各參數的行為。

這次以 20 萬個 ASCII 字元實測，假 CLI 回報收到完整的 200,000 個字元。它驗證的是傳輸方式，不代表真實模型的 context window 一定裝得下。

stdout 不一定就是答案

有的 CLI 回一整個 JSON，有的回 JSONL，也就是一行一個事件。啟動訊息、工具結果與最後答案，不能全部原封不動塞進 content。

範例只接受 {"result":"文字"}，缺欄位、空答案或 is_error: true 都回 502。換成 JSONL 型 CLI，就要另外寫事件解析器，找出最後的 assistant 訊息，不能只拿最後一行。

例如 Claude Code 非互動模式提供 -p 與結構化輸出；如果要接它，可將命令改成參數陣列 ['claude', '-p', '--output-format', 'json']，再依所用版本的輸出確認解析器。這是接入示意，本文沒有實測這個真實 CLI 的呼叫，也沒有處理它的登入流程。

HTTP 成功，不代表 CLI 成功

CLI 非零退出時，不能照樣回 200，再把「發生錯誤」當成模型答案。就算退出碼是零，也要檢查應用層錯誤與答案格式。

check=True 負責非零退出，後面的 JSON 驗證負責輸出內容。兩關都過了，才回成功。

逾時也是同樣的道理。模型可能慢，但請求不能無限等下去；呼叫端的等待時間也要比這裡的 CLI timeout 留出一些餘裕。若 CLI 還會產生其他子程序，則要另做整組程序的清理，不能假設直接子程序結束就全部結束。

實測結果與限制

這次在 Python 3.14.4，以本機 HTTP 請求與假 CLI 跑過 17 個情境：

中文回覆、20 萬字元 stdin，以及含 shell 語法的文字都正確傳遞。
壞掉的 JSON、非物件請求、多輪訊息、工具、串流、未知模型與非文字內容都回 400。
超大 Content-Length 在送出 body 前就被拒絕，回 413。
CLI 非零退出、無效 JSON、缺少或空白答案、應用層錯誤都回 502。
假 CLI 刻意拖延，回 504。

這份範例只綁 127.0.0.1，使用標準函式庫的簡單 HTTP server，依序處理請求。它沒有驗證身分、請求讀取期限、輸出大小限制或正式的並行管理，適合本機理解流程，不能直接當成公開服務。

每次 HTTP 請求也都是新 CLI 呼叫，不會自動保留前一輪歷史。要支援多輪、工具或串流，必須逐項定義轉換與錯誤行為，不能只把請求欄位加進來就算完成。

為什麼這樣選

當時的需求是讓原本只認 HTTP 的程式能呼叫既有 CLI，所以先加一層薄薄的轉接，保留已經能工作的執行方式。

若你需要的是模型供應商完整的 API 功能，直接使用原生 API 會少掉一層格式轉換。CLI 包裝的價值，是讓既有工具接得上；代價則是 CLI 旗標、輸出格式與程序生命週期，都變成這層服務要維護的事。

ingress-nginx 退役之後：在臨時叢集實測 Traefik 的 ingress-nginx 相容模式與 Gateway API

Jimmy — Mon, 02 Nov 2026 13:23:06 +0000

一句話結論：用 ingress-nginx 的小叢集，不必急著重寫所有 Ingress。實測下來，Traefik 的 ingress-nginx 相容模式可以原封不動吃下常見的 annotation；想一步到位改 Gateway API 也行，但轉址狀態碼、IP 白名單這類細節要自己補。這篇是評估，不是遷移紀錄。

遇到的問題

單機叢集常見的配置是：k3s 的內建 Traefik 關掉，自己用 Helm 裝 ingress-nginx，所有服務掛 ingressClassName: nginx，再用幾個 nginx.ingress.kubernetes.io/... annotation 處理 HTTPS 轉址、逾時、IP 白名單。

這個專案已經退役了。官方 repo 的說明寫得很直接：

2026 年 3 月之後，不再有新版本、bug 修正，也不再修補新發現的安全漏洞。
已經部署的不會壞，Helm chart 和映像也還在。
沒有安裝過的人，建議直接找一個 Gateway API 的實作。

也就是說現有的叢集不會馬上出事，但每一天都在累積「沒人修」的風險。接下來有兩種做法：

換 controller，Ingress 不動。 讓別的 controller 認得 nginx 的 annotation。
換 API。 改寫成 Gateway API 的 Gateway 與 HTTPRoute。

這篇不下結論要選哪個，而是在隔離的臨時叢集把兩條路都實際跑一遍，記下哪些順利、哪些要注意。

測試環境

整個實驗用一個臨時的 k3d 單節點叢集，不佔主機的埠，測完就刪。

項目	版本
k3s（k3d 預設）	v1.31.5
Traefik（Helm chart 42.2.0）	v3.7.16
Gateway API CRD（standard）	v1.7.0
cert-manager	v1.21.3
ingress2gateway	v1.2.0

測試用的後端是 traefik/whoami，它會回傳請求的標頭，還有 ?wait=25s 這種可以讓後端故意慢回應的參數，以及 /echo 的 WebSocket 端點，很適合拿來測逾時。

要先講清楚的限制：

叢集裡用自簽憑證，沒有真的向 Let's Encrypt 申請。
從叢集內的 Pod 發請求，沒有經過 NodePort 或 LoadBalancer，所以「來源 IP 會不會被改掉」沒有驗證。
單節點，沒做效能比較。

手把手步驟

前置：k3s 內建的 Traefik 不能直接用

先查了 k3s 自帶的 Traefik。k3d 預設的 k3s v1.31.5，內建的是 Traefik 2.11.18。

Traefik 的 ingress-nginx 相容 provider，官方文件寫明需要 v3.6.2 以上。所以 v1.31.5 附的版本沒有這個功能（用 traefik --help 也確實只看到 kubernetesgateway，而且還需要 --experimental.kubernetesgateway）。

比較新的 k3s 會附 Traefik 3.7.x：查 k3s v1.37.1 的內建 manifest，chart 是 41.4.0，對應 Traefik v3.7.12。但舊版 k3s 的叢集，得自己用 Helm 裝新版 Traefik。

下面的實驗都是這樣做：建叢集時停用內建 Traefik，再用 Helm 裝。

k3d cluster create demo --servers 1 --agents 0 --no-lb \
  --k3s-arg "--disable=traefik@server:0"

路線一：讓 Traefik 直接吃 nginx 的 Ingress

Helm values 只要打開 provider：

providers:
  kubernetesIngressNGINX:
    enabled: true     # 預設 ingressClass 是 nginx

原本的 Ingress 完全不用改。測試用的是三種最常見的寫法，原封不動貼進去：

# 1. HTTPS 轉址
metadata:
  annotations:
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"

# 2. 長時間逾時
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"

# 3. IP 白名單
    nginx.ingress.kubernetes.io/whitelist-source-range: "192.0.2.0/24"

實測結果：

項目	結果
HTTP → HTTPS 轉址	`308 Permanent Redirect`，`Location` 正確帶回原本的路徑，和 ingress-nginx 的預設一致
`whitelist-source-range`	名單外的來源收到 `403 Forbidden`
`proxy-read-timeout`	有生效。為了方便驗證，改成 5 秒、後端 25 秒才回應，結果在 5.0 秒收到 `504`；改成 60 秒就正常通過
`backend-protocol: "HTTPS"`	後端用自簽憑證的 HTTPS，收到 `200`；拿掉 annotation 就變成 `400`
WebSocket	透過這個 Ingress 連線、閒置 30 秒後仍可收發

這個 provider 可以和 Gateway API 的 provider 同時開著。Traefik 官方文件沒有說明兩者能不能並存，所以實測了：同一個 Traefik 裡，Ingress 和 HTTPRoute 都正常回應。

有一個小地方：Ingress 的 ADDRESS 欄位是空的。這個 provider 預設沒有回填 status.loadBalancer，chart 有 publishService 這個選項，我沒有測它有沒有用。依賴 Ingress status 的工具（例如自動建立 DNS 記錄的）要留意。

另外，如果打算讓 ingress-nginx 和 Traefik 並行一段時間再切換，官方文件提醒兩個 controller 會互相覆寫 Ingress 的 status，路由不受影響，但監看 status 的工具會被干擾。這一點我沒有實測。

路線二：改寫成 Gateway API

先裝 Gateway API 的標準 CRD，再裝 Traefik 並打開 Gateway provider：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.7.0/standard-install.yaml

providers:
  kubernetesGateway:
    enabled: true
gateway:
  enabled: false       # 自己建 Gateway

Traefik 的 chart 輸出訊息建議安裝 v1.5.1，我裝的是 v1.7.0，GatewayClass 仍然正常被接受。

Gateway 的 listener 埠必須對應 Traefik 的 entrypoint（預設是 HTTP 8000、HTTPS 8443），不是對外的 80 和 443：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata: {name: main, namespace: traefik}
spec:
  gatewayClassName: traefik
  listeners:
    - name: web
      port: 8000
      protocol: HTTP
      allowedRoutes: {namespaces: {from: All}}
    - name: websecure
      port: 8443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs: [{name: demo-tls}]
      allowedRoutes: {namespaces: {from: All}}

HTTP 轉 HTTPS

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: {name: app-redirect, namespace: demo}
spec:
  parentRefs: [{name: main, namespace: traefik, sectionName: web}]
  hostnames: [app.example.test]
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect: {scheme: https, statusCode: 308}

這一段有三個發現：

不要寫 port。 一開始寫了 port: 443，Location 變成 https://app.example.test:443/x。拿掉之後才是乾淨的 https://app.example.test/x。
statusCode 預設是 302。 沒寫的話，原本 ingress-nginx 的 308 會變成臨時轉址。
308 可以用，但屬於 Extended。 CRD 的說明是「301 與 302 是 Core，其餘是 Extended」。實測 Traefik 3.7.16 接受並回傳 308 Permanent Redirect。換別的 Gateway 實作就不一定支援，要看該實作的文件。

IP 白名單

Gateway API 標準沒有 IP 白名單的欄位。Traefik 的做法是建一個 Middleware，再用 ExtensionRef 掛到 HTTPRoute：

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata: {name: only-office, namespace: demo}
spec:
  ipAllowList:
    sourceRange: ["192.0.2.0/24"]
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: {name: internal, namespace: demo}
spec:
  parentRefs: [{name: main, namespace: traefik, sectionName: websecure}]
  hostnames: [internal.example.test]
  rules:
    - filters:
        - type: ExtensionRef
          extensionRef: {group: traefik.io, kind: Middleware, name: only-office}
      backendRefs: [{name: whoami, port: 80}]

名單外的來源收到 403 Forbidden，把 sourceRange 換成 Pod 網段就通過。這是 Traefik 專屬的寫法，換 Gateway 實作就得重寫。

cert-manager 整合

憑證的位置從 Ingress 的 annotation，搬到 Gateway 的 listener。cert-manager 要打開 Gateway 支援：

config:
  apiVersion: controller.config.cert-manager.io/v1alpha1
  kind: ControllerConfiguration
  enableGatewayAPI: true

Gateway 加上 issuer 的 annotation，listener 指向一個「還不存在」的 Secret：

metadata:
  annotations:
    cert-manager.io/cluster-issuer: selfsigned
spec:
  listeners:
    - name: auto
      hostname: auto.example.test
      port: 8443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs: [{name: auto-tls}]

大約 12 秒後，cert-manager 自動建出 Certificate（READY=True）和 auto-tls 這個 Secret，Traefik 開始用它提供 HTTPS，請求回 200。

這裡用的是自簽的 issuer。真正用 Let's Encrypt 時，DNS-01 或 HTTP-01 的流程這次沒有驗證。

長連線與逾時

原本 annotation 裡的 proxy-read-timeout: 3600，主要是為了 WebSocket 和長時間回應。到了 Traefik，要分三種情況看。

預設值。 不調任何逾時：

WebSocket 連上之後閒置 400 秒，再送一次訊息，仍然收到回應。
後端 100 秒才回應的 HTTP 請求，等到 100.1 秒成功收到 200。

3600 秒本身沒有實際等待測試，只能說預設值下，閒置幾百秒不會被切斷。

調得很短的 entrypoint 逾時。 為了確認哪些設定會影響，把 HTTPS entrypoint 的 readTimeout、writeTimeout、idleTimeout 都設成 10 秒：

ports:
  websecure:
    transport:
      respondingTimeouts:
        readTimeout: 10s
        writeTimeout: 10s
        idleTimeout: 10s

WebSocket 閒置 30 秒，仍然正常。升級成 WebSocket 之後，連線不受這幾個逾時影響。
一般 HTTP 請求，後端 25 秒才回應，在第 10 秒被切斷（客戶端看到連線被中斷，沒有收到 HTTP 狀態）。

也就是說，要讓「長時間才回應」的請求（例如串流輸出）不被切掉，要看的是 entrypoint 的 writeTimeout。預設值下 100 秒的回應沒有被切斷（前面實測過），所以一般不用動，但一旦被調過就會是問題。

nginx annotation 不能蓋過 entrypoint。 在 entrypoint 設了 10 秒的情況下，即使 Ingress 寫了 proxy-read-timeout: "3600"，後端 25 秒的請求還是在 10 秒被切斷。annotation 控制的是後端那一段的逾時，不會改寫 entrypoint 的設定。

ingress2gateway 轉出來的東西

官方的轉換工具 ingress2gateway 可以把現有的 Ingress 轉成 Gateway API。拿上面的三個 Ingress 餵給 v1.2.0：

ingress2gateway print --input-file ing.yaml --providers ingress-nginx

轉換器會印出警告，值得逐條看：

force-ssl-redirect 被標為 Unsupported annotation。不過因為 Ingress 有 TLS，工具仍然自動產生了 308 的 HTTP → HTTPS 轉址路由，結果是對的，警告看起來只是沒有逐個 annotation 處理。
whitelist-source-range 轉換失敗：IP-based authorization is not supported。白名單會直接掉，轉完的路由是沒有限制的。
逾時 annotation 會做「best-effort」轉成 timeouts.request，但數字不對。

最後一點值得單獨講。同樣的 annotation，轉出來的結果：

`proxy-read-timeout`（秒）	轉出的 `timeouts.request`
60	`10m0s`（應該是 1 分鐘）
100	`16m40s`（應該是 1 分 40 秒）
3600	`10h0m0s`（應該是 1 小時）

每一筆都是預期的 10 倍。從原始碼看，解析 annotation 的那一步是正確的（秒數轉成 Duration），所以問題出在後面哪一步，這裡沒有追到，也沒找到對應的 issue。這是 v1.2.0 的觀察，之後版本可能已經修掉，重點是轉換結果一定要人工逐項核對，不要直接 apply。

踩到的坑

整理一下實測中遇到的：

k3s 內建的 Traefik 可能太舊。 v1.31.5 附的是 2.11.18，沒有 ingress-nginx 相容 provider，要自己用 Helm 裝 3.6.2 以上。
Gateway 的 listener 埠是 entrypoint 的埠。 寫成 80、443 會對不上。
RequestRedirect 不要寫 port，也別忘了 statusCode。 前者會讓網址多出 :443，後者預設是 302，不是 ingress-nginx 的 308。
IP 白名單在 Gateway API 沒有標準寫法。 得靠實作專屬的 Middleware，轉換工具也不會幫你處理。
轉換工具的輸出要核對。 至少逾時數字要自己重算。

為什麼這樣評估

如果現有叢集的 Ingress 很多，而且多半只用到轉址、逾時、白名單這幾個 annotation，路線一的成本最低：換掉 controller 就好，YAML 一行不改，風險也最小。缺點是 annotation 的相容只涵蓋「一部分」。Traefik 官方文件也寫了某些 annotation 的行為有差異，所以還是要逐項驗證。

路線二是長期比較乾淨的方向，因為 Kubernetes 官方文件說 Ingress API 已經凍結，並建議改用 Gateway。但每個服務都得重寫，白名單、逾時這類能力要換成實作專屬的寫法，等於把鎖定換了一個地方。

所以比較務實的順序是：先用路線一把 controller 換掉，擺脫退役的專案；再依需求，一個服務一個服務搬到 Gateway API。這篇只是把可行性驗過一遍，哪一天真的動手，仍然要在自己的叢集重新驗證，尤其是真實憑證、來源 IP 與多節點的情境。

單機 Kubernetes 的管理介面連換兩次：Rancher Portainer Headlamp，以及 sessionTTL 與 token 的坑

Jimmy — Mon, 02 Nov 2026 09:35:06 +0000

一句話結論：單機或小叢集只想要一個「看得到所有 workload」的介面，Headlamp 夠用而且很輕。Rancher 和 Portainer 都不是不好，是對這個場景太重，或剛好踩到記憶體的坑。

當初怎麼做

單機的 Kubernetes 叢集，總是想要一個網頁介面：不用每次都敲 kubectl get pods -A，看 log、看資源用量也比較直覺。

第一個選的是 Rancher。理由很單純：名氣大、功能完整，感覺「正式的叢集就該有」。

哪裡不行

Rancher：用不到的功能太多，壞了又很難修

Rancher 預設會帶一整組週邊元件：多叢集管理、Fleet、Turtles、內嵌的 Cluster API controller。

某一天 Rancher 就卡在 CrashLoopBackOff，連續好幾天。原因是兩套內嵌的 CAPI controller 的 CRD，storedVersions 版本衝突。官方文件有記載這類問題，正式的解法是跑它自己的清理工具，而那是破壞性的。

回頭看，這個判斷就很明顯：一台機器、一個叢集，從頭到尾沒用過下游叢集、Fleet、Turtles。為了一個「看叢集」的需求，裝了一整個多叢集管理平台，出問題時要追的東西比要看的東西還多。

所以沒有去追這個衝突，直接整個換掉。

Portainer：輕量，但看 Helm 頁面會吃光記憶體

換成 Portainer CE，用 Helm 安裝，單機叢集夠用。

直到點進 Kubernetes 的 Helm 頁面。這個頁面會讀 Helm repository 的 index，記憶體瞬間飆高。

原本 limit 是 512Mi，pod 連續被 OOMKilled 三次，前端出現「Unable to retrieve helm repositories」和一堆連線被重置的錯誤。

調到 1Gi 之後還是撐不住，反覆 OOM。與其繼續加記憶體，不如承認它的行為不適合這台機器。

換成什麼

換成 Headlamp。它是 Kubernetes SIG 的專案，只做 Kubernetes，介面簡單，資源限制設 300m CPU、256Mi 記憶體就夠。

用 Helm 安裝，重點設定是 ingress 和一個 clusterRoleBinding 綁 cluster-admin，這樣可視範圍就是整個叢集。

遷移怎麼進行

遷移本身很單純，因為這類管理介面幾乎沒有自己的狀態要搬：

新增 Headlamp 的部署設定，移除 Portainer 的。
確認舊的 namespace 和 PVC 真的被清掉，沒清就手動刪。
把文件、儀表板裡寫死的舊 namespace 名稱全部換掉。
產生登入 token。

接下來才是真正花時間的部分，登入。

踩到的坑

Headlamp 的登入頁需要貼上一個 ServiceAccount 的 bearer token。

坑一：token 的有效期限

最先想到的是用 kubectl create token 產生 token。預設的有效期限只有 1 小時，所以文件上寫的是加 --duration=8760h（一年）。

後來發現隔天還是要重新登入，就修改文件，說「API Server 通常會限制手動產生 token 的存活時間，--duration 無法突破上限」，改用一個永久的 Secret：

apiVersion: v1
kind: Secret
metadata:
  name: headlamp-permanent-token
  namespace: portal
  annotations:
    kubernetes.io/service-account.name: headlamp
type: kubernetes.io/service-account-token

建立之後，Kubernetes 的 controller 會自動把 token 填進這個 Secret，而且不會過期。取出來用：

kubectl -n portal get secret headlamp-permanent-token -o jsonpath='{.data.token}' | base64 -d

Secret 本身不含明文憑證，可以放進 Git。

這個做法是對的，但當時的診斷是錯的。為了驗證，這次在一個全新的 k3s（v1.31.5）叢集重做一遍：

方式	token 的有效期限
`kubectl create token`（預設）	1 小時
`kubectl create token --duration=8760h`	8760 小時（一年），沒被截短
`kubernetes.io/service-account-token` 的 Secret	沒有 `exp`，不會過期

也就是說，在預設的 k3s 上，--duration=8760h 其實會生效。隔天又被要求重新登入，真正的原因是下一個坑。當時那個叢集有沒有額外的 token 期限上限，已經無法確認，所以不能說前面的說法一定是錯的，但至少「--duration 無法突破上限」不是普遍成立的結論。

永久 Secret 仍然比較省事：不用記得重新產生，也能放進 Git 管理。要記得這個 token 綁的是 cluster-admin，等於整個叢集的鑰匙，不要貼在聊天或截圖裡。

坑二：token 沒過期，卻還是要重新登入

Headlamp 前端有自己的 session TTL，預設只有 24 小時，跟 token 有效期限無關。到期之後被踢回登入頁，要重貼同一組還有效的 token。預設值 24 小時是照上游文件與相關 issue（新增 session TTL 設定）的說法，這次沒有另外量測。

chart 有 config.sessionTTL 可以調，文件說上限是一年，於是設成 31536000 秒。

結果 Headlamp 直接 CrashLoopBackOff：

invalid value "3.1536e+07" for flag -session-ttl: parse error

原因出在 chart 的 template：它把 sessionTTL 直接插進 args，沒有轉成整數。Helm 讀 values 檔裡的數字時是 float64，Go 預設的浮點數輸出格式，數值一到 7 位數就改用科學記號。

不用部署，本機 helm template 就能重現。測 chart 0.43.0，傳進去的值和渲染結果如下：

`config.sessionTTL`	渲染出的參數
`999999`	`-session-ttl=999999`
`1000000`	`-session-ttl=1e+06`
`31536000`	`-session-ttl=3.1536e+07`

分界就在 7 位數。再用寫這篇時最新的 0.46.0 測一次，31536000 仍然渲染成 3.1536e+07，問題還在。

所以只能取 6 位數以內的值。設成 999999，約 11.5 天，是不踩到科學記號的最長值。

這類「數字在 YAML 裡是整數，進了 template 變成浮點數」的坑，不只在 Headlamp，任何 chart 把數字裸插進 command line 都可能遇到。覺得數字很大的時候，先 helm template 看一眼渲染結果再部署。

坑三：Application 永遠 OutOfSync

如果用 GitOps 工具管理，Headlamp 部署後可能一直顯示 OutOfSync，雖然服務完全正常。

chart 固定在 Deployment 的 pod spec 帶入 hostUsers: true。這個欄位依賴 user namespace 的 feature gate，k3s v1.31.5 預設沒開，API server 收到會直接丟掉這個欄位，結果 live 的物件永遠沒有它，對不上期望的內容。

在乾淨的 k3s v1.31.5 上實測：chart 渲染出 hostUsers: true，套用之後讀回 Deployment，這個欄位是空的。

解法是在 Application 加 ignoreDifferences 忽略這個欄位。

換了之後的代價

Portainer 還能順便管主機上的 Docker，Headlamp 只管 Kubernetes。這個功能隨著替換一起捨棄，需要看 Docker 時回到命令列。

另外，Headlamp 比較陽春。沒有 Rancher 的多叢集、也沒有 Portainer 那種一站式的應用範本。對單機叢集來說，這些剛好都用不到。

如果日後真的要管多個叢集，或需要比較完整的權限管理，Rancher 這類工具還是會回來，只是這一次不會為了一個「看 pod」的需求先裝它。

Helm umbrella chart 多加一個上游 chart，結果整批 Application 都渲染失敗：改用本地 wrapper chart（實測）

Jimmy — Sun, 01 Nov 2026 17:31:14 +0000

一句話結論：umbrella chart 要多裝一個新上游 chart 時，別把新的 repo 網址直接加進 umbrella 的 dependencies。把 tgz 放進一個本地 wrapper chart 的 charts/，umbrella 只依賴 file:// 的 wrapper，渲染環境就不需要認識那個新 repo。

遇到的問題

這個做法是用一次翻車學來的。

前提是這樣的：一個 umbrella chart 把所有元件包在一起，上游的 chart 一律「vendor」進 repo，也就是 helm dependency update 之後，把 charts/*.tgz 和 Chart.lock 一起 commit。這樣 GitOps 的渲染環境不用每次都上網抓東西。

接著有人要加一個新的上游 chart。照習慣做：在 umbrella 的 Chart.yaml 加一筆 dependency，repo 填新的網址，本機 helm dependency update，tgz 和 lock 一起 commit，推上去。

結果是所有用這個 umbrella 渲染的 Application 同時壞掉，不只新加的那個元件。

原因是渲染環境的設定。這類環境（例如 ArgoCD 的 config management plugin）通常會在 helm dependency build 之前，先替「已知的幾個 repo」跑 helm repo add。新的 repo 不在清單裡，dependency build 就停在這一步，連已經 vendor 好的 tgz 都沒機會用上。

最後只好 revert，再換一個做法重來。

先重現一次錯誤

不用整套叢集，一個本機的 chart repo 就能重現。

先做一個很小的上游 chart operator，打包後用 python3 -m http.server 當成 repo 來源，再建一個 umbrella 去依賴它：

# umbrella/Chart.yaml
apiVersion: v2
name: umb
version: 0.1.0
dependencies:
  - name: operator
    version: 0.1.0
    repository: http://127.0.0.1:18765

在有做過 helm repo add 的環境跑 helm dependency update，會產生 Chart.lock 和 charts/operator-0.1.0.tgz。

接著把環境換成全新的（獨立的 HELM_CACHE_HOME、HELM_CONFIG_HOME、HELM_DATA_HOME，等於沒有加過任何 repo），charts/ 裡的 tgz 留著不動，直接 build：

helm dependency build umbrella

Error: no repository definition for http://127.0.0.1:18765. Please add the missing repos via 'helm repo add'

就是這個錯誤。Chart.lock 在、tgz 也在，但 helm dependency build 還是要求 repo 必須先被加進本機設定。

charts/ 裡有沒有 tgz，結果都一樣（兩種情況都實測過）。build 會先照 lock 檢查 repo，不會直接拿現成的 tgz 來用。

手把手步驟

解法是多包一層。

步驟一：建一個 wrapper chart

wrapper 是一個很薄的 chart，只負責把上游 chart 的 tgz 帶進來。

components/operator-wrapper/
├── Chart.yaml
├── values.yaml
├── charts/
│   └── operator-0.1.0.tgz   # helm pull 下來的上游 tgz
└── templates/               # 需要的話放自己的資源

tgz 用 helm pull 取得，直接放進 wrapper 的 charts/，這個目錄要 commit：

helm pull operator --repo https://charts.example.org/ --version 0.1.0 \
  --destination components/operator-wrapper/charts

步驟二：wrapper 的 Chart.yaml 要宣告 dependencies

這一步最容易漏，下一節會用實測說明為什麼不能省。

apiVersion: v2
name: operator-wrapper
version: 0.1.0
dependencies:
  - name: operator
    version: 0.1.0
    repository: https://charts.example.org/

這裡的 repo 只是記錄用途，wrapper 自己不會被 dependency build。Helm 展開 wrapper 時，直接讀 charts/ 裡的 tgz。

步驟三：umbrella 只依賴 wrapper

# umbrella/Chart.yaml
dependencies:
  - name: operator-wrapper
    version: 0.1.0
    repository: file://../components/operator-wrapper
    condition: operator-wrapper.enabled

file:// 的 repo 不需要 helm repo add。

在乾淨環境跑 helm dependency build umbrella，會直接把 wrapper 打包進 umbrella，沒有任何 repo 檢查。umbrella 的依賴清單裡完全沒有新的上游 repo，渲染環境自然不用認識它。

升級上游版本時，重新 helm pull 蓋掉 wrapper 的 tgz，同步改 wrapper 的 Chart.yaml 版本即可。

踩到的坑：巢狀子 chart 的 condition 沒生效

很多上游 chart 自己還帶子 chart，並用 condition 開關，例如：

# operator 自己的 Chart.yaml
dependencies:
  - name: sidecar
    version: 0.1.0
    repository: file://../sidecar
    condition: sidecar.enabled

預設 sidecar.enabled: true。我們想關掉它，就在 wrapper 的 values 寫：

operator:
  sidecar:
    enabled: false

實測發現一個差異。同一個 tgz、同一份 values，只差 wrapper 的 Chart.yaml 有沒有宣告 operator 這個 dependency：

wrapper 的 Chart.yaml	`helm template` 渲染出的資源
沒有宣告 dependencies，只是把 tgz 丟進 `charts/`	`operator-main`、`sidecar-extra`（sidecar 還是被裝了）
有宣告 `operator` 這個 dependency	只有 `operator-main`

沒宣告時，Helm 把 charts/ 裡的 tgz 當成「手動放進來的子 chart」，不會處理它內部的 condition，sidecar.enabled: false 被默默忽略。

這個差異很難察覺，因為不會報錯，只是多了一個不想要的資源。最初就是這樣多裝了一個不需要的元件，才發現要把 tgz 同時列在 dependencies 裡。

上面的結果是用 Helm v3.21.4 實測的。其他版本沒有逐一確認，升級 Helm 之後建議用同樣方式對一遍。

為什麼這樣選

先講代價。wrapper 多了一層，values 的路徑也多一層：想改上游的設定，得寫在 operator-wrapper.operator.… 底下，而不是直接寫 operator.…。每升級一次上游，都要手動 helm pull 並 commit 新的 tgz。

換來的好處有兩個：

渲染環境的 repo 清單不需要再改。只要把環境設定放在叢集外的地方（例如 ArgoCD 的 plugin 設定），每多一個上游 repo 就得動一次，而且動了之後還得重新部署那個設定。
新增上游 chart 的失敗範圍縮小。加進 wrapper 的 chart 有問題，頂多是 wrapper 自己渲染失敗，不會讓 umbrella 被牽連。

另一個做法是直接去改渲染環境，多加一筆 helm repo add。這能行，缺點是環境設定和 chart 內容分兩處維護，漏了其中一邊，就會再來一次整批壞掉。

用 Drain3 把 log 變成「新樣板才通知」：不用寫一堆關鍵字規則（附可跑的範例）

Jimmy — Sun, 01 Nov 2026 16:14:56 +0000

一句話結論：與其替每種錯誤寫關鍵字規則，不如讓 Drain3 把 log 歸納成「樣板」，只在出現沒看過的樣板時通知一次。已知的問題不吵你，新的問題才會冒出來。

遇到的問題

最常見的 log 告警做法是：log 裡出現 error，就通知。

這種規則在第一週還算好用，很快就會變成噪音。一個依賴服務重啟，幾百行 connection refused 一起噴出來，通知響不停。看完才發現是已知問題，下次又響。

接著開始加例外：這種錯誤不要報，那種超過幾次才報。規則越寫越多，卻還是會漏掉真正重要的事，也就是第一次出現的新錯誤。

其實真正想問的是：「這行 log 跟我以前看過的，是不是同一種？」

這就是 log 樣板（template）要解決的事。connection refused addr=10.0.0.8:5432 attempt=2 和 connection refused addr=10.0.0.41:5432 attempt=4 其實是同一種，只是變數不同。把變數抽掉，剩下的骨架就是樣板。每個樣板記下來，之後只要出現沒見過的，才值得通知。

Drain3 是一個做這件事的 Python 套件，演算法是 Drain，本身不用訓練資料，一行一行餵進去就會即時歸納。

手把手步驟

準備環境

只需要裝一個套件：

pip install drain3==0.9.11

下面的結果都是在 drain3==0.9.11、Python 3.12 實測的。

先準備一些假的 log

為了讓結果可以重現，先用一支小腳本產生假 log。第一批有三種問題，第二批是同樣的三種，外加一種全新的 disk quota exceeded：

# gen.py
import random
import sys

random.seed(7)
batch = sys.argv[1]


def ip():
    return f"10.0.{random.randint(0, 9)}.{random.randint(1, 250)}"


def ts():
    return f"2026-01-0{random.randint(1, 9)}T0{random.randint(0, 9)}:{random.randint(10, 59)}:{random.randint(10, 59)}Z"


out = []
for _ in range(400):
    out.append(f'{ts()} level=error msg="connection refused" addr={ip()}:5432 attempt={random.randint(1, 5)}')
for _ in range(300):
    out.append(f'{ts()} level=error msg="request failed" path=/api/items/{random.randint(1, 99999)} status=500 took={random.randint(5, 900)}ms')
for _ in range(60):
    out.append(f'{ts()} level=warn msg="retry failed" job=sync-{random.randint(1, 40)} reason=timeout after {random.randint(1, 30)}s')

if batch == "2":
    for _ in range(25):
        out.append(f'{ts()} level=error msg="disk quota exceeded" volume=pvc-{random.randint(1, 9)} used={random.randint(90, 99)}%')

random.shuffle(out)
print("\n".join(out))

python3 gen.py 1 > batch1.log   # 760 行
python3 gen.py 2 > batch2.log   # 785 行

核心腳本：只印出新樣板

# novelty.py
import re
import sys

from drain3 import TemplateMiner
from drain3.file_persistence import FilePersistence
from drain3.masking import MaskingInstruction
from drain3.template_miner_config import TemplateMinerConfig

STATE = sys.argv[1]

config = TemplateMinerConfig()
config.masking_instructions = [
    MaskingInstruction(r"\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?", "TS"),
    MaskingInstruction(r"(?:\d{1,3}\.){3}\d{1,3}(?::\d+)?", "IP"),
    MaskingInstruction(r"\b0x[0-9a-fA-F]+\b|\b[0-9a-f]{12,}\b", "HEX"),
    MaskingInstruction(r"(?<![\w.])[-+]?\d+(?:\.\d+)?(?:ms|s|m|%)?(?![\w.])", "NUM"),
]
config.drain_sim_th = 0.5
config.drain_depth = 4
config.snapshot_interval_minutes = 10 ** 6   # 不要中途存檔，結尾才存
miner = TemplateMiner(FilePersistence(STATE), config)

new = {}
lines = 0
for raw in sys.stdin:
    line = re.sub(r"\s+", " ", raw).strip()
    if not line:
        continue
    lines += 1
    result = miner.add_log_message(line)
    if result["change_type"] == "cluster_created":
        new[result["cluster_id"]] = line

miner.save_state("run-end")

templates = {c.cluster_id: c.get_template() for c in miner.drain.clusters}
print(f"lines={lines} total_templates={len(templates)} new_templates={len(new)}")
for cid in new:
    print(f"  NEW #{cid}: {templates[cid]}")

重點只有三個。

add_log_message 的回傳值。 它會告訴你這行 log 是 cluster_created（建了新樣板）、cluster_template_changed（既有樣板被泛化）還是 none。只看 cluster_created，就是「新樣板」。

FilePersistence。 樣板庫存在檔案裡，下一次執行會接著用。這是「以前看過」的記憶來源，沒有它每次執行都會把所有樣板當成新的。

masking（遮蔽）。 先用正規表示式把時間戳、IP、數字換成 <TS>、<IP>、<NUM>，再交給 Drain。後面的坑會看到它為什麼重要。

跑起來看結果

先餵第一批，建立基準：

python3 novelty.py state.bin < batch1.log

lines=760 total_templates=3 new_templates=3
  NEW #1: <TS> level=error msg="connection refused" addr=<IP> attempt=<NUM>
  NEW #2: <TS> level=error msg="request failed" path=/api/items/<NUM> status=<NUM> took=<NUM>
  NEW #3: <TS> level=warn msg="retry failed" job=sync-<NUM> reason=timeout after <NUM>

760 行 log 被歸納成 3 個樣板，變數都被抽掉了。

同一批再跑一次：

lines=760 total_templates=3 new_templates=0

沒有任何新樣板，所以不通知。

換第二批，裡面多了一種新錯誤：

python3 novelty.py state.bin < batch2.log

lines=785 total_templates=4 new_templates=1
  NEW #4: <TS> level=error msg="disk quota exceeded" volume=pvc-<NUM> used=<NUM>

785 行裡，前面三種問題的幾百行完全沒有動靜，只有 25 行的 disk quota exceeded 被抓出來。實際要接通知，就是把這幾行輸出送去聊天工具或 webhook 即可。

把 Loki 接進來

這一段沒有包含在這篇的範例裡。樣板庫的檔案放在 PVC 上，Pod 重啟也不會遺失。

踩到的坑

坑一：變數沒遮蔽，樣板數量爆炸

這是最容易中的坑。Drain 預設會把「含數字的 token」當成變數，所以前面的假 log 就算不寫 masking，也只會得到 3 個樣板（實測結果也一樣）。

但如果變數是純字母，又剛好出現在行首附近，情況就不同。例如行首是 8 個隨機小寫字母的主機名：

hsreltpu worker sctapi failed to fetch rhgwp from upstream
rrpmuehu worker eqmxav failed to fetch ycfys from upstream

這其實是同一種錯誤，但餵 500 行進去，不遮蔽的話會得到：

lines=500 total_templates=100 new_templates=100

100 個樣板，每一個都被當成「新樣板」，通知會被洗版。數字剛好是 Drain 預設單一節點最多 100 個分支，超過後才開始合併。

加一條遮蔽規則把行首那段換成 <ID>：

MaskingInstruction(r"^[a-z]{8}(?= worker)", "ID")

同樣 500 行：

lines=500 total_templates=1 new_templates=1
  NEW #1: <ID> worker <*> failed to fetch <*> from upstream

100 個變成 1 個。要訣是：觀察輸出的樣板數，如果遠比預期的問題種類多，八成是有一種變數沒被遮蔽。檢查幾個看起來很像、只差一個詞的樣板，就能知道要補什麼規則。

坑二：第一次執行，所有樣板都是「新」的

樣板庫是空的，第一輪跑完，每一個樣板都是新樣板，你會一次收到幾十則通知。

做法是：第一輪只學不通知。可以在狀態裡記一個 bootstrapped 旗標，第一輪結束才設成 true，之後才開始通知。

坑三：偵測器自己的輸出也被當成 log

如果偵測器把通知內容印到 stdout，而 Loki 又收集了偵測器所在的 namespace，下一輪就會撈到它自己上一輪的輸出，把通知文字學成新樣板，然後又通知一次，無限循環。

查詢時要把偵測器自己的 container 排除（container!="detector"）。Loki 自己也會把查詢語句寫進它的 log，裡面剛好包含 error 這類關鍵字，同樣要排除。

這一點沒有在範例裡重現，是實際跑偵測器時遇到的。

為什麼這樣選

這個做法的限制要先講清楚。

「新樣板」只代表「以前沒出現過」，不代表「很嚴重」。一個無害的警告第一次出現，一樣會通知。它回答的是「有沒有新的事發生」，不回答「該不該緊張」。

另外，如果某個問題已經持續很久，因為早就學過它的樣板，之後不會再通知你。要補這個缺口，可以另外加一條「同一個樣板的出現次數突然暴增」的判斷，但那是另一個主題，這篇不展開。

換來的好處是維護成本很低：沒有關鍵字清單要更新，新服務上線不用先寫規則，而且通知量跟「新問題的種類數」成正比，而不是跟 log 量成正比。

如果 log 格式很固定、種類也有限，直接寫關鍵字規則可能更簡單。Drain3 比較適合服務很多、格式各異、不想一個個盯的情況。

告警來了，讓 LLM 先做第一輪診斷：Grafana webhook 加一個小接收端就能做到（附可跑的範例）

Jimmy — Sun, 01 Nov 2026 15:05:11 +0000

一句話結論：告警通知別等 LLM。原始告警先照常送出，再另外補一則「診斷補充」，LLM 逾時或壞掉，頂多少一則補充，不會漏掉告警。

遇到的問題

告警通知通常只有一行：PostgreSQL down、PodNotReady。收到之後，下一步幾乎都一樣：打開 Grafana 或 Loki，撈那個服務最近的錯誤 log，看有沒有線索。

這個「撈 log、看一遍、猜原因」的動作很機械，剛好是 LLM 擅長的事。如果通知送到手機時，底下已經附上「最近 15 分鐘出現大量 connection refused，可能是資料庫掛了，先看資料庫 Pod」，至少可以決定要不要現在就爬起來處理。

這篇做一個最小版本：Grafana 的 webhook 打到一個小接收端，接收端撈 Loki、問 LLM、把診斷當作第二則訊息送出去。

先說清楚這篇驗證了什麼。

有實測：接收端的流程。用假的通知出口、假的 Loki、假的 OpenAI 相容 LLM 服務跑過，驗證了送出順序、去重、數量上限、逾時處理。
沒有評估：LLM 診斷的品質。假的 LLM 只會回固定的三句話，診斷準不準，取決於你用的模型和 log 的內容，這篇不做保證。
沒有實測：接上真正的 Grafana 與 Loki。Grafana webhook 的 payload 格式是照官方文件的欄位寫的（status、alerts[].labels、annotations、fingerprint），Loki 用的是標準的 query_range API。

手把手步驟

設計原則：四個決定

先講四個決定，後面的程式碼就是照這個寫的。

原始告警永遠先送。 不要讓 LLM 擋在告警前面。LLM 慢、逾時、API 額度用完都是常態，這時候不能漏告警。
診斷是另外一則訊息。 不是改寫原本的通知，而是補在後面。診斷失敗，就補一則「診斷失敗」。
只做 firing，而且同一個告警只診斷一次。 Grafana 會依 repeat_interval 重複送同一個告警，每次都問 LLM 又花錢又洗版。用 fingerprint 去重。
LLM 只讀不動。 prompt 明確寫「不要建議會改動系統的指令」，接收端也沒有給它任何執行能力。它只負責回答「可能是什麼」。

接收端程式

下面是完整的程式，只用標準函式庫：

"""Grafana webhook 接收端：先轉發原始告警，再補一則 LLM 做的第一輪診斷。"""
import json
import os
import threading
import time
import urllib.parse
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

NOTIFY_URL = os.environ["NOTIFY_URL"]  # 通知出口，收 {"text": "..."}
LOKI_URL = os.environ["LOKI_URL"]
LLM_URL = os.environ["LLM_URL"]  # OpenAI 相容的 /v1/chat/completions
LLM_MODEL = os.environ.get("LLM_MODEL", "my-model")
LLM_TIMEOUT = int(os.environ.get("LLM_TIMEOUT", "60"))
MAX_RCA_PER_REQUEST = 3
SEEN_TTL = 4 * 3600

seen: dict[str, float] = {}  # fingerprint -> 上次做 RCA 的時間
lock = threading.Lock()


def post_json(url, payload, timeout=10):
    req = urllib.request.Request(url, json.dumps(payload).encode(), {"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=timeout) as resp:
        return json.load(resp)


def notify(text):
    post_json(NOTIFY_URL, {"text": text})


def recent_errors(namespace, minutes=15, limit=30):
    now = time.time_ns()
    query = f'{{namespace="{namespace}"}} |~ "(?i)(error|exception|fail|fatal|panic)"'
    params = urllib.parse.urlencode({
        "query": query, "limit": limit, "direction": "backward",
        "start": now - minutes * 60 * 10**9, "end": now,
    })
    with urllib.request.urlopen(f"{LOKI_URL}/loki/api/v1/query_range?{params}", timeout=10) as resp:
        data = json.load(resp)
    return [line for s in data["data"]["result"] for _, line in s["values"]][:limit]


def diagnose(alert):
    labels, ann = alert["labels"], alert.get("annotations", {})
    logs = recent_errors(labels["namespace"]) if "namespace" in labels else []
    prompt = (
        "你是維運助手，只做第一輪診斷，不要建議任何會改動系統的指令。\n"
        f"告警：{labels.get('alertname')}\n摘要：{ann.get('summary', '')}\n"
        f"標籤：{json.dumps(labels, ensure_ascii=False)}\n"
        "最近 15 分鐘的錯誤 log：\n" + ("\n".join(logs) or "(沒有撈到)") + "\n\n"
        "請用三點回答：1. 可能原因 2. 影響範圍 3. 先看哪裡。總共不超過 200 字。"
    )
    reply = post_json(LLM_URL, {"model": LLM_MODEL, "messages": [{"role": "user", "content": prompt}]},
                      timeout=LLM_TIMEOUT)
    return reply["choices"][0]["message"]["content"].strip()


def handle(body):
    alerts = body.get("alerts", [])
    # 第一步：原始告警立刻送出，LLM 失敗也不會漏
    notify("\n".join(f"[{a['status']}] {a['labels'].get('alertname')}: {a.get('annotations', {}).get('summary', '')}"
                     for a in alerts))
    done = 0
    for a in alerts:
        if a["status"] != "firing" or done >= MAX_RCA_PER_REQUEST:
            continue
        fp = a.get("fingerprint", a["labels"].get("alertname", ""))
        with lock:
            if time.time() - seen.get(fp, 0) < SEEN_TTL:
                continue  # 同一個告警的 repeat 不重跑
            seen[fp] = time.time()
        done += 1
        try:
            notify(f"🔎 {a['labels'].get('alertname')} 診斷補充\n{diagnose(a)}")
        except Exception as exc:  # 逾時、連線失敗、格式不對都一樣處理
            notify(f"🔎 {a['labels'].get('alertname')} 診斷失敗或逾時（{type(exc).__name__}），請直接看原始告警")


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        self.send_response(200)  # 先回 200，Grafana 才不會因為等 LLM 而逾時重送
        self.end_headers()
        threading.Thread(target=handle, args=(body,), daemon=True).start()

    def log_message(self, *args):
        pass


if __name__ == "__main__":
    ThreadingHTTPServer(("0.0.0.0", int(os.environ.get("PORT", "8080"))), Handler).serve_forever()

幾個地方值得講。

先回 200，再處理。 do_POST 一收到就回 200，診斷丟到背景執行緒。LLM 動輒幾十秒，不先回應的話，Grafana 那邊的 webhook 連線會一直被佔著。

handle 第一步就是送原始告警。 順序是整個設計的重點：notify(...) 在 diagnose(...) 之前。

去重靠 fingerprint。 Grafana 的 webhook 每個告警都帶一個 fingerprint，同一個告警每次都一樣。seen 記下上次診斷的時間，4 小時內不重做。這份記錄在記憶體裡，程式重啟就清空，對這個用途夠用。

每次請求最多診斷 3 條。 一次大故障可能同時冒出幾十條告警，全部送去問 LLM 不合理。多出來的只收到原始告警。

撈哪些 log？ 範例是以告警 label 裡的 namespace 去撈 Loki 近 15 分鐘的錯誤類 log，最多 30 行。這一段要依自己的 label 慣例改。告警沒有 namespace 就不撈，直接讓 LLM 憑告警本身回答。

設定與啟動

四個環境變數：

變數	意義
`NOTIFY_URL`	通知出口，接收 `{"text": "..."}` 的 POST
`LOKI_URL`	Loki 位址
`LLM_URL`	OpenAI 相容的 `/v1/chat/completions`
`LLM_MODEL`	模型名稱

NOTIFY_URL=http://notify.example.internal/send \
LOKI_URL=http://loki.example.internal:3100 \
LLM_URL=http://llm.example.internal/v1/chat/completions \
python3 rca_webhook.py

Grafana 這邊建一個 webhook 類型的聯絡點，網址指到這個接收端（預設 8080 埠，可用 PORT 改），再把通知策略指到它即可。

實測結果

用 Notify、Loki、LLM 三個假服務跑五個情境，每個情境結果如下。

1. 新的 firing 告警。 先收到原始告警，緊接著收到「診斷補充」。webhook 本身 0.01 秒就回應了，診斷是背景處理的。

> [firing] DbDown: DbDown 觸發
> 🔎 DbDown 診斷補充
  1. 資料庫連線被拒絕
  2. 依賴它的服務都會受影響
  3. 先看資料庫 Pod 是否在重啟

2. 同一個 fingerprint 再來一次。 只收到原始告警，LLM 的呼叫次數維持 1，沒有重跑。

3. resolved。 只送原始的 resolved 通知，沒有診斷。

4. 一次進來 5 條不同的告警。 5 條原始告警合成一則送出，之後只有 3 則診斷（Many0 到 Many2），LLM 呼叫剛好 3 次。

5. LLM 逾時。 這裡把逾時設成 2 秒、假 LLM 睡 5 秒。原始告警照常送出，之後補一則：

> 🔎 SlowLLM 診斷失敗或逾時（TimeoutError），請直接看原始告警

最後貼一下實際送給 LLM 的 prompt，可以看出給它的資料有多簡單：

你是維運助手，只做第一輪診斷，不要建議任何會改動系統的指令。
告警：DbDown
摘要：DbDown 觸發
標籤：{"alertname": "DbDown", "namespace": "demo", "severity": "critical"}
最近 15 分鐘的錯誤 log：
level=error msg="connection refused" addr=db:5432
level=error msg="connection refused" addr=db:5432

請用三點回答：1. 可能原因 2. 影響範圍 3. 先看哪裡。總共不超過 200 字。

踩到的坑

1. 把 LLM 放在告警的必經之路上。 最直覺的做法是「先問 LLM，再把結果跟告警一起送」。一旦 LLM 掛了，連告警都收不到，那就是用複雜度換來更低的可靠度。所以才會先送原始告警。

2. repeat 造成重複診斷。 沒有做去重的話，同一個還沒恢復的告警每隔 repeat_interval 就會再問一次 LLM。用 fingerprint 去重是最簡單的解法。

3. 限制要放在接收端，不是只靠 prompt。 「不要建議會改動系統的指令」寫在 prompt 裡只是請求。真正的限制是接收端根本沒有執行任何東西的能力，LLM 的輸出只會被當成文字送出去。如果之後要讓它真的去查東西，工具也應該是唯讀的。

4. 大故障時的數量上限。 資料庫掛掉時，依賴它的十幾個服務可能同時告警。沒有上限的話，一瞬間打出十幾次 LLM 請求。

為什麼這樣選

這個做法的價值在「降低半夜判斷的成本」，不在「取代人」。診斷可能是錯的，也可能只是把 log 裡最顯眼的那行重述一遍。它適合拿來決定「要不要現在處理」，不適合直接拿來決定「怎麼修」。

做這個小接收端的成本也要算進去：多一個要維護的服務、每次告警一次 LLM 呼叫的費用，還有 log 內容會送給模型供應商這件事。log 裡如果有敏感資料，要先在撈出來的階段遮蔽，或者改用地端模型。

換來的好處是：不用改告警規則、不用改 Grafana，只是在 webhook 的後面多接一段，不滿意隨時可以拿掉。

小規模叢集可以不裝 Alertmanager：用 Grafana 內建告警同時管 metrics 與 logs（實測）

Jimmy — Sun, 01 Nov 2026 13:25:24 +0000

一句話結論：小規模叢集可以把 Alertmanager 關掉，改用 Grafana 內建的告警引擎，用同一套規則、同一套通知策略處理指標與日誌。代價是 Prometheus 自己那一百多條預設規則，不會再通知任何人，要的規則得在 Grafana 裡重寫。

遇到的問題

kube-prometheus-stack 預設的告警路徑是這樣：Prometheus 評估規則，把觸發的告警送給 Alertmanager，再由 Alertmanager 分組、路由、發通知。

指標告警這樣做沒問題。但叢集裡通常還有日誌，想對「log 出現某個錯誤關鍵字」告警，就變成另一條路：要有 Loki 自己的 ruler，或另外想辦法。

結果是：規則寫在 PrometheusRule 的 CRD 裡，路由寫在 Alertmanager 的設定檔裡，日誌告警又在別的地方。小規模的叢集，光是維護這三處就嫌多。

另一個選擇是：只用 Grafana。Grafana 本身就內建告警引擎，規則可以同時查 Prometheus 和 Loki，通知策略也在同一個地方設定。

這篇用實測帶一遍怎麼做，也把關掉 Alertmanager 的代價講清楚。

手把手步驟

前提與測試版本

手邊要有一個用 kube-prometheus-stack 安裝的 Grafana 與 Prometheus。要測日誌告警的話，還需要一個 Loki 資料來源（uid 為 loki），沒有 Loki 的話，把下面的日誌規則略過即可。

下面的 values，是在這些版本上實測的：

元件	版本
kube-prometheus-stack	chart 92.10.1
內含的 Grafana chart	14.0.1
grafana/loki	chart 7.3.0

叢集是 k3s v1.31.5（單節點）。版本不同的話，欄位可能不一樣，請對一下 chart 的 values.yaml。

步驟一：關掉 Alertmanager

在 kube-prometheus-stack 的 values 加上：

alertmanager:
  enabled: false

defaultRules:
  disabled:
    # 沒有 Alertmanager 時這條一定會亮
    PrometheusNotConnectedToAlertmanagers: true

第二段很容易漏掉。chart 有一條預設規則 PrometheusNotConnectedToAlertmanagers，內容就是「Prometheus 沒有連到任何 Alertmanager」，等待時間 10 分鐘。

關掉 Alertmanager 又不關這條規則，10 分鐘後它就會一直亮著，而且永遠不會好。

步驟二：用 chart values 定義聯絡點與通知策略

Grafana 的 chart 支援用 alerting: 直接把告警資源寫進 values，部署時就會載入。放在 kube-prometheus-stack 的 grafana: 底下：

grafana:
  alerting:
    contactpoints.yaml:
      apiVersion: 1
      contactPoints:
        - orgId: 1
          name: demo-webhook
          receivers:
            - uid: demo-webhook
              type: webhook
              settings:
                url: http://receiver.monitoring.svc.cluster.local:8080/alert
                httpMethod: POST

    policies.yaml:
      apiVersion: 1
      policies:
        - orgId: 1
          receiver: demo-webhook
          group_by: ["alertname"]
          group_wait: 10s
          group_interval: 1m
          repeat_interval: 4h

聯絡點

聯絡點就是「通知要送去哪裡」。這裡用最簡單的 webhook，後面會放一個接收端來驗證。實際使用時，換成 email、聊天工具等其他類型即可。

通知策略

策略決定哪些告警送給哪個聯絡點。這裡只有一條預設策略，全部都送給 demo-webhook，並以 alertname 分組。

group_wait: 10s 是為了測試時快一點看到結果，平常用預設值就好。

步驟三：用 values 定義告警規則

同樣放在 grafana.alerting 底下，再加一個 rules.yaml。這裡放兩條規則：一條查 Prometheus，一條查 Loki。

    rules.yaml:
      apiVersion: 1
      groups:
        - orgId: 1
          name: demo
          folder: demo
          interval: 30s
          rules:
            # 指標規則：容器重啟（Prometheus 資料來源）
            - uid: container-restarts
              title: ContainerRestarts
              condition: C
              for: 0s
              noDataState: OK
              execErrState: Error
              labels:
                severity: warning
              annotations:
                summary: "有容器在最近 5 分鐘內重啟過"
              data:
                - refId: A
                  relativeTimeRange: {from: 300, to: 0}
                  datasourceUid: prometheus
                  model:
                    refId: A
                    expr: 'sum by (namespace, pod) (increase(kube_pod_container_status_restarts_total{namespace="demo"}[5m]))'
                    instant: true
                - refId: B
                  datasourceUid: __expr__
                  model:
                    refId: B
                    type: reduce
                    expression: A
                    reducer: last
                    datasource: {type: __expr__, uid: __expr__}
                - refId: C
                  datasourceUid: __expr__
                  model:
                    refId: C
                    type: threshold
                    expression: B
                    conditions:
                      - evaluator: {type: gt, params: [0]}
                    datasource: {type: __expr__, uid: __expr__}

            # 日誌規則：log 裡出現 ERROR_DEMO（Loki 資料來源）
            - uid: error-logs
              title: ErrorLogs
              condition: C
              for: 0s
              noDataState: OK
              execErrState: Error
              labels:
                severity: critical
              annotations:
                summary: "最近 1 分鐘內 log 出現錯誤關鍵字"
              data:
                - refId: A
                  relativeTimeRange: {from: 120, to: 0}
                  datasourceUid: loki
                  model:
                    refId: A
                    expr: 'sum(count_over_time({namespace="demo"} |= "ERROR_DEMO" [1m]))'
                    queryType: instant
                - refId: B
                  datasourceUid: __expr__
                  model:
                    refId: B
                    type: reduce
                    expression: A
                    reducer: last
                    datasource: {type: __expr__, uid: __expr__}
                - refId: C
                  datasourceUid: __expr__
                  model:
                    refId: C
                    type: threshold
                    expression: B
                    conditions:
                      - evaluator: {type: gt, params: [0]}
                    datasource: {type: __expr__, uid: __expr__}

規則的結構三段式，兩條規則都一樣。

A 是查詢：對資料來源下 PromQL 或 LogQL。
B 是縮減（reduce）：把查詢結果壓成單一數字。
C 是閾值（threshold）：B 大於 0 就算觸發。

condition: C 指的是以 C 的結果當作這條規則的判斷依據。

兩條規則查的是不同資料來源，但規則的寫法、通知策略、聯絡點完全一樣，這就是「一套引擎管指標與日誌」的樣子。

datasourceUid 要對上資料來源的 uid。kube-prometheus-stack 預設的 Prometheus 資料來源 uid 是 prometheus，Loki 是自己加的，這裡設成 loki。

步驟四：套用並確認載入

helm upgrade monitoring prometheus-community/kube-prometheus-stack \
  --version 92.10.1 -n monitoring -f prom-values.yaml --wait

Grafana 有提供 provisioning API，可以直接問它載入了什麼。先 port-forward，再用 admin 帳號查：

curl -s -u admin:<密碼> http://127.0.0.1:3000/api/v1/provisioning/alert-rules
curl -s -u admin:<密碼> http://127.0.0.1:3000/api/v1/provisioning/contact-points
curl -s -u admin:<密碼> http://127.0.0.1:3000/api/v1/provisioning/policies

實測看到的是：兩條規則（ContainerRestarts、ErrorLogs）、一個 demo-webhook 聯絡點，以及預設策略的 receiver 是 demo-webhook、group_by 是 alertname。

也可以確認 Prometheus 真的沒有連 Alertmanager：

kubectl get --raw \
  "/api/v1/namespaces/monitoring/services/monitoring-kube-prometheus-prometheus:9090/proxy/api/v1/alertmanagers"

實測結果 activeAlertmanagers 與 droppedAlertmanagers 都是 0。

步驟五：放一個接收端，製造事件驗證

先放一個會把收到的 POST 印出來的小接收端：

apiVersion: v1
kind: Pod
metadata: {name: receiver, namespace: monitoring, labels: {app: receiver}}
spec:
  containers:
    - name: r
      image: python:3.12-alpine
      command: [python, -u, -c]
      args:
        - |
          from http.server import BaseHTTPRequestHandler, HTTPServer
          class H(BaseHTTPRequestHandler):
              def do_POST(self):
                  n = int(self.headers.get('content-length', 0))
                  print('POST', self.path, self.rfile.read(n).decode()[:2500], flush=True)
                  self.send_response(200); self.end_headers()
              def log_message(self, *a): pass
          HTTPServer(('', 8080), H).serve_forever()
---
apiVersion: v1
kind: Service
metadata: {name: receiver, namespace: monitoring}
spec:
  selector: {app: receiver}
  ports: [{port: 8080, targetPort: 8080}]

再製造兩種事件：一個會一直重啟的容器，和一個一直印出錯誤關鍵字的容器。

kubectl create namespace demo

kubectl -n demo run crasher --image=busybox:1.36 --restart=Always -- \
  sh -c 'echo starting; sleep 15; exit 1'

kubectl -n demo run noisy --image=busybox:1.36 --restart=Always -- \
  sh -c 'while true; do echo "ERROR_DEMO something broke"; sleep 5; done'

等大約一兩分鐘，看接收端的 log：

kubectl logs -n monitoring receiver

會看到兩筆 firing 的 POST，內容是 Grafana 的 webhook 格式，重點欄位長這樣：

{"receiver":"demo-webhook","status":"firing","alerts":[{"status":"firing",
 "labels":{"alertname":"ErrorLogs","grafana_folder":"demo","severity":"critical"},
 "annotations":{"summary":"最近 1 分鐘內 log 出現錯誤關鍵字"}, ...

另一筆是 ContainerRestarts，label 多了 namespace="demo" 和 pod="crasher"，因為規則的查詢有 sum by (namespace, pod)。

步驟六：確認恢復通知

把兩個測試 Pod 刪掉：

kubectl -n demo delete pod noisy crasher

等約三分鐘，接收端會收到 ErrorLogs 的 resolved。

ContainerRestarts 在我測的這三分鐘內還沒有恢復，這是正常的：它的查詢是 increase(...[5m])，窗口有 5 分鐘，要等重啟的紀錄滑出窗口才會變成 0。

踩到的坑

1. 關掉 Alertmanager，但沒關那條「沒連到 Alertmanager」的規則

這條規則在 chart 裡是預設就有的（等待 10 分鐘，severity 是 warning）。我特地比對過：關掉 Alertmanager 之後它仍然會被渲染出來，要在 defaultRules.disabled 裡明確關掉，渲染結果裡才會消失。

不關的話，10 分鐘後它就會一直亮著。

2. 預設那一百多條規則還在跑，但不會通知任何人

這是關掉 Alertmanager 最大的代價，一定要知道。

實測：Prometheus 載入了 148 條告警規則，但 Alertmanager 數量是 0。其中 Watchdog 這種永遠觸發的規則，在 Prometheus 裡是 firing，但接收端一次都沒收到。

也就是說，kube-prometheus-stack 預設附的 KubePodCrashLooping、NodeFilesystemSpaceFillingUp 這類規則，狀態會在 Prometheus 的 Alerts 頁亮起來，卻沒有任何通知出去。

要這些規則的通知，就得在 Grafana 裡自己寫（或匯入）。Grafana 文件有 Import to Grafana-managed rules 這個功能，可以把資料來源管理的規則轉成 Grafana 管理的規則，這部分我沒有實測。

3. values 裡的雙大括號要跳脫

Grafana chart 會把 alerting: 底下的內容當成 Helm 模板處理。如果規則的 annotation 裡想寫 Grafana 的樣板語法（例如用 {{ $labels.pod }} 帶出 Pod 名稱），那組雙大括號會先被 Helm 當成它自己的模板。

chart 的說明有寫：不是要給 Helm 處理的雙大括號必須跳脫。本篇為了簡單，annotation 全部寫成固定文字，避開這個問題，要用樣板語法的話，請照 chart 的說明處理跳脫。

為什麼這樣選

先說一個誠實的點：省的記憶體很少。Alertmanager 在這個叢集大約只吃 38 MiB，不是為了省資源才關它。

真正的理由是這兩個：

一個地方管指標和日誌

Grafana 官方文件說，Grafana 管理的告警規則可以查很多種資料來源，甚至在單一規則裡同時用多個資料來源。所以指標和日誌用同一套寫法、同一個 UI、同一套通知策略。

規則可以跟著 values 一起進版本控制

規則、聯絡點、策略都寫在 values 裡，跟著 Helm 部署，改動走 Git，不需要登入 UI 手動設定。

什麼情況應該保留 Alertmanager

Prometheus 官方文件對 Alertmanager 的定位，是接收 Prometheus 之類的用戶端送來的告警，負責去重、分組、路由到各種通知管道，也處理靜音與抑制。

如果符合下面任一種情況，保留它比較合適：

手上有很多現成的 PrometheusRule（或直接使用 kube-prometheus-stack 的預設規則），不想重寫。
需要 Alertmanager 的功能，例如 inhibition。
多個團隊共用 Prometheus，每個團隊有自己的路由設定。

反過來，單一叢集、規則不多、又想同時管日誌告警的話，只用 Grafana 比較簡單。

用 kube-prometheus-stack 在單機 Kubernetes 上架 Prometheus 與 Grafana：k3s 要調的 values（實測）

Jimmy — Wed, 21 Oct 2026 03:14:22 +0000

一句話結論：單機 k3s 叢集用 kube-prometheus-stack 一個 chart 就能裝好 Prometheus 與 Grafana，但要記得關掉 kube-proxy、scheduler、controller-manager 這三個元件，不然對應的規則會一直誤報。整套大約吃 850 MiB 記憶體。

遇到的問題

叢集跑起來之後，下一個問題是：它現在健康嗎？哪個 Pod 吃了太多資源？

Prometheus 加 Grafana 幾乎是標準答案。但要自己一個一個裝 Prometheus、Grafana、kube-state-metrics、node-exporter，再接起來、再寫規則，工作量不小。

kube-prometheus-stack 把這些打包成一個 chart。問題是它的預設值，是以標準的 Kubernetes 叢集為前提，換成 k3s 就會冒出一些意料之外的東西。

這篇整理出在單機 k3s 上需要調整的地方，所有 values 都在一個全新的單節點叢集上實際跑過。

手把手步驟

前提與測試版本

手邊要有一個 Kubernetes 叢集和 Helm。下面的指令與 values，是在這些版本上實測的：

元件	Chart 版本	應用程式版本
kube-prometheus-stack	92.10.1	Prometheus Operator v0.94.1

叢集是 k3s v1.31.5（單節點）。版本不同的話，values 的欄位可能不一樣，請對一下 chart 的 values.yaml。

步驟一：加 Helm repo

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

步驟二：寫 values

kube-prometheus-stack 一次帶來 Prometheus Operator、Prometheus、Grafana、Alertmanager、kube-state-metrics、node-exporter 和一整套預設規則與儀表板。新建 prom-values.yaml：

# k3s 把 kube-proxy／scheduler／controller-manager 編進 k3s 主程序，不是獨立的 Pod，
# chart 預設找不到對應的目標，不關的話對應的規則會一直誤報
kubeProxy: {enabled: false}
kubeScheduler: {enabled: false}
kubeControllerManager: {enabled: false}

prometheus:
  prometheusSpec:
    # 預設只選同一個 release 的 ServiceMonitor／規則，其他 namespace 的 exporter 會漏抓
    serviceMonitorSelectorNilUsesHelmValues: false
    podMonitorSelectorNilUsesHelmValues: false
    ruleSelectorNilUsesHelmValues: false
    retention: 7d
    retentionSize: 4GB
    resources:
      requests: {cpu: 100m, memory: 256Mi}
      limits: {cpu: 500m, memory: 1Gi}
    storageSpec:
      volumeClaimTemplate:
        spec:
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 10Gi

說明一下。

關掉三個 k3s 沒有的元件

這三個元件在 k3s 上是編在主程序裡的，不是獨立的 Pod，chart 預設的做法找不到它們。不關的話，後面「踩到的坑」會講到對應的規則會怎麼樣。

selector 三行

serviceMonitorSelectorNilUsesHelmValues 這三個設成 false，Prometheus 才會抓其他 release、其他 namespace 的 ServiceMonitor 和規則。

預設是只選跟這個 chart 同一個 release 標籤的資源，之後如果別的 Helm release 帶了自己的 ServiceMonitor，就會被忽略。

保留與容量

metrics 留 7 天，並用 retentionSize: 4GB 當第二道保險，避免磁碟被吃滿。兩個條件，先到的先生效。

資源與儲存

resources 把 Prometheus 的記憶體限制在 1 GiB，storageSpec 給它一顆 10 GiB 的 PVC。單機磁碟有限，這兩個數字請依自己的機器調整。

步驟三：安裝

helm upgrade --install monitoring prometheus-community/kube-prometheus-stack \
  --version 92.10.1 -n monitoring --create-namespace \
  -f prom-values.yaml --wait --timeout 10m

這個 chart 比較大，第一次拉映像大概要幾分鐘。

完成後確認：

kubectl get pods -n monitoring

應該會看到 Prometheus、Alertmanager、Grafana、Operator、kube-state-metrics、node-exporter 都是 Running。

步驟四：驗證

Grafana

先取得密碼，帳號是 admin：

kubectl get secret -n monitoring -l app.kubernetes.io/component=admin-secret \
  -o jsonpath="{.items[0].data.admin-password}" | base64 --decode; echo

再 port-forward：

kubectl port-forward -n monitoring svc/monitoring-grafana 3000:80

打開 http://localhost:3000 登入，到 Dashboards，chart 已經預設放好一批 Kubernetes 相關的儀表板。

Prometheus 目標與告警

kubectl port-forward -n monitoring svc/monitoring-kube-prometheus-prometheus 9090:9090

打開 http://localhost:9090，Status → Targets 應該全部是 UP（API server、CoreDNS、kubelet、kube-state-metrics、node-exporter、Grafana 等）。

Alerts 頁只會有一條在跑：Watchdog。這是 kube-prometheus-stack 刻意放的一條「永遠觸發」的心跳規則，用來確認告警管線本身活著，看到它是正常的。

如果看到其他規則在 firing，通常就是下面「踩到的坑」會講的情況。

資源用量

裝完幾分鐘後，用 kubectl top pods -n monitoring 量到的數字：

元件	記憶體
Grafana	約 465 MiB
Prometheus	約 292 MiB
Alertmanager	約 38 MiB
Prometheus Operator	約 26 MiB
kube-state-metrics	約 20 MiB
node-exporter	約 9 MiB

加起來約 850 MiB。整個節點（含 k3s 本身）當時用了約 2.4 GB。

這是剛裝好、幾乎沒有流量的數字。Prometheus 的用量會隨著抓取的目標與時間序列數量增加，上線之後請再觀察一陣子。

踩到的坑

1. k3s 上不關那三個元件，規則會一直誤報

這個我特地驗證過：把 kubeProxy、kubeScheduler、kubeControllerManager 都打開，過一分鐘去看規則，KubeProxyDown、KubeSchedulerDown、KubeControllerManagerDown 三條都進入 pending，等待時間是 900 秒。

也就是說 15 分鐘後它們就會變成 firing，而且永遠不會好，因為預設的設定在 k3s 上找不到任何目標。

要說明的是，k3s 並不是沒有這三個元件的 metrics。k3s 文件的 Requirements 頁，在網路埠的表格裡就列了 kube-proxy（10249）、kube-controller-manager（10257）、kube-scheduler（10259）的 metrics 埠。

只是想真的監控它們，需要自己處理綁定位址與抓取設定，這部分沒有實測，這裡選擇直接關掉。

另外用 helm template 比對渲染結果：打開時會多出這三條規則和對應的 ServiceMonitor，關掉之後兩者都是 0。

所以關掉這三個元件，是同時把目標、ServiceMonitor 和規則一起移除。

2. 別的 Helm release 的 ServiceMonitor 抓不到

chart 預設只選有自己 release 標籤的 ServiceMonitor、PodMonitor 和規則。

如果之後用另一個 Helm release 安裝資料庫或其他應用，它們帶的 ServiceMonitor 不會被這個 Prometheus 抓到，Targets 頁上就是看不到。

步驟二的那三行 ...NilUsesHelmValues: false 就是用來解這個問題的：改成不依 release 標籤過濾。

3. 叢集一大，可能撞到 inotify 上限

節點與 Pod 多了之後，系統可能開始隨機報 Too many open files，而且不是檔案描述符不夠，而是 inotify 的配額用完。

kind 的 Known Issues 文件對這點有說明：Ubuntu 預設的 fs.inotify.max_user_instances 是 128、max_user_watches 是 8192，對有很多節點的叢集不夠。

暫時調高：

sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl fs.inotify.max_user_instances=512

要永久生效，把兩行寫進 /etc/sysctl.conf（或 /etc/sysctl.d/ 底下的檔案）。這個設定是整台主機共用的，用容器當節點的叢集（例如 k3d、kind）會吃到同一份配額。

為什麼這樣選

kube-prometheus-stack，而不是自己組

一個 chart 就帶來 Operator、Prometheus、Grafana、kube-state-metrics、node-exporter 和一整套預設規則與儀表板。

自己一個一個裝也可以，但光是把它們接起來、再維護規則，就是不少工作。

代價是這個 chart 很大，預設值是為標準叢集設計的，換成 k3s 這種精簡發行版就要像上面這樣調整。

retention 7 天加容量上限

單機磁碟有限，所以同時設了時間（7 天）和容量（4 GB）兩個上限。要長期保存 metrics 的話，需要調大這兩個值和 PVC，或是把資料送到遠端儲存。

保留預設的 Alertmanager

這份 values 沒有動 Alertmanager，它會跟著預設一起裝起來。這是最省事的起點，之後想怎麼處理告警，再另外調整。

在 Kubernetes 上用 Loki + Alloy 收集 Pod log：單機小規模的 Helm values（實測）

Jimmy — Wed, 21 Oct 2026 03:13:53 +0000

一句話結論：單機叢集想集中看 Pod 的 log，可以用單一二進位模式的 Loki，加一個 Alloy 透過 Kubernetes API 收 log。兩份 values 就能跑起來，合計大約只吃 130 MiB 記憶體。

遇到的問題

Pod 出事的時候，最常做的事就是 kubectl logs。

但 Pod 重啟之後，上一次的 log 就看不到了。想跨 Pod、跨時間搜尋，更是做不到。

Loki 是這類需求常見的選擇。麻煩的是，官方 chart 的預設值是為正式環境設計的，直接 helm install 在單機叢集上，不是跑不起來，就是太重。

這篇把 Loki 和收集器 Alloy 需要調整的地方整理出來，所有 values 都在一個全新的單節點 k3s 叢集上實際跑過。

手把手步驟

前提與測試版本

手邊要有一個 Kubernetes 叢集和 Helm。下面的指令與 values，是在這些版本上實測的：

元件	Chart 版本	應用程式版本
grafana/loki	7.3.0	Loki 3.6.12
grafana/alloy	1.13.1	Alloy v1.20.1

叢集是 k3s v1.31.5（單節點）。版本不同的話，values 的欄位可能不一樣，請對一下 chart 的 values.yaml。

步驟一：加 Helm repo

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

兩個元件都放在 monitoring namespace，下面的指令會自動建立。

步驟二：裝 Loki（單一二進位模式）

Loki 的 chart 預設是 SimpleScalable 模式，需要物件儲存（例如 S3），還會拆成 backend、read、write 好幾組。

單機小規模用不到，改成單一二進位加本機檔案系統。新建 loki-values.yaml：

deploymentMode: SingleBinary

loki:
  auth_enabled: false
  commonConfig:
    replication_factor: 1
  schemaConfig:
    configs:
      - from: "2024-04-01"
        store: tsdb
        object_store: filesystem
        schema: v13
        index:
          prefix: index_
          period: 24h
  storage:
    type: filesystem
  limits_config:
    retention_period: 24h
  compactor:
    retention_enabled: true
    delete_request_store: filesystem
    compaction_interval: 1h

singleBinary:
  replicas: 1
  resources:
    requests: {cpu: 100m, memory: 256Mi}
    limits: {cpu: 500m, memory: 1Gi}
  persistence:
    enabled: true
    size: 10Gi

# 小規模單機用不到的元件，全部關掉
backend: {replicas: 0}
read: {replicas: 0}
write: {replicas: 0}
gateway: {enabled: false}
chunksCache: {enabled: false}
resultsCache: {enabled: false}
lokiCanary: {enabled: false}
test: {enabled: false}
sidecar:
  rules: {enabled: false}
monitoring:
  selfMonitoring: {enabled: false}
  serviceMonitor: {enabled: false}
  rules: {enabled: false}

幾個重點。

單一二進位

deploymentMode: SingleBinary 配上 backend、read、write 的 replicas: 0，才會只跑一個 Pod。

保留 24 小時

retention_period: 24h 只是設定了保留時間，真正去刪舊資料的是 compactor，所以 compactor.retention_enabled: true 要一起開，而且要指定 delete_request_store。

少了這兩項，log 不會被清掉，磁碟會慢慢長大。

關掉一堆東西

gateway、兩個 cache、canary、測試 Pod、規則 sidecar 在正式環境有用，單機用不到，關掉可以少跑好幾個 Pod。

安裝：

helm upgrade --install loki grafana/loki --version 7.3.0 \
  -n monitoring --create-namespace \
  -f loki-values.yaml --wait --timeout 6m

確認：

kubectl get pods -n monitoring

loki-0 應該是 1/1 Running。

步驟三：裝 Alloy 收 log

Alloy 是 Grafana 現在主推的收集器，用 Kubernetes API 把 Pod 的 log 轉送到 Loki。新建 alloy-values.yaml：

controller:
  type: deployment
  replicas: 1

rbac:
  create: true
serviceAccount:
  create: true

alloy:
  resources:
    requests: {memory: 256Mi}
    limits: {memory: 512Mi}
  configMap:
    create: true
    content: |
      discovery.kubernetes "pods" {
        role = "pod"
      }

      discovery.relabel "pods" {
        targets = discovery.kubernetes.pods.targets

        rule {
          source_labels = ["__meta_kubernetes_namespace"]
          target_label  = "namespace"
        }
        rule {
          source_labels = ["__meta_kubernetes_pod_name"]
          target_label  = "pod"
        }
        rule {
          source_labels = ["__meta_kubernetes_pod_container_name"]
          target_label  = "container"
        }
        rule {
          source_labels = ["__meta_kubernetes_pod_label_app_kubernetes_io_name"]
          target_label  = "app"
        }
      }

      loki.source.kubernetes "pods" {
        targets    = discovery.relabel.pods.output
        forward_to = [loki.write.default.receiver]
      }

      loki.write "default" {
        endpoint {
          url = "http://loki.monitoring.svc.cluster.local:3100/loki/api/v1/push"
        }
      }

設定檔是一條管線，從上往下：

discovery.kubernetes 找出所有 Pod。
discovery.relabel 把 namespace、Pod 名稱、容器名稱、app 標籤變成 Loki 的 label。
loki.source.kubernetes 讀取這些 Pod 的 log。
loki.write 推送到 Loki。

最後的 url 是上一步 Loki 的 Service 名稱，release 名稱不是 loki 或 namespace 不同的話，這裡要跟著改。

因為是用 Kubernetes API 讀 log，這個元件不需要特權容器，也不用掛載主機的目錄，所以用一個 Deployment 就夠，不需要每個節點一個 DaemonSet。

安裝：

helm upgrade --install alloy grafana/alloy --version 1.13.1 \
  -n monitoring -f alloy-values.yaml --wait --timeout 5m

步驟四：驗證

Loki 有沒有收到 log

Loki 沒有網頁介面，用 Kubernetes 的 service proxy 直接問它：

kubectl get --raw \
  "/api/v1/namespaces/monitoring/services/loki:3100/proxy/loki/api/v1/labels"

收到 log 之後會看到這些 label：

{"status":"success","data":["app","container","instance","job","namespace","pod","service_name"]}

再實際查幾行 log。下面的查詢是 {namespace="monitoring"}（已經 URL 編碼），換成自己有 Pod 的 namespace 也可以：

kubectl get --raw \
  "/api/v1/namespaces/monitoring/services/loki:3100/proxy/loki/api/v1/query_range?query=%7Bnamespace%3D%22monitoring%22%7D&limit=3"

回傳的 JSON 裡，data.result[].stream 是 label，values 是 [時間戳, log 內容] 的陣列。

接上 Grafana（選用）

如果叢集裡已經有 Grafana，新增一個 Loki 資料來源就能用 Explore 查 log：

Type：Loki
URL：http://loki.monitoring.svc.cluster.local:3100

按 Save & test，看到 Data source successfully connected. 就接通了。接著在 Explore 查 {namespace="monitoring"}，查詢語言是 LogQL。

資源用量

裝完幾分鐘後，用 kubectl top pods 量到的數字：

元件	記憶體
Loki	約 73 MiB
Alloy	約 55 MiB

合計約 130 MiB。這是剛裝好、流量很小的數字，log 量變大之後 Loki 的用量會增加，上線之後請再觀察一陣子。

踩到的坑

1. Loki 的 chart 用預設值根本裝不起來

我直接 helm install grafana/loki，不加任何設定，會出現：

Error: execution error at (loki/templates/write/statefulset-write.yaml:50:28):
Please define loki.storage.bucketNames.chunks

補上檔案系統的儲存設定、但仍用預設的部署模式，則是：

Cannot run scalable targets (backend, read, write) or distributed targets
without an object storage backend.

原因就是預設的 SimpleScalable 模式需要物件儲存。單機請明確設定 deploymentMode: SingleBinary，並且把 backend、read、write 的 replicas 設成 0。

2. Loki 啟動時的 memberlist 警告可以忽略

單一二進位模式第一次啟動時，log 裡會出現類似這樣的警告：

Failed to resolve loki-memberlist.monitoring.svc.cluster.local ...

這是 Loki 在嘗試加入叢集，單副本的情況下找不到其他成員，過幾秒就會繼續正常啟動。只要 loki-0 最後是 1/1 Running 就沒事。

3. 要有 compactor，保留時間才會生效

只設 retention_period 不會刪資料。要同時開 compactor.retention_enabled: true 並指定 delete_request_store，這點在 Loki 官方的 Log retention 文件裡有說明。

4. 看不到節點本身的 log

loki.source.kubernetes 只能收 Pod 的 log。官方文件特別註明，它收不到 Kubernetes 節點本身的 log（例如 systemd 的 log）。

如果也需要節點層級的 log，要另外加其他來源。

為什麼這樣選

Loki 單一二進位，而不是 SimpleScalable

單機沒有高可用的需求，檔案系統加單一副本最簡單。

代價是：這個模式沒有水平擴展，也沒有備援，資料就放在一顆 PVC 上。log 量大到單機撐不住的時候，才需要換成物件儲存加分散式部署。

Alloy，而不是 Promtail

Grafana 的 Promtail 文件上寫得很清楚：Promtail 已經在 2026 年 3 月 2 日結束生命週期（EOL），不再有任何支援與更新，之後的功能開發都在 Alloy。所以新的部署直接用 Alloy。

用 loki.source.kubernetes 的好處，官方文件也寫了：它透過 Kubernetes API 讀 log，不需要特權容器，也不需要 root。

保留只有 24 小時

這是刻意的。單機磁碟有限，log 主要用來排查剛發生的問題，要長期保存的話，需要調大 retention_period 和 PVC。

k3d 別再用 image import 了：改用本機 registry，磁碟再也不會莫名其妙爆掉

Jimmy — Mon, 19 Oct 2026 03:06:46 +0000

一句話結論：在 k3d 裡自己 build 的映像，不要一直 k3d image import，建一個本機 registry，再把 docker.io 的 mirror 指過去，節點需要時才拉，磁碟用量和舊版本回收都會好處理很多。

遇到的問題

我在本機用 k3d 跑著一個多節點的叢集，裡面有不少服務是自己 build 的映像。

一開始都是 build 完就 k3d image import，簡單、不用架任何東西，用起來也很順。

直到有一天，系統碟快滿了。

一查才發現，每個節點的 /var/lib/rancher/k3s 都長到 20 多 GB。原因有兩個：

每個節點都存一份。 k3d image import 是把映像塞進「每一個」節點各自的 containerd，節點越多，存的份數越多。
舊版本永遠不會被回收。 tag 固定寫 0.1.0，每次重新 build 都覆蓋同一個 tag，舊的那份就變成 <none>，沒有任何東西會去清它。

而 kubelet 預設要等到磁碟用量 85% 才開始回收映像（回收到 80%）。

另外「閒置太久就回收」的 imageMaximumGCAge 預設是關閉的。

系統碟夠大的話，這個門檻幾乎永遠不會觸發，舊映像就這樣一路堆上去。

後來改成用本機 registry，下面是實際的做法，可以跟著做。

手把手步驟

步驟一：建叢集的時候順便建 registry

k3d 的設定檔可以直接宣告 registry，一次到位。新建一個 cluster.yaml：

apiVersion: k3d.io/v1alpha5
kind: Simple
metadata:
  name: dev
servers: 1
agents: 2
registries:
  create:
    name: k3d-dev-registry
    host: "127.0.0.1"
    hostPort: "5001"
    image: docker.io/library/registry:3
    volumes:
      - /srv/k3d-registry:/var/lib/registry
  config: |
    mirrors:
      "docker.io":
        endpoint:
          - http://k3d-dev-registry:5000

有幾個地方先說明一下。

兩個埠

hostPort: "5001" 是在主機上 push 用的埠。節點之間互相連是走容器內的 5000，所以 mirror 的 endpoint 寫 :5000。

這兩個埠很容易搞混。

資料放哪裡

volumes 把 registry 的資料放到主機上，叢集砍掉重建，映像也還在。路徑請換成自己的。

registry 版本

image 指定 registry:3，原因放在後面「踩到的坑」講。

mirror

重點是 mirrors：把 docker.io 的 mirror 指到這個本機 registry。

之後 Manifest 裡寫的 myorg/app:0.1.0（等於 docker.io/myorg/app:0.1.0）會先去本機 registry 找，找不到才自動回退到 Docker Hub。

k3s 文件寫得很清楚：containerd 對每個 registry 都有一個隱含的「預設 endpoint」，不管 mirror 怎麼設，最後一定會試它。

所以 Helm chart 或 YAML 完全不用改映像名稱。

然後建叢集：

k3d cluster create --config cluster.yaml

步驟二：確認 registry 起來了

curl -s http://127.0.0.1:5001/v2/_catalog

剛建好應該會看到：

{"repositories":[]}

步驟三：build 之後 push 到本機 registry

先 build 你的映像，再 tag 成本機 registry 的位址然後 push：

docker build -t myorg/app:0.1.0 .
docker tag  myorg/app:0.1.0 127.0.0.1:5001/myorg/app:0.1.0
docker push 127.0.0.1:5001/myorg/app:0.1.0

注意 push 的路徑是 myorg/app:0.1.0，不要帶 docker.io/。因為節點是依「docker.io 底下的 myorg/app」去 mirror 找的，路徑要對得上。

再看一次 catalog，應該就有東西了：

curl -s http://127.0.0.1:5001/v2/_catalog
# {"repositories":["myorg/app"]}

步驟四：部署，Manifest 照舊

你的 Deployment 繼續寫：

image: myorg/app:0.1.0
imagePullPolicy: IfNotPresent

部署之後，建議直接到節點裡驗證，確認它真的是從本機 registry 拉的，而不是剛好從 Docker Hub 拉到同名映像：

docker exec k3d-dev-server-0 crictl pull myorg/app:0.1.0

再去 registry 看一下有沒有被請求過（或者乾脆把 Docker Hub 上不存在的名字拿來測，能拉到就一定是本機的）。

步驟五：同一個 tag 重新 build 的時候

如果 tag 不變（例如固定用 0.1.0），重新 push 之後，節點上可能還留著舊的 0.1.0。

這時 IfNotPresent 不會重新去拉。解法是 push 完順手把各節點上同名的 tag 刪掉：

for node in k3d-dev-server-0 k3d-dev-agent-0 k3d-dev-agent-1; do
  docker exec "$node" crictl rmi docker.io/myorg/app:0.1.0 >/dev/null 2>&1 || true
done

這樣下次 Pod 重建時就會重新拉新的。

正在跑的容器不受影響。

被你覆蓋掉的舊版本，內容在 registry 裡還是會佔空間，要跑 garbage collect 才會回收。

跑 GC 之前，請先確定沒有人正在 push。

Distribution 官方文件明確警告：GC 進行時如果同時上傳映像，layer 可能被誤刪，造成映像損壞。

建議先用 --dry-run 預覽會刪什麼：

docker exec k3d-dev-registry \
  registry garbage-collect --dry-run --delete-untagged /etc/distribution/config.yml

確認沒問題再正式執行：

docker exec k3d-dev-registry \
  registry garbage-collect --delete-untagged /etc/distribution/config.yml

如果你的 tag 每次都不一樣（用 git SHA 之類），其實就不需要步驟五的第一段，只要偶爾跑 GC 就好。

步驟六：把 kubelet 的映像回收調積極一點

映像改由 registry 提供之後，節點上的映像被回收了也沒關係，要用時再拉回來就好。

所以可以把回收門檻調低。新增一個 kubelet-image-gc.conf：

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
imageGCHighThresholdPercent: 50
imageGCLowThresholdPercent: 40
imageMaximumGCAge: 168h

意思是：磁碟用到 50% 就開始回收，一直回收到 40%（kubelet 預設是 85% 和 80%）；另外，閒置超過 7 天的映像，不管磁碟用量多少都回收。

有一點要知道：Kubernetes 文件提到，imageMaximumGCAge 不會跨 kubelet 重啟追蹤。

kubelet 一重啟，計時就歸零，要重新等滿這段時間。

所以節點常常重啟的話，這個條件很難真正觸發，主要還是靠磁碟門檻在回收。

然後在 cluster.yaml 把它掛進每個節點，並讓 kubelet 讀取那個目錄：

volumes:
  - volume: /srv/kubelet-image-gc.conf:/etc/rancher/k3s/kubelet.conf.d/50-image-gc.conf
    nodeFilters:
      - all
options:
  k3s:
    extraArgs:
      - arg: --kubelet-arg=config-dir=/etc/rancher/k3s/kubelet.conf.d
        nodeFilters:
          - all

實際效果

改用 registry、調整 kubelet 回收之後，節點的磁碟用量差很多。

	改之前	改之後
每個節點的 `/var/lib/rancher/k3s`	約 25 GB	約 5 到 11 GB
本機 registry	沒有	約 3.6 GB

這組數字要稍微保守看待。

「改之前」是當時量到的，現在已經沒辦法重現。

「改之後」是現在量的。這個目錄除了映像，還包含容器的可寫層、log 等，所以不同節點差異會比較大，取決於上面跑了哪些 Pod。

所以拿來看趨勢就好，不是嚴格的前後對照實驗。

如果你已經有叢集了

不用重建。

做法是在每個節點寫一份 /etc/rancher/k3s/registries.yaml（內容就是上面的 mirror 設定），再逐一重啟節點。

要注意重啟節點時，上面的 Pod 也會跟著重啟，跟主機重開機差不多，挑個不忙的時間做。

流程可以寫成一個小 script：先把節點上現有的映像推進 registry，再寫設定，最後一個一個重啟。

踩到的坑

1. registry:2 的 GC 會把映像刪壞

這個坑我踩得最久。

--delete-untagged 在 registry:2 上，會把 OCI index 底下的子 manifest 當成沒有 tag 的東西刪掉。而用較新版 Docker（containerd image store）push 上去的映像，剛好就是 OCI index。

結果就是 GC 跑完，映像整個拉不下來。

換成 registry:3 之後就正常了，所以一開始就選 v3。

2. imageMaximumGCAge 沒有對應的命令列參數

本來想用 --kubelet-arg 直接傳，結果 kubelet 直接起不來。

它只能寫在 KubeletConfiguration 檔案裡，所以才要用 config-dir 這種 drop-in 的方式。

3. 先別在節點上跑 crictl rmi --prune

在映像還沒進 registry 之前，這個指令會把節點上「目前沒在使用」的映像一起刪掉。

而那些映像又沒有別的地方可以拉回來，之後排到那個節點的排程工作就會 ImagePullBackOff。

我就是這樣被咬過一次，最後從別的節點把映像複製回來才解決。

順序應該是：先把映像都放進 registry，再交給 kubelet 的 GC 去清。

為什麼這樣選

考慮過兩種做法。

直接用 localhost:5001/myorg/app 這種名稱

好處是很明確，不會有「這個映像到底從哪來」的疑問。

缺點是 Manifest 要改，而且 chart 要同時給本機和其他環境用，不想為了這個維護兩套映像名稱。

mirror docker.io（最後選的）

Manifest 一個字都不用改，要換環境也不受影響。

但缺點要記得：只要本機 registry 沒有，就會回退去 Docker Hub 拉同名的映像。

所以映像的命名空間（上面的 myorg）一定要是自己在 Docker Hub 上擁有的。不然有人在那邊註冊同名映像，registry 沒東西時就會拉到別人的。

如果只是做一次性的實驗，k3d image import 其實完全夠用，不需要為了這個架 registry。

映像很多、又會頻繁覆蓋同一個 tag 的情況下，才覺得值得。

ArgoCD App of Apps 實作：一個 root Application 管理叢集裡所有的 App

Jimmy — Fri, 16 Oct 2026 04:00:12 +0000

一句話結論：把 ArgoCD 裝好之後，只手動 apply 一個 root Application，讓它掃描 Git 裡的某個目錄；之後要新增、修改、移除任何 App，都只要改 Git，不用再碰 kubectl apply。

遇到的問題

GitOps 的第一步，通常是為每個服務建立一個 ArgoCD Application。

服務少的時候沒問題。服務一多，就變成每新增一個，都要手動 kubectl apply 一份 Application 的 YAML。

這等於在 GitOps 裡留了一個沒被 GitOps 管的缺口：Application 本身不在 Git 的管理範圍內。

解法是 App of Apps：用一個 Application，去管理其他所有 Application。

這篇用最小的例子，從安裝 ArgoCD 開始，走完整個流程。

手把手步驟

步驟一：用 Helm 裝 ArgoCD

前提是手邊已經有一個 Kubernetes 叢集，minikube、kind 或雲端的都可以。

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

helm upgrade --install argocd argo/argo-cd \
  --namespace argocd --create-namespace \
  --wait --timeout 15m

確認 ArgoCD 起來了：

kubectl -n argocd get pods
kubectl -n argocd rollout status deploy/argocd-server

官方的 Getting Started 是用 kubectl apply 安裝 manifest。這裡改用 Helm，之後想調整參數（資源限制、Ingress 等）比較方便，也方便升級。

步驟二：登入 UI 看一下

最簡單的方式是 port-forward：

kubectl port-forward svc/argocd-server -n argocd 8080:443

然後用瀏覽器打開 https://localhost:8080（憑證是自簽的，瀏覽器會警告）。

帳號是 admin，初始密碼這樣取：

argocd admin initial-password -n argocd

沒有裝 argocd CLI 的話，也可以直接讀 Secret：

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d; echo

官方文件提醒：登入並改完密碼之後，要把 argocd-initial-admin-secret 刪掉。這個 Secret 只是初始用，留著沒有意義。

步驟三：準備 Git repo 的結構

建一個 Git repo，結構長這樣：

gitops/
├── bootstrap/
│   └── root-app.yaml     # 手動 apply 一次
└── apps/                  # root 會掃描這個目錄
    └── guestbook.yaml     # 一個子 Application

兩個目錄要分開：bootstrap/ 放只需要手動套用一次的東西，apps/ 放 root 要持續掃描的東西。

不要把 root 自己放進 apps/，否則會變成 root 在管理自己，行為難以預期，也很難理解。

步驟四：寫一個子 Application

apps/guestbook.yaml，使用 ArgoCD 官方的範例 repo，大家都能拿到：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

幾個欄位值得說明一下。

namespace

Application 這個物件本身預設要放在 argocd namespace。

spec.destination.namespace 才是這個 App 的資源要部署到哪裡。兩個很容易搞混。

finalizer

resources-finalizer.argocd.argoproj.io 的作用是：刪除這個 Application 時，連它部署出來的資源也一起刪掉（預設是前景的 cascading deletion）。

沒有加的話，刪掉 Application 只會移除 ArgoCD 的紀錄，資源還留在叢集裡。

syncPolicy

automated 打開自動同步。prune: true 代表 Git 裡移除的資源，叢集裡也會被刪掉。selfHeal: true 代表有人手動改了叢集內容，ArgoCD 會把它改回 Git 的樣子。

CreateNamespace=true 讓 ArgoCD 在目標 namespace 不存在時自動建立。

步驟五：寫 root Application

bootstrap/root-app.yaml：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/<你的帳號>/gitops.git
    targetRevision: main
    path: apps
    directory:
      recurse: true
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

這份 YAML 跟子 Application 長得幾乎一樣，差別有兩個。

path: apps 加 directory.recurse: true

path 指向要掃描的目錄。ArgoCD 預設只讀該目錄第一層的檔案，要往下一層一層讀，要設 recurse: true。

所以之後可以在 apps/ 底下用子資料夾整理，root 一樣讀得到。

destination 的 namespace 是 argocd

因為 root 部署出來的東西就是「Application 這種物件」，而它們預設要在 argocd namespace。

把這個 repo 推到 Git，repoURL 換成自己的。如果是私有 repo，要先在 ArgoCD 設定 repo 的存取憑證。

步驟六：套用 root，看它長出子 App

kubectl apply -f bootstrap/root-app.yaml

這是唯一一次要手動 apply 的東西。

看一下結果：

kubectl get applications -n argocd

預期會看到 root 與 guestbook 兩個，狀態慢慢變成 Synced 與 Healthy：

NAME        SYNC STATUS   HEALTH STATUS
guestbook   Synced        Healthy
root        Synced        Healthy

ArgoCD 預設大約每 3 分鐘輪詢一次 Git，所以 push 之後可能要等一下。急的話，在 UI 上按 Refresh 就會立刻檢查。

步驟七：新增、移除 App，只改 Git

要新增一個 App，在 apps/ 加一個 Application 的 YAML，commit、push。

等下一輪輪詢（或按 Refresh），root 就會偵測到新檔案，建立對應的 Application，新的 App 再各自同步。

要移除，把檔案刪掉再 push。因為 root 有 prune: true，那個 Application 會被刪除，加上子 Application 的 finalizer，它部署的資源也會一起清掉。

全程不需要再對叢集下 kubectl apply。

踩到的坑

1. 刪掉 root，會連帶刪光所有子 App 和它們的資源

root 有加 finalizer，所以刪除它會級聯往下刪：先刪子 Application，子 Application 因為也有 finalizer，再刪它們部署的資源。

換句話說，一個 kubectl delete application root，就能把整個叢集的服務清空。

官方的 Cluster Bootstrapping 文件有專門一節在講這件事。

如果不想要這種風險，可以考慮不給 root 加 finalizer，或是關掉 root 的 prune。取捨是：以後刪除 root 或移除子 Application 時，要自己處理殘留的資源。

2. 子 Application 本身的設定，是由 root 負責同步的

這個坑很隱蔽。假設改了某個子 Application 的設定（例如 plugin 的環境變數、syncOptions），push 之後，如果 root 還沒同步這個改動，子 Application 會繼續用舊的設定渲染，狀態還顯示 Synced，但新開的資源就是沒有出現。

我就是這樣被騙過：看起來一切正常，卻怎麼等都沒有東西。

處理方式是：先確認 root 已經是 Synced，再對子 Application 做一次 hard refresh：

kubectl -n argocd annotate application <名稱> \
  argocd.argoproj.io/refresh=hard --overwrite

hard 的意思是連 manifest 快取都清掉再重新評估。

3. recurse: true 會讀到目錄裡所有的 YAML

root 掃描的目錄裡，只應該放 Application 的 manifest。

如果裡面混了其他 YAML（文件、範例、值檔），ArgoCD 會把它們都當成要部署的資源，可能直接報錯，或是意外建立不該存在的東西。

把「手動套用一次的東西」和「持續掃描的東西」分在不同目錄，就是為了避免這個問題。

為什麼這樣選

官方的 Cluster Bootstrapping 文件，推薦的其實是 ApplicationSet，App of Apps 被列為替代方案。

ApplicationSet 適合「很多個長得很像的 App」或「要部署到很多個叢集」，用 generator 一次產生一堆 Application，不用寫一堆 YAML。

我選 App of Apps 的原因很單純：

一個 App 一個檔案，看檔案就知道它的設定，容易讀。
每個 App 的設定可以各自不同（有的自動同步，有的手動）。
概念簡單，不需要先學 generator 和模板語法。

單一叢集、App 數量不多、每個差異不小的情況，這樣就夠了。要管很多叢集或很多相似的 App，可以直接看 ApplicationSet。

另外有一個官方的安全警告值得記住：App of Apps 是管理員專用的工具。

能在任意 Project 底下建立 Application，等於是管理員等級的權限。所以只有管理員能對 root 所指向的 repo 推送，改動也應該經過審核。

DEV Community: Jimmy

Bitnami 映像搬家後：漏改 exporter 的坑，以及用原映像加上 pgvector

當初怎麼做

為什麼只改主映像不夠

手把手：先看渲染結果

1. 把用到的 image 分開列出

2. 渲染後逐一核對

後來為什麼又自己 build

怎麼確認相容

換了之後的代價

延伸閱讀

把 AI CLI 包成 OpenAI 相容 API：從 stdin、JSON 輸出到逾時處理（附可跑範例）

遇到的問題

先決定相容到哪裡

手把手步驟

1. 先準備一支假 CLI

2. 加上 HTTP 包裝

3. 啟動並送一個請求

踩到的坑

長 prompt 不要塞在命令列參數裡

stdout 不一定就是答案

HTTP 成功，不代表 CLI 成功

實測結果與限制

為什麼這樣選

延伸閱讀

ingress-nginx 退役之後：在臨時叢集實測 Traefik 的 ingress-nginx 相容模式與 Gateway API

遇到的問題

測試環境

手把手步驟

前置：k3s 內建的 Traefik 不能直接用

路線一：讓 Traefik 直接吃 nginx 的 Ingress

路線二：改寫成 Gateway API

HTTP 轉 HTTPS

IP 白名單

cert-manager 整合

長連線與逾時

ingress2gateway 轉出來的東西

踩到的坑

為什麼這樣評估

延伸閱讀

單機 Kubernetes 的管理介面連換兩次：Rancher Portainer Headlamp，以及 sessionTTL 與 token 的坑

當初怎麼做

哪裡不行

Rancher：用不到的功能太多，壞了又很難修

Portainer：輕量，但看 Helm 頁面會吃光記憶體

換成什麼

遷移怎麼進行

踩到的坑

坑一：token 的有效期限

坑二：token 沒過期，卻還是要重新登入

坑三：Application 永遠 OutOfSync

換了之後的代價

延伸閱讀

Helm umbrella chart 多加一個上游 chart，結果整批 Application 都渲染失敗：改用本地 wrapper chart（實測）

遇到的問題

先重現一次錯誤

手把手步驟

步驟一：建一個 wrapper chart

步驟二：wrapper 的 Chart.yaml 要宣告 dependencies

步驟三：umbrella 只依賴 wrapper

踩到的坑：巢狀子 chart 的 condition 沒生效

為什麼這樣選

延伸閱讀

用 Drain3 把 log 變成「新樣板才通知」：不用寫一堆關鍵字規則（附可跑的範例）

遇到的問題

手把手步驟

準備環境

先準備一些假的 log

核心腳本：只印出新樣板

跑起來看結果

把 Loki 接進來

踩到的坑

坑一：變數沒遮蔽，樣板數量爆炸

坑二：第一次執行，所有樣板都是「新」的

坑三：偵測器自己的輸出也被當成 log

為什麼這樣選

延伸閱讀

告警來了，讓 LLM 先做第一輪診斷：Grafana webhook 加一個小接收端就能做到（附可跑的範例）

遇到的問題

手把手步驟