跳至主要内容

故障排除

本節提供常見問題的故障排除指南和解決方案，幫助您快速解決使用上的困難。

常見問題​

建置問題​

  • 請檢查 Node.js 版本（需要 18 以上版本）
  • 請確認已使用 npm install 安裝所有相依套件

部署問題​

  • 請確認 Kubernetes 叢集連線正常
  • 請檢查資源配額和限制設定

網路問題​

  • 請確認 O-RAN 介面連線正常
  • 請檢查防火牆和安全群組設定

詳細故障排除步驟​

Kubernetes 相關問題​

Pod 無法啟動​

當您遇到 Pod 啟動問題時，請依照以下步驟進行檢查：

# 檢查 Pod 狀態
kubectl get pods -n nephio-agents

# 查看 Pod 詳細資訊
kubectl describe pod <pod-name> -n nephio-agents

# 檢查容器 logs
kubectl logs <pod-name> -n nephio-agents -c <container-name>

服務無法存取​

如果服務無法正常存取，請嘗試以下診斷步驟：

# 檢查服務狀態
kubectl get svc -n nephio-agents

# 檢查端點
kubectl get endpoints -n nephio-agents

# 測試服務連線
kubectl port-forward svc/<service-name> 8080:8080

Agent 相關問題​

Agent 無回應​

如果 Agent 沒有回應，請嘗試以下解決步驟：

# 重新啟動 Agent
kubectl rollout restart deployment/<agent-deployment> -n nephio-agents

# 檢查 Agent 配置
kubectl get configmap agent-config -n nephio-agents -o yaml

# 檢查 Agent 健康狀態
kubectl get pods -n nephio-agents -l app=<agent-name>

配置問題​

當遇到配置相關問題時：

# 驗證配置檔案
kubectl describe configmap agent-config -n nephio-agents

# 檢查掛載的設定
kubectl exec -it <pod-name> -n nephio-agents -- cat /etc/config/agent_config.yaml

O-RAN 整合問題​

介面連線失敗​

當 O-RAN 介面連線發生問題時，請檢查：

  • 請檢查網路策略設定
  • 請確認 O-RAN 元件狀態
  • 請確認介面設定正確

資料流問題​

如果資料流有異常，請執行以下檢查：

  • 請檢查監控指標
  • 請確認資料格式正確
  • 請確認端點設定無誤

效能問題​

記憶體使用過高​

當系統記憶體使用率過高時：

# 檢查資源使用情況
kubectl top pods -n nephio-agents

# 調整記憶體限制
kubectl patch deployment <agent-name> -n nephio-agents \
  --patch '{"spec":{"template":{"spec":{"containers":[{"name":"agent","resources":{"limits":{"memory":"2Gi"}}}]}}}}'

CPU 使用率過高​

當 CPU 使用率異常時：

# 檢查 CPU 使用情況
kubectl top nodes

# 擴展 Agent 副本數量
kubectl scale deployment <agent-name> --replicas=3 -n nephio-agents

監控和 Logs​

查看 Agent Logs​

查看 Agent 運作狀況：

# 即時查看 logs
kubectl logs -f deployment/<agent-name> -n nephio-agents

# 查看特定時間範圍的 logs
kubectl logs deployment/<agent-name> -n nephio-agents --since=1h

# 查看所有 Agent 的 logs
kubectl logs -n nephio-agents -l app=claude-agent --tail=100

監控指標​

檢查系統監控數據：

# 檢查 Prometheus 指標
kubectl port-forward svc/prometheus 9090:9090 -n nephio-agents

# 存取 Grafana 儀表板
kubectl port-forward svc/grafana 3000:3000 -n nephio-agents

安全性問題​

RBAC 權限問題​

當遇到權限相關問題時：

# 檢查服務帳戶權限
kubectl auth can-i --list --as=system:serviceaccount:nephio-agents:agent-service-account

# 檢查 RBAC 設定
kubectl get clusterrole,clusterrolebinding -o wide | grep agent

TLS 憑證問題​

當憑證有問題時：

# 檢查憑證有效性
kubectl get secret tls-secret -n nephio-agents -o yaml

# 更新憑證
kubectl delete secret tls-secret -n nephio-agents
kubectl create secret tls tls-secret --cert=path/to/cert.pem --key=path/to/key.pem -n nephio-agents

資料問題​

資料庫連線問題​

當資料庫連線有問題時：

# 檢查資料庫 Pod 狀態
kubectl get pods -n nephio-agents -l app=database

# 測試資料庫連線
kubectl exec -it <agent-pod> -n nephio-agents -- nc -zv <db-host> <db-port>

資料同步問題​

如果資料同步出現異常：

  • 請檢查網路延遲狀況
  • 請確認資料格式正確
  • 請確認同步設定無誤

診斷工具​

內建診斷指令​

使用系統提供的診斷工具：

# 執行健康檢查
make health-check

# 執行完整診斷
make diagnose

# 產生診斷報告
make diagnostic-report

手動診斷​

手動檢查系統狀態：

# 檢查叢集狀態
kubectl cluster-info

# 檢查節點狀態
kubectl get nodes -o wide

# 檢查系統事件
kubectl get events --sort-by='.lastTimestamp' -A

獲得協助​

如果您遇到此處未涵蓋的問題，請依照以下步驟尋求協助：

  1. 檢查 Logs：kubectl logs -n nephio-agents deployment/orchestrator-agent
  2. 查看故障排除指南：瀏覽相關的故障排除部分
  3. 執行診斷：make diagnose
  4. 檢查相容性：查看相容性矩陣
  5. GitHub 問題回報：在 GitHub Issues 回報問題
  6. 社群支援：加入 Nephio 社群

常見錯誤碼​

HTTP 錯誤碼​

  • 400 Bad Request - 請求格式有誤
  • 401 Unauthorized - 認證失敗
  • 403 Forbidden - 權限不足
  • 404 Not Found - 找不到資源
  • 500 Internal Server Error - 伺服器內部錯誤

系統錯誤碼​

  • AGT001 - Agent 啟動失敗
  • AGT002 - 配置載入錯誤
  • AGT003 - O-RAN 介面連線失敗
  • AGT004 - 資料同步錯誤

預防措施​

定期維護​

為了避免問題發生，建議您：

  • 定期更新 Agent 版本
  • 持續監控資源使用情況
  • 定期備份重要配置

最佳實踐​

建議遵循以下最佳實踐：

  • 使用適當的資源限制設定
  • 配置合適的監控警報
  • 實施完善的安全策略

需要更多協助嗎？歡迎查看我們的 GitHub 討論區 或 聯絡技術支援。

最後更新：2025年8月