升級與回滾

升級就是更換你所固定的確切映象，回滾就是換回上一個。在 Community 上，那是映象的 確切版本標籤，如果你固定了摘要，還包括它的摘要：該版本被重新構建時，標籤可能被 再次推送到新的位元組上，而摘要永遠不會移動（參見 Docker → 固定映象）。在 Enterprise 上，那是 你的釋出說明中點名的摘要（企業版額外提供）。本頁的其他內容對 兩者都相同。Docker → 升級與回滾 記錄了操作流程以及每一步的原因；本頁把它重述為一份檢查清單，並加上特定版本所要求的 步驟。

升級

1. 閱讀你正在執行的版本與目標版本之間每個 ObjectStack 版本的說明，並逐一完成下文 中它的特定版本步驟。主版本的變化意味著底層有破壞性 變更。
2. **備份資料庫。**模式遷移是單向向前的：回滾映象並不會回滾模式。
3. 把映象改為新的確切版本，如果你固定了摘要，就改為它的摘要，然後重啟。模式會在 執行時報告就緒之前更新到最新；破壞性的變更會拒絕啟動並點名自身，直到你用 os migrate apply --allow-destructive 應用它。
4. 確認就緒端點（/api/v1/ready）返回 200。

回滾

保留上一個版本，如果你固定了摘要，還要保留它的摘要：那就是回滾。要回滾，就恢復它並重復第 3 步 —— 只要你要離開的 版本沒有做不相容的模式變更，這就是有效的（釋出說明會說明何時做了這樣的變更）。金鑰 也有同樣的單向邊界：在 ObjectStack 17.7 或更高版本上設定或輪換的金鑰，17.7 之前 的版本無法讀取（參見下文的 17.7）。

應用單獨進行版本管理

應用本身如果以已釋出產物的形式交付，則獨立於映象進行版本管理 —— 參見 部署 → 應用如何進入。把已釋出的產物視為不可變 的：如果你原地覆蓋一個產物，即使資料庫備份完美無缺，你也會失去幹淨回滾的能力 （備份 → 產物版本管理）。

特定版本步驟

上面的步驟對每個版本都相同。ObjectOS 底層的一些 ObjectStack 版本還要求運維人員 採取行動：在新映象啟動之前設定一個變數、執行一次資料遷移、輪換一個憑據。Community 映象的版本就是 ObjectStack 版本；在 Enterprise 上，映象的 釋出清單說明了它內嵌的是 哪個 ObjectStack 版本。按從舊到新的順序，結合上面的步驟，逐一完成你所跨越的每個 版本的小節。

每個小節都是該版本升級檢查清單中屬於運維人員的部分，並連結到完整的清單；一個版本 對你所執行的應用（它的後設資料和程式碼）做了哪些改變，寫在同一份清單和 更新日誌中。os migrate 命令是新映象內嵌版本的 ObjectStack CLI。它們會啟動應用來讀取其後設資料，所以要用部署啟動時的同一套環境 執行它們 —— 同一個資料庫和同一個應用 —— 參見 CLI → 資料庫遷移。

**先在副本上演練。**釋出說明把大多數檢查清單條目標記為 not exercised：它們 源自變更本身，而不是來自一次實際走過的升級。先針對資料庫的副本執行每一步，並在 對真實資料庫操作之前做好備份。

ObjectStack 17.0

• 執行這兩項資料遷移。os migrate files-to-references，然後加 --apply 再 執行一次；以及 os migrate value-shapes，等它不再報告任何內容後，再加 --apply 執行一次。在各自記錄下標誌之前，17.0 之前建立的資料庫會繼續接受格式錯誤的檔案和 引用值，並給出警告；之後則會拒絕它們。對於來不及修復的整合，參見 應急開關。
• **應用所繫結的每個資料來源都必須能連線。**無法連線的資料來源會讓啟動失敗，並且只要 有一個停止響應，/api/v1/ready 就返回 503。

完整清單：17.0.0。

ObjectStack 17.1

• 在升級之前，列出已關閉的許可權集和崗位（active: false）。從 17.1 起它們不再 授權，點名了已停用崗位的共享規則會被撤銷其共享。重新啟用那些仍應授權的。
• **在 isolated 下重新簽發 API 金鑰。**17.1 之前簽發的金鑰不帶組織，在 OS_TENANCY_POSTURE=isolated 下會被拒絕。
• **匯出按物件授予。**出廠的管理員許可權集不再匯出每個物件；在需要匯出的地方，在 應用自己的許可權集中授予 allowExport。

完整清單：17.1.0。

ObjectStack 17.2

• **把基於 http_request_errors_total 的監控重新指向別處。**這個序列已經退役， 讀數恆為零，看起來就像一個健康的伺服器。使用 http_requests_total{status=~"5.."}。
• 授予 manage_platform_settings 或 manage_metadata 給任何呼叫外部資料來源 路由的憑據；這些路由現在會以 403 拒絕其他呼叫者。

完整清單：17.2.0。

ObjectStack 17.3

• 隔離牆式姿態：在新映象啟動之前設定 OS_PLATFORM_OWNER_EMAIL，否則它會 拒絕啟動。參見 環境變數。
• **在新的唯一索引能夠建立之前，對自動編號去重。**執行 os migrate duplicates， 修復它報告的重複項，然後重新執行 os migrate plan。在你完成之前，索引不會建立， 唯一性也不會強制執行；啟動只會記錄這一點，所以乾淨的啟動並不能證明索引存在。
• **回填 sys_record_share。**17.3 之前寫入的共享授權不帶組織，按租戶範圍的讀取 會找不到它們。ObjectStack 以 @objectstack/plugin-sharing 的兩個函式提供這項 回填 —— planSysRecordShareOrganizationBackfill（試執行）和 runSysRecordShareOrganizationBackfill —— 而不是一個 os 命令，啟動時也不會 有任何東西執行它。
• **開放註冊現在必須宣告。**沒有宣告受眾姿態的應用只接受邀請：除非該地址持有一份 待處理的邀請，否則自行註冊會以 403 SELF_REGISTRATION_CLOSED 被拒絕（全新安裝 上的第一個賬戶不受此限）。

完整清單：17.3.0。

ObjectStack 17.4

• **在 isolated 下，重新簽發不帶組織的 API 金鑰。**它們會從 200 變為 401。 在 group 下，這樣的金鑰仍然可用。
• 在授權儲存不可達時，預期儲存下載和設定路由返回 503，而它們過去會悄悄 降級。

完整清單：17.4.0。

ObjectStack 17.5

升級之前：

• 隔離牆式姿態：在 OS_PLATFORM_OWNER_EMAIL 中列出每一位平臺管理員（逗號 分隔，已驗證的地址）。admin_full_access 授權不再賦予這一身份，沒有宣告的部署 啟動後會沒有任何平臺管理員。
• **對定時任務做出決定。**除非部署設定了 OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true， 否則時間觸發的流程和打包的 cron 作業會停止執行。在 isolated 下，先給每個定時 流程的開始節點指定它以哪個 organization 身份執行，並排空它被掛起的執行。參見 流程。
• **預檢賬戶身份變更。**執行 os migrate account-issuer（只讀；只要有兩個賬戶會 衝突，它就以非零狀態退出），並解決它報告的每一個衝突：衝突的行永遠不會替你合併。

進入這個版本：

os migrate account-issuer                     # expect: safe to drop
os migrate plan                               # read every destructive change first
os migrate apply --allow-destructive          # drops sys_account.issuer, after a backup
os migrate account-issuer                     # again: expect zero collisions

--allow-destructive 會應用計劃中列出的每一項破壞性變更，而不只是這一項 —— 這 就是要先看計劃的原因。

之後：

• 匿名的 GET /api/v1/auth/get-session 返回 401，不再是帶 null 的 200。
• 分析會以 403 拒絕無法讀取該物件的呼叫者。
• 失敗的通知投遞記錄保留 7 天，而不是 90 天。

完整清單：17.5.0。

ObjectStack 17.6

• 如果應用聲明瞭讀取或寫入物件的匿名端點（authRequired: false），先暫緩 升級。從 17.6 起，它對每個物件都會被拒絕，而且沒有任何受支援的渠道會給匿名 呼叫者授予許可權集，17.7 中也是如此。公開表單是另一扇門，會繼續正常工作。
• 授予 manage_platform_settings 給每個通過 /api/v1/meta 讀取 datasource 或 external_catalog 後設資料、或儲存 datasource 後設資料的使用者或 整合。
• 找出與打包流程同名的儲存流程（啟動日誌會對每一個發出警告）。從 17.6 起， 打包的流程優先，儲存的那個會停止執行；把你需要的那個以新名稱克隆一份。
• 重寫靜態儲存的後設資料正文副本：os migrate audit-metadata-bodies，然後加 --apply 再執行一次。⚠️ 在 17.6.0 上，即使是試執行也會寫入資料庫 —— 請針對 副本執行。
• 找出早於西元 1000 年的 datetime 值並改寫它們；升級之後，任何攜帶這種值的 寫入都會被拒絕。

完整清單：17.6.0。

ObjectStack 17.7

升級之前：

• **在已退役欄位仍被宣告時，執行任何需要讀取其殘留列的轉換。**升級之後，沒有任何 執行時入口會返回該列；只有 os migrate unmapped-columns --object NAME 能讀取它。
• 給每個必須保持公開的公開表單加上 sharing.enabled: true，在應用中和儲存的 覆蓋層中都要加。沒有它，表單會返回 404 FORM_NOT_FOUND。
• **如果你可能需要回滾到 17.7 之前，請保留重新設定每個金鑰的途徑。**在 17.7 上 設定、輪換或重新封裝的金鑰會以更早的版本無法開啟的格式寫入。
• 替換記憶體中的啟動儲存（OS_DATABASE_DRIVER=memory，或 memory:// URL）： 它會被拒絕。

進入這個版本：執行 os migrate audit-metadata-bodies，然後加 --apply 再執行 一次，以從審計和活動副本中刪除儲存的內容雜湊。17.7 的試執行不再寫入。升級之前持有 的後設資料版本令牌會返回一次 409 METADATA_CONFLICT；重新讀取該項即可獲得新的令牌。

首次啟動之後：

• 輪換每個流程金鑰 —— 入站鉤子的 secret 和 http 節點的 signingSecret —— 在啟動日誌報告它已遷移到 sys_flow_credential 之後進行，並把新值交給負責簽名或 校驗的一方。
• **輪換 JWT 簽名金鑰，並撤銷和重新簽發必須保持私密的分享連結。**它們之前的值可能 在審計軌跡中留有副本，而升級不會改寫審計軌跡。如何輪換簽名金鑰取決於你的部署 如何提供這些金鑰，因此請按照你的部署自己的流程進行。
• **恢復、取消或清除升級前暫停的流程執行。**它們儲存的變數中仍以明文儲存著憑據。
• 可選，並且只在你不會回滾到 17.7 之前時執行：os secret rewrap，然後加 --apply 再執行一次，以新格式重新封裝較舊的金鑰。升級路徑上沒有任何東西會執行它。
• 從任何寫入 /api/settings/localization 的客戶端中刪除已退役的本地化鍵： date_format、time_format、number_format、first_day_of_week。點名其中任何 一個的請求會被整體以 400 拒絕。
• 對未驗證的本地郵箱地址的外部登入會被拒絕（account_not_linked）；它不再 悄悄地關聯到那個賬戶。

完整清單：17.7.0。

企業版額外提供

企業版映象按摘要固定，從不按標籤，所以升級就是更換摘要，回滾就是換回上一個。

1. 從釋出說明中取得新的摘要，並在上線之前閱讀映象的 釋出清單：確認產品 主版本線是你所在的那一條，並檢查內嵌執行時的兼容範圍是否移動了。
2. 備份資料庫，然後修改映象摘要並重啟技術棧。遷移會在新副本接收流量之前執行到 完成。
3. 確認就緒端點返回 200，且副本報告為健康。保留上一個摘要以便回滾。

• Kubernetes —— 升級同樣是更換映象摘要，並讓遷移 Job 在新副本提供服務之前 執行到完成。參見 Kubernetes → 滾動升級就是更換摘要。
• 物理隔離 —— 在外部校驗新的摘要，把它傳入內部，修改固定的摘要，然後重啟。 保留上一個摘要：在物理隔離的網路中，它可能是你唯一能回滾到的副本。參見 物理隔離 → 把映象帶進網路內部。