常见问题与排障
按你遇到的现象找条目。先查对应业务记录，再按同一时间点核对应用日志；不同记录能证明的范围见结果判断与排障和应用日志。文件日志以实际部署路径为准，默认 logs\datahub.log。
安装与启动
双击 datahub.exe 窗口一闪就没
程序留下了错误信息就退出了。请改用命令提示符启动（见首次使用），窗口会停留并显示原因。常见原因：端口被占用、configs\config.yaml 被改坏（多删了空格或冒号）。
提示端口被占用，或浏览器打不开控制台
- 先看启动窗口：
address already in use通常表示端口已被占用；Windows 错误 10013（“访问套接字的方式不被允许”）也可能表示端口被系统保留，即使找不到监听程序也不能使用。 - 先核对错误中的端口：默认 API 使用 6700，控制台使用 6701。确认需要换端口后，用记事本打开
configs\config.yaml，把server:下port: 6700改成可用的 API 端口（例如6800），同时确认它加 1 后的控制台端口（此例6801）也可用，再保存。 - 正常停止并重启
datahub.exe，用启动日志 Static Web Console 给出的完整地址访问控制台；此例是http://127.0.0.1:6801/web/，不是6800/web/。端口不是任意数字都可用；再次失败时按新错误排查，不要关闭防火墙或强行结束不认识的程序。 - 改配置文件必须重启才生效。
/ping正常只证明 API 可访问；若启动日志提示只提供 API，先核对发布包的web\index.html及启动目录，见打开控制台。API 与控制台端口都不能直接开放到公网。
从另一台电脑打不开控制台
默认配置只接受本机访问（server.host 为 "127.0.0.1"）。确需内网访问时把它改成 "0.0.0.0" 并重启；同时务必确认网络可信——控制台没有登录密码，见首次使用的安全提示。
需要登录吗？忘记密码怎么办？
不需要登录，也没有账号密码。控制台地址直接打开即可；页面上如出现"登录/注册"样式页面，是模板残留地址（/web/login），不是真实入口。既然没有登录，也就没有"忘记密码"问题——保护控制台靠的是网络边界（别暴露给不可信的人）。
机器人与连接
机器人列表里状态"启用"，但在线状态是"离线"
启用≠在线。"启用"只是档案开关；在线需要：连接配置已启用 + OneBot 实现端已启动并登录 + 通信链路正常。逐项检查后，在机器人管理页点刷新再看。
连接状态一直显示"连接中"
本程序在反复尝试连接你填的地址但连不上。检查：实现端是否已启动、地址/端口/路径是否写对、方向是否选反（正向=本程序开端口等待；反向=本程序主动连出去，与部分实现端软件的叫法相反，别按名字猜）。可在 logs\datahub.log 搜 dial failed，错误原文会写明连不上谁。
连接状态"异常"，后面跟了一串英文
这就是失败原因，常见如 config missing url …（配置缺地址）。系统自带的"默认连接"因为没有填地址，启动后就会显示这条异常——这是自带示例的正常状态，不是你装坏了；不需要它就禁用，需要用就编辑它填上地址。
正向连接显示"已连接"，但群里没任何反应
"已连接"只说明链路这一侧就绪（正向连接下本程序端口开成功就可能显示），不代表实现端已经接入、更不代表收到群消息。请确认实现端确实已按该地址/端口连入，并以能否收到群消息为准。
接入成功后，群列表还是空的
“默认QQ群设置”是内置配置模板，不代表真实群已经接入。接入成功后到 群设置 → 群列表 → 同步群，选择在线连接，并核对目标 QQ 群号。按连接机器人的步骤同步，再确认列表中的群号、名称与所属连接。
设置与生效
保存成功了，为什么群里没反应
"保存成功"只说明配置已记下。要按顺序核对整条链路：机器人在线 → 机器人在目标群里 → 群设置里对应功能已开启 → 方案/规则已启用 → 触发条件真的满足。任何一环断了，群里都不会有动作；可在 日志中心（群消息记录、审计日志、应用日志）对照排查。
问答不回复，先查什么？
先核对选群、词条启用和实际匹配方式，再查这条消息是否先被有效指令或审核规则处理。问答页的测试匹配不能代替真实发群验证。命中数、受理数、发送确认的含义及全局问答层限制见问答。
关闭群聊监控，为什么还有动作？
这个开关只控制本群关键词、刷屏执法、媒体识别、撤回与消息留存，不是全部处罚来源的总闸。文件监控、群员事件、智能名片、指令及持续清退有各自入口。按群聊监控和止损说明查具体来源，不反复开关无关功能。
为什么第二次警告就禁言，或信用分没有变化？
警告有累计窗口与次数升级，信用分另按启用状态、事件类型和扣分规则判断；两者不是同一计数。先读告警与信用分，核对当前群保存的规则，不用表单初始值猜处罚。
只想让某个词/某个人不被处理
关键词层面：监控规则里的 免检词（消息含免检词时只豁免这一条规则，不是整个方案）。人的层面：规则里的 等级规避（达到该权限等级的用户不适用该规则）。群管还有独立的受保护用户判定，适用条件见权限管理；名单配置分别见全局黑白名单和群黑白名单，不能把某一条规则的豁免当成全局保护。
备份文件在哪？怎么确认备份是好的？
默认在发布包目录 backups\ 下，改过备份路径时以实际配置为准；文件名形如 backup_20260930_030000_xxxxxxxx.gz。到 应用设置 → 高级设置 → 数据备份设置 → 查看历史，点记录里的 验证，出现"备份完整性校验通过"表示归档通过了该项校验，不表示已经实际恢复，也不保证归档包含程序目录里的全部文件。注意：当前界面提供备份、历史记录和完整性校验，没有执行数据恢复的操作入口，重要备份请另行复制到其他盘或设备。
恢复备份前，验证通过能说明什么？
“验证”只检查归档，不会把数据还原到在线数据库；“恢复默认”只重置相应配置，也不是备份恢复。当前控制台没有恢复入口，本手册也不提供经过验证的恢复步骤。请保留原程序、部署配置、数据库和自定义路径中的文件，将备份另存到安全位置，并联系维护者确认适用的恢复方案；不要自行解压覆盖数据库。备份范围与限制见恢复备份。
怎样核对页面上的版本号？
仪表盘“系统信息”卡与左侧栏底部显示的都是后端程序构建版本，来源相同；页面页脚只有版权文字，不提供独立的前端版本号。两处版本相同不能证明前端文件也已更新。排障时记录显示的版本、构建时间（如有）、所用系统和完整错误信息；不要用安装目录名代替版本。检查更新只查询版本信息，不会替换程序。
停用与恢复
怎样临时停掉某个功能
大多数功能都有开关：监控方案可整体停用，单条规则可禁用，群级功能在对应群设置里关闭；AI 的停用方法见AI 功能。保存后刷新确认开关仍为关闭。停用通常保留配置，但不会撤销已经发出的消息、禁言或踢出；正在执行的操作也不能仅凭开关关闭就认定已取消。
怎样完全停止程序
到运行 datahub.exe 的窗口按 Ctrl+C，等待程序退出。下次从同一目录、使用同一配置启动，程序会读取原有数据；改过数据库、日志、图片或备份路径的，应同时保留那些目录。不要把正常重启当成备份恢复，也不要用强制结束进程替代正常停止。
还有没覆盖到的现象？先到 日志中心 → 应用日志 按时间点找错误条目，把错误文字拿去搜索或提问。