自託管快速上手
用 Docker Compose 啟動 Multica，完成登入，並連線第一臺執行電腦。
自託管 Multica 分成兩部分：
| 部分 | 執行什麼 | 放在哪裡 |
|---|---|---|
| Multica 服務 | Web、API 和 PostgreSQL | 一臺安裝了 Docker 的機器 |
| 執行電腦 | Multica 守護程序和 AI 程式設計工具 | 開發者實際工作的電腦 |
它們可以是同一臺機器，也可以分開。自託管替換的只是 Multica Cloud 部分。
這篇文件使用 Docker Compose。Kubernetes 部署見倉庫中的 Self-hosting guide。
開始前
執行 Multica 服務的機器需要：
- Docker Engine 或 Docker Desktop，並且
docker compose可以執行 - Git、Make、curl 和 OpenSSL
- 本機的
3000、8080埠未被佔用
先確認 Docker 和 Compose 可用：
docker info
docker compose versionMultica 使用 Compose v2，也就是 docker compose。舊版的 docker-compose v1 不受支援。
執行電腦還需要至少一款已經安裝並登入的 AI 程式設計工具，例如 Claude Code、Codex 或 Cursor。第 5 步再安裝 Multica CLI。
啟動 Multica
在準備執行服務的機器上執行：
git clone --depth 1 https://github.com/multica-ai/multica.git
cd multica
make selfhost之後再次執行 make selfhost 會繼續使用現有的 .env 和資料卷，不會重新生成金鑰。
make selfhost 拉取已釋出的映象，不會編譯當前 checkout 中的程式碼。需要測試本地原始碼時，使用 make selfhost-build。
已釋出的映象跟隨最新的 release tag，而直接 git clone 檢出的是 main，通常領先於發版。如果你要在這個 checkout 上構建任何東西（CLI，或透過 make selfhost-build 構建映象），先切換到與映象對應的 release tag，讓構建產物和執行中的容器保持同一版本：
git fetch --tags --depth 1
git checkout $(git tag -l 'v*' --sort=-v:refname | head -1)確認服務已經就緒
檢視容器狀態：
docker compose -f docker-compose.selfhost.yml pspostgres 顯示為 healthy，backend 和 frontend 應處於執行狀態。然後檢查 backend、資料庫和 migration：
curl -fsS http://localhost:8080/readyz正常響應是：
{"status":"ok","checks":{"db":"ok","migrations":"ok"}}Backend 容器每次啟動時都會先執行資料庫 migration，再啟動服務，不需要手動執行 migration 命令。
選擇訪問方式
直接開啟 http://localhost:3000。後面執行 multica setup self-host 時也不需要傳 URL。
登入並建立工作區
開啟本機的 http://localhost:3000，或剛才配置的 https://app.example.com，輸入信箱獲取驗證碼。
預設沒有配置郵件服務。請求驗證碼後，可以從 backend 日誌中讀取：
docker compose -f docker-compose.selfhost.yml logs backend \
| grep "Verification code"日誌中會出現類似內容：
[DEV] Verification code for you@example.com: 123456輸入驗證碼並建立第一個工作區。配置 Resend 或 SMTP 後，驗證碼透過郵件傳送，成員無需讀取容器日誌，具體見登入與註冊配置。
自託管部署預設使用 APP_ENV=production，不會啟用固定驗證碼。不要在公網例項上設定 MULTICA_DEV_VERIFICATION_CODE。
連線執行電腦
下面的命令在執行 AI 程式設計工具的電腦上執行，不一定是執行 Docker 的伺服器。
每次執行都擁有守護程序所屬使用者的全部權限，該使用者能讀寫的一切，執行都能讀寫。請用專用 Unix 使用者、容器或虛擬機器來執行守護程序，而不是你的個人帳號。詳見安全模型。
先安裝 Multica CLI：
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash然後讓 CLI 連線你的服務。按 Multica 服務所在的位置選擇：
multica setup self-host服務在另一臺機器上時，傳入的是剛才配置的兩個地址。這條命令會先檢查 <server-url>/health，再開啟瀏覽器完成登入。登入完成後，它會儲存本機憑據並啟動守護程序。這一步報 Server not reachable，說明 /health 沒有透過探測拿到 200，可能的原因有三種：代理把所有流量轉給了不轉發該路徑的舊版 frontend；代理根本沒把 /health 路由到 backend；更底層的問題（DNS、TLS、防火牆、超時、backend 返回 5xx）。見故障排查。
確認連線狀態：
multica daemon status正常情況下，輸出中會顯示：
Daemon: runningAgents中包含本機已安裝的 AI 程式設計工具Workspaces大於0
常用管理命令
以下命令都在 multica 倉庫目錄中執行：
# 檢視狀態
docker compose -f docker-compose.selfhost.yml ps
# 檢視 backend 日誌
docker compose -f docker-compose.selfhost.yml logs -f backend
# 應用 .env 變化
docker compose -f docker-compose.selfhost.yml up -d
# 停止服務，保留資料卷
docker compose -f docker-compose.selfhost.yml downdocker compose down 會保留 pgdata 和 backend_uploads。加上 -v 會刪除這些資料卷，包括資料庫；除非確定要清空例項，否則不要執行 docker compose down -v。
升級
確認沒有釘死映象 tag
兩個映象都寫成 ${MULTICA_IMAGE_TAG:-latest}（docker-compose.selfhost.yml：services.backend.image、services.frontend.image），而 .env.example 裡預設是 MULTICA_IMAGE_TAG=latest。
grep MULTICA_IMAGE_TAG .env
# MULTICA_IMAGE_TAG=v0.4.5 ← 釘死了：先改成 latest（或你想要的版本）如果你在 .env 裡釘死了 MULTICA_IMAGE_TAG，下面的升級命令都升不上去。 pull 只是把同一個 tag 重拉一遍，版本原地不動，不報錯，也沒有任何警告。
備份 Postgres
migration 只往前走、不回滾，所以正式環境升級前先導一份：
docker compose -f docker-compose.selfhost.yml exec -T postgres \
pg_dump -U multica multica > multica-backup.sql && gzip multica-backup.sql如果你改過 POSTGRES_USER / POSTGRES_DB，把 multica 換成 .env 裡的實際值。資料存在名為 multica_pgdata 的 volume 裡，docker compose down 不會刪它，但 down -v 會。
不要把 pg_dump 直接管道接給 gzip。 shell 取的是管道里最後一條命令的退出碼，所以 pg_dump ... | gzip > backup.sql.gz 在匯出失敗時照樣返回 0，留下一個格式完全合法、但裡面什麼都沒有的 20 位元組壓縮包。先重定向到檔案，pg_dump 自己的退出碼才算數，&& 也只會壓縮真正成功的那份匯出。
拉取新映象並重建容器
在已有部署上，下面兩種寫法結果相同：Makefile 裡的 selfhost target 跑的就是同一套 docker compose pull + up -d，只是額外多做了兩件事，.env 缺失時生成一份，以及等 /health 就緒後列印一段狀態彙總。用哪個都行：
cd multica
git pull --ff-only
make selfhost和第 2 步一樣，backend 容器啟動時會在對外提供服務之前先跑 ./migrate up（docker/entrypoint.sh）。沒有單獨的升級命令，把新映象起起來，本身就是升級這一步。想看過程：
docker compose -f docker-compose.selfhost.yml logs -f backend需要回填歷史資料的 migration（如 103）也會自動完成回填。自動回填極少數情況下失敗，報 refusing to drop legacy daily rollups，處理見故障排查。
用 /readyz 驗證，不要用 /health
curl -s localhost:8080/readyz
# {"status":"ok","checks":{"db":"ok","migrations":"ok"}}只要不是 HTTP 200 且兩項都是 ok，就說明新版本沒把 migration 跑完，先去看 backend 日誌，別急著放流量進來。
/health 是 liveness 探針，只要程序還活著就返回 {"status":"ok"}，migration 失敗了它照樣是 ok。/readyz（server/cmd/server/router.go 中註冊的 readyHandler，/healthz 是它的別名）會檢查資料庫和已應用的 migration 集合，升級出問題能被它攔下來。
常見問題
| 現象 | 先檢查什麼 |
|---|---|
/readyz 沒有返回 ok | 執行 docker compose -f docker-compose.selfhost.yml logs backend postgres。 |
| 收不到驗證碼 | 請求一次驗證碼，再從 backend 日誌中查詢 Verification code。 |
setup self-host 提示 server 不可達 | 在執行電腦上請求 https://api.example.com/health，確認 DNS、TLS 和反向代理都可達。返回 404 說明代理把 /health 轉給了不轉發該路徑的舊版 frontend，改為直通 backend（見故障排查）。 |
守護程序沒有列出 Agents | 確認 AI 程式設計工具在 PATH 中並已登入，然後執行 multica daemon restart。 |
| 任務一直排隊 | 執行 multica daemon status，確認守護程序正在執行並連線了工作區。 |
更多情況見故障排查。
接下來
- 登入與註冊配置 — 配置郵件、Google 登入和註冊範圍。
- 環境變數 — 檢視完整的服務端配置。
- Self-hosting guide — Kubernetes、升級和手動部署。
- 桌面應用 — 讓 Desktop 連線自託管服務。