前言

这里记录一下绍如何在Linux服务器（Ubuntu/Debian）上部署AstrBot机器人框架，同时配置Napcat QQ机器人作为消息通道，并添加必要的辅助功能（如Swap内存优化、GitHub操作、邮件发送、网页截图等）。

一、基础环境配置

1.1 更新系统包

1
sudo apt update

1.2 安装Python环境

1
2
3
4
5
# 安装Python3基础包
sudo apt install python-is-python3

# 安装完整的Python3和虚拟环境工具
sudo apt install python3-full python3-venv

二、部署AstrBot

对于想快速开始的（推荐）

1
2
3
uv tool install astrbot
astrbot init # Only execute this command for the first time to initialize the environment
astrbot

否则也可以手动安装项目（不推荐）

2.1 克隆项目并创建虚拟环境

1
2
# 克隆AstrBot仓库
git clone https://github.com/AstrBotDevs/AstrBot && cd AstrBot

2.2 安装依赖并启动

使用uv(推荐):

1
2
3
uv sync
uv run main.py
screen -dmS astr bash -c "uv run --no-sync main.py"

不使用uv:

1
2
3
4
5
6
7
8
9
10
11
12
13
# 创建Python虚拟环境
python3 -m venv astr

# 激活虚拟环境
source astr/bin/activate

# 中国大陆使用清华镜像源加速安装
python -m pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

# 启动AstrBot
python main.py

screen -dmS astr bash -c "python main.py"

注意：首次启动会生成配置文件，按提示完成基础配置后即可正常运行。

覆盖安装：

1
2
3
cd AstrBot
git fetch --depth=1 origin $(git ls-remote --tags --sort='-v:refname' https://github.com/AstrBotDevs/AstrBot.git | head -n1 | awk -F/ '{print $3}')
git reset --hard FETCH_HEAD

命令解释：

  • git fetch --depth=1 origin <tag>：获取最新标签的代码，但不合并
  • git reset --hard FETCH_HEAD：强制将当前目录的文件覆盖成刚获取的版本
  • 这种方式会保留目录下多余的文件（如配置文件、数据文件等），只更新被版本控制跟踪的文件

三、优化服务器内存（Swap配置）

对于内存较小的服务器，建议配置Swap分区避免因内存不足导致服务崩溃。

3.1 创建Swap文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 创建2GB的swap文件（根据磁盘空间调整大小）
sudo fallocate -l 2G /swapfile

# 如果fallocate不支持，使用dd命令替代
# sudo dd if=/dev/zero of=/swapfile bs=1M count=2048

# 设置正确权限
sudo chmod 600 /swapfile

# 格式化为swap
sudo mkswap /swapfile

# 立即启用
sudo swapon /swapfile

# 验证是否生效
free -h

3.2 优化Swap使用策略

1
sudo vi /etc/sysctl.conf

添加以下配置：

1
vm.swappiness=60

说明：swappiness值（0-100）控制系统使用Swap的积极程度，60是一个相对平衡的配置。

四、部署Napcat QQ机器人

4.1 安装Napcat

Napcat提供了无Root权限的安装方式，以下是在安装完成后的启动和管理方法：

如果是Oracle Linux

1
2
3
4
# 安装 Fedora 官方 EPEL 源
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
# 更新缓存
sudo dnf makecache
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 安装NapCat脚本
curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& sudo bash napcat.sh

# 启动Napcat（前台运行）
xvfb-run -a /root/Napcat/opt/QQ/qq --no-sandbox

# 后台运行（使用screen）
# 启动会话
screen -dmS napcat bash -c "xvfb-run -a /root/Napcat/opt/QQ/qq --no-sandbox"

# 指定QQ号启动
screen -dmS napcat bash -c "xvfb-run -a /root/Napcat/opt/QQ/qq --no-sandbox -q QQ号码"

# 附加到会话查看
screen -r napcat
# 按 Ctrl+A 然后按 D 分离会话

# 停止会话
screen -S napcat -X quit

假设你的服务器有充足的资源，并且想要服务随系统自动启动、崩溃后能自动复活，那么可以使用pm2(基础占用 40M ~ 60M)。

4.2 Napcat相关信息

  • 插件位置：/root/Napcat/opt/QQ/resources/app/app_launcher/napcat
  • WebUI Token：查看 /root/Napcat/opt/QQ/resources/app/app_launcher/napcat/config/webui.json 文件获取
  • CLI工具：直接运行 napcat 命令启动交互式界面

4.3 安装代理支持（如需使用Socks代理）

1
2
pip install httpx[socks]
pip install httpcore[socks]

五、集成GitHub操作

5.1 配置GitHub Personal Access Token

为了让机器人能够操作GitHub，需要生成Personal Access Token（PAT）：

  1. 访问 GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. 生成新的token，选择需要的权限（如repo、workflow等）
  3. 将token配置到AstrBot的配置文件中

安全提示：请妥善保管您的Token，不要分享给他人或在公开场合泄露。示例中的Token已脱敏处理。

六、配置邮件发送功能

6.1 安装邮件客户端

1
2
sudo apt install s-nail -y
apt install libnss3-tools

6.2 配置邮箱

创建或编辑配置文件 /etc/s-nail.rc：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 启用v15兼容模式
set v15-compat

# 发送邮件配置
set mta=smtps://your_email@qq.com:your_authorization_code@smtp.qq.com:465
set smtp-auth=LOGIN
set from=your_email@qq.com

# 接收邮件配置
set folder=imaps://your_email@qq.com:your_authorization_code@imap.qq.com:993
set inbox=+INBOX

# SSL/TLS 设置
set tls-verify=ignore
set verbose

也可以创建用户级配置文件 ~/.mailrc，内容相同。

6.3 发送测试邮件

1
2
3
4
5
6
7
8
9
10
echo "这是一封测试邮件" | \
s-nail -v -S v15-compat \
       -S mta=smtps://your_email%40qq.com:your_authorization_code@smtp.qq.com:465 \
       -S smtp-auth=LOGIN \
       -S smtp-auth-user=your_email@qq.com \
       -S smtp-auth-password=your_authorization_code \
       -S from=your_email@qq.com \
       -S tls-verify=ignore \
       -s "测试主题" \
       recipient@example.com

注意：邮箱授权码需要在QQ邮箱设置中获取，不是QQ密码。示例中的授权码已脱敏。

6.4 解决格式问题

如果在编辑配置文件时遇到 ^M 字符（Windows格式换行符），请使用Vim转换：

1
vim /etc/s-nail.rc

在Vim中执行：

1
2
:set fileformat=unix
:wq

七、配置网页截图功能（Puppeteer）

为了让机器人能够访问网页并截图，需要安装Puppeteer。

7.1 安装Puppeteer

1
2
3
4
5
6
7
8
# 全局安装puppeteer
pnpm install puppeteer -g

# 在项目目录安装
pnpm add puppeteer

# 安装Chrome浏览器
pnpm dlx puppeteer browsers install chrome

7.2 测试Puppeteer

创建测试文件 puppeteer-test.js：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
// 引入 puppeteer 库
import puppeteer from 'puppeteer';

(async () => {
  let browser;
  try {
    console.log('正在启动浏览器...');
    // 启动浏览器实例（添加no-sandbox参数解决权限问题）
    browser = await puppeteer.launch({
      args: ['--no-sandbox', '--disable-setuid-sandbox']
    });
    console.log('浏览器已启动。');

    // 打开新页面
    const page = await browser.newPage();
    console.log('已创建新页面。');

    // 导航到example.com
    console.log('正在导航到 https://example.com ...');
    await page.goto('https://example.com', {
      waitUntil: 'networkidle2',
    });
    console.log('页面导航完成。');

    // 获取页面标题
    const pageTitle = await page.title();
    console.log(`页面标题是: ${pageTitle}`);

    // 截图保存
    await page.screenshot({ path: 'example.png', fullPage: false });
    console.log('页面截图已保存为 example.png');

    // 验证
    if (pageTitle === 'Example Domain') {
      console.log('✅ 验证成功！Puppeteer 工作正常。');
    } else {
      console.log('❌ 验证失败：页面标题不匹配。');
    }

  } catch (error) {
    console.error('❌ 运行过程中发生错误:', error);
  } finally {
    if (browser) {
      await browser.close();
      console.log('浏览器已关闭。');
    }
  }
})();

7.3 解决沙箱问题

如果在运行Puppeteer时遇到沙箱相关的错误，添加 --no-sandbox 参数：

1
2
3
const browser = await puppeteer.launch({
  args: ['--no-sandbox', '--disable-setuid-sandbox']
});

参考官方文档：https://pptr.dev/troubleshooting

八、使用PM2管理AstrBot进程

8.1 创建日志目录

1
mkdir -p logs

8.2 配置PM2启动文件

创建 ecosystem.config.js：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
module.exports = {
  apps: [{
    name: 'astrbot',
    script: 'main.py',
    interpreter: './astr/bin/python',
    cwd: '/path/to/AstrBot',
    out_file: './logs/out.log',
    error_file: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss',
    env: {
      NODE_ENV: 'production'
    }
  }]
}

8.3 启动并保存PM2配置

1
2
3
4
5
6
# 启动AstrBot
pm2 start ecosystem.config.js

# 保存PM2配置（开机自启）
pm2 save
pm2 startup

说些什么吧！

giscus