常见问题
不知道从哪查？先走下面决策树。
专题入口：五分钟跑起来 · 运维入口 · 排障 · 配置要点
不确定属于哪一类？
专题页：
学习机制
Q: 牛牛为什么会说群里没出现过的话？
A: 有跨群机制。超过阈值的相似表达会沉淀成全局语料，别的群也可能用上。
Q: 为什么有时像在回复「命令」？
A: 可能是从其他机器人、或其他群的消息里学到的。
Q: 怎么教牛牛说一句固定的话？
A: 重复训练就行，例如：
—— 牛牛你好
—— 你好呀
—— 牛牛你好
—— 你好呀
—— 牛牛你好
—— 你好呀使用与管理
Q: 牛牛说了不合适的话怎么处理？
A: 群管或号主（admins 里的 QQ）回复那条消息发「不可以」，或直接撤回。多群一起禁用后，会变成全局禁用。
Q: 没人说话时，为什么牛牛会突然发言？
A: 主动发言功能。内容同样来自学到的群聊语料。
Q: 管理员、号主、超管都是什么?
A:
| 角色 | 是谁 |
|---|---|
| 群管理员 | QQ 群里的管理员 |
| 号主 | 该牛数据库 admins 里的 QQ（旧称「牛牛管理员」）；可管这只牛的部分能力，例如私聊「牛牛重新上号」 |
| 超管 | config/pallas.toml 的 [bootstrap] superusers（或 SUPERUSERS），对所有牛最高权限 |
运维该牛的人，通常应写进 admins。怎么配见下文 如何为牛牛配置号主（admins）。
Q: 如何为牛牛配置号主（admins）？
A: account 为该牛牛的 QQ 号；admins 为 QQ 号组成的 JSON 数组（整数）。不能在 .env 里配置；改库或 Web 控制台保存后，权限会按 BotConfig 缓存规则生效（Mongo 侧文档缓存约 60 秒），未立刻生效时可稍等或重启 Bot。
方式一：Web 控制台「实例与连接」（推荐）
- 浏览器登录 Pallas-Bot 控制台（路径前缀见
pallas_webui的PALLAS_WEBUI_HTTP_BASE，常见为/pallas/）。 - 打开侧边栏 「实例与连接」。
- 在 「NoneBot 框架」 面板找到目标牛牛：若 库配置 为 未入库，点 「初始化配置」，添加号主 QQ 并保存。会在数据库中创建该牛的
bot_config行，不依赖协议端或relogin_bot插件。 - 已在库中的牛牛可在 「数据库中的实例」 面板点编辑修改号主与其它选项。
方式二：Web 控制台「数据库管理」
- 打开侧边栏 「数据库管理」（前端路由
database，完整路径形如/pallas/database）。 - 在表类型中选择
config (bot_config)，找到或新建account等于目标牛牛 QQ 的行。 - 编辑
admins为 JSON 数组（例如[123456789, 987654321]）并保存。
可选：relogin_bot「创建牛牛」时自动写入
若已启用 relogin_bot（pallas-plugin-protocol），超管私聊 「创建牛牛」 可在参数中带 号主 QQ（可多个）；协议端创建账号并启动后会自动写入 admins。未使用该插件、或牛牛已在其它协议端连上时，请用方式一。
命令格式见 relogin_bot 说明。
方式三：超管私聊「牛牛添加号主」（pb_core）
由 pb_core（牛牛核心，默认加载）提供，仅超管可用，须 私聊 牛牛发送：
默认所有 QQ 都加到 当前私聊的牛；只有显式带 牛 目标牛QQ（关键字后空格接 QQ）时才改配指定牛。
| 场景 | 示例 |
|---|---|
| 为当前私聊的牛添加号主 | 牛牛添加号主 2777777777 |
| 一次为当前牛添加多个号主 | 牛牛添加号主 2777777777 2666666666 |
| 多牛部署，指定目标牛 | 牛牛添加号主 2777777777 牛 3888888888 |
目标牛关键字也可写作 牛牛、bot、account（关键字后空格接 QQ）。也可 @ 号主 代替手写 QQ。若目标牛 尚未入库，命令会 自动创建 bot_config 行并写入 admins；已在库中则 合并追加（去重）。详见 pb_core 说明。
方式四：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 表。
Q: 如何备份 MongoDB / PostgreSQL？
A: WebUI「数据库」页有「数据库备份」面板；若未检测到 mongodump / pg_dump，页面会给出官方下载链接。也可在仓库根执行：uv run python tools/scripts/backup_database.py（按当前 db_backend），PostgreSQL 专用：tools/scripts/backup_pg.py 或 sh tools/scripts/backup.sh -p。
更新与版本
Q: Docker 和 git clone，更新方式有啥区别？
A: Docker：代码在镜像里，更新主要是 docker compose pull 后重建容器，一般没有本机 git 冲突；数据与配置应在卷（data/、config/pallas.toml 等）里。git clone：更新是 git pull（或控制台「Bot 更新」在检测到 git 工作副本时的等价操作）；若你改过与上游同一已跟踪文件，可能冲突，需本地处理后再拉。详见 标准部署 - 后续更新 与 Docker 部署。
Q: git pull --autostash 能避免所有冲突吗？
A: **不能。**它只缓解「有未提交改动时 checkout/merge 被挡住」的情况；双方改了同一行等仍会产生冲突标记，必须人工解决。脚本或定时任务若需无人值守，更稳妥的是使用 git pull --ff-only，失败即停止并告警，而不是强行合并。
Q: 控制台「版本与更新」里 Bot 一键更新失败，提示不是 git 工作副本？
A: 典型于 Docker 镜像内运行：容器里没有完整 .git 目录，更新页会显示 deployment_mode: docker，请用 镜像拉取 更新 Bot。若在 clone 目录运行仍失败，请根据返回的 HTTP 详情原文（或日志）排查：git fetch 网络、fetch 后仍无对应标签、stash pop 冲突，或 非快进（开发路径使用 pull --ff-only）等。
Q: 怎样减少以后 git pull 跟上游冲突？
A: 尽量不要在仓库里直接改已跟踪源码；自定义用 config/pallas.toml、data/（含 WebUI 的 webui.json）、local/plugins/（extra_plugin_dirs）以及文档允许的挂载路径。若必须改源码，建议 fork 后维护自己的分支。详见 升级与站点定制。
Q: 控制台更新页显示的 deployment_mode 是什么？
A: docker：请用镜像更新；release_tag / release_tag_dirty / dev_clone：分别表示发布 tag 干净目录、tag 上有本地改动、开发分支克隆；后三者可用 WebUI git 更新（dirty 时会自动 stash）。见 升级与站点定制。
部署排障
Q: 启动后不回复，应该先查什么？
A: 先检查数据库连通性、OneBot WebSocket 是否已连上（Docker 默认 Compose 无独立 NapCat，需在 /pallas/protocol 协议端管理里创建实例并配置 WS）、config/pallas.toml 与 data/pallas_config/webui.json 是否生效，再看控制台是否有持续报错。
Q: 控制台 / 协议端管理页的口令在哪里配？
A: 不再从 .env 读取口令。首次启动在日志里打印随机口令，哈希保存在 data/pallas_console/auth_state.json；浏览器访问 /pallas/login 或协议端登录页登录。仅本机开发可在 pallas_webui 配置中开启 pallas_webui_dev_mode 跳过控制台鉴权。
Q: 遗忘了控制台 / 协议端管理页的登录口令怎么办？
A: 磁盘上只有哈希，没有「忘记密码」邮件或在线找回；需能访问 Bot 的数据目录或历史日志。
- 从未在设置里改过口令：可看同目录下的
data/pallas_console/default_login_password.txt（若仍存在）。 - 仍保留首次启动时的终端 / 容器日志：其中会有「Pallas-Bot 默认口令」一类输出。
- 以上都没有：停掉 Bot，删除或移走
data/pallas_console/auth_state.json后重启；进程会重新生成随机口令并写入日志（必要时可一并删除session_secret.bin，避免旧会话状态干扰）。所有已登录会话会失效，新口令请妥善保存。
Q: 执行 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 部署 文档中的「排障」一节。
Q: 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。
Q: PostgreSQL 是否一定要用超级用户 / 管理员账号？
A: 不必。 4.0 默认路径只连目标库做建表与迁移；pg_stat_statements 在独立事务里尝试启用，失败只降级诊断。Compose 用 POSTGRES_DB 建好库即可。托管 PG 请先建空库再填连接信息；可选扩展见 deploy/pg/extensions.sql。对应需求：Issue #222。
Q: Docker 里日志写「连接 MongoDB 127.0.0.1:27017」对吗？
A: 在容器里 127.0.0.1 只指向容器自己，连不到 Compose 里的 mongodb / postgres 服务。本仓库 docker-compose.yml 已注入 MONGO_HOST=mongodb、MONGO_PORT=27017，并在用内置 PG 时注入 PG_HOST=postgres、PG_PORT=5432（与 service 名一致），覆盖 pallas.toml 里写的本机地址；若仍看到 127.0.0.1，多半是旧 compose 未更新或自建编排未设置。外置数据库时请删改 compose 里对应项并在 pallas.toml 写明真实地址。详见 Docker 部署。
Q: 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 部署 排障。
Q: 本地 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 / 代理。详见 Docker 部署 排障。
Q: 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 --profile postgres up -d。否则插值会回落到 compose 默认值，可能与 Bot 实际使用的账号不一致。
Q: 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 部署 中「排障」与配置步骤里的说明。
Q: 协议端管理里反向 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」一节。
4.0 布局与迁移
Q: 3.x 的 src/plugins 插件在 4.0 还能用吗？
A: 不能沿用旧路径。 4.0 已移除 src/ 目录；内置玩法迁至 packages/ 与 pallas-plugin-* 官方插件，社区插件应使用 pallas.api.* 与 packages/<name>/ 或 local/plugins/ 布局。从 3.x 升级请读 4.0 迁移指南。
Q: 社区作者如何只依赖内核、不克隆整仓？
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/。
Q: WebUI 首次登录为什么要走 Setup Wizard？
A: 默认口令仅用于首次启动；改密后 setup_state.json 标记完成，路由守卫才放行其它页面。向导还推荐配置协议端与插件扩展；AI 体检仅在需要智能对话时可选配置。详见 WebUI「首次 Setup Wizard」页。
