123 lines
4.0 KiB
Markdown
123 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
1. fetch và reset checkout về `origin/master`;
|
|
2. build/start app + observability services;
|
|
3. validate/reload Caddy;
|
|
4. apply migrations;
|
|
5. kiểm tra health/readiness/web;
|
|
6. smoke một condition→drug response;
|
|
7. 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:
|
|
|
|
1. verify SHA tồn tại;
|
|
2. reset checkout về SHA đó;
|
|
3. rebuild app/observability tier;
|
|
4. chạy migrations idempotent;
|
|
5. 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:
|
|
|
|
1. đặt lại `QDRANT_COLLECTION` về collection cũ;
|
|
2. restart `ai-service`;
|
|
3. xác nhận manifest check và smoke query;
|
|
4. 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 |
|
|
|
|
## Liên quan
|
|
|
|
- [Deployment architecture](../20-deployment.md)
|
|
- [CI/CD](../22-ci-cd.md)
|
|
- [Production operations](../24-production-operations.md)
|
|
- [Troubleshooting](../25-troubleshooting.md)
|