Files

Ho Ngoc Hai 4f48eadea8 docs: Nâng cấp hướng dẫn triển khai Kubernetes cục bộ với sơ đồ quy trình, hướng dẫn chi tiết và chú thích song ngữ.

2026-01-05 19:15:09 +07:00

7.8 KiB

Raw Blame History

Hướng Dẫn Phát Triển Local (Local Development)

EN: Local Development Guide

VI: Hướng dẫn phát triển cục bộ

Cập nhật: 2026-01-05 Độ khó: Trung bình (Intermediate) Thời gian thiết lập: 15-30 phút

Workflow / Quy Trình

graph TD
    Start([Bắt đầu / Start]) --> Prerequisites[1. Yêu cầu Hệ thống<br/>Prerequisites]
    Prerequisites --> Clone[2. Clone & Install]
    Clone --> Env[3. Cấu hình Environment<br/>(Shared & Service-Specific)]
    Env --> DB[4. Setup Database<br/>(Migrate & Seed)]
    DB --> Run[5. Chạy Dự án<br/>(Native/Docker/Hybrid)]
    Run --> Dev[6. Development Loop<br/>(Watch Mode)]
    Dev --> Test[7. Testing & Verify]
    Test --> End([Hoàn tất / Complete])

    subgraph "Các Chế độ Chạy / Run Modes"
        Run --> Mode1[Cách 1: Native (Nhanh nhất)]
        Run --> Mode2[Cách 2: Hybrid (Linh hoạt)]
        Run --> Mode3[Cách 3: Full Docker (Production-like)]
    end

    style Start fill:#d4edda,stroke:#28a745,stroke-width:2px
    style End fill:#d4edda,stroke:#28a745,stroke-width:2px
    style Env fill:#fff3cd,stroke:#ffc107
    style DB fill:#fff3cd,stroke:#ffc107
    style Run fill:#cce5ff,stroke:#007bff

Tổng Quan / Overview

Hướng dẫn này cung cấp quy trình chi tiết để thiết lập môi trường phát triển (development environment) cho hệ sinh thái GoodGo Microservices. Bạn sẽ học cách chạy các service, thiết lập cơ sở dữ liệu và quy trình làm việc hiệu quả với hot-reload.

1. Yêu Cầu Hệ Thống / Prerequisites

Trước khi bắt đầu, đảm bảo máy của bạn đã cài đặt các công cụ sau:

Node.js: Phiên bản LTS mới nhất (v20+).
PNPM: Package manager chính của dự án (npm install -g pnpm).
Docker Desktop: Cần thiết để chạy các dịch vụ hạ tầng (Redis, Database local).
Git: Để quản lý mã nguồn.
Neon Account (Tùy chọn): Nếu sử dụng Neon Database trên cloud (khuyên dùng cho dev).

2. Cài Đặt Ban Đầu / Initial Setup

2.1 Clone và Cài Đặt Dependencies

# EN: Clone the repository
# VI: Clone repository về máy
git clone <repository-url>
cd Base

# EN: Install dependencies using pnpm
# VI: Cài đặt các thư viện phụ thuộc bằng pnpm
pnpm install

2.2 Script Khởi Tạo Nhanh (Khuyến nghị)

Dự án có script tự động hóa các bước khởi tạo cơ bản:

# EN: Run initialization script
# VI: Chạy script khởi tạo
./scripts/setup/init-project.sh

Script này sẽ:

Cài đặt dependencies.

Copy các file môi trường mẫu (.env.example -> .env).

Tạo Prisma client.

3. Cấu Hình Environment / Environment Configuration

Dự án sử dụng chiến lược Hybrid Environment để tối ưu hóa việc quản lý cấu hình:

3.1 Shared Configuration (Cấu hình chung)

File: deployments/local/.env.local Chứa các biến dùng chung cho toàn bộ hệ thống (JWT, Redis, Logging).

# EN: Create shared env file from example
# VI: Tạo file môi trường chung từ file mẫu
cp deployments/local/env.local.example deployments/local/.env.local

3.2 Service-Specific Configuration (Cấu hình riêng)

Mỗi service (ví dụ iam-service) cần file .env.local riêng chứa thông tin đặc thù như Database URL và Port.

# EN: Create service-specific env file
# VI: Tạo file môi trường riêng cho service
cp services/iam-service/env.local.example services/iam-service/.env.local

Nội dung quan trọng cần chú ý trong services/iam-service/.env.local:

# Database URL (Sử dụng Neon Tech hoặc Local Postgres)
DATABASE_URL=postgresql://user:password@host:5432/db_name?sslmode=require

# Port của Service (Mỗi service phải khác nhau)
PORT=5001

# Tên Service
SERVICE_NAME=iam-service

# Redis Host (localhost cho Native Dev, redis cho Docker Dev)
REDIS_HOST=localhost

4. Setup Database

Sau khi cấu hình DATABASE_URL, bạn cần đồng bộ schema và tạo dữ liệu mẫu.

# EN: Run migrations for iam-service
# VI: Chạy migration cho iam-service
./scripts/db/migrate.sh iam-service dev

# EN: Seed initial data (optional)
# VI: Tạo dữ liệu mẫu (tùy chọn)
./scripts/db/seed.sh iam-service

5. Các Chế Độ Chạy / Run Modes

Bạn có thể chạy dự án theo 3 cách tùy thuộc vào nhu cầu:

Cách 1: Native Development (Khuyên dùng cho Backend Dev)

Chạy trực tiếp trên máy host. Tốc độ cao nhất, hot-reload nhanh nhất.

Khởi động Hạ tầng (Infrastructure):

# EN: Start Redis and Traefik in Docker background
# VI: Khởi động Redis và Traefik chạy ngầm bằng Docker
cd deployments/local
docker-compose up -d redis traefik
cd ../..

Chạy Service:

# EN: Start iam-service in watch mode
# VI: Chạy iam-service ở chế độ watch
pnpm --filter @goodgo/iam-service dev

Cách 2: Hybrid Development (Linh hoạt)

Dùng khi bạn cần chạy nhiều service phụ trợ trong Docker, nhưng muốn dev trực tiếp 1 service chính.

# EN: Start dependent services in Docker
# VI: Chạy các service phụ thuộc trong Docker
docker-compose -f deployments/local/docker-compose.yml up -d user-service payment-service

# EN: Run the service you are working on natively
# VI: Chạy service bạn đang làm việc trực tiếp trên máy
pnpm --filter @goodgo/iam-service dev

Cách 3: Full Docker (Mô phỏng Production)

Chạy toàn bộ hệ thống trong Docker. Tốt cho việc kiểm tra tích hợp (Integration Test) nhưng không có hot-reload.

# EN: Start everything with Docker Compose
# VI: Chạy tất cả bằng Docker Compose
cd deployments/local
docker-compose up -d

6. Access & Verification / Truy Cập & Kiểm Tra

Sau khi khởi động, bạn có thể truy cập các điểm cuối sau:

Service	URL	Mô tả
API Gateway	`http://localhost/api/v1`	Cổng truy cập chính qua Traefik
IAM Service	`http://localhost:5001`	Truy cập trực tiếp service
Health Check	`http://localhost:5001/health`	Kiểm tra trạng thái service
Metrics	`http://localhost:5001/metrics`	Prometheus metrics
API Docs	`http://localhost:5001/api-docs`	Swagger UI

Kiểm tra Health Check

# EN: Check liveness
# VI: Kiểm tra liveness
curl http://localhost:5001/health/live

# EN: Check readiness
# VI: Kiểm tra readiness
curl http://localhost:5001/health/ready

7. Troubleshooting / Xử Lý Sự Cố

Port Already In Use

Lỗi: Error: listen EADDRINUSE: address already in use :::5001

Giải pháp:

# EN: Find process using port 5001
# VI: Tìm process đang chiếm port 5001
lsof -i :5001

# EN: Kill the process
# VI: Tắt process đó
kill -9 <PID>

Database Connection Error

Lỗi: P1001: Can't reach database server

Giải pháp:

Kiểm tra lại biến DATABASE_URL.
Nếu dùng Docker Postgres local, đảm bảo container đang chạy (docker ps).
Nếu dùng Neon, kiểm tra kết nối internet.

Module Not Found

Lỗi: Không tìm thấy các package nội bộ (ví dụ @goodgo/logger).

Giải pháp:

# EN: Re-install dependencies and build packages
# VI: Cài lại dependencies và build lại packages
pnpm install
pnpm build

Tài Liệu Tham Khảo / References

Kubernetes Guide - Triển khai lên K8s Local.
Project Architecture - Tổng quan kiến trúc hệ thống.

7.8 KiB Raw Blame History

Hướng Dẫn Phát Triển Local (Local Development)

Workflow / Quy Trình

Tổng Quan / Overview

1. Yêu Cầu Hệ Thống / Prerequisites

2. Cài Đặt Ban Đầu / Initial Setup

2.1 Clone và Cài Đặt Dependencies

2.2 Script Khởi Tạo Nhanh (Khuyến nghị)

3. Cấu Hình Environment / Environment Configuration

3.1 Shared Configuration (Cấu hình chung)

3.2 Service-Specific Configuration (Cấu hình riêng)

4. Setup Database

5. Các Chế Độ Chạy / Run Modes

Cách 1: Native Development (Khuyên dùng cho Backend Dev)

Cách 2: Hybrid Development (Linh hoạt)

Cách 3: Full Docker (Mô phỏng Production)

6. Access & Verification / Truy Cập & Kiểm Tra

Kiểm tra Health Check

7. Troubleshooting / Xử Lý Sự Cố

Port Already In Use

Database Connection Error

Module Not Found

Tài Liệu Tham Khảo / References

7.8 KiB

Raw Blame History