常见问题
按症状查找答案；部署、启动与运行时问题先完成 排障 的前三项检查。需要继续定位时，再按下列入口进入对应专题。查日志落盘路径、控制台导出或 Docker/curl 拉日志见 日志。
问题分类
聊天内容与学习
牛牛为什么会说群里没出现过的话？
A: 有跨群机制。超过阈值的相似表达会沉淀成全局语料，别的群也可能用上。
为什么有时像在回复「命令」？
A: 可能是从其他机器人、或其他群的消息里学到的。
怎么教牛牛说一句固定的话？
A: 重复训练即可，例如：
—— 牛牛你好
—— 你好呀
—— 牛牛你好
—— 你好呀
—— 牛牛你好
—— 你好呀账号与管理
牛牛说了不合适的话怎么处理？
A: 群管或号主（admins 里的 QQ）回复那条消息发「不可以」，或直接撤回。多群一起禁用后，会变成全局禁用。
没人说话时，为什么牛牛会突然发言？
A: 主动发言功能。内容同样来自学到的群聊语料。
管理员、号主、超管都是什么?
A: 见专页 号主（含三种角色对照与配置步骤）。摘要：
| 角色 | 是谁 |
|---|---|
| 群管理员 | QQ 群里的管理员 |
| 号主 | 该牛数据库 admins 里的 QQ |
| 超管 | pallas.toml 的 [bootstrap] superusers |
如何为牛牛配置号主（admins）？
A: 推荐在控制台 实例与连接 初始化 / 编辑，或超管私聊 牛牛添加号主 …。步骤、示例与其它方式见 号主。
方式四：MongoDB（DB_BACKEND=mongodb）（控制台不便时）
- 集合名：
config（对应代码中的BotConfigModule）。 - 文档字段：
account（牛牛 QQ，数值）、admins（QQ 号数组）。 - 库名：与当前 Bot 使用的 Mongo 数据库名一致（见
config/pallas.toml的[bootstrap.mongo] db或连接串说明）。
在 mongosh 中示例（将数字换成实际 QQ）：
db.config.updateOne(
{ account: 3888888888 },
{ $set: { admins: [2777777777, 2666666666] } }
)若该 account 尚无文档，可在 Web「实例与连接」用 初始化配置 创建，或自行插入完整结构。
方式五：PostgreSQL（DB_BACKEND=postgresql）
- 表名：
bot_config。 - 主键列：
account（bigint，牛牛 QQ）。 admins：jsonb，内容为 JSON 数组。
UPDATE bot_config
SET admins = '[2777777777, 2666666666]'::jsonb
WHERE account = 3888888888;也可在 WebUI「数据库」页直接编辑 bot_config 表。
如何备份 MongoDB / PostgreSQL？
A: WebUI「数据库」页有「数据库备份」面板；若未检测到 mongodump / pg_dump，页面会给出官方下载链接。也可在仓库根执行：uv run python tools/scripts/backup_database.py（按当前 db_backend），PostgreSQL 专用：uv run python tools/scripts/backup_pg.py（或 sh tools/scripts/backup_pg.sh）。
更新与版本问题
Docker 和 git clone，更新方式有什么区别？
A: Docker：代码在镜像里，更新主要是 docker compose pull 后重建容器，一般没有本机 git 冲突；数据与配置应在卷（data/、config/pallas.toml 等）里。git clone：更新是 git pull（或控制台「Bot 更新」在检测到 git 工作副本时的等价操作）；若你改过与上游同一已跟踪文件，可能冲突，需本地处理后再拉。详见 升级与站点定制 与 Docker 部署。
git pull --autostash 能避免所有冲突吗？
A: **不能。**它只缓解「有未提交改动时 checkout/merge 被挡住」的情况；双方改了同一行等仍会产生冲突标记，必须人工解决。脚本或定时任务若需无人值守，更稳妥的是使用 git pull --ff-only，失败即停止并告警，而不是强行合并。
控制台「版本与更新」里 Bot 一键更新失败，提示不是 git 工作副本？
A: 典型于 Docker 镜像内运行：容器里没有完整 .git 目录，更新页会显示 deployment_mode: docker，请用 镜像拉取 更新 Bot。若在 clone 目录运行仍失败，请根据返回的 HTTP 详情原文（或日志）排查：git fetch 网络、fetch 后仍无对应标签、stash pop 冲突，或 非快进（开发路径使用 pull --ff-only）等。
怎样减少以后 git pull 跟上游冲突？
A: 尽量不要在仓库里直接改已跟踪源码；自定义用 config/pallas.toml、data/（含 WebUI 的 webui.json）、local/plugins/（extra_plugin_dirs）以及文档允许的挂载路径。若必须改源码，建议 fork 后维护自己的分支。详见 升级与站点定制。
控制台更新页显示的 deployment_mode 是什么？
A: docker：请用镜像更新；release_tag / release_tag_dirty / dev_clone：分别表示发布 tag 干净目录、tag 上有本地改动、开发分支克隆；后三者可用 WebUI git 更新（dirty 时会自动 stash）。见 升级与站点定制。
启动、连接与 Docker 排障
启动后不回复查什么？
A: 先按 排障 的前三项检查部署形态、配置覆盖与连接路径；随后检查数据库连通性、OneBot WebSocket 是否已连上（Docker 默认 Compose 无独立 NapCat，需在 /pallas/protocol 创建实例并配置 WS），以及控制台是否有持续报错。
控制台 / 协议端管理页的登录密钥在哪里配？
A: 不再从 .env 读取密钥。首次启动在日志里打印随机密钥，哈希保存在 data/pallas_console/auth_state.json；浏览器访问 /pallas/login 或协议端登录页登录。仅本机开发可在 pallas_webui 配置中开启 pallas_webui_dev_mode 跳过控制台鉴权。
遗忘了控制台 / 协议端管理页的登录密钥怎么办？
A: 磁盘上只有哈希，没有「忘记密码」邮件或在线找回；需能访问 Bot 的数据目录或历史日志。
- 从未在设置里改过密钥：可看同目录下的
data/pallas_console/default_login_password.txt（若仍存在）。 - 仍保留首次启动时的终端 / 容器日志：其中会有「Pallas-Bot 默认密钥」一类输出。
- 以上都没有：停掉 Bot，删除或移走
data/pallas_console/auth_state.json后重启；进程会重新生成随机密钥并写入日志（必要时可一并删除session_secret.bin，避免旧会话状态干扰）。所有已登录会话会失效，新密钥请妥善保存。
执行 docker compose 时报 project name must not be empty 怎么办？
A: Compose 默认用当前文件夹名作为项目名；目录名为中文等时，部分 Docker Desktop 会推出空项目名从而报错。处理方式：
- 使用本仓库最新的
docker-compose.yml，其中已设置顶层name: pallas-bot。 - 或启动时显式指定项目名：
docker compose -p pallas-bot up -d（带 profile 时同理写在--profile前即可）。 - PowerShell 也可先执行：
$env:COMPOSE_PROJECT_NAME = "pallas-bot"。
同一台机器多套实例请使用不同项目名（如 -p pallas-home2），避免网络与资源名冲突。更多说明见 Docker 部署 文档中的「排障」一节。
Postgres 容器日志里 FATAL: database "PallasBot" does not exist 是什么问题？
A: 表示 Postgres 里没有叫 PallasBot 的库，而 Bot 的 PG_DB（默认）正在连它。常见情况是 ./postgres/data 卷以前用别的 POSTGRES_DB 初始化过，改配置后不会自动建新库。可对齐 PG_DB 与已有库名、删卷重建（会丢数据）或进容器 CREATE DATABASE。本地也可设 PG_AUTO_CREATE_DB=true（需 CREATEDB）。详见 Docker 部署、deploy/pg/README.md。
PostgreSQL 是否一定要用超级用户 / 管理员账号？
A: 不必。 默认路径只连目标库做建表与迁移，不会尝试安装 pg_stat_statements。需要慢查询统计时，在 [env] 显式设置 PG_STAT_STATEMENTS_ENABLED = "true"；数据库管理员还须预加载 pg_stat_statements，并让该账号能够创建扩展或预先创建它。Compose 用 POSTGRES_DB 建好库即可。托管 PG 请先建空库再填连接信息；可选扩展见 deploy/pg/extensions.sql。对应需求：Issue #222。
Docker 里日志写「连接 MongoDB 127.0.0.1:27017」对吗？
A: 在容器里 127.0.0.1 只指向容器自己，连不到 Compose 里的 postgres / mongodb 服务。本仓库 docker-compose.yml 已注入 PG_HOST=postgres、PG_PORT=5432（与 service 名一致）；--profile mongo 时另有 MONGO_HOST=mongodb、MONGO_PORT=27017，覆盖 pallas.toml 里写的本机地址；若仍看到 127.0.0.1，多半是旧 compose 未更新或自建编排未设置。外置数据库时请删改 compose 里对应项并在 pallas.toml 写明真实地址。详见 Docker 部署。
Docker 里 help 报「样式路径不存在 /app/resource/styles/default」？
A: 常见原因是 volume 把整个 /app/resource 挂成宿主机目录，而宿主机上没有 resource/styles/default，盖住了镜像里自带的 help 样式。请把 compose 改为只挂载 ./pallas-bot/resource/voices:/app/resource/voices（与仓库 docker-compose.yml 一致），或在宿主机 resource 下补全 styles/default。详见 Docker 部署 排障。
本地 docker build 拉 python:3.12-slim 报 registry-1.docker.io / EOF？
A: 多为 Docker Hub 访问不稳定（国内常见）。可在仓库根目录使用带 BASE_IMAGE 的镜像前缀构建，例如：docker build --build-arg BASE_IMAGE=docker.m.daocloud.io/library/python:3.12-slim -t pallasbot:local .（以你当前能访问的镜像站为准）；或为 Docker 配置 registry-mirrors / 代理。完整的 Compose 镜像覆盖、uv 索引与 WebUI Git 镜像边界见 Docker 部署 · 下载慢与镜像源。
Docker Compose 起内置 Postgres 时，还要不要在 compose 里再配一套 POSTGRES_USER？
A: 不用。 仓库 docker-compose.yml 已用 PG_USER / PG_PASSWORD / PG_DB 插值生成 POSTGRES_*。你只需在 pallas-bot/config/compose.env（由 config/compose.env.example 复制）里维护 PG_*，并与 pallas.toml 的 [bootstrap.postgres] 一致；启动时带上 docker compose --env-file ./pallas-bot/config/compose.env up -d。否则插值会回落到 compose 默认值，可能与 Bot 实际使用的账号不一致。
Docker 启动报错里提到 mounting、pallas.toml、not a directory 或 directory onto file 是什么情况？
A: Compose 把宿主机 ./pallas-bot/config/pallas.toml 挂到容器 /app/config/pallas.toml，两边都必须是同一个文件。若宿主机上该路径被建成了文件夹（例如在还没有配置文件时就启动过，或手动建错），就会报这类错。请删除错误目录，从仓库复制 config/pallas.example.toml 为文件放到该路径，再重新 docker compose up。详见 Docker 部署 中「排障」与配置步骤里的说明。
协议端管理里反向 WebSocket 要不要写成「主机为 pallasbot」？和 Compose 的 pallasbot 是什么关系？
A: pallasbot 只是 Compose 服务名，DNS 只在同一 Compose 网络里的容器之间有效。协议端在 Linux Docker 模式下用 docker run 起的 NapCat 默认不在该网络里；若把客户端地址写成 ws://pallasbot:<PORT>/onebot/v11/ws（明文 WebSocket、主机填服务名），在默认桥接场景下往往连不上。插件会把 主机 改成解析后的 PALLAS_PROTOCOL_DOCKER_ONEBOT_HOST（留空时 Linux bridge 多为默认网关 IP 或 172.17.0.1；host 网络为 127.0.0.1）再写入 onebot*.json，不会自动替你填 pallasbot。一般不必为此去「取消」Compose 自定义网络；只有当你自行把 NapCat 做成与 Bot 同一 Compose 网络的 service 时，才适合继续用 ws://pallasbot:<PORT>/onebot/v11/ws 这类内网写法。详见 Docker 部署 与 pb_protocol 插件说明 中「Docker 与反向 WebSocket」一节。
V4 布局与迁移问题
「媒体服务 / AI Runtime」显示不可达，聊天也不能配了吗？
A: 不能混为一谈。 LLM 聊天固定走 Bot 内核 Provider，在 AI 配置 → 接入 测通并保存即可，不要求 :9099 可达。媒体服务红灯只影响唱歌/TTS 等媒体任务。排障见 LLM 与 AI。
3.x 的 src/plugins 插件在 V4 还能用吗？
A: 不能沿用旧加载目录。 3.x 的 NoneBot plugin_dirs 指向 src/plugins/；V4 已改为 packages/，不会再扫描 src/plugins/。内置玩法迁至 packages/ 与 pallas-plugin-* 官方插件；站点私有插件放 local/plugins/，社区插件应使用 pallas.api.*。从 3.x 升级请读 V4 迁移指南。
社区作者如何只依赖内核、不克隆整仓？
A: 使用 PyPI 包 pallas-core（也可本地构建 wheel：./scripts/build_core.sh），在扩展 pyproject.toml 声明 pallas-core>=4.0.0,<5.0.0，业务代码只 import pallas.api.*。示例见 pallas.api Cookbook 与 templates/pallas-plugin-extension/。
WebUI 首次登录为什么要走 Setup Wizard？
A: 默认密钥仅用于首次启动；改密后 setup_state.json 标记完成，路由守卫才放行其它页面。向导还推荐配置协议端与插件扩展。需要智能对话时再到侧栏 AI 配置 配 Provider 并打开对话总闸。详见 WebUI「首次 Setup Wizard」页。
