故障排查：啟動、登入、許可權

從症狀出發，先檢查最小的邊界。

ObjectOS 無法啟動

**先讀日誌的最後幾行，再做別的。**這裡有一大類啟動失敗是有意的拒絕，而不是崩潰：執行時會檢查它收到的配置，列印一條點名相互矛盾的變數的致命錯誤，然後退出。這些訊息會準確地指出問題所在，重啟多少次都不會改變結果。

無論哪個版本，你最可能遇到的拒絕：

日誌說	含義
某個資料驅動無法連線	`OS_DATABASE_URL` 中的資料庫 —— 或者應用把物件繫結到的某個資料來源 —— 無法訪問，或者其憑據錯誤。啟動會被拒絕，而不是提供一個對每個請求都報錯的伺服器。
有一項待處理的破壞性模式變更，並點名了每一項變更	新的應用或版本需要一項會丟失資料的變更。先備份，然後用 `os migrate apply --allow-destructive` 有意識地應用它，再重啟。
產物的期望摘要和實際摘要	`OS_ARTIFACT_URL` 上的完整性固定值與獲取到的位元組不匹配 —— 參見下文。
埠已被佔用	`os start` 從不換用其他埠。釋放它，或者同時修改 `OS_PORT` 和代理的上游。
聲明瞭多節點拓撲	在一個沒有多節點許可證、或協調是程序內的執行時上，`OS_CLUSTER_REPLICAS` 大於 1。執行一個副本 —— 參見 Docker → 多節點。
`Cannot find module 'pg'`	裸裝的 Node.js 沒有 PostgreSQL 驅動。映象中帶有 `pg` 和 `mysql2`；在映象之外，把驅動安裝在 CLI 旁邊（`npm install -g pg`）。

如果日誌中沒有致命錯誤，就檢查常見原因：出故障的服務的容器日誌，以及探針 —— /api/v1/health 在程序提供 HTTP 服務後即有響應，/api/v1/ready 則要等資料庫有響應之後。

應用不是你預期的那個

部署所提供的應用恰好只來自一個地方，而是哪個地方是由部署宣告的決策 —— 參見啟動模式。當執行中的應用不是你釋出的那個時：

**確認這個部署處於哪種模式。**如果沒有設定產物引用，執行時提供的就是它的映象所帶的內容 —— 在 Community 上，是 /srv/app/objectstack.json 處的檔案，或者一個空核心加上安裝進它的應用；在 Enterprise 上，是映象中編寫的後設資料，加上安裝進它的任何內容。釋出一個新的產物在部署指定它之前不會改變任何東西。
檢查啟動橫幅，它會點名實際載入的應用。
不匹配的完整性固定值會拒絕啟動，並同時列印期望的摘要和實際的摘要。同時列印這兩者正是關鍵所在：它能區分一個被重新發布的產物和一個被替換的產物。
**沒有固定值、且產物主機不可達時，啟動會明確地失敗。**在沒有固定值的路徑上沒有快取回落 —— 沒有任何東西能驗證快取副本的真實性。編排會重試；執行時永遠不會自己捏造一個不同的應用。
有固定值、且主機不可達時，本地快取的副本可能會被使用 —— 但只限於其位元組的雜湊仍與固定值相符的副本，並會以一條警告說明這一點。快取在每次讀取時都會重新計算雜湊；檔名從來不是依據。
**設定一個已退役的產物變數並不會選中應用。**在企業版映象上，其中一個會直接拒絕啟動；其他的則根本沒有任何東西讀取，所以部署會像你什麼都沒設定一樣啟動。已退役的名稱列出了它們及其替代項。

在全新的部署上，第一個註冊的賬戶會成為管理員。這條規則計算的是人員，而不是登入：一個預置了人員記錄、卻沒有登入賬戶的應用會讓資料庫看起來已有資料，所以註冊保持關閉，而預置的人員又沒有可用於登入的密碼。啟動日誌會以 error 級別在 no_sign_in_account_at_boot 下報告這一情況。恢復要在帶外進行 —— 往資料庫寫入一條邀請記錄，然後進行一次普通的註冊；ObjectStack 的自託管指南逐步介紹了這一過程。要預防這種情況，就隨人員一起預置登入賬戶，或者在第一個管理員存在之前讓目錄保持為空。

檢查：

已配置 OS_AUTH_SECRET —— 沒有它，登入端點會被完全跳過；
OS_AUTH_URL 和 OS_TRUSTED_ORIGINS 指定的是公網地址；
OIDC 回撥 URL 與公網地址一致；
ObjectOS 能訪問 OIDC 發現 URL；
受信任的源包含公網域名；
Cookie 的作用域是部署的公網主機名。

使用者看不到記錄

檢查：

部署主機名是否正確。
使用者是否屬於預期的組織。
物件的 read 許可權。
行級安全。
共享規則或記錄共享。
如果只是部分欄位缺失，檢查欄位安全。

設定無法編輯

某項設定可能被環境覆蓋值鎖定了。生效的設定按以下順序解析：

Environment -> Tenant -> User -> Default

如果環境提供了值，執行時的編輯應當被拒絕，而不是悄悄地覆蓋它。

無法讀取儲存的金鑰

加密的設定、secret 欄位和資料來源憑據都用 OS_SECRET_KEY 加密。如果它們在一次重啟或恢復之後無法解密，說明金鑰變了：一個從未設定它的容器自行生成了一個金鑰，並隨檔案系統一起丟失了，或者資料庫在沒有原始金鑰的情況下被恢復了。設定託管備份的原始值 —— 參見備份。新的金鑰無法恢復用舊金鑰加密的值。

Webhook 或作業不執行

檢查：

產物的 requires 列表包含所需的能力；
ObjectOS 映象包含可選的服務包；
佇列/作業服務的配置可用；
定時流程和 cron 作業需要 OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true —— 未設定即為關閉；
允許訪問目標的出站網路；
投遞日誌或作業執行記錄在 Setup 診斷中可見。

資料庫錯誤

檢查：

資料庫 URL 和驅動型別；
從 ObjectOS 到資料庫的網路訪問；
憑據和 TLS 選項；
模式同步/遷移日誌；
如果使用本地 SQLite，檢查儲存持久化。

企業版額外提供

需許可證的映象在啟動時還會拒絕另外幾種配置：

日誌說	含義
兩項設定被一起點名為不受支援的組合	一種無法協同工作的許可證模式和雲端姿態 —— 最常見的是在一個配置為沒有控制平面的部署上使用普通的、線上校驗的許可證。物理隔離給出了受支援的矩陣。
隔離牆式部署需要許可證	在沒有許可證的情況下要求了多組織租戶姿態。隔離是一項需許可證的能力；執行時不會假裝擁有它來提供服務。
某項決策沒有做出	在多組織姿態下，新註冊使用者的成員資格策略和掛載的 AI Agent 集合都沒有安全的預設值。宣告任何一個可用的值都會被接受；不設定則不行。
設定了一個已退役的變數	舊的產物選擇變數會拒絕啟動，並點名它的替代項。參見已退役的名稱。
缺少叢集金鑰	開啟叢集驅動會使一個在所有副本間共享的加密金鑰成為必需。

故障排查

本頁內容