Files

Ho Ngoc Hai 495618ded7 docs: Thêm tài liệu kiến trúc bảo mật, hướng sự kiện, nhất quán dữ liệu, khả năng quan sát và caching bằng tiếng Việt, đồng thời cập nhật các tài liệu hướng dẫn và kiến trúc hiện có.

2026-01-07 10:22:42 +07:00

6.1 KiB

Raw Blame History

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.

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
```
node -v
# v20.10.0
```
PNPM: v8.0.0 trở lên (sử dụng pnpm workspaces)
```
pnpm -v
# 8.12.0
```
Docker & Docker Compose: Cho infrastructure cục bộ
```
docker -v
# Docker version 24.0.0
```
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ẻ.

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 Traefik fill:#e1f5ff
    style DB fill:#f0e1ff
    style Redis fill:#fff4e1

Cấu trúc Dự án

Repository tuân theo cấu trúc monorepo:

Base/
├── apps/                 # Ứng dụng Frontend
│   ├── web-client/       # Next.js web application
│   └── mobile-client/    # Flutter mobile application
├── 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)
│   ├── logger/           # Structured logging
│   ├── types/            # TypeScript types chia sẻ
│   └── http-client/      # Client HTTP nội bộ
├── infra/                # Cấu hình Infrastructure
│   ├── traefik/          # Cấu hình API Gateway
│   └── databases/        # Scripts thiết lập Database
├── deployments/          # Cấu hình Deploy
│   ├── local/            # Docker Compose cho dev
│   └── k8s/              # Kubernetes manifests
└── docs/                 # Tài liệu

Cài đặt & Thiết lập

1. Clone Repository

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.

# 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.

Tạo project tại neon.tech.
Tạo branch tên dev (hoặc main).
Lấy Connection String từ dashboard.
Cập nhật file deployments/local/.env.local:

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.

cd deployments/local
docker-compose up -d
# Expected output: Containers for traefik, redis, kafka created

5. Cài đặt Dependencies

pnpm install

6. Setup Database Schema

Đẩy Prisma schema lên Neon database.

# 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.

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

Copy từ template:

cp -r services/_template services/my-new-service

Cập nhật tên trong package.json.
Thêm logic trong src/modules/.
Đăng ký trong deployments/local/docker-compose.yml.

Thực hiện Thay đổi

Tạo branch mới: feature/my-feature.
Implement thay đổi.
Chạy tests: pnpm test.
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.

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:

Kiểm tra kết nối internet (Neon là cloud DB).
Kiểm tra DATABASE_URL trong deployments/local/.env.local.
Đả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