文檔中心 / 問題排查指南
本頁目錄

問題排查指南

本文檔幫助您解决 OntiCards 部署和運行過程中遇到的問題。

一、部署問題

1.1 Docker 啟動失败

症狀：執行 docker-compose up 後容器未能正常啟動

  1. 1

    檢查 Docker 是否正常運行

  2. 2
    docker --version docker-compose --version
  3. 3

    查看详細錯誤資訊

  4. 4
    docker-compose up
    

    不加 -d 参数可以看到实时日志
  5. 5

    常见錯誤速查表

錯誤資訊可能原因解决方法
"docker: command not found"Docker 未安裝安裝 Docker Desktop
"docker daemon not running"Docker 服務未啟動啟動 Docker 服務
"port is already allocated"埠被占用修改 docker-compose.yml 中的埠或释放占用埠

1.2 埠被占用

症狀：提示 "port is already allocated" 或 " Ports are not available"

  1. 1

    查看埠占用情况

  2. 2
    # Windows netstat -ano | findstr :3000
  3. 3

    Linux/Mac

    lsof -i :3000

  4. 4

    關閉占用埠的程式，或修改 docker-compose.yml 中的埠映射

  5. 5
    services: frontend: ports:
    

    • "3001:3000"  # 改为其他端口

1.3 容器不斷重啟

症狀：容器啟動後立即退出或反復重啟

  1. 1

    查看容器日誌

  2. 2
    docker-compose logs -f <服务名>
  3. 3

    常见原因及解决

原因解决方法
環境變數組態錯誤檢查 .env 檔案組態
資料庫連接失败確認資料庫服務正常且網絡可达
磁盘空間不足清理磁盘空間

二、訪問問題

2.1 無法訪問前端頁面

症狀：瀏覽器打開 http://localhost:3000 显示無法連接

  1. 1

    確認容器是否運行

  2. 2
    docker-compose ps
  3. 3

    查看前端日誌

  4. 4
    docker-compose logs -f frontend
  5. 5

    檢查埠映射

  6. 6
    docker port onticards-frontend
  7. 7

    對照常见原因清單

現象處理方式
容器未啟動執行 docker-compose up -d
埠映射錯誤檢查 docker-compose.yml
防火墙拦截檢查防火墙設置

2.2 後端 API 請求失败

症狀：前端頁面能打開，但操作時報錯 "請求失败"

  1. 1

    確認後端服務是否運行

  2. 2
    docker-compose ps backend
  3. 3

    查看後端日誌

  4. 4
    docker-compose logs -f backend
  5. 5

    測試 API 健康檢查

  6. 6
    curl http://localhost:8000/api/health

三、資料庫連接問題

3.1 無法連接目標資料庫

症狀：添加數據源時 "測試連接" 失败

  1. 1

    檢查目標資料庫是否運行

  2. 2

    確認服務進程已啟動

  3. 3

    確認網絡連通性

  4. 4
    # 测试端口是否可达 telnet <目标IP> <端口>
  5. 5

    Windows PowerShell

    Test-NetConnection -ComputerName <目标IP> -Port <端口>

  6. 6

    檢查防火墙設置

  7. 7

    確認目標資料庫所在主機的 3306/5432 等埠已放行

  8. 8

    確認用戶名密碼正確

  9. 9

    以 mysql -u user -p 等命令直連測試一次

  10. 10

    確認資料庫允許远程連接

  11. 11

    檢查 bind-address 組態（如 MySQL 預設 127.0.0.1）

常见資料庫埠速查

資料庫預設埠
MySQL3306
PostgreSQL5432
Oracle1521
SQL Server1433
达梦5236
KingBase54321

3.2 連接超時

症狀：測試連接時提示 "連接超時"

ℹ️提示
  • 網絡不可达
  • 防火墙拦截
  • 資料庫最大連接數已滿
  • 應用端連接池达到上限

ℹ️提示
  • 檢查網絡和防火墙（telnet / Test-NetConnection）
  • 联系 DBA 增加連接數或释放空闲連接
  • 確認連接資訊中的主機地址正確

四、LLM 調用問題

4.1 LLM API 調用失败

症狀：查詢時報錯 "LLM 調用失败" 或 "API 請求錯誤"

  1. 1

    查看後端日誌中的 LLM 調用錯誤

  2. 2
    docker-compose logs -f backend | grep -i "llm\|openai\|qwen"
  3. 3

    檢查環境變數組態是否加載

  4. 4
    docker-compose exec backend env | grep LLM
  5. 5

    對照錯誤資訊表

錯誤資訊可能原因解决方法
"Invalid API key"API Key 錯誤檢查 LLM_API_KEY 組態
"connection timeout"網絡不通/代理問題檢查網絡和代理組態
"rate limit exceeded"請求頻率超限降低請求頻率或升級套餐
"model not found"模型名稱錯誤檢查 LLM_MODEL 組態

4.2 網絡訪問問題

症狀：國內無法訪問 OpenAI 等國外服務

方案一：組態代理

# 在 .env 中配置代理 LLM_BASE_URL=http://your-proxy:7890

方案二：使用國內模型

LLM_PROVIDER=qwen     # 阿里通义千问 LLM_PROVIDER=moonshot # 月之暗面

五、數據卡片生成問題

5.1 數據卡片生成緩慢

症狀：添加數據源後，數據卡片生成很慢或卡住

ℹ️提示
  • 表數量太多
  • LLM 回應慢
  • 網絡不穩定

ℹ️提示
  • 耐心等待，首次生成需要一些時間
  • 檢查 LLM 服務是否正常
  • 表數量较多時可以分批添加

5.2 數據卡片生成失败

症狀：提示 "數據卡片生成失败"

  1. 1

    查看後端日誌中的具體錯誤

  2. 2

    docker-compose logs -f backend 寻找 stack trace

  3. 3

    檢查 LLM 服務是否正常

  4. 4

    用其他 client（如 curl）直接調用 LLM，確認可用

  5. 5

    確認目標資料庫連接正常

  6. 6

    在數據源列表中點击「測試連接」

  7. 7

    檢查資料庫權限

  8. 8

    需要 SELECT 與讀取表結構（DBA）的權限

六、质檢功能問題

6.1 质檢規則執行失败

症狀：執行质檢時報錯

ℹ️提示
  • 規則 SQL 語法錯誤 → 檢查規則組態
  • 資料庫連接問題 → 確認數據源正常
  • 權限不足 → 確認有 SELECT 權限

6.2 质檢結果為空

症狀：執行完成後沒有檢測到任何問題

ℹ️提示
  • 數據確實沒有問題
  • 規則組態過于寬松
  • 規則條件與實际數據不匹配

七、性能問題

7.1 系統運行緩慢

  1. 1

    檢查资源使用

  2. 2
    docker stats
  3. 3

    對照常见原因

現象處理方式
記憶體不足增加 Docker 記憶體限製
磁盘空間不足清理磁盘
並發請求過多限流或擴容

7.2 查詢超時

症狀：查詢長時間無回應或提示超時

ℹ️提示
  • 增加查詢超時時間組態
  • 减少查詢的數據範围（如縮短時間範围）
  • 檢查資料庫性能

八、日誌查看方法

8.1 查看所有服務日誌

docker-compose logs -f

8.2 查看指定服務日誌

# 后端日志
docker-compose logs -f backend

# 前端日志
docker-compose logs -f frontend

8.3 限製日誌行數

docker-compose logs --tail=100 backend

8.4 搜索特定關鍵詞

docker-compose logs | grep -i "error"

九、快速诊斷命令速查

  1. 1

    檢查容器狀態

  2. 2
    docker-compose ps
  3. 3

    檢查资源使用

  4. 4
    docker stats
  5. 5

    檢查埠占用

  6. 6
    netstat -ano | findstr "3000 8000"
  7. 7

    測試網絡連通性

  8. 8
    ping <目标地址>
  9. 9

    測試埠連通性

  10. 10
    telnet <目标地址> <端口>
  11. 11

    查看服務日誌

  12. 12
    docker-compose logs -f

十、获取更多幫助

如果以上方法無法解决您的問題：

  1. 查看 FAQ 常见問題解答
  1. 查看 用戶手冊 了解功能使用
  1. 提交 GitHub Issue：https://github.com/stepll2026/OntiCards/issues

提交 Issue 時請提供：

  • 錯誤日誌（敏感資訊請脱敏）
  • 操作步驟描述
  • 環境資訊（作業系統、Docker 版本等）

本文檔最後更新時間：2026 年 08 月

← 上一篇
部署指南
下一篇 →
SSO 單點登入（JWT）