附錄 C · 疑難排解

完整的錯誤碼清單由坤安技術支援提供的錯誤碼對照文件維護。這份附錄做的是另一件事：把你在畫面上實際遇到的狀況，對應到原因與解法。

1. 「我要的按鈕不見了」

這幾乎一定是權限問題，不是系統故障。 你沒有權限的控制項，Merak 是不畫出來，而不是把它變灰。

依序檢查：

你有那個權限嗎？ 開啟 /profile，權限區塊會列出你的角色給你的一切。對照附錄 A §3。
這筆資料的狀態允許嗎？ 很多操作有狀態前提——應用程式要未啟用才能刪、帳號要已鎖定才能解鎖。見附錄 B。
功能旗標關著嗎？ Agentless 與圖片功能受旗標控制。若整個區塊對所有人都不存在，代表你的部署沒有開啟它。
是跨功能相依嗎？ 少了 另一種 資源的讀取權限，整張卡片或篩選欄位都會消失——裝置區塊需要 device:R、組織篩選需要 organization:R，以此類推。

2. 登入

症狀	原因	該怎麼做
「電子郵件或密碼錯誤」	帳號或密碼打錯。	重新輸入；必要時走忘記密碼。
「帳號已被鎖定」	連續登入失敗。	由管理員在該帳號上按解鎖。
「帳號已被停用」	帳號處於停用狀態。	由管理員重新啟用。
「嘗試次數過多」	觸發速率限制。	稍候再試。
「成員帳號無法存取管理主控台」	你在主控台使用了成員帳號。	改用 Agentless 入口網站。
登入後立刻被踢出來	登入階段建立失敗，或帳號類型檢查沒過。	再試一次；若重複發生，到稽核日誌查失敗紀錄。
出現一則「登入逾時」並回到登入頁	refresh token 到期。這是預期行為。	重新登入。

2.1 MFA

症狀	原因	該怎麼做
驗證碼被拒絕，提示框保持開啟	驗證碼錯誤，或已經被用過。	等下一組——TOTP 驗證碼是一次性的。
登入時跳出註冊對話框	政策要求 MFA，而這個帳號從未註冊。	掃描 QR Code 並輸入驗證碼，見 01 §4.2。
被要求輸入兩組驗證碼（僅入口網站）	工作階段與服務授權各需要一組，而驗證碼不允許重複使用。	輸入下一組，或按略過，見 11 §2.3。
驗證器不見了	—	由管理員在該帳號上使用重設 MFA，然後你重新註冊。
帳號上沒有重設 MFA 按鈕	該帳號其實沒有註冊過（已啟用 MFA 為關），或狀態不是啟用中／已鎖定。	沒有東西可以重設。

2.2 帳號啟用與密碼重設

症狀	原因	該怎麼做
「連結無效」	權杖已過期（一小時）或已使用。	請管理員重寄信件。
「帳號已啟用」	帳號已經是啟用狀態。	直接登入。
舊信的連結突然失效	重寄會讓前一個權杖失效。	使用最新那封信。
送出按鈕一直不能按	六條密碼規則沒有全部通過。	看欄位下方的即時檢查清單。
「輸入內容無效」	送出的資料被拒絕。	重新檢查後再試。

3. 建立與編輯資料

症狀	原因	該怎麼做
「此名稱已被使用」	已有同名資料（輸入時即時檢查）。	換一個。
「此電子郵件已被使用」	已有其他帳號使用。	換一個。
建立精靈的下一步一直是停用的	有必填欄位空白或無效，或非同步檢查還在跑。	等檢查完成，再修正欄位。
欄位變紅但沒有訊息	訊息渲染失敗。	請回報——這是缺陷，不是規則。
複製出來的資料建立不了	預填值與既有資料衝突。	編號最多探測 20 次，超過就交由欄位自己的檢查提示。請手動改名稱。
建立表單上的存取權欄位是唯讀的	你缺少兩側權限中的一個。	見附錄 A §4.3。資料仍然可以建立，只是不帶那項關聯。
複製出來的使用者角色變少了	防提權機制移除了你無法授予的角色。系統有警告過你。	請有那些權限的人代為指派。

4. 刪除

症狀	原因	該怎麼做
刪除被拒，「資源仍有關聯資料」	仍存在關聯資源。	成員有強制刪除確認框。應用程式、組織、角色與使用者沒有強制刪除——請先清掉相依關係。
應用程式上沒有刪除按鈕	它還在啟用中。	先停用。
角色上沒有刪除按鈕	那是系統角色。	系統角色不能刪除。
批次刪除顯示 `M/N 筆符合`	部分列不符合前提（狀態不對，或是系統角色）。	用只保留符合的，或去調整那些列。
刪除成員時說還有裝置	該成員仍有已註冊的裝置。	先停用再刪除那些裝置，或使用強制刪除。

5. 應用程式與端點

症狀	原因	該怎麼做
「虛擬 DNS 與 X 衝突」，無法送出	另一個應用程式攔截了同樣的位址與連接埠。	改位址或改連接埠。這一項刻意阻擋——兩個應用程式攔截同一個名稱，在 DNS 階段根本分不出來。
服務端點下方出現提示，指出另一個應用程式	同一個後端目標已經被別處使用。	這不會阻擋。一台後端在同一組 `IP:port` 上承載多個站台，是正常拓撲。
編輯後衝突訊息還留著	不應該如此——成對的兩半都會重跑檢查。	請回報。
路由層掛掉時衝突檢查靜靜地放行	檢查失敗時視為「沒有衝突」，不阻擋你。	送出時後端會再驗證一次。
通訊協定類型無法編輯	它在建立時就固定了。	唯一例外是兩種協定都沒有的資料，可以補寫一次——補完之後就再度固定。
描述無法編輯	設計如此，建立後即唯讀。	—
複製出來的應用程式虛擬 DNS 連接埠是空的	往上探測 20 次都找不到未被占用的連接埠。	請自己指定一個。

6. Agentless

兩層都必須到位：成員持有席次，而且 成員已綁定到該應用程式。此外應用程式本身也要開啟 Agentless。

症狀	原因	該怎麼做
應用程式上的 Agentless 開關打不開	三道關卡之一：L7 協定不是 `http`／`https`；租戶的 Agentless 功能未啟用；Agentless 服務配額已滿。	對症處理。關閉則永遠允許。
開啟 Agentless 時出現別名衝突	另一個應用程式推導出相同的別名。	改應用程式的名稱——別名是推導出來的，你無法自行輸入。
成員的 Agentless 席次開關是停用的	沒有可用席次，或根本沒購買。	釋出席次或加購。配額可在 `/profile` 查看。
把成員的席次關掉被拒絕	該成員仍持有 Agentless 綁定。	先移除綁定；訊息會告訴你還剩幾筆。
Agentless 成員選擇器裡的候選列是停用的	那些成員沒有席次。	先到成員資料上授予席次。
成員看得到服務卡片，卻打不開	缺少逐位成員的綁定（常見於存取權只來自組織的情況）。	個別綁定該成員。
成員的服務清單是空的	完全沒有應用程式存取權，或能連上的應用程式都沒開 Agentless。	兩者都檢查。
卡片卡在「準備中…」	該應用程式的 Agentless 狀態是 `provisioning` 或 `error`。	後端會自行重新驅動佈建；請看應用程式詳細頁。
成員的存取約 30 分鐘後失效	服務授權目前無法續期。	請他重新登入入口網站。
席次莫名其妙被用光	在你檢查完到儲存之間，別人搶走了最後一個。	席次是否可用，最終以後端為準。

7. Merak Node

症狀	原因	該怎麼做
沒有下載 bootstrap kit 按鈕	節點已佈署。安裝程式在成功後會刪掉那份一次性憑證，所以已經沒有東西可以給你。	—
已佈署的節點沒有重新產生 JWT 按鈕	刻意隱藏，避免有人用重發憑證當作取得新安裝包的繞路。	—
bootstrap kit 對話框回報載入失敗	這是雲端節點，沒有安裝程式。	雲端節點由系統為你佈建。
bootstrap kit 說沒有有效的權杖	24 小時的註冊權杖已過期。	從對話框使用重新產生 JWT。
`install.sh` 拒絕執行	主機不是 Ubuntu 22.04 LTS。	換一台支援的主機。
建立節點時出現配額訊息而失敗	router 配額已用盡。	到 `/profile` 查看 Merak Node 配額。
建立在步驟一以欄位錯誤失敗	名稱重複、欄位格式錯誤，或未選擇 router 角色（它沒有預設值）。	明確選一個角色。
節點顯示 `OFFLINE`	目前連不上。這不代表「已佈署」。	安裝包與 JWT 仍可用。重跑 `install.sh` 前先確認它是否曾經註冊成功。
即時狀態顯示 `UNKNOWN`	路由層連不上。	檢查節點網路。

8. 匯入

症狀	原因	該怎麼做
送出被擋，「請拆分檔案」	超過 500 列。	拆檔，或用附加匯入檔案分次匯入——合併後的批次一樣受 500 列上限限制。
關聯欄位出現紅色標籤	該名稱比對不到東西。關聯欄位採精確比對，刻意不做模糊比對，避免差一點的名稱把你綁到錯的資料上。	修正拼寫，或從下拉選單挑選。
角色匯入時某個權限名稱解析不出來	你自己沒有那個權限，所以它根本不在你的選項清單裡。	請有該權限的人處理，或拿掉這一欄。
列舉值解析不出來	精確與模糊比對都找不到。	在預覽中用下拉選單；範本裡的範例一定是有效值。
狀態變更被判定為錯誤	生命週期不允許該轉換。	匯入不能繞過生命週期。見附錄 B §2。
名稱重複只是琥珀色警告	這是刻意的——後端允許兩筆資料同名。	除非你本來就不想同名，否則不需要處理。
「第 N 列也會更新這筆資料」	兩列比對到同一筆既有資料，後送出的那筆生效。	若它們編輯的是不同欄位就沒問題；否則請合併。
空白儲存格沒有把欄位清空	空白代表「別動」，永遠不是「清空」。	支援清空的欄位（描述）請用 `\N`。
空白的狀態或 MFA 欄位什麼都沒做	修改模式下這些欄位刻意沒有預設值。	真的要改就明確填上。
修改模式的列送不出去——「未比對」	沒有定位到既有資料。	編輯任一比對鍵（ID、電子郵件、名稱）；自動完成解析到唯一一筆時就會釘住。
已比對的列一直重新比到錯的資料	釘選是刻意黏著的。	用撤銷比對，再編輯鍵值。撤銷期間不會重跑比對，因此不會立刻又釘回你剛否決的那一筆。
使用者匯入的某列失敗，但使用者其實建立了	角色指派失敗會讓整列使用者失敗。	手動指派角色，或修好後重新匯入。
角色匯入的某列成功，但少了一個權限	角色匯入容忍權限授予失敗——只有角色本體建立失敗才會讓該列失敗。	到角色詳細頁補上該權限。
第二個檔案把第一個蓋掉了	不應該如此——附加是合併。	請回報。
附加的檔案解析失敗	只有那個檔案沒進來。	你既有的列不受影響；修好後再附加一次。

9. 匯出

症狀	原因	該怎麼做
第二個分頁顯示「排隊中」	匯出會跨分頁依序執行，避免對伺服器重複索取。	等一下。
CSV 裡少了關聯欄位	你缺少該關聯的讀取權限，因此整欄被省略。	見 09 §2.3。
匯出所選少了關聯欄位	所選匯出只帶基本欄位，因為關聯需要逐列去抓。	改用完整匯出。
Excel 開啟中文亂碼	不應該發生——匯出是 UTF-8 含 BOM。	確認檔案中途沒有被其他程式另存過。
進度一直是不確定的轉圈	第一頁回來之前是正常的。	等一下，它會變成 `已取得／總數`。
審批頁沒有匯出按鈕	審批刻意不提供匯出。	—

10. 清單、篩選與表格

症狀	原因	該怎麼做
點列身沒有反應	列點選只有在至少勾了一個核取方塊之後才生效，避免誤選。	先勾一個核取方塊，或雙擊開啟詳細頁。
我的選取不見了	新的搜尋會清空選取，背景重新整理則不會。	重新選取。
稽核日誌好像少了讀取操作	動作篩選留空時會刻意排除 `GET`。	明確勾選 GET。
清單一打開就已經被篩選過	套用了儲存的預設篩選。	在面板或偏好設定中清除預設。
分享出去的連結忽略了我的預設	正確行為——網址帶條件時一律以網址為準。	—
我要的欄位不見了	很多欄位預設是隱藏的。	在欄位設定齒輪中打開。
欄位設定沒有跟著我換到另一台機器	它是依瀏覽器儲存的。	匯出／匯入你的偏好設定，見 10 §9。
時間看起來不對	時間依你的時區偏好顯示。	檢查 `/preference`。
切換時區後時間沒有變	它從下一次重繪起生效。	換頁或重新載入。

11. 個人資料、租戶與配額

症狀	原因	該怎麼做
頁首的租戶名稱是空白的	讀取它需要 `tenant:R`；頁面選擇降級而不是失敗。	指派一個帶有該權限的角色。
「此帳號無法取得配額資訊」	讀取配額需要 `license:R`。	同上。
配額卡片一直轉圈	不應該如此——轉圈代表「還在載入」，訊息代表「載完了，沒有東西」。	請回報。
配額上限顯示 `0`	`0` 在所有資源代表無限制，只有 Agentless 席次例外，那裡代表未購買。	看文字，不要看數字。
改完密碼被登出了	預期行為。你必須用新密碼重新登入。	—
匯入偏好設定後語言變了	當語言等於那台裝置的瀏覽器語言時算是預設值，因此不會被寫進匯出檔。	手動設定，見 10 §9。
匯入 `{}` 把所有設定都重設了	預期行為。匯入是權威式取代，檔案中沒有的面向會回到預設值。	—

12. 審批

症狀	原因	該怎麼做
我看得到佇列，卻沒有裁決按鈕	你有 `tokenRequest:R` 但沒有 `tokenRequest:U`。	申請修改權限。
部分列沒有裁決按鈕	只有 `PENDING` 的列可以裁決。	—
資源對話框說內容過大	超過 20,000 字元；系統刻意不傾印原始內容。	去查一下提出申請的來源。
某個巢狀分支說層數太深	超過 8 層。	同上。
對話框內容渲染失敗	只有對話框壞掉；清單仍可使用，下一列打開時是乾淨的。	請回報該內容的結構。
裝置的申請內容看起來很可信	裡面每個欄位都是用戶端自行宣告的，都可以偽造。系統刻意不放「已驗證」徽章。	請與你的資產清冊、目錄服務或 MDM 核對。
我只看得懂指紋雜湊	指紋來源一定顯示在它旁邊。	硬體推導的指紋，遠比從 MAC 清單推導的強。

13. 錯誤碼前綴

完整說明請參考坤安技術支援提供的錯誤碼對照文件。

前綴	範圍
`COMMON_`	權限、找不到資料、速率限制、伺服器錯誤
`AUTH_`	登入、工作階段、MFA、帳號啟用、認證伺服器
`USER_`	管理員管理
`MEMBER_`	成員管理
`DEVICE_`	裝置管理與註冊
`APP_`	應用程式管理
`NODE_`	Merak 節點管理
`ROLE_`	角色管理
`PERM_`	權限管理
`ORG_`	組織管理
`WORKFLOW_`	存取申請流程
`AUDIT_`	稽核
`TENANT_`	租戶管理
`LICENSE_`	授權管理
`AGENTLESS_`	Agentless 席次、綁定與佈建
`AGENT_`	Agent 平台（Agent 用戶端介面，不是主控台）
`CONN_`	連線管理（Agent 用戶端介面）

帳號啟用已經沒有自己的前綴。啟用連結被用掉與密碼被拒絕的代碼分別是 AUTH_024 與 AUTH_025；Agentless 的症狀見 §6，各代碼的意義與介面的處理方式則見錯誤碼對照文件。
若你拿到的代碼不在目錄裡，回報時請原樣引用——介面對不認得的代碼只會顯示通用訊息，所以那組代碼是唯一還留著的線索。

14. 什麼時候該回報

開票之前先蒐集以下資訊——前三項通常就足以在稽核日誌裡找到那個事件：

發生的時間，以及 你的時區設定。
你的帳號，以及牽涉到的資料。
稽核日誌上的 請求 ID（找得到的話）。
畫面上顯示的 完整訊息，以及錯誤碼（若有）。
是否可重現，以及其他管理員是否也會遇到。