admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): Update guides with enhanced troubleshooting sections and visual clarity

Browse Source 
- 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.
This commit is contained in:
Ho Ngoc Hai
2026-01-08 17:01:14 +07:00
parent b441a7757a
commit 51bc4c8ec0
4 changed files with 133 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/en/guides/iam-migration.md
View File

@@ -374,11 +374,15 @@ If you encounter issues during migration:
- ✅ Monitor gradual rollout - ✅ Monitor gradual rollout
- ✅ Prepare rollback plan - ✅ Prepare rollback plan
**Common Issues:** ### Common Issues & Solutions
- Database connection errors → Check DATABASE_URL
- Missing environment variables → Verify .env file | Issue | Cause | Solution |
- Type errors → Run `pnpm prisma generate` |-------|-------|----------|
- Service not starting → Check logs with `docker-compose logs` | 🔴 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:** **Visual Indicators:**
- 🔵 Old Components (Unchanged) - 🔵 Old Components (Unchanged)

30
docs/en/guides/observability.md
View File

@@ -218,18 +218,17 @@ Create custom dashboards in Grafana:
## Color Palette Reference ## 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 | | Component Type | Fill Color | Stroke Color | Purpose |
|----------|------------|-------| |----------------|------------|--------------|----------|
| **Services** | `#2d3748` | Microservices subgraph | | 🚀 Services | `#e94560` | `#c81e3b` | Microservices (red) |
| **Collection** | `#2c5282` | Data collection components | | 📊 Collectors | `#f39c12` | `#d68910` | Data collection (orange) |
| **Storage** | `#2f855a` | Database nodes | | 💾 Storage | `#3498db` | `#2874a6` | Storage (blue) |
| **Visualization** | `#744210` | Grafana/UI components | | 📊 Visualization | `#9b59b6` | `#7d3c98` | Visualization (purple) |
| **Service Nodes** | `#4a5568` | Individual services | | 📦 Subgraphs | `#1a1a2e` - `#533483` | `#16213e` - `#0f3460` | Logical groups |
| **Collectors** | `#3182ce` | Prometheus/Promtail |
| **Databases** | `#38a169` | Storage systems | **All text uses `color:#ffffff` (white) for readability on dark backgrounds**
| **Dashboards** | `#d69e2e` | Grafana node |
## Quick Tips ## Quick Tips
@@ -274,6 +273,15 @@ sum(metric_name) by (label)
## Troubleshooting ## 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 ### Logs Not Appearing in Loki
1. Check Promtail logs: `docker logs promtail` 1. Check Promtail logs: `docker logs promtail`

75
docs/vi/guides/kubernetes-local.md
View File

@@ -252,41 +252,40 @@ kubectl delete namespace iam-local
## Quick Tips ## 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 ```bash
# Xem tất cả resources trong namespace # 🔍 Debugging
kubectl get all -n iam-local 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 # 🔄 Quản Lý Image
kubectl logs -f -n iam-local -l app=iam-service --tail=100 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 # 🚀 Deploy Nhanh
kubectl exec -it -n iam-local deployment/iam-service -- sh 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 # 🧹 Cleanup
kubectl top pods -n iam-local 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
# 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
``` ```
### 🔍 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 ### 📋 Deployment Checklist
- [ ] ✅ Docker Desktop Kubernetes enabled - [ ] ✅ Docker Desktop Kubernetes enabled
@@ -337,14 +336,20 @@ kubectl describe node docker-desktop
7. **Enable logging** để dễ debug 7. **Enable logging** để dễ debug
8. **Regular cleanup** các resources không dùng 8. **Regular cleanup** các resources không dùng
### 🎨 Visual Indicators ### 🎨 Trạng Thái Visual
Khi đọc pod status: - 🟢 **Running** - Service hoạt động bình thường
- 🟢 `Running` = Pod hoạt động bình thường - 🟡 **Pending** - Đang chờ resources
- 🟡 `Pending` = Đang chờ scheduling - 🔴 **CrashLoopBackOff** - Service liên tục fail (kiểm tra logs!)
- 🔴 `CrashLoopBackOff` = Pod liên tục crash - 🔵 **ContainerCreating** - Pod đang khởi động
- 🔵 `ContainerCreating` = Đang tạo container - ⚫ **Terminating** - Pod đang tắt
- ⚠️ `ImagePullBackOff` = Không pull được image
### 💡 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 ### 🔗 Tài Liệu Tham Khảo

91
docs/vi/guides/local-deployment.md
View File

@@ -227,35 +227,74 @@ docker-compose logs traefik
```mermaid ```mermaid
graph TB graph TB
Client([Client]) Client[👤 Client<br/>Browser] --> Traefik
Traefik[Traefik<br/>API Gateway<br/>:80, :8080]
IAM[iam-service<br/>:5001] Traefik[🌐 Traefik<br/>API Gateway<br/>:80, :8080]
Admin[web-admin<br/>:3000]
WebClient[web-client<br/>:3001] Traefik --> IAM[🔐 IAM Service<br/>Authentication<br/>:5001]
Redis[(Redis<br/>:6379)] Traefik --> Admin[⚙️ Web Admin<br/>Dashboard<br/>:3000]
Postgres[(PostgreSQL<br/>Neon)] Traefik --> WebClient[🌍 Web Client<br/>Application<br/>:3001]
Client --> Traefik IAM --> Redis[(💾 Redis<br/>Cache<br/>:6379)]
Traefik --> IAM IAM --> DB[(🗄️ PostgreSQL<br/>Neon Database)]
Traefik --> Admin
Traefik --> WebClient classDef client fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#eee
IAM --> Redis classDef gateway fill:#0f3460,stroke:#16213e,stroke-width:3px,color:#eee
IAM --> Postgres classDef service fill:#16213e,stroke:#533483,stroke-width:2px,color:#eee
classDef frontend fill:#1a1a40,stroke:#6c5ce7,stroke-width:2px,color:#eee
style Client fill:#1a1a2e,stroke:#4a4e69,stroke-width:2px,color:#fff classDef data fill:#2d132c,stroke:#801336,stroke-width:2px,color:#eee
style Traefik fill:#0f3460,stroke:#16213e,stroke-width:3px,color:#fff
style IAM fill:#533483,stroke:#301934,stroke-width:2px,color:#fff class Client client
style Admin fill:#533483,stroke:#301934,stroke-width:2px,color:#fff class Traefik gateway
style WebClient fill:#533483,stroke:#301934,stroke-width:2px,color:#fff class IAM service
style Redis fill:#c9184a,stroke:#590d22,stroke-width:2px,color:#fff class Admin,WebClient frontend
style Postgres fill:#c9184a,stroke:#590d22,stroke-width:2px,color:#fff class Redis,DB data
``` ```
**Chú Giải:** **Chú Giải:**
- 🌐 **Client**: Người dùng/trình duyệt bên ngoài - 👤 **Client**: Người dùng truy cập qua trình duyệt
- 🚪 **Traefik**: API Gateway và router - 🌐 **Gateway**: Traefik API Gateway (định tuyến tự động)
- 🔧 **Services**: Microservices backend - 🔐 **Backend**: IAM Service (xác thực)
- 💾 **Storage**: Redis cache và PostgreSQL database - ⚙️ **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 ## Tài Liệu Tham Khảo