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

# 部署環境需求

部署 MaiAgent 私有雲／地端 2026 Q3 的環境需求：主機、作業系統、網路與連接埠、網域與憑證、Kubernetes、寄信、模型服務相容性、登入方式，以及未開通服務時的系統行為。

本頁列出部署 MaiAgent 私有雲／地端 2026 Q3 所需的環境條件，供 IT 評估現有環境是否適合。各服務人數的建議規格與 GPU 節點需求，見技術人員手冊的[系統需求](https://docs.maiagent.ai/tech/platform-development/system-requirements)。

{% hint style="info" %}
本頁的「私有雲」「地端」指合約約定的部署型態，決定能不能使用需要連到雲端服務的功能，與主機本身能不能連外無關。🔺 表示需開通（開通雲端服務，依用量月結）或需另行部署的項目，請洽 MaiAgent 專案窗口。
{% endhint %}

## 主機 <a href="#hosts" id="hosts"></a>

* **最低需求**：記憶體 16 GB、部署目錄所在磁碟可用空間 40 GB；未達無法安裝。
* **正式環境建議**：記憶體 48 GB、可用空間 200 GB 以上。低於建議值仍可安裝，適合測試或 POC 規模。
* **部署帳號的家目錄**：另需約 27 GB 放部署包（解開後可以刪除壓縮檔）。
* **GPU（地端選配）**：自建模型與離線語音辨識需 NVIDIA GPU（圖形處理器）主機。離線主機無法在安裝時自動安裝驅動，需事先裝好 NVIDIA 驅動（執行 `nvidia-smi` 能看到 GPU）。

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

| 項目     | 支援範圍                                              |
| ------ | ------------------------------------------------- |
| 發行版    | Ubuntu 22.04／24.04／26.04、RHEL 8／9、Rocky Linux 8／9 |
| CPU 架構 | x86\_64、arm64                                     |
| 限制     | RHEL／Rocky 需關閉 SELinux；RHEL／Rocky 8 離線安裝需 8.10 以上 |

## 網路 <a href="#network" id="network"></a>

### 連線安裝與離線安裝 <a href="#online-vs-offline" id="online-vs-offline"></a>

| 安裝方式 | 適用情況                                  | 說明                                                                      |
| ---- | ------------------------------------- | ----------------------------------------------------------------------- |
| 連線安裝 | 主機能連到 MaiAgent 指定的下載來源與模型來源（清單於簽約後提供） | 安裝時直接下載物料，並會更新主機作業系統（含核心，可能需要重開機）；有變更管理流程者建議採離線安裝。分散式部署時，每一台主機都要能連到這些來源 |
| 離線安裝 | 封閉網路；只開白名單或需經代理伺服器者也視同封閉網路            | 物料事先備妥，以 USB（exFAT 或 NTFS 格式）或跳板機帶入                                     |

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

| 存取方式    | 使用者連線需開放的連接埠        |
| ------- | ------------------- |
| 以 IP 存取 | 8000、3333、3334、9000 |
| 以網域存取   | 80、443              |

### 雲端服務連線 <a href="#cloud-connectivity" id="cloud-connectivity"></a>

* **私有雲**：要使用雲端模型、雲端語音轉文字、網頁搜尋、雲端連接器等功能時，主機要能連到對應的服務。只開白名單時，需開放的位址請洽 MaiAgent。
* **地端**：不適用（地端不提供需要連雲端的功能）。

### 內部系統連線 <a href="#internal-systems" id="internal-systems"></a>

助理要連內部系統（MCP（模型連接協定）／API）時，需設定允許連線的內部網段；未設定時，後台會拒絕內網位址。網段可在部署後補上。

## 網域與憑證 <a href="#domain-and-tls" id="domain-and-tls"></a>

* **預設**：以主機 IP 存取，使用系統自動產生的憑證，瀏覽器會出現安全性警告。
* **使用自有網域**：需四個子網域（預設為 api／admin／webchat／minio，可自訂）的 DNS 與憑證（自有憑證機構簽發或公開憑證）。憑證須涵蓋使用者連線用的網域或 IP；日後更換憑證不需停機。

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

* 網址一律是網域形式（api／admin／webchat／minio，kibana 選用）。正式環境需這幾個子網域的內部 DNS 與憑證；離線環境必須使用自有網域與內部 DNS。
* Kubernetes 版本預設 1.31，可選 1.36。
* 目標主機若是 RHEL 8，使用 Kubernetes 1.36 時要 8.6 以上，並改用 cgroup v2（需重開機）。
* 需開放 6443 等叢集連接埠，並關閉 swap。

## 寄信 <a href="#email" id="email"></a>

邀請成員、重設密碼都靠寄信，需要一台郵件伺服器：

* 需提供：伺服器位址、連接埠、加密方式（STARTTLS 或 SSL）、登入帳號密碼、寄件者信箱。
* 伺服器要能用帳號密碼登入；不支援免帳密的內部轉信。
* 沒有郵件伺服器時，成員帳號改由管理員建立並設定密碼。

## 模型服務 <a href="#model-service" id="model-service"></a>

可使用既有的模型服務（OpenAI 相容端點），需提供 LLM、Embedding、Reranker 三種模型。

* Embedding 服務須接受 `encoding_format: base64` 與 `truncate_prompt_tokens` 兩個參數，請先向服務提供者確認。
* 目標主機要連得到這個服務網址；使用企業內部憑證機構簽發的憑證時，需另外提供憑證。

## 登入方式 <a href="#login-methods" id="login-methods"></a>

支援本地帳號密碼、Google、SAML 2.0（Azure AD）、Keycloak、Cloudflare Access、身份同步（LDAP（目錄服務）／SCIM（帳號自動佈建協定））。使用單一登入時，需身分提供者的登入端點與憑證。**地端**不提供 Google 登入。

## 備份儲存 <a href="#backup-storage" id="backup-storage"></a>

備份預設存放在系統碟，主機故障時會一起遺失。建議準備獨立磁碟或網路儲存。

## 未開通或未部署服務時的系統行為 <a href="#without-value-added-services" id="without-value-added-services"></a>

未開通或未部署對應服務 🔺 的功能無法使用，部分功能的設定入口可能仍會顯示。需開通或另行部署的功能見 [2026 Q3 版本說明](/license/id-2026-q3/release-notes.md#value-added-services)。

## 其他限制 <a href="#limits" id="limits"></a>

* 平台檔案連結有 1 小時時效；外部系統若要引用平台檔案，需每次重新取得連結。
* 附件上限：對話附件 10 MB，知識庫上傳 100 MB。
* 部署在雲端主機、使用者從公網 IP 或 NAT 位址連線時，主機需設定網路轉址規則。


---

# 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/license/deployment/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.