> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/platform-development/architecture.md).

# 部署架構

MaiAgent 部署架構：一體式與分散式部署的差異、服務元件與資料流，以及部署包的 Docker 單機／Docker 分散式／Kubernetes 三種部署型態。

MaiAgent 是一個可擴展的生成式 AI 平台，支援多樣化的應用場景。為了適應不同的業務需求與資源配置方式，平台提供了兩種主要的部署模式：**一體式部署** 與 **分散式部署**。

本章節將說明這兩種架構的差異、適用情境以及各自的優缺點，並提供實際的部署參考。私有雲與地端以部署包安裝時，一體式對應「Docker 單機」，分散式對應「Docker 分散式」或「Kubernetes」，見本頁最後的[部署包的三種部署型態](#deployment-types-in-practice)。

## 一體式部署

### 架構說明

在一體式部署模式下，MaiAgent 的所有核心組件（例如主服務、任務調度服務、資料儲存、資料庫、前端服務等）都安裝並運行在同一台伺服器。特徵是**集中化管理**，部署簡單，適合快速上線與測試環境。

MaiAgent 平台不需要 GPU 即可運行，能在一般 CPU 環境中順暢部署與執行。但若在具有 GPU 資源的機器上，平台亦能與模型部署於同一環境中，以充分利用硬體加速效能。以下提供兩種常見架構圖供參考。

### 架構圖

1. 部署於含 GPU 的伺服器：

MaiAgent 平台與模型服務共同安裝在同一台機器，平台以內部 API 的方式負責請求協調與流量控制，模型則利用 GPU 提供高效推理能力。平台與模型服務放置一起時，不需額外購買只運行平台的一般伺服器，降低整體硬體支出。

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-c44f0012dfa26a57f94b3502599ef95e0449b82b%2F%E6%88%AA%E5%9C%96%202025-09-07%20%E4%B8%8A%E5%8D%8810.45.02.png?alt=media" alt=""><figcaption></figcaption></figure>

2. 部署於不含 GPU 的伺服器：

MaiAgent 部署於不含 GPU 的伺服器時，因為仍需要模型服務，因此需透過 API 的方式與 GPU 伺服器或是雲端 API 推論服務串接。平台與模型服務與分離時，可獨立擴展，依需求彈性增加或減少算力，讓架構更具彈性與可維護性。

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-ae088ec75c4ed0ad2b74d027af6f5afdae86dff2%2F%E6%88%AA%E5%9C%96%202025-09-07%20%E4%B8%8A%E5%8D%8811.35.32.png?alt=media" alt=""><figcaption></figcaption></figure>

## 分散式部署

### 架構說明

在分散式部署模式下，MaiAgent 的各個核心模組被拆分成獨立服務，並分布在多台伺服器。不同模組可根據需求進行水平擴展，實現高可用性與大規模處理能力。

* **雲平台（Cloud PaaS）環境**\
  在公有雲或私有雲環境中，可直接利用平台即服務（PaaS）的能力，如 Kubernetes（含客戶既有的叢集）、AWS ECS、GCP Cloud Run、Azure Container Apps 等。這些服務提供容器編排、負載平衡、自動擴縮（auto-scaling）與監控機制，能讓分散式模組快速部署並動態調整資源，減少基礎設施維運負擔。
* **地端（On-Premise VM）環境**\
  即使在地端 VM 的情境下，也能透過虛擬機或裸機伺服器架設容器平台或應用服務框架，實現與雲端類似的分散式管理與擴展能力。雖然需自行規劃叢集資源、監控與備援機制，但同樣可達到高可用性與彈性伸縮。

### 架構圖

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-b75d99c8b7d76847ec9ff2bd2c967640c156f6b3%2F%E6%88%AA%E5%9C%96%202025-09-07%20%E4%B8%8A%E5%8D%8811.28.15.png?alt=media" alt=""><figcaption></figcaption></figure>

## 部署模式比較表

<table><thead><tr><th width="133.58203125">特性</th><th>一體式部署</th><th>分散式部署</th></tr></thead><tbody><tr><td><strong>架構設計</strong></td><td>所有組件集中於單一伺服器/容器</td><td>各組件拆分為獨立服務，分布於多節點</td></tr><tr><td><strong>基礎設施成本</strong></td><td>低，單台伺服器即可</td><td>高，需要多台伺服器或雲端資源</td></tr><tr><td><strong>部署成本</strong></td><td>低</td><td>高，部署困難，需要 DevOps 團隊</td></tr><tr><td><strong>維護成本</strong></td><td>低，集中管理</td><td>高，需跨伺服器跨服務維護與監控</td></tr><tr><td><strong>可擴展性</strong></td><td>無，受限於單一機器資源</td><td>有，可針對瓶頸模組獨立擴容</td></tr><tr><td><strong>高可用性</strong></td><td>無，單點故障導致全系統中斷</td><td>有，單一服務故障不影響整體系統</td></tr><tr><td><strong>適用場景</strong></td><td>PoC、開發測試、小規模應用</td><td>正式上線、大規模、多部門</td></tr></tbody></table>

## 服務元件與資料流 <a href="#components-and-data-flow" id="components-and-data-flow"></a>

上方架構圖只畫出主要的服務類別。以部署包安裝時，實際會部署的元件與彼此的連線如下（以 Docker 部署為例）：

```mermaid
flowchart LR
    User["使用者瀏覽器"] --> Proxy["反向代理 Nginx"]
    Proxy --> Admin["後台前端"]
    Proxy --> WebChat["對話頁前端"]
    Proxy --> API["MaiAgent Server（Django API）"]
    Proxy --> Storage[("物件儲存 Garage 或 MinIO")]
    API --> Broker["訊息佇列 RabbitMQ"]
    Beat["排程器 Celery Beat"] --> Broker
    Broker --> Worker["Worker（一般、低優先）"]
    API --> PgBouncer["連線池 PgBouncer"]
    Worker --> PgBouncer
    PgBouncer --> PG[("PostgreSQL")]
    API --> Redis[("Redis 快取")]
    API --> ES[("Elasticsearch")]
    Worker --> ES
    API --> Storage
    Worker --> Storage
    API --> Models["模型服務 LLM、Embedding、Reranker"]
    Worker --> Models
```

* **訊息佇列（RabbitMQ）**：MaiAgent Server 與排程器把背景任務放進佇列，由 Worker 取出處理。一般 Worker 處理訊息串流輸出等工作，低優先 Worker 處理文件向量化等耗時工作。
* **排程器（Celery Beat）**：觸發週期性任務，固定只執行一個。
* **連線池（PgBouncer）**：MaiAgent Server 與 Worker 經由它連到 PostgreSQL。
* **反向代理**：對外的 HTTPS 入口。瀏覽器上傳與下載檔案時，會經由反向代理直接存取物件儲存（以 IP 加埠號連線時是 9000 埠）。Kubernetes 部署改由 Traefik 或 Cilium Gateway 擔任，各服務之間以叢集內部位址連線。
* **模型服務**：可以是主機上的 vLLM、客戶既有的 OpenAI 相容服務，或雲端模型，見[地端模型服務接入](https://docs.maiagent.ai/tech/platform-development/onprem-model-services.md)。
* **資料各放哪裡**：關聯資料（組織、Agent、對話、設定）在 PostgreSQL；知識庫與記憶功能的向量與段落在 Elasticsearch（知識庫可改用[自帶向量資料庫](https://docs.maiagent.ai/tech/platform-development/bring-your-own-vector-db.md)）；上傳的檔案在物件儲存；Redis 只做 API 快取與暫存。MaiAgent Server 與 Worker 直接以各供應商的 SDK 呼叫模型服務，架構中沒有獨立的模型閘道服務；企業要集中管理模型呼叫時用平台的 [AI Gateway](https://docs.maiagent.ai/tech/ai-gateway/ai-gateway-openai-compatible.md) 功能。

各元件在 AWS、GCP 與部署包中的對應見[概覽](https://docs.maiagent.ai/tech/platform-development/gai-lan.md)。

## 分散式部署的高可用與流量路徑 <a href="#ha-and-traffic-paths" id="ha-and-traffic-paths"></a>

部署包的三種部署型態，各自能做到的高可用程度不同：

|        | Docker 單機                                                              | Docker 分散式                 | Kubernetes                                                                                     |
| ------ | ---------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------- |
| 入口     | Nginx 反向代理（在主機上）                                                       | Nginx（在部署主機上）              | Traefik 或 Cilium Gateway；多節點時前面再接負載平衡器                                                         |
| 應用層副本  | API 容器數可以加到多個（Nginx 自動對多個 API 容器做負載分配）；一般 Worker 預設 2 個、低優先 Worker 1 個 | 同左，但各類服務各在一台主機             | API 預設 2 個副本、一般 Worker 2 個、低優先 Worker 1 個；排程器固定 1 個                                            |
| 資料層    | 單一實例                                                                   | 單一實例，集中在資料主機               | PostgreSQL、Redis、Elasticsearch、物件儲存各一個實例；資料放在 Longhorn 複寫儲存（多節點時預設 3 份），節點故障時由叢集把資料服務重新排程到其他節點 |
| 控制平面   | —                                                                      | —                          | 控制節點 3 台時以 VIP 做高可用（kube-vip、keepalived，或客戶既有的外部負載平衡器）                                         |
| 單一節點故障 | 整個系統停止                                                                 | 該主機上的服務停止（例如資料主機故障則全系統不可用） | 應用層自動補副本；資料層重新排程期間短暫中斷                                                                         |

**Kubernetes 的對外入口**依部署設定的網路環境決定，四種選一：

| 網路環境          | 流量路徑                                            | 客戶要準備的                        |
| ------------- | ----------------------------------------------- | ----------------------------- |
| 雲端負載平衡器       | DNS → 雲端 ALB／NLB（或客戶自家的 Nginx 反向代理）→ 節點 → 入口控制器 | 負載平衡器與其健康檢查、DNS               |
| Cloudflare 代理 | DNS → Cloudflare → 節點 80／443 → 入口控制器            | Cloudflare 設定、DNS             |
| 地端負載平衡        | DNS → Cilium 以 L2 或 BGP 宣告的服務 IP → 入口控制器        | 一段保留給平台的 IP 範圍（避免與既有位址衝突）、DNS |
| 單機直連          | DNS → 節點 80／443 → 入口控制器                         | DNS                           |

**規劃時的注意事項**

* 平台的 API 同時提供串流回覆（SSE）與 WebSocket 連線；負載平衡器與反向代理要允許長連線與 WebSocket 升級，閒置逾時不要設得太短，否則串流回覆會在中途被切斷。
* Kubernetes 只支援「每個服務一個網域」，網域要在客戶的 DNS（離線環境是內部 DNS）設好；憑證見[維運重點：網域與 TLS 憑證](https://docs.maiagent.ai/tech/platform-development/onprem-operations.md#tls-and-domain)。
* 需要的 VIP、服務 IP 範圍、DNS 名稱、防火牆規則與網段，由客戶網路團隊決定後填入《部署設定確認表》；連線埠見[系統需求：連線埠](https://docs.maiagent.ai/tech/platform-development/system-requirements.md#ports)。
* 跨機房或跨可用區的主動—主動部署、資料庫的多副本與自動容錯移轉，不在部署包的範圍內；有這類需求請洽 MaiAgent 評估。
* 平台不替模型服務做高可用；主機上的 vLLM 停止時，使用該模型的對話會失敗，直到服務恢復。

## 部署包的三種部署型態 <a href="#deployment-types-in-practice" id="deployment-types-in-practice"></a>

私有雲與地端用部署包安裝時，上述兩種部署模式的實際做法如下：

| 部署模式 | 部署包的部署型態   | 做法摘要                                                                           |
| ---- | ---------- | ------------------------------------------------------------------------------ |
| 一體式  | Docker 單機  | 所有服務裝在同一台主機；400 人以下的正式環境可用                                                     |
| 分散式  | Docker 分散式 | 由一台部署主機透過 SSH 把服務裝到多台主機，實測拓樸為應用、資料、背景工作三台                                      |
| 分散式  | Kubernetes | 由安裝程式建立叢集（kubeadm、Cilium、Longhorn），或用 Helm 裝到客戶既有的叢集；需要 MaiAgent 依部署設定產生的專用部署包 |

型態怎麼選、各型態的限制與功能差異見[部署型態與功能對照](https://docs.maiagent.ai/tech/platform-development/onprem-deployment-types.md)，主機規格見[系統需求](https://docs.maiagent.ai/tech/platform-development/system-requirements.md)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/platform-development/architecture.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
