> 规范网页：https://docs.tensuu.com/快速入门指南/常见问题.html ｜ Markdown：/快速入门指南/常见问题.md ｜ 文档修订：2026.10.26

# 常见问题与排障

按你遇到的现象找条目。先查对应业务记录，再按同一时间点核对应用日志；不同记录能证明的范围见[结果判断与排障](../核心概念/结果判断与排障.md)和[应用日志](../功能模块详解/17_应用日志.md)。文件日志以实际部署路径为准，默认 `logs\datahub.log`。

## 安装与启动

### 双击 datahub.exe 窗口一闪就没

程序留下了错误信息就退出了。请改用命令提示符启动（见[首次使用](首次使用.md#启动-运行-datahub-exe)），窗口会停留并显示原因。常见原因：端口被占用、`configs\config.yaml` 被改坏（多删了空格或冒号）。

### 提示端口被占用，或浏览器打不开控制台

1. 先看启动窗口：`address already in use` 通常表示端口已被占用；Windows 错误 10013（“访问套接字的方式不被允许”）也可能表示端口被系统保留，即使找不到监听程序也不能使用。
2. 先核对错误中的端口：默认 API 使用 6700，控制台使用 6701。确认需要换端口后，用记事本打开 `configs\config.yaml`，把 `server:` 下 `port: 6700` 改成可用的 API 端口（例如 `6800`），同时确认它加 1 后的控制台端口（此例 `6801`）也可用，再保存。
3. 正常停止并重启 `datahub.exe`，用启动日志 **Static Web Console** 给出的完整地址访问控制台；此例是 `http://127.0.0.1:6801/web/`，不是 `6800/web/`。端口不是任意数字都可用；再次失败时按新错误排查，不要关闭防火墙或强行结束不认识的程序。
4. 改配置文件必须重启才生效。`/ping` 正常只证明 API 可访问；若启动日志提示只提供 API，先核对发布包的 `web\index.html` 及启动目录，见[打开控制台](首次使用.md#打开控制台)。API 与控制台端口都不能直接开放到公网。

### 从另一台电脑打不开控制台

默认配置只接受**本机**访问（`server.host` 为 `"127.0.0.1"`）。确需内网访问时把它改成 `"0.0.0.0"` 并重启；同时务必确认网络可信——控制台没有登录密码，见[首次使用](首次使用.md)的安全提示。

### 需要登录吗？忘记密码怎么办？

不需要登录，也没有账号密码。控制台地址直接打开即可；页面上如出现"登录/注册"样式页面，是模板残留地址（`/web/login`），不是真实入口。既然没有登录，也就没有"忘记密码"问题——保护控制台靠的是网络边界（别暴露给不可信的人）。

## 机器人与连接

### 机器人列表里状态"启用"，但在线状态是"离线"

**启用≠在线**。"启用"只是档案开关；在线需要：连接配置已启用 + OneBot 实现端已启动并登录 + 通信链路正常。逐项检查后，在机器人管理页点刷新再看。

### 连接状态一直显示"连接中"

本程序在反复尝试连接你填的地址但连不上。检查：实现端是否已启动、地址/端口/路径是否写对、方向是否选反（**正向=本程序开端口等待；反向=本程序主动连出去**，与部分实现端软件的叫法相反，别按名字猜）。可在 `logs\datahub.log` 搜 `dial failed`，错误原文会写明连不上谁。

### 连接状态"异常"，后面跟了一串英文

这就是失败原因，常见如 `config missing url …`（配置缺地址）。系统自带的"默认连接"因为没有填地址，启动后就会显示这条异常——**这是自带示例的正常状态**，不是你装坏了；不需要它就禁用，需要用就编辑它填上地址。

### 正向连接显示"已连接"，但群里没任何反应

"已连接"只说明链路这一侧就绪（正向连接下本程序端口开成功就可能显示），**不代表实现端已经接入、更不代表收到群消息**。请确认实现端确实已按该地址/端口连入，并以能否收到群消息为准。

### 接入成功后，群列表还是空的

“默认QQ群设置”是内置配置模板，不代表真实群已经接入。接入成功后到 **群设置 → 群列表 → 同步群**，选择在线连接，并核对目标 QQ 群号。按[连接机器人](连接机器人.md#更多说明)的步骤同步，再确认列表中的群号、名称与所属连接。

## 设置与生效

### 保存成功了，为什么群里没反应

"保存成功"只说明配置已记下。要按顺序核对整条链路：机器人在线 → 机器人在目标群里 → 群设置里对应功能已开启 → 方案/规则已启用 → 触发条件真的满足。任何一环断了，群里都不会有动作；可在 **日志中心**（群消息记录、审计日志、应用日志）对照排查。

### 问答不回复，先查什么？ {#问答为什么没有回复}

先核对选群、词条启用和实际匹配方式，再查这条消息是否先被有效指令或审核规则处理。问答页的测试匹配不能代替真实发群验证。命中数、受理数、发送确认的含义及全局问答层限制见[问答](../功能模块详解/15_问答.md)。

### 关闭群聊监控，为什么还有动作？

这个开关只控制本群关键词、刷屏执法、媒体识别、撤回与消息留存，不是全部处罚来源的总闸。文件监控、群员事件、智能名片、指令及持续清退有各自入口。按[群聊监控](../功能模块详解/08_群聊监控.md)和[止损说明](../核心概念/结果判断与排障.md#止损与回退)查具体来源，不反复开关无关功能。

### 为什么第二次警告就禁言，或信用分没有变化？

警告有累计窗口与次数升级，信用分另按启用状态、事件类型和扣分规则判断；两者不是同一计数。先读[告警与信用分](../功能模块详解/群基本设置.md#告警与信用分)，核对当前群保存的规则，不用表单初始值猜处罚。

### 只想让某个词/某个人不被处理

关键词层面：监控规则里的 **免检词**（消息含免检词时只豁免这一条规则，不是整个方案）。人的层面：规则里的 **等级规避**（达到该权限等级的用户不适用该规则）。群管还有独立的受保护用户判定，适用条件见[权限管理](../高级功能/权限管理.md)；名单配置分别见[全局黑白名单](../功能模块详解/06_全局黑白名单.md)和[群黑白名单](../功能模块详解/14_黑白名单.md)，不能把某一条规则的豁免当成全局保护。

### 备份文件在哪？怎么确认备份是好的？

默认在发布包目录 `backups\` 下，改过备份路径时以实际配置为准；文件名形如 `backup_20260930_030000_xxxxxxxx.gz`。到 **应用设置 → 高级设置 → 数据备份设置 → 查看历史**，点记录里的 **验证**，出现"备份完整性校验通过"表示归档通过了该项校验，不表示已经实际恢复，也不保证归档包含程序目录里的全部文件。注意：当前界面提供备份、历史记录和完整性校验，没有执行数据恢复的操作入口，重要备份请另行复制到其他盘或设备。

### 恢复备份前，验证通过能说明什么？ {#备份验证通过-怎样恢复数据}

“验证”只检查归档，不会把数据还原到在线数据库；“恢复默认”只重置相应配置，也不是备份恢复。当前控制台没有恢复入口，本手册也不提供经过验证的恢复步骤。请保留原程序、部署配置、数据库和自定义路径中的文件，将备份另存到安全位置，并联系维护者确认适用的恢复方案；不要自行解压覆盖数据库。备份范围与限制见[恢复备份](../功能模块详解/07_云端设置.md#当前没有数据恢复入口)。

### 怎样核对页面上的版本号？ {#页面上两个版本号不一样}

仪表盘“系统信息”卡与**左侧栏底部**显示的都是后端程序构建版本，来源相同；页面页脚只有版权文字，不提供独立的前端版本号。两处版本相同不能证明前端文件也已更新。排障时记录显示的版本、构建时间（如有）、所用系统和完整错误信息；不要用安装目录名代替版本。检查更新只查询版本信息，不会替换程序。

## 停用与恢复

### 怎样临时停掉某个功能

大多数功能都有开关：监控方案可整体停用，单条规则可禁用，群级功能在对应群设置里关闭；AI 的停用方法见[AI 功能](../功能模块详解/28_AI%20功能.md)。保存后刷新确认开关仍为关闭。停用通常保留配置，但不会撤销已经发出的消息、禁言或踢出；正在执行的操作也不能仅凭开关关闭就认定已取消。

### 怎样完全停止程序

到运行 `datahub.exe` 的窗口按 `Ctrl+C`，等待程序退出。下次从同一目录、使用同一配置启动，程序会读取原有数据；改过数据库、日志、图片或备份路径的，应同时保留那些目录。不要把正常重启当成备份恢复，也不要用强制结束进程替代正常停止。

---

还有没覆盖到的现象？先到 **日志中心 → 应用日志** 按时间点找错误条目，把错误文字拿去搜索或提问。