Agent Proxy¶

概述¶

Agent Proxy 係一個由 Infisical CLI 提供嘅輕量級 secrets 代理服務，部署喺 wiki.benhoweb.com 嘅私有雲 Docker 環境入面。佢嘅核心功能係將 Infisical 後端所管理嘅 18 個服務密鑰聚合喺同一個代理節點，並透過 HTTP 請求嘅 Proxy-Authorization header 自動注入到對應嘅上游服務，達到統一憑證管理同動態授權嘅效果。同傳統嘅環境變數注入方式相比，Agent Proxy 提供咗更靈活、更安全嘅 secrets 分發機制，特別適合用於多服務微服務架構或 API Gateway 場景。

喺本機環境中，Agent Proxy 以容器方式運行，鏡像為 infisical/cli:latest，靜態 IP 設定為 172.21.0.64，並連接至外置嘅 cf_network 網絡。呢個設計確保代理服務可以同 Infisical 後端、其他服務（例如 LiteLLM、Cloudflare Tunnel）穩定互通，同時保持網絡隔離。

架構¶

Agent Proxy 嘅架構涉及三個主要部分：

Infisical 後端
位於 http://infisical-backend:8080，係 secrets 嘅中央儲存庫，儲存所有服務嘅密鑰、捲動歷史同存取權限。Agent Proxy 透過 Universal Auth 進行機器身份認證，取得讀取 secrets 嘅資格。
Agent Proxy 節點
即係本容器。佢啟動後會連接到 Infisical 後端，根據 client ID 同 client secret 取得短期 access token，然後拉取所有已授權嘅 secrets。當下游服務將流量導向呢個代理時，Agent Proxy 會根據目標主機名稱或路徑，揀選對應嘅服務密鑰，並以 Proxy-Authorization header 附加喺轉發請求前面。
下游服務
例如 LiteLLM、內部 API 等。佢哋唔需要直接接觸 Infisical，只需要將請求發送畀 Agent Proxy，並信任代理注入嘅授權資訊。因為 --unmatched-host=allow 參數，即使係未匹配嘅主機亦會被允許通過，只係唔會注入任何 secrets。

整體數據流：下游服務 → HTTP 請求 → Agent Proxy（172.21.0.64:某埠）→ 根據 host 判斷 → 加載對應 secret → 注入 Proxy-Authorization header → 轉發至真實目標服務。呢個過程對上游服務嚟講係完全透明，但安全性由代理集中把關。

部署¶

以下係實際使用嘅 Docker Compose 節選：

services:
  agent-proxy:
    image: infisical/cli:latest
    container_name: agent-proxy
    restart: unless-stopped
    command: secrets agent-proxy start --unmatched-host=allow
    volumes:
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro
      - /home/opc/agent-proxy/data:/root/.infisical
    environment:
      - TZ=Asia/Hong_Kong
      - INFISICAL_DOMAIN=http://infisical-backend:8080
      - INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=${INFISICAL_PROXY_CLIENT_ID}
      - INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=${INFISICAL_PROXY_CLIENT_SECRET}
    networks:
      cf_network:
        ipv4_address: 172.21.0.64
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: "0.5"

networks:
  cf_network:
    external: true

部署步驟：

確保 Infisical 後端已經運行，並且你可以喺同一個 Docker 網絡（cf_network）內存取 infisical-backend:8080。
喺 Infisical 後台建立一個 Universal Auth 機器身份，並將對應嘅 client ID 同 client secret 設定喺環境變數檔案或 .env 入面。
執行 docker compose up -d 啟動服務。
檢查日誌確認代理已成功認證並開始監聽。

配置¶

主要配置項包括：

TZ=Asia/Hong_Kong：設定容器時區，確保日誌時間同香港時間一致。
INFISICAL_DOMAIN：指到 Infisical 後端服務地址，必須確保網絡連通。
INFISICAL_UNIVERSAL_AUTH_CLIENT_ID 同 ..._SECRET：使用環境變數引用 .env 檔案，避免明文寫死喺 compose 內。
--unmatched-host=allow：允許未匹配任何 secret 嘅 host 請求仍然通過，適合做 fallback 或透明代理。
Volume 掛載：/home/opc/agent-proxy/data 持久化 Infisical 本地緩存及 token，避免每次重啟都重新認證。
網絡設定：指定靜態 IP 172.21.0.64，這樣下游服務可以用固定 IP 連接到代理，亦方便防火牆規則。
資源限制：限制記憶體 256M、CPU 0.5，確保呢個輕量代理唔會佔用過多資源。

維運與監控¶

日常維運建議：

日誌查詢：使用 docker logs agent-proxy 查看代理運作狀態。如果出現認證錯誤，通常會喺日誌輸出 401 或 invalid client credentials。
健康檢查：可以定期用 curl -x http://172.21.0.64:80 https://target-service 測試代理是否正常注入 header。留意 Proxy-Authorization 是否存在。
資源監控：因為有設定資源上限，可以用 docker stats 監控實際使用情況。如果記憶體長期接近 256M，要考慮是否 secret 數量過多或需要調整緩存策略。
更新鏡像：infisical/cli:latest 會持續更新，建議喺測試環境先驗證新版本，然後再 upgrade。
輪換密鑰：當 Infisical 後台輪換服務密鑰時，Agent Proxy 會自動偵測並重新注入，無需重啟容器。但如果本地緩存過期，則需要確認容器可以連接到後端。

常見問題¶

問：Agent Proxy 啟動後冇任何日誌，係咪正常？
答：可以利用 --log-level 參數增加日誌詳細程度。如果完全冇輸出，首先檢查 INFISICAL_DOMAIN 是否正確，同埋容器能否 ping 通 infisical-backend。

問：下游服務收唔到 Proxy-Authorization，點解？
答：可能原因包括：對應 host 未有喺 Infisical 入面配置任何 secret；或者代理啟動時因為網絡問題未能成功拉取 secrets。執行 docker exec agent-proxy infisical secrets 檢查本地已快取嘅 secrets 列表。

問：--unmatched-host=allow 會唔會有安全隱患？
答：呢個參數令到任何 host 都可以被代理，但只有匹配 secret 嘅先會注入授權 header。如果代理暴露喺唔受信任嘅網絡，建議改為 --unmatched-host=reject 或只允許特定 host。

問：點樣確認 18 個服務密鑰已經全部聚合？
答：你可以喺 Infisical 後台睇返呢個機器身份被賦予咗幾多個 secrets；亦可以通過代理嘅 debug 端點或日誌查詢。

來源¶

自動生成（2026-08-19 容器覆蓋率補完第二批）

Agent Proxy¶

概述¶

架構¶

部署¶

配置¶

維運與監控¶

常見問題¶

相關鏈接¶

來源¶