> 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-versioning-and-upgrades.md).
# 版本與升級
私有雲與地端的季度版（2026.Qn）怎麼編號、同季更新與跨季升級的流程摘要、預估停機時間、退版限制，以及地端功能為什麼會晚於 SaaS
私有雲與地端部署不跟著 SaaS 持續更新，而是使用季度版。本頁寫給負責維運排程與變更管理的客戶 IT 與 SI 夥伴：版本怎麼看、升級要準備什麼、會停機多久，以及出問題時能退到哪裡。
{% hint style="info" %}
本頁是規劃用的摘要。升級的完整步驟寫在隨部署包提供的安裝手冊，新版本的功能差異與升級前後要調整的設定寫在 MaiAgent 隨新版本提供的版本說明，請洽 MaiAgent 窗口取得。
{% endhint %}
## 季度版是什麼
* **以季為單位的版本線**：地端版本依季度分線，例如 `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` 沒有。
各季度版提供哪些功能，以版本說明為準；私有雲與地端之間的差異見[部署型態與功能對照](/tech/platform-development/onprem-deployment-types.md#feature-availability)。
## 同季更新與跨季升級
| | 同季更新 | 跨季升級 |
| ------ | --------------------------------- | ---------------------------------------- |
| 例子 | `2026.Q3-09.24` → `2026.Q3-09.30` | `2026.Q2` → `2026.Q3` |
| 步驟 | 相同 | 相同 |
| 實測停機時間 | 約 10 分鐘 | 約 20 分鐘（資料庫結構更新約 11 分鐘） |
| 要多注意的事 | — | 資料庫結構更新較久；新版才有的系統設定採新版的預設值；先看版本說明列出的調整項目 |
* 實測環境的資料量很少；資料越多，資料庫結構更新越久，請預留較寬的停機時間並事先通知使用者。
* **功能開關會保留**：已經設定過的功能開關（包括客戶在後台改過的）升級時不會改。升級只設定新版本才有的開關，以及《部署設定確認表》上答過、但之前從未套用的題目。
* **官方內建 Agent**：升到 `2026.Q3-10.02` 起的版本時，如果這台還沒設定過官方市集，升級會把它打開。要維持關閉，請在升級前於確認表答「不要」。
* **物件儲存沿用原本的引擎**：原本用 MinIO 的環境升級後仍是 MinIO。
* **只更新 MaiAgent 本身的服務**（後端、背景工作、後台、對話頁，以及有啟用的本機模型服務等選配元件）。反向代理、搜尋引擎、資料庫等元件的設定變更不會在升級時套用；需要時版本說明會註明。
## 升級流程摘要
{% stepper %}
{% step %}
### 取得目前的部署設定
升級沿用安裝時的部署設定，只改版本號，不重新設定。這份設定含模型服務的金鑰，請依公司規定保存與傳遞。
{% endstep %}
{% step %}
### 進場前備齊新版物料
離線環境在能上網的作業電腦下載新版部署包與映像，並逐檔比對 checksum；連線環境可在主機上直接下載。私有雲要確認部署設定裡的部署類別仍是私有雲。
{% endstep %}
{% step %}
### 換上新部署包並檢查
把新部署包放到主機上，**舊的部署包目錄保留**，退版時要用。執行安裝前檢查，確認版本號與物料都正確。
{% endstep %}
{% step %}
### 執行升級
升級程式依序：檢查部署包版本與部署類別（私有雲或地端；不一致就停下、不做任何變更）→ 自動備份 → 後端換新版並更新資料庫結構 → 背景工作 → 後台與對話頁 → 確認所有服務都已換成新版本。升級前的備份會標記保留，不會被依天數清掉。
{% endstep %}
{% step %}
### 升級後確認
確認各服務的版本號、執行一次功能驗收測試、檢查功能開關的套用結果，並登入後台確認既有的知識庫與檔案都在。確認新版穩定後，再解除升級前備份的保留標記。
{% endstep %}
{% endstepper %}
## 升級前要準備的空間
| 位置 | 需要的空間 |
| ----------- | ------------------------------------ |
| 安裝帳號的家目錄 | 新部署包壓縮檔約 7 GB，解開後約 7.7 GB；舊的部署包目錄要保留 |
| 部署目錄 | 新版映像檔約 8 GB |
| Docker 資料目錄 | 載入後的新版映像約 8 GB；舊版映像會保留，退版時要用 |
| 備份目錄 | 一份完整備份 |
## 退版限制
* **完整退版只能靠升級前的備份**。升級途中某個服務換版失敗時，只有那個服務會自動退回舊版映像；在它之前已換好的服務與已更新的資料庫結構不會退回，系統會處於新舊混合的狀態，必須還原升級前的備份。
* **升級之後新增的資料會遺失**：還原會把資料庫、上傳的檔案、服務設定與網站憑證一起回到升級前。
* **退版順序不能反過來**：要先還原備份，再換回舊的部署包目錄。新版的資料庫結構配舊版程式會無法登入；較新的部署包會在動手前擋下這種情況。
* **Kubernetes**：還原只還原資料，不會把服務換回舊版映像；要退回舊版請洽 MaiAgent 協助。
* **Kubernetes 叢集版本**：升級只換 MaiAgent 的版本，不換叢集本身的版本；既有叢集從 1.31 升到 1.36 目前不支援。
實測（Docker 單機）：同季更新後退回，還原約 157 秒，完成後 10 秒內可以登入，版本、資料庫結構與既有資料都回到升級前。
{% hint style="warning" %}
Docker 分散式與 Kubernetes 環境升級或退版前，請先與 MaiAgent 窗口確認升級計畫並排定時間。
{% endhint %}
## 從 2026.Q2 升到 2026.Q3
* Q3 的功能開關會在這次升級時第一次設定：部署設定有確認表的答案時照表，沒有時採用預設值（版本說明會列出）。要照確認表設定，請在升級前換上確認表匯出的升級用設定。
* Q2 的「是否限制建立助理數量」會換成數字上限：勾選的方案變成最多 1 個，沒勾的變成不限，跟 Q2 時的實際行為相同。
## 相關頁面
* [部署型態與功能對照](/tech/platform-development/onprem-deployment-types.md)
* [維運重點：備份與還原](/tech/platform-development/onprem-operations.md#backup-and-restore)
* [系統需求](/tech/platform-development/system-requirements.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-versioning-and-upgrades.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.