Deployment

Minara Agent is designed to deploy as a single container with one mounted volume for state. This page explains the Docker image, the common deployment shapes, and the knobs you'll want to tune in production.

The Dockerfile

Dockerfile is a multi-stage build:

Stage 1: builder. node:24-slim plus python3 / make / g++ for compiling better-sqlite3's native addon. Installs deps, type-checks, and emits dist/ via tsc.
Stage 2: runtime. node:24-slim with just the built dist/, package.json, and node_modules/ copied from the builder. Drops to the non-root node user and exposes port 8080.

最終鏡像不包含 TypeScript 源碼、測試套件或構建工具鏈。大小約為 300 MB（未壓縮），取決於 pnpm 鎖定文件。

數據目錄

MINARA_DATA_DIR=/data

所有可變狀態都存放在此目錄下：

/data
├── minara.db          ← SQLite (WAL)
├── minara.db-wal
├── minara.db-shm
├── logs/              ← 按天轮转的 NDJSON
├── sandbox/files/     ← 沙盒用户文件
├── workspace/         ← SOUL.md / AGENTS.md / 等
├── env                ← 保存的 `minara config set model.defaultModel` / `minara auth messaging add`
└── auth/              ← 加密的身份验证配置文件

將 /data 掛載為卷。容器中的其他所有內容都是不可變的。沒有卷的 docker run --rm 仍可用於臨時實驗，但退出時會丟失狀態。

常見部署形式

1. 容器中的交互式 REPL

docker run --rm -it \
  -v minara-data:/data \
  -e ANTHROPIC_API_KEY=sk-... \
  -e MINARA_API_KEY=... \
  minara

默認 CMD 運行 dist/gateway/cli.js，進入 REPL。用於對生產鏡像進行本地測試。

2. HTTP 網關服務

docker run -d --name minara \
  -v minara-data:/data \
  -p 127.0.0.1:8080:8080 \
  -e ANTHROPIC_API_KEY=sk-... \
  -e MINARA_API_KEY=... \
  minara \
  node dist/gateway/server.js

用 node dist/gateway/server.js 覆蓋 CMD 以運行 HTTP 網關而非 REPL。 Dockerfile 中的健康檢查已探測端口 8080 的 /healthz， Docker/Kubernetes 可直接使用。

將網關暴露到 localhost 之外

網關驅動涉及資金的端點，因此綁定到非本地迴環地址時必須進行身份驗證。將端口發佈到網絡接口之前，請先設置 token：

export GATEWAY_AUTH_TOKEN=$(openssl rand -hex 32)

此後每個請求都必須攜帶 Authorization: Bearer $GATEWAY_AUTH_TOKEN。面向互聯網的服務請在前面部署帶 TLS 的反向代理。若在非迴環綁定下未設置 token，網關將拒絕啟動（交互模式）或自動生成 token（Docker/CI 模式，寫入 <dataDir>/gateway-token）。

3. 在同一數據目錄上運行 CLI 和網關

將網關作為長期運行的服務，同時針對相同數據目錄打開一次性 REPL 進行交互式調試：

docker run --rm -it \
  -v minara-data:/data \
  -e ANTHROPIC_API_KEY=sk-... \
  minara \
  node dist/gateway/cli.js

兩個進程讀寫同一 SQLite 文件。WAL 模式意味著併發讀不會相互阻塞，但兩個進程同時寫入仍是壞主意。附加到運行中的網關時，將 REPL 視為主要用於讀取的調試器。

4. 僅 Autopilot 部署

docker run -d \
  -v minara-data:/data \
  -e ANTHROPIC_API_KEY=sk-... \
  -e MINARA_API_KEY=... \
  -e MINARA_AUTOPILOT_ENABLED=true \
  -e MINARA_DAILY_CAP_USD=500 \
  -e MINARA_AUTOPILOT_CAP_USD=50 \
  minara \
  node dist/gateway/server.js

啟用 Autopilot 時，HTTP 網關在啟動時引導 Autopilot 運行時。這些限額強制實施硬上限，LLM 無法突破。

環境變量

最低要求：

ANTHROPIC_API_KEY（或 OPENROUTER_API_KEY 等）用於 LLM 提供商。
MINARA_API_KEY 用於 Minara 交易後端，除非使用交互式設備登錄流程。

生產環境中強烈推薦：

MINARA_DAILY_CAP_USD：每日支出硬上限。
MINARA_PER_TX_MAX_USD：每筆交易硬上限。
MINARA_DATA_DIR=/data：顯式固定數據目錄（避免鏡像默認值變更時出現意外）。
LOG_LEVEL=info：debug 較安全但日誌量會增加約 4 倍。

詳見環境變量。

密鑰

不要將密鑰烘焙到鏡像中。Dockerfile 的所有內容都可以公開發布；所有憑證在運行時通過環境變量或綁定掛載的文件傳入。

對於 Kubernetes：使用掛載為環境變量的 Secret 資源。對於 Docker Compose：使用指向鏡像外 .env 文件的 env_file。對於普通 Docker：從主機環境使用 -e KEY=value。

tools/_shared/result.ts 中的掩碼器會在審計日誌中隱藏已知敏感密鑰。就算密鑰出現在工具參數中，也不會被持久化到磁盤。這是縱深防禦措施，請勿完全依賴。切勿將密鑰放入鏡像。

健康檢查

鏡像包含內置 HEALTHCHECK，探測端口 8080 上的 /healthz。在以下情況下端點返回 200：

SQLite 文件可以打開。
LLM 提供商已解析憑證。
工具註冊表至少註冊了一個工具。

如需更深入的檢查，改為查詢 /status。它返回數據庫統計、技能計數、活躍觸發器計數和上次成功 LLM 調用的時間戳。

升級

兩種選擇：

替換容器。 docker pull minara:latest，停止舊容器，用相同卷啟動新容器。apps/agent/src/platform/db.ts 中的模式遷移是冪等的，在啟動時運行，數據得以保留。
通過 CLI 自更新。 在容器內運行 minara update 檢測安裝路徑並調用適當的升級流程。用於長期運行的個人部署；對於由編排器管理生命週期的生產環境不太適用。

跨主版本升級前始終備份：

docker exec minara \
  sqlite3 /data/minara.db ".backup '/data/backups/minara-pre-upgrade.db'"

水平擴展

Minara 設計用於單節點操作。SQLite 是瓶頸：同一時刻只有一個寫入者。對於水平擴展的 HTTP 網關，有兩種選擇：

一個節點擁有狀態，其他節點代理。 運行單個"狀態"容器包含 SQLite 卷，副本將寫入操作轉發到它。讀可直接命中副本。
切換到 Postgres。 apps/agent/src/storage/ 下的存儲層足夠精細，遷移到 Postgres 是可行的，但尚無人實現。如需此功能，請提交 issue。

實際上大多數部署都是單節點的。package.json 中的 Redis 代碼路徑用於水平擴展時的可選分佈式鎖定，但不是啟動時必需項。

可觀測性

容器日誌是 stdout 上的 NDJSON。直接將其管道到日誌聚合器：

docker logs minara | vector --config vector.toml

對於 Prometheus 風格指標，抓取 /status 並解析 JSON 響應。目前沒有專用 /metrics 端點；如需 Prometheus 格式，請提交 issue 或貢獻一個。

詳見可觀測性。

資源規模

單用戶部署的典型資源使用量：

CPU：空閒 ≈ 1 核的 1%，忙碌（活躍輪次）≈ 1 核的 20%。真正的工作在 LLM 提供商端進行。
內存：150–300 MB 常駐。增長主要是 SQLite 頁緩存和內存日誌環形緩衝區。
磁盤：日常使用每月 20–100 MB。審計日誌是主要消耗者； MINARA_LOG_RETENTION_DAYS 限制它。
網絡：突發式。空閒接近零；活躍輪次可向 LLM 提供商傳送幾 MB。

這些是指南。如運行繁重的研究工作負載或包含多個標的的 Autopilot，預期各項增加 2–4 倍。

不要做的事

不要多個進程同時寫入同一 SQLite 文件並期望併發寫入安全。 SQLite 是單寫入者。使用上述單所有者加代理的形式。
不要跳過卷掛載。 沒有它每次重啟都會丟失審計日誌、記憶和身份驗證狀態。
不要在未設置 GATEWAY_AUTH_TOKEN 且沒有終止 TLS 的反向代理的情況下綁定到 0.0.0.0（或去掉 -p 中的 127.0.0.1: 前綴）。 網關暴露涉及資金的端點；否則安全綁定守衛將拒絕啟動或自動生成 token。
不要將密鑰放入鏡像。 絕對不要。就算只是"今天測試"也不行。
不要禁用權限等級鉤子鏈作為 Autopilot 測試的快捷方式。 如想要無操作支出上限，改用 MINARA_AUTOPILOT_CAP_USD=0.01。

本頁目錄