維運重點：離線安裝、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 放不下。
注意事項
部署設定要在進場前定案。改到功能、版本或 CPU 架構就需要不同的物料，只能回到作業電腦重新下載；只跟這台主機有關的設定（例如使用者連線的位址）可以在現場改。
Docker 分散式：物料要放到每一台跑 Docker 的主機。
Kubernetes 的離線安裝另有備料項目（叢集元件、Helm chart、儲存元件的系統套件）。網域要在內部 DNS 設好，不能用依賴公開 DNS 解析的網域服務。
部署設定含模型服務的金鑰，升級時還會用到，請依公司規定加密保存。
Messenger、Instagram、WhatsApp 通道需要 Meta 從網際網路呼叫 MaiAgent 的 API，離線環境無法使用。
網域與 TLS 憑證
重點
兩種連線方式：IP 加埠號（不需要網域），或每個服務一個網域（例如 API、後台、對話頁各一個）。Kubernetes 只支援後者。要開放的埠見系統需求：連線埠。
使用者從其他位址連線時（例如雲端主機的公網 IP、NAT 對外位址，或指向它們的網域），安裝時的伺服器位址要填使用者實際連線的位址。填成主機的內網 IP，使用者從外部會開不了後台，也無法上傳檔案。
安裝時自動產生自簽憑證，瀏覽器第一次開啟會出現安全性警告。要換成客戶的憑證時，公開 CA 或企業內部 CA 簽發的都可以，
.pfx或「憑證檔＋私鑰」兩種形式都接受；部署包附的轉換工具會檢查憑證與私鑰是否配對、憑證鏈是否完整、多久到期。換憑證不需要重新安裝，實測套用期間 API 呼叫全部成功，服務不中斷。
注意事項
憑證上的名稱（SAN）要包含使用者連線用的位址。使用者用 IP 連線時，憑證要包含這個 IP；公開 CA 通常不簽發含 IP 的憑證。
雲端與多數 NAT 環境中，主機連不到自己的外部位址，部署後的驗收測試會全部連線逾時。需要在主機加上 NAT 規則，把「連自己外部位址」的流量轉回內網位址。
企業內部 CA：根 CA 要加進後端服務的信任清單，否則後端連回自己的網址時會驗證失敗；CA 憑證要含 Key Usage 欄位。
系統不會主動通知憑證到期，請把到期檢查排進客戶既有的監控或排程。
還原備份時，網站憑證也會回到備份當時的那一張。
Kubernetes 的憑證存在叢集裡；要使用企業內部 CA 簽發的憑證，請先洽 MaiAgent。Docker 分散式與 Kubernetes 換證前，請先與 MaiAgent 窗口確認步驟並安排時間。
備份與還原
重點
部署包附備份腳本，一次備份資料庫、物件儲存（上傳的檔案）、搜尋索引、快取與訊息佇列、反向代理設定，以及服務設定（含各服務的密碼與加密金鑰）。
預設存在主機上的備份目錄，保留 7 天；備份目錄與保留天數都可以調整，也可以用排程（cron）定期備份。
還原會停止服務、覆蓋資料，再重新啟動，期間系統無法使用。實測（新安裝、資料很少）：備份約 1 分鐘，還原約 2.5 分鐘。
升級前會自動備份，並標記保留，見版本與升級：退版限制。
注意事項
預設的備份目錄跟系統在同一顆磁碟，主機故障時備份會一起遺失。請掛載獨立磁碟或網路儲存當備份目錄。
服務設定裡的加密金鑰遺失後，加密過的資料無法解開。不要刪除或替換。
還原有先後依賴，請整份還原，不要只還原其中一部分。
正式使用前，建議做一次還原演練：建立一筆可辨識的資料、備份、刪除、還原，確認資料回來。
Docker 分散式在部署主機執行，各台的資料集中存到部署主機。Kubernetes 在控制節點執行；叢集是客戶自己的（不是由安裝程式建立）時不能用內建腳本，請改用叢集既有的備份機制。
備份失敗不會觸發監控告警，請另外確認排程備份的結果。
監控（選配）
重點
啟用後部署 VictoriaMetrics（指標，預設保留 30 天）、VictoriaLogs（日誌，預設保留 14 天）與 Grafana 儀表板，涵蓋主機、容器、資料庫、快取、搜尋引擎、物件儲存與訊息佇列；主機有 NVIDIA 驅動時也會收 GPU 的使用率、記憶體與溫度。
告警是另一個開關：開啟後依內建規則（例如主機 CPU、記憶體、磁碟用量過高）以 Email 通知。通知目前只支援 Email（SMTP）。
注意事項
以下目前不在監控範圍：應用層指標（例如 HTTP 錯誤率、請求延遲）、業務指標（對話量等）、從外部確認使用者連得進來、憑證到期、備份成功與否。外部可用性請用客戶既有的外部監控去打 API 網址。
Kubernetes 的監控介面沒有對外路由，要用 port-forward 連線。
監控與告警的導入方式（門檻、通知對象）請在啟用前與 MaiAgent 確認。
部署後驗收
重點
部署設定選擇自動驗收時（建議開啟），安裝最後會執行功能驗收測試（deploy-test），產生 HTML 與 JSON 報告。之後也可以單獨再跑，例如換憑證或升級之後。
通過標準：第 0 階段（基礎設施）與第 1 階段（冒煙測試）必須全部通過；第 2 階段以後的失敗逐項看原因。略過的項目通常是沒有啟用的選配功能，略過或未驗證都不算通過。
部署前有填《部署設定確認表》時，用隨確認表產生的核對工具比對系統實際的設定，確認功能開關都照表設定。
1
安裝結果
沒有失敗的步驟
2
服務狀態
所有服務都在執行
3
後台、對話頁、管理介面
都能開啟並登入
4
預設帳號密碼
已修改，出廠密碼無法登入
5
功能驗收測試
第 0、1 階段全部通過
6
備份
備份腳本執行成功
7
確認表核對（有填確認表時）
沒有不一致的項目
注意事項
部署包建立的預設管理帳號使用公開的出廠密碼。安裝完成後請立刻修改，改好之前不要開放給使用者連線。
驗收測試用的帳號密碼改過之後，要同步更新部署目錄裡保存的那份，否則之後的驗收測試會登入失敗。
瀏覽器操作類的測項需要另外交付的驗收映像，沒有時報告會標示為未驗證。
主機重新開機後服務會自動啟動，實測約 1.5 分鐘後可以登入。
邀請信與通知信的寄送設定
成員管理的 Email 邀請、轉真人通知等信件由平台透過客戶的 SMTP 伺服器寄出。部署包不包含郵件伺服器，也不會在安裝時設定寄信；安裝後請由系統管理員在管理介面（Django 系統管理後台）的 Email 設定填寫：
SMTP 伺服器：主機、埠號、帳號密碼與寄件人位址。沒有設定時，邀請信不會寄出。
註冊頁面 URL 樣板：邀請信裡的註冊連結，填成後台的登入網址加上邀請碼參數，例如
https://<後台網址>/login?invitationCode={invitationCode}，{invitationCode}會被換成該筆邀請的邀請碼。後台網址就是安裝時給使用者連線的後台位址（含網域與 TLS 時用https://）。沒有填時，邀請信會寄不出去。
登出後導向指定網址
採用單一登入（SSO）或把 MaiAgent 嵌在企業入口網站裡的部署，後台自帶的登入頁通常用不到，使用者登出後停在那一頁沒有出路。部署設定可以指定「登出後導向網址」，例如企業入口首頁或 IdP 的登出端點。
設定後的行為
下列三種情況都會整頁導向該網址：使用者主動登出、閒置逾時被登出、未登入時直接開啟後台連結。
導向是整頁跳轉，按瀏覽器的上一頁不會回到後台登入頁。
未設定時維持原本行為，回到 MaiAgent 的登入頁。
網址格式
接受
http://、https://開頭的完整網址，或以單一/開頭的站內路徑。其他格式（例如
javascript:或以//開頭的網址）會被忽略，視同未設定。
相關頁面
最後更新於
這有幫助嗎？