Linux 环境下的 Nonebot2 QQ机器人搭建指南#

本文是 Nonebot2 教程系列的 Linux 篇，主要介绍如何在 Linux 系统上配置和部署 QQ 机器人。

一、框架安装#

1. 安装 NapCat#

推荐使用 Docker 方式安装 NapCat，具体步骤请参考官方文档。安装完成后，按照框架接入指南完成配置。

2. 环境迁移准备#

如果你已在本地环境调试好机器人，可以通过复制以下文件到服务器来快速部署：

src 文件夹
pyproject.toml
poetry.lock

二、Python 环境配置#

在 Ubuntu 系统上安装 Python 3.10.11 的详细步骤：

1. 系统更新#

先更新一下包管理器的包列表，确保系统是最新的：

1
sudo apt update

2. 安装必要依赖#

安装编译 Python 需要的一些工具和库：

1
sudo apt install -y software-properties-common
2
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
3
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
4
libffi-dev liblzma-dev python3-openssl git

3. 添加 Python PPA#

使用 Python 官方的 PPA 仓库来安装特定版本的 Python：

1
sudo add-apt-repository ppa:deadsnakes/ppa
2
sudo apt update

4. 安装 Python 3.10#

安装 Python 3.10.12：

1
sudo apt install python3.10

5. 配置 pip#

安装 Python 包管理工具 pip：

1
sudo apt install python3.10-distutils
2
wget https://bootstrap.pypa.io/get-pip.py
3
sudo python3.10 get-pip.py

6. 验证安装#

最后，检查 Python 版本，确保安装成功：

1
python3.10 --version

💡 如果显示 Python 3.10.11，则表示安装成功。

三、项目依赖管理#

完成 Python 安装后，需要创建项目结构并安装依赖：

创建 Nonebot 项目目录
复制之前准备的文件到相应位置
创建并激活虚拟环境
使用 Poetry 安装依赖

⚠️ 如果在安装依赖时遇到超时问题，可以考虑配置代理。

四、配置网络代理#

1. 安装和配置 Clash#

推荐参考详细教程配置 Clash 代理。配置完成后，可以使用以下命令控制 Clash：

1
systemctl start clash # 启动代理
2
systemctl stop clash # 停止代理

2. 代理相关命令#

1
查看当前代理设置
2
echo $http_proxy
3
echo $https_proxy
4

5
临时关闭代理
6
unset http_proxy https_proxy all_proxy

3. SSL 错误解决#

如果遇到 SSL 错误：error:0a000126:ssl routines::unexpected eof while reading，可以参考这篇文章解决。

常见问题与解决方案#

Poetry 安装超时
- 配置国内镜像源
- 使用代理
- 增加超时时间
依赖安装失败
- 检查 Python 版本兼容性
- 确认系统依赖是否完整
- 查看错误日志定位具体问题
网络连接问题
- 验证代理配置
- 检查防火墙设置
- 确认端口是否开放

🔍 遇到问题时，建议先查看 Nonebot2 的官方文档和问题解答。

Chasing the Dawn

Nonebot2——QQ机器人搭建教程-Linux篇