Pemecahan Masalah Kegagalan Umum
Tujuan: memberikan panduan ketat gejala-penyebab-perbaikan untuk kegagalan integrasi yang umum.
Matriks Kegagalan
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
POST /query mengembalikan 401 (Missing bearer token) | Header Authorization tidak ada | Kirim Authorization: Bearer <token> dari alur bootstrap auth |
POST /query mengembalikan 401 (Invalid token) | JWT kedaluwarsa/tidak valid atau issuer/audience salah | Bootstrap ulang token dan konfirmasi konfigurasi auth (AUTH_ISSUER, AUTH_AUDIENCE, URL JWKS) |
POST /query mengembalikan 400 (start_ts must be <= end_ts) | Rentang waktu pada body tidak valid | Pastikan start_ts kurang dari atau sama dengan end_ts |
POST /log mengembalikan 400/error validasi | Body request bukan objek JSON valid | Selalu kirim body JSON (minimal {}) |
Tulis channel privat mengembalikan 401 | Tidak ada token untuk channel yang dilindungi | Kirim token Bearer pemilik yang valid |
Baca/tulis channel privat mengembalikan 404 | Akun tidak cocok dengan pemilik channel | Gunakan token dengan claim JWT acc yang sesuai |
Upgrade WebSocket privat mengembalikan 401 | Token hilang/tidak valid saat upgrade | Sertakan header Authorization yang valid saat upgrade |
Upgrade WebSocket privat mengembalikan 404 | acc token tidak cocok dengan pemilik channel | Sambungkan ulang dengan token akun pemilik |
POST /query mengembalikan files kosong | Tidak ada file dalam rentang atau filter terlalu sempit | Perluas rentang/filter dan verifikasi worker uploader/kompresi berjalan |
Endpoint /query hilang dari OpenAPI | Integrasi database dinonaktifkan | Set DATABASE_URL dan restart service untuk mengaktifkan rute query |
Diagnostik Cepat
JSONLOG_BASE_URL="http://localhost:3002"
curl -sS "${JSONLOG_BASE_URL}/health"
curl -sS "${JSONLOG_BASE_URL}/stats"
curl -sS "${JSONLOG_BASE_URL}/openapi.json" | jq '.paths | keys'Diagnostik Auth Dengan Script
cd jsonlog
set -a && source .env && set +a
npm run test:auth:smokeAlur smoke ini memvalidasi perilaku tanpa auth, auth tidak valid, dan auth valid untuk /query.