إنتقل إلى المحتوى الرئيسي

استكشاف الأخطاء وإصلاحها

استكشاف الأخطاء وإصلاحها

تشخيص المشكلات الشائعة لوكيل DuoKey AWS XKS Proxy وحلّها

ينطبق على:
AWS XKS ProxyConnectivity IssuesError Resolution

قائمة التحقق التشخيصية السريعة​

المتطلبات المسبقة

  • التحقق من حالة اتصال مخزن المفاتيح الخارجي
  • استجابة نقطة نهاية سلامة وكيل XKS
  • تأكيد الاتصال الشبكي من AWS إلى الوكيل
  • شهادات TLS صالحة وغير منتهية الصلاحية
  • بيانات اعتماد مصادقة SigV4 صحيحة
  • وجود المفتاح الخارجي في مدير المفاتيح
  • إمكانية الوصول إلى مدير المفاتيح الخارجي من الوكيل
  • مقاييس CloudWatch الحديثة تُظهر نشاطًا
  • سجلّات الوكيل تُظهر طلبات حديثة

المشكلات الشائعة​

1. XksProxyUriUnreachableException​

تحذير
الخطأ:XksProxyUriUnreachableException: The XKS proxy URI endpoint is unreachable

الأسباب المحتملة:

  • وكيل XKS متوقّف أو غير قيد التشغيل
  • مشكلات في الاتصال الشبكي
  • جدار الحماية يحظر نطاقات عناوين IP الخاصة بـ AWS KMS
  • فشل دقة DNS
  • مشكلات في شهادة TLS
Diagnose ConnectivityBASH
# 1. Check if proxy is running
curl -k https://your-proxy-address.com/health

# 2. Check DNS resolution
nslookup your-proxy-address.com
dig your-proxy-address.com

# 3. Check TLS certificate
echo | openssl s_client -connect your-proxy-address.com:443 -servername your-proxy-address.com

# 4. Check proxy logs
tail -f /var/log/duokey-xks-proxy/proxy.log

2. XksProxyInvalidResponseException​

تحذير
الخطأ:XksProxyInvalidResponseException: The XKS proxy returned an invalid response

الأسباب المحتملة:

  • الوكيل لا يتوافق مع مواصفات واجهة برمجة تطبيقات وكيل AWS XKS
  • مشكلات في تنسيق JSON في استجابات الوكيل
  • رموز حالة HTTP غير صحيحة
  • حقول استجابة مطلوبة مفقودة

3. XksProxyIncorrectAuthenticationCredentialException​

تحذير
الخطأ:XksProxyIncorrectAuthenticationCredentialException: Authentication credential is incorrect

الأسباب المحتملة:

  • عدم تطابق بيانات اعتماد SigV4 بين AWS والوكيل
  • انتهاء صلاحية بيانات الاعتماد أو تدويرها
  • انحراف الساعة بين AWS والوكيل

4. XksKeyNotFoundException​

تحذير
الخطأ:XksKeyNotFoundException: External key not found

الأسباب المحتملة:

  • عدم تطابق معرّف المفتاح (حساس لحالة الأحرف)
  • حذف المفتاح من مدير المفاتيح الخارجي
  • تكوين واجهة خلفية خاطئة للمفاتيح
  • مشكلة في توجيه DuoKey Cockpit

5. مشكلات زمن الاستجابة المرتفع​

الأعراض: عمليات تستغرق أكثر من 100 مللي ثانية لإتمامها

الأسباب المحتملة:

  • زمن استجابة شبكي بين AWS والوكيل
  • مشكلات في أداء مدير المفاتيح الخارجي
  • قيود موارد الوكيل
  • المسافة الجغرافية

6. مشكلات شهادة TLS​

الأعراض: فشل مصافحة TLS أو تحذيرات الشهادة

الأسباب المحتملة:

  • شهادات منتهية الصلاحية
  • سلسلة الشهادات غير مكتملة
  • شهادة خاطئة للنطاق
  • شهادة غير موثوقة من قبل AWS

7. انقطاع اتصال مخزن المفاتيح الخارجي​

الأعراض: يظهر مخزن المفاتيح الخارجي على أنه غير متصل

استكشاف الأخطاء المتقدم وإصلاحها​

وضع التصحيح​

Enable Debug LoggingYAML
# config.yml
logging:
level: debug
components:
  authentication: debug
  encryption: debug
  routing: debug
  backend: debug
Review Debug LogsBASH
systemctl restart duokey-xks-proxy
tail -f /var/log/duokey-xks-proxy/proxy.log | jq .

التقاط الحزم​

Capture Network TrafficBASH
# Capture HTTPS traffic to/from proxy
tcpdump -i any -s 0 -w /tmp/xks-traffic.pcap port 443

# Analyze with Wireshark
wireshark /tmp/xks-traffic.pcap

تصحيح فحص السلامة​

Detailed Health CheckBASH
# Detailed health check
curl -v https://your-proxy:443/kms/xks/v1/health \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

# Expected response:
# {
# "status": "OK",
# "version": "1.0",
# "keyManagers": [
# {
# "name": "vault-primary",
# "status": "ACTIVE"
# }
# ]
# }

مرجع رموز الأخطاء​

رمز الخطأالوصفالأسباب الشائعة
XksProxyUriUnreachableExceptionتعذّر الوصول إلى الوكيلالشبكة، جدار الحماية، توقّف الوكيل
XksProxyInvalidResponseExceptionاستجابة وكيل غير صالحةالتوافق مع واجهة برمجة التطبيقات، أخطاء برمجية
XksProxyIncorrectAuthenticationCredentialExceptionفشل المصادقةبيانات اعتماد خاطئة، انحراف الساعة
XksKeyNotFoundExceptionلم يُعثر على المفتاح الخارجيمعرّف مفتاح خاطئ، حذف المفتاح
XksKeyInvalidConfigurationExceptionتكوين المفتاح غير صالحنوع مفتاح خاطئ، مفتاح معطّل
XksProxyInvalidConfigurationExceptionتكوين الوكيل غير صالحعنوان URL خاطئ، إعدادات غير صالحة

الحصول على المساعدة​

قبل التواصل مع الدعم​

Gather Diagnostic InformationBASH
# 1. System information
uname -a
cat /etc/os-release

# 2. Proxy version and status
/usr/local/bin/duokey-xks-proxy --version
systemctl status duokey-xks-proxy

# 3. Recent logs
tail -100 /var/log/duokey-xks-proxy/proxy.log > proxy-logs.txt

# 4. External key store status
aws kms describe-custom-key-stores \
  --custom-key-store-id cks-xxxxx > keystore-status.json

# 5. CloudWatch metrics
aws cloudwatch get-metric-statistics \
  --namespace AWS/KMS \
  --metric-name XksProxyLatency \
  --dimensions Name=CustomKeyStoreId,Value=cks-xxxxx \
  --start-time $(date -u -d '1 hour ago' '+%Y-%m-%dT%H:%M:%S') \
  --end-time $(date -u '+%Y-%m-%dT%H:%M:%S') \
  --period 300 \
  --statistics Average,Maximum > cloudwatch-metrics.json

# 6. Network test results
curl -v https://your-proxy:443/health > network-test.txt 2>&1

معلومات الاتصال​

الموردجهة الاتصال
دعم DuoKey[email protected]
دعم AWSافتح حالة في وحدة تحكم AWS
المجتمعمناقشات GitHub

التدابير الوقائية​

فحوصات السلامة المنتظمة​

Automated Health Check ScriptBASH
#!/bin/bash
# /usr/local/bin/xks-health-check.sh

PROXY_URL="https://your-proxy:443/health"
ALERT_EMAIL="[email protected]"

RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $PROXY_URL)

if [ "$RESPONSE" != "200" ]; then
  echo "XKS Proxy health check failed: HTTP $RESPONSE" | \
      mail -s "XKS Proxy Alert" $ALERT_EMAIL
  exit 1
fi

exit 0
Schedule Health CheckBASH
# Add to cron
*/5 * * * * /usr/local/bin/xks-health-check.sh

جدول الصيانة المنتظمة​

التكرارالمهمة
أسبوعيًامراجعة السجلّات والمقاييس
شهريًااختبار إجراءات التعافي من الكوارث
ربع سنويتدوير بيانات الاعتماد
سنويًاتجديد شهادات TLS

الخطوات التالية​

إدارة المفاتيح

إدارة مفاتيح KMS الخاصة بك

المراقبة

إعداد مراقبة شاملة

البدء

العودة إلى دليل الإعداد

انظر أيضًا