> 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/onprem-deployment-types.md).

# 部署型態與功能對照

私有雲與地端部署的三種部署型態（Docker 單機、Docker 分散式、Kubernetes）怎麼選，以及 SaaS、私有雲、地端的功能可用性對照

MaiAgent 的私有雲與地端部署用同一套部署包安裝：在客戶的主機上執行部署包的安裝程式，依部署設定把平台服務裝成 Docker 容器或 Kubernetes 工作負載。本頁寫給評估或規劃部署的客戶 IT 與 SI 夥伴：三種部署型態怎麼選、私有雲和地端差在哪裡，以及哪些功能在私有雲或地端不提供。

{% hint style="info" %}
本頁是規劃用的摘要。完整的安裝步驟（主機盤點、備料、安裝、驗證）寫在隨部署包提供的安裝手冊，請洽 MaiAgent 窗口取得。主機規格見[系統需求](/tech/platform-development/system-requirements.md)。
{% endhint %}

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

|                           | Docker 單機        | Docker 分散式                     | Kubernetes                      |
| ------------------------- | ---------------- | ------------------------------ | ------------------------------- |
| 架構                        | 所有服務裝在同一台主機      | 服務分散到多台主機，由一台部署主機透過 SSH 安裝其他主機 | 由安裝程式建立叢集，或安裝到客戶既有的叢集           |
| 適合                        | PoC、400 人以下的正式環境 | 單台主機放不下，或要把資料層與背景工作分開          | 需要多節點高可用，或客戶已有 Kubernetes 維運能力  |
| 使用者連線方式                   | IP 加埠號，或每個服務一個網域 | 同左                             | 只支援網域（每個服務一個網域），需要 DNS          |
| 部署包                       | 一般部署包            | 一般部署包                          | MaiAgent 依客戶的部署設定產生的專用部署包       |
| 內建備份腳本                    | 可用               | 可用，備份集中存到部署主機                  | 叢集由安裝程式建立時可用；客戶既有的叢集請用叢集本身的備份機制 |
| Code Interpreter（程式碼執行沙箱） | 支援               | 支援                             | 不支援                             |

### Docker 單機 <a href="#docker-single-host" id="docker-single-host"></a>

* 安裝手冊的主線情境。實測一台 16 vCPU／64 GB 的主機，安裝約 30 分鐘，其中資料庫遷移約 16 分鐘；8 vCPU／32 GB 的主機實測 34～52 分鐘，多出來的時間大多在資料庫遷移。
* 主機重新開機後服務會自動啟動。安裝可以重複執行，已建立的資料與改過的密碼都會保留。
* 依服務人數的建議規格見[系統需求：依服務人數的建議規格](/tech/platform-development/system-requirements.md#sizing-by-users)。

### Docker 分散式 <a href="#docker-distributed" id="docker-distributed"></a>

安裝程式只在部署主機執行，其他主機由它透過 SSH 安裝。可將服務拆到 3 台主機，各台執行主機都須符合[系統需求的最低預留資源](/tech/platform-development/system-requirements.md#host-thresholds)：

| 主機       | 放什麼                                     |
| -------- | --------------------------------------- |
| 部署主機（應用） | 反向代理、後端 API、後台與對話頁；訊息佇列 RabbitMQ 預設也在這台 |
| 資料主機     | PostgreSQL、Redis、Elasticsearch、物件儲存     |
| 背景工作主機   | 背景工作（一般、低優先）、排程器與背景工作監控                 |

* 每台主機要用同一個有 sudo 權限的一般帳號，部署主機要能用金鑰 SSH 到其他每一台。
* 離線安裝時，物料要放到每一台跑 Docker 的主機。
* 實測 3 台離線安裝約 33～44 分鐘。

### Kubernetes <a href="#kubernetes" id="kubernetes"></a>

* **要用環境專用的部署包**：先產生部署設定交給 MaiAgent，由 MaiAgent 產生這個環境專用的部署包再安裝。之後要改規模（容量、記憶體、副本數），也要請 MaiAgent 重新產生部署包。
* **叢集**：可以由安裝程式建立（一併安裝 kubeadm、Cilium 網路與 Longhorn 儲存），也可以用 Helm 安裝到客戶既有的叢集。控制節點要高可用時建議 3 台；多節點時會在叢集內安裝映像倉庫。
* **Kubernetes 版本**：預設 1.31；新建的叢集可以選 1.36。把既有叢集從 1.31 升到 1.36 目前不支援。
* **規模**：依環境大小選 test、small、mid、large 四種規模設定，容量見[系統需求：Kubernetes 規模設定](/tech/platform-development/system-requirements.md#kubernetes-sizing)。
* 實測單節點（16 vCPU／64 GB、200 GB 磁碟、small）含叢集本身的安裝約 35～37 分鐘。
* 退回舊版需要 MaiAgent 協助，見[版本與升級](/tech/platform-development/onprem-versioning-and-upgrades.md#rollback)。

## 怎麼選 <a href="#how-to-choose" id="how-to-choose"></a>

1. **服務 400 人以下、可以接受單台主機故障時整個系統停止**：選 Docker 單機，維運最單純。
2. **超過 400 人**：改用 Docker 分散式或 Kubernetes，規格請洽 MaiAgent 評估。
3. **需要節點層級的高可用**：選 Kubernetes 多節點。
4. **要讓 Agent 執行程式碼（Code Interpreter）**：目前只有 Docker 部署支援。

{% hint style="warning" %}
部署型態在第一次安裝時決定。日後要從 Docker 換成 Kubernetes，需要搬移資料，請先洽 MaiAgent 評估。
{% endhint %}

部署費用與時程依使用人數、部署型態、GPU 與模型、整合與客製範圍而定，沒有固定的標準價或標準工期；請洽 MaiAgent 窗口，提供上述資訊後評估報價。

## 私有雲與地端的差別 <a href="#private-cloud-vs-onprem" id="private-cloud-vs-onprem"></a>

私有雲與地端用同一套部署包安裝，差別在部署設定裡的「部署類別」（私有雲或地端），它決定能不能使用需要連到雲端服務的功能：

* **地端**（預設）：視為連不到雲端服務的環境。語音 Agent、通話中心、雲端語音辨識、雲端連接器一律關閉。
* **私有雲**：主機可以連到雲端服務，上述功能可依需要開啟。

主機放在公有雲上，不代表要設成私有雲；以部署前與 MaiAgent 一起確認的《部署設定確認表》為準。

{% hint style="danger" %}
私有雲或地端要在**第一次安裝前**定案。裝成地端之後才改成私有雲，上述功能不會自動打開；升級時若部署設定與主機目前的部署類別不一致，升級會在變更任何東西之前停下。
{% endhint %}

## 功能可用性對照 <a href="#feature-availability" id="feature-availability"></a>

以 2026.Q3 季度版為準。SaaS 欄的功能依方案與組織設定開通；私有雲與地端欄的「可選」表示依《部署設定確認表》決定開或關。

| 功能                              | SaaS | 私有雲                         | 地端                    |
| ------------------------------- | ---- | --------------------------- | --------------------- |
| 語音 Agent                        | ✓    | 可選，需部署即時語音元件                | 不提供                   |
| 通話中心                            | ✓    | 可選，新建的組織預設開啟                | 不提供                   |
| 雲端語音辨識                          | ✓    | 可選                          | 不提供，改用離線語音辨識          |
| 離線語音辨識（部署在主機內，需要 GPU）           | —    | 選配                          | 選配                    |
| 雲端連接器（Google Drive 等雲端服務）       | ✓    | 可選                          | 不提供                   |
| AI Gateway                      | ✓    | 可選，新建的組織預設開啟                | 可選，新建的組織預設開啟；只能用自建的模型 |
| 自帶向量資料庫                         | ✓    | 新建的組織預設開啟                   | 新建的組織預設開啟             |
| 官方內建 Agent（官方市集）                | ✓    | 預設開啟，可在確認表關閉                | 預設開啟，可在確認表關閉          |
| 網路搜尋、地圖、圖片與影片生成                 | ✓    | 可選，主機要能連到對應的雲端服務並設定金鑰       | 可選，主機要能連到對應的雲端服務並設定金鑰 |
| 爬蟲（網頁抓取匯入知識庫）                   | ✓    | 可選，由雲端爬取服務執行，主機要能連到該服務並設定金鑰 | 同左；完全離線的環境無法使用        |
| Code Interpreter                | ✓    | 可選，限 Docker 部署              | 可選，限 Docker 部署        |
| Messenger、Instagram、WhatsApp 通道 | ✓    | 預設不開放，見下方說明                 | 預設不開放，離線環境無法使用        |
| Office 線上編輯（檔案庫）                | ✓    | 尚未納入季度版                     | 尚未納入季度版               |

* **Messenger、Instagram、WhatsApp**：需要客戶自備 Meta App，而且 MaiAgent 的 API 要能從網際網路被 Meta 呼叫到。要啟用時，把 Meta App 的設定交給 MaiAgent 重新產生後台映像；只改部署設定不會生效。
* **AI Gateway** 自 2026.Q3 起提供，用法見 [AI Gateway：OpenAI 相容 API 串接](/tech/ai-gateway/ai-gateway-openai-compatible.md)。
* **自帶向量資料庫**的規格見[自帶向量資料庫](/tech/platform-development/bring-your-own-vector-db.md)。
* SaaS 上的新功能會先上線，地端在之後的季度版納入，見[版本與升級：地端功能時程](/tech/platform-development/onprem-versioning-and-upgrades.md#feature-timing)。

## 相關頁面 <a href="#related-pages" id="related-pages"></a>

* [系統需求](/tech/platform-development/system-requirements.md)
* [版本與升級](/tech/platform-development/onprem-versioning-and-upgrades.md)
* [地端模型服務接入](/tech/platform-development/onprem-model-services.md)
* [維運重點：離線安裝、備份、TLS、監控與驗收](/tech/platform-development/onprem-operations.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/onprem-deployment-types.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.