Xử lý sự cố & câu hỏi thường gặp
Đối tượng: mọi role. Mỗi mục ghi triệu chứng → nguyên nhân → xử lý, kèm khi nào tự làm được và khi nào gọi owner/admin/sysadmin.
1. Quyền và truy cập
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
| 403 ở mọi thứ | Chưa có membership; phân quyền fail-closed | Nhờ owner cấp quyền hoặc dùng AGENTBOARD_BOOTSTRAP_OWNERS; dev local bật AGENTBOARD_DEV_IDENTITY=1 |
Là member nhưng Approve bị chặn | Đúng thiết kế: approve cần admin + human | Nhờ cấp admin nếu bạn thực sự là người duyệt |
| Script CI dùng service token approve → 403 | Đúng thiết kế, không có bypass (scope gate:approve không tồn tại; token phân giải về system) | Chuyển bước approve cho người thật |
| Không xoá được owner cuối (409) | Chống tự khoá | Cấp owner cho người khác trước rồi xoá |
| Pentest header giả approve không 403 | Sự cố bảo mật P0 | Dừng nghiệm thu — sysadmin kiểm tra JWT verify + nginx strip header + loopback |
Chi tiết: Vì sao Human Gate không bypass được.
2. Agent và task
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
| Task tạo được nhưng không chạy | Không có agent CLI nào trên PATH | GET /api/agents kiểm tra; production build từ Dockerfile.agents; liên hệ sysadmin |
| Agent chạy nhưng kết quả tệ | description chung chung, thiếu AC; .board/wiki/INDEX.md rỗng | Viết lại mô tả + AC cụ thể + non-goals; nạp tài liệu vào Wiki trước |
| Agent sửa file ngoài phạm vi | Thiếu giới hạn | Đặt ALLOWED_REPO_ROOTS (sysadmin); viết non-goals trong mô tả |
| Agent treo / lặp vô nghĩa / đi sai hướng | Prompt thiếu, yêu cầu đổi giữa chừng | Khi agent treo: Follow-up → Stop+sửa mô tả → Request Changes → cleanup-worktree → chờ lease 30s |
Task quá 3 vòng rework → needs-human | Chống lặp vô tận | Làm tay trong worktree, commit, approve lại |
git merge báo "Committer identity unknown" | Container thiếu git identity system | docker exec agentjira_server git config --system user.email agentjira@localhost + user.name AgentJira |
| Server crash khi agent chạy — mất việc? | Không mất | Lease 30s hết hạn, boot recovery về idle + Activity system_recovery, worktree giữ nguyên → bấm Run lại |
| Xoá task rồi lấy lại? | Không | Dùng Archive thay Delete |
3. Planner (AI lập kế hoạch)
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
[LLM VCR ERROR] Cassette cache miss | Đang mode replay (mặc định) | Sysadmin đặt AGENTBOARD_LLM_MODE=live + key + model |
| Apply Plan bị từ chối "cycle detected" | dependsOn tạo vòng A→B→A | Sửa trong PlanDraftEditor rồi apply lại |
| Plan quá chung chung | Không research codebase, Wiki trống | Bật research; nạp kiến trúc vào Wiki trước |
| Model OpenRouter không dùng được cho Planner | Không hỗ trợ structured outputs | Chạy Diagnose #3; preflight cảnh báo LLM_OPENROUTER_MODEL_UNVERIFIED |
4. Wiki và tri thức
Đọc kỹ — lỗi ở đây thường CHẾT LẶNG
Suy biến mềm Arkon: khi Arkon down hoặc Space không link, hệ thống không báo 500 mà bỏ qua Wiki, Board vẫn 200 OK. Phát hiện bằng 4 dấu hiệu:
- Tab Wiki trống trong khi biết Department có trang.
.board/wiki/INDEX.mdchứa "No wiki pages available for this space".- Activity task có
system_warning. - Log server có
[preflight] ARKON_URL_*.
Kiểm tra nhanh:
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))"
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
| Tab Wiki trống (đủ 4 dấu hiệu trên) | Arkon down / sai ARKON_API_URL / thiếu link | Sysadmin kiểm tra health, env, link Space↔Department |
| Semantic search không kết quả | Chưa nhập Embedding key (riêng, khác LLM key) ở Settings → Model Catalog | Nhập key, thử lại |
| Đổi model embedding rồi search hỏng | Vector khác số chiều | Đừng đổi sau khi đã nạp; muốn đổi: Online Re-embed Migration + Diagnose #6 trước |
Nguồn upload báo error | Embed thất bại — trang Wiki đã ghi, chỉ thiếu vector | Dán key embedding thật → Retry (chỉ chạy lại commit, idempotent) |
| Draft conflict khi approve | Hai người sửa cùng trang | Vào Wiki Rebase gỡ conflict rồi merge lại |
5. Realtime, mạng, dữ liệu
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
| Board không tự cập nhật | WebSocket 403 | Hostname công khai phải trong ALLOWED_HOSTS; DevTools → Network → WS |
| HTTP 429 | Rate limit 3000 req/phút/IP | Tăng RATE_LIMIT_MAX nếu thật cần |
| Backup ở đâu | 3 stores độc lập | agentjira_db + arkon_postgres + arkon_minio — lệnh ở runbook §5 |
6. Giới hạn đã biết Phase 1 (không phải bug)
| Giới hạn | Hiện trạng | Cách xoay |
|---|---|---|
| Bơm Wiki vào worktree (deadline 8s) | đã nối | — |
wikiProposals → draft Arkon | đã nối (sau complete) | — |
| Reviewer Agent độc lập | đã nối (auto cần LLM thật) | Người duyệt cuối ở human-gate |
Repair loop result.json (2 vòng, 5m/vòng) | đã nối | Fallback regex nếu vẫn sai |
| MCP write trực tiếp (K5) | chưa triển khai (đã hoãn) | dùng đường file |
@mention subtask, theo dõi chi phí token | chưa có | tạo task con tay; xem dashboard provider |
withRepoLock 1 process | không chống git tay / nhiều instance | không git tay trong repo gốc khi agent đang chạy |
| Test Arkon còn mỏng | kiểm tay luồng quan trọng | theo MANUAL-TEST-PLAN |
Chi tiết: Giới hạn đã biết Phase 1.
7. Khi nào gọi ai
| Gặp | Gọi |
|---|---|
| Cần quyền, đổi role, mất admin Space | Space owner |
| Diff chưa đạt, rework/merge conflict sâu | Approver |
| Deploy, secret, JWT/proxy, backup, Arkon down, thiếu key, agent CLI thiếu | SysAdmin |
| Draft Wiki/skill cần duyệt, plan MRP lạ, embedding/search hỏng | Knowledge manager |