Sự cố thường gặp & checklist go-live
Đối tượng: sysadmin trực sự cố và nghiệm thu. Playbook đầy đủ: runbook §6 + Xử lý sự cố.
Xử lý nhanh theo dấu hiệu
| Dấu hiệu | Xử lý nhanh |
|---|---|
| Server crash khi agent đang chạy | Không mất việc: lease 30s hết hạn, boot recovery quét toàn bộ Space, task về idle + Activity system_recovery, worktree giữ nguyên → user bấm Run lại. Sweeper 15s thu hồi lease treo lúc vận hành |
| Wiki tắt âm thầm | 4 dấu hiệu: tab Wiki trống · INDEX.md "No wiki pages available" · Activity system_warning · log [preflight] ARKON_URL_*; test fetch('http://arkon_api:5055/health') từ server |
| Tạo Space 500 | 99% thiếu/cặp sai ARKON_SSO_SHARED_SECRET/SSO_SHARED_SECRET (provisioning 403) |
| Board mất realtime | ALLOWED_HOSTS thiếu hostname công khai → WS 403 (DevTools → Network → WS) |
Planner [LLM VCR ERROR] | đang replay — bật live + key + model |
| Nghi cấu hình OpenRouter | Preview trước Save; Diagnose 6 bước; no endpoints = model ngừng phục vụ → đổi model |
Server từ chối boot: WS_TOPICS_WITHOUT_PUBLIC_URL / PUBLIC_URL_NOT_IN_ALLOWED_HOSTS | AGENTBOARD_WS_TOPICS=1 mà thiếu AGENT_BOARD_PUBLIC_URL hoặc host không nằm trong ALLOWED_HOSTS (chủ ý, chỉ khi cờ bật) — đặt cả 2 biến cho khớp, hoặc tắt cờ để boot lại |
| Board load nhưng không live | Socket chưa vào room: No updates = server từ chối (không phải member Space); No updates yet = subscribe treo, kiểm tra log IDENTITY_PENDING (danh tính chưa giải được lúc upgrade — JWKS chậm hoặc thiếu TRUST_PROXY_IDENTITY) — theo chỉ báo header, không đoán |
Nguồn kẹt processing | Phân biệt cổng chờ người với lỗi thật: awaiting_approval / plan_ready là đỗ đúng, không phải kẹt — chỉ can thiệp khi quá 20s sau khi Arkon đã trạng thái cuối mà board chưa hội tụ (kiểm cờ trong container + log poller) |
Checklist go-live / sau deploy
-
[preflight]sạch sau restart; health 4 endpoint OK. - Pentest Human Gate → 403 cả 3 phát (header giả, service token, viewer).
- Tạo Space mẫu provisioning thành công (Department + 5 persona + Wiki Home).
- Planner live + Reviewer Agent chạy (không tự tắt vì thiếu key); Diagnose OpenRouter xanh khi dùng.
- Backup 3 stores chạy tay 1 lần thành công; rollback đọc lại 1 lần.
- Nghiệm thu trên DEV FULL-STACK/PRODUCTION theo MANUAL-TEST-PLAN (48 case, 9 test 🔴 chặn go-live gồm 3 pentest).