Cách deploy và rollback production

Phân loại

Loại tài liệu: How-to.

Reader job: phát hành một thay đổi lên EC2 Compose và khôi phục commit trước nếu verification thất bại.

Khi nào dùng hướng dẫn này

Production hiện tại là một EC2 host chạy Docker Compose. Đây không phải quy trình Kubernetes/ArgoCD. Deploy bình thường chạy bằng deploy.yml; rollback có workflow manual riêng.

Điều kiện tiên quyết

Thay đổi đã được review.
CI của commit đã xanh; lưu ý deploy workflow chưa phụ thuộc CI bằng needs.
GitHub secrets EC2_HOST, EC2_SSH_KEY và GRAFANA_ADMIN_PASSWORD hợp lệ.
Biết last-known-good SHA trước khi deploy.
Thay đổi migration đã được đánh giá vì migrations chỉ đi tới, không có down.

Bước 1 — Xác định deploy có được trigger không

Push lên master chỉ trigger deploy khi thay đổi nằm trong path filter:

apps/ai-service/**;
apps/web/**;
packages/**;
drug entity artifact;
infra/docker/**;
chính deploy.yml.

Docs-only change không deploy production. Có thể dùng workflow_dispatch khi cần chạy chủ động.

Bước 2 — Ghi release context

Trước khi chạy, lưu:

target SHA
last-known-good SHA
CI run URL
deploy run URL
thay đổi config/migration
người theo dõi rollout

Không deploy đồng thời với một corpus switch nếu chưa có kế hoạch rollback riêng cho collection.

Bước 3 — Chạy deploy workflow

Workflow thực hiện trên host:

fetch và reset checkout về origin/master;
build/start app + observability services;
validate/reload Caddy;
apply migrations;
kiểm tra health/readiness/web;
smoke một condition→drug response;
kiểm tra Prometheus, Tempo, Grafana và một trace cụ thể.

Theo dõi log đến khi tất cả assertion pass. Job fail không đồng nghĩa host đã tự rollback; workflow deploy không có automatic rollback.

Bước 4 — Verify sau deploy

Kiểm tra tối thiểu:

/health và /ready trả 200;
web tải được;
query smoke trả answerable và citation chi_dinh;
trace ID có trong Tempo;
duocthu_requests_total query được;
dashboard Grafana được provision;
không có spike mới ở abstain/provider failure.

Giữ một cửa sổ quan sát trước khi tuyên bố rollout hoàn tất.

Rollback bằng workflow

Mở workflow Rollback production, chọn workflow_dispatch, nhập target_sha là last-known-good commit. Workflow:

verify SHA tồn tại;
reset checkout về SHA đó;
rebuild app/observability tier;
chạy migrations idempotent;
chạy health checks.

Rollback không đảo schema database. Nếu release chứa migration không tương thích ngược, dừng và lập kế hoạch phục hồi dữ liệu/schema thay vì chạy workflow mù.

Rollback corpus

Code rollback và corpus rollback là hai thao tác khác nhau. Nếu vừa switch Qdrant collection:

đặt lại QDRANT_COLLECTION về collection cũ;
restart ai-service;
xác nhận manifest check và smoke query;
không xóa collection mới cho đến khi điều tra xong.

Troubleshooting

Triệu chứng	Kiểm tra đầu tiên	Recovery
Build fail sau reset	GitHub log và Docker build log trên host	Rollback workflow về SHA cũ
`ai-service` restart loop	`ManifestMismatch` trong container log	Sửa collection/model binding
Smoke answer fail	Response + 200 dòng ai-service log	Rollback nếu ảnh hưởng live path
Tempo chưa ready	Retry/log Tempo	Không coi rollout complete
Migration fail	Migration output và DB state	Dừng; không chạy reset schema tùy tiện

4.0 KiB Raw Blame History