การแก้ไขปัญหา

คู่มือการแก้ไขปัญหาเบื้องต้นที่พบบ่อยที่สุด โดยจัดแบ่งตามอาการแสดงที่คุณจะตรวจพบ ปัญหาของระบบเกตเวย์ส่วนใหญ่มักเกิดขึ้นจากนโยบายความปลอดภัยของ Gate ทำงานอย่างถูกต้อง ซึ่ง status code ที่ส่งกลับมาจะเป็นตัวบอกว่าเกิดขึ้นจาก Gate ใด

เอกสารนี้เหมาะสำหรับใคร

วิศวกรแพลตฟอร์ม (platform engineer) ที่ต้องการวิเคราะห์ตรวจสอบระบบติดตั้งปัจจุบัน สำหรับรายละเอียดความหมายของแต่ละ Gate ในมุมมองของนักพัฒนา โปรดดูคู่มือ เมื่อการร้องขอถูกบล็อก แทน

เกตเวย์ส่งกลับสถานะที่ไม่คาดคิด

คำร้องขอจะทำงานผ่านการคัดกรองความปลอดภัยของ Gate ต่าง ๆ ตามลำดับที่กำหนดไว้ ซึ่ง HTTP status code จะเป็นตัวระบุว่า Gate ใดเป็นผู้หยุดคำร้องขอนั้น ดูรายละเอียดกระบวนการทั้งหมดได้ที่ วงจรชีวิตของการร้องขอ

HTTP Status	Gate	สาเหตุที่น่าจะเป็นไปได้	แหล่งตรวจสอบข้อมูล
401 Unauthorized	Key-auth	ไม่มี API key, คีย์ไม่ถูกต้อง, คีย์หมดอายุ หรือคีย์ยังไม่ได้รับการปรับประสานสถานะ	ตรวจสอบว่าคีย์ดังกล่าวมีอยู่ใน console หรือไม่ และตรวจสอบการกำหนดส่วนนำหน้าคีย์รวมถึงค่ากำหนดของ header
403 Forbidden	Guardrails / tenant guard	ตรวจพบข้อมูลเข้าข่าย prompt-injection หรือข้อมูล PII หรือมีการใช้คีย์ MCP ไปเรียกเข้าถึงเซิร์ฟเวอร์ของโปรเจกต์อื่น	ตรวจสอบข้อมูลที่ ระบบป้องกัน (Guardrails) และตรวจสอบว่าเส้นทางของผู้เช่าตรงกับคีย์ที่ใช้หรือไม่
404 Not Found	Routing	ไม่มีการแมปชื่อโมเดลดังกล่าวไว้ในโปรเจกต์	ตรวจสอบที่หน้า การจัดเส้นทาง (Routing) เพื่อเพิ่มเส้นทางการแมปโมเดล
429 Too Many Requests	Budget & limits	ใช้งานเกินงบประมาณ USD หรือเกินขีดจำกัด token ต่อนาที	งบประมาณและขีดจำกัด
413 Payload Too Large	Gateway	ขนาดเนื้อหาของการร้องขอใหญ่เกินกว่าค่าสูงสุดของบัฟเฟอร์ โดยค่าเริ่มต้นคือ 10 MiB	ปรับเพิ่มค่า gateway.maxRequestBytes หากคุณจำเป็นต้องรับส่งข้อมูลขนาดใหญ่ประเภทมัลติโหมด
503 Service Unavailable	Upstream / reconcile	ไม่สามารถเชื่อมต่อไปยังผู้ให้บริการต้นทางได้ หรือเกตเวย์ยังไม่ได้รับการปรับประสานสถานะ	ตรวจสอบการเชื่อมต่อของผู้ให้บริการและสถานะความพร้อมของ control-plane ตามรายละเอียดด้านล่าง

คีย์ใหม่ งบประมาณ หรือผู้ให้บริการที่ตั้งค่าใหม่ยังไม่มีผลบังคับใช้

control plane จะทำการปรับประสานการเปลี่ยนแปลงต่าง ๆ ไปยัง gateway อย่างต่อเนื่อง ซึ่งโดยปกติจะมีผลภายในเวลาไม่กี่วินาที

• ตรวจสอบสถานะความพร้อมของ control plane:

  kubectl -n opsta-ai-gateway get pods -l app=control-plane
  kubectl -n opsta-ai-gateway logs deploy/control-plane | tail -50

• การปรับประสานสถานะครั้งแรกจะเริ่มทำเมื่อระบบเริ่มทำงานและคอยควบคุมความพร้อมทำงาน (gates readiness): หาก control-plane ยังไม่เปลี่ยนสถานะเป็น Ready ตัว gateway อาจจะยังคงให้บริการอ้างอิงตามโครงสร้างกำหนดค่าก่อนหน้า โปรดรอให้กระบวนการติดตั้งและเริ่มระบบเสร็จสิ้นสมบูรณ์ก่อน

• ระบบการปรับประสานสถานะจะทำงานตามรอบเวลาเพิ่มเติมเพื่อเป็นตัวช่วยสมานสถานะระบบอัตโนมัติ (self-healing): เพื่อให้ความคลาดเคลื่อนชั่วคราวได้รับการแก้ไขให้ถูกต้องเองโดยอัตโนมัติ

ปัญหาเกี่ยวกับใบรับรองความปลอดภัยหรือระบบ DNS

• เบราว์เซอร์แสดงสถานะใบรับรองไม่ปลอดภัยหรือไม่ถูกต้อง: ตรวจสอบว่าใบรับรองความปลอดภัยได้รับการออกเรียบร้อยแล้ว ในโหมด letsencrypt ให้ตรวจสอบที่ทรัพยากร Certificate หรือ Order ของ cert-manager หากการทดสอบด้วยวิธี DNS-01 เกิดค้าง มักมีสาเหตุมาจากโทเค็นผู้ให้บริการ DNS ไม่มีสิทธิ์ในการบริหารจัดการ dnsZone ที่ตั้งค่าไว้ ดูรายละเอียดเพิ่มเติมได้ที่ TLS และโดเมน
• ไม่สามารถแปลงชื่อโฮสต์ (hostname) ได้: ตรวจสอบว่าระเบียน DNS wildcard เช่น *.your-domain ชี้มายัง gateway เรียบร้อยแล้ว หรือในกรณีใช้งาน Cloudflare Tunnel ให้ตรวจสอบว่าได้กำหนดค่าโฮสต์สาธารณะไว้ถูกต้องแล้ว
• การออกใบรับรองถูกจำกัดอัตรา (rate-limit): อาจเกิดจากการที่คุณระบุค่าเป็น letsencrypt-prod ในระหว่างขั้นตอนทดลองติดตั้ง โปรดสลับมาใช้ค่า letsencrypt-staging ก่อนจนกว่าจะตั้งค่าได้ถูกต้อง จากนั้นจึงสลับกลับไปใช้ค่าเดิม

ไม่สามารถลงชื่อเข้าใช้งานหน้าจอ Console ได้

• ตรวจสอบว่า sso.emailDomain ตรงกับโดเมนอีเมลของผู้ใช้งานของคุณ และตรวจสอบว่าโหมด sso.mode ถูกตั้งค่าไว้อย่างเหมาะสมสำหรับสภาพแวดล้อมนั้น ๆ เช่น เลือกใช้ google หรือใช้ mock ภายในคลัสเตอร์สำหรับการทดสอบระบบ
• สำหรับระบบ SSO แบบแยกตามรายองค์กร โปรดตรวจสอบความถูกต้องในการเชื่อมต่อ IdP และการจับคู่คุณลักษณะ ดูรายละเอียดเพิ่มเติมได้ที่ SSO และ IdP
• ตรวจสอบให้แน่ใจว่าได้ระบุอีเมลผู้ดูแลระบบเริ่มต้น (bootstrap admin) เรียบร้อยแล้วในขั้นตอนติดตั้งระบบ มิฉะนั้นจะไม่มีใครสามารถเข้าถึงส่วนงานของผู้ดูแลระบบได้เลย

Pod ไม่สามารถเริ่มทำงานได้

• รันคำสั่ง kubectl -n opsta-ai-gateway describe pod <name> เพื่อตรวจสอบรายละเอียดข้อผิดพลาด เช่น ข้อผิดพลาดการดาวน์โหลดอิมเมจ (โปรดเช็คค่า imagePullSecrets และในกรณีของระบบปิดโปรดเช็คว่าได้ทำสำเนาอิมเมจเรียบร้อยแล้ว), ปัญหาการผูก persistent volume (โปรดเช็คค่า global.storageClass) หรือการทำงานบกพร่องของ readiness-probe
• สำหรับส่วนประกอบที่ขึ้นต่อกันกับฐานข้อมูลจะรอดำเนินการจนกว่าระบบ PostgreSQL จะพร้อมทำงาน โปรดตรวจสอบว่าคลัสเตอร์ CloudNativePG ทำงานอยู่ในสถานะสมบูรณ์ก่อนเป็นอันดับแรก

ข้อมูลวัดระยะไกลว่างเปล่าหรือแสดงข้อมูลข้ามผู้เช่า

• แดชบอร์ดแสดงข้อมูลจำกัดผิดขอบเขตผู้เช่า มักมีสาเหตุหลักมาจากการกำหนดปิดการทำงานของ control plane เนื่องจากระบบการแยกส่วนข้อมูลเป็นรายองค์กรจำเป็นต้องพึ่งพาการประมวลผลของส่วนนี้ ดูรายละเอียดเพิ่มเติมได้ที่ ระบบตรวจสอบสถานะการทำงานของแพลตฟอร์ม
• ไม่พบข้อมูลใด ๆ แสดงขึ้นมาเลย: ตรวจสอบว่าระบบเก็บข้อมูล (collector) มีการดึงข้อมูลจาก gateway หรือไม่ และตรวจสอบว่าคีย์ observability.enabled ถูกกำหนดค่าเป็น true เรียบร้อยแล้ว

หากปัญหายังคงไม่ได้รับการแก้ไข

โปรดรวบรวมไฟล์บันทึกการทำงานของ control plane, ไฟล์ล็อกของ gateway pod และผลลัพธ์ของคำสั่ง kubectl get pods -A ภายใน namespace ของแพลตฟอร์มทั้งหมดก่อนทำการยกระดับปัญหา และหากคุณมีข้อตกลงบริการดูแลระบบ Opsta Managed Service สามารถนำข้อมูลเหล่านี้แจ้งติดต่อฝ่ายสนับสนุนเทคนิคของเราได้ทันที

ขั้นตอนต่อไป

• วงจรชีวิตของการร้องขอ — กระบวนการคัดกรองของแต่ละ Gate ที่อยู่เบื้องหลัง status code ต่าง ๆ
• เอกสารอ้างอิงการกำหนดค่า — รายการคีย์กำหนดค่าทั้งหมดพร้อมระบุค่าเริ่มต้น