From 51bc4c8ec08f675c08cd2f8f3eb5d8001541a220 Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Thu, 8 Jan 2026 17:01:14 +0700 Subject: [PATCH] feat(docs): Update guides with enhanced troubleshooting sections and visual clarity - Added detailed troubleshooting tables in the IAM migration, observability, and Kubernetes local deployment guides to assist users in diagnosing common issues. - Improved Mermaid diagrams with clearer component labels and color coding for better visualization. - Enhanced the structure of the Vietnamese documentation to align with the English version, ensuring consistency across guides. - Included quick tips and common issues sections to facilitate user navigation and understanding. --- docs/en/guides/iam-migration.md | 14 +++-- docs/en/guides/observability.md | 30 ++++++---- docs/vi/guides/kubernetes-local.md | 75 ++++++++++++------------ docs/vi/guides/local-deployment.md | 91 +++++++++++++++++++++--------- 4 files changed, 133 insertions(+), 77 deletions(-) diff --git a/docs/en/guides/iam-migration.md b/docs/en/guides/iam-migration.md index 4b38199f..3c540554 100644 --- a/docs/en/guides/iam-migration.md +++ b/docs/en/guides/iam-migration.md @@ -374,11 +374,15 @@ If you encounter issues during migration: - ✅ Monitor gradual rollout - ✅ Prepare rollback plan -**Common Issues:** -- Database connection errors → Check DATABASE_URL -- Missing environment variables → Verify .env file -- Type errors → Run `pnpm prisma generate` -- Service not starting → Check logs with `docker-compose logs` +### Common Issues & Solutions + +| Issue | Cause | Solution | +|-------|-------|----------| +| 🔴 Migration failed | Database connection | Check `DATABASE_URL` in `.env` | +| 🔴 Service won't start | Missing env vars | Verify all env vars are set | +| 🟡 Slow performance | Database indexes | Run Prisma migrations completely | +| 🟡 Connection timeout | Network issues | Check firewall & security groups | +| 🔵 New endpoints 404 | Routing config | Update Traefik/Ingress config | **Visual Indicators:** - 🔵 Old Components (Unchanged) diff --git a/docs/en/guides/observability.md b/docs/en/guides/observability.md index a1f09633..c424f7b5 100644 --- a/docs/en/guides/observability.md +++ b/docs/en/guides/observability.md @@ -218,18 +218,17 @@ Create custom dashboards in Grafana: ## Color Palette Reference -This guide uses a dark color palette optimized for readability: +Diagrams use a dark color palette for better readability: -| Category | Color Code | Usage | -|----------|------------|-------| -| **Services** | `#2d3748` | Microservices subgraph | -| **Collection** | `#2c5282` | Data collection components | -| **Storage** | `#2f855a` | Database nodes | -| **Visualization** | `#744210` | Grafana/UI components | -| **Service Nodes** | `#4a5568` | Individual services | -| **Collectors** | `#3182ce` | Prometheus/Promtail | -| **Databases** | `#38a169` | Storage systems | -| **Dashboards** | `#d69e2e` | Grafana node | +| Component Type | Fill Color | Stroke Color | Purpose | +|----------------|------------|--------------|----------| +| 🚀 Services | `#e94560` | `#c81e3b` | Microservices (red) | +| 📊 Collectors | `#f39c12` | `#d68910` | Data collection (orange) | +| 💾 Storage | `#3498db` | `#2874a6` | Storage (blue) | +| 📊 Visualization | `#9b59b6` | `#7d3c98` | Visualization (purple) | +| 📦 Subgraphs | `#1a1a2e` - `#533483` | `#16213e` - `#0f3460` | Logical groups | + +**All text uses `color:#ffffff` (white) for readability on dark backgrounds** ## Quick Tips @@ -274,6 +273,15 @@ sum(metric_name) by (label) ## Troubleshooting +### Common Issues + +| Issue | Symptoms | Solution | +|-------|----------|----------| +| ⚠️ No logs visible | Grafana Explore shows no logs | Check Promtail is running: `docker ps \| grep promtail` | +| 📊 Missing metrics | Services don't appear in Prometheus targets | Check service `/metrics` endpoint | +| 🔴 Container won't start | `docker ps` doesn't show container | View logs: `docker-compose logs ` | +| 🌐 Network issue | Services can't connect | Create network: `docker network create microservices-network` | + ### Logs Not Appearing in Loki 1. Check Promtail logs: `docker logs promtail` diff --git a/docs/vi/guides/kubernetes-local.md b/docs/vi/guides/kubernetes-local.md index 33750c27..afc59f41 100644 --- a/docs/vi/guides/kubernetes-local.md +++ b/docs/vi/guides/kubernetes-local.md @@ -252,41 +252,40 @@ kubectl delete namespace iam-local ## Quick Tips -### 🎯 Lệnh Kubectl Hữu Ích + +### 🔍 Các Vấn Đề Thường Gặp & Giải Pháp + +| Vấn đề | Triệu chứng | Giải pháp | +|--------|-------------|-----------| +| 🔴 **ImagePullBackOff** | Pod bị kẹt ở trạng thái `ImagePullBackOff` | Đặt `imagePullPolicy: Never` trong deployment YAML
Chạy `kind load docker-image` nếu dùng Kind | +| 🔴 **CrashLoopBackOff** | Pod liên tục restart | Kiểm tra logs với `kubectl logs`
Verify `DATABASE_URL` trong secrets
Đảm bảo DB accessible qua `host.docker.internal` | +| 🟡 **Pending LoadBalancer** | Service External-IP hiển thị `` | Bình thường trên local—dùng `kubectl port-forward` thay thế | +| 🟡 **Connection Refused** | Không kết nối được sau port-forward | Kiểm tra pod đang `Running` (không phải `CrashLoopBackOff`)
Verify port mapping chính xác | + +### 📖 Tham Chiếu Lệnh Thiết Yếu ```bash -# Xem tất cả resources trong namespace -kubectl get all -n iam-local +# 🔍 Debugging +kubectl get pods -n iam-local -w # Theo dõi pods real-time +kubectl describe pod -n iam-local # Thông tin chi tiết pod + events +kubectl logs -f -n iam-local # Stream logs +kubectl exec -it -n iam-local -- /bin/sh # Shell vào container -# Xem logs của tất cả pods với label -kubectl logs -f -n iam-local -l app=iam-service --tail=100 +# 🔄 Quản Lý Image +docker build -t service:local -f Dockerfile . # Build image +kind load docker-image service:local --name desktop # Load vào Kind cluster +docker images | grep service # Liệt kê local images -# Exec vào pod để debug -kubectl exec -it -n iam-local deployment/iam-service -- sh +# 🚀 Deploy Nhanh +kubectl apply -f deployment.yaml -n iam-local # Deploy single manifest +kubectl apply -f . -n iam-local # Deploy tất cả files trong thư mục +kubectl rollout restart deployment/iam-service -n iam-local # Force restart pods -# Xem resource usage -kubectl top pods -n iam-local - -# Restart deployment -kubectl rollout restart deployment/iam-service -n iam-local - -# Xem rollout history -kubectl rollout history deployment/iam-service -n iam-local - -# Rollback về version trước -kubectl rollout undo deployment/iam-service -n iam-local +# 🧹 Cleanup +kubectl delete pod -n iam-local --force # Force delete pod bị kẹt +kubectl delete namespace iam-local --force --grace-period=0 # Force delete namespace ``` -### 🔍 Debug Patterns - -| Vấn đề | Lệnh kiểm tra | Giải pháp | -|--------|--------------|----------| -| Pod không start | `kubectl describe pod -n iam-local ` | Kiểm tra Events section | -| Image pull failed | `kubectl get events -n iam-local` | Đảm bảo `imagePullPolicy: IfNotPresent` | -| Service unreachable | `kubectl get svc -n iam-local` | Kiểm tra port mapping | -| Config issues | `kubectl get configmap -n iam-local -o yaml` | Verify config values | -| Secret issues | `kubectl get secret -n iam-local` | Check secret exists | - ### 📋 Deployment Checklist - [ ] ✅ Docker Desktop Kubernetes enabled @@ -337,14 +336,20 @@ kubectl describe node docker-desktop 7. **Enable logging** để dễ debug 8. **Regular cleanup** các resources không dùng -### 🎨 Visual Indicators +### 🎨 Trạng Thái Visual -Khi đọc pod status: -- 🟢 `Running` = Pod hoạt động bình thường -- 🟡 `Pending` = Đang chờ scheduling -- 🔴 `CrashLoopBackOff` = Pod liên tục crash -- 🔵 `ContainerCreating` = Đang tạo container -- ⚠️ `ImagePullBackOff` = Không pull được image +- 🟢 **Running** - Service hoạt động bình thường +- 🟡 **Pending** - Đang chờ resources +- 🔴 **CrashLoopBackOff** - Service liên tục fail (kiểm tra logs!) +- 🔵 **ContainerCreating** - Pod đang khởi động +- ⚫ **Terminating** - Pod đang tắt + +### 💡 Pro Tips + +1. **⚡ Fast Rebuild**: Để iterate nhanh, dùng `kubectl rollout restart deployment/iam-service -n iam-local` sau khi rebuild image +2. **🔍 Watch Mode**: Dùng flag `-w` để theo dõi resources update real-time +3. **📝 YAML Validation**: Chạy `kubectl apply --dry-run=client -f file.yaml` để validate trước khi apply +4. **🎯 Label Filtering**: Dùng `-l app=iam-service` để filter resources theo label thay vì gõ pod names ### 🔗 Tài Liệu Tham Khảo diff --git a/docs/vi/guides/local-deployment.md b/docs/vi/guides/local-deployment.md index 73ab3496..a2c7ea00 100644 --- a/docs/vi/guides/local-deployment.md +++ b/docs/vi/guides/local-deployment.md @@ -227,35 +227,74 @@ docker-compose logs traefik ```mermaid graph TB - Client([Client]) - Traefik[Traefik
API Gateway
:80, :8080] - IAM[iam-service
:5001] - Admin[web-admin
:3000] - WebClient[web-client
:3001] - Redis[(Redis
:6379)] - Postgres[(PostgreSQL
Neon)] - - Client --> Traefik - Traefik --> IAM - Traefik --> Admin - Traefik --> WebClient - IAM --> Redis - IAM --> Postgres - - style Client fill:#1a1a2e,stroke:#4a4e69,stroke-width:2px,color:#fff - style Traefik fill:#0f3460,stroke:#16213e,stroke-width:3px,color:#fff - style IAM fill:#533483,stroke:#301934,stroke-width:2px,color:#fff - style Admin fill:#533483,stroke:#301934,stroke-width:2px,color:#fff - style WebClient fill:#533483,stroke:#301934,stroke-width:2px,color:#fff - style Redis fill:#c9184a,stroke:#590d22,stroke-width:2px,color:#fff - style Postgres fill:#c9184a,stroke:#590d22,stroke-width:2px,color:#fff + Client[👤 Client
Browser] --> Traefik + + Traefik[🌐 Traefik
API Gateway
:80, :8080] + + Traefik --> IAM[🔐 IAM Service
Authentication
:5001] + Traefik --> Admin[⚙️ Web Admin
Dashboard
:3000] + Traefik --> WebClient[🌍 Web Client
Application
:3001] + + IAM --> Redis[(💾 Redis
Cache
:6379)] + IAM --> DB[(🗄️ PostgreSQL
Neon Database)] + + classDef client fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#eee + classDef gateway fill:#0f3460,stroke:#16213e,stroke-width:3px,color:#eee + classDef service fill:#16213e,stroke:#533483,stroke-width:2px,color:#eee + classDef frontend fill:#1a1a40,stroke:#6c5ce7,stroke-width:2px,color:#eee + classDef data fill:#2d132c,stroke:#801336,stroke-width:2px,color:#eee + + class Client client + class Traefik gateway + class IAM service + class Admin,WebClient frontend + class Redis,DB data ``` **Chú Giải:** -- 🌐 **Client**: Người dùng/trình duyệt bên ngoài -- 🚪 **Traefik**: API Gateway và router -- 🔧 **Services**: Microservices backend -- 💾 **Storage**: Redis cache và PostgreSQL database +- 👤 **Client**: Người dùng truy cập qua trình duyệt +- 🌐 **Gateway**: Traefik API Gateway (định tuyến tự động) +- 🔐 **Backend**: IAM Service (xác thực) +- ⚙️ **Frontend**: Ứng dụng Web Admin & Client +- 💾 **Storage**: Redis cache & PostgreSQL database + +## Quick Tips + +### 🚨 Các Vấn Đề Thường Gặp + +| Vấn Đề | Giải Pháp | +|--------|-----------| +| **Xung đột port** | Kiểm tra port 80/5001/6379 đã được sử dụng: `lsof -i :` | +| **Service không khởi động** | Kiểm tra logs: `docker-compose logs ` | +| **Kết nối database** | Xác minh `DATABASE_URL` trong `.env.local` chính xác | +| **Kết nối Redis** | Đảm bảo Redis healthy: `docker-compose exec redis redis-cli ping` | +| **Traefik routing** | Kiểm tra dashboard tại http://localhost:8080 để xem trạng thái routes | + +### 🎯 Development Workflow + +```bash +# Restart nhanh (thay đổi code) +docker-compose restart iam-service + +# Rebuild đầy đủ (thay đổi dependencies) +docker-compose up -d --build iam-service + +# Clean restart (vấn đề database) +docker-compose down -v && docker-compose up -d +``` + +### 🔐 Security Checklist + +- ✅ Thay đổi `JWT_SECRET` mặc định (tối thiểu 32 ký tự) +- ✅ Sử dụng `.env.local` riêng cho từng môi trường (không commit) +- ✅ Xác minh CORS origins khớp với frontend URLs +- ✅ Bật HTTPS trong production (không cần cho local) + +### 📊 Monitoring + +- **Traefik Dashboard**: http://localhost:8080 - Xem tất cả routes và services +- **Service Health**: http://localhost/api/v1/auth/health - Kiểm tra trạng thái service +- **Redis CLI**: `docker-compose exec redis redis-cli` - Query cache trực tiếp ## Tài Liệu Tham Khảo