> 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/system-requirements.md).

# 系統需求

私有雲與地端部署的主機需求：CPU、記憶體、磁碟、作業系統、對外與內部連線埠、依服務人數的建議規格，以及 GPU 節點的驅動與運算能力需求

本頁列出以部署包安裝 MaiAgent（私有雲或地端）時，主機要準備的規格與網路條件，寫給規劃硬體與網路的客戶 IT 與 SI 夥伴。部署型態的差異見[部署型態與功能對照](/tech/platform-development/onprem-deployment-types.md)。

{% hint style="info" %}
基本部署需為 MaiAgent 預留至少 **32 GB RAM（記憶體）與 60 GB 可用磁碟空間**。這是基本部署的預留資源下限，正式環境仍需依使用量評估；模型、文件、映像、備份與升級所需的額外空間另計。
{% endhint %}

## 主機門檻 <a href="#host-thresholds" id="host-thresholds"></a>

Docker 單機、分散式與既有站的應用／資料主機都須符合下列最低預留資源；不足時請先擴充。純反向代理主機與 Kubernetes 控制機另行評估，Kubernetes 工作節點依[規模設定](#kubernetes-sizing)、服務與副本數規劃。

| 項目                                        | 最低預留資源      | 建議（低於只適合測試、PoC） |
| ----------------------------------------- | ----------- | --------------- |
| CPU                                       | —           | 8 vCPU          |
| 記憶體（RAM）                                  | 32 GB       | 48 GB           |
| 可用磁碟（部署目錄所在的磁碟；Docker 資料目錄在另一顆磁碟時，那一顆也要看） | 60 GB（全新安裝） | 200 GB          |

* 記憶體以系統回報的數字判斷，會比標稱容量少一點（64 GB 的主機約顯示 61 GB），檢查已把這個差距算進去。
* 60 GB 指安裝前的可用磁碟空間，不是磁碟總容量。映像下載與載入會同時占用空間，請依本次部署內容額外預留，並在安裝前執行部署包的 `--check` 檢查。
* 升級時需要額外空間放新版部署包與映像，見[版本與升級：升級前要準備的空間](/tech/platform-development/onprem-versioning-and-upgrades.md#upgrade-disk-space)。

## 依服務人數的建議規格 <a href="#sizing-by-users" id="sizing-by-users"></a>

Docker 單機、所有服務在同一台主機時的建議規格，不含在本機執行模型所需的 GPU 資源：

| 服務人數     | 建議規格                                         |
| -------- | -------------------------------------------- |
| 200 人以下  | 12 vCPU／64 GB                                |
| 400 人以下  | 16 vCPU／64 GB                                |
| 超過 400 人 | 建議改用 Docker 分散式或 Kubernetes，規格請洽 MaiAgent 評估 |

這組數字來自 MaiAgent 的壓力測試，假設同時在線人數約為服務人數的 20%。實際負載（知識庫大小、檔案解析量、同時對話數）差異大時，請洽 MaiAgent 重新評估。

Docker 分散式可將應用、資料與背景工作拆到不同主機；各台執行主機均須預留至少 32 GB RAM 與 60 GB 可用磁碟空間。拓樸見[部署型態與功能對照：Docker 分散式](/tech/platform-development/onprem-deployment-types.md#docker-distributed)。

## Kubernetes 規模設定 <a href="#kubernetes-sizing" id="kubernetes-sizing"></a>

Kubernetes 部署依規模設定配置各服務的儲存容量：

| 規模    | 適用      | PostgreSQL | Redis | 物件儲存  | Elasticsearch（容量／heap） | 映像倉庫  |
| ----- | ------- | ---------- | ----- | ----- | ---------------------- | ----- |
| test  | 單節點 PoC | 5Gi        | 2Gi   | 5Gi   | 5Gi／2g                 | 30Gi  |
| small | 10 人以下  | 10Gi       | 2Gi   | 20Gi  | 10Gi／4g                | 50Gi  |
| mid   | 100 人以下 | 20Gi       | 5Gi   | 50Gi  | 30Gi／8g                | 50Gi  |
| large | 正式環境    | 100Gi      | 10Gi  | 200Gi | 100Gi／16g              | 100Gi |

* 映像倉庫只在多節點時安裝；單節點直接把映像匯入節點，不占這一欄的空間。
* Elasticsearch 的記憶體會保留 heap 大小、上限是 heap 的兩倍（mid：8Gi／16Gi），節點的可用記憶體要放得下。
* 單節點時所有容量都放在同一台主機的儲存路徑，儲存元件（Longhorn）會保留磁碟的 20% 不用。放不下時服務會停在 Pending、安裝中途失敗，請改選較小的規模或改用更大的磁碟。

## 作業系統與帳號 <a href="#operating-systems" id="operating-systems"></a>

| 項目     | 需求                                                |
| ------ | ------------------------------------------------- |
| 作業系統   | Ubuntu 22.04／24.04／26.04、RHEL 8／9、Rocky Linux 8／9 |
| CPU 架構 | amd64 或 arm64                                     |
| 帳號     | 一個有 sudo 權限的一般帳號；安裝程式不接受以 root 執行                 |
| Docker | 不需要預先安裝，由部署流程安裝                                   |

* **RHEL／Rocky Linux**：要先關閉 SELinux 並重新開機。RHEL／Rocky 8 離線安裝需要 8.10 以上。
* **Kubernetes 1.36 用在 RHEL／Rocky 8**：要 8.6 以上，並切換到 cgroup v2。
* 離線安裝時，部署包要包含目標主機作業系統的離線套件；主機盤點會列出需要的版本，缺少時請 MaiAgent 提供對應的部署包。

## 連線埠 <a href="#ports" id="ports"></a>

**主機上不能被其他服務占用的埠**：80、443、5432、6379、9000、9200；以 IP 加埠號連線時另加 8000、3333、3334。

**要對使用者開放的埠**（防火牆或安全群組）：

| 使用者連線方式  | 要開放的埠                                                     |
| -------- | --------------------------------------------------------- |
| IP 加埠號   | 8000（API）、3333（後台）、3334（對話頁）、9000（物件儲存；瀏覽器上傳與下載檔案會直接連這個埠） |
| 每個服務一個網域 | 80、443                                                    |

* Kubernetes 只支援「每個服務一個網域」。
* Docker 分散式：部署主機要能以 SSH 金鑰登入其他主機；主機之間還需要互通資料庫、快取、搜尋引擎、物件儲存與訊息佇列的連線，實際清單依拓樸而定，請洽 MaiAgent 提供。

**連線安裝時主機要能連到的地方**（離線安裝不需要）：MaiAgent 的映像與部署包下載站、Hugging Face（在本機執行模型時下載權重）、Docker Hub（本機模型服務的映像）、Docker 官方套件來源、PyPI，以及作業系統的套件來源。只開白名單、要經過 proxy，或只連得到其中一部分時，一律改用離線安裝，見[維運重點：離線安裝](/tech/platform-development/onprem-operations.md#air-gap-install)。

### 營運時主機要連出去的地方 <a href="#outbound-connections" id="outbound-connections"></a>

安裝完成後，平台只在使用對應功能時才需要主機連出去；連線一律由 MaiAgent 主機主動發起，防火牆只要放行主機到目的地的方向。全部不開放也能運作（只用主機上的模型、不接外部系統）。

| 功能                                                                     | 目的地                                                                                             | 常見埠號                        |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------- |
| 模型服務在另一台主機或雲端                                                          | 模型服務的網址，或雲端供應商的 API 端點                                                                          | 443，或模型服務自訂的埠               |
| 資料庫功能（Text to SQL）接客戶既有資料庫                                             | 客戶的 PostgreSQL、MySQL、SQL Server、Oracle 或 SynxDB                                                 | 5432、3306、1433、1521（依資料庫設定） |
| 知識庫改用[自帶向量資料庫](/tech/platform-development/bring-your-own-vector-db.md) | 客戶的 Elasticsearch、OpenSearch、Oracle 或 SynxDB                                                    | 9200、1521、5432              |
| 對話平台（LINE、Teams、Email 等）                                               | 各平台的 API；Email 另需 SMTP／IMAP 伺服器                                                                 | 443；SMTP 25／465／587         |
| 寄送邀請信、通知信                                                              | 客戶的 SMTP 伺服器                                                                                    | 25／465／587                  |
| 爬蟲、網路搜尋、地圖、圖片與影片生成                                                     | 對應的雲端服務（見[功能可用性對照](/tech/platform-development/onprem-deployment-types.md#feature-availability)） | 443                         |
| 單一登入（SSO）與 LDAP 身分同步                                                   | 客戶的 IdP 或目錄伺服器                                                                                  | 依 IdP；LDAP 389／636          |
| 自架 MCP Server、API 工具                                                   | 客戶指定的網址                                                                                         | 依服務                         |

* **只有連出，沒有連入**：客戶內部系統不需要主動連到 MaiAgent 主機，例外是對話平台的 webhook（LINE、Messenger 等平台要能從網際網路呼叫 MaiAgent 的 API）與客戶自己寫的 API 串接。
* **內部網段**：主機與客戶內部資料庫、模型主機之間的路由由客戶網路團隊規劃；部署包不包含 VPN、專線或 VPC 對等連線等網路元件。主機放在客戶雲端上時，與機房內資料庫的連線請用客戶既有的雲端到機房連線（VPN 或專線）。
* **SaaS 連到客戶內部資料庫**時，連線來自 MaiAgent 的雲端服務，需要在客戶防火牆放行來源 IP，請洽 MaiAgent 窗口取得；需要 VPN 或 VPC 對等連線等其他接法時，請先洽 MaiAgent 評估。資料庫端的檢查項目見使用者手冊[建立與設定資料庫：網路前置](https://docs.maiagent.ai/build/database/create-database#network-prerequisites)。

## GPU 節點 <a href="#gpu-nodes" id="gpu-nodes"></a>

平台本身不需要 GPU。只有在主機上自建模型服務或離線語音辨識時才需要：

| 項目                       | 需求                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| 作業系統                     | 與平台主機相同（Ubuntu 22.04／24.04／26.04、RHEL 8／9、Rocky Linux 8／9，amd64 或 arm64），見[作業系統與帳號](#operating-systems) |
| GPU                      | NVIDIA GPU，運算能力（compute capability）7.0 以上，例如 V100、A100、H100                                             |
| NVIDIA 驅動                | 525.60 以上                                                                                               |
| NVIDIA Container Toolkit | 部署時自動安裝（連線與離線安裝都支援 Ubuntu 與 RHEL／Rocky，離線安裝的套件隨部署包提供）                                                   |
| GPU 容器執行環境               | 由部署流程把 Docker（或 Kubernetes 節點的容器執行環境）設定成使用 NVIDIA runtime；主機上已裝好驅動、Toolkit 與 runtime 時會直接沿用             |

* **驅動由誰裝**：連線安裝且主機是 Ubuntu 時，部署流程會自動安裝最適合的 NVIDIA 驅動並重新開機；RHEL／Rocky Linux 或離線安裝時，請在部署前自行安裝驅動，確認 `nvidia-smi` 可以執行後再開始部署。
* **NVSwitch 平台**（HGX／DGX 的 SXM GPU）要在部署設定開啟 NVIDIA Fabric Manager。
* 使用 FP8 的模型設定（FP8 KV cache）需要 Ada Lovelace、Hopper 或 Blackwell 世代；Ampere 世代（例如 A100）不支援。各模型的 GPU 建議見 [GPU 算力硬體規劃](/tech/platform-development/gpu.md)。
* **NVIDIA GB10**（Dell Pro Max GB10、DGX Spark，GPU 與系統共用 128 GB 記憶體）要改用另一種 GPU 掛載方式，而且同一台主機上所有模型服務的記憶體占用比例合計不要超過 0.92，部署時請告知 MaiAgent。
* 部署範本只支援 NVIDIA GPU。其他加速卡請洽 MaiAgent 評估。
* 離線語音辨識需要 GPU。離線文件解析（Docling）本身不需要 GPU；要描述文件裡的圖片時，需要接一個 OpenAI 相容的 LLM（例如主機上的模型服務）。

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

* [部署型態與功能對照](/tech/platform-development/onprem-deployment-types.md)
* [地端模型服務接入](/tech/platform-development/onprem-model-services.md)
* [GPU 算力硬體規劃](/tech/platform-development/gpu.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/system-requirements.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.