疑難排解

常見問題

Error: agent 'demo-1' not found

• 使用 clish agent show 驗證代理名稱
• 檢查代理程式是否成功建立

• 使用clish agent onboarding-token issue生成新令牌
• 確保代理使用正確的憑證進行連接

憑證驗證問題

Error: The agent does not respond to credential validation within timeout period

• 代理程式無法連接到 SVM（網路問題、防火牆阻擋）
• 代理程式過載或無回應
• SVM 已關閉或無法連接

1. 透過管理服務 CLI 重新啟動代理並發出新的啟動令牌：
   clish agent re-onboard --instance <agent-name>
2. 在 Ontap 代理安裝資料夾中修改 config.yaml 檔案（預設：C:\Program Files\v1fs-ontap-agent\）
3. 移除 device_token 鍵及其值
4. 新增 onboarding_token 鍵值並使用新發行的權杖：
   onboarding_token: eyJh......
5. 啟動 Ontap 代理服務 (v1fs-ontap-agent)
6. 使用管理服務 CLI 驗證代理連線狀態
7. 代理成功連接後，請使用以下方式重新輸入憑證：

   clish agent credential modify --instance
       <agent-name>

8. 檢查代理日誌以查找 SVM 連接錯誤：
9. 從代理程式測試到 SVM 的網路連線：
   • 驗證從代理程序 pod 可達到 SVM 管理 LIF
   • 檢查代理與 SVM 之間的防火牆規則

注意 當驗證失敗或超時時，憑證會自動回滾到先前的可用版本，以防止服務中斷。

SVM 拒絕了憑證

Error: Agent rejected credentials: Failed to connect to SVM: authentication failed

• 使用者名稱或密碼無效
• SVM 使用者帳號已鎖定、過期或停用
• 使用者缺乏對 SVM 的必要權限
• ONTAP API 無法存取

1. 驗證憑證是否正確：
   • 檢查使用者名稱的拼寫和大小寫敏感性
   • 確保密碼與 SVM 使用者帳號相符
   • 確認您使用的是正確的 SVM 管理憑證
2. 檢查 SVM 使用者帳號狀態（在 ONTAP CLI 上）：
   security login show -user-or-group-name <username> -vserver <svm-name>
   尋找：
   • 帳戶鎖定狀態
   • 密碼到期
   • 驗證方法（應為「密碼」或「網域」）
3. 驗證使用者是否具有適當的權限：
   • 用戶應至少擁有 readonly 或 vsadmin 角色以使用 SVM
   • 檢查角色指派：
     security login show -vserver <svm-name> security login role show -vserver <svm-name> -role <role-name>
4. 檢查 SVM API 存取：
   # On ONTAP CLI vserver services web show -vserver <svm-name>
   確保 ONTAPI 和 REST API 已啟動
5. 檢查 ONTAP 審計日誌中的驗證失敗嘗試：

   # On ONTAP CLI 
   event log show -severity error -message-name *authentication*

代理狀態無效，無法更新憑證

Error: agent 'demo-1' is in state 'onboarding', cannot set credentials

• 代理必須處於credential-required或running狀態才能接受憑證更新
• 代理可能卡在過渡狀態中

1. 檢查目前的代理狀態：
   clish agent show --instance <agent-name>
   注意 State 和 Connected 欄位
2. 如果代理程式卡在onboarding狀態：
   • 確認代理已完成初始上線流程
   • 檢查代理程式是否成功使用啟動代碼連接
3. 如果代理處於init狀態：
   • 代理需要先完成初始連接
   • 確保在代理配置中正確配置入門令牌
   • 使用有效的啟動代碼重新啟動代理程式
4. 如果代理處於disconnected狀態：
   • 驗證代理程式 Pod 與管理服務之間的網路連線
   • 檢查管理服務日誌以查找連接錯誤

代理未通過 WebSocket 連接

Error: agent 'demo-1' is not connected via WebSocket, cannot validate credentials

• 憑證驗證需要一個活躍的 WebSocket 連線來傳送憑證並接收驗證結果
• 代理服務可能已停止、正在重新啟動或有網路問題

1. 確認代理服務正在運行。
2. 檢查用戶端連線狀態：
   clish agent show --instance <agent-name>
   尋找Connected: disconnected
3. 檢查代理日誌中的 WebSocket 連接錯誤
4. 檢查網路連線：
   • 驗證代理程式是否能夠連接管理服務 WebSocket 端點
   • 檢查是否有網路政策或防火牆阻擋 WebSocket 連線
5. 等待代理重新連接：
   • 代理在斷線時會自動嘗試重新連接
   • 監控連線狀態
6. 如果代理未重新連接，請檢查裝置令牌是否已過期（可能需要clish agent re-onboard）

偵錯的實用指令

clish agent show

clish agent show --instance <agent-name>

clish scanner scan-policy show