NcatBot 文档

外观

Linux 安装

约 1064 字大约 4 分钟

2025-03-25

检查基本环境

推荐使用 Ubuntu 22.04 LTS 版本.

Python

如果使用 Debian/Ubuntu 并且版本低于 22.04(不包括), 需要手动更新 Python 版本到 3.10 及以上, 推荐更新到 3.12.

安装 NcatBot

项目已经发布到 PYPI, 可以使用 pip 直接下载本项目.

另外, 如果你下载过 github 上的 .zip 压缩文件并解压出来过, 请删掉它们.

在终端直接运行:

pip(稳定版, 推荐)
pip install ncatbot -U -i https://mirrors.aliyun.com/pypi/simple

安装其它基本工具

curl 必须安装, 其它工具的安装可以跳过.

Debian/Ubuntu
sudo apt-get update -y -qq && sudo apt-get -y -qq install curl zip unzip jq curl xvfb screen xauth procps

检查网络环境

NcatBot 需要使用 3000、3001、6099 三个端口, 请确保你的服务器以及系统均已经放通了这三个端口.

3000 的需求并非强制的, 可以忽略, 3001, 6099 分别是默认的 websocket 端口和 WebUI 端口, 必须保证放通. 当然, 你可以通过配置项修改端口.

服务器防火墙

在云服务器提供商, 例如阿里云, 腾讯云提供的安全组中, 确保放通了 3000、3001、6099 三个端口.

如果 NcatBot 和 NapCat 都在同一个服务器上, 一般可以省略这一步.

NcatBot 和 NapCat 的关系.

系统防火墙

Debian/Ubuntu

Debian/Ubuntu 系统通常预装了 UFW, 但默认未启用. 如果未安装，可以通过以下命令安装:

sudo apt update
sudo apt install ufw

查看防火墙状态及规则(需要确保状态为 disabled/inactivated/inactive 或者已经放通所需的端口):

sudo ufw status

禁用防火墙:

sudo ufw disable

放通所需端口:

sudo ufw allow 3000/tcp
sudo ufw allow 3001/tcp
sudo ufw allow 6099/tcp

RPM/CentOS

一般情况下, RPM 系列都内置了 firewall-cmd 工具, 如果确实没有, 可以用以下命令安装:

sudo dnf update
sudo dnf install firewalld

查看防火墙状态(需要确保状态为 disabled/inactivated/inactive 或者放通所需要的端口):

sudo firewall-cmd --state
sudo firewall-cmd --list-all

放通所需端口:

sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=3001/tcp
sudo firewall-cmd --permanent --add-port=6099/tcp
sudo firewall-cmd --reload

执行代码

准备 QQ 号

为了测试, 需要两个 QQ 号：

  • 一个 QQ 号称为 Bot, Bot 一般是小号, 它由 NcatBot 控制.
  • 另一个 QQ 号称为 root, root 一般是大号, 由你自己控制, 拥有管理 Bot 的权限.

NcatBot 相当于一个电脑 QQ 客户端，为了避免重复登录，请在电脑上退出 Bot QQ 的登录。

执行代码

  1. 复制以下代码(记得把代码中的 bt_uin 改成 Bot 的 QQ 号, 把 root 改成你的 QQ 号), 保存到工作目录下 main.py 中.

  2. 在终端中输入 python3 main.py 执行代码, 执行过程中可能会提示需求重启服务(紫色页面), 参考FAQ 操作.

  3. 扫码登录完成并提示 Bot 启动成功 后, 用 root QQ 号向你的 Bot QQ 号 私聊发送一句 测试, 收到 NcatBot 测试成功喵~ 的消息, 说明 NcatBot 已经成功运行起来了!

Python
# ========= 导入必要模块 ==========
from ncatbot.core import BotClient, GroupMessage, PrivateMessage
from ncatbot.utils import get_log

# ========== 创建 BotClient ==========
bot = BotClient()
_log = get_log()

# ========= 注册回调函数 ==========
@bot.group_event()
async def on_group_message(msg: GroupMessage):
    _log.info(msg)
    if msg.raw_message == "测试":
        await msg.reply(text="NcatBot 测试成功喵~")

@bot.private_event()
async def on_private_message(msg: PrivateMessage):
    _log.info(msg)
    if msg.raw_message == "测试":
        await bot.api.post_private_msg(msg.user_id, text="NcatBot 测试成功喵~")

# ========== 启动 BotClient==========
if __name__ == "__main__":
    bot.run(bt_uin="123456") # 这里写 Bot 的 QQ 号

常见问题

安装过程中，出现紫色界面(Package configuration)并卡住

先 Ctrl+C 退出程序, 重启服务器, 再执行 python3 main.py。

更多

查阅 FAQ

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025 NcatBot