ARTICLE DETAIL

建站实战干货

来自一线的建站与推广经验沉淀，每一条都经过真实交付验证。

首页 / 资讯中心 / 正文

CentOS 7 部署 Miao-Yunzai QQ 机器人：从 Node.js 环境到扫码登录全攻略

2026/8/6 7:10:25 拓冰建站 浏览量
CentOS 7 部署 Miao-Yunzai QQ 机器人：从 Node.js 环境到扫码登录全攻略

1. 项目背景与核心价值

最近在折腾一个基于QQ的机器人，想实现一些自动回复、群管或者娱乐功能，很多朋友都推荐了 Yunzai-Bot 这个框架。不过，原版的 Yunzai 已经停止维护了，社区里活跃的是它的一个分支——喵版 Yunzai，也就是 Miao-Yunzai。这个版本在原版基础上做了大量优化和功能更新，插件生态也更丰富，是目前搭建这类机器人的首选。

但说实话，对于很多刚接触 Linux 服务器或者 Node.js 生态的朋友来说，在 CentOS 这类服务器系统上从头部署 Miao-Yunzai，可能会遇到一堆“拦路虎”：Node.js 版本不对、依赖装不上、Redis 没启动、QQ 扫码登录失败……网上的教程要么太老，要么步骤跳跃，照着做总卡在某个莫名其妙的报错上。我自己在 CentOS 7.6 和 7.9 上反复折腾了好几遍，踩遍了几乎所有能踩的坑，才终于把流程跑通。

所以，这篇内容就是一份超详细的、面向新手的、在 CentOS 系统上安装 Miao-Yunzai 的实战指南。我会假设你有一台干净的 CentOS 服务器（物理机或虚拟机均可），从零开始，带你一步步完成所有环境准备、软件安装、配置和启动。不止告诉你“怎么做”，更会解释“为什么这么做”，以及遇到各种报错时该如何排查和解决。目标很简单：让你能一次成功，把机器人跑起来。

2. 环境准备：打造稳固的基石

在安装任何应用之前，打好基础环境是关键。对于 Miao-Yunzai 来说，它依赖于 Node.js 运行时、Redis 数据库以及 Git 等工具。在 CentOS 上，我们需要先处理好系统更新、基础工具和关键的软件源。

2.1 系统更新与基础工具安装

首先，通过 SSH 连接到你的 CentOS 服务器。建议使用非 root 用户操作，但为了教程清晰，这里以 root 用户为例（生产环境请自行配置 sudo 权限）。

第一步永远是更新系统，并安装一些后续步骤必需的编译工具和基础软件包。

# 更新系统软件包到最新 yum update -y # 安装基础开发工具组、Git、Wget 等 yum groupinstall -y "Development Tools" yum install -y git wget curl vim openssl-devel

这里解释一下几个包的作用：

  • Development Tools：这是一个软件包组，包含了gcc,gcc-c++,make等编译工具。后续从源码编译 Node.js 或者安装某些 Node.js 原生模块（node-gyp）时是必需的。
  • git：用于从 GitHub 克隆 Miao-Yunzai 的源代码仓库。
  • wget和curl：命令行下载工具，用于获取 Node.js 安装包等资源。
  • vim：一个文本编辑器，用于修改配置文件。如果你习惯nano，也可以安装nano。
  • openssl-devel：OpenSSL 的开发库，Node.js 的某些加密相关功能需要它。

执行完上述命令后，基础环境就准备好了。

2.2 Node.js 安装：版本选择与避坑指南

Miao-Yunzai 对 Node.js 版本有明确要求，通常需要 Node.js 16 或更高版本（推荐 18+）。CentOS 默认的 yum 源里的 Node.js 版本通常很老（比如 v6.x），完全无法使用。因此，我们必须从官方渠道安装指定版本。

为什么不推荐用yum install nodejs？因为 CentOS 官方仓库和 EPEL 仓库中的nodejs包版本极低，无法满足现代前端和 Node.js 应用的需求，强行安装会导致后续npm install时出现大量语法错误和兼容性问题。

方案选择：NodeSource 仓库最稳定、最推荐的方法是通过 NodeSource 提供的仓库来安装。NodeSource 维护了各个主要版本的 Node.js 仓库，安装方便且更新及时。

  1. 清理可能存在的旧版 Node.js（如果是新系统可跳过）：

    yum remove -y nodejs npm

  2. 添加 NodeSource 仓库并安装 Node.js 18 LTS（长期支持版，稳定）：

    # 下载并执行 NodeSource 的安装脚本，添加 Node.js 18.x 的仓库 curl -fsSL https://rpm.nodesource.com/setup_18.x | bash - # 从新添加的仓库安装 Node.js 和 npm yum install -y nodejs

    注意：curl -fsSL中的-f表示失败时静默退出，-s静默模式，-S在错误时显示错误信息，-L跟随重定向。这是一个安全的做法。脚本执行过程中会配置 yum 仓库。

  3. 验证安装：

    node -v # 应该输出 v18.x.x 类似的版本号 npm -v # 应该输出对应的 npm 版本号，如 9.x.x 或 10.x.x

如果遇到网络问题无法从 nodesource.com 下载？有时国内服务器访问国外源速度慢或失败。可以尝试使用国内镜像，但需注意镜像的更新可能滞后。一个替代方案是手动下载二进制包：

# 以 Node.js 18.20.0 为例，从国内镜像站下载 wget https://registry.npmmirror.com/-/binary/node/v18.20.0/node-v18.20.0-linux-x64.tar.xz # 解压到 /usr/local 目录 tar -xJf node-v18.20.0-linux-x64.tar.xz -C /usr/local/ # 创建软链接，使 node 和 npm 命令全局可用 ln -sf /usr/local/node-v18.20.0-linux-x64/bin/node /usr/local/bin/node ln -sf /usr/local/node-v18.20.0-linux-x64/bin/npm /usr/local/bin/npm ln -sf /usr/local/node-v18.20.0-linux-x64/bin/npx /usr/local/bin/npx # 验证 node -v

2.3 Redis 安装与基础配置

Miao-Yunzai 使用 Redis 作为缓存和会话存储数据库，这是必须的组件。CentOS 7 默认的 yum 源里的 Redis 版本是 3.2.x，虽然能用，但版本较老。我们可以选择安装默认版本，或者通过 Remi 仓库安装较新的稳定版。

方案一：安装默认仓库的 Redis（简单）

yum install -y redis systemctl start redis systemctl enable redis

方案二：通过 Remi 仓库安装较新版本（如 6.x/7.x）

  1. 安装 EPEL 仓库和 Remi 仓库：
    yum install -y epel-release yum install -y http://rpms.remirepo.net/enterprise/remi-release-7.rpm
  2. 启用 Remi 仓库中的 Redis 6 模块并安装：
    yum-config-manager --enable remi yum install -y redis6 --enablerepo=remi

    注意：yum-config-manager命令可能包含在yum-utils包中，如果提示命令不存在，请先yum install -y yum-utils。

  3. 启动并设置开机自启：
    systemctl start redis6 systemctl enable redis6
    此时 Redis 的服务名可能是redis6而不是redis，配置文件路径也可能在/etc/redis6/redis.conf。

验证 Redis 是否正常运行：

# 连接到 Redis 命令行，执行 ping 命令 redis-cli ping # 如果返回 PONG，说明 Redis 服务运行正常。

一个关键的配置检查：默认情况下，Redis 只监听127.0.0.1（本地回环地址），这对于 Miao-Yunzai 在同一台机器上访问是没问题的。但如果你后续需要远程管理或者有其他特殊需求，可能需要修改绑定地址。检查配置文件/etc/redis.conf（或/etc/redis6/redis.conf）中的bind行：

vim /etc/redis.conf # 找到 `bind 127.0.0.1` 这一行，确保它存在且没有被注释（前面没有#）。 # 这意味着 Redis 只允许本机连接，安全性更高。对于 Miao-Yunzai 来说，保持默认即可。

2.4 Chromium 浏览器安装（可选但强烈推荐）

Miao-Yunzai 的某些插件（特别是涉及网页截图、OCR识别等功能的插件）依赖于一个无头浏览器环境来渲染页面。最常见的就是 Puppeteer，它默认会尝试下载 Chromium。但在服务器环境，特别是国内网络下，这个下载过程极易失败，导致插件报错。

为了避免后续麻烦，我们提前在系统层面安装 Chromium 或 Chrome。

# 添加 Google Chrome 仓库（这里以安装 Chrome 稳定版为例，它包含 Chromium 核心） wget https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm # 安装 Chrome yum install -y ./google-chrome-stable_current_x86_64.rpm # 或者，如果你更倾向于使用开源版本的 Chromium，可以通过 EPEL 仓库安装（版本可能略旧） # yum install -y chromium

安装完成后，可以测试一下无头模式是否能运行：

google-chrome-stable --headless --no-sandbox --disable-gpu --dump-dom https://www.example.com

如果这条命令能执行并输出网页的 DOM 内容，说明浏览器环境基本可用。--no-sandbox参数在 Linux 服务器环境下通常是必需的，否则可能会因权限问题崩溃。

3. 部署 Miao-Yunzai 本体

基础环境全部就绪后，我们就可以开始部署机器人本体了。这一步主要包括获取代码、安装依赖和初始配置。

3.1 获取项目代码与目录规划

首先，选择一个合适的目录来存放我们的机器人。不建议放在 root 目录下，可以创建一个专门的目录，比如/opt或/home下。

# 切换到 /opt 目录，你也可以选择其他位置，如 /home cd /opt # 克隆 Miao-Yunzai 的仓库 git clone --depth=1 https://github.com/yoimiya-kokomi/Miao-Yunzai.git # 进入项目目录 cd Miao-Yunzai

这里使用了--depth=1参数进行浅克隆，只下载最新的提交历史，速度更快，节省空间。

目录权限问题：确保当前用户对/opt/Miao-Yunzai目录有读写权限。如果使用 root 克隆，后续可能涉及文件归属问题。一个良好的实践是创建一个专门的非 root 用户来运行机器人（出于安全考虑），但为了教程简化，我们暂时用当前用户操作。如果你创建了新用户，记得将目录所有者更改过去：chown -R newuser:newuser /opt/Miao-Yunzai。

3.2 安装 Node.js 依赖：解决网络与编译难题

这是整个安装过程中最容易出错的一步。npm install会从 npm 官方仓库（默认在国外）下载大量包，并可能编译一些原生模块（如puppeteer相关的canvas、sqlite3等）。

步骤一：配置 npm 镜像源（大幅提升下载速度）

# 设置淘宝镜像源 npm config set registry https://registry.npmmirror.com/ # 验证配置 npm config get registry # 应该输出 https://registry.npmmirror.com/

步骤二：执行安装

npm install

这个过程可能会持续几分钟到十几分钟，取决于你的网络速度和服务器性能。控制台会滚动大量的安装日志。

步骤三：应对常见安装错误

  1. node-gyp编译错误：如果看到关于gyp、C++ compiler的错误，通常是缺少编译环境。我们已经安装了Development Tools，所以这个问题应该已解决。如果还报错，可能是缺少更具体的头文件，可以尝试：

    yum install -y python2 # 或 python3，node-gyp 需要 Python # 以及一些可能的库 yum install -y libX11-devel libXext-devel libXrender-devel libXtst-devel cups-devel pango-devel atk-devel libuuid-devel

  2. puppeteer下载 Chromium 失败：这是最高频的错误。现象是卡在Downloading Chromium很久，然后报网络超时。因为我们之前已经系统安装了 Chrome/Chromium，可以跳过这一步。

    • 方法A（推荐）：在安装前设置环境变量跳过下载。
      # 设置环境变量，告诉 puppeteer 使用系统已安装的 Chrome export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome-stable # 然后再次运行 npm install npm install
    • 方法B：如果已经安装失败，可以清除 npm 缓存并重试。
      npm cache clean --force rm -rf node_modules package-lock.json # 设置环境变量后重新安装 export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install

  3. 权限错误（EACCES）：如果你不是 root 用户，可能在全局安装某些包或写入某些目录时遇到权限问题。不要使用sudo npm install！这会导致文件所有权混乱。正确的做法是修复 npm 的全局目录权限，或者使用--prefix参数安装到用户目录。对于项目本地依赖，在项目目录下直接npm install一般不会有问题。

  4. 内存不足（OOM）：在内存较小的服务器（如 1GB）上，编译某些大型原生模块（如canvas）时可能会因内存不足而崩溃。可以尝试增加交换空间（Swap）：

    # 创建一个 2GB 的交换文件 dd if=/dev/zero of=/swapfile bs=1M count=2048 chmod 600 /swapfile mkswap /swapfile swapon /swapfile # 为了永久生效，将以下行添加到 /etc/fstab # /swapfile swap swap defaults 0 0

3.3 初始化配置与插件安装

依赖安装成功后，Miao-Yunzai 还不能直接运行，它需要一些初始配置，并且核心功能依赖于一个名为yunzai-bot的插件。

  1. 复制配置文件模板：

    # 复制默认配置文件 cp config/config_default.js config/config.js cp config/redis_default.js config/redis.js
    • config.js：机器人的主配置文件，包含 QQ 账号、主人 QQ、日志级别等设置。
    • redis.js：Redis 数据库的连接配置。

  2. 安装核心插件yunzai-bot： Miao-Yunzai 本身是一个框架，其核心功能（如消息处理、插件加载）由yunzai-bot插件提供。我们需要将它安装到plugins目录。

    # 进入 plugins 目录 cd plugins # 克隆 yunzai-bot 插件 git clone --depth=1 https://github.com/yoimiya-kokomi/yunzai-bot.git # 返回 Miao-Yunzai 根目录 cd ..

  3. 安装其他常用插件（可选）： 社区有很多有趣的插件，比如xiaoyao-cvs-plugin（图鉴查询）、flower-plugin（抽卡、娱乐）等。安装方式类似，都是git clone到plugins目录下。建议初期先只安装核心插件，确保基础运行正常后再逐步添加，以便于问题排查。

    cd plugins git clone --depth=1 https://github.com/yoimiya-kokomi/xiaoyao-cvs-plugin.git # ... 克隆其他插件 cd ..

4. 配置与启动：让机器人“活”起来

现在，代码和依赖都准备好了，我们需要进行最关键的一步：配置机器人并启动它。这涉及到修改配置文件、处理登录以及管理进程。

4.1 配置文件详解与修改

我们需要编辑两个主要的配置文件：config/config.js和config/redis.js。

1. 配置 Redis (config/redis.js)： 这个文件通常不需要修改，如果你按照前面的步骤安装了 Redis 且没有改动端口和密码，默认配置就能连接。

// config/redis.js 默认内容 export default { host: '127.0.0.1', // Redis 服务器地址，本地就是 127.0.0.1 port: 6379, // Redis 端口，默认 6379 password: '', // 如果你设置了 Redis 密码，在这里填写 db: 0, // 使用的数据库编号，默认 0 }

检查一下：如果你的 Redis 服务名是redis6或者修改了端口，需要相应调整host和port。如果设置了密码（通过requirepass指令在redis.conf中），务必填写password。

2. 配置机器人主设置 (config/config.js)： 这是最重要的配置文件，用文本编辑器打开它：

vim config/config.js

你需要关注并修改以下几个关键部分：

// config/config.js 片段 export default { // ****** 必填项 ****** // 机器人的 QQ 号 qq: 123456789, // ****** 强烈建议修改 ****** // 主人的 QQ 号，用于接收报错和发送管理命令 masterQQ: 987654321, // 日志级别，开发调试可以设为 `trace` 或 `debug`，生产环境用 `info` 或 `warn` log_level: 'info', // 平台设置，1 为安卓手机，2 为安卓平板，3 为安卓手表，4 为 macOS，5 为 iPad // 不同平台可能影响消息发送频率限制和部分功能。通常用 1 或 2。 platform: 1, // 是否启用 HTTP API 服务，以及监听的端口 // 如果你需要通过其他程序调用机器人的 API，可以开启 http: { enable: false, host: '0.0.0.0', port: 5700, }, // 心跳包设置，保持连接用，一般默认即可 heart_interval: 5000, // 消息发送间隔（毫秒），防止风控，根据网络情况调整 send_interval: 200, // 其他更多高级配置可以暂时保持默认 }
  • qq：这是机器人的 QQ 号。你需要准备一个小号QQ，不建议使用大号，因为机器人需要长期在线，且可能涉及频繁操作。
  • masterQQ：你自己的 QQ 号。当机器人出现严重错误时，会通过 QQ 消息通知你。你也可以通过向机器人私聊发送特定命令（如#重启）来管理它。
  • platform：模拟的客户端类型。1（手机）最通用，但某些情况下2（平板）可能更稳定。如果登录时遇到版本过低等提示，可以尝试切换这个值。

保存并退出编辑器。

4.2 首次启动与扫码登录

配置完成后，就可以尝试启动机器人了。Miao-Yunzai 使用pnpm作为启动命令（它也是一个包管理器，在npm install时已安装）。

启动命令：

# 在 Miao-Yunzai 项目根目录下执行 pnpm start

或者使用 npm 脚本：

npm run start

第一次启动会进行一些初始化工作，然后最关键的一步出现了：扫码登录。控制台会输出一个二维码图片（用字符画显示），并提示你使用手机 QQ 扫描登录。

扫码登录的详细过程与避坑：

  1. 准备手机 QQ：确保用于扫码的手机 QQ 已经登录了你配置的机器人 QQ 号（即config.js里的qq）。不要用其他 QQ 号扫码。
  2. 扫描控制台二维码：打开手机 QQ，点击右上角“+” -> “扫一扫”，对准终端上的二维码。
  3. 授权登录：手机会提示“正在通过 QQ 扫码登录‘Mirai’”，点击“允许登录”或“登录”。
  4. 等待连接：扫码成功后，控制台会显示“扫码成功，正在登录…”。如果网络通畅，稍等片刻就会显示“登录成功”或“收到在线状态事件”。

可能遇到的问题及解决方案：

  • 二维码不显示或乱码：某些终端或 SSH 客户端可能不支持显示字符画二维码。可以尝试：
    • 检查 SSH 客户端是否支持 UTF-8 编码。
    • 尝试使用pnpm start的--qr-show参数（如果支持），或者查看日志文件logs/下是否有二维码图片生成（有些版本会保存为文件）。
    • 使用pnpm login命令，它可能会提供另一种登录方式（如手动输入 ticket）。
  • 扫码后提示“版本过低”或“当前版本不支持”：
    • 修改config.js中的platform值，尝试2（平板）或5（iPad）。
    • 尝试使用pnpm start的--protocol 6参数（如果协议版本支持）。
  • 扫码后一直卡在“登录中…”或连接失败：
    • 网络问题：确保服务器可以正常访问腾讯的服务器。检查防火墙是否放行了相关端口（通常不需要特殊配置）。
    • 设备锁：如果机器人 QQ 号开启了设备锁，扫码后需要在手机上确认。确保手机 QQ 已登录该账号，并留意是否有确认提示。
    • 缓存问题：删除data目录下的device.json和session.token等文件（先停止机器人），然后重新启动扫码。这相当于重置了登录设备信息。
      # 停止机器人后执行 rm -rf data/device.json data/session.token pnpm start
  • 登录成功后很快掉线：
    • 可能是心跳包设置问题，检查网络稳定性。
    • 也可能是腾讯的风控机制，新号或异地登录容易被踢。保持在线一段时间，或者尝试更换登录platform。

4.3 进程管理与后台运行

通过pnpm start启动是在前台运行的，关闭 SSH 窗口或按Ctrl+C就会停止机器人。我们需要让它在后台持续运行。

方案一：使用screen或tmux（简单易用）这是最推荐新手使用的方法，可以随时 attach 回会话查看日志。

# 安装 screen (如果未安装) yum install -y screen # 创建一个新的 screen 会话，命名为 `yunzai` screen -S yunzai # 在新会话中，切换到 Miao-Yunzai 目录并启动 cd /opt/Miao-Yunzai pnpm start # 然后按下 Ctrl+A，再按 D 键，将会话分离到后台。 # 机器人会在后台继续运行。 # 要重新连接会话查看日志，使用： screen -r yunzai # 如果忘记了会话名，可以用 screen -ls 列出所有会话。

方案二：使用 systemd 服务（生产环境推荐）这种方式更规范，可以开机自启，方便用systemctl命令管理。

  1. 创建服务文件：
    vim /etc/systemd/system/miao-yunzai.service
  2. 写入以下内容（根据你的实际路径修改WorkingDirectory和ExecStart）：
    [Unit] Description=Miao-Yunzai Bot Service After=network.target redis.service [Service] Type=simple User=root # 建议改为一个非 root 用户，例如 `useradd -m yunzai` 后改为 `User=yunzai` WorkingDirectory=/opt/Miao-Yunzai ExecStart=/usr/bin/pnpm start Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target

    注意：ExecStart的路径需要是pnpm的绝对路径，可以用which pnpm命令查看。如果pnpm不在/usr/bin/下，请修改。

  3. 重新加载 systemd 配置，启动服务并设置开机自启：
    systemctl daemon-reload systemctl start miao-yunzai systemctl enable miao-yunzai
  4. 查看服务状态和日志：
    systemctl status miao-yunzai # 查看实时日志 journalctl -u miao-yunzai -f

方案三：使用 nohup（临时用）

cd /opt/Miao-Yunzai nohup pnpm start > yunzai.log 2>&1 & # 输出会被重定向到 yunzai.log 文件 # 查看日志 tail -f yunzai.log

5. 基础测试、插件管理与故障排查

机器人成功启动并登录后，我们还需要验证其基本功能是否正常，并学习如何管理插件。

5.1 基础功能测试

登录成功后，控制台会持续输出心跳和收到的消息日志。我们可以进行一个最简单的测试：

  1. 私聊测试：用你的主人 QQ（masterQQ）给机器人 QQ 发送一条消息，比如“测试”。在控制台日志中，你应该能看到类似[接收][私聊]的记录。机器人默认可能没有回复，这取决于已安装的插件。
  2. 发送命令：安装yunzai-bot核心插件后，它自带一些基础命令。尝试向机器人私聊发送：
    • #帮助或#help：查看命令列表。
    • #状态：查看机器人运行状态。
    • #重启：重启机器人（需要主人权限）。 如果机器人能正确回复，说明消息接收、处理和发送的整个链路是通的。

5.2 插件管理：安装、更新与禁用

Miao-Yunzai 的插件都存放在plugins目录下，每个插件一个文件夹。

  • 安装新插件：进入plugins目录，使用git clone插件仓库地址即可。克隆后，通常需要重启机器人（或在控制台按R键重载插件）才能生效。

    cd /opt/Miao-Yunzai/plugins git clone --depth=1 <插件仓库地址> cd .. # 然后重启机器人，或者在运行中的机器人控制台按 R 键（如果支持热重载）

  • 更新插件：进入特定插件目录，执行git pull。

    cd /opt/Miao-Yunzai/plugins/yunzai-bot git pull

    注意：更新插件后，有时需要同时更新其依赖。可以尝试在插件目录下运行npm install（如果该插件有独立的package.json文件）。更稳妥的做法是重启整个机器人。

  • 禁用/启用插件：

    • 重命名法：在插件目录名前加一个下划线_或点.，例如将xiaoyao-cvs-plugin重命名为_xiaoyao-cvs-plugin，机器人启动时就会忽略它。
    • 配置文件法：某些插件支持在config目录下有自己的配置文件，里面可能有enable: false的选项。
    • 禁用后需要重启机器人。

  • 删除插件：直接删除插件对应的文件夹即可，然后重启机器人。

5.3 常见故障与排查思路

即使按照教程一步步来，也可能遇到问题。这里提供一个通用的排查思路：

  1. 查看日志：这是最重要的第一步！日志文件位于logs/目录下，按日期命名。也可以通过控制台实时查看。仔细阅读错误信息，它通常会给出明确的线索。

    # 查看最新的错误日志 tail -f logs/error/最新的错误日志文件.log # 或者查看综合日志 tail -f logs/最新的综合日志文件.log

  2. 检查 Redis 连接：很多启动失败是因为 Redis 没连上。确保 Redis 服务正在运行，并且配置config/redis.js中的host、port、password正确。

    systemctl status redis redis-cli ping

  3. 检查 Node.js 和 npm 版本：确认版本符合要求（Node.js >= 16）。

    node -v npm -v

  4. 检查依赖是否完整：如果启动时报某个模块找不到（Cannot find module ‘xxx’），可能是依赖安装不完整。尝试删除node_modules和package-lock.json，重新npm install（注意环境变量）。

    rm -rf node_modules package-lock.json npm cache clean --force # 再次确认环境变量（如果之前设置过） export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install

  5. 端口冲突：如果修改了config.js中的 HTTP API 端口（如 5700），确保该端口没有被其他程序占用。

  6. 权限问题：确保运行机器人的用户对Miao-Yunzai目录及其子目录有读写权限。检查logs/、data/等目录是否可写。

  7. QQ 风控：这是非技术性问题，但很常见。表现为登录失败、频繁掉线、消息发不出等。可以尝试：

    • 更换登录platform。
    • 在手机 QQ 上多活跃一下机器人账号（挂时长、聊天）。
    • 尝试在服务器所在地的 IP 段登录（如果是云服务器）。
    • 过一段时间再试。

6. 进阶配置与优化建议

当机器人稳定运行后，可以考虑一些进阶配置来提升体验和安全性。

6.1 使用反向 WebSocket 连接（go-cqhttp）

Miao-Yunzai 默认使用 “扫码登录” 方式，这实际上是内部集成了一套协议实现。但对于更稳定、功能更丰富的需求，社区普遍推荐使用go-cqhttp作为独立的 QQ 客户端，Miao-Yunzai 通过 WebSocket 连接到它。这样做的好处是协议更新更及时，功能更全，且两者进程分离，更稳定。

  1. 下载并配置 go-cqhttp：
    • 从 GitHub Release 页面下载对应 Linux 架构的 go-cqhttp 二进制文件。
    • 解压后，首次运行会生成配置文件config.yml。
    • 主要配置项：
      account: uin: 123456789 # 机器人 QQ 号 password: '' # 密码，不填则用扫码登录 # 反向 WebSocket 设置 servers: - ws-reverse: universal: ws://127.0.0.1:2536/go-cqhttp # 端口需与 Miao-Yunzai 配置对应 reconnect-interval: 3000
  2. 配置 Miao-Yunzai： 在config.js中，找到并修改connect配置：
    export default { // ... 其他配置 connect: { // 将 type 从 1 (扫码) 改为 2 (WS反向连接) type: 2, // go-cqhttp 反向 WS 的地址，与上面配置对应 ws: 'ws://127.0.0.1:2536/go-cqhttp', }, // ... 其他配置 }
  3. 启动顺序：先启动 go-cqhttp 并完成登录，再启动 Miao-Yunzai。

6.2 日志管理与切割

默认的日志文件会越来越大，需要定期清理或切割。可以使用 Linux 自带的logrotate工具。

  1. 创建 logrotate 配置文件：
    vim /etc/logrotate.d/miao-yunzai
  2. 写入以下内容：
    /opt/Miao-Yunzai/logs/*.log { daily missingok rotate 7 compress delaycompress notifempty create 644 root root postrotate # 如果使用 systemd 服务，可以发送信号让程序重新打开日志文件 systemctl reload miao-yunzai 2>/dev/null || true endscript }
    这个配置会每天轮转日志，保留最近7天的压缩备份。

6.3 安全注意事项

  1. 不要使用 root 用户长期运行：建议创建一个专用用户（如yunzai）来运行机器人，并修改相关文件和目录的归属。
    useradd -m -s /bin/bash yunzai chown -R yunzai:yunzai /opt/Miao-Yunzai # 然后修改 systemd 服务文件中的 User=yunzai
  2. 保护配置文件：config.js里包含了你的 QQ 号，虽然不是密码，但也应避免泄露。确保配置文件权限设置合理（如chmod 600 config/config.js）。
  3. 防火墙：如果开启了 HTTP API（config.js中的http.enable: true），确保防火墙只允许可信 IP 访问对应的端口（默认 5700）。
  4. 定期更新：关注项目 GitHub 仓库的 Release 和 Issues，定期更新 Miao-Yunzai 本体和插件，以获取新功能和安全修复。更新前做好备份。

整个部署过程从系统准备到机器人跑起来，步骤虽多，但每一步都有其必要性。遇到问题多查日志，善用搜索引擎和项目社区的 Issues 页面，大部分坑都有前人踩过。保持耐心，按照这个指南一步步操作，你的 Miao-Yunzai 机器人一定能在 CentOS 服务器上顺利安家。