11f2bf26e6
Some checks failed
CI / Lint → Typecheck → Test → Build (22) (push) Failing after 29s
CI / E2E Tests (push) Has been skipped
CodeQL Analysis / CodeQL (javascript-typescript) (push) Failing after 2m42s
Deploy / Build Web Image (push) Failing after 27s
Deploy / Build AI Services Image (push) Failing after 29s
E2E Tests / Playwright E2E (push) Failing after 43s
Deploy / Build API Image (push) Failing after 1m31s
Security Scanning / Dependency Audit (pnpm) (push) Failing after 6s
Security Scanning / Trivy Scan — API Image (push) Failing after 5m35s
Security Scanning / Trivy Scan — AI Services Image (push) Failing after 3m45s
Deploy / Deploy to Staging (push) Has been skipped
Deploy / Smoke Test Staging (push) Has been skipped
Deploy / Deploy to Production (push) Has been skipped
Deploy / Smoke Test Production (push) Has been skipped
Deploy / Rollback Staging (push) Has been skipped
Deploy / Rollback Production (push) Has been skipped
Security Scanning / Trivy Scan — Web Image (push) Failing after 13m51s
Security Scanning / Trivy Filesystem Scan (push) Failing after 14m46s
Security Scanning / Security Gate (push) Has been cancelled
156 lines
4.6 KiB
Markdown
156 lines
4.6 KiB
Markdown
# Môi Trường Phát Triển
|
|
|
|
## Yêu Cầu Cài Đặt
|
|
|
|
- **Docker Engine 24+** & Docker Compose v2
|
|
- **Node.js 22 LTS**
|
|
- **pnpm 10.27+** — cài đặt qua `corepack enable && corepack prepare pnpm@latest --activate`
|
|
|
|
## Khởi Động Nhanh
|
|
|
|
```bash
|
|
# 1. Sao chép các biến môi trường
|
|
cp .env.example .env
|
|
|
|
# 2. Khởi động tất cả dịch vụ hạ tầng
|
|
docker compose up -d
|
|
|
|
# 3. Kiểm tra tất cả dịch vụ đang hoạt động bình thường
|
|
docker compose ps
|
|
|
|
# 4. Cài đặt các phụ thuộc
|
|
pnpm install
|
|
|
|
# 5. Tạo Prisma client
|
|
pnpm db:generate
|
|
|
|
# 6. Chạy các migration cơ sở dữ liệu
|
|
pnpm db:migrate:dev
|
|
|
|
# 7. Seed dữ liệu vào cơ sở dữ liệu (tuỳ chọn)
|
|
pnpm db:seed
|
|
|
|
# 8. Khởi động API và Web ở chế độ phát triển
|
|
pnpm dev
|
|
```
|
|
|
|
API chạy tại `http://localhost:3001/api/v1`, Web tại `http://localhost:3000`.
|
|
|
|
> **Swagger UI**: `http://localhost:3001/api/v1/docs` — tài liệu API tương tác.
|
|
|
|
## Các Dịch Vụ Hạ Tầng
|
|
|
|
| Dịch vụ | Cổng | Mô tả | Bảng điều khiển/UI |
|
|
|---------|---------|-------------|--------------|
|
|
| PostgreSQL + PostGIS | 5432 | Cơ sở dữ liệu với truy vấn không gian địa lý | — |
|
|
| Redis | 6379 | Cache, phiên đăng nhập, hàng đợi | — |
|
|
| Typesense | 8108 | Công cụ tìm kiếm toàn văn bản | `http://localhost:8108/health` |
|
|
| MinIO | 9000 / 9001 | Lưu trữ đối tượng tương thích S3 | `http://localhost:9001` (console) |
|
|
| AI Services | 8000 | FastAPI — AVM + kiểm duyệt nội dung | `http://localhost:8000/health` |
|
|
| Prometheus | 9090 | Thu thập số liệu giám sát | `http://localhost:9090` |
|
|
| Grafana | 3002 | Bảng điều khiển & giám sát | `http://localhost:3002` |
|
|
|
|
## Các Lệnh Thông Dụng
|
|
|
|
### Docker Compose
|
|
|
|
```bash
|
|
# Khởi động các dịch vụ
|
|
docker compose up -d
|
|
|
|
# Xem nhật ký (tất cả hoặc từng dịch vụ cụ thể)
|
|
docker compose logs -f
|
|
docker compose logs -f postgres
|
|
|
|
# Dừng các dịch vụ (dữ liệu được giữ nguyên trong volume)
|
|
docker compose down
|
|
|
|
# Dừng và xoá toàn bộ dữ liệu
|
|
docker compose down -v
|
|
|
|
# Khởi động lại một dịch vụ đơn lẻ
|
|
docker compose restart redis
|
|
|
|
# Kiểm tra tình trạng dịch vụ
|
|
docker compose ps
|
|
```
|
|
|
|
### Phát Triển
|
|
|
|
```bash
|
|
pnpm dev # Khởi động tất cả ứng dụng ở chế độ theo dõi
|
|
pnpm build # Build tất cả các gói
|
|
pnpm lint # ESLint trên toàn bộ monorepo
|
|
pnpm typecheck # Kiểm tra kiểu TypeScript
|
|
pnpm format # Định dạng bằng Prettier
|
|
pnpm test # Chạy kiểm thử đơn vị/tích hợp
|
|
```
|
|
|
|
### Cơ Sở Dữ Liệu
|
|
|
|
```bash
|
|
pnpm db:generate # Tạo lại Prisma client
|
|
pnpm db:migrate:dev # Tạo và áp dụng các migration
|
|
pnpm db:seed # Seed dữ liệu vào cơ sở dữ liệu
|
|
pnpm db:studio # Mở Prisma Studio (trình chỉnh sửa trực quan)
|
|
pnpm db:reset # Đặt lại cơ sở dữ liệu (thao tác phá huỷ dữ liệu)
|
|
```
|
|
|
|
### Kiểm Thử E2E
|
|
|
|
```bash
|
|
pnpm test:e2e # Chạy tất cả kiểm thử E2E
|
|
pnpm test:e2e:api # Chỉ kiểm thử API
|
|
pnpm test:e2e:web # Chỉ kiểm thử giao diện Web
|
|
pnpm test:e2e:report # Mở báo cáo kiểm thử HTML
|
|
```
|
|
|
|
## Kết Nối Đến Các Dịch Vụ
|
|
|
|
### PostgreSQL
|
|
|
|
```bash
|
|
# Qua psql
|
|
psql postgresql://goodgo:goodgo_secret@localhost:5432/goodgo
|
|
|
|
# Xác minh PostGIS
|
|
psql postgresql://goodgo:goodgo_secret@localhost:5432/goodgo -c "SELECT PostGIS_Version();"
|
|
```
|
|
|
|
### Redis
|
|
|
|
```bash
|
|
redis-cli -p 6379 ping
|
|
```
|
|
|
|
### Typesense
|
|
|
|
```bash
|
|
curl http://localhost:8108/health
|
|
```
|
|
|
|
### MinIO
|
|
|
|
- **API**: `http://localhost:9000`
|
|
- **Console**: `http://localhost:9001` (đăng nhập bằng `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` từ file `.env`)
|
|
|
|
### AI Services
|
|
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
```
|
|
|
|
### Grafana
|
|
|
|
- **URL**: `http://localhost:3002`
|
|
- **Đăng nhập**: `admin` / `admin` (mặc định, có thể cấu hình qua `.env`)
|
|
|
|
## Xử Lý Sự Cố
|
|
|
|
- **Xung đột cổng** — Thay đổi cổng trong `.env` (ví dụ: `DB_PORT=5433`)
|
|
- **Lỗi quyền truy cập** — Chạy `docker compose down -v` rồi khởi động lại
|
|
- **PostGIS không khả dụng** — Đảm bảo đang sử dụng image `postgis/postgis:16-3.4`
|
|
- **Prisma client lỗi thời** — Chạy `pnpm db:generate` sau khi kéo các thay đổi schema
|
|
- **AI service không khởi động được** — Kiểm tra `docker compose logs ai-services` để xem lỗi phụ thuộc Python
|
|
- **Typesense không khoẻ mạnh** — Xác minh `TYPESENSE_API_KEY` khớp trong `.env` và cấu hình Docker
|