pos-system/docs/vi/guides/troubleshooting.md

Hướng Dẫn Xử Lý Sự Cố (Troubleshooting)

Lưu ý: Hướng dẫn này tập trung vào việc debug GoodGo Microservices Platform trong môi trường phát triển cục bộ (Docker Compose).

Mục lục

1. Chẩn đoán Chung
2. Vấn đề Infrastructure
   • Database (Neon/PostgreSQL)
   • Redis
   • Traefik Gateway
3. Vấn đề Service
   • Service Không Khởi Động
   • Lỗi Prisma/Database
   • Lỗi Authentication
4. Công cụ Debug
5. Câu hỏi Thường Gặp (FAQ)

---

Chẩn đoán Chung

Khi có sự cố, hãy làm theo danh sách kiểm tra sau:

1. Kiểm tra Trạng thái Service:

   cd deployments/local
   docker-compose ps
   

   Tất cả services nên ở trạng thái Up hoặc Running.

2. Xem Logs:

   # Xem logs của service cụ thể
   docker-compose logs -f <service-name>
   
   # Xem 100 dòng cuối của tất cả
   docker-compose logs --tail=100
   

3. Kiểm tra Kết nối:

   • Có thể truy cập Gateway không? curl http://localhost/health
   • Có thể truy cập Dashboard không? http://localhost:8080

---

Vấn đề Infrastructure

Database (Neon/PostgreSQL)

Vấn đề: P1001: Can't reach database server hoặc Connection timed out

• Nguyên nhân 1: Lỗi kết nối Internet (Neon là cloud DB).
• Nguyên nhân 2: Sai DATABASE_URL trong .env.
• Nguyên nhân 3: Địa chỉ IP bị chặn bởi Neon.

Giải pháp:

1. Ping thử: ping neon.tech.
2. Kiểm tra file deployments/local/.env.local. URL nên có dạng: postgres://user:pass@ep-xyz.aws.neon.tech/neondb
3. Vào Neon Dashboard -> Settings, đảm bảo đã chọn "Allow all IPs" hoặc thêm IP hiện tại của bạn.

Vấn đề: P1003: Database does not exist

• Nguyên nhân: Bạn kết nối sai tên database.
• Sửa: Kiểm tra cuối chuỗi kết nối (thường là /neondb). Nếu dùng tên DB tùy chỉnh, đảm bảo nó đã được tạo trên Neon.

Redis

Vấn đề: Redis connection refused hoặc ECONNREFUSED

• Nguyên nhân: Container Redis chưa chạy hoặc sai port mapping.

Giải pháp:

1. Kiểm tra trạng thái: docker-compose ps redis.
2. Khởi động lại: docker-compose restart redis.
3. Xem logs: docker-compose logs redis.
4. Chuỗi kết nối từ services:
   • Bên trong Docker: redis:6379
   • Từ Host: localhost:6379

Traefik Gateway

Vấn đề: 404 Not Found khi gọi API (ví dụ: http://localhost/api/v1/auth)

• Nguyên nhân: Service bị down hoặc Labels cấu hình sai.

Giải pháp:

1. Kiểm tra Traefik Dashboard tại http://localhost:8080.
   • Tìm trong "HTTP Routers" và "Services".
   • Nếu service không hiện, kiểm tra labels trong docker-compose.yml.
2. Đảm bảo PathPrefix trùng khớp với request:

   - "traefik.http.routers.iam.rule=PathPrefix(`/api/v1/auth`)"
   

3. Kiểm tra health checks xem service có healthy không.

Vấn đề: Bad Gateway hoặc Gateway Timeout

• Nguyên nhân: Service bị crash hoặc phản hồi quá lâu.
• Sửa: Xem logs cụ thể của service (docker-compose logs iam-service).

---

Vấn đề Service

Service Không Khởi Động

Triệu chứng: Trạng thái container là Exited (1) hoặc Restarting.

Debug:

1. Xem logs ngay lập tức:

   docker-compose logs iam-service
   

2. Lỗi thường gặp: Config validation error
   • Sửa: Kiểm tra biến môi trường. Chạy ./scripts/setup/init-project.sh để copy .env.
3. Lỗi thường gặp: PrismaClientInitializationError
   • Sửa: Lỗi kết nối database (xem phần Infrastructure).

Lỗi Prisma/Database

Lỗi: P2025: Record to update not found

• Sửa: Lỗi logic. Đảm bảo ID tồn tại trước khi update.

Lỗi: P2002: Unique constraint failed

• Sửa: Bạn đang cố insert dữ liệu trùng lặp (ví dụ: trùng email).

Lỗi: Migration failed

• Sửa:
  1. Xóa thư mục prisma/migrations (chỉ làm ở dev!).
  2. Reset DB: pnpm prisma migrate reset.
  3. Regenerate client: pnpm prisma generate.

Lỗi Authentication

Vấn đề: 401 Unauthorized dù token hợp lệ

• Nguyên nhân 1: Token hết hạn.
• Nguyên nhân 2: Public key mismatch (Service không verify được token do IAM ký).
• Nguyên nhân 3: Lệch giờ (Thời gian Docker khác Host).

Giải pháp:

1. Kiểm tra logs xem lỗi verify JWT cụ thể.
2. Restart services để refresh keys.
3. Sync thời gian Docker: restart Docker Desktop.

---

Công cụ Debug

1. Truy cập Shell của Container

Để xem files hoặc chạy lệnh bên trong container:

docker-compose exec iam-service sh
# hoặc /bin/bash

2. Kiểm tra Database (Prisma Studio)

Giao diện trực quan để xem/sửa dữ liệu:

pnpm --filter @goodgo/iam-service prisma studio
# Mở http://localhost:5555

3. Kiểm tra Redis

docker-compose exec redis redis-cli
> PING
PONG
> KEYS *
1) "user:123:session"

4. Test API Trực tiếp

Dùng curl hoặc Postman.

# Health Check
curl -v http://localhost/api/v1/auth/health/live

# Login (ví dụ)
curl -X POST http://localhost/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com", "password":"password"}'

---

Câu hỏi Thường Gặp (FAQ)

H: Tại sao thay đổi của tôi không cập nhật? Đ: Nếu sửa .env hoặc docker-compose.yml, bạn phải restart:

docker-compose down && docker-compose up -d

Nếu sửa code, hot-reloading sẽ tự chạy. Nếu không, restart container.

H: Làm sao để reset toàn bộ hệ thống? Đ: Cẩn thận, lệnh này xóa toàn bộ dữ liệu!

docker-compose down -v
# -v xóa cả volumes (dữ liệu Redis, v.v.)

H: Máy tính chạy rất chậm khi bật dự án. Đ: Docker tốn nhiều RAM.

1. Tắt các service không dùng (ví dụ future-service).
2. Tăng giới hạn resource trong cài đặt Docker Desktop.