duocthu/docs/operations.md

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) đã stop từ 2026-08-18, không còn nhận deploy tự động và không còn là đường lui sống; xem mục Rollback bên dưới cho cách khởi động lại nếu cần.

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):

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

Rollback

Image bị lỗi (phổ biến nhất): gh workflow run rollback-k3s.yml -f target_sha=<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). Workflow tự xác nhận image đã tồn tại trên GHCR, repoint medical-chatbot-app (dùng chung sync_practice_argocd.py với đường deploy xuôi), chờ tới khi Application thật sự Synced/Healthy trên đúng tag đó (không chỉ tin lệnh sync đã gọi xong — có race với ArgoCD selfHeal, xem comment trong script), rồi mới xác nhận realvuxbaro.me sống. Chưa tự động hoá; kích hoạt thủ công qua workflow_dispatch, không trigger theo push.

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): Compose EC2 (i-039fc8f6102467a54, 52.0.158.61) đã stop (không terminate) ngày 2026-08-18 theo quyết định chỉ dùng 1 EC2 — không còn là đường lui sống. Máy vẫn tồn tại (root EBS DeleteOnTermination=true, nên terminate mới mất vĩnh viễn), đóng băng ở code df57e6b từ trước cutover. Muốn dùng lại làm đường lui khẩn cấp: aws ec2 start-instances --instance-ids i-039fc8f6102467a54, chờ container tự khởi động (docker-compose.prod.yml không có auto-start service, kiểm tra lại), xác nhận corpus/schema còn tương thích với migration hiện tại của production trước khi trỏ A record — thời gian đứng máy càng lâu, xác suất lệch corpus càng cao. Đây là việc thủ công, không có script/workflow nào làm sẵ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

1. Lấy trace_id, correlation_id, otel_trace_id từ response.
2. Tra rag_retrieval_trace để xem query, scope, intent, decision, reason, drug và citations.
3. Kiểm tra Prometheus request/stage duration, decision, provider failure và generation rejection.
4. Nếu OTel bật, tìm trace trong Tempo/Grafana để xác định stage chậm/lỗi.
5. 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.