NapCatQQ QQ 机器人框架免费可用

hiquant

于 2025-04-10 10:51:23 发布

阅读量555

点赞数 16

文章标签：机器人

本文链接：https://blog.csdn.net/zhangyunchou2015/article/details/147113348

版权

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

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

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

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

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

核心概念：

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

前提条件：

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

步骤 1：寻找并获取 NapCatQQ

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

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

创建工作目录：
```
mkdir ~/napcatqq
cd ~/napcatqq
```
创建 docker-compose.yml 文件：
```
nano docker-compose.yml
```

粘贴并修改 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"] # 可能需要指定启动命令，参考文档

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

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

很多 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