跳至主要内容

常見問題與故障排除

快速診斷流程​

常見問題表格​

問題症狀可能原因解決方式
UI 無法開啟(connection refused)port-forward 未執行或已中斷重新執行 kubectl port-forward -n sentinel-system svc/sentinel 8080:80
登入失敗(帳號密碼錯誤)預設帳號已被修改或遺忘重置 users.json(見下方步驟)
Policy 套用後無效模式為 Monitoring(非 Protect)在 Tracing Policy 列表切換該 Policy 的 Mode,或以頁面頂部的 Global Protect Mode banner 全域切換為 ON
Behavior Discovery 無資料Tetragon Agent 未正常運作確認 tetragon DaemonSet 狀態(見下方步驟)
Security Events 頁面空白TracingPolicy 尚未建立,或 Tetragon 事件串流中斷先到「Cluster → Event Sources」確認各節點 Ingestion 為 Connected(Stream Down 時檢查 Tetragon gRPC 綁定與網路),再確認已建立 TracingPolicy
Vulnerabilities 頁面顯示 Trivy Operator was not found in this cluster.尚未安裝 Trivy Operator(只套用 deploy/sentinel.yaml 不會安裝)依 安裝 Trivy Operator 安裝
Vulnerabilities 頁面顯示 Sentinel is not permitted to read vulnerability reports.從 v0.59 以前升級,ClusterRole 缺少 vulnerabilityreports 讀取規則重新套用 deploy/sentinel.yaml
工作負載一直停在 partial 或 Not scannedTrivy Operator 以舊版 values 安裝,沒有共用的 Trivy server,掃描容器互搶快取鎖(cache may be in use by another process);或掃描逾時以目前的 deploy/trivy-operator-values.yaml 執行 helm upgrade,再 rollout restart deployment/trivy-operator(見 安裝 Trivy Operator)
剛掃描完的結果沒有出現掃描報告摘要快取 5 分鐘在 Vulnerabilities 頁面按 Refresh
Registry 掃描以權限錯誤失敗從 v0.61 以前升級,缺少 sentinel-system 內的 Role sentinel-registry-scan重新套用 deploy/sentinel.yaml
Registry 的 Image 掃描出現 context deadline exceededv0.63.2(含)以前單一 Image 掃描沿用 Trivy 預設的 5 分鐘上限升級至 v0.63.3+(上限為 13 分鐘)
quay.io 使用萬用字元 Filter(如 myorg/*)且設定帳密時出現 the registry's token service refused the credentials (HTTP 400)v0.63.1(含)以前的已知問題升級至 v0.63.2+
YAML 編輯器沒有顯示v0.53.0 至 v0.59.4 的編輯器從公開 CDN 載入,被 Content-Security-Policy 擋下(離線叢集也無法載入)升級至 v0.59.5+,編輯器已內建於 Image
Pod 啟動失敗(CrashLoopBackOff)ServiceAccount 無法連線叢集或 RBAC 設定錯誤確認 ServiceAccount 與 ClusterRoleBinding 設定是否正確

重置管理員密碼​

忘記管理員密碼時,依部署方式處理:

未設定永久儲存(預設 emptyDir):帳號資料跟著 Pod 走,直接重啟即會重建預設帳號:

kubectl -n sentinel-system rollout restart deployment sentinel

已掛載 PV / PVC:需刪除儲存卷上的 users.json 再重啟。K8s Sentinel 容器是精簡的單一執行檔映像且以唯讀根檔案系統執行,不一定能以 kubectl exec 進入操作;最可靠的方式是建立一個臨時 Pod 掛載同一個 PVC 來刪檔:

kubectl -n sentinel-system run cleanup --rm -it --restart=Never --image=busybox --overrides='{"spec":{"containers":[{"name":"cleanup","image":"busybox","command":["rm","/data/users.json"],"volumeMounts":[{"name":"data","mountPath":"/data"}]}],"volumes":[{"name":"data","persistentVolumeClaim":{"claimName":"sentinel-data"}}]}}'

kubectl -n sentinel-system rollout restart deployment sentinel

重啟完成後以預設帳號 admin / admin 登入,系統會依首次登入流程強制要求設定新密碼(見登入 K8s Sentinel)。

確認 Tetragon Agent 狀態​

kubectl get pods -n kube-system -l app.kubernetes.io/name=tetragon
kubectl logs -n kube-system -l app.kubernetes.io/name=tetragon --tail=50

確認所有 tetragon Pod 均處於 Running 狀態,且 log 中無 ERROR 或 FATAL 訊息。若 DaemonSet Pod 數量不足(未覆蓋所有節點),請檢查節點 taints 與 tolerations 設定。

查看 K8s Sentinel 日誌​

# 查看最近 100 行日誌
kubectl logs -n sentinel-system deployment/sentinel --tail=100

# 即時追蹤日誌輸出
kubectl logs -n sentinel-system deployment/sentinel -f

日誌中可查看 API 請求記錄、JWT 驗證錯誤、TracingPolicy 操作結果等資訊,有助於快速定位問題根源。

提示

排查問題時,建議先執行以下指令確認 sentinel-system namespace 中所有資源的整體狀態:

kubectl get all -n sentinel-system

確認 Deployment、ReplicaSet、Pod、Service 均處於正常狀態後,再針對個別元件深入排查。