Xử lý sự cố và checklist go-live
Trang này tổng hợp cách xử lý nhanh các sự cố thường gặp theo dấu hiệu và checklist nghiệm thu trước go-live. Đọc khi bạn trực sự cố hoặc chuẩn bị deploy production.
Đố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
# 1. Preflight sạch + health 4 mặt
docker compose -f docker-compose.prod.yml logs --tail=50 agentjira_server | grep -i preflight
curl -fsS http://127.0.0.1:8080/api/health
curl -fsS http://127.0.0.1:5055/health
# 2. Cờ tới được container chưa (đừng tin file .env)
docker exec agentjira_server printenv | grep AGENTBOARD_
curl -s localhost:8081/api/features
# 3. Wiki sống thật (không suy biến mềm)
docker exec agentjira_server node -e "fetch('http://arkon_api:5055/health').then(r=>console.log(r.status)).catch(e=>console.log('DOWN',e.message))"
-
[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 (77 case, 16 test 🔴 chặn go-live gồm 3 pentest).
Gặp lỗi? Xem Xử lý sự cố.
Đi tiếp: Vận hành hằng ngày · Model Catalog & OpenRouter · Xử lý sự cố · Vận hành & backup