常见问题（FAQ）

May 14, 2026 · View on GitHub

导航：README · 标准部署 · Docker 部署

本页收录 Pallas-Bot 的常见问题与排查建议。若你是首次部署，建议先阅读 README.md 中的「快速开始」；控制台与协议端管理页的口令说明、遗忘后的重置方式见本页「部署排障」。

学习机制

Q: 怎么教牛牛说一句固定的话？

A: 可以通过重复训练强化，例如：

—— 牛牛你好
—— 你好呀
—— 牛牛你好
—— 你好呀
—— 牛牛你好
—— 你好呀

使用与管理

Q: 牛牛说了不合适的话怎么处理？

A: 群管理员或者号主（在 admins 中的账号）可以回复该消息发送“不可以”，或直接撤回。多群共同禁用后，会形成全局禁用。

Q: 管理员、号主、超管都是什么?

A: 群管理员指 QQ 群里的管理员。号主在本项目文档与帮助里即原「牛牛管理员 / 牛牛管理」所指：数据库 admins 数组里的 QQ，可控制该牛牛的部分能力（例如私聊「牛牛重新上号」）；通常应把实际运维该牛的 QQ 配进 admins。超管即 .env 里 SUPERUSERS，对所有牛牛有最高权限。

给牛牛增加/修改 admins 的方式见下文如何为牛牛配置号主（admins）。

Q: 如何为牛牛配置号主（`admins`）？

A: account 为该牛牛的 QQ 号；admins 为 QQ 号组成的 JSON 数组（整数）。不能在 .env 里配置；改库或改 Web 控制台里的数据后，权限会按 BotConfig 缓存规则生效（Mongo 侧文档缓存约 60 秒），未立刻生效时可稍等或重启 Bot。

新建牛牛时（自动写入 admins）：由超管私聊发送 「创建牛牛」（插件 relogin_bot），在命令参数中带上 号主 QQ（可填多个）；插件在协议端创建账号并启动后，会把这些号主 自动写入该牛牛的 admins，通常不必再手动改库或进 Web「数据库管理」补一行。命令格式与流程见 relogin_bot 说明。

方式一：Web 控制台（推荐，与前端「数据库管理」联动）

浏览器登录 Pallas Web 控制台（路径前缀见 pallas_webui 的 PALLAS_WEBUI_HTTP_BASE，常见为 /pallas/）。
打开侧边栏 「数据库管理」（前端路由 database，完整路径形如 /pallas/database，随 HTTP 基路径变化）。
在表类型中选择 config (bot_config)，找到 account 等于目标牛牛 QQ 的行。
编辑 admins 为 JSON 数组（例如 [123456789, 987654321]）并保存。

方式二：MongoDB（DB_BACKEND=mongodb）

集合名：config（对应代码中的 BotConfigModule）。
文档字段：account（牛牛 QQ，数值）、admins（QQ 号数组）。
库名：与当前 Bot 使用的 Mongo 数据库名一致（见 .env 中 MONGO_DB / 连接串说明）。

在 mongosh 中示例（将数字换成实际 QQ）：

db.config.updateOne(
  { account: 3888888888 },
  { $set: { admins: [2777777777, 2666666666] } }
)

若该 account 尚无文档，需先有 Bot 运行产生的配置或自行插入完整结构；一般已有行时只更新 admins 即可。

方式三：PostgreSQL（DB_BACKEND=postgresql）

表名：bot_config。
主键列：account（bigint，牛牛 QQ）。
admins：jsonb，内容为 JSON 数组。

UPDATE bot_config
SET admins = '[2777777777, 2666666666]'::jsonb
WHERE account = 3888888888;

命令行工具也可使用仓库提供的 tools/config/config.mongodb 等脚本（若你环境已配置好）；与直接改库等价，择一即可。

更新与版本

Q: Docker 部署和 git clone 部署，更新方式有什么区别？

A: Docker：应用代码在镜像里，更新主要是 docker compose pull 后重建容器，一般没有本机仓库的 git 冲突问题；数据与配置应在卷或 .env 中，与镜像代码分离。git clone：更新是 git pull（或控制台「Bot 更新」在检测到 git 工作副本时执行的等价操作），若你修改了与上游同一已跟踪文件，可能出现合并冲突，需要本地处理后再拉。详见标准部署 - 后续更新与 Docker 部署。

Q: `git pull --autostash` 能避免所有冲突吗？

A: **不能。**它只缓解「有未提交改动时 checkout/merge 被挡住」的情况；双方改了同一行等仍会产生冲突标记，必须人工解决。脚本或定时任务若需无人值守，更稳妥的是使用 git pull --ff-only，失败即停止并告警，而不是强行合并。

Q: 控制台「版本与更新」里 Bot 一键更新失败，提示不是 git 工作副本？

A: 典型于 Docker 镜像内运行：容器里没有完整 .git 目录，此时请用 镜像拉取 更新 Bot，不要用该 git 按钮。若在 clone 目录运行仍失败，请根据返回的 HTTP 详情原文（或日志）排查：git fetch 网络、fetch 后仍无对应标签、工作区不干净（发布标签切换路径会拒绝）、或 非快进（开发路径使用 pull --ff-only）等。

Q: 怎样减少以后 `git pull` 跟上游冲突？

A: 尽量不要在仓库里直接改已跟踪源码；自定义用 .env、data/、以及文档允许的挂载路径。若必须改源码，建议 fork 后维护自己的分支，并清楚合并策略，避免与主线长期分叉。

部署排障

Q: 启动后不回复，应该先查什么？

A: 先检查数据库连通性、OneBot WebSocket 是否已连上（Docker 默认 Compose 无独立 NapCat，需在 /protocol/console/ 协议端管理里创建实例并配置 WS）、.env 是否生效，再看控制台是否有持续报错。

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。详见 Docker 部署排障。

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 名一致），覆盖挂载 .env 里的本机地址；若仍看到 127.0.0.1，多半是旧 compose 未更新或自建编排未设置。外置数据库时请删改 compose 里对应项并在 .env 写明真实地址。详见 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/.env 里维护 PG_*（与 Bot 进程读的是同一份），启动时带上 docker compose --env-file ./pallas-bot/.env --profile postgres up -d，让 Compose 能读到这些变量；否则插值会回落到 compose 里写的默认值，可能与 Bot 实际使用的账号不一致。

Q: Docker 启动报错里提到 `mounting`、`.env`、`not a directory` 或 `directory onto file` 是什么情况？

A: Compose 把宿主机 ./pallas-bot/.env 挂到容器 /app/.env，两边都必须是同一个文件。若宿主机上 .env 被建成了文件夹（例如在还没有 .env 文件时就启动过，或手动建错），就会报这类错。请删除宿主机上错误的 pallas-bot/.env 目录，从仓库复制 .env 为文件放到该路径，再重新 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 部署与 pallas_protocol 插件说明中「Docker 与反向 WebSocket」一节。