98 lines
5.5 KiB
Markdown
98 lines
5.5 KiB
Markdown
# 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):
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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.
|
|
|