Pallas-Bot

外观

4.0 安装验收 Checklist ​

字数
1572 字
阅读时间
8 分钟

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

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

0. 走查前准备 ​

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

路径 A：Docker 全栈新装（推荐新用户） ​

目标：Bot + PostgreSQL + Redis + Ollama + AI，一条 compose 起。

A1. 准备目录与配置 ​

  • 新建部署目录（例 ~/pallas-deploy），不要用中文空名作 Compose 项目目录名
  • 复制 docker-compose.full.yml、（可选）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. 启动 ​

bash
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
  • docker compose ... ps 中 pallasbot、postgres、redis、pallasbot-ai、ollama 为 running/healthy（ollama-init 可 exited 0）
  • docker compose ... logs ollama-init 显示模型 pull 完成（或进行中无持续报错）

A3. 探活 ​

bash
curl -s http://127.0.0.1:8088/pallas/api/health | python3 -m json.tool
curl -s http://127.0.0.1:9099/health | python3 -m json.tool
  • Bot health 返回正常 JSON（非连接拒绝）
  • AI health 中 llm.configuration_ok 为 true（或 provider_status 本地可达）
  • 浏览器打开 http://<宿主机>:8088/pallas/ 能进登录/Setup Wizard

A4. 控制台与配置 ​

  • 首次登录完成 Setup Wizard（改密、协议端提示可稍后）
  • WebUI「智能对话与 AI 服务」显示 AI 在线或探测成功
  • data/pallas_config/webui.json 已生成（卷持久化）

A5. 协议端与群（可选，完整体验） ​

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

A6. 收尾 ​

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

路径 B：本机开发（uv，无 Docker 全栈） ​

目标：开发者本机 Bot + 可选 AI bootstrap。

B1. Bot 本体 ​

bash
cd /path/to/Pallas-Bot
uv sync --dev --extra pg          # 示例默认 postgresql
cp config/pallas.example.toml config/pallas.toml
# 编辑 superusers；本地 PG 或改用 mongodb 段
uv run pallas doctor
uv run pallas                       # 或 uv run nb run
  • pallas doctor 无致命项（config、uv、pyproject 为 ok）
  • http://127.0.0.1:8088/pallas/api/health 正常
  • WebUI 可登录

B2. AI Runtime（同级仓） ​

bash
# Pallas-Bot-AI 与 Pallas-Bot 同级目录
cd /path/to/Pallas-Bot
uv run pallas ai path               # 应打印 ../Pallas-Bot-AI
uv run pallas ai setup              # 或进 AI 仓 ./scripts/ai_bootstrap.sh
  • Redis 可达（脚本可自动 docker compose -f docker-compose.4.0-ci.yml up -d）
  • Ollama 或远端 LLM 配置正确（--remote-only 时跳过 Ollama）
  • curl -s http://127.0.0.1:9099/health 正常
  • Bot pallas.toml 或 WebUI：LLM_CHAT_ENABLED=true，AI_SERVER_HOST/PORT 指向 AI

B3. LLM 联调（可选） ​

bash
cd /path/to/Pallas-Bot
uv run python tools/integration_llm_chat.py --ai-port 9099
  • 脚本输出无致命错误（需已配置 PG/Mongo 与测试用环境变量时按脚本提示）

路径 C：仅 AI Docker（Bot 在宿主机或其他机器） ​

bash
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（compose 默认）；Bot 在 compose 内用服务名 pallasbot
  • 从 Bot 发起到 AI 的任务能收到 callback（WebUI 运行态或群内一条 LLM 回复）

路径 D：3.x 升级 / 沿用 MongoDB（兼容） ​

目标：老数据卷不动，只验证升级后仍能跑。

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

Mongo → PG 迁移

改 db_backend 不会自动迁数据。新装才默认 PG；要迁 PG 需单独迁移方案，不在本清单范围。

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

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

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

常见问题速查 ​

现象先查
compose 项目名为空部署目录名含特殊字符；compose 已设 name:
pallas.toml not a directory挂载路径误建成文件夹
PG pg_isready 失败compose.env 的 PG_* 与 TOML 不一致；或旧 postgres/data 库名冲突
AI health 失败docker compose logs pallasbot-ai；Redis/Ollama 是否 healthy
群无 LLM 回复callback 地址；LLM_CHAT_ENABLED；AI 日志与 Bot 是否同网段
帮助图样式异常勿把整个 resource 挂到 /app/resource（见 DockerDeployment）

更多：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 是否改为固定版本（发布策略）

记录模板（可复制） ​

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