Pallas-Bot Docker 部署
使用 Docker Compose 运行官方镜像，适合生产环境统一版本、隔离依赖。需预先安装 Docker 与 Compose 插件（docker compose version 有输出即可）。
部署前检查清单
| 项 | 说明 |
|---|---|
| Docker | Engine + Compose V2；Linux 可用 curl -fsSL https://get.docker.com | bash |
| 目录 | 单独目录存放 docker-compose.yml 与 pallas-bot/ 数据（勿用中文空名目录作项目名，见排障） |
| 配置 | pallas-bot/config/pallas.toml 必须从示例复制并编辑（文件，非目录） |
| 数据库 | 新装 PostgreSQL（docker-compose.full.yml 或 pallas.example.toml 默认）；3.x 升级 沿用 MongoDB（docker-compose.yml） |
| 端口 | 宿主机映射 8088（或自定义）需在防火墙放行 |
| 备份 | 持久化 pallas-bot/data 与数据库卷 |
步骤 1：安装 Docker 与 Compose
- Windows Docker Desktop（推荐 WSL2 后端）
- Linux 安装
验证：
docker --version
docker compose version如何确认成功：两条命令均正常输出版本号。
Linux Rootless（可选）
dockerd-rootless-setuptool.sh install，见 官方文档。
步骤 2：准备 Compose 与目录
将仓库
docker-compose.yml复制到部署目录（例如~/pallas-deploy/）。创建数据目录并复制主配置：
mkdir -p pallas-bot/config pallas-bot/data
cp /path/to/Pallas-Bot/config/pallas.example.toml pallas-bot/config/pallas.toml编辑
pallas-bot/config/pallas.toml（必做）：superusers、db_backend、数据库段。按需调整 compose 中
volumes：
volumes:
- ./pallas-bot/resource/voices:/app/resource/voices
- ./pallas-bot/config/pallas.toml:/app/config/pallas.toml
- ./pallas-bot/data:/app/data要点：
pallas.toml必须是宿主机上的普通文件；若误建成文件夹，启动会报not a directory（见排障）。- 只挂载
resource/voices，勿把整个resource挂到/app/resource，否则会盖住镜像内styles/default。 data持久化 WebUI、协议端、控制台口令等。
如何确认成功：file pallas-bot/config/pallas.toml 显示为文本文件；pallas-bot/data 目录存在。
步骤 3：选择数据库并启动
全栈（新装推荐：Bot + PostgreSQL + AI + Ollama）
- 复制
docker-compose.full.yml与config/pallas.example.toml（已默认postgresql）。 - 准备目录与
compose.env（PG_*与pallas.toml中[bootstrap.postgres]一致）。 - 启动：
docker compose -f docker-compose.full.yml --env-file ./pallas-bot/config/compose.env up -d- 首次拉取 Ollama 模型需数分钟，可看
docker compose -f docker-compose.full.yml logs -f ollama-init pallasbot-ai。
如何确认成功：curl -s http://127.0.0.1:8088/pallas/api/health 与 curl -s http://127.0.0.1:9099/health 均正常。
有 NVIDIA GPU 时追加 -f docker-compose.full.gpu.yml。
MongoDB（3.x 升级 / 沿用现有数据）
pallas.toml 中 db_backend = "mongodb" 并填写 [bootstrap.mongo]。compose 已为 Bot 注入 MONGO_HOST=mongodb。
docker compose up -dPostgreSQL（仅 Bot，不含 AI；原 compose 分步栈）
pallas.toml设db_backend = "postgresql"并填写[bootstrap.postgres]。- 复制
config/compose.env.example→pallas-bot/config/compose.env，使PG_*与 TOML 一致。 - 启动：
docker compose --env-file ./pallas-bot/config/compose.env --profile postgres up -d如何确认成功：
docker compose ps
docker compose logs -f pallasbot
curl -s http://127.0.0.1:8088/pallas/api/health步骤 4：协议端与 QQ
详见 连接 QQ / 协议端。Docker 下打开：
http://<宿主机IP>:8088/pallas/protocol
NapCat 与 Docker 模式
Linux 下管理页使用 Docker 模式 拉起 NapCat 时，需在 pallasbot 服务挂载 /var/run/docker.sock（compose 内已注释说明，注意安全）。
自管 NapCat 时，WebSocket：ws://<可达Bot的地址>:8088/onebot/v11/ws。
如何确认成功：控制台显示在线 Bot；群内 牛牛帮助 有响应。
步骤 5：访问控制台
| 服务 | 地址 |
|---|---|
| Web 控制台 | http://<宿主机>:8088/pallas/ |
| 协议端管理 | http://<宿主机>:8088/pallas/protocol |
使用启动日志中的口令登录；生产环境勿开 pallas_webui_dev_mode。
日常运维
docker compose logs -f pallasbot备份、防火墙与更新
备份：./pallas-bot/data/、pallas.toml、数据库卷（./mongo/data 或 ./postgres/data）
防火墙：仅对可信 IP 开放 8088；公网请加 HTTPS 与强认证。
更新：
docker compose down
docker compose pull
docker compose up -d
# PostgreSQL profile 时加上 --env-file 与 --profile postgres站点插件若挂载 ./pallas-bot/local/plugins，需在 pallas.toml 设置 extra_plugin_dirs。见 升级与站点定制。
宿主机探活（可选）
Bot 已在容器内运行时：
uv run python tools/scripts/bot_watchdog.py --docker-container pallasbot --no-spawn容器名须与 compose 中 container_name / 服务名一致。详见 标准部署 · 进程守护。
自建镜像与 PALLAS_UV_EXTRAS
官方镜像 pallasbot/pallas-bot:latest 为单进程用途。自行 docker build 时，仓库根目录 .dockerignore 默认不打包 tests/、docs/、.git、data/、local/ 等。
| 场景 | 建议 PALLAS_UV_EXTRAS | 说明 |
|---|---|---|
| 单进程 + MongoDB | perf | 默认 compose 栈 |
| 单进程 + PostgreSQL | perf,pg | Dockerfile 默认值 |
| 多进程分片 | perf,pg,deploy-shard | 需配置 REDIS_URL |
| 4.0 core 仅接话 | perf,pg | 默认不装玩法扩展 |
| 4.0 + 常用玩法 | perf,pg,plugins-game | 决斗 + 谁是卧底；仅用于镜像预装 |
| 4.0 全官方插件 | perf,pg,deploy-full | 决斗 + MAA + 谁是卧底 |
| 4.0 全部官方插件 | perf,pg,deploy-all | 11 个官方插件包 |
示例：
docker build \
--build-arg PALLAS_UV_EXTRAS=perf,pg \
--build-arg PALLAS_BOT_VERSION=3.0.0 \
-t pallasbot:local .国内拉取基础镜像失败见下方排障 · python:3.12-slim。
多进程分片（可选）
十余只及以上牛牛、需 hub + worker 时，参考 docker-compose.shard.example.yml：
- hub 映射 8088；worker 映射 8090、8091…
- hub 与所有 worker 共用同一份
pallas.toml与data/挂载
说明见 多进程分片架构。
排障
project name must not be empty
仓库 compose 已设 name: pallas-bot。若仍报错：docker compose -p pallas-bot up -d，或避免用特殊字符作当前目录名。
pallas.toml ... not a directory
宿主机 pallas-bot/config/pallas.toml 被建成了目录。删除该目录，重新 cp config/pallas.example.toml 为文件后再 up。
help 告警样式路径不存在
勿将空 ./pallas-bot/resource 挂到 /app/resource；仅挂载 voices 子目录。
PG：database "PallasBot" does not exist
数据卷曾用其他 POSTGRES_DB 初始化，与当前 PG_DB 不一致。对齐库名或清空 ./postgres/data 后重建，见 FAQ。
拉取 python:3.12-slim 失败
使用镜像加速或：
docker build --build-arg BASE_IMAGE=docker.m.daocloud.io/library/python:3.12-slim -t pallasbot:local .Compose 服务名与 WebSocket
协议端插件按 pallas.toml 的 HOST/PORT 生成 WS；不会自动使用 compose 服务名 pallasbot。自管 NapCat 且与 Bot 同网络时，可手写 ws://pallasbot:8088/onebot/v11/ws。
接下来
| 我想… | 文档 |
|---|---|
| 非 Docker 标准部署 | 标准部署 |
| 改配置项说明 | 配置要点 |
| 装官方插件 | 安装官方插件 |
| 更多排错 | FAQ |
