故障排除

本文檔整理花店管理系統常見問題及解決方案。

應用程式啟動問題

資料庫連線失敗

症狀：

HikariPool-1 - Exception during pool initialization.
org.postgresql.util.PSQLException: Connection refused

解決方案：

1. 確認資料庫服務正在運行
2. 檢查連線字串
3. 確認防火牆設定

# 測試資料庫連線
psql -h localhost -U florist -d florist

# 檢查 PostgreSQL 服務
systemctl status postgresql

Flyway 遷移失敗

症狀：

FlywayException: Validate failed: Migration checksum mismatch

解決方案：

1. 不要修改已執行的遷移腳本
2. 如需重建，使用 flywayRepair

./gradlew flywayRepair
./gradlew flywayMigrate

Port 被佔用

症狀：

Web server failed to start. Port 8080 was already in use.

解決方案：

# 找出佔用的程序
lsof -i :8080

# 終止程序
kill -9 <PID>

# 或更改應用程式端口
java -jar app.jar --server.port=8081

運行時問題

OutOfMemoryError

症狀：

java.lang.OutOfMemoryError: Java heap space

解決方案：

1. 增加 JVM 記憶體
2. 檢查是否有記憶體洩漏

# 增加記憶體
java -Xms512m -Xmx2g -jar app.jar

# 開啟 heap dump
java -XX:+HeapDumpOnOutOfMemoryError -jar app.jar

連線池耗盡

症狀：

HikariPool-1 - Connection is not available, request timed out after 30000ms

解決方案：

1. 檢查是否有未關閉的連線
2. 增加連線池大小
3. 縮短連線超時

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      connection-timeout: 20000
      leak-detection-threshold: 60000

快取問題

症狀：資料更新後顯示舊資料

解決方案：

1. 確認快取失效邏輯正確
2. 手動清除快取

# 透過 Actuator 清除快取
curl -X POST http://localhost:8080/actuator/caches/products/clear

前端問題

CORS 錯誤

症狀：

Access to XMLHttpRequest has been blocked by CORS policy

解決方案：

app:
  cors:
    allowed-origins:
      - http://localhost:5173
      - https://florist.leandev.io
    allowed-methods:
      - GET
      - POST
      - PUT
      - PATCH
      - DELETE

CSP 違規

症狀：

Refused to execute inline script because it violates the following CSP directive

解決方案：

1. 確認 script 標籤有 nonce 屬性
2. 檢查 CSP header 配置

靜態資源 404

症狀：CSS、JS 檔案載入失敗

解決方案：

1. 確認前端建置輸出正確
2. 檢查 base href 配置

# 確認檔案存在
ls -la src/main/resources/static/assets/

認證問題

Token 過期

症狀：

401 Unauthorized: Token has expired

解決方案：

1. 實作 token refresh 邏輯
2. 檢查 token 過期時間設定

權限不足

症狀：

403 Forbidden: Access Denied

解決方案：

1. 確認使用者角色
2. 檢查 API 權限設定

# 查看使用者權限
SELECT a.username, r.name as role, auth.name as authority
FROM account a
JOIN account_roles ar ON a.id = ar.account_id
JOIN role r ON ar.role_id = r.id
JOIN role_authorities ra ON r.id = ra.role_id
JOIN authority auth ON ra.authority_id = auth.id
WHERE a.username = 'admin';

效能問題

慢查詢

診斷：

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true
        generate_statistics: true

解決方案：

1. 新增索引
2. 優化查詢
3. 使用快取

高 CPU 使用率

診斷：

# 查看執行緒狀態
jstack <PID> > thread_dump.txt

# 查看 CPU 使用
top -H -p <PID>

日誌分析

啟用詳細日誌

logging:
  level:
    io.leandev: DEBUG
    org.springframework.security: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql: TRACE

常用日誌位置

環境	位置
本地開發	Console 輸出
Tomcat	/opt/tomcat/logs/catalina.out
Docker	docker logs <container>

取得協助

如果以上方案無法解決問題：

1. 收集相關日誌
2. 記錄重現步驟
3. 聯繫開發團隊

下一步

• 監控與告警 - 設定監控預防問題
• 部署總覽 - 返回部署總覽