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:

   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