废话少说直接 开干

----简单说明一下 此机器人原理是读取qq信息拿到信息后根据你指定命令然后自己DIY 所有功能----

简单把整个架构写出来免得创建错文件路径

/root/qqbot/
├── docker-compose.yml          # 多容器编排配置（NoneBot + NapCat）
├── .env.prod                   # NoneBot2 的生产环境配置文件（配置 Token、端口等）
└── bot/
    └── src/
        └── plugins/
            └── order/
                └── __init__.py # 核心业务代码（包含连接池、指令分流、白名单拦截）

1.准备一台2-2服务器吧我觉得够用了 因为我本身有站点就用的4-8

安装宝塔或者不安装都行  刚开始为了可视化可以安装宝塔 （安装宝塔就一条命令去宝塔官网看吧）

2.环境准备好了后直接开始安装docker （系统这边以德班为例）

下载好宝塔的可以直接点docker 安装

或者直接ssh

1. 一键安装 Docker 核心服务
curl -fsSL https://get.docker.com | bash

2. 启动并设置开机自启
systemctl enable --now docker

3. 安装 Docker Compose 编排工具
# 下载二进制文件
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 赋予可执行权限
chmod +x /usr/local/bin/docker-compose

# 创建软链接以支持 docker compose 命令
ln -sf /usr/local/bin/docker-compose /usr/libexec/docker/cli-plugins/docker-compose

docker --version
docker compose version
有问题的命令用ai 解决

3.接下来新建目录 -在宿主机新建 /root/qqbot 目录，并在该目录下创建以下两个核心配置文件

docker-compose.yml 
使用 host 网络模式，并注入 LANG=C.UTF-8 保证中文字符与标准 Emoji 的完美兼容

version: '3.8'

services:
  nonebot:
    image: nonebot/nonebot2:latest
    container_name: nonebot
    network_mode: host
    volumes:
      - ./bot:/app
    environment:
      - ENVIRONMENT=prod
      - LANG=C.UTF-8
      - LC_ALL=C.UTF-8
    restart: always

  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    network_mode: host
    volumes:
      - ./napcat_config:/app/config
    environment:
      - ACCOUNT=你的机器人QQ号
    restart: always

3. 创建   .env.prod

配置 NoneBot2 的生产环境参数，开启 Token 安全鉴权。
 

HOST=127.0.0.1
PORT=3001
COMMAND_START=[""] #这个是👉 不需要任何符号，直接发文字就能触发命令可以里面加一个# 然后你发东西
就等#xx 才能触发不加后面就是默认都触发
COMMAND_SEP=[""]
ONEBOT_ACCESS_TOKEN="注意这里的token 到时候和Napcat 客户端web反代token保持一致"

上面这个页面后面会说不用管

启动一键容器 cd /root/qqbot && docker compose up -d

• -d 参数：意思是后台运行（Daemon）。加上它，容器就会在后台默默为你工作，不会因为你关闭 SSH 终端而挂掉。

• 查看运行状态：如果想看容器跑起来没有，可以用 docker compose ps。

• 查看实时日志：如果机器人没反应，想排查问题，可以用 docker compose logs -f 实时盯着它的后台输出。

4.NapCatQQ 侧网络配置

这里由于不能直接访问服务器内网然后不去做反代直接进行和自己电脑打隧道 

cmd 输入

在你的本地电脑上打开一个新的终端窗口，运行这行命令（把 服务器IP 换成你的真实公网 IP）：
ssh -N -L 6099:127.0.0.1:6099 root@服务器IP

然后粘贴密码就行 那个密码不会显示的粘贴直接回车没报错就是进去了

这个终端会静止不动，这是正常的，千万别关掉它！

然后本机输入

进入网络配置选择Websocket 客户端 然后url 填ws://127.0.0.1:3001/onebot/v11/ws
token 就是上面和你说的保持一致 
这个就是向NoneBot 通信和我们到时候后端写的代码进行交互

网络配置 - NapCat WebUIhttp://127.0.0.1:6099/webui/network

5.再创建我们需要机器人功能插件的目录

mkdir -p /root/qqbot/bot/src/plugins/order

# 新建插件目录 mkdir -p /root/qqbot/bot/src/plugins/help

这里随便以我的菜单插件为例

cat > /root/qqbot/bot/src/plugins/help/__init__.py << 'EOF'
# -*- coding: utf-8 -*-
from nonebot import on_message, logger
from nonebot.adapters.onebot.v11 import GroupMessageEvent

# 白名单群（和订单插件保持一致）
ALLOWED_GROUPS = [620863096, 1076775470]

# ========== 帮助文本 ==========
HELP_MAIN = """=== 机器人功能总览 ===
【查询类】
#查询订单  订单/账号状态查询

【工具类】
#帮助      查看功能菜单

使用说明：
• 所有指令以 # 开头
• 输入 #帮助 + 功能名 看详细用法
例：#帮助 订单
========================"""

HELP_ORDER = """=== 订单查询 详细说明 ===
支持两种查询方式，自动识别

1. 按订单号查（纯数字）
#查询订单 10086

2. 按账号查（字母/中文/混合）
#查询订单 test_user

注意：只支持白名单群使用
========================"""

HELP_UNKNOWN = "未找到对应功能，发送 #帮助 查看全部可用指令。"

# ========== 触发逻辑 ==========
help_matcher = on_message(priority=2, block=False)


@help_matcher.handle()
async def handle_help(event: GroupMessageEvent):
    gid = event.group_id
    text = event.get_plaintext().strip()

    if gid not in ALLOWED_GROUPS:
        return

    # 主帮助：#帮助 / #help
    if text in ["#帮助", "#help", "#帮助菜单"]:
        logger.info("[帮助] 触发主菜单")
        await help_matcher.finish(HELP_MAIN)
        return

    # 分项帮助：#帮助 功能名
    if text.startswith("#帮助 "):
        func = text.replace("#帮助", "").strip()
        logger.info(f"[帮助] 查询详情: {func}")
        
        if func in ["订单", "订单查询", "查单"]:
            await help_matcher.finish(HELP_ORDER)
        else:
            await help_matcher.finish(HELP_UNKNOWN)
EOF

然后重新预热扩展机制每次修改都要

cd /root/qqbot && docker compose restart nonebot

然后用自己大号再群里面输入你加的关键词测试

/root/qqbot/bot/src/plugins/
├── order/
│   └── __init__.py      # 本文订单查询逻辑
└── 新功能目录/
    └── __init__.py      # 独立编写新的 on_message 逻辑即可，互不干扰

ps:

原理架构

【用户在QQ群发消息】 
       │
       ▼
【QQ服务器】 -> 投递到你的服务器
       │
       ▼
【NapCatQQ (扮演翻译官角色)】
   * 负责把腾讯的私有协议数据包，翻译成全行业通用的 OneBot v11 标准格式
       │
       ▼  (通过 WebSocket 通道实时推送)
【NoneBot2 (扮演大脑角色)】
   * 接收并解析 OneBot 格式的消息，匹配 "#查询订单" 等指令
       │
       ▼  (毫秒级查询)
【MySQL 数据库】
       │
       ▼  (数据加工组合成漂亮的 Emoji 文本)
【NoneBot2】 -> 沿原路 WebSocket 通道秒回
       │
       ▼
【NapCatQQ】 -> 翻译回 QQ 私有数据
       │
       ▼
【QQ群聊展现 (完成闭环)】

有问题滴滴我 如有侵权请联系