这是一个关于 NapCatQQ 的使用教程。

极度重要声明与风险提示：

1. 非官方且高风险： NapCatQQ 是一个基于 QQ Linux 协议的 非官方 QQ 机器人框架。它不是腾讯官方提供的工具。
2. 账号封禁风险： 使用 NapCatQQ 或任何类似非官方工具登录和操作 QQ 账号，严重违反腾讯 QQ 的用户协议，极有可能导致你的 QQ 账号被临时限制功能、强制下线，甚至永久封禁。请务必使用不重要的、专门用于测试的小号进行实验，切勿在你的主号或重要账号上使用！由此产生的一切后果（包括但不限于账号封禁、数据丢失等）均需自行承担。
3. 项目维护与变动： 这类项目依赖于对 QQ 协议的逆向工程，QQ 协议更新可能导致其随时失效。NapCatQQ 本身可能有不同的分支 (fork) 或后继者。你需要关注其 GitHub 仓库（或相关社区）以获取最新信息、兼容版本和维护状态。本教程基于其通用概念，具体细节可能因版本而异。
4. 法律与道德： 请确保你的使用目的合法合规，符合道德规范，不得用于发送垃圾信息、骚扰他人、进行欺诈或任何非法活动。

---

教程：使用 NapCatQQ 搭建 QQ 机器人

目标： 学习如何安装、配置和运行 NapCatQQ，并通过其提供的 API (通常是 HTTP 或 WebSocket) 与 QQ 进行交互，实现基本的机器人功能（如收发消息）。

核心概念：

• 协议模拟： NapCatQQ 通过模拟 Linux QQ 客户端的行为来登录和收发消息。
• API 服务： 它运行后会提供一个 API 接口（通常是 HTTP 和/或 正向/反向 WebSocket），你的机器人程序（客户端）可以通过调用这些 API 来控制 QQ 账号。
• 事件推送： 当 QQ 账号收到消息或其他事件时，NapCatQQ 会将这些事件通过配置好的方式（如反向 WebSocket 或 HTTP POST）推送给你的机器人程序。

前提条件：

1. Linux 环境： NapCatQQ 主要设计运行在 Linux 服务器上。也可以通过 Docker 在 Windows/macOS 上运行，但最终模拟的是 Linux QQ 协议。
2. (推荐) Docker 和 Docker Compose： 使用 Docker 是最方便、隔离性最好的部署方式。需要先安装好 Docker Engine 和 Docker Compose。
3. (备选) Node.js 环境： 如果不使用 Docker，某些版本的 NapCatQQ 可能需要特定的 Node.js 版本（请查阅具体项目的文档）。
4. 一个 QQ 小号： 再次强调，必须使用一个你不担心被封禁的 QQ 小号进行测试。
5. 基础命令行知识： 熟悉 Linux 命令行的基本操作。
6. 基础编程知识： 你需要编写代码（如 Python, JavaScript 等）来调用 NapCatQQ 的 API 并处理事件。本教程将以 Python 为例。

---

步骤 1：寻找并获取 NapCatQQ

1. GitHub 搜索： 由于项目可能存在多个分支或迭代，最佳方式是在 GitHub 上搜索 “NapCatQQ” 或相关关键词。
   • 关注 Star 数量、最近更新时间、Issue 活跃度等，选择一个看起来比较活跃和维护良好的仓库。
   • 仔细阅读该仓库的 README.md 文件！ 这是了解特定版本安装和配置方法的最重要来源。
2. 确定部署方式： 查看文档，确定是推荐使用 Docker 镜像还是需要手动下载源码/二进制文件进行安装。本教程优先介绍 Docker 方式。

---

步骤 2：使用 Docker 部署 NapCatQQ (推荐)

1. 创建工作目录：

   mkdir ~/napcatqq
   cd ~/napcatqq
   

2. 创建 docker-compose.yml 文件：

   nano docker-compose.yml
   

3. 粘贴并修改 Docker Compose 配置：

   version: '3' # 或者根据项目文档推荐的版本
   
   services:
     napcatqq:
       # !!! 关键：替换为你找到的、推荐的 NapCatQQ Docker 镜像名称和标签 !!!
       # 例如：mlikiowa/napcat-docker:latest, richardchien/napcat-minimal:latest 等
       # 请务必从项目文档确认正确的镜像！
       image: <napcatqq_image_name>:<tag>
       container_name: napcatqq_instance
       restart: always
       # 端口映射：将容器内的 API 端口映射到宿主机
       # 默认 HTTP 端口通常是 3000 或其他，WebSocket 端口可能不同
       # 请根据项目文档修改端口号！
       ports:
         - "3000:3000" # 示例：将宿主机的 3000 端口映射到容器的 3000 (HTTP API)
         # - "3001:3001" # 示例：可能用于 WebSocket API
       volumes:
         # 持久化存储配置和数据（如 device.json, token 等），防止容器重启后丢失
         - ./napcat_data:/app/napcat_data # 将宿主机当前目录下的 napcat_data 映射到容器内路径
                                        # 容器内的具体路径请根据项目文档确认！
       environment:
         # 可能的环境变量配置，例如直接设置 QQ 号和密码（但不推荐，优先使用配置文件）
         # - ACCOUNT=12345678
         # - PASSWORD=your_password
         # - NAPCAT_CONFIG_PATH=/app/napcat_data/config.yml # 指定配置文件路径 (如果支持)
       # entrypoint: ["node", "index.js"] # 可能需要指定入口点，参考文档
       # command: ["--config", "/app/napcat_data/config.yml"] # 可能需要指定启动命令，参考文档
   

4. 重要修改点：

   • image: 必须替换为你在步骤 1 中找到的、并且项目文档推荐的 正确 Docker 镜像名称和标签。
   • ports: 冒号后面的端口是容器内部 NapCatQQ 监听的 API 端口（HTTP/WS），冒号前面是你希望在宿主机上访问该服务的端口。请务必查阅文档确认容器内的默认端口。确保宿主机端口未被占用。
   • volumes: 冒号后面的路径是容器内部存放配置和数据（如登录凭证 device.json）的路径，冒号前面是宿主机上的对应目录（这里是 ./napcat_data，会在当前目录下创建）。容器内路径必须根据项目文档确认，以便正确持久化数据。
   • environment, entrypoint, command： 这些根据具体 NapCatQQ 版本的需要进行配置，用于传递账号信息（不推荐明文密码）、指定配置文件、覆盖启动命令等。优先查阅项目文档。

5. 创建配置文件 (如果需要)：

   • 很多 NapCatQQ 版本依赖于一个配置文件（例如 config.yml 或 config.json）来设置 QQ 账号、密码（或扫码登录）、API 密钥、反向事件上报地址等。
   • 在宿主机的 ./napcat_data 目录下（与 volumes 中对应的宿主机路径一致）创建这个配置文件。
   • 创建 ./napcat_data 目录：

     mkdir napcat_data
     cd napcat_data
     

   • 创建并编辑配置文件 (假设是 config.yml)：

     nano config.yml
     

   • 根据项目文档填写配置内容：

     # !!! 这是一个示例，具体配置项和格式请务必参考你所用 NapCatQQ 版本的文档 !!!
     account: 12345678 # 你的 QQ 小号
     # password: your_password # 不推荐！优先扫码登录或使用 token
     login:
       type: qrcode # 或 password, token 等，具体看文档支持
       # token: xxx # 如果支持 token 登录
     
     # API 相关配置
     http:
       enable: true
       host: 0.0.0.0 # 容器内监听地址
       port: 3000   # 容器内监听端口 (需要与 docker-compose.yml 里的内部端口对应)
       # secret: your_api_secret # API 访问密钥 (可选，增加安全性)
       # post_timeout: 60 # 超时时间
     
     ws:
       enable: true
       host: 0.0.0.0
       port: 3001 # 正向 WebSocket 端口
     
     # 反向事件上报配置 (NapCatQQ -> 你的机器人程序)
     reverse:
       enable: true
       # - type: http # 通过 HTTP POST 上报
       #   url: http://your_bot_server_ip:port/event # 你的机器人程序监听事件的地址
       #   secret: your_reverse_secret # 上报密钥 (可选)
       - type: websocket # 通过反向 WebSocket 上报
         url: ws://your_bot_server_ip:port/ws/event # 你的机器人程序监听的 WebSocket 地址
         # secret: your_reverse_secret
         reconnect_interval: 5000 # 重连间隔 (ms)
     
     # 其他配置，如日志级别、设备信息文件路径等
     log_level: info
     device_file: ./device.json # 设备信息文件，用于免扫码登录 (路径相对于容器内工作目录或配置文件)
     
     # ... 可能还有很多其他配置项 ...
     

   • 关键配置：
     • 登录方式 (login.type)： 强烈推荐 qrcode (扫码登录)。首次运行需要扫码，成功后生成的 device.json (或类似文件，名称看文档) 会保存在 napcat_data 目录下，下次启动可尝试使用设备信息快速登录。
     • API 端口 (http.port, ws.port)： 必须与 docker-compose.yml 中 ports: 的后半部分（容器内端口）一致。
     • 反向事件上报 (reverse)： 这是让 NapCatQQ 主动将收到的消息等事件发送给你的机器人程序的关键。你需要配置你的机器人程序监听的地址 (url)。your_bot_server_ip 通常是你宿主机的 IP 地址（或者如果机器人程序也在 Docker 网络中，可能是机器人容器的名称），port 是机器人程序监听的端口。
     • API 密钥 (http.secret, reverse.secret)： 强烈建议设置密钥，增加安全性。

6. 返回上级目录：

   cd .. # 回到 ~/napcatqq 目录
   

7. 启动 NapCatQQ 服务：

   docker compose up -d
   

   Docker 会下载镜像（如果本地没有）并根据配置启动容器。

8. 首次登录 (扫码)：

   • 查看容器日志，等待出现二维码提示或二维码图片（可能以 Base64 形式输出在日志中，需要自行转换）。

   docker compose logs -f napcatqq_instance # 实时查看日志

   *   快速使用手机 QQ 扫描日志中提供的二维码进行登录。
   *   登录成功后，日志会显示相关信息，并且应该会在 `./napcat_data` 目录下生成 `device.json` 或类似文件。按 `Ctrl+C` 停止查看日志（服务仍在后台运行）。
   
   

---

步骤 3：编写机器人程序 (Python 示例)

你的机器人程序需要做两件事：

1. 调用 NapCatQQ 的 API (例如发送消息)。
2. 接收并处理来自 NapCatQQ 的事件推送 (例如处理收到的消息)。

这里提供一个简单的 Python 示例，使用 requests 调用 HTTP API，并使用 Flask 监听 HTTP POST 事件推送（假设你在 config.yml 中配置了反向 HTTP POST）。

import requests
import json
import logging
from flask import Flask, request, abort

# --- 配置 ---
NAPCAT_API_BASE_URL = "http://localhost:3000" # NapCatQQ HTTP API 地址 (如果在同一台机器)
NAPCAT_API_SECRET = "your_api_secret"         # 与 config.yml 中的 http.secret 一致 (如果设置了)
REVERSE_SECRET = "your_reverse_secret"        # 与 config.yml 中的 reverse.secret 一致 (如果设置了)
BOT_LISTEN_HOST = "0.0.0.0"                   # 机器人监听地址
BOT_LISTEN_PORT = 5001                        # 机器人监听端口 (需要 NapCatQQ 能访问到)

# --- 日志配置 ---
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

# --- Flask App 用于接收事件 ---
app = Flask(__name__)

# --- API 调用函数 ---
def call_napcat_api(endpoint, payload=None):
    """调用 NapCatQQ HTTP API"""
    url = f"{NAPCAT_API_BASE_URL}{endpoint}"
    headers = {'Content-Type': 'application/json'}
    if NAPCAT_API_SECRET:
        headers['Authorization'] = f'Bearer {NAPCAT_API_SECRET}' # 或者根据文档使用其他认证方式

    try:
        if payload:
            response = requests.post(url, headers=headers, json=payload, timeout=10)
        else:
            response = requests.get(url, headers=headers, timeout=10)

        response.raise_for_status() # 如果状态码不是 2xx，则抛出异常
        return response.json()
    except requests.exceptions.RequestException as e:
        logging.error(f"调用 API {endpoint} 失败: {e}")
        return None
    except json.JSONDecodeError as e:
        logging.error(f"解析 API {endpoint} 响应失败: {e}, 响应内容: {response.text}")
        return None

# --- 事件处理 ---
@app.route('/event', methods=['POST']) # 路径需要与 config.yml 中的 reverse.url 匹配
def handle_event():
    """处理来自 NapCatQQ 的事件推送"""
    # 验证 Secret (如果配置了)
    if REVERSE_SECRET:
        # NapCatQQ 通常通过 X-Signature 或类似 Header 发送签名，具体看文档
        # 这里假设是简单的 token 验证 (具体验证方式需查阅 NapCatQQ 文档)
        client_secret = request.headers.get('X-Secret') # Header 名称可能不同
        if client_secret != REVERSE_SECRET:
            logging.warning("收到未授权的事件请求")
            abort(403) # Forbidden

    event_data = request.json
    if not event_data:
        logging.warning("收到空的事件数据")
        return "OK" # 告诉 NapCatQQ 已收到

    logging.info(f"收到事件: {json.dumps(event_data, ensure_ascii=False, indent=2)}")

    # --- 在这里编写你的机器人逻辑 ---
    # 例如，处理私聊消息
    if event_data.get("post_type") == "message" and event_data.get("message_type") == "private":
        user_id = event_data.get("user_id")
        message = event_data.get("raw_message")
        sender_info = event_data.get("sender", {})
        sender_nickname = sender_info.get("nickname", "未知用户")

        logging.info(f"收到来自 {sender_nickname}({user_id}) 的私聊消息: {message}")

        # 简单回复
        if "你好" in message:
            reply_message = f"你好呀，{sender_nickname}！"
            send_private_message(user_id, reply_message)

    # 处理群聊消息
    elif event_data.get("post_type") == "message" and event_data.get("message_type") == "group":
        group_id = event_data.get("group_id")
        user_id = event_data.get("user_id")
        message = event_data.get("raw_message")
        sender_info = event_data.get("sender", {})
        sender_nickname = sender_info.get("card") or sender_info.get("nickname", "未知群成员") # 优先用群名片

        logging.info(f"收到群 {group_id} 中 {sender_nickname}({user_id}) 的消息: {message}")

        # 在群里 @ 发送者并回复 (需要 NapCatQQ API 支持 CQ 码或类似格式)
        if "菜单" in message:
            # 注意：CQ 码格式 [CQ:at,qq=USER_ID] 可能需要根据 NapCatQQ 文档调整
            reply_message = f"[CQ:at,qq={user_id}] 机器人菜单：\n1. 功能A\n2. 功能B"
            send_group_message(group_id, reply_message)

    # 需要告诉 NapCatQQ 已成功处理事件 (即使不做任何回复)
    return "OK"

# --- 封装常用 API 调用 ---
def send_private_message(user_id, message):
    """发送私聊消息"""
    endpoint = "/sendPrivateMsg" # 具体 endpoint 请查阅 NapCatQQ API 文档
    payload = {
        "user_id": user_id,
        "message": message
        # 可能还有 as_markdown 等参数
    }
    logging.info(f"尝试发送私聊消息给 {user_id}: {message}")
    result = call_napcat_api(endpoint, payload)
    if result and result.get("status") == "ok": # 假设成功的响应包含 status: ok
        logging.info("发送成功")
        return True
    else:
        logging.error(f"发送失败: {result}")
        return False

def send_group_message(group_id, message):
    """发送群聊消息"""
    endpoint = "/sendGroupMsg" # 具体 endpoint 请查阅 NapCatQQ API 文档
    payload = {
        "group_id": group_id,
        "message": message
    }
    logging.info(f"尝试发送群聊消息到 {group_id}: {message}")
    result = call_napcat_api(endpoint, payload)
    if result and result.get("status") == "ok":
        logging.info("发送成功")
        return True
    else:
        logging.error(f"发送失败: {result}")
        return False

def get_self_info():
    """获取机器人自身信息"""
    endpoint = "/getLoginInfo" # 具体 endpoint 请查阅 NapCatQQ API 文档
    logging.info("尝试获取登录信息...")
    result = call_napcat_api(endpoint)
    if result and result.get("status") == "ok":
        logging.info(f"获取成功: {result.get('data')}")
        return result.get('data')
    else:
        logging.error(f"获取失败: {result}")
        return None

# --- 启动 Flask 服务器 ---
if __name__ == '__main__':
    # 先尝试获取一次登录信息，确认 NapCatQQ 服务正常
    get_self_info()

    # 启动 Flask 服务器来监听事件
    logging.info(f"启动事件监听服务器在 {BOT_LISTEN_HOST}:{BOT_LISTEN_PORT}")
    # 注意：use_reloader=False 在某些情况下可能更稳定，尤其是在 Docker 中
    app.run(host=BOT_LISTEN_HOST, port=BOT_LISTEN_PORT, debug=False, use_reloader=False)

运行 Python 机器人程序：

1. 确保 NapCatQQ 服务正在运行 并且你的 QQ 小号已登录。
2. 安装 Python 依赖：

   pip install requests Flask
   

3. 修改 Python 脚本中的配置： 确保 NAPCAT_API_BASE_URL, NAPCAT_API_SECRET, REVERSE_SECRET, BOT_LISTEN_PORT 与你的 NapCatQQ 配置和网络环境匹配。
   • 如果 Python 脚本和 NapCatQQ 在同一台机器，NAPCAT_API_BASE_URL 通常是 http://localhost:端口号。
   • 确保 NapCatQQ 容器可以访问到你的 Python 脚本监听的地址和端口（BOT_LISTEN_HOST 和 BOT_LISTEN_PORT）。如果都在本机，通常没问题。如果在不同 Docker 容器或网络中，需要配置网络。
   • 确保你在 NapCatQQ 的 config.yml 中配置的反向事件上报 URL 指向 http://<你的机器IP>:<BOT_LISTEN_PORT>/event。
4. 运行脚本：

   python your_bot_script.py
   

5. 测试：
   • 用另一个 QQ 号给你的机器人小号发送私聊消息 “你好”。
   • 在你的小号加入的群里发送 “菜单”。
   • 观察 Python 脚本的日志输出和 QQ 上的回复。

---

步骤 4：管理和排错

• 查看 NapCatQQ 日志： docker compose logs -f napcatqq_instance 是最重要的排错工具。查看是否有登录错误、API 调用失败、事件推送失败等信息。
• 配置文件： 仔细检查 docker-compose.yml 和 NapCatQQ 的 config.yml（或其他配置文件）是否正确，特别是端口、密钥、路径、URL 等。
• 网络问题：
  • 确保 NapCatQQ 容器能够访问你的机器人脚本监听的事件上报地址。
  • 确保你的机器人脚本能够访问 NapCatQQ 的 API 地址。
  • 检查服务器防火墙是否允许相应的端口通信。
• 版本兼容性： 确保你的 NapCatQQ 版本与你使用的 QQ 协议版本（或者说 QQ 客户端版本，如果它是基于特定客户端的话）兼容。QQ 更新后可能需要等待 NapCatQQ 更新。
• 登录问题：
  • 首次登录务必快速扫码。
  • 确保 device.json（或类似文件）被正确持久化存储，并且 NapCatQQ 能够读取它。
  • 如果遇到滑块验证码或设备锁，可能需要按照项目文档的指引进行处理（有时需要手动处理或项目本身有特殊支持）。
• 账号冻结/封禁： 如果账号被限制登录或封禁，这是使用此类工具的最大风险，通常无法轻易解封。停止使用，并考虑更换小号。

---

总结与后续

本教程提供了一个使用 Docker 部署 NapCatQQ 并通过 Python 进行基本交互的框架。

• 关键在于阅读文档： 你选择的 NapCatQQ 版本的 官方 README.md 和文档 是最权威的信息来源，本教程仅为通用指引。API endpoint、配置项、认证方式、支持的功能都以官方文档为准。
• 从小功能开始： 先实现简单的消息收发，再逐步探索更复杂的功能（如获取好友/群列表、处理图片、文件、管理群成员等）。
• 再次强调风险： 时刻牢记使用非官方工具可能带来的账号风险。

祝你在探索 QQ 机器人的过程中学习愉快，但请务必谨慎行事！