goodgo-platform/docs/audits/README_INFRASTRUCTURE.md

# 📚 GoodGo Platform — Tài liệu Hạ tầng

Thư mục này chứa **ba tài liệu vận hành toàn diện** dành cho hạ tầng GoodGo Platform.

## 📖 Các Tệp Tài liệu

### 1. **INFRASTRUCTURE_RUNBOOK.md** (1.458 dòng)
**→ Đọc tài liệu này để có tài liệu tham chiếu vận hành đầy đủ**

Hướng dẫn toàn diện bao gồm:
- ✅ Tóm tắt điều hành (tổng quan 12+ dịch vụ)
- ✅ Danh sách đầy đủ các dịch vụ kèm cổng, kiểm tra sức khoẻ, phụ thuộc
- ✅ Đặc tả Docker Compose (môi trường dev, prod, CI)
- ✅ Tầng cơ sở dữ liệu (PostgreSQL 16 + PostGIS, 22 mô hình Prisma)
- ✅ Gộp kết nối (cấu hình PgBouncer, chế độ giao dịch)
- ✅ Chiến lược sao lưu & khôi phục (sao lưu tự động hàng ngày, xác minh)
- ✅ Bộ nhớ đệm & tìm kiếm (Redis giảm cấp nhẹ nhàng, Typesense toàn văn)
- ✅ Giám sát & quan sát (Prometheus, bảng điều khiển Grafana, nhật ký Loki)
- ✅ Tích hợp thanh toán (VNPay, MoMo, ZaloPay, xử lý callback)
- ✅ Kiểm tra sức khoẻ (liveness, readiness, probe theo phụ thuộc)
- ✅ Tài liệu tham chiếu đầy đủ biến môi trường
- ✅ Quy trình triển khai (CI/CD GitHub Actions, bản dựng Docker)
- ✅ Hướng dẫn xử lý sự cố chi tiết với 7+ vấn đề phổ biến
- ✅ Quy trình khẩn cấp và truy vấn Prometheus

**Dùng khi:** Tạo runbook, điều tra sự cố, giới thiệu thành viên mới vào đội vận hành

---

### 2. **INFRASTRUCTURE_QUICK_REFERENCE.md** (222 dòng)
**→ Đọc tài liệu này để tra cứu nhanh**

Tài liệu tham chiếu nhanh bao gồm:
- 🚀 Lệnh khởi động nhanh (dev, prod, CI)
- 📊 Bản đồ dịch vụ với cổng và kiểm tra sức khoẻ
- 🗄️ Tổng quan cơ sở dữ liệu (lịch sao lưu, gộp kết nối)
- 💾 Tóm tắt bộ nhớ đệm & tìm kiếm (tính năng Redis, Typesense)
- 📈 Liên kết bảng điều khiển giám sát
- 💳 Tóm tắt cổng thanh toán
- 🏥 Tài liệu tham chiếu endpoint kiểm tra sức khoẻ
- 🔐 Biến môi trường quan trọng
- 📦 Ảnh container triển khai
- 🆘 Các bước xử lý sự cố phổ biến (5 cách khắc phục nhanh)
- 📝 Vị trí tệp quan trọng và liên kết
- 📞 Lệnh Docker thường dùng

**Dùng khi:** Gỡ lỗi nhanh, tra cứu ca trực, kiểm tra sức khoẻ nhanh

---

### 3. **INFRASTRUCTURE_AUDIT.md** (1.246 dòng)
**→ Đọc tài liệu này để xem toàn bộ lịch sử kiểm tra**

Kiểm tra chi tiết bao gồm:
- Nội dung tệp cấu hình thô
- Phân tích từng dòng của từng dịch vụ
- Đặc tả biến môi trường
- Sơ đồ luồng callback thanh toán (dạng văn bản)
- Chi tiết cài đặt kiểm tra sức khoẻ
- Quy trình xác minh sao lưu
- Các giai đoạn quy trình CI/CD

**Dùng khi:** Xác minh độ chính xác tài liệu hạ tầng, kiểm toán tuân thủ

---

## 🎯 Điều hướng Nhanh

### Theo Vai trò

**🔧 Kỹ sư DevOps/SRE**
1. Bắt đầu: INFRASTRUCTURE_QUICK_REFERENCE.md (tổng quan 5 phút)
2. Tìm hiểu sâu: INFRASTRUCTURE_RUNBOOK.md (phần 2-3, 7, 11)
3. Tham chiếu: INFRASTRUCTURE_AUDIT.md (để xem cấu hình thô)

**💼 Quản lý Kỹ thuật/Trưởng nhóm Kỹ thuật**
1. Bắt đầu: INFRASTRUCTURE_RUNBOOK.md (phần 1: Tóm tắt Điều hành)
2. Chi tiết: INFRASTRUCTURE_RUNBOOK.md (phần 2-6, 10)

**🚀 Kỹ sư Trực**
1. Bắt đầu: INFRASTRUCTURE_QUICK_REFERENCE.md (toàn bộ tài liệu)
2. Xử lý sự cố: INFRASTRUCTURE_RUNBOOK.md (phần 12)
3. Gỡ lỗi: INFRASTRUCTURE_AUDIT.md (nhật ký/cấu hình thô nếu cần)

**👤 Thành viên Mới**
1. Bắt đầu: INFRASTRUCTURE_QUICK_REFERENCE.md (tổng quan)
2. Tìm hiểu: INFRASTRUCTURE_RUNBOOK.md (phần 1-6)
3. Thực hành: Dùng các lệnh phổ biến từ Quick Reference

---

## 🔍 Câu hỏi Thường gặp & Nơi Tìm Câu trả lời

| Câu hỏi | Tài liệu | Phần |
|----------|----------|------|
| "Có bao nhiêu dịch vụ đang chạy?" | Runbook | 1. Tóm tắt Điều hành |
| "Tôi cần biết những cổng nào?" | Quick Reference | 📊 Bản đồ Dịch vụ |
| "Cơ sở dữ liệu được sao lưu thế nào?" | Runbook | 8. Sao lưu & Khôi phục |
| "Callback thanh toán thất bại, làm gì?" | Runbook | 12. Xử lý Sự cố (Callback Thanh toán) |
| "Redis bị lỗi, ứng dụng có hoạt động không?" | Runbook | 5. Bộ nhớ đệm & Tìm kiếm (Giảm cấp Nhẹ nhàng) |
| "Làm sao khởi động lại một dịch vụ?" | Quick Reference | 📞 Lệnh Thường dùng |
| "Cấu hình giám sát như thế nào?" | Runbook | 6. Giám sát & Quan sát |
| "Biến môi trường ở đâu?" | Runbook | 9. Biến Môi trường |
| "Làm sao triển khai lên production?" | Runbook | 11. Quy trình Triển khai |
| "Kiểm tra sức khoẻ làm gì?" | Runbook | 7. Kiểm tra Sức khoẻ |

---

## 📊 Tổng quan Hạ tầng

```
Development Environment
├── 12 Services (no resource limits)
├── PostgreSQL 16 + PostGIS (5432)
├── Redis 7 (6379, 256MB)
├── Typesense 27.1 (8108)
├── Prometheus (9090, 15-day retention)
├── Grafana (3002, 7 dashboards)
├── Loki (3100, 15-day logs)
└── API/Web/AI services

Production Environment
├── 14 Services (with resource limits, security hardening)
├── PgBouncer (6432, 20-connection pool)
├── PostgreSQL 16 + PostGIS (5432)
├── Redis 7 (6379, 512MB, password auth)
├── Typesense 27.1 (8108)
├── Prometheus (9090, 30-day retention)
├── Grafana (3002, secrets management)
├── Loki (3100, 15-day logs)
└── API/Web/AI services (zero-downtime deployments)

CI/E2E Environment
├── 4 Services (tmpfs for speed)
├── PostgreSQL test DB
├── Redis (no persistence)
└── Typesense + MinIO (tmpfs)
```

---

## 🔗 Tệp Liên quan trong Kho lưu trữ

```
goodgo-platform-ai/
├── README_INFRASTRUCTURE.md (TỆP NÀY)
├── INFRASTRUCTURE_RUNBOOK.md (Tài liệu tham chiếu đầy đủ)
├── INFRASTRUCTURE_QUICK_REFERENCE.md (Tra cứu nhanh)
├── INFRASTRUCTURE_AUDIT.md (Kiểm tra chi tiết)
│
├── docker-compose.yml (Môi trường Dev)
├── docker-compose.prod.yml (Production)
├── docker-compose.ci.yml (Testing)
│
├── .env.example (Mẫu biến môi trường)
├── prisma/schema.prisma (Mô hình dữ liệu, 22 mô hình Prisma)
│
├── infra/pgbouncer/ (Gộp kết nối)
├── monitoring/ (Cấu hình Prometheus, Grafana, Loki)
├── scripts/backup/ (Script sao lưu và xác minh)
│
└── .github/workflows/ (Quy trình CI/CD)
    ├── ci.yml (Lint → Test → Build)
    ├── deploy.yml (Dựng ảnh, triển khai)
    ├── e2e.yml (Kiểm thử đầu-cuối)
    ├── backup-verify.yml (Xác minh sao lưu hàng tuần)
    └── security.yml (Quét phụ thuộc)
```

---

## 🆘 Hỗ trợ Khẩn cấp

### "API bị lỗi. Tôi cần kiểm tra gì?"
1. Đọc: INFRASTRUCTURE_QUICK_REFERENCE.md → 🆘 Xử lý Sự cố
2. Lệnh nhanh:
   ```bash
   docker compose ps api
   docker compose logs api --tail=50
   curl http://localhost:3001/health/ready
   ```
3. Vẫn chưa giải quyết được: Xem INFRASTRUCTURE_RUNBOOK.md → 12. Xử lý Sự cố

### "Tôi cần triển khai lên production"
1. Đọc: INFRASTRUCTURE_QUICK_REFERENCE.md → 📦 Triển khai
2. Tiếp theo: INFRASTRUCTURE_RUNBOOK.md → 11. Quy trình Triển khai
3. Xem lại: `.github/workflows/deploy.yml` để biết các bước thực tế

### "Cơ sở dữ liệu chậm"
1. Đọc: INFRASTRUCTURE_RUNBOOK.md → 4. Tầng Cơ sở Dữ liệu (Gộp Kết nối)
2. Kiểm tra: INFRASTRUCTURE_QUICK_REFERENCE.md → 🆘 "Gộp kết nối cơ sở dữ liệu đầy?"
3. Truy vấn: Dùng truy vấn Prometheus từ INFRASTRUCTURE_RUNBOOK.md

### "Làm sao khôi phục từ bản sao lưu?"
1. Đọc: INFRASTRUCTURE_RUNBOOK.md → 8. Sao lưu & Khôi phục
2. Các bước: Phần "Restore from Backup" với lệnh chính xác

---

## 📈 Chỉ số Chính & SLO

Từ phần giám sát trong INFRASTRUCTURE_RUNBOOK.md:

| Chỉ số | Cảnh báo | Nghiêm trọng | Nguồn |
|--------|---------|----------|--------|
| Độ trễ p99 API | > 1s (5 phút) | > 3s (3 phút) | Histogram Prometheus |
| p99/endpoint API | > 2s (5 phút) | N/A | Prometheus |
| Tỷ lệ lỗi 5xx | > 1% (5 phút) | N/A | Prometheus |
| Phản hồi cơ sở dữ liệu | Được giám sát | Được giám sát | Bảng điều khiển Grafana |
| Khả dụng Redis | Giảm cấp nhẹ nhàng | Giảm cấp nhẹ nhàng | Ứng dụng tiếp tục trên DB |

Bảng điều khiển có sẵn tại `http://localhost:3002` (Grafana):
- API Latency
- API Overview
- Database Metrics
- Logs & Errors
- Search Analytics
- Web Vitals
- Business Metrics

---

## 🔐 Lưu ý Bảo mật

Từ phần biến môi trường trong INFRASTRUCTURE_RUNBOOK.md:

**QUAN TRỌNG (Production):**
- JWT_SECRET phải có ít nhất 32 ký tự (tạo: `openssl rand -base64 48`)
- KYC_ENCRYPTION_KEY phải là 64 ký tự hex (tạo: `openssl rand -hex 32`)
- Tất cả thông tin xác thực cổng thanh toán phải được luân chuyển định kỳ
- Redis yêu cầu xác thực bằng mật khẩu trong môi trường production
- Container Docker chạy với người dùng không phải root (người dùng node)
- Hệ thống tệp chỉ đọc cho container ứng dụng
- Đặt cờ no new privileges

---

## 📞 Quy trình Leo thang

1. **Vấn đề Khẩn cấp?** → INFRASTRUCTURE_QUICK_REFERENCE.md
2. **Vấn đề Phức tạp?** → INFRASTRUCTURE_RUNBOOK.md phần 12
3. **Cần Lịch sử Kiểm tra?** → INFRASTRUCTURE_AUDIT.md
4. **Vẫn Chưa Giải quyết?** → Kiểm tra .github/workflows/ hoặc lịch sử git

---

## 📝 Cập nhật Tài liệu

Các tài liệu này được tạo vào **ngày 11 tháng 4 năm 2026** từ một cuộc kiểm tra hạ tầng toàn diện của monorepo GoodGo Platform.

**Để giữ tài liệu luôn cập nhật:**
- Cập nhật tài liệu này khi thêm dịch vụ mới
- Xem lại cấu hình giám sát sau khi thay đổi hạ tầng
- Kiểm thử quy trình sao lưu hàng tháng (đã được tự động hoá)
- Cập nhật runbook dựa trên postmortem sự cố

---

## 🎓 Lộ trình Học tập

**Dành cho thành viên mới:**
1. **Ngày 1:** Đọc INFRASTRUCTURE_QUICK_REFERENCE.md (30 phút)
2. **Ngày 2:** Đọc INFRASTRUCTURE_RUNBOOK.md phần 1-3 (1 giờ)
3. **Ngày 3:** Thực hành lệnh từ Quick Reference cùng người hướng dẫn
4. **Ngày 4:** Đọc INFRASTRUCTURE_RUNBOOK.md phần 4-7 (1,5 giờ)
5. **Ngày 5:** Đọc INFRASTRUCTURE_RUNBOOK.md phần 8-12 (1,5 giờ)
6. **Tuần 2:** Theo sát kỹ sư trực, thực hành xử lý sự cố
7. **Tuần 3:** Nhận ca trực

---

**Cập nhật lần cuối:** Ngày 11 tháng 4 năm 2026  
**Phiên bản:** 1.0  
**Người bảo trì:** GoodGo Platform SRE Team

---

*Để đặt câu hỏi hoặc cập nhật tài liệu này, liên hệ: devops@goodgo.vn*