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.