9ba4a478ee
- Updated Mermaid diagrams in the deployment and development guides for better visual representation and consistency. - Improved formatting and clarity in the Kubernetes local deployment and IAM migration guides, including detailed workflows and troubleshooting sections. - Enhanced the Vietnamese documentation to align with the English version, ensuring consistency across guides. - Added quick tips and common issues sections to facilitate user navigation and understanding.
235 lines
7.2 KiB
Markdown
235 lines
7.2 KiB
Markdown
# Hướng Dẫn Local Development
|
|
|
|
>Hướng dẫn phát triển cục bộ
|
|
|
|
## Workflow / Quy Trình
|
|
|
|
```mermaid
|
|
graph TD
|
|
Start([Bắt đầu / Start]) --> Prerequisites["1. Yêu cầu Hệ thống - Prerequisites"]
|
|
Prerequisites --> Clone["2. Clone và Install"]
|
|
Clone --> Env["3. Cấu hình Environment - Shared và Service-Specific"]
|
|
Env --> DB["4. Setup Database - Migrate và Seed"]
|
|
DB --> Run["5. Chạy Dự án - Native/Docker/Hybrid"]
|
|
Run --> Dev["6. Development Loop - Watch Mode"]
|
|
Dev --> Test["7. Testing và 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:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
|
|
style End fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
|
|
style Prerequisites fill:#7F8C8D,color:#fff
|
|
style Clone fill:#7F8C8D,color:#fff
|
|
style Env fill:#E67E22,color:#fff
|
|
style DB fill:#E67E22,color:#fff
|
|
style Run fill:#2980B9,color:#fff
|
|
style Dev fill:#2980B9,color:#fff
|
|
style Test fill:#3498DB,color:#fff
|
|
style Mode1 fill:#8E44AD,color:#fff
|
|
style Mode2 fill:#8E44AD,color:#fff
|
|
style Mode3 fill:#8E44AD,color:#fff
|
|
```
|
|
|
|
## 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
|
|
|
|
```bash
|
|
# VI: Clone repository về máy
|
|
git clone <repository-url>
|
|
cd Base
|
|
|
|
# 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:
|
|
|
|
```bash
|
|
# 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).
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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`**:
|
|
|
|
```properties
|
|
# 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.
|
|
|
|
```bash
|
|
# VI: Chạy migration cho iam-service
|
|
./scripts/db/migrate.sh iam-service dev
|
|
|
|
# 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.
|
|
|
|
1. **Khởi động Hạ tầng (Infrastructure)**:
|
|
```bash
|
|
# VI: Khởi động Redis và Traefik chạy ngầm bằng Docker
|
|
cd deployments/local
|
|
docker-compose up -d redis traefik
|
|
cd ../..
|
|
```
|
|
|
|
2. **Chạy Service**:
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# VI: Kiểm tra liveness
|
|
curl http://localhost:5001/health/live
|
|
|
|
# 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**:
|
|
```bash
|
|
# VI: Tìm process đang chiếm port 5001
|
|
lsof -i :5001
|
|
|
|
# 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**:
|
|
```bash
|
|
# 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](kubernetes-local.md) - Triển khai lên K8s Local.
|
|
- [Project Architecture](../../docs/vi/ARCHITECTURE.vi.md) - Tổng quan kiến trúc hệ thống.
|