pos-system/docs/vi/guides/deployment.md

Hướng Dẫn Deployment

Hướng dẫn deployment cho GoodGo Microservices Platform trên các môi trường Local, Staging, và Production sử dụng Kubernetes và Neon PostgreSQL

Mục lục

1. Kiến trúc Deployment
2. Yêu cầu Tiên quyết
3. Thiết lập Database (Neon)
4. Local Deployment
5. Quy trình CI/CD
6. Staging Deployment
7. Production Deployment
8. Scaling & Resilience
9. Quy trình Rollback

---

Kiến trúc Deployment

graph TD
 subgraph "CI/CD Pipeline - GitHub Actions"
 Code[Code Push] --> Test[Run Tests]
 Test --> Build[Build Docker Image]
 Build --> Registry[Push to Registry]
 Registry --> Deploy[Deploy to K8s]
 end

 subgraph "Infrastructure - Kubernetes"
 Ingress[Traefik Ingress] --> Service[K8s Service]
 Service --> Pods[Application Pods]
 Pods --> Secrets[K8s Secrets]
 end

 subgraph "External Services"
 Pods --> Neon[(Neon PostgreSQL)]
 Pods --> Redis[(Redis Cloud)]
 end

 Deploy --> Ingress

 style Code fill:#1e3a5f,color:#e0e7ff
 style Test fill:#065f46,color:#d1fae5
 style Build fill:#1e40af,color:#dbeafe
 style Registry fill:#581c87,color:#f3e8ff
 style Deploy fill:#9a3412,color:#fed7aa
 style Ingress fill:#312e81,color:#e0e7ff
 style Service fill:#1e40af,color:#dbeafe
 style Pods fill:#14532d,color:#d1fae5
 style Secrets fill:#78350f,color:#fef3c7
 style Neon fill:#4c1d95,color:#f3e8ff
 style Redis fill:#854d0e,color:#fef3c7

---

Yêu cầu Tiên quyết

Trước khi deploy, đảm bảo bạn có:

• Công cụ: Cài đặt kubectl, helm, docker.
• Quyền truy cập:
• Kubernetes Cluster (EKS/GKE/DigitalOcean).
• Container Registry (GHCR/DockerHub).
• Tài khoản Neon Console.
• Cấu hình:
• File KUBECONFIG đã được setup.
• GitHub Secrets đã cấu hình cho CI/CD.

---

Thiết lập Database (Neon)

Chúng tôi sử dụng Neon Serverless PostgreSQL cho tất cả môi trường để tận dụng tính năng branching và auto-scaling.

1. Tạo Project: Đăng nhập neon.tech và tạo project goodgo-platform.
2. Tạo Branches:

• main -> Cho Development/Local.
• staging -> Cho môi trường Staging.
• production -> Cho môi trường Production (Protected).

3. Lấy Connection Strings:

• Lưu lại connection string cho từng branch (Khuyến nghị dùng Pooler mode).

---

Local Deployment

Cho phát triển cục bộ, chúng ta sử dụng Docker Compose.

# 1. Setup Biến môi trường
cp deployments/local/env.local.example deployments/local/.env.local
# Sửa .env.local với connection string của Neon branch `main`

# 2. Khởi động Infrastructure (Redis, Traefik, v.v.)
cd deployments/local
docker-compose up -d

# 3. Khởi động Services (Hot-reload)
pnpm dev

---

Quy trình CI/CD

Chúng tôi sử dụng GitHub Actions để tự động hóa deployment.

Workflow	Trigger	Mô tả
ci-check.yml	Pull Request	Chạy unit tests, linting, và kiểm tra build.
deploy-staging.yml	Push vào develop	Build image -> Deploy vào Namespace Staging.
deploy-prod.yml	Release / Tag	Build image -> Deploy vào Namespace Production.

Cấu hình Secrets (GitHub)

Cài đặt các secrets này trong phần settings của repository:

• NEON_DATABASE_URL_STAGING: Connection string cho branch staging.
• NEON_DATABASE_URL_PRODUCTION: Connection string cho branch production.
• KUBECONFIG_STAGING: Base64 encoded kubeconfig cho staging.
• KUBECONFIG_PRODUCTION: Base64 encoded kubeconfig cho production.
• DOCKER_REGISTRY_TOKEN: Dùng để push images.

---

Staging Deployment

Staging phản chiếu production nhưng sử dụng tài nguyên tiết kiệm hơn.

Deployment Thủ công

# 1. Tạo Secrets
kubectl create secret generic iam-service-secrets \
 --from-literal=database-url='<STAGING_NEON_URL>' \
 --from-literal=jwt-secret='<RANDOM_SECRET>' \
 -n staging

# 2. Apply Manifests
kubectl apply -f deployments/staging/kubernetes/ -n staging

# 3. Verify
kubectl get pods -n staging

Qua CI/CD

Push code vào branch develop. Action sẽ:

1. Chạy tests.
2. Chạy prisma migrate deploy vào Database Staging.
3. Cập nhật Kubernetes deployment image.

---

Production Deployment

Production sử dụng cấu hình high-availability (HA).

1. Chuẩn bị Database

• Đảm bảo branch Production trên Neon được set protected.
• Cấu hình Point-in-Time Recovery (PITR) window (ví dụ: 7 ngày).

2. Các bước Deployment Thủ công

# 1. Tạo Namespace
kubectl create namespace production

# 2. Tạo Secrets (Khuyến nghị Sealed Secrets) hoặc Standard Secrets
kubectl create secret generic iam-service-secrets \
 --from-literal=database-url='<PROD_NEON_URL>' \
 --from-literal=jwt-secret='<SECURE_RANDOM_SECRET>' \
 --from-literal=jwt-refresh-secret='<SECURE_RANDOM_SECRET>' \
 -n production

# 3. Deploy
kubectl apply -f deployments/production/kubernetes/ -n production

3. Xác minh

# Kiểm tra trạng thái Rollout
kubectl rollout status deployment/iam-service -n production

# Xem Logs
kubectl logs -l app=iam-service -n production

---

Scaling & Resilience

Horizontal Pod Autoscaler (HPA)

Chúng tôi sử dụng HPA để tự động scale số lượng pods dựa trên CPU/Memory.

# Ví dụ cấu hình HPA
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
 name: iam-service-hpa
spec:
 minReplicas: 2
 maxReplicas: 10
 metrics:
 - type: Resource
 resource:
 name: cpu
 target:
 type: Utilization
 averageUtilization: 70

Zero-Downtime Deployment

Kubernetes xử lý việc này thông qua Rolling Updates.

• MaxSurge: 25% (Thêm pods mới trước khi xóa pods cũ).
• MaxUnavailable: 0 (Đảm bảo không có downtime trong quá trình update).

---

Quy trình Rollback

Nếu deployment thất bại hoặc gây ra lỗi nghiêm trọng:

Kubernetes Rollback

# Undo deployment gần nhất
kubectl rollout undo deployment/iam-service -n production

# Undo về một revision cụ thể
kubectl rollout undo deployment/iam-service -n production --to-revision=2

Database Rollback

Vì Neon hỗ trợ branching và PITR:

1. Vào Neon Console.
2. Restore branch production về timestamp trước khi migration bị lỗi.
3. Cảnh báo: Việc này có thể gây mất dữ liệu giao dịch mới. Hãy cẩn trọng.