goodgo-platform/docs/audits/INFRASTRUCTURE_QUICK_REFERENCE.md

GoodGo Platform — Tài Liệu Tham Khảo Nhanh về Cơ Sở Hạ Tầng

🚀 Khởi Động Nhanh

# Phát triển
docker compose up -d --wait

# Sản xuất
docker compose -f docker-compose.prod.yml up -d --wait

# CI/E2E
docker compose -f docker-compose.ci.yml up -d --wait

📊 Bản Đồ Dịch Vụ (Dev)

Dịch Vụ	Cổng	Kiểm Tra Sức Khỏe	Trạng Thái
API (NestJS)	3001	GET /health	🟢
Web (Next.js)	3000	GET /	🟢
AI Services (Python)	8000	GET /health	🟢
PostgreSQL + PostGIS	5432	pg_isready	🟢
Redis	6379	PING	🟢
Typesense	8108	GET /health	🟢
MinIO	9000	mc ready local	🟢
Prometheus	9090	GET /-/healthy	🟢
Grafana	3002	GET /api/health	🟢
Loki	3100	GET /ready	🟢
Promtail	9080	(thụ động)	🟢

📊 Bản Đồ Dịch Vụ (Prod)

Giống như dev, cộng thêm PgBouncer (6432) để gộp kết nối.

🗄️ Cơ Sở Dữ Liệu

• Loại: PostgreSQL 16 + PostGIS
• Schema: 22 mô hình Prisma
• Sao lưu: Hằng ngày lúc 02:00 UTC, lưu giữ 7 ngày
• Gộp Kết Nối (Prod): PgBouncer (chế độ giao dịch, 20 kết nối)
• Xác minh: Kiểm tra khôi phục tự động hàng tuần

Các Bảng Chính:

• User, RefreshToken, OAuthAccount, Agent
• Property, PropertyMedia, Listing
• SavedSearch, Transaction, Inquiry, Lead
• Payment (VNPAY/MOMO/ZALOPAY/BANK_TRANSFER)
• Plan, Subscription, UsageRecord
• Valuation, MarketIndex, NotificationLog, AdminAuditLog, Review

💾 Bộ Nhớ Đệm & Tìm Kiếm

• Redis: 512MB (prod), 256MB (dev), lưu trữ AOF, loại bỏ LRU
• Typesense: Tìm kiếm toàn văn bản trên các danh sách, hỗ trợ lập chỉ mục địa lý

📈 Giám Sát

• Prometheus: Lưu giữ 30 ngày (prod), 15 ngày (dev)
• Grafana: Bảng điều khiển được cấu hình sẵn (7 bảng)
• Loki: Lưu giữ nhật ký 15 ngày, phân tích cú pháp JSON Pino
• Cảnh báo: Độ trễ p99 > 1s (cảnh báo), > 3s (nghiêm trọng), 5xx > 1%

💳 Tích Hợp Thanh Toán

Cổng Thanh Toán	Nhà Cung Cấp	Theo Dõi Trạng Thái	Xác Minh Callback
VNPay	VNPAY	✅	HMAC SHA-256
MoMo	MOMO	✅	HMAC
ZaloPay	ZALOPAY	✅	Key 1/2
Bank Transfer	BANK_TRANSFER	Thủ công	N/A

Trình Xử Lý Callback:

• Idempotent (mẫu updateIfStatus)
• Chuyển trạng thái nguyên tử (PENDING → COMPLETED/FAILED)
• Xuất bản sự kiện miền (kích hoạt các hành động tiếp theo)

🏥 Kiểm Tra Sức Khỏe

GET /health          # Liveness (luôn 200)
GET /health/ready    # Readiness (kiểm tra DB + Redis)
GET /health/db       # Chỉ cơ sở dữ liệu
GET /health/redis    # Chỉ Redis

🔐 Biến Môi Trường (Quan Trọng)

# Cơ sở dữ liệu
DB_USER=goodgo
DB_PASSWORD=<required>
DATABASE_URL_DIRECT=postgresql://...  # For migrations

# Redis (Prod yêu cầu mật khẩu)
REDIS_PASSWORD=<required-in-prod>

# Typesense API Key
TYPESENSE_API_KEY=<required>

# JWT Secrets (BẮT BUỘC, tối thiểu 32 ký tự)
JWT_SECRET=<openssl rand -base64 48>
JWT_REFRESH_SECRET=<openssl rand -base64 48>

# KYC Encryption (Chỉ Prod)
KYC_ENCRYPTION_KEY=<openssl rand -hex 32>  # 64 hex chars

# Cổng Thanh Toán (tùy chọn nếu bị tắt)
VNPAY_TMN_CODE=
MOMO_PARTNER_CODE=
ZALOPAY_APP_ID=

📦 Triển Khai

Container:

• goodgo-api:${IMAGE_TAG} — NestJS API
• goodgo-web:${IMAGE_TAG} — Next.js Frontend
• goodgo-ai-services:${IMAGE_TAG} — Python FastAPI

Registry: ghcr.io/goodgo/

CI/CD: GitHub Actions

• ci.yml — Kiểm tra, build, lint khi push
• deploy.yml — Build image, triển khai lên staging (tự động) hoặc prod (thủ công)
• backup-verify.yml — Xác minh khôi phục hàng tuần
• e2e.yml — Bộ kiểm thử đầu cuối

🆘 Khắc Phục Sự Cố

API không hoạt động bình thường?

docker compose exec api curl http://localhost:3001/health/ready
docker compose logs api --tail=50

Gộp kết nối cơ sở dữ liệu đầy?

docker compose exec pgbouncer psql -h 127.0.0.1 -p 6432 -U pgbouncer_stats -c "SHOW stats"

Redis ngừng hoạt động?

docker compose exec redis redis-cli ping
# Ứng dụng vẫn tiếp tục chạy (dự phòng DB), nhưng chậm hơn

Typesense không lập chỉ mục?

curl http://localhost:8108/collections/listings -H "X-TYPESENSE-API-KEY: ${KEY}"
# Lập chỉ mục lại: docker compose exec api npx ts-node scripts/reindex-listings.ts

Callback thanh toán thất bại?

docker compose logs api | grep -i callback
# Kiểm tra VNPAY_HASH_SECRET / MOMO_SECRET_KEY / ZALOPAY_KEY1

Sao lưu bị kẹt?

docker compose exec pg-backup bash -c "tail -f /var/log/pg-backup.log"
docker compose exec postgres psql -U goodgo -d goodgo -c "SELECT * FROM pg_stat_activity WHERE wait_event_type IS NOT NULL;"

📝 Các Tệp Quan Trọng

Đường Dẫn	Mục Đích
docker-compose.yml	Dev (không giới hạn tài nguyên, tất cả dịch vụ)
docker-compose.prod.yml	Prod (PgBouncer, giới hạn, bí mật)
docker-compose.ci.yml	Kiểm thử (tmpfs, dịch vụ tối thiểu)
INFRASTRUCTURE_RUNBOOK.md	Tài liệu đầy đủ (tệp đồng hành)
prisma/schema.prisma	Mô hình dữ liệu hoàn chỉnh
infra/pgbouncer/pgbouncer.ini	Cấu hình gộp kết nối
monitoring/prometheus/alert-rules.yml	Định nghĩa cảnh báo
scripts/backup/pg-backup.sh	Tự động hóa sao lưu hàng ngày
scripts/backup/pg-verify-backup.sh	Xác minh khôi phục
.github/workflows/*.yml	Pipeline CI/CD

🔗 Liên Kết

• Grafana: http://localhost:3002 (admin/admin)
• Prometheus: http://localhost:9090
• MinIO Console: http://localhost:9001
• API Docs: http://localhost:3001/api (nếu Swagger được bật)
• Frontend: http://localhost:3000

📞 Lệnh Thường Dùng

# Xem tất cả dịch vụ
docker compose ps

# Theo dõi nhật ký
docker compose logs -f api web postgres redis

# Thực thi lệnh trong container
docker compose exec api npx prisma db push
docker compose exec postgres psql -U goodgo -d goodgo

# Khởi động lại một dịch vụ
docker compose restart api

# Dọn dẹp hoàn toàn (chỉ dev!)
docker compose down -v && docker compose up -d --wait

# Sao lưu & khôi phục cơ sở dữ liệu
docker compose exec postgres pg_dump -U goodgo -d goodgo | gzip > backup.sql.gz
docker compose exec postgres pg_restore -U goodgo -d goodgo backup.sql.gz

# Kiểm tra endpoint sức khỏe
curl http://localhost:3001/health/ready | jq
curl http://localhost:3001/health/db | jq
curl http://localhost:3001/health/redis | jq

---

Để biết thêm thông tin chi tiết, xem INFRASTRUCTURE_RUNBOOK.md

Cập nhật lần cuối: ngày 11 tháng 4 năm 2026