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.
2026-01-08 17:01:14 +07:00
parent b441a7757a
commit 51bc4c8ec0
4 changed files with 133 additions and 77 deletions
--- 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)
--- 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 <service-name>` |
+| 🌐 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`
--- 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<br/>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`<br/>Verify `DATABASE_URL` trong secrets<br/>Đảm bảo DB accessible qua `host.docker.internal` |
+| 🟡 **Pending LoadBalancer** | Service External-IP hiển thị `<pending>` | 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`)<br/>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 <POD_NAME> -n iam-local          # Thông tin chi tiết pod + events
+kubectl logs -f <POD_NAME> -n iam-local               # Stream logs
+kubectl exec -it <POD_NAME> -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 <POD_NAME> -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 <pod-name>` | 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

--- 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<br/>API Gateway<br/>:80, :8080]
-    IAM[iam-service<br/>:5001]
-    Admin[web-admin<br/>:3000]
-    WebClient[web-client<br/>:3001]
-    Redis[(Redis<br/>:6379)]
-    Postgres[(PostgreSQL<br/>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<br/>Browser] --> Traefik
+    
+    Traefik[🌐 Traefik<br/>API Gateway<br/>:80, :8080]
+    
+    Traefik --> IAM[🔐 IAM Service<br/>Authentication<br/>:5001]
+    Traefik --> Admin[⚙️ Web Admin<br/>Dashboard<br/>:3000]
+    Traefik --> WebClient[🌍 Web Client<br/>Application<br/>:3001]
+    
+    IAM --> Redis[(💾 Redis<br/>Cache<br/>:6379)]
+    IAM --> DB[(🗄️ PostgreSQL<br/>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 :<port>` |
+| **Service không khởi động** | Kiểm tra logs: `docker-compose logs <service-name>` |
+| **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