文档中心 / 问题排查指南
本页目录

问题排查指南

本文档帮助您解决 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）