From c44d3e170cc263711635ea432002c40108dce65f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=84=AD=E6=B2=9B=E8=BB=92?= <jettcheng1018@gmail.com>
Date: Wed, 17 Sep 2025 00:49:57 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=BE=8C=E7=AB=AF?=
 =?UTF-8?q?=E9=8C=AF=E8=AA=A4=E6=97=A5=E8=AA=8C=E7=9B=A3=E6=8E=A7=E6=8C=87?=
 =?UTF-8?q?=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 完整的錯誤日誌使用教學
- 常見問題排查流程
- 監控工具使用方法
- 實際案例分析
- 快速診斷檢查清單
- 最佳實踐建議

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/03_development/error-logging-guide.md | 502 +++++++++++++++++++++
 1 file changed, 502 insertions(+)
 create mode 100644 docs/03_development/error-logging-guide.md

diff --git a/docs/03_development/error-logging-guide.md b/docs/03_development/error-logging-guide.md
new file mode 100644
index 0000000..9e63b85
--- /dev/null
+++ b/docs/03_development/error-logging-guide.md
@@ -0,0 +1,502 @@
+# 🔍 DramaLing 後端錯誤日誌監控指南
+
+## 📋 目錄
+1. [錯誤日誌系統概覽](#錯誤日誌系統概覽)
+2. [監控工具使用方法](#監控工具使用方法)
+3. [常見錯誤類型和排查](#常見錯誤類型和排查)
+4. [實際使用案例](#實際使用案例)
+5. [日誌級別說明](#日誌級別說明)
+6. [快速診斷檢查清單](#快速診斷檢查清單)
+
+---
+
+## 🎯 錯誤日誌系統概覽
+
+DramaLing 後端配備了完整的錯誤日誌系統，幫助開發者快速定位和解決問題。
+
+### ✅ **已配置的功能**
+- **全域錯誤處理中介軟體**：捕獲所有未處理的異常
+- **詳細日誌配置**：Debug 級別記錄
+- **結構化日誌**：包含請求詳情、堆疊追蹤
+- **資料庫操作日誌**：SQL 查詢和執行時間
+- **認證流程日誌**：完整的登入註冊追蹤
+
+### 🗂️ **相關檔案**
+- `Middleware/ErrorHandlingMiddleware.cs` - 全域錯誤處理
+- `appsettings.json` - 日誌配置
+- `Controllers/AuthController.cs` - 認證日誌
+- `Program.cs` - 中介軟體註冊
+
+---
+
+## 🛠️ 監控工具使用方法
+
+### **1. 查看即時日誌**
+```bash
+# 查看當前後端服務的所有日誌
+BashOutput(bash_id: "33d454")
+```
+
+### **2. 過濾特定錯誤**
+```bash
+# 只看錯誤和異常日誌
+BashOutput(bash_id: "33d454", filter: "Error|Exception|fail")
+
+# 只看認證相關日誌
+BashOutput(bash_id: "33d454", filter: "Registration|Login|Auth")
+
+# 只看資料庫錯誤
+BashOutput(bash_id: "33d454", filter: "Database|DbCommand|Entity")
+```
+
+### **3. 監控特定功能**
+```bash
+# 監控 JWT 相關問題
+BashOutput(bash_id: "33d454", filter: "JWT|Token|Bearer")
+
+# 監控模型驗證錯誤
+BashOutput(bash_id: "33d454", filter: "ModelState|Validation")
+```
+
+### **4. 找出服務 ID**
+如果不知道當前的 bash_id，使用：
+```bash
+/bashes
+```
+然後找到運行 `dotnet run --urls=http://localhost:5000` 的服務 ID。
+
+---
+
+## 🚨 常見錯誤類型和排查
+
+### **1. 認證錯誤**
+
+#### **問題症狀**：
+- 用戶無法登入
+- JWT token 無效
+- 401 Unauthorized 錯誤
+
+#### **排查方法**：
+```bash
+BashOutput(bash_id: "33d454", filter: "Login attempt|Authentication|JWT|Bearer")
+```
+
+#### **典型日誌**：
+```
+info: Login attempt for email: user@example.com
+warn: Bearer was not authenticated. Failure message: IDX10503: Signature validation failed
+info: User logged in successfully: 4111625f-e44c-4878-8fd0-4377eed45f04
+```
+
+#### **解決步驟**：
+1. 檢查 JWT 密鑰配置
+2. 驗證 token 格式是否正確
+3. 確認用戶是否存在於資料庫
+
+### **2. 資料庫錯誤**
+
+#### **問題症狀**：
+- 註冊失敗
+- 資料無法儲存
+- 500 Internal Server Error
+
+#### **排查方法**：
+```bash
+BashOutput(bash_id: "33d454", filter: "DbCommand|Database|EntityFramework")
+```
+
+#### **典型日誌**：
+```
+dbug: Executed DbCommand (2ms) [Parameters=[@__request_Email_0='test@example.com']]
+      SELECT EXISTS (SELECT 1 FROM "user_profiles" WHERE "u"."email" = @__request_Email_0)
+info: Database ensured created
+```
+
+#### **解決步驟**：
+1. 檢查資料庫檔案是否存在
+2. 驗證 SQL 查詢是否正確
+3. 確認資料庫連線字串
+
+### **3. 模型驗證錯誤**
+
+#### **問題症狀**：
+- 表單驗證失敗
+- 400 Bad Request
+- 密碼格式錯誤
+
+#### **排查方法**：
+```bash
+BashOutput(bash_id: "33d454", filter: "ModelState|Validation|BadRequest")
+```
+
+#### **典型日誌**：
+```
+warn: Invalid model state for registration: {"Password": ["Password must be at least 8 characters"]}
+dbug: The request has model state errors, returning an error response
+```
+
+#### **解決步驟**：
+1. 檢查前端表單驗證
+2. 確認後端模型註解
+3. 驗證請求格式
+
+### **4. 應用程式異常**
+
+#### **問題症狀**：
+- 系統崩潰
+- 未預期的錯誤
+- 堆疊溢出
+
+#### **排查方法**：
+```bash
+BashOutput(bash_id: "33d454", filter: "Exception|fail:|error:")
+```
+
+#### **典型日誌**：
+```
+fail: Error during user registration
+      System.InvalidOperationException: Unable to determine the relationship...
+         at Microsoft.EntityFrameworkCore.Infrastructure.ModelValidator...
+```
+
+#### **解決步驟**：
+1. 查看完整堆疊追蹤
+2. 檢查相關程式碼
+3. 驗證依賴注入配置
+
+---
+
+## 📝 實際使用案例
+
+### **案例 1：用戶註冊失敗排查**
+
+**問題**：前端註冊表單提交後返回 500 錯誤
+
+**排查步驟**：
+
+1. **檢查認證日誌**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "Registration attempt")
+   ```
+
+2. **查看詳細錯誤**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "Error during user registration")
+   ```
+
+3. **檢查資料庫操作**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "INSERT INTO.*user_profiles")
+   ```
+
+**可能的解決方案**：
+- 資料庫關聯配置錯誤
+- 模型驗證失敗
+- 密碼雜湊錯誤
+
+### **案例 2：JWT Token 驗證失敗**
+
+**問題**：用戶登入後無法訪問受保護的端點
+
+**排查步驟**：
+
+1. **查看 Token 生成**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "User logged in successfully")
+   ```
+
+2. **檢查 Token 驗證**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "Bearer.*authenticated|Token.*validation")
+   ```
+
+3. **查看認證失敗原因**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "Failed to validate the token")
+   ```
+
+**可能的解決方案**：
+- JWT 密鑰不匹配
+- Token 格式錯誤
+- Token 過期
+
+### **案例 3：API 端點無回應**
+
+**問題**：API 請求沒有回應或超時
+
+**排查步驟**：
+
+1. **檢查請求是否到達**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "Request starting.*POST.*register")
+   ```
+
+2. **查看路由匹配**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "Route matched|Executing endpoint")
+   ```
+
+3. **檢查異常處理**
+   ```bash
+   BashOutput(bash_id: "33d454", filter: "An unhandled exception occurred")
+   ```
+
+**可能的解決方案**：
+- 路由配置錯誤
+- 控制器異常
+- 中介軟體問題
+
+---
+
+## 📊 日誌級別說明
+
+### **Debug**
+- **目的**：詳細的開發調試信息
+- **內容**：執行流程、參數值、內部狀態
+- **例子**：
+  ```
+  dbug: Creating DbConnection.
+  dbug: Executed DbCommand (2ms) [Parameters=[@p0='value']]
+  ```
+
+### **Information**
+- **目的**：重要的業務事件記錄
+- **內容**：正常操作、成功事件
+- **例子**：
+  ```
+  info: User registered successfully: 4111625f-e44c-4878-8fd0-4377eed45f04
+  info: Application started. Press Ctrl+C to shut down.
+  ```
+
+### **Warning**
+- **目的**：潛在問題警告
+- **內容**：不影響功能但需要注意的情況
+- **例子**：
+  ```
+  warn: Failed to determine the https port for redirect.
+  warn: Invalid model state for registration
+  ```
+
+### **Error**
+- **目的**：錯誤和異常記錄
+- **內容**：需要立即處理的問題
+- **例子**：
+  ```
+  fail: Error during user registration
+  info: An unhandled exception occurred during request execution
+  ```
+
+---
+
+## 🎯 快速診斷檢查清單
+
+當遇到問題時，按以下順序檢查：
+
+### **Step 1: 服務健康檢查**
+```bash
+curl "http://localhost:5000/health"
+```
+**預期結果**：`{"status":"Healthy","timestamp":"..."}`
+
+### **Step 2: 查看最新錯誤**
+```bash
+BashOutput(bash_id: "33d454", filter: "Error|fail|Exception")
+```
+**目的**：快速找出最近發生的錯誤
+
+### **Step 3: 檢查特定功能**
+根據問題類型選擇：
+
+```bash
+# 🔐 認證問題
+BashOutput(bash_id: "33d454", filter: "Auth|Login|Register|JWT")
+
+# 🗄️ 資料庫問題
+BashOutput(bash_id: "33d454", filter: "Database|DbCommand|Entity")
+
+# 📝 模型驗證問題
+BashOutput(bash_id: "33d454", filter: "ModelState|Validation")
+
+# 🌐 API 路由問題
+BashOutput(bash_id: "33d454", filter: "Route|Endpoint")
+```
+
+### **Step 4: 深入分析**
+```bash
+# 查看詳細追蹤
+BashOutput(bash_id: "33d454", filter: "StackTrace|InnerException")
+
+# 查看完整請求流程
+BashOutput(bash_id: "33d454", filter: "Request starting.*POST")
+```
+
+---
+
+## 💡 進階技巧
+
+### **1. 組合過濾器**
+```bash
+# 同時監控多個關鍵字
+BashOutput(bash_id: "33d454", filter: "Error.*Auth|Exception.*User")
+
+# 排除某些日誌
+BashOutput(bash_id: "33d454", filter: "Error(?!.*Entity)")
+```
+
+### **2. 時間範圍分析**
+日誌包含精確時間戳，可以：
+- 對比問題發生時間
+- 追蹤請求處理時長
+- 分析系統性能
+
+### **3. 關聯分析**
+使用 TraceId 和 RequestId 追蹤單一請求的完整生命週期：
+```
+=> TraceId:8270820e8be6f0bdb0cc7ed6c8623004 => RequestId:0HNFL7QLPM33V:00000001
+```
+
+### **4. 即時監控**
+可以定期檢查日誌來監控系統健康狀況：
+```bash
+# 每隔一段時間檢查錯誤
+BashOutput(bash_id: "33d454", filter: "Error|fail")
+```
+
+---
+
+## 🔧 常用監控命令
+
+### **日常監控**
+```bash
+# 檢查服務狀態
+curl "http://localhost:5000/health"
+
+# 查看最新日誌
+BashOutput(bash_id: "33d454")
+
+# 只看錯誤
+BashOutput(bash_id: "33d454", filter: "Error|Exception|fail")
+```
+
+### **功能測試**
+```bash
+# 測試註冊功能
+curl -X POST "http://localhost:5000/api/auth/register" \
+  -H "Content-Type: application/json" \
+  -d '{"username": "test", "email": "test@example.com", "password": "testpass123"}'
+
+# 測試登入功能
+curl -X POST "http://localhost:5000/api/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "test@example.com", "password": "testpass123"}'
+```
+
+### **問題排查**
+```bash
+# 檢查認證問題
+BashOutput(bash_id: "33d454", filter: "Auth|Login|Register|JWT")
+
+# 檢查資料庫問題
+BashOutput(bash_id: "33d454", filter: "Database|DbCommand|SQL")
+
+# 檢查 API 路由問題
+BashOutput(bash_id: "33d454", filter: "Route|Endpoint|Controller")
+```
+
+---
+
+## 📚 日誌範例解讀
+
+### **成功註冊的日誌**
+```
+info: Registration attempt for user: logtest, Email: logtest@example.com
+dbug: Executed DbCommand (0ms) [Parameters=[@__request_Email_0='logtest@example.com']]
+      SELECT EXISTS (SELECT 1 FROM "user_profiles" WHERE "u"."email" = @__request_Email_0)
+dbug: Executed DbCommand (1ms) [Parameters=[@p0='4111625f-e44c-4878-8fd0-4377eed45f04', ...]]
+      INSERT INTO "user_profiles" (Id, username, email, password_hash, ...)
+info: User registered successfully: 4111625f-e44c-4878-8fd0-4377eed45f04
+```
+
+### **驗證錯誤的日誌**
+```
+warn: Invalid model state for registration: {"Password": ["Password must be at least 8 characters"]}
+dbug: The request has model state errors, returning an error response.
+info: Executing BadRequestObjectResult, writing value of type 'ValidationProblemDetails'
+```
+
+### **系統異常的日誌**
+```
+fail: Error during user registration
+      System.InvalidOperationException: Unable to determine the relationship...
+         at Microsoft.EntityFrameworkCore.Infrastructure.ModelValidator...
+info: An unhandled exception occurred during request execution. Request: POST /api/auth/register
+```
+
+---
+
+## 🎯 故障排除流程圖
+
+```
+問題發生
+    ↓
+檢查服務是否運行 (/health)
+    ↓
+查看最新錯誤日誌 (Error|Exception)
+    ↓
+根據錯誤類型選擇：
+    ├─ 認證問題 → 檢查 Auth 日誌
+    ├─ 資料庫問題 → 檢查 DbCommand 日誌
+    ├─ 驗證問題 → 檢查 ModelState 日誌
+    └─ 系統異常 → 檢查 StackTrace 日誌
+    ↓
+分析具體錯誤原因
+    ↓
+實施修復方案
+    ↓
+重新測試驗證
+```
+
+---
+
+## 🚀 最佳實踐
+
+### **1. 定期監控**
+- 每次部署後檢查日誌
+- 定期查看錯誤趨勢
+- 監控關鍵業務流程
+
+### **2. 錯誤分類**
+- **緊急**：系統崩潰、資料庫連線失敗
+- **重要**：認證失敗、API 異常
+- **一般**：驗證錯誤、業務邏輯問題
+
+### **3. 日誌保存**
+重要錯誤日誌應該保存下來用於：
+- 問題追蹤
+- 性能分析
+- 系統優化
+
+---
+
+## 📞 支援
+
+如果遇到無法解決的問題：
+
+1. **收集信息**：保存相關日誌
+2. **重現問題**：記錄重現步驟
+3. **檢查環境**：確認配置和依賴
+4. **尋求協助**：提供完整的錯誤資訊
+
+---
+
+**最後更新**：2025-09-16
+**版本**：v1.0
+**適用於**：DramaLing .NET Core API Backend
+
+---
+
+## 🔗 相關文檔
+
+- [API 開發指南](./api/README.md)
+- [資料庫配置](./setup/env-setup.md)
+- [開發環境設置](./setup/README.md)
\ No newline at end of file