> 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-operations.md).
# 維運重點：離線安裝、TLS、備份、監控與驗收
私有雲與地端部署的維運重點：離線（air-gap）安裝、網域與 TLS 憑證、備份與還原、監控（選配）與部署後驗收，各項的重點與注意事項
本頁整理以部署包安裝 MaiAgent（私有雲或地端）時，客戶 IT 與 SI 夥伴在規劃與日常維運要掌握的五件事。每一項列出重點與容易出錯的地方，實際的指令與預期輸出寫在隨部署包提供的安裝手冊，請洽 MaiAgent 窗口取得。
## 離線（air-gap）安裝
**重點**
* **怎麼判定**：主機不能直接連到 MaiAgent 的下載站與 Hugging Face 時，一律用離線安裝。只開白名單、要經過 proxy、只連得到其中一部分，也算離線。
* **只需進場一次**：進場前，在能上網的作業電腦依部署設定下載部署包、服務映像與模型權重，並逐檔比對 checksum；進場後把物料放進主機，檢查無誤再安裝。
* **物料大小**：實測 Docker 單機的預設功能是 12 個映像、約 8.7 GB；啟用監控與告警約 9.2 GB。在主機上執行模型時，權重另計。
* **怎麼帶進現場**：作業電腦接上客戶內網直接複製，或用 USB。USB 要用 exFAT 或 NTFS 格式：後端映像單一檔案約 7.5 GB，FAT32 放不下。
{% hint style="warning" %}
**注意事項**
* 部署設定要在進場前定案。改到功能、版本或 CPU 架構就需要不同的物料，只能回到作業電腦重新下載；只跟這台主機有關的設定（例如使用者連線的位址）可以在現場改。
* Docker 分散式：物料要放到每一台跑 Docker 的主機。
* Kubernetes 的離線安裝另有備料項目（叢集元件、Helm chart、儲存元件的系統套件）。網域要在內部 DNS 設好，不能用依賴公開 DNS 解析的網域服務。
* 部署設定含模型服務的金鑰，升級時還會用到，請依公司規定加密保存。
* Messenger、Instagram、WhatsApp 通道需要 Meta 從網際網路呼叫 MaiAgent 的 API，離線環境無法使用。
{% endhint %}
## 網域與 TLS 憑證
**重點**
* **兩種連線方式**：IP 加埠號（不需要網域），或每個服務一個網域（例如 API、後台、對話頁各一個）。Kubernetes 只支援後者。要開放的埠見[系統需求：連線埠](/tech/platform-development/system-requirements.md#ports)。
* **使用者從其他位址連線時**（例如雲端主機的公網 IP、NAT 對外位址，或指向它們的網域），安裝時的伺服器位址要填使用者實際連線的位址。填成主機的內網 IP，使用者從外部會開不了後台，也無法上傳檔案。
* **安裝時自動產生自簽憑證**，瀏覽器第一次開啟會出現安全性警告。要換成客戶的憑證時，公開 CA 或企業內部 CA 簽發的都可以，`.pfx` 或「憑證檔＋私鑰」兩種形式都接受；部署包附的轉換工具會檢查憑證與私鑰是否配對、憑證鏈是否完整、多久到期。
* **換憑證不需要重新安裝**，實測套用期間 API 呼叫全部成功，服務不中斷。
{% hint style="warning" %}
**注意事項**
* 憑證上的名稱（SAN）要包含使用者連線用的位址。使用者用 IP 連線時，憑證要包含這個 IP；公開 CA 通常不簽發含 IP 的憑證。
* 雲端與多數 NAT 環境中，主機連不到自己的外部位址，部署後的驗收測試會全部連線逾時。需要在主機加上 NAT 規則，把「連自己外部位址」的流量轉回內網位址。
* 企業內部 CA：根 CA 要加進後端服務的信任清單，否則後端連回自己的網址時會驗證失敗；CA 憑證要含 Key Usage 欄位。
* 系統不會主動通知憑證到期，請把到期檢查排進客戶既有的監控或排程。
* 還原備份時，網站憑證也會回到備份當時的那一張。
* Kubernetes 的憑證存在叢集裡；要使用企業內部 CA 簽發的憑證，請先洽 MaiAgent。Docker 分散式與 Kubernetes 換證前，請先與 MaiAgent 窗口確認步驟並安排時間。
{% endhint %}
## 備份與還原
**重點**
* 部署包附備份腳本，一次備份資料庫、物件儲存（上傳的檔案）、搜尋索引、快取與訊息佇列、反向代理設定，以及服務設定（含各服務的密碼與加密金鑰）。
* 預設存在主機上的備份目錄，保留 7 天；備份目錄與保留天數都可以調整，也可以用排程（cron）定期備份。
* 還原會停止服務、覆蓋資料，再重新啟動，期間系統無法使用。實測（新安裝、資料很少）：備份約 1 分鐘，還原約 2.5 分鐘。
* 升級前會自動備份，並標記保留，見[版本與升級：退版限制](/tech/platform-development/onprem-versioning-and-upgrades.md#rollback)。
{% hint style="danger" %}
**注意事項**
* 預設的備份目錄跟系統在同一顆磁碟，主機故障時備份會一起遺失。請掛載獨立磁碟或網路儲存當備份目錄。
* 服務設定裡的加密金鑰遺失後，加密過的資料無法解開。不要刪除或替換。
* 還原有先後依賴，請整份還原，不要只還原其中一部分。
* 正式使用前，建議做一次還原演練：建立一筆可辨識的資料、備份、刪除、還原，確認資料回來。
* Docker 分散式在部署主機執行，各台的資料集中存到部署主機。Kubernetes 在控制節點執行；叢集是客戶自己的（不是由安裝程式建立）時不能用內建腳本，請改用叢集既有的備份機制。
* 備份失敗不會觸發監控告警，請另外確認排程備份的結果。
{% endhint %}
## 監控（選配）
**重點**
* 啟用後部署 VictoriaMetrics（指標，預設保留 30 天）、VictoriaLogs（日誌，預設保留 14 天）與 Grafana 儀表板，涵蓋主機、容器、資料庫、快取、搜尋引擎、物件儲存與訊息佇列；主機有 NVIDIA 驅動時也會收 GPU 的使用率、記憶體與溫度。
* 告警是另一個開關：開啟後依內建規則（例如主機 CPU、記憶體、磁碟用量過高）以 Email 通知。通知目前只支援 Email（SMTP）。
{% hint style="warning" %}
**注意事項**
* 以下目前不在監控範圍：應用層指標（例如 HTTP 錯誤率、請求延遲）、業務指標（對話量等）、從外部確認使用者連得進來、憑證到期、備份成功與否。外部可用性請用客戶既有的外部監控去打 API 網址。
* Kubernetes 的監控介面沒有對外路由，要用 port-forward 連線。
* 監控與告警的導入方式（門檻、通知對象）請在啟用前與 MaiAgent 確認。
{% endhint %}
## 部署後驗收
**重點**
* 部署設定選擇自動驗收時（建議開啟），安裝最後會執行功能驗收測試（deploy-test），產生 HTML 與 JSON 報告。之後也可以單獨再跑，例如換憑證或升級之後。
* **通過標準**：第 0 階段（基礎設施）與第 1 階段（冒煙測試）必須全部通過；第 2 階段以後的失敗逐項看原因。略過的項目通常是沒有啟用的選配功能，略過或未驗證都不算通過。
* 部署前有填《部署設定確認表》時，用隨確認表產生的核對工具比對系統實際的設定，確認功能開關都照表設定。
| # | 驗收項目 | 通過條件 |
| - | ------------- | ------------ |
| 1 | 安裝結果 | 沒有失敗的步驟 |
| 2 | 服務狀態 | 所有服務都在執行 |
| 3 | 後台、對話頁、管理介面 | 都能開啟並登入 |
| 4 | 預設帳號密碼 | 已修改，出廠密碼無法登入 |
| 5 | 功能驗收測試 | 第 0、1 階段全部通過 |
| 6 | 備份 | 備份腳本執行成功 |
| 7 | 確認表核對（有填確認表時） | 沒有不一致的項目 |
{% hint style="danger" %}
**注意事項**
* 部署包建立的預設管理帳號使用公開的出廠密碼。安裝完成後請立刻修改，改好之前不要開放給使用者連線。
* 驗收測試用的帳號密碼改過之後，要同步更新部署目錄裡保存的那份，否則之後的驗收測試會登入失敗。
* 瀏覽器操作類的測項需要另外交付的驗收映像，沒有時報告會標示為未驗證。
* 主機重新開機後服務會自動啟動，實測約 1.5 分鐘後可以登入。
{% endhint %}
## 邀請信與通知信的寄送設定
成員管理的 Email 邀請、轉真人通知等信件由平台透過客戶的 SMTP 伺服器寄出。部署包不包含郵件伺服器，也不會在安裝時設定寄信；安裝後請由系統管理員在**管理介面**（Django 系統管理後台）的 Email 設定填寫：
* **SMTP 伺服器**：主機、埠號、帳號密碼與寄件人位址。沒有設定時，邀請信不會寄出。
* **註冊頁面 URL 樣板**：邀請信裡的註冊連結，填成後台的登入網址加上邀請碼參數，例如 `https://<後台網址>/login?invitationCode={invitationCode}`，`{invitationCode}` 會被換成該筆邀請的邀請碼。後台網址就是安裝時給使用者連線的後台位址（含網域與 TLS 時用 `https://`）。沒有填時，邀請信會寄不出去。
{% hint style="info" %}
* 這兩項是整個部署共用的系統設定，組織後台沒有對應欄位，組織管理員改不了；要調整請找系統管理員。
* 改了註冊頁面 URL 樣板只影響之後寄出的信，已寄出的邀請信仍帶舊連結，需要時在後台的邀請狀態重新發送。
* 這個設定和使用者手冊的 [對話平台基本設定：自訂域名（CNAME）](https://docs.maiagent.ai/build/channels/basic-settings#custom-domain) 無關：自訂網域只影響對話頁的公開網址。
{% endhint %}
### 哪些信需要寄信設定與註冊頁面網址
下表列出平台會主動寄出的系統信，以及寄信設定（上方的 SMTP 伺服器，或 AWS SES）、註冊頁面 URL 樣板沒有設定時各自的結果。每種信什麼時候寄、寄給誰、能不能關閉，見使用者手冊的 [系統通知與 Email](https://docs.maiagent.ai/start/system-emails)。
| 系統信 | 需要寄信設定 | 需要註冊頁面 URL 樣板 | 沒有寄信設定時 |
| -------------------------------------------------------- | ------ | -------------------------------- | --------------------------------------------------------- |
| 重設密碼信 | 是 | 否 | 使用者在登入頁送出「忘記密碼」會看到錯誤，收不到信 |
| 邀請信 | 是 | 是：沒填時這筆邀請直接標為寄送失敗，按「重新發送」也會失敗 | 邀請標為寄送失敗 |
| 設定密碼信（批次匯入成員） | 是 | 否 | 成員照樣建立，但整批不寄信，也不留寄送紀錄 |
| 轉真人通知信 | 是 | 信中的對話連結取註冊頁面 URL 樣板的網址：沒填時連結無法點開 | 不寄信；通知中心的轉真人通知照常發出 |
| 連接器申請信 | 是 | 否 | 不寄信；成員的申請照常送出 |
| MCP 工具需要重新授權 | 是 | 否 | 不寄信，只發通知中心的通知 |
| 排程略過了授權失效的工具 | 是 | 否 | 不寄信；排程的執行紀錄照常記錄被略過的工具 |
| 點數餘額不足提醒、個人額度即將用罄／到期 | 是 | 否 | 不寄信；通知中心的提醒照常發出 |
| 組織審核通過／未通過、資料即將永久清除 | 是 | 否 | 不寄信 |
| 方案與 Credits 通知（方案已排定、方案已生效、本月 Credits 已發放、Credits 已加值入帳） | 是 | 否 | 私有雲與地端預設關閉，不會寄出；開啟後若沒有寄信設定，每封信會記錄為失敗，補好設定後可在管理介面的通知紀錄重新寄送 |
{% hint style="warning" %}
* 連接器申請信、MCP 工具需要重新授權、排程略過了授權失效的工具這三種信，信中附的後台連結目前固定指向雲端版網址（`admin.maiagent.ai`）。私有雲與地端的收件人請直接登入自家後台，到連接器管理或工具頁面處理，不要點信中的連結。
* 改用 SMTP 或 AWS SES 寄信時，邀請信與設定密碼信的**主旨與信件範本**沒有預設值，請一併填寫，否則寄出的信沒有主旨與內容。
{% endhint %}
## 登出後導向指定網址
採用單一登入（SSO）或把 MaiAgent 嵌在企業入口網站裡的部署，後台自帶的登入頁通常用不到，使用者登出後停在那一頁沒有出路。部署設定可以指定「登出後導向網址」，例如企業入口首頁或 IdP 的登出端點。
**設定後的行為**
* 下列三種情況都會整頁導向該網址：使用者主動登出、閒置逾時被登出、未登入時直接開啟後台連結。
* 導向是整頁跳轉，按瀏覽器的上一頁不會回到後台登入頁。
* 未設定時維持原本行為，回到 MaiAgent 的登入頁。
**網址格式**
* 接受 `http://`、`https://` 開頭的完整網址，或以單一 `/` 開頭的站內路徑。
* 其他格式（例如 `javascript:` 或以 `//` 開頭的網址）會被忽略，視同未設定。
{% hint style="info" %}
這是後台前端的部署設定，套用到整個部署的所有組織，組織後台沒有對應欄位。安裝時可以一併設定；安裝後要新增或修改，請洽 MaiAgent 窗口安排套用，前端服務重新載入設定後生效。各 SSO 類型登出時對 IdP 的行為，見使用者手冊 [第三方登入：登出行為](https://docs.maiagent.ai/org/sso#logout-behavior)。
{% endhint %}
## 相關頁面
* [部署型態與功能對照](/tech/platform-development/onprem-deployment-types.md)
* [系統需求](/tech/platform-development/system-requirements.md)
* [版本與升級](/tech/platform-development/onprem-versioning-and-upgrades.md)
* [地端模型服務接入](/tech/platform-development/onprem-model-services.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-operations.md?ask=&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.