Pallas-Bot

外观

标准部署 ​

字数
2178 字
阅读时间
10 分钟

面向 VPS / 本机长期运行。只想先跑通请看 五分钟跑起来。

导航

五分钟跑起来 · Docker · 配置 · 连接 QQ · 分片 · FAQ

部署前检查清单 ​

在开始前请确认：

项要求
硬件建议 2 核 CPU / 4 GB 内存 起；多牛或启用 AI 功能需更高配置
系统Linux（推荐）或 Windows；长期运行优先 Linux + systemd
QQ 账号使用小号登录协议端，勿用大号
网络服务器可访问数据库端口；若外网访问控制台，需开放 HTTP 端口（默认 8088）
数据库已安装 PostgreSQL（4.0 默认），或可连接远程实例；3.x 升级可继续用 MongoDB
工具git、Python 3.12+（或由 uv 自动安装）、uv
配置将准备 config/pallas.toml（从示例复制，非可选项）

多牛、高负载生产环境可选用 多进程分片 或 Docker 部署。

步骤 1：获取源码 ​

bash
git clone https://github.com/PallasBot/Pallas-Bot.git
cd Pallas-Bot

如何确认成功：目录内存在 pyproject.toml、config/pallas.example.toml。

国内网络若 git clone 失败，可配置代理或换镜像源后重试。

步骤 2：安装依赖 ​

bash
uv sync
PostgreSQL
bash
uv sync --extra pg
可选：分词加速 perf
bash
uv sync --extra perf

如何确认成功：命令退出码为 0，且 .venv 已创建；可执行 uv run python -c "import nonebot" 无报错。

可选：多进程分片模板

除默认单进程外，可选用 deploy/ 中的分片模板：

场景依赖应用配置
多进程分片uv sync --extra deploy-sharduv run python tools/apply_deploy_profile.py shard → 在 pallas.toml [env] 配置 REDIS_URL → ./scripts/run_sharded_bot.sh start

消息审查 4.0 默认开启，在 WebUI「通用配置 → 消息审查」配置即可，无需部署模板。

当前分片模式依赖 Redis 协调 claim。deploy-shard 与 coord-redis 均安装 redis 依赖；shard extra 不含 redis 客户端，不能单独满足当前分片运行要求。

步骤 3：准备主配置 config/pallas.toml（必做） ​

bash
cp config/pallas.example.toml config/pallas.toml

编辑 config/pallas.toml，至少完成：

  1. [bootstrap] superusers：填写你的 QQ 号（超管，用于控制台与高危操作）。
  2. db_backend：新装默认 postgresql；3.x 升级可继续 mongodb。
  3. [bootstrap.postgres] 或 [bootstrap.mongo]：填写数据库地址、库名、账号密码（与步骤 4 中实际库一致）。

示例（PostgreSQL，4.0 默认）：

toml
[bootstrap]
host = "0.0.0.0"
port = 8088
superusers = ["你的QQ号"]
db_backend = "postgresql"

[bootstrap.postgres]
host = "127.0.0.1"
port = 5432
user = "pallas"
password = "pallas"
db = "PallasBot"

从旧版 .env 迁移：

bash
uv run python tools/migrate_env_to_pallas.py

如何确认成功：config/pallas.toml 为文件（非目录），且 superusers、数据库段已填写。勿将含密钥的文件提交到 git。

插件与通用项可在首次启动后于 Web 控制台修改（落盘 data/pallas_config/webui.json），详见 配置要点 与 配置存储。

步骤 4：准备数据库 ​

4.0 新装默认 PostgreSQL（uv sync --extra pg）。从 3.x 升级、已有 Mongo 数据的站点可继续用 MongoDB，不必为上 4.0 强迁。

库表由 Pallas-Bot 首次启动时自动初始化，无需手工建表（PG 需目标库已存在；勿依赖超级用户）。详见 Docker 部署 · PG 排障。

如何确认成功：

  • PostgreSQL：psql -h ... -U ... -d ... 可登录，且库名与 pallas.toml 中 db 一致。
  • MongoDB（若沿用）：mongosh 或客户端能连上 pallas.toml 中的 host/port。

步骤 5：（可选）语音资源 ​

Pallas-Bot 启动时会尝试自动下载语音包。

FFmpeg 与手动语音包

若需 FFmpeg（唱歌等）：安装 FFmpeg

自动下载失败时，可手动将 Pallas.zip 解压到 resource/voices/，结构见 path_structure.txt。

如何确认成功：启动日志无语音目录相关致命错误；resource/voices/ 下存在预期文件。

步骤 6：启动 Bot ​

bash
uv run nb run

如何确认成功：

  1. 日志中出现 NoneBot / 插件加载完成，无数据库连接致命错误。
  2. 日志中打印 Web 控制台初始口令（存于 data/pallas_console/）。
  3. 浏览器访问 http://<主机IP>:8088/pallas/api/health（或控制台首页），返回正常。
  4. 浏览器打开 http://<主机IP>:8088/pallas/，使用口令登录成功。

勿关闭运行 Bot 的终端（未配置守护时关闭即停止服务）。Linux 生产环境请使用下文 systemd 或 Docker。

步骤 7：接入 QQ 协议端 ​

详见 连接 QQ / 协议端。摘要：

方式 A：协议端管理（推荐）

  1. 打开 http://<主机IP>:8088/pallas/protocol
  2. 创建 NapCat 实例、扫码登录
  3. 确认 WebSocket 指向 ws://<Bot主机>:8088/onebot/v11/ws

方式 B：自管 NapCat

按 NapCat 文档安装，正向 WS 填上述地址。

如何确认成功：控制台显示账号在线；群内发 牛牛帮助 有响应。

生产环境建议 ​

systemd 守护（Linux）

示例 unit（路径与用户按实际修改）：

ini
[Unit]
Description=Pallas-Bot
After=network.target mongod.service

[Service]
Type=simple
User=pallas
WorkingDirectory=/opt/Pallas-Bot
ExecStart=/home/pallas/.local/bin/uv run nb run
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启用：sudo systemctl enable --now pallas-bot.service。状态：systemctl status pallas-bot。

也可使用仓库 tools/scripts/bot_watchdog.py 探活 /pallas/api/health；若 Bot 已由 systemd 启动，须加 --no-spawn，避免重复占用端口。

备份与安全
  • 备份：data/pallas_config/webui.json、data/pallas_console/、协议端实例数据
  • 防火墙：仅对可信网络开放 8088
  • 生产：勿长期开启 pallas_webui_dev_mode；公网访问请 HTTPS + 强口令
  • 更新：git pull + uv sync + 重启；Docker 见 Docker 部署

自定义请尽量只改 config/pallas.toml、data/、local/plugins/。见 升级与站点定制。

多进程分片（可选） ​

同一台机器长期运行多只牛牛且单进程卡顿时，可使用 hub + worker，共用 data/ 与同一份 config/pallas.toml。

  • 启动：./scripts/run_sharded_bot.sh start（详见 多进程分片架构说明）。
  • Redis：必需；请先配置 REDIS_URL 并安装 coord-redis / deploy-shard，否则分片 claim 无法正常工作。
  • 控制台与协议端管理仅访问 hub 端口（默认 8088）。
  • 切换前请备份 data/；Docker 示例见 Docker 部署 · 多进程分片。

进程守护脚本（可选） ​

仓库提供 tools/scripts/bot_watchdog.py：请求 /pallas/api/health，连续失败后结束子进程并重启，或对 Docker 容器执行 docker restart。

场景用法
由脚本拉起 Botuv run python tools/scripts/bot_watchdog.py
Bot 已由 systemd/Docker 运行必须加 --no-spawn
监护容器--docker-container <名> --no-spawn

HOST/PORT 从环境变量或 config/pallas.toml 的 [bootstrap] 读取。完整参数：uv run python tools/scripts/bot_watchdog.py --help。

访问控制台与协议端 ​

服务默认地址
Web 控制台http://<主机>:8088/pallas/
协议端管理http://<主机>:8088/pallas/protocol

修改了 host/port 或自定义路径时，以 pallas.toml 与插件配置为准。

AI 功能（可选） ​

基础功能（复读、轮盘等）不依赖独立 AI 服务。唱歌、酒后闲聊、TTS 等需 Pallas-Bot-AI，对 GPU/内存要求较高，性能不足可跳过。

作为插件部署 ​

面向已有 NoneBot 项目的开发者；仅部署独立牛牛可跳过本节。

  1. 获取源码并 uv sync（PG 用 --extra pg）。
  2. 将 src/foundation 等内核层与所需 src/plugins/* 复制到现有 Bot。
  3. 在 bot.py 中于启动时调用 init_db()、ensure_voices()（参见仓库 bot.py）。
  4. 配置使用 config/pallas.toml + webui.json。

插件列表见 插件索引。多 Bot 共存时注意 matcher 优先级与 block 插件。

社区与支持 ​

与 README 社区区块 保持一致。

开发者 ​

拉牛牛 ​

闲聊 ​

接下来 ​

我想…文档
装决斗、MAA 等安装官方插件
查插件口令插件索引
用控制台改配置Web 控制台
排错FAQ
Docker 部署Docker 部署