4.0 安装验收 Checklist

July 26, 2026 · View on GitHub

维护者从 0 安装时按本清单走查。每条打勾前记录 日期 / 环境（OS、GPU、Docker 版本）；失败项记录现象与日志路径。

相关文档：Docker 部署 · AI Runtime · 运维入口 · 升级 · FAQ

0. 走查前准备

项要求
机器干净目录；建议 ≥ 8GB 内存；全栈 + Ollama 建议 ≥ 16GB 或接受 CPU 推理较慢
Dockerdocker --version、docker compose version 有输出（Docker 路径）
网络可拉取 pallasbot/* 镜像与 Ollama 模型（首次约 15–40 分钟）
端口宿主机 8088（Bot）未被占用；使用媒体 Runtime 时另留 9099
仓库仅 compose 时可不克隆；本机开发须克隆 Pallas-Bot；使用媒体 Runtime 时 AI 本机路径须同级 Pallas-Bot-AI

路径 A：Docker 全栈新装

目标：Bot + PostgreSQL + Redis；按需在同一 compose 增加 Ollama 与 AI 媒体 Runtime。

A1. 准备目录与配置

  • 新建部署目录（例 ~/pallas-deploy）；Compose 项目目录名勿含中文或空格
  • 按 Docker 部署 · 全栈 将文档中的全栈 YAML 另存为 docker-compose.full.yml（GPU 另存 docker-compose.full.gpu.yml）
  • mkdir -p pallas-bot/config pallas-bot/data pallas-bot-ai/logs
  • 复制 config/pallas.example.toml → pallas-bot/config/pallas.toml
  • 编辑 pallas.toml：superusers；db_backend = "postgresql" 与 [bootstrap.postgres] 一致
  • 复制 config/compose.env.example → pallas-bot/config/compose.env；PG_* 与 TOML postgres 段一致

A2. 启动

cd ~/pallas-deploy
docker compose -f docker-compose.full.yml --env-file ./pallas-bot/config/compose.env up -d
# NVIDIA GPU: 追加 -f docker-compose.full.gpu.yml
# 可选预拉 Ollama 模型: 追加 --profile pull-models（默认不预拉，改在 WebUI 拉）
  • docker compose ... ps：pallasbot、postgres、redis 为 running/healthy；启用完整 AI 栈时再核对 pallasbot-ai、ollama（默认无 ollama-init；仅加了 --profile pull-models 时可为 exited 0）
  • 唱歌/TTS 等媒体能力才需要 pallasbot/pallas-bot-ai；需要完整媒体栈时，在 compose.env 设 PALLAS_AI_IMAGE=pallasbot/pallas-bot-ai:latest 并叠加 GPU compose

失败分支：某服务非 healthy → docker compose logs <服务名>；PG 见 Docker 部署 · PG 排障。

A3. 探活

curl -s http://127.0.0.1:8088/pallas/api/health | python3 -m json.tool
  • Bot health 返回 JSON（非连接拒绝）
  • 浏览器 http://<宿主机>:8088/pallas/ 可进登录 / Setup Wizard

A4. 控制台与配置

  • 首次登录完成 Setup Wizard（改密、协议端可稍后）
  • WebUI「AI 配置 → 接入」配置 Provider、模型与密钥，并通过连通性测试
  • data/pallas_config/webui.json 已生成（卷持久化）

A5. 协议端与群（可选）

  • http://<宿主机>:8088/pallas/protocol 可创建 / 管理协议端实例
  • QQ 连上后群内 牛牛帮助 有响应
  • 打开 LLM_CHAT_ENABLED 后，@牛牛 或智能对话有一条成功回复（首次可能较慢）

A6. 收尾

  • docker compose ... down 后 up -d 再探活；pallas-bot/data、postgres/data 数据仍在
  • 记录总耗时与卡点（模型下载、health 超时等）

路径 B：本机开发（uv）

目标：本机 Bot；按需接入 LLM Provider 或 AI 媒体 Runtime。

B1. Bot 本体

cd /path/to/Pallas-Bot
uv sync --dev
cp config/pallas.example.toml config/pallas.toml
# 编辑 superusers；本地 PG 或 mongodb 段
uv run pallas doctor
uv run pallas
  • pallas doctor 无致命项
  • http://127.0.0.1:8088/pallas/api/health 正常
  • WebUI 可登录

B2. LLM Provider

# 启动 Bot 后，在 http://127.0.0.1:8088/pallas/ 打开 AI 配置 → 接入
  • Provider、模型与密钥已保存并测试成功
  • LLM_CHAT_ENABLED=true
  • @牛牛 有一条成功回复

B3. AI Runtime（仅媒体 / RWKV）

cd /path/to/Pallas-Bot
uv run pallas ai setup --with-media
  • curl -s http://127.0.0.1:9099/health 正常
  • AI_SERVER_HOST / AI_SERVER_PORT 指向 AI Runtime
  • 媒体 worker 就绪；需要遗留 RWKV 时 /api/chat 可用

B4. LLM 联调（可选）

cd /path/to/Pallas-Bot
uv run python tools/integration_llm_chat.py
  • 脚本无致命错误（按脚本提示配置 PG/Mongo 与测试环境变量）

路径 C：仅 AI Docker（媒体 / RWKV，Bot 在宿主机或其他机器）

cd /path/to/Pallas-Bot-AI
docker compose -f docker-compose.llm.yml up -d
# GPU: 追加 -f docker-compose.llm.gpu.yml
  • 9099/health 正常
  • Bot 侧 CALLBACK_HOST：同机 Docker 用 host.docker.internal；Bot 在 compose 内用服务名 pallasbot
  • 媒体或 RWKV 任务可收到 callback

路径 D：3.x 升级 / 沿用 MongoDB

目标：老数据卷不动，验证升级后仍可运行。

  • 升级前备份：pallas-bot/data/、mongo/data/、pallas.toml
  • pallas.toml 保持 db_backend = "mongodb" + [bootstrap.mongo]
  • 使用根目录 docker-compose.yml 并加 --profile mongo；勿换 PG 卷
  • docker compose --env-file ./pallas-bot/config/compose.env --profile mongo up -d 后 Bot health 正常
  • 历史群数据、语料、配置仍在（抽一条已知数据核对）
  • （可选）uv run python tools/migrate_env_to_pallas.py 仅从旧 .env 迁移一次

注意：改 db_backend 不会自动迁数据。新装默认 PG；迁 PG 须单独迁移方案，不在本清单范围。

路径 E：仅 Bot + Mongo/PG（不含 AI）

适用：先跑通本体与 WebUI，暂不接智能对话。

栈命令
PG（默认）docker compose --env-file ./pallas-bot/config/compose.env up -d
Mongo（升级栈）docker compose --env-file ./pallas-bot/config/compose.env --profile mongo up -d
  • health + WebUI + 帮助菜单
  • 不接 AI 时群内无 LLM 属预期

常见问题速查

现象先查
compose 项目名为空部署目录名含特殊字符；compose 已设 name:
pallas.toml not a directory挂载路径误建成文件夹
PG pg_isready 失败compose.env 的 PG_* 与 TOML 不一致；或旧 postgres/data 库名冲突
Provider 测试失败 / 群无 LLM 回复WebUI「AI 配置 → 接入」的 Base URL、密钥、模型；确认 LLM_CHAT_ENABLED
媒体 Runtime health 失败docker compose logs pallasbot-ai；Redis/Ollama 是否 healthy
媒体任务无结果AI_SERVER_*、callback 地址、AI 与 Bot 网络
帮助图样式异常勿将整个 resource 挂到 /app/resource（见 Docker 部署）

更多：FAQ · 排障 · LLM 与 AI 运维

GA 发布前维护者附加项

  • 三仓 dev-v2 CI 全绿
  • 本清单路径 A + B 至少在一种环境完整走通并记录
  • CHANGELOG / 4.0 迁移指南与 compose 默认一致
  • pallas-core wheel 构建与 PyPI 发布（.github/workflows/publish-pypi-core.yml，随 v* tag）
  • 镜像 tag 与 compose 中 latest 是否改为固定版本（发布策略）

记录模板

日期：
环境：OS / RAM / GPU / Docker 版本
路径：（A/B/C/D/E）
结果：通过 / 部分通过
失败项：
日志：
备注：