故障排查
最后更新: 2026/10/18
按启动与初始化、登录、数据连接与数据集、报表、大屏分类，列出现象、原因和解决方法，均来自源码行为。
概述
排查的通用顺序：先看现象和提示文字，再缩小范围（数据集单独预览是否有数据、报表是否绑定正确、大屏是否通过“自检”），最后查看日志。日志在程序目录的 logs/，Sight Report 为 sight-data-error.log 与 sight-data-info.log，Sight Wall 为 sight-wall-error.log 与 sight-wall-info.log；以系统服务运行时另见 journalctl -u sight-report -f（Linux）或 logs/launchd.err.log（macOS）。
本页只收录能在源码中确认的问题。概念性问答见 常见问题。
启动与初始化
| 现象 |
原因 |
解决方法 |
| 启动脚本报“未找到 java 命令”或“检测到 Java x，需 JDK 21+” |
未安装 JDK，或版本低于 21 |
安装 JDK 或 JRE 21 及以上版本并加入 PATH，用 java -version 验证。2.0.61 之前的版本必须是 JDK |
| 页面或接口提示“系统没有初始化” |
尚未完成初始化；或已配置的平台数据库连不上 |
未初始化时访问 /setup 完成向导。已初始化的，检查平台数据库是否可达、data/work/database.config 是否指向正确的库 |
| 日志出现“数据库已配置但当前不可达，进入降级模式” |
外接平台数据库启动时不可达 |
程序会先用内存 H2 让 Web 起来，并在后台重试连接，库恢复可达后自动切换到真实库。恢复期间授权会按试用运行，恢复后自动引导。请尽快修复数据库网络或账号 |
| 机器开启了系统级 SOCKS 代理，JVM 连不上内网数据库，表现为初始化或启动时连接超时 |
Java 的 Socket 会使用系统代理设置，JDBC 连接被转发到代理 |
在 JVM_OPTS 中加入 -Djava.net.useSystemProxies=false -DsocksProxyHost= -DsocksProxyPort=，仅去掉环境变量 ALL_PROXY 不够 |
| 初始化时提示“数据库连接验证失败，请检查地址与账号密码” |
地址、端口、账号、密码或库名有误 |
在向导里先点「测试连接」，通过后再点「下一步」 |
| 初始化时提示“数据库驱动无法识别” |
JDBC URL 的类型无法识别 |
用向导的「数据库类型」下拉框选择类型，让 JDBC URL 自动生成，不要手写不规范的 URL |
| PostgreSQL 系数据库测试连接通过，后续建表却报权限错误 |
填写的模式（schema）不存在时，PostgreSQL 系会静默回落到 public |
填好用户名密码后展开「模式名称」下拉框，从数据库里已有的模式中选择 |
| 提示“系统已初始化，请勿重复初始化” |
系统已经初始化过 |
直接登录即可，无需也不能再次初始化 |
登录与授权
| 现象 |
原因 |
解决方法 |
| 提示“密码错误达到 N，账号已被锁定”或“ip已被锁定” |
连续输错密码触发登录锁定，默认 5 次、锁定 10 分钟 |
等待锁定时间结束；管理员可在「系统 > 系统设置 > 登录解锁」中解除；也可在「登录」页签调整锁定策略 |
| 点击「忘记密码？」提示“系统暂未开通邮件自助找回” |
未配置邮件渠道 |
联系管理员重置；管理员本人可用应急重置通道 /admin/reset，见 首次初始化与登录 |
| 应急重置页提示“应急重置通道未开启” |
配置项 app.admin-reset.enabled 被设为 false |
将其改回 true（默认即为开启） |
| 应急重置提示“重置失败，请检查校验串是否与服务端文件一致” |
reset-admin.txt 内容与填写不一致、不在程序目录、创建已超过 60 分钟，或内容少于 16 位 |
重新在 jar 所在目录创建文件，写入不少于 16 位的随机字符，回页面点「重新检测文件」后再提交 |
| 提示“当前访问人数已达上限，请稍后再试或联系管理员。” |
未注册状态下，滚动窗口内访问来源 IP 数达到上限，默认 1 小时 2 个 |
等窗口过期，或在「系统 > 注册管理」录入授权。运维可用 sight-data.trial.<产品标识>.max-ips 与 sight-data.trial.<产品标识>.window-ms 调整未注册时的限额，产品标识为 report 或 datawall |
| 登录后一段时间自动退出 |
会话超时，默认 1440 分钟（24 小时） |
重新登录；管理员可在「系统 > 系统设置 > 登录」页签的「登录超时设置」中调整 |
数据连接与数据集
| 现象 |
原因 |
解决方法 |
| 测试连接失败 |
网络、防火墙、数据库白名单，或主机、端口、账号密码、库名有误 |
从 Sight 所在服务器直接测试到数据库主机端口的连通性，并核对连接信息 |
| 新建连接时下拉里的数据库类型带“（需上传驱动）” |
该数据库的 JDBC 驱动未随平台提供 |
「系统 > 数据连接 > 驱动管理」中「上传驱动」，仅支持 .jar |
| 保存连接提示“JDBC 连接串包含被禁止的危险参数，已拒绝”，或“数据源连接属性 [xxx] 被禁止” |
连接串或扩展参数含 allowLoadLocalInfile、autoDeserialize、socketFactory、queryInterceptors、H2 的 INIT= / RUNSCRIPT 等已知高危项 |
删除这些参数后再保存 |
| API 数据集提示“目标地址被禁止（内网/环回/元数据）”，或“仅支持 http/https 协议”“主机名无法解析” |
API 数据集的出站保护：只允许公网 http / https，且不自动跟随重定向 |
改用公网地址；完全可信的内网环境可用 -Dsightdata.api-dataset.ssrf-guard.enabled=false 或环境变量 SIGHT_DATA_API_SSRF_GUARD=false 关闭校验 |
| SQL 提示存在多条语句而被拒绝 |
语句中间有分号，或末尾有多个分号 |
一个数据集只写一条查询；仅末尾一个分号会被允许 |
| 较老版本中，SQL 末尾带分号，预览、分页或计数报语法错误 |
旧版本在给 SQL 包装分页与计数语句时未去掉结尾分号 |
该问题已在 2026-07-20 的提交中修复（报表与大屏两条取数链路），升级到之后的版本；或先去掉结尾分号 |
| 备份恢复后所有数据连接都建不起来 |
备份不包含 data/drivers，恢复后驱动 .jar 缺失 |
在「驱动管理」重新上传驱动 |
| 示例报表报错或数据不对 |
示例表 demo_* 被修改、删除，或初始化时没有导入演示数据 |
「系统 > 系统设置 > 示例数据 > 重新导入」，勾选「强制重建示例数据表」会整体替换 demo_ 表内容 |
报表
| 现象 |
原因 |
解决方法 |
| 导出或公开链接提示“报表尚未发布，无法查看！”，通过接口导出时返回 JSON 错误而不是文件 |
草稿状态的报表不能导出或公开访问 |
在设计器中点击「发布」。接口调用方需先发布，并检查响应是否为文件流 |
| 报表没有数据 |
数据集本身无结果，或字段绑定、父格设置有误 |
先在数据集编辑器点「数据预览」看是否有数据；有数据则检查单元格的「数据集」「数据字段」和「展开方向」、父格设置 |
| 生成明细表时提示“数据集「xxx」没有字段，请先在数据集里预览一次以获取字段” |
数据集尚未取得字段 |
打开数据集点击「数据预览」，或点击「确定」保存一次，保存时会读取 SQL 输出列 |
| 打印或导出错位、PDF 中文字形缺失 |
套打坐标或页边距未校准；字体未嵌入 |
见 套打与定位、PDF 字体嵌入 |
大屏
| 现象 |
原因 |
解决方法 |
| 「联动本页」是灰的 |
页面里还没有页面变量 |
在「交互」页签里就地新建并接上，或在左栏「数据集 > 页面变量」创建 |
| 配好的联动不触发 |
联动指向的组件已被删除，这类联动不会报错，只是永远不触发；或只在设计态查看 |
用工具栏「自检」查看指向不存在组件的联动；联动和动效要在预览里才会真正运行 |
| 组件显示的是写死的数字 |
组件没有绑定数据集，模板自带的是示例数据 |
属性面板把「固定值」切成「数据集」，选数据集和字段；用「自检」的“数据源接入”检查 |
| 导入大屏后图片不显示 |
大屏引用了非自包含的外链素材 |
导入时会扫描并提醒，使用导入后的「一键本地化」把外链素材转存到平台 |
| 大屏数据不刷新 |
未设置定时刷新 |
在右侧「画布」页签的「运行态刷新」设置；SQL 数据集也可在高级设置里单独设刷新间隔 |
| 通过 MCP 连接的 AI 无法创建或修改大屏 |
令牌没有勾选权限，默认只读 |
管理员在「系统 > MCP 接入」为令牌勾选「写草稿」 |
求助时请提供
- 现象截图、界面上的完整提示文字和复现步骤。
logs/ 下 error 日志（Sight Report 为 sight-data-error.log，Sight Wall 为 sight-wall-error.log）中对应时间的异常堆栈。- 产品与版本号（页头产品名后可显示版本号，见 更新日志）。
相关文档
