Mindroom

Overview

Mindroom 是一個以容器方式部署、可自行託管的人工智能中介服務，來自 mindroom-ai/mindroom 這個開放專案。它在 benhoweb.com 的架構中負責連接 Matrix 通訊協定、LiteLLM 模型閘道，以及對外提供 OpenAI-compatible API 的角色。

Mindroom 本身並不包含大型語言模型，它更像是「AI 控制面板 + 聊天機械人 + API 代理人」：利用 Matrix 做聊天介面，讓使用者可以在 Matrix 房間內與 AI agent 互動；同時接收 /v1/* 的 OpenAI-style 請求，再轉發到 LiteLLM 去呼叫不同 LLM/embedder 供應商。

此部署運行於 Oracle Cloud，並採用 Docker Compose 管理。由於整個服務放在私有 Docker network 內，對外沒有直接暴露主機連接埠，因此需要配合 Cloudflare Tunnel 或其他反向代理使用。

Architecture

Mindroom 的實際執行環境有幾個重要組成部分：

• cf_network：一個預先建立的自訂 Docker bridge network。Mindroom 被指定使用靜態 IP 172.21.0.87，令同一個網絡內的其他容器（例如 LiteLLM、cloudflared、Matrix homeserver）可以用穩定位址訪問它。
• Matrix homeserver（Tuwunel）：Mindroom 需要連接 Matrix homeserver 才能註冊機械人帳號及收發聊天消息。此處的 Matrix homeserver 由內部容器 Tuwunel 提供，流量直接經過 cf_network 傳送，不經 Cloudflare Tunnel。
• LiteLLM：所有 LLM 和 embedder 請求都經 LiteLLM 統一轉發。因此 Mindroom 的 OPENAI_API_KEY 欄位實際填入的是 LiteLLM 的 API key，而非真正 OpenAI key。
• 持久化資料：Mindroom 會保存設定、憑證、機械人註冊狀態等資料，必須透過 volume 持久化，避免容器重建後失去所有狀態。

Mindroom 的設計原則是「對內以 Matrix 為中心，對外以 API 為中心」：Matrix 使用者通過聊天室觸發 AI agent；外部程式則可以調用 Mindroom 的 OpenAI-compatible API。

Deployment

Mindroom 需要一部可運行 Docker 和 Docker Compose 的 Linux 主機，Oracle Cloud 只是一個可行的託管環境。

構建配置時，需要確保 cf_network 已經存在，而且 172.21.0.87 未被其他容器佔用。之後在 .env 定義所有變數，再以 Docker Compose 啟動。一個典型的服務定義如下：

services:
  mindroom:
    image: ghcr.io/mindroom-ai/mindroom:latest
    container_name: mindroom
    restart: unless-stopped
    mem_limit: 2g
    networks:
      cf_network:
        ipv4_address: 172.21.0.87
    environment:
      - TZ=Asia/Hong_Kong
      - MATRIX_HOMESERVER=${MATRIX_HOMESERVER}
      - MATRIX_SERVER_NAME=${MATRIX_SERVER_NAME}
      - MATRIX_REGISTRATION_TOKEN=${MATRIX_REGISTRATION_TOKEN}
      - OPENAI_API_KEY=${LITELLM_KEY_MINDROOM}
      - OPENAI_BASE_URL=http://litellm:4000/v1
      - MINDROOM_API_KEY=${MINDROOM_API_KEY}
      - MINDROOM_CREDENTIALS_ENCRYPTION_KEY=${MINDROOM_CREDENTIALS_ENCRYPTION_KEY}
      - OPENAI_COMPAT_API_KEYS=${OPENAI_COMPAT_API_KEYS}
      - LOG_LEVEL=INFO
    volumes:
      - ./config:/data

這個配置檔刻意不寫 ports:，目的是避免 Mindroom 在主機上直接開連接埠；外部請求應由 Cloudflare Tunnel 或其他 proxy 帶入 cf_network。

實際部署步驟可簡化為：

1. 建立 cf_network；
2. 準備 .env；
3. 執行 docker compose --env-file .env up -d；
4. 檢查容器日誌及 Matrix 帳號註冊情況。

Configuration

Mindroom 依賴多個環境變數。同一個 .env 檔內的值，既要被 Mindroom 使用，也可能被 LiteLLM 或 Cloudflare Tunnel 使用。

變數	用途
TZ	設定時區，此部署使用 Asia/Hong_Kong。
MATRIX_HOMESERVER	Matrix homeserver 的內部 URL，指向 Tuwunel；不建議填寫公開域名。
MATRIX_SERVER_NAME	Matrix 的公開伺服器名稱，用作帳號/房間的 server_name 部分。
MATRIX_REGISTRATION_TOKEN	用於 Mindroom 自動註冊 mindroom_user 及 agent Matrix 帳號。
OPENAI_API_KEY	此值不是真正的 OpenAI key，而是 ${LITELLM_KEY_MINDROOM}，用於向 LiteLLM 驗證。
OPENAI_BASE_URL	指向 http://litellm:4000/v1，令 Mindroom 知道所有模型請求都應該送去 LiteLLM。
MINDROOM_API_KEY	Dashboard 及管理 API 的身份驗證 key。
MINDROOM_CREDENTIALS_ENCRYPTION_KEY	用作靜態加密已儲存的 credential；此值必須固定，一旦更改將無法解密舊資料。
OPENAI_COMPAT_API_KEYS	外部 client 以 Bearer token 打 Mindroom /v1 時使用的 key；未設定時會返回 401 locked。
LOG_LEVEL	日誌等級，此部署使用 INFO。

如果 LiteLLM 需要轉發 OpenAI 或其他 provider，相關 key 應存放在 LiteLLM 層，而不是 Mindroom 環境內。這樣可以避免 .env 之內累積太多相同名稱的 API key。

Operations

日常操作主要圍繞 Docker Compose 與容器日誌：

• 查狀態：docker compose ps mindroom
• 睇日誌：docker logs -f mindroom
• 重啟服務：docker compose restart mindroom
• 更新映像：docker compose pull mindroom && docker compose up -d mindroom

因為配置有 restart: unless-stopped，主機重新開機後 Mindroom 通常會自動恢復。mem_limit: 2g 則限制容器最多使用 2GB 記憶體，避免某一次異常請求拖垮 Oracle Cloud 主機。

備份時要特別注意以下幾項：

• .env 內的所有 key；
• MINDROOM_CREDENTIALS_ENCRYPTION_KEY；
• volume 內由 Mindroom 產生的設定資料庫或狀態檔；
• Matrix homeserver 的使用者註冊記錄。

FAQ

點解 Mindroom 的 OPENAI_API_KEY 唔直接填 OpenAI key？

因為在此架構中，Mindroom 唔應該直接與 api.openai.com 溝通。所有模型供應商都應由 LiteLLM 統一處理。填 LITELLM_KEY_MINDROOM 可以令請求帶住 LiteLLM 的鑰匙，而唔會撞到其他服務本來使用緊嘅 OPENAI_API_KEY。

點解一定要設定 OPENAI_BASE_URL？

實測發現，openai Python SDK/provider 不會完全依照 models[].host 轉換 endpoint。如果唔填 OPENAI_BASE_URL，Mindroom 會用預設值 https://api.openai.com/v1，最終會因為 key 唔對而回傳 401。因此要明確寫成 http://litellm:4000/v1。

OPENAI_COMPAT_API_KEYS 唔設得唔得？

如果唔設，Mindroom 的 /v1 兼容 API 會鎖住，外部 client 請求會被回應 401 locked。淨係使用 Dashboard 或 Matrix agent 嘅話未必受影響，但想公開 API 就必須設定。

Mindroom 可唔可以同 Matrix homeserver 分開行唔同網絡？

可以，但需要確保網絡延遲和安全性都可接受。此處之所以將兩者放入 cf_network，係想 Matrix homeserver 與 Mindroom 之間直接用內部位址溝通，唔使經 Cloudflare Tunnel 出街再入返嚟。

Related Links

• docker
• docker-compose
• litellm
• Matrix
• oracle-cloud
• cloudflare-tunnel

Source

Coverage auto (container scan)