Superlog 自行託管安裝與 VPS 資源需求

Superlog 自行託管實際安裝的內容

若要自行託管 Superlog，請先複製儲存庫，使用 Docker Compose 啟動 Postgres、ClickHouse 與 OpenTelemetry collector，執行一次資料庫 migration，然後從原始碼啟動 4 個 Node 服務。您的應用程式會將 OTLP（OpenTelemetry protocol）traces、logs 與 metrics 傳送至 intake 埠。Superlog 會為這些資料建立指紋，將重複事件彙整為單一 incident，並由 agent 撰寫第一輪 triage 結果。安裝需要一個下午。開始之前，最值得先了解的是所需資源與實際限制。

Superlog 採用 Apache 2.0 授權，原始碼位於 github.com/superloglabs/superlog。截至 2026 年 8 月，該專案約有 1.2k 顆 stars、在 main 上約有 460 次 commits，且完全沒有 release tags。最後一點會直接影響安裝方式：git checkout v1.0.0 沒有任何可供 checkout 的內容，因此您必須自行固定某個 commit，或使用複製當天早上 main 當時的版本。

Superlog 能回答 Uptime Kuma 與 Langfuse 無法回答的問題

從外部看，自架監控工具似乎可以互相替代。實際上並非如此，選錯工具只會浪費伺服器資源，卻得不到任何好處。

• Uptime Kuma 從外部探測端點，只回答一個問題：服務是否正常。
• Zabbix 在 Ubuntu 24.04 上監控主機與服務，根據你設定的門檻檢查 CPU、記憶體、磁碟與服務狀態。
• Langfuse 追蹤 LLM 呼叫，記錄每次呼叫的 prompt、模型、token、延遲與成本。
• Superlog 會接收一般服務原本就會產生的遙測資料，並將重複發生的失敗轉換為事件。

Superlog 負責回答另一個問題：哪裡發生故障，以及原因為何。它不處理 LLM 呼叫，也不會從外部探測你的服務。它會接收一般應用程式程式碼產生的 OTLP，並在分流處理階段加入 agent。這正是值班人員通常會先執行的初步檢查。

對 VPS 預算而言，真正重要的差異在於儲存方式。Uptime Kuma 只需 1 GB RAM 也能順利運作，因為它只儲存幾千筆檢查結果。Superlog 使用 column store，因為遙測資料寫入一次後，還要依時間範圍查詢數百萬筆資料。這正是 ClickHouse 的用途，而不是 Postgres 的用途。Postgres 仍在整體架構中，負責儲存少量關聯式資料，例如專案、使用者、事件與 ingest key。

docker compose up -d 實際啟動哪些項目？

它會啟動 3 個容器，而且其中沒有任何一個是 Superlog。期待執行一個指令就完成安裝的人，通常會對此感到意外。

• postgres:16，發布到主機的 5434 埠
• clickhouse/clickhouse-server:26.1，使用 8123 提供 HTTP，並使用 9000 提供原生通訊協定
• otel/opentelemetry-collector-contrib:0.150.1，使用 4317 提供 gRPC，並使用 4318 提供透過 HTTP 的 OTLP

Superlog 應用程式會在主機上從原始碼執行，並由 pnpm dev 啟動。截至 August 2026，repository 中沒有 production compose file，因此若要長期執行，必須自行為各應用程式的 start script 建立 systemd unit，或使用 tree 中隨附的各應用程式 Dockerfile。

請記住 span 經過的路徑，因為下方每個失敗情況，都是其中一個 hop 中斷所造成。你的應用程式會將 OTLP 發送至 Superlog intake proxy。proxy 會使用 ingest key 驗證請求，為請求加上 project id，然後轉送至 collector。collector 會移除 client 嘗試設定的任何 superlog.* attribute，從 proxy 提供的 header 加入 superlog.project_id，再進行批次處理並寫入 ClickHouse。web app 和 API 會從 ClickHouse 讀取 telemetry，其他所有資料則從 Postgres 讀取。

移除這些 attribute 是實際的 multi-tenancy 控制措施，不是裝飾用途。若沒有這項控制，任何持有一組有效 ingest key 的人，都能自行設定 superlog.project_id，並將資料寫入其他 project 的資料中。

VPS 需要多大的規模？

對於低攝取量的單節點安裝，建議規劃 4 vCPU、8 GB RAM 與 40 GB SSD。這是規劃下限，不是實測結果，因此應先以此作為起始規模，再根據實際流量驗證。

記憶體主要分配到 4 個部分。ClickHouse 的設計目標是具備充足 RAM 的機器，其預設值也以此為前提。Postgres 16 在這裡的需求較低，因為它儲存的是中繼資料，而不是遙測資料。collector 的需求也不高。4 個 Node 程序則不同：Vite 開發伺服器加上 3 個 tsx watch 程序，每個都可能占用數百 MB，因此在 2 GB 的主機上執行 pnpm dev 會很吃力。

磁碟空間是較不明顯的問題。在這個 monorepo 中，pnpm install 會先拉取 AWS SDK、ClickHouse client、OpenTelemetry SDK 與 React toolchain，之後你才會攝取第一個 span。ClickHouse 接著會隨流量增加。請同時測量：

df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"

在低流量下，少數服務每分鐘傳送幾百個 span，主機負載很低，ClickHouse 大多時間處於閒置狀態。真正造成負載的是突發流量：例如一次錯誤的部署，導致每分鐘產生數千筆相同錯誤。指紋比對會將這些錯誤彙整為讀者看到的一個 incident，但 ClickHouse 底層仍會寫入每一筆資料列。

保留期限由你設定。collector 的 ClickHouse exporter 會建立資料表、otel_traces、otel_logs，以及每種 metric type 各自的一個資料表。只有在 infra/collector/config.yaml 中的設定指定 time to live 時，才會套用到期時間。資料不會自行過期，因此若未事先規劃，繁忙的一個月就可能耗盡整個磁碟。

從固定的 commit 安裝

git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'

git tag -l 沒有輸出是截至 2026 年 8 月的預期結果。選擇你測試過的 commit，並固定使用該版本：

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

接著處理工具鏈：

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

package.json 宣告 engines.node 為 >=20.0.0，並將 packageManager 宣告為 pnpm@9.12.0。在較舊版本的 Node 上執行安裝時，pnpm 會以 ERR_PNPM_UNSUPPORTED_ENGINE 停止，並指出所需的版本。Ubuntu 24.04 軟體庫中的 nodejs 套件早於 20，因此請透過 NodeSource 或 nvm 安裝 Node 20 或更新版本。儲存庫附有 .nvmrc，因此如果已安裝 nvm，nvm use 會選取指定的版本。

pnpm install
docker compose up -d
docker compose ps

請等待健康檢查完成，不要把 up -d 視為服務已就緒。Postgres 和 ClickHouse 都在 compose 檔案中宣告健康檢查：

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

ClickHouse 會回應 Ok.，而 pg_isready 會回應 accepting connections。在 8123 上收到 connection refused，表示容器仍在啟動，或容器已停止。docker compose logs clickhouse 可判斷是哪一種情況；如果核心因記憶體不足而終止容器，docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled 會回報 true。這表示主機規模太小，而不是設定錯誤。

接著執行 migration 並啟動應用程式：

pnpm --filter @superlog/db db:migrate
pnpm dev

請注意埠號：是 5434，不是 5432。compose 檔案將 Postgres 發布在 5434，避免與主機上已安裝的 Postgres 發生衝突；應用程式的 .env.example 檔案也使用相同設定，並包含 DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog。如果在已執行 Postgres 的主機上，將 migration 指向 5432，可能會收到 connection refused；更嚴重時，migration 可能會套用到錯誤的資料庫。

pnpm dev 會啟動儲存庫 Procfile 列出的 4 個程序：api、web、worker 和 proxy。每個程序都會將輸出同步寫入 tmp/logs/，因此可在 tail -f tmp/logs/proxy.log 監看 ingest。README 將 web app 設定在 http://localhost:5173，API 設定在 http://localhost:4100，OTLP intake 設定在 http://localhost:4101。

在將任何服務指向這些端點前，先確認實際繫結的埠號：

ss -lntp | grep -E '4100|4101|5173'
curl -sS http://127.0.0.1:4101/health

這項資訊之後很重要。proxy 會從 PORT 環境變數讀取自己的埠號；如果 PORT 未設定，則回退至 4000。development stack 會自動為你設定該變數，但你自行撰寫的 systemd unit 不會。因此，若 exporter 將目標設為 4101，而 proxy 實際監聽 4000，就會收到 connection refused，且不會提供其他線索。

傳送一筆追蹤資料、產生一個錯誤、查看一個事件

在 Web 應用程式中建立專案，並複製其 ingest key。接收端會使用該 key 驗證每個請求，因此未附帶 key 的遙測資料不會送達 ClickHouse。

使用標準環境變數，將任一 OpenTelemetry SDK 指向接收端：

export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'

接收端會從 x-api-key 標頭讀取 key；如果 exporter 以這種方式較容易設定，也接受 authorization: bearer YOUR_INGEST_KEY。它提供 3 個標準 OTLP 路徑：/v1/traces、/v1/logs 與 /v1/metrics，以及 /health。

有一個陷阱值得特別說明。OTEL_EXPORTER_OTLP_ENDPOINT 是基礎 URL，SDK 會將訊號路徑附加到此 URL。訊號專用變數（例如 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT）則會完全依原值使用，不會附加路徑。若將訊號專用變數設為 http://127.0.0.1:4101，每次匯出都會 POST 至 /。這不是有效路由，因此不會有資料抵達；SDK 會記錄匯出失敗，但應用程式看起來仍然正常。

對於 Node 服務，不需修改程式碼即可驗證整個資料管線：

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js

現在刻意造成一個錯誤。任何會拋出例外的路由都可以：

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom

依序檢查各個環節，因為第一個出現間斷的位置會指出失敗的環節：

tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'

如果 otel_traces 的計數持續增加，但 Web 應用程式中沒有資料，表示專案不一致。請確認 ingest key 所屬的專案。如果計數沒有增加，但 proxy log 有活動，問題可能出在 collector 或 ClickHouse 寫入流程，請查看 docker compose logs collector。如果 proxy log 完全沒有活動，表示 exporter 未抵達接收端：可能是連接埠錯誤、路徑錯誤，或 key 被拒絕。

在 Web 應用程式中，這些重複失敗會合併為一個事件，而不是每個請求各列一筆。Superlog 會為傳入的訊號建立指紋，並將相符的訊號分組。這能將收件匣中 4,000 個相同錯誤整合為一個事件。接著，agent 會在該群組上記錄調查結果。

調查步驟會呼叫模型，因此 worker 必須設定 model provider。請從你鎖定版本的 commit 中，每個應用程式目錄內的 .env.example 檔案取得這些變數名稱，不要依賴外部文件，因為這些名稱會隨 main 一起變更。GitHub 與 Sentry 整合也適用相同原則；它們各自在 docs/github-app-setup.md 與 docs/sentry-app-setup.md 提供設定文件，webhook payload 則記錄於 docs/webhooks.md。

讓 intake 保持私有，並將 agent 設為唯讀

Docker 預設會將容器連接埠發佈到 0.0.0.0。這些已發佈的連接埠會繞過 ufw，因為 Docker 會將自己的規則寫入 DOCKER-USER chain，而該 chain 會在 ufw 處理封包前先行評估。在具備公開 IP 的 VPS 上，隨附的 compose 檔案會將 ClickHouse HTTP 設為 8123，並將 Postgres 設為 5434，因此網際網路可以直接連入。該檔案中的認證資訊是開發環境預設值：ClickHouse 使用者為 default，密碼為空；Postgres 則以 postgres 同時作為使用者名稱與密碼。

將它們綁定到 loopback。compose 檔案中的每個已發佈連接埠，都會從環境變數取得主機端連接埠，因此只要在 repository root 建立 .env 即可：

POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318

在信任結果前先進行驗證，然後重新建立容器：

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

docker compose config 會印出解析後的檔案，因此你可以直接查看 127.0.0.1:5434:5432，不必猜測。接著，ss 應顯示 127.0.0.1:5434，且絕不應顯示 0.0.0.0:5434。不要透過重新宣告 ports 的 compose override 檔案來修正這個問題，因為 Compose 會合併不同檔案中的連接埠清單，而不是取代它們。結果會同時保留兩個綁定，公開連接埠仍然開放。

intake 也需要相同的防護。你的 ingest key 會隨標頭傳送，因此前方必須使用 TLS（transport layer security）：在 proxy 前方以 nginx 或 Caddy 終止 TLS，或將 ingest 保留在私有網路或 WireGuard tunnel 內。5173 上的 web app 是 Vite development server，完全不應直接面向網際網路。

接著處理 agent 本身。Superlog 的主張是由 agent 進行調查並提出修正，而其中重要的詞是「提出」。在你觀察它處理數起真實事件前，先讓它對 production 保持唯讀。為 GitHub App 授予讀取範圍，並允許它建立 pull request，再由你進行審查。能讀取遙測資料並寫入 patch 的 agent 很有用。能夠重新啟動服務的 agent，風險層級則完全不同；這應該是你刻意做出的決定，而不是被預設設定被動賦予的權限。成本也需要同樣重視，因為每次調查都會呼叫模型：在將 agent 指向吵雜的 production system 前，先 規劃 VPS 上的 agent 支出預算，並保留 agent 實際執行內容的紀錄，讓突如其來的 pull request 背後具備 audit trail。

會遇到的故障，以及用來表示這些故障的字串

• ERR_PNPM_UNSUPPORTED_ENGINE 期間出現 pnpm install，表示 Node 版本低於 20。node -v 可在一行中確認這一點。
• 遷移期間出現 ECONNREFUSED 127.0.0.1:5434，表示 compose stack 尚未啟動，或 DATABASE_URL 指定了錯誤的連接埠。
• ClickHouse 反覆重新啟動通常是記憶體問題。讀取 docker compose logs clickhouse，然後檢查容器中的 OOMKilled 是否為 true。
• Exporter 回報成功，但 Web 應用程式仍顯示空白，通常表示資料直接傳送至 4318 上的 collector，略過了 proxy 所執行的專案標記。
• 正式環境安裝在 4101 上遭到拒絕連線，表示 proxy 已回退至 PORT=4000。在 unit file 中明確設定 PORT。
• docker compose ps 顯示 0.0.0.0:8123，表示 loopback 綁定未生效。執行 docker compose config，並讀取解析後的連接埠。

Flawless、HyperProbe，以及 Superlog 的定位

這個類別仍在發展初期，各工具對 agent 可接觸範圍的定義也不同。Flawless 是開放原始碼的 AI SRE（site reliability engineering）工具，主要用於 Kubernetes。它會讀取既有的 Prometheus、Loki 與 Grafana stack，而不是自行管理整個資料管線。HyperProbe 則採取相反方向：截至 2026 年 8 月，它是閉源的託管產品，會在執行中的程序內放置唯讀 probe，以擷取變數狀態，並透過 MCP（model context protocol）將這些狀態提供給 assistant。

Superlog 位於兩者之間。它端到端管理整個資料管線，從 OTLP intake 一直到 ClickHouse 儲存，並將 agent 放在問題分流步驟，而不是修復步驟。這種設計正是自行託管 Superlog 屬於基礎架構決策，而不是啟動後就能置之不理的 container 的原因。執行 Superlog 後，你同時也在執行 column store；它需要與你自行管理的其他 database 一樣受到妥善維護。

FAQ

自架 Superlog 需要多少 RAM？

若單一節點的資料寫入量較低，請準備 8 GB RAM、4 vCPU 與 40 GB 磁碟空間。這套架構包含 Postgres、ClickHouse、OpenTelemetry collector 與 4 個 Node process，而 ClickHouse 需要預留足夠資源。1 GB 或 2 GB 的 VPS 不足以執行：僅 pnpm install 就相當耗用資源，負載增加時 ClickHouse 也可能被 kernel 的 out-of-memory killer 終止。請使用 docker stats --no-stream 與 free -m 測量自己的數值，不要直接採信任何已公布的數字，包括本段數值。

OTLP exporter 應指向哪個埠？

請指向 Superlog intake proxy；README 將其設定在 http://localhost:4101。該 proxy 提供 /v1/traces、/v1/logs 與 /v1/metrics，並使用從 x-api-key header 或 authorization: bearer header 取得的專案 ingest key 進行驗證。4318 埠是底層的 OpenTelemetry collector。直接向該埠匯出會略過 proxy，而 proxy 才是將 project id 加入資料的元件。若未設定 PORT，proxy 會回退至 4000 埠。因此，請執行 ss -lntp，確認實際繫結的埠，再判定是否使用 4101。

Superlog 能取代 Uptime Kuma 或 Zabbix 嗎？

不能。Uptime Kuma 用來確認從網路外部是否能連到端點，Zabbix 則會根據你設定的閾值監控主機與服務指標。Superlog 會接收應用程式產生的 traces、logs 與 metrics，並將重複發生的故障歸納為 incidents。請同時保留外部 uptime probe，因為當承載 telemetry pipeline 的主機故障時，在其他位置執行的 probe 仍能回報該問題。

Superlog agent 能變更我的 production systems 嗎？

只能在你授予權限的範圍內變更。它產生的是調查結果與建議變更，需由人員審查。初期請讓 GitHub App 僅具備 read scopes，並使用 pull requests；worker 持有的任何 credentials 也應限制為讀取權限。請將 production 的寫入權限視為另一項需要審慎決定的設定，因為能重新啟動服務的 agent，所需承擔的風險遠高於只能讀取 telemetry 並建立 patch 供審查的 agent。

我應固定 commit，還是追蹤 main？

請固定 commit。截至 2026 年 8 月，該 repository 沒有 release tags，因此 main 是唯一可用的移動目標，而且每週會有數個 commits。請記錄測試過的 SHA，部署該版本，並在升級前閱讀 diff。git log --oneline <old-sha>..main 是審查位置；每個 app 的 .env.example 檔案則是升級後確認新增必要變數的第一個位置。