Vận hành, triển khai và xử lý sự cố

Loại chính: How-to
Phạm vi: k3s + ArgoCD (production kể từ cutover 2026-08-17)

Production (realvuxbaro.me) chạy trên k3s, quản lý bởi ArgoCD Application medical-chatbot-app (ai-service + web + observability) và medical-chatbot-data (PostgreSQL + Qdrant, tách release để prune/self-heal phía app không bao giờ đụng vào dữ liệu). Cả hai đặt syncPolicy.automated với selfHeal + prune — mọi merge vào master áp thẳng vào production, không có cổng duyệt thủ công. EC2 Docker Compose (52.0.158.61) không còn nhận deploy tự động; xem coordination/CLAUDE_PLAN_CICD_SAFETY_2026-08-18.md cho lý do và tình trạng hiện tại của máy đó.

Deploy

Hai loại thay đổi đi hai đường khác nhau:

Thay đổi code app (apps/ai-service/**, apps/web/**, packages/**, ingestion/data/verified/drug_entities.json) — merge vào master kích hoạt build-practice-images.yml: build + push image GHCR gắn tag theo commit SHA, sau đó .github/scripts/sync_practice_argocd.py ghi tag mới vào Application medical-chatbot-app và gọi sync. Workflow tự xác nhận readytochat.realvuxbaro.me đã lên bản mới trước khi báo thành công. ci.yml (ruff/pytest/lint/build) chạy độc lập trên cùng push — CI đỏ không tự động chặn deploy, hai workflow không phụ thuộc nhau.

Thay đổi chart/config (infra/helm/**) — helm-chart.yml lint + render + assert bất biến (Qwen, rerank, TLS, refute volumeClaimTemplates...) trên PR. Merge xong, ArgoCD tự phát hiện và sync — không qua CI nào chạy trên production thật, review ở PR là cổng chắn duy nhất.

Sau deploy (cả hai loại):

xác nhận Application Synced/Healthy và image tag/chart revision đúng;
gửi smoke case qua web, gồm answerable có citation và abstain;
quan sát error rate, latency, provider failure và decision distribution;
ghi lại thời điểm, SHA/revision và kết quả.

Rollback

Không có workflow rollback một-cú-bấm cho k3s hiện tại — đây là phần còn thiếu, xem coordination/CLAUDE_PLAN_CICD_SAFETY_2026-08-18.md mục PR C.

Image bị lỗi (phổ biến nhất): gọi trực tiếp ArgoCD API bằng logic của sync_practice_argocd.py nhưng với IMAGE_TAG=<sha tốt lần trước> — lấy SHA đó từ lần chạy build-practice-images.yml thành công gần nhất trước đó (gh run list --workflow=build-practice-images.yml). Không có nút bấm sẵn cho việc này; phải chạy script hoặc gọi API thủ công.

Chart/config bị lỗi: git revert commit gây lỗi trên master qua PR bình thường; ArgoCD selfHeal tự áp bản revert. Muốn ngay lập tức thay vì chờ chu kỳ poll, sync thủ công qua ArgoCD UI/CLI.

Sự cố nặng ở tầng cluster (k3s tự nó hỏng, không phải lỗi ở app): trong lúc Compose EC2 (52.0.158.61) còn tồn tại và chưa bị tắt, đường lui cuối cùng là trỏ A record realvuxbaro.me về IP đó (TTL 60s) — chỉ đúng khi Compose đang chạy bản tương thích với corpus/schema hiện tại, không phải đường lui mặc định. Một khi Compose bị dừng/xoá theo quyết định giữ 1 EC2, đường lui này không còn.

Không có cơ chế nào ở trên tự rollback Qdrant corpus hay database migration. Với corpus, dùng snapshot/migration riêng; không rollback dữ liệu phá huỷ khi chưa có backup.

Theo dấu request

Lấy trace_id, correlation_id, otel_trace_id từ response.
Tra rag_retrieval_trace để xem query, scope, intent, decision, reason, drug và citations.
Kiểm tra Prometheus request/stage duration, decision, provider failure và generation rejection.
Nếu OTel bật, tìm trace trong Tempo/Grafana để xác định stage chậm/lỗi.
Phân loại nguyên nhân: input/scope, corpus/retrieval, provider/model hoặc grounding.

/metrics có thể yêu cầu Authorization: Bearer <token> khi METRICS_TOKEN được đặt.

Observability stack

Local stack là Prometheus, OpenTelemetry Collector, Tempo và Grafana. OTel mặc định tắt. Observability failure không được làm service dừng trả lời; trace write failure phải xuất hiện trong metric/log. Production monitoring cần readiness và synthetic query vì health không chứng minh citation pipeline hoạt động end-to-end.

Troubleshooting

Triệu chứng	Kiểm tra đầu tiên	Không nên làm
service không ready	datastore, startup log, manifest/model/dimensions	bỏ qua manifest gate
`provider_unavailable` tăng	region, credential, quota, network, stage trace	báo “Dược thư không có dữ liệu”
retrieval score thấp	drug/section route, collection và manifest	hạ threshold không qua eval
grounding rejection tăng	evidence packet, model output, validator	hiển thị raw output
clarify lặp	history, field thiếu, circuit breaker	tăng loop vô hạn
citation sai trang	printed-page map, chunk payload, quarantine	thay printed page bằng physical page

Các reason grounding quan trọng gồm ungrounded_number, invalid_citation, uncited_claim, unsupported_claim và incomplete_answer. Giữ fail-closed và thêm regression test trước khi sửa prompt/parser/validator.

5.5 KiB Raw Blame History