Docker Compose 部署

本頁說明如何用 Docker Compose 部署 Hagicode。它適合伺服器、NAS、團隊共用或需要環境隔離的情境；個人本機使用請優先考慮 Microsoft Store 或 Desktop。

為什麼選 Docker Compose

• 環境隔離，相依衝突更少
• 可一次啟動目前支援的 Hagicode 服務堆疊
• 設定、升級與維護路徑統一
• 主機只需要 Docker，無需另外安裝 Node.js 或 Git

關於預設資料儲存

目前支援的 Docker Compose 範本依預設本機 SQLite 資料路徑來組織持久化資料。大多數情況下，您不需要在主機上額外準備獨立的資料庫服務。

影片教學

若你想先看完整流程，可先看影片教學：

在 Bilibili 觀看影片教學

影片內容簡介：

• Docker Compose 部署的完整流程示範
• 設定檔產生和修改說明
• 服務啟動和驗證步驟
• 常見問題和解決方案

影片長度：約 15 分鐘

前置需求

在開始之前，請確保您的系統已安裝 Docker 和 Docker Compose。

安裝 Docker

Windows

下載並安裝 Docker Desktop for Windows。安裝完成後，確保 Docker Desktop 正在執行。

macOS

下載並安裝 Docker Desktop for Mac。安裝完成後，確保 Docker Desktop 正在執行。

Linux

請依 Docker 官方文件為您的發行版安裝 Docker Engine 與 Docker Compose 外掛程式：Install Docker Engine。不同發行版的軟體來源與套件名稱不同，請不要直接套用其他發行版的指令。

安裝完成後，啟動 Docker 服務並設定開機自動啟動：

sudo systemctl start docker
sudo systemctl enable docker

驗證安裝

安裝完成後，執行以下指令驗證 Docker 和 Docker Compose 是否正確安裝：

docker --version
docker compose version

快速開始

1. 產生 Docker Compose 設定檔

使用 Docker Compose Builder 產生 docker-compose.yml。它是獨立網站，產生規則與更新以該網站為準。

產生器支援：

• 選擇 API 供應商（智譜 AI、Anthropic 官方、自訂 API），並設定 API URL 與 Token
• 自訂連接埠、容器名稱、持久化目錄與工作目錄
• 選擇內建資料庫或外部資料庫
• 自動處理 Windows / Linux 的平台差異與常見檔案權限問題
• 使用受支援的 Docker Hub 映像檔

操作步驟：

1. 開啟 Docker Compose Builder。
2. 依據您的需求填寫設定：選擇 API 供應商，設定連接埠、資料庫、工作目錄等選項。
3. 點擊產生按鈕，取得 docker-compose.yml 設定。
4. 將產生的設定儲存為 docker-compose.yml 檔案。
5. 如果需要，建立 .env 檔案設定敏感資訊，避免把 Token 直接寫進 compose 檔案。

映像檔來源

產生器使用 Docker Hub 作為受支援的映像檔來源：

• 映像檔位址：newbe36524/hagicode:{tag}
• 適用情境：適合支援 Docker Hub 映像加速的使用者
• 注意事項：部分地區可能需要設定映像加速器

取得 API Token

Docker 部署透過產生器設定的 API 供應商存取模型，您需要先準備一個可用的 API Token：

智譜 AI：取得 API Token →

• 中國大陸存取穩定，回應更快
• 性價比高，適合日常使用

Anthropic 官方：取得 API Token →

• 直接使用 Anthropic 的服務

也可以在產生器中選擇自訂 API。

2. 啟動服務

在 docker-compose.yml 所在目錄執行以下指令：

docker compose up -d

此指令將：

• 下載並啟動產生的設定中所定義的 Hagicode 容器
• 建立並設定網路
• 初始化預設資料目錄與執行階段依賴項

3. 驗證服務狀態

檢查容器是否正在執行：

docker compose ps

您應該會看到產生的設定中所定義的服務處於 “running” 狀態。

查看服務日誌：

# 查看所有服務日誌
docker compose logs

# 查看 Hagicode 服務日誌
docker compose logs hagicode

# 即時追蹤日誌
docker compose logs -f hagicode

存取應用程式

服務啟動成功後，透過瀏覽器存取：

http://localhost:45000

如果您在產生器中修改了連接埠，請使用您設定的主機連接埠。首次開啟時會進入初始化嚮導，請繼續閱讀 初始化嚮導設定。

設定說明

如需修改設定（如變更連接埠、切換 API 供應商等），您可以：

1. 重新使用 Docker Compose Builder 產生新設定
2. 手動編輯 docker-compose.yml 和 .env 檔案
3. 重新建立容器使設定生效：

docker compose up -d

docker compose restart 只會重新啟動現有容器，不會套用對 docker-compose.yml 或 .env 的修改。修改設定後請使用 docker compose up -d。

資料持久化

目前支援的 Docker Compose 路徑預設使用 SQLite 資料檔案與持久化磁碟區。若您需要檢查資料掛載位置或備份策略，請直接查看產生後的 docker-compose.yml 中磁碟區與資料目錄對應設定。

日常維護

停止與啟動

# 停止服務（保留容器與資料）
docker compose stop

# 再次啟動
docker compose start

# 停止並移除容器（資料磁碟區仍然保留）
docker compose down

不要隨意給 docker compose down 加上 -v，它會同時刪除 compose 檔案中宣告的資料磁碟區。

升級版本

1. 在升級前先備份資料目錄（見下文）。
2. 將 docker-compose.yml 中的映像檔標籤 newbe36524/hagicode:{tag} 改為目標版本，或重新用產生器產生設定。
3. 拉取新映像檔並重新建立容器：

docker compose pull
docker compose up -d

備份資料

先執行 docker compose stop 讓服務停止寫入，再備份 docker-compose.yml 中磁碟區與資料目錄對應所指向的目錄或資料磁碟區，然後執行 docker compose start 恢復服務。

後續步驟

現在您已經成功部署了 Hagicode。接下來請：

1. 閱讀 初始化嚮導設定，建立預設 Hagicoder 與第一個專案。
2. 在 建立普通會話 中先用唯讀模式了解專案，再視需要繼續到 建立提案會話。

如果您更喜歡使用桌面應用程式，請參閱 Desktop 安裝指南。