# 策展 · X (Twitter) 🔥

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 作者：Makisuo (@makisuo) · 平台：X (Twitter) · 日期：2026-05-31

> 原始來源：https://x.com/makisuo/status/2061051991896596711

## 中文摘要

Maple Local 透過單一執行檔實現本機部署。

Makisuo 發布了 Maple Local，這是一款專為開發者及其 Agent 設計的免費本機 OpenTelemetry (OTEL) 工具。它捨棄了沉重的容器化部署，透過單一 Bun 編譯的二進位檔案，整合了 OTLP 接收器、嵌入式 ClickHouse 資料庫、查詢 API 及儀表板，讓使用者能在數秒內開始進行遙測資料的擷取與除錯。

**安裝與部署**
Maple Local 的設計目標是極致的輕量與離線可用性，無需雲端服務或身份驗證。安裝過程會自動偵測作業系統與架構，並處理必要的權限與環境變數設定。

1. 執行安裝指令：
   ```bash
   curl -fsSL https://maple.dev/cli/install | sh
   ```
   此指令會將 `maple` 與 `libchdb` 安裝至 `~/.maple/bin`，並自動設定 `PATH`。若需卸載，可執行 `curl -fsSL https://maple.dev/cli/uninstall | sh`。

2. 啟動伺服器：
   - 一般啟動：`maple start`
   - 離線模式（將儀表板打包在二進位檔內）：`maple start --offline`
   - 背景執行：`maple start -d`（停止請使用 `maple stop`）

**遙測資料擷取**
Maple Local 支援標準的 OTLP/HTTP 協定，開發者只需將應用程式的輸出端指向本機位址，無需額外的認證標頭。

- 設定環境變數以導向本機：
  ```bash
  export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"
  export OTEL_SERVICE_NAME="my-service"
  ```
- 應用程式啟動後，資料將自動流入本機的 `~/.maple/data` 目錄中，並透過相同的查詢引擎進行分析。

**CLI 查詢與互動**
該工具不僅是伺服器，同時也是強大的 CLI 查詢介面，方便 Agent 直接呼叫以進行除錯或分析。

- 常用查詢指令範例：
  - 查看服務狀態：`maple services`
  - 查詢特定服務的追蹤紀錄：`maple traces --service api --since 1h`
  - 檢視錯誤分組：`maple errors --since 24h`
  - 執行自訂 SQL 查詢：`maple query "SELECT count() FROM traces"`
- 格式化輸出：可透過 `--format table` 取得易讀的表格，或使用 `--debug` 查看編譯後的 SQL 語句。

**技術架構與設計**
Maple Local 的核心優勢在於其整合度。它透過 `bun:ffi` 直接呼叫 `libchdb`，實現了與嵌入式 ClickHouse 的高效互動，避免了子程序開銷或多語言環境的複雜性。此外，該工具支援本機與遠端工作空間的無縫切換，透過 `maple use local` 或 `maple use remote` 即可切換目標環境，並可透過 `maple whoami` 確認當前連線狀態。更多設計細節可參考 [Maple Local 設計文件](https://maple.dev/docs/local-mode/)。

## 標籤

新產品, 開源專案, Deployment, 自動化, Maple Local, OpenTelemetry, ClickHouse