Skip to content

部署指南.md

Latest commit

 

History

History
316 lines (227 loc) · 7.85 KB

部署指南.md

File metadata and controls

316 lines (227 loc) · 7.85 KB
Raw

Phobos Bot 部署指南

部署架构

NapCat (QQ协议层) ←→ WebSocket ←→ Phobos Bot ←→ Discord API
     ↕                         (本机 localhost:8080)
  QQ 服务器

NapCat 和 Phobos Bot 都在同一台 Windows 机器上运行，通过本机 WebSocket 通信。

第一步：准备 QQ 小号

你需要一个 QQ 小号 作为 Bot 账号。

重要提示：

  • ❌ 不要用你的主 QQ 号
  • ✅ 注册一个新 QQ 号（手机号注册即可）
  • ⚠️ 小号需要 养号：注册后每天用手机登录发几条消息，持续 3~5 天再用于 Bot 操作，否则容易触发风控
  • ⚠️ 不要用刚注册的账号直接挂 Bot，新号+高频发消息=秒封

把小号拉进目标群：

用这个小号登录手机 QQ，搜索群号 630590659 并申请入群，通过后 Bot 才能在该群收发消息。

第二步：部署 NapCat（Windows 本地）

NapCat 有两种部署方式。推荐方式 A（Shell 安装器），更稳定；方式 B（Docker）需要 Windows 开启 WSL2 + Docker Desktop。

方式 A：NapCat.Shell 安装器（推荐）

1. 下载 NapCat.Shell

访问 NapCat 官方 GitHub Release 页面： https://github.com/NapNeko/NapCatQQ/releases

下载 NapCat.Shell.zip（Windows 版）。

2. 解压

解压到任意目录，例如 D:\NapCat。

3. 安装 QQ NT 版

NapCat 依赖 QQ NT 版（官方新版 QQ），如果电脑没有，先安装： https://im.qq.com/pcqq/

4. 启动 NapCat

1. 打开 D:\NapCat 目录
2. 双击运行 NapCat.bat（或 NapCat.exe）
3. 会弹出 QQ 登录窗口，使用你的 QQ 小号扫码登录
4. 登录成功后，NapCat 会自动启动 OneBot 服务

5. 验证启动

查看控制台输出，应该看到类似：

[NapCat] WebSocket 服务已启动: ws://0.0.0.0:8080

如果端口冲突，可以在配置文件中修改。

方式 B：Docker 部署（需要 WSL2 + Docker Desktop）

如果你已安装 Docker Desktop（Windows），可以直接用我们项目的编排：

1. 创建 docker-compose.yml：

version: "3.8"

services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
    ports:
      - "8080:8080"     # WebSocket 端口
      - "6099:6099"     # WebUI 管理界面
    volumes:
      - ./napcat_config:/app/napcat/config
      - ./napcat_logs:/app/napcat/logs
    restart: unless-stopped

  phobos-bot:
    build: .
    container_name: phobos-bot
    volumes:
      - ./data:/app/data
    depends_on:
      - napcat
    restart: unless-stopped

2. 启动 NapCat：

docker compose up -d napcat

3. 查看日志获取登录二维码：

docker logs napcat 2>&1 | findstr "二维码"

用手机 QQ 扫码登录。

4. 访问 WebUI（可选）：

打开浏览器访问 http://localhost:6099/webui

首次访问需要 Token，从日志获取：

docker logs napcat 2>&1 | findstr "WebUi"

第三步：配置 OneBot WebSocket

NapCat 启动后会自动生成配置文件，位置取决于部署方式：

方式 配置文件路径
Shell 安装器 D:\NapCat\config\onebot11_{QQ号}.json
Docker ./napcat_config/onebot11_{QQ号}.json

编辑该配置文件，确保内容如下：

{
  "network": {
    "httpServers": [],
    "httpSseServers": [],
    "httpClients": [],
    "websocketServers": [
      {
        "name": "phobos-bot",
        "enable": true,
        "host": "0.0.0.0",
        "port": 8080,
        "reportSelfMessage": false,
        "enableForcePushEvent": true,
        "messagePostFormat": "array",
        "token": ""
      }
    ],
    "websocketClients": [],
    "plugins": []
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false,
  "imageDownloadProxy": ""
}

⚠️ 重点：token 留空（""），因为我们的 config.yaml 中没配 token。如果你要加 token 保护，两边要一致。

修改后重启 NapCat：

  • Shell 安装器：关闭 NapCat 窗口重新双击启动
  • Docker：docker compose restart napcat

验证 WebSocket 已启动：

# Shell 安装器：看控制台输出
# Docker：
docker logs napcat 2>&1 | findstr "WebSocket"

应该看到：

WebSocket服务: 0.0.0.0:8080, : 已启动

第四步：配置 Phobos Bot 的 QQ 连接

编辑 data/config.yaml，更新 QQ 相关配置：

qq:
  bot_qq: 123456789          # ← 改成你的 QQ 小号号码
  group_id: 630590659         # ← 目标 QQ 群号，不需要改
  onebot_ws_url: "ws://127.0.0.1:8080"  # ← NapCat WebSocket 地址

onebot_ws_url 的 8080 端口需要跟你 NapCat 配置中的 port 一致。如果改了 NapCat 端口，这里也要同步改。

第五步：启动 Phobos Bot

确保 NapCat 已经在运行（WebSocket 已监听），然后启动 Bot：

# 从项目根目录
python -m src.main

正常启动日志如下：

{"ts": "2026-06-02T...", "level": "INFO", "module": "__main__", "event": "startup", "message": "Phobos Bot starting..."}

同时会尝试连接 Discord 和 QQ：

  • Discord：连接成功后触发 on_ready 事件
  • QQ：通过 WebSocket 连接 NapCat，成功后接收 QQ 群消息

第六步：验证部署

在两个平台各发一条消息验证：

测试场景 操作 预期结果
QQ → Discord 在 QQ 群 630590659 发送消息 Discord 频道 #phobos-chat 出现 [QQ] 你的昵称: 消息内容
Discord → QQ 在 Discord #phobos-chat 发送消息 QQ 群出现 [Discord] 你的昵称: 消息内容
翻译功能 发送超过 10 个字符的非中/英文消息 另一侧出现原文+译文

常见问题排查

Q1: Bot 启动后 QQ 群消息收不到

NapCat ←→ Phobos Bot 连接状态检查：
1. 确认 NapCat 控制台显示 "WebSocket服务已启动"
2. 确认 config.yaml 的 onebot_ws_url 端口与 NapCat 配置一致
3. 确认 QQ 小号已在目标群中

Q2: Bot 启动报错 "Connection refused"

原因：Phobos Bot 连接 NapCat WebSocket 被拒绝
排查：
1. NapCat 是否已启动？
2. onebot_ws_url 的端口与 NapCat 配置的是否一致？
3. NapCat 防火墙是否放行了该端口？

Q3: QQ 小号消息发送失败

原因：风控或频率限制
排查：
1. 小号是否是新号？新号需要养几天
2. 检查 qq_rate_limit: 1.0 是否过低？尝试改为 2.0（2秒/条）
3. 登录手机 QQ 看看是否被限制

Q4: NapCat 登录失败

1. 确认 QQ 小号账号密码正确
2. 如果提示"版本过低"，更新 QQ NT 版到最新
3. 扫码登录时确认手机 QQ 是同一账号
4. 删除 config 目录下的缓存文件重新登录

Q5: Discord Bot 连接失败

1. 检查 Discord Token 是否有效（可在 Discord Developer Portal 重新生成）
2. 确认 Bot 已被邀请进 C&C Mod Haven 服务器
3. 确认 Bot 有 #phobos-chat 频道的读写权限

QQ 风控注意事项

风险点 建议
新号高频发送 新号前 3 天仅接收不发送，后续逐步提高频率
发送太快 qq_rate_limit: 1.0 已是保守值，如仍封号可改为 2.0
频繁登录 NapCat 启动一次后可保持长期运行，不要频繁重启
消息内容 避免包含明显"机器人"特征的长篇模板回复
养号技巧 每天用手机登录小号，加几个群，发几条正常聊天消息

一键启动脚本（Windows）

创建 start.bat 文件在项目根目录：

@echo off
cd /d %~dp0
echo [Phobos Bot] 启动中...
echo [Phobos Bot] 请确保 NapCat 已在运行
python -m src.main
pause

以后每次启动点这个 bat 就行。