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.
260 lines
7.1 KiB
Markdown
260 lines
7.1 KiB
Markdown
# Hướng Dẫn Bắt Đầu
|
|
|
|
> **Lưu ý**: Hướng dẫn này giả định bạn đang cài đặt trên macOS hoặc Linux. Người dùng Windows nên sử dụng WSL2.
|
|
|
|
## Mục lục
|
|
|
|
1. [Yêu cầu tiên quyết](#yêu-cầu-tiên-quyết)
|
|
2. [Tổng quan Kiến trúc](#tổng-quan-kiến-trúc)
|
|
3. [Cấu trúc Dự án](#cấu-trúc-dự-án)
|
|
4. [Cài đặt & Thiết lập](#cài-đặt--thiết-lập)
|
|
5. [Quy trình Phát triển](#quy-trình-phát-triển)
|
|
6. [Các Lệnh Thường dùng](#các-lệnh-thường-dùng)
|
|
7. [Xử lý Sự cố](#xử-lý-sự-cố)
|
|
|
|
## Yêu cầu tiên quyết
|
|
|
|
Trước khi bắt đầu, đảm bảo bạn đã cài đặt:
|
|
|
|
* **Node.js**: v20.0.0 trở lên (khuyến nghị v22+ hoặc v25+)
|
|
```bash
|
|
node -v
|
|
# v25.2.1
|
|
```
|
|
* **PNPM**: v8.15.0 trở lên (sử dụng pnpm workspaces)
|
|
```bash
|
|
pnpm -v
|
|
# 8.15.0
|
|
```
|
|
* **Docker & Docker Compose**: v24.0.0 trở lên cho infrastructure cục bộ
|
|
```bash
|
|
docker -v
|
|
# Docker version 29.1.3, build f52814d
|
|
```
|
|
* **Git**: Để quản lý version
|
|
* **Tài khoản Neon**: Serverless PostgreSQL (https://neon.tech)
|
|
|
|
## Tổng quan Kiến trúc
|
|
|
|
GoodGo Platform sử dụng kiến trúc microservices với layer infrastructure chia sẻ.
|
|
|
|
```mermaid
|
|
graph TD
|
|
Client[Client Apps] --> Traefik[Traefik Gateway]
|
|
|
|
Traefik --> IAM[IAM Service]
|
|
Traefik --> Template[Template Service]
|
|
|
|
IAM --> DB[(Neon PostgreSQL)]
|
|
IAM --> Redis[(Redis Cache)]
|
|
IAM --> Kafka[Kafka Events]
|
|
|
|
style Client fill:#7F8C8D,color:#fff
|
|
style Traefik fill:#2980B9,color:#fff
|
|
style IAM fill:#27AE60,color:#fff
|
|
style Template fill:#E67E22,color:#fff
|
|
style DB fill:#8E44AD,color:#fff
|
|
style Redis fill:#F39C12,color:#fff
|
|
style Kafka fill:#3498DB,color:#fff
|
|
```
|
|
|
|
### Color Palette / Bảng màu
|
|
|
|
```mermaid
|
|
graph LR
|
|
A["Primary #2980B9"] --> B["Data/Cache #F39C12"]
|
|
B --> C["Success #27AE60"]
|
|
C --> D["Warning #E67E22"]
|
|
D --> E["Error #C0392B"]
|
|
E --> F["Processing #8E44AD"]
|
|
F --> G["Info #3498DB"]
|
|
G --> H["Neutral #7F8C8D"]
|
|
|
|
style A fill:#2980B9,color:#fff
|
|
style B fill:#F39C12,color:#fff
|
|
style C fill:#27AE60,color:#fff
|
|
style D fill:#E67E22,color:#fff
|
|
style E fill:#C0392B,color:#fff
|
|
style F fill:#8E44AD,color:#fff
|
|
style G fill:#3498DB,color:#fff
|
|
style H fill:#7F8C8D,color:#fff
|
|
```
|
|
|
|
## Cấu trúc Dự án
|
|
|
|
Repository tuân theo cấu trúc monorepo:
|
|
|
|
```
|
|
Base/
|
|
apps/ # Ứng dụng Frontend
|
|
app-admin/ # Admin dashboard application
|
|
app-client/ # Client mobile application (Flutter)
|
|
web-client/ # Next.js web application
|
|
web-docs/ # Documentation website (Next.js)
|
|
services/ # Backend microservices
|
|
iam-service/ # Service xác thực & phân quyền
|
|
_template/ # Template cho service mới
|
|
packages/ # Thư viện chia sẻ (Shared libraries)
|
|
auth-sdk/ # Authentication SDK
|
|
config/ # Shared configuration utilities
|
|
http-client/ # Client HTTP nội bộ
|
|
logger/ # Structured logging (@goodgo/logger)
|
|
tracing/ # OpenTelemetry tracing
|
|
types/ # TypeScript types chia sẻ
|
|
infra/ # Cấu hình Infrastructure
|
|
databases/ # Scripts thiết lập Database
|
|
docker/ # Docker configurations
|
|
observability/ # Prometheus, Grafana, Loki configs
|
|
secrets/ # Secrets management templates
|
|
traefik/ # Cấu hình API Gateway
|
|
deployments/ # Cấu hình Deploy
|
|
local/ # Docker Compose cho dev
|
|
staging/ # Staging environment configs
|
|
production/ # Production Kubernetes manifests
|
|
scripts/ # Automation scripts
|
|
build/ # Build scripts
|
|
db/ # Database utilities
|
|
deploy/ # Deployment scripts
|
|
dev/ # Development helpers
|
|
observability/ # Monitoring setup scripts
|
|
setup/ # Initial setup scripts
|
|
utils/ # Utility scripts
|
|
docs/ # Tài liệu
|
|
en/ # English documentation
|
|
vi/ # Vietnamese documentation
|
|
```
|
|
|
|
## Cài đặt & Thiết lập
|
|
|
|
### 1. Clone Repository
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd Base
|
|
```
|
|
|
|
### 2. Cấu hình Môi trường
|
|
|
|
Mỗi service và infrastructure cục bộ cần biến môi trường. Chúng tôi cung cấp templates sẵn.
|
|
|
|
```bash
|
|
# Khởi tạo setup dự án (copy .env.example sang .env)
|
|
./scripts/setup/init-project.sh
|
|
```
|
|
|
|
### 3. Thiết lập Neon Database
|
|
|
|
Dự án sử dụng Neon (Serverless PostgreSQL) cho mọi môi trường.
|
|
|
|
1. Tạo project tại [neon.tech](https://neon.tech).
|
|
2. Tạo branch tên `dev` (hoặc `main`).
|
|
3. Lấy Connection String từ dashboard.
|
|
4. Cập nhật file `deployments/local/.env.local`:
|
|
|
|
```env
|
|
DATABASE_URL="postgres://user:pass@ep-xyz.region.neon.tech/neondb"
|
|
```
|
|
|
|
### 4. Khởi động Infrastructure
|
|
|
|
Khởi động các dịch vụ hỗ trợ (Redis, Traefik, Observability) bằng Docker Compose.
|
|
|
|
```bash
|
|
cd deployments/local
|
|
docker-compose up -d
|
|
# Expected output: Containers for traefik, redis, kafka created
|
|
```
|
|
|
|
### 5. Cài đặt Dependencies
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### 6. Setup Database Schema
|
|
|
|
Đẩy Prisma schema lên Neon database.
|
|
|
|
```bash
|
|
# Chạy migration cho IAM service
|
|
pnpm --filter @goodgo/iam-service prisma migrate dev
|
|
```
|
|
|
|
### 7. Khởi động Services
|
|
|
|
Chạy tất cả backend services ở chế độ development.
|
|
|
|
```bash
|
|
pnpm dev
|
|
# hoặc chạy service cụ thể
|
|
pnpm --filter @goodgo/iam-service dev
|
|
```
|
|
|
|
## Quy trình Phát triển
|
|
|
|
### Tạo Service Mới
|
|
|
|
1. Copy từ template:
|
|
```bash
|
|
cp -r services/_template services/my-new-service
|
|
```
|
|
2. Cập nhật tên trong `package.json`.
|
|
3. Thêm logic trong `src/modules/`.
|
|
4. Đăng ký trong `deployments/local/docker-compose.yml`.
|
|
|
|
### Thực hiện Thay đổi
|
|
|
|
1. Tạo branch mới: `feature/my-feature`.
|
|
2. Implement thay đổi.
|
|
3. Chạy tests: `pnpm test`.
|
|
4. Commit với conventional commits: `feat(iam): add login endpoint`.
|
|
|
|
## Các Lệnh Thường dùng
|
|
|
|
| Lệnh | Mô tả |
|
|
| :--- | :--- |
|
|
| `pnpm install` | Cài đặt dependencies |
|
|
| `pnpm dev` | Chạy tất cả services (dev mode) |
|
|
| `pnpm build` | Build tất cả packages và services |
|
|
| `pnpm test` | Chạy unit tests |
|
|
| `pnpm lint` | Kiểm tra lỗi cú pháp (Lint) |
|
|
| `docker-compose up -d` | Bật local infra |
|
|
| `docker-compose down` | Tắt local infra |
|
|
|
|
## Xử lý Sự cố
|
|
|
|
### Xung đột Port (Port Conflicts)
|
|
|
|
**Lỗi**: `Bind for 0.0.0.0:80 failed: port is already allocated`
|
|
|
|
**Giải pháp**: Kiểm tra process nào đang dùng port 80 (thường là web server khác) và tắt nó, hoặc đổi port Traefik trong `docker-compose.yml`.
|
|
|
|
```bash
|
|
lsof -i :80
|
|
kill -9 <PID>
|
|
```
|
|
|
|
### Lỗi Kết nối Database
|
|
|
|
**Lỗi**: `P1001: Can't reach database server`
|
|
|
|
**Giải pháp**:
|
|
1. Kiểm tra kết nối internet (Neon là cloud DB).
|
|
2. Kiểm tra `DATABASE_URL` trong `deployments/local/.env.local`.
|
|
3. Đảm bảo IP của bạn được allow trong Neon dashboard.
|
|
|
|
### Gateway Không Tìm Thấy Service
|
|
|
|
**Lỗi**: `404 Not Found` từ api.localhost
|
|
|
|
**Giải pháp**:
|
|
1. Kiểm tra service có đang chạy không.
|
|
2. Kiểm tra Traefik dashboard tại http://localhost:8080.
|
|
3. Kiểm tra labels `PathPrefix` trong `docker-compose.yml`.
|
|
|
|
## Bước Tiếp Theo
|
|
|
|
* [Hướng dẫn Development](development.md) - Chi tiết chuẩn code và quy trình
|
|
* [Tài liệu API](../api/openapi/) - Khám phá các API endpoints
|
|
* [Kiến trúc Hệ thống](../architecture/system-design.md) - Hiểu về thiết kế hệ thống
|