版本與升級

私有雲與地端的季度版（2026.Qn）怎麼編號、同季更新與跨季升級的流程摘要、預估停機時間、退版限制，以及地端功能為什麼會晚於 SaaS

私有雲與地端部署不跟著 SaaS 持續更新，而是使用季度版。本頁寫給負責維運排程與變更管理的客戶 IT 與 SI 夥伴：版本怎麼看、升級要準備什麼、會停機多久，以及出問題時能退到哪裡。

本頁是規劃用的摘要。升級的完整步驟寫在隨部署包提供的安裝手冊，新版本的功能差異與升級前後要調整的設定寫在 MaiAgent 隨新版本提供的版本說明，請洽 MaiAgent 窗口取得。

季度版是什麼

• 以季為單位的版本線：地端版本依季度分線，例如 2026.Q2、2026.Q3。各季度線獨立維護，同一季內會持續發布更新。

• 版本號：季度加上發布日期，例如 2026.Q3-10.02。

• 一組交付組合：每次發布包含後端、後台、對話頁三個版本號，三者要使用 MaiAgent 提供的同一組（例如後端與後台是 2026.Q3-10.02、對話頁是 2026.Q3-09.28）。

• 部署包：安裝程式本身另有版本，升級時會一起換成新的部署包。

目前維護中的季度線：2026.Q3（最新）與 2026.Q2，兩條線都還在發布更新；2026.Q1 已停止更新，請升級到維護中的季度線。新部署一律使用最新的季度線。要確認某條線是否仍在維護、或取得最新版本號，請洽 MaiAgent 窗口。

怎麼看目前安裝的版本：部署設定裡的後端、後台、對話頁版本欄位就是這台的版本；主機上也可以直接看各服務容器使用的映像標籤（Docker：docker compose ps；Kubernetes：kubectl get deploy -n maiagent -o wide）。

地端功能時程

新功能會先在 SaaS 上線，再於之後的季度版納入地端。因此同一時間，地端可用的功能會少於 SaaS。例如：

• Office 線上編輯（檔案庫）目前只在 SaaS 提供，尚未納入季度版。

• AI Gateway 與部署在主機內的 LocalAI 離線語音辨識，從 2026.Q3 起才提供；2026.Q2 沒有。

各季度版提供哪些功能，以版本說明為準；私有雲與地端之間的差異見部署型態與功能對照。

同季更新與跨季升級

	同季更新	跨季升級
例子	2026.Q3-09.24 → 2026.Q3-09.30	2026.Q2 → 2026.Q3
步驟	相同	相同
實測停機時間	約 10 分鐘	約 20 分鐘（資料庫結構更新約 11 分鐘）
要多注意的事	—	資料庫結構更新較久；新版才有的系統設定採新版的預設值；先看版本說明列出的調整項目

• 實測環境的資料量很少；資料越多，資料庫結構更新越久，請預留較寬的停機時間並事先通知使用者。

• 功能開關會保留：已經設定過的功能開關（包括客戶在後台改過的）升級時不會改。升級只設定新版本才有的開關，以及《部署設定確認表》上答過、但之前從未套用的題目。

• 官方內建 Agent：升到 2026.Q3-10.02 起的版本時，如果這台還沒設定過官方市集，升級會把它打開。要維持關閉，請在升級前於確認表答「不要」。

• 物件儲存沿用原本的引擎：原本用 MinIO 的環境升級後仍是 MinIO。

• 只更新 MaiAgent 本身的服務（後端、背景工作、後台、對話頁，以及有啟用的本機模型服務等選配元件）。反向代理、搜尋引擎、資料庫等元件的設定變更不會在升級時套用；需要時版本說明會註明。

升級流程摘要

1

取得目前的部署設定

升級沿用安裝時的部署設定，只改版本號，不重新設定。這份設定含模型服務的金鑰，請依公司規定保存與傳遞。

2

進場前備齊新版物料

離線環境在能上網的作業電腦下載新版部署包與映像，並逐檔比對 checksum；連線環境可在主機上直接下載。私有雲要確認部署設定裡的部署類別仍是私有雲。

3

換上新部署包並檢查

把新部署包放到主機上，舊的部署包目錄保留，退版時要用。執行安裝前檢查，確認版本號與物料都正確。

4

執行升級

升級程式依序：檢查部署包版本與部署類別（私有雲或地端；不一致就停下、不做任何變更）→ 自動備份 → 後端換新版並更新資料庫結構 → 背景工作 → 後台與對話頁 → 確認所有服務都已換成新版本。升級前的備份會標記保留，不會被依天數清掉。

5

升級後確認

確認各服務的版本號、執行一次功能驗收測試、檢查功能開關的套用結果，並登入後台確認既有的知識庫與檔案都在。確認新版穩定後，再解除升級前備份的保留標記。

升級前要準備的空間

位置	需要的空間
安裝帳號的家目錄	新部署包壓縮檔約 7 GB，解開後約 7.7 GB；舊的部署包目錄要保留
部署目錄	新版映像檔約 8 GB
Docker 資料目錄	載入後的新版映像約 8 GB；舊版映像會保留，退版時要用
備份目錄	一份完整備份

退版限制

• 完整退版只能靠升級前的備份。升級途中某個服務換版失敗時，只有那個服務會自動退回舊版映像；在它之前已換好的服務與已更新的資料庫結構不會退回，系統會處於新舊混合的狀態，必須還原升級前的備份。

• 升級之後新增的資料會遺失：還原會把資料庫、上傳的檔案、服務設定與網站憑證一起回到升級前。

• 退版順序不能反過來：要先還原備份，再換回舊的部署包目錄。新版的資料庫結構配舊版程式會無法登入；較新的部署包會在動手前擋下這種情況。

• Kubernetes：還原只還原資料，不會把服務換回舊版映像；要退回舊版請洽 MaiAgent 協助。

• Kubernetes 叢集版本：升級只換 MaiAgent 的版本，不換叢集本身的版本；既有叢集從 1.31 升到 1.36 目前不支援。

實測（Docker 單機）：同季更新後退回，還原約 157 秒，完成後 10 秒內可以登入，版本、資料庫結構與既有資料都回到升級前。

Docker 分散式與 Kubernetes 環境升級或退版前，請先與 MaiAgent 窗口確認升級計畫並排定時間。

從 2026.Q2 升到 2026.Q3

• Q3 的功能開關會在這次升級時第一次設定：部署設定有確認表的答案時照表，沒有時採用預設值（版本說明會列出）。要照確認表設定，請在升級前換上確認表匯出的升級用設定。

• Q2 的「是否限制建立助理數量」會換成數字上限：勾選的方案變成最多 1 個，沒勾的變成不限，跟 Q2 時的實際行為相同。

相關頁面

• 部署型態與功能對照

• 維運重點：備份與還原

• 系統需求