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

Sơ Đồ Xử Lý Sự Cố

flowchart TD
 Start([ Phát Hiện Sự Cố]) --> CheckStatus{Kiểm tra<br/>Trạng thái Service}

 CheckStatus -->|Tất cả Running| CheckLogs[ Xem Logs]
 CheckStatus -->|Một số Down| IdentifyService[ Xác định Service<br/>Bị Lỗi]

 IdentifyService --> ServiceType{Loại Service?}

 ServiceType -->|Infrastructure| InfraCheck[ Kiểm tra<br/>Infrastructure]
 ServiceType -->|Application| AppCheck[ Kiểm tra<br/>Application]

 InfraCheck --> DBCheck{Database?}
 InfraCheck --> RedisCheck{Redis?}
 InfraCheck --> TraefikCheck{Traefik?}

 DBCheck -->|Có| DBSolution[ Kiểm tra DATABASE_URL<br/> Verify kết nối Neon<br/> Kiểm tra IP whitelist]
 RedisCheck -->|Có| RedisSolution[ Restart Redis<br/> Kiểm tra port mapping<br/> Verify connection string]
 TraefikCheck -->|Có| TraefikSolution[ Kiểm tra labels<br/> Verify PathPrefix<br/> Kiểm tra health status]

 AppCheck --> ErrorType{Loại Lỗi?}

 ErrorType -->|Config| ConfigFix[ Kiểm tra .env variables<br/> Chạy init-project.sh]
 ErrorType -->|Prisma| PrismaFix[ Kiểm tra migrations<br/> Regenerate client<br/> Reset database]
 ErrorType -->|Auth| AuthFix[ Kiểm tra token expiry<br/> Verify keys<br/> Sync thời gian Docker]

 CheckLogs --> LogAnalysis{Log Hiện<br/>Lỗi?}
 LogAnalysis -->|Có| ErrorType
 LogAnalysis -->|Không| ConnCheck[ Kiểm tra Kết nối]

 ConnCheck --> GatewayTest{Gateway<br/>Truy Cập Được?}
 GatewayTest -->|Không| TraefikCheck
 GatewayTest -->|Có| ServiceTest{Service<br/>Truy Cập Được?}

 ServiceTest -->|Không| AppCheck
 ServiceTest -->|Có| Resolved([ Đã Giải Quyết])

 DBSolution --> Restart[ Restart Services]
 RedisSolution --> Restart
 TraefikSolution --> Restart
 ConfigFix --> Restart
 PrismaFix --> Restart
 AuthFix --> Restart

 Restart --> Verify{Đã Sửa<br/>Xong?}
 Verify -->|Có| Resolved
 Verify -->|Không| DeepDebug[ Debug Sâu<br/>Hơn]

 DeepDebug --> ContainerShell[Truy cập Container Shell]
 DeepDebug --> PrismaStudio[Dùng Prisma Studio]
 DeepDebug --> RedisInspect[Kiểm tra Redis]
 DeepDebug --> APITest[Test API Trực tiếp]

 style Start fill:#1a1a2e,color:#fff
 style Resolved fill:#0f3460,color:#fff
 style CheckStatus fill:#16213e,color:#fff
 style ServiceType fill:#16213e,color:#fff
 style ErrorType fill:#16213e,color:#fff
 style DBCheck fill:#16213e,color:#fff
 style RedisCheck fill:#16213e,color:#fff
 style TraefikCheck fill:#16213e,color:#fff
 style GatewayTest fill:#16213e,color:#fff
 style ServiceTest fill:#16213e,color:#fff
 style Verify fill:#16213e,color:#fff
 style LogAnalysis fill:#16213e,color:#fff
 style InfraCheck fill:#1a1a40,color:#fff
 style AppCheck fill:#1a1a40,color:#fff
 style DBSolution fill:#0f4c75,color:#fff
 style RedisSolution fill:#0f4c75,color:#fff
 style TraefikSolution fill:#0f4c75,color:#fff
 style ConfigFix fill:#0f4c75,color:#fff
 style PrismaFix fill:#0f4c75,color:#fff
 style AuthFix fill:#0f4c75,color:#fff
 style Restart fill:#3282b8,color:#fff
 style DeepDebug fill:#1b262c,color:#fff
 style IdentifyService fill:#1a1a40,color:#fff
 style CheckLogs fill:#1a1a40,color:#fff
 style ConnCheck fill:#1a1a40,color:#fff
 style ContainerShell fill:#0f3460,color:#fff
 style PrismaStudio fill:#0f3460,color:#fff
 style RedisInspect fill:#0f3460,color:#fff
 style APITest fill:#0f3460,color:#fff

---

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.

---

Mẹo Nhanh (Quick Tips)

Lệnh Debug Nhanh

# Kiểm tra nhanh các service bị lỗi
docker-compose ps | grep -v "Up"

# Xem logs tất cả services (50 dòng cuối)
docker-compose logs -f --tail=50

# Restart service cụ thể không rebuild
docker-compose restart iam-service

# Rebuild và restart service
docker-compose up -d --build iam-service

# Kiểm tra resource usage
docker stats --no-stream

# Dọn dẹp resources không dùng
docker system prune -a --volumes

Các Pattern Lỗi Thường Gặp

Pattern Lỗi	Nguyên nhân Có thể	Cách Sửa Nhanh
ECONNREFUSED	Service chưa chạy	docker-compose restart <service>
P1001	Database không kết nối được	Kiểm tra DATABASE_URL và internet
P2002	Dữ liệu trùng lặp	Kiểm tra unique constraints
401 Unauthorized	Token hết hạn/không hợp lệ	Refresh token hoặc đăng nhập lại
404 Not Found	Route sai/service down	Kiểm tra Traefik dashboard
502 Bad Gateway	Service bị crash	Xem logs service
Config validation error	Thiếu biến môi trường	Chạy init-project.sh

Mẹo Phân Tích Logs

Những gì cần tìm trong logs:

• Server listening on port XXXX = Service khởi động thành công
• Warning: = Vấn đề không nghiêm trọng
• Error: = Vấn đề nghiêm trọng cần xử lý
• Trace: = Chi tiết luồng thực thi

Các pattern grep hữu ích:

# Tìm tất cả lỗi
docker-compose logs | grep -i error

# Tìm lỗi của service cụ thể
docker-compose logs iam-service | grep -i "error\|failed"

# Tìm vấn đề database connection
docker-compose logs | grep -i "prisma\|database\|p1001\|p1003"

# Tìm vấn đề auth
docker-compose logs | grep -i "unauthorized\|401\|jwt\|token"

Quản Lý Tài Nguyên

Docker Resources Khuyến nghị:

• RAM: Tối thiểu 4GB, Khuyến nghị 8GB
• CPU: Tối thiểu 2 cores, Khuyến nghị 4 cores
• Disk: Tối thiểu 10GB dung lượng trống

Kiểm tra resource usage:

# Tổng quan hệ thống
docker system df

# Theo từng container
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

Lệnh dọn dẹp:

# Xóa containers đã dừng
docker container prune

# Xóa images không dùng
docker image prune -a

# Xóa volumes không dùng ( mất dữ liệu!)
docker volume prune

# Tùy chọn hạt nhân ( xóa mọi thứ!)
docker system prune -a --volumes

Best Practices

1. Luôn kiểm tra logs trước khi thay đổi gì
2. Dùng Traefik Dashboard (http://localhost:8080) để verify routing
3. Giữ .env.local cập nhật với credentials đúng
4. Đừng xóa volumes trừ khi muốn mất dữ liệu
5. Restart Docker Desktop nếu gặp vấn đề network lạ
6. Dùng docker-compose down && up sau khi thay đổi .env
7. Giữ services đang chạy mà bạn đang develop
8. Tắt services không dùng để tiết kiệm tài nguyên

Visual Indicators

Khi đọc logs, chú ý các pattern sau:

• [INFO] = Hoạt động bình thường
• [WARN] = Cần theo dõi
• [ERROR] = Cần xử lý ngay
• [DEBUG] = Thông tin chi tiết
• [TRACE] = Luồng thực thi rất chi tiết

Tài Liệu Liên Quan

• Hướng dẫn Local Deployment - Hướng dẫn setup
• Hướng dẫn Development - Workflow phát triển
• Hướng dẫn Kubernetes Local - Troubleshooting K8s
• Hướng dẫn Neon Database - Quản lý database