1. 项目概述为什么选择Miao-Yunzai如果你在Linux服务器上折腾过QQ机器人尤其是基于Node.js的Yunzai-Bot那你大概率听说过或者被它的环境依赖、版本兼容问题折腾得够呛。传统的Yunzai-Bot在部署时常常会遇到Node.js版本、Redis配置、插件依赖等一系列“拦路虎”对于新手来说从零开始搭建无异于一场噩梦。而“喵版Yunzai”也就是Miao-Yunzai正是为了解决这些痛点而生的一个分支版本。简单来说Miao-Yunzai是在原版Yunzai-Bot基础上进行深度优化和整合的版本。它最大的特点就是“开箱即用”的属性大大增强。项目维护者通常会预先处理好一些棘手的依赖比如特定版本的Puppeteer用于模拟浏览器登录QQ、优化过的插件加载机制甚至提供了一键安装脚本。这对于想在CentOS这类稳定但软件包可能稍显陈旧的Linux发行版上快速部署机器人的用户来说吸引力是巨大的。你不用再像以前那样一个个去解决Node.js版本冲突、Chromium无法启动、Redis连接失败这些令人头疼的问题安装过程被极大地简化和标准化了。我选择在CentOS 7/8上部署一方面是考虑到生产环境的稳定性很多云服务器默认提供的正是CentOS镜像另一方面这个过程能覆盖从系统准备、环境配置到机器人上线的完整链路其中遇到的坑和解决方案对于其他Linux发行版如Ubuntu、Debian也有很高的参考价值。这次安装的目标不仅仅是让机器人跑起来更是要理清每一个步骤背后的原理让你知其然更知其所以然未来无论遇到什么问题都能自己动手排查。2. 安装前准备理清思路与备齐工具在真正动手敲命令之前花几分钟做好准备工作能避免后面绝大多数莫名其妙的错误。安装Miao-Yunzai不是一个孤立的操作它依赖于一个完整的软件栈。2.1 核心依赖解析首先我们必须清楚Miao-Yunzai需要哪些“地基”Node.js运行环境这是核心中的核心。Miao-Yunzai是一个Node.js应用所有的逻辑都由JavaScript/TypeScript编写。版本选择是关键太老的版本可能不支持新的语法特性太新的版本又可能与某些原生模块如canvas、puppeteer不兼容。根据Miao-Yunzai项目仓库的推荐通常需要Node.js 16或18的LTS长期支持版本。我们将采用最稳妥的方式通过NodeSource仓库安装指定版本的Node.js而不是使用CentOS默认的、版本过旧的软件包。包管理工具npm/pnpm/yarn用于安装项目自身的JavaScript依赖包。npm随Node.js安装但它的性能和磁盘空间占用有时不尽如人意。pnpm是近年来非常流行的替代品通过硬链接和符号链接来节省磁盘空间并提升安装速度。很多现代Node.js项目包括Miao-Yunzai都推荐使用pnpm。我们将安装并使用pnpm。Redis数据库Yunzai-Bot使用Redis作为缓存和会话存储。例如机器人的登录状态、一些临时数据、插件缓存等都存放在Redis里。它是一个内存数据库速度极快对于需要快速响应的聊天机器人场景至关重要。CentOS默认的软件源里包含Redis我们可以直接安装。Chromium浏览器这是实现“无头浏览器”登录QQ的关键。Puppeteer库需要调用一个实际的Chromium或Chrome浏览器来模拟用户操作。在服务器这种没有图形界面的环境下我们需要安装Chromium的无头版本。CentOS官方源可能没有最新版我们会通过配置EPEL企业版Linux额外软件包仓库来安装。系统基础工具如Git用于克隆代码、wget/curl下载文件、开发工具链如gcc-c、make用于编译某些原生Node模块等。2.2 服务器环境检查登录你的CentOS服务器假设你已通过SSH连接我们首先做一个全面的体检# 1. 检查系统版本确认是CentOS 7还是8这会影响后续一些仓库的配置。 cat /etc/redhat-release # 2. 检查当前用户。建议使用非root的普通用户进行操作避免权限过高带来风险。 whoami # 3. 检查关键工具是否已安装。如果未安装后续步骤会进行安装。 git --version # 如果没有输出说明未安装 wget --version # 或 curl --version注意强烈建议使用一个具有sudo权限的普通用户例如botuser来执行所有操作。如果某些命令需要更高权限如安装软件包再通过sudo来提权。全程使用root用户是危险且不规范的。如果你的服务器是一个全新的、最小化安装的CentOS那么很多工具可能都没有。别担心接下来的步骤会带你一步步装好所有东西。3. 基础环境搭建从零构建Node.js生态这是整个安装过程中最需要耐心的一步基础打得好后面才能一帆风顺。3.1 配置系统软件源与安装基础工具首先更新系统并安装必备的工具包。EPEL仓库提供了大量CentOS官方源中没有的额外软件是我们获取新版软件的重要渠道。# 切换到root用户或使用sudo执行以下命令 sudo -i # 更新现有的yum包管理器缓存 yum update -y # 安装EPEL仓库Extra Packages for Enterprise Linux # CentOS 7: yum install -y epel-release # CentOS 8 略有不同可能需要先启用PowerTools仓库再安装epel-release # dnf install -y epel-release # 安装基础编译工具和依赖 yum groupinstall -y Development Tools yum install -y wget curl git vim openssl-devel zlib-devel # 退出root用户回到你的普通用户 exit3.2 安装并配置Node.js环境我们不使用CentOS自带的旧版Node.js。这里采用NodeSource提供的官方仓库可以安装指定版本。# 1. 下载并运行NodeSource安装脚本这里以Node.js 18.x LTS为例请根据Miao-Yunzai项目要求选择版本 # 访问 https://github.com/nodesource/distributions 查看最新安装命令 curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash - # 2. 安装Node.js和npm sudo yum install -y nodejs # 3. 验证安装 node --version # 应输出 v18.x.x npm --version # 应输出 9.x.x 或更高3.3 安装pnpm并配置淘宝镜像Node.js自带的npm有时安装依赖较慢我们换用更高效的pnpm并配置国内镜像加速。# 1. 使用npm全局安装pnpm sudo npm install -g pnpm # 2. 验证pnpm安装 pnpm --version # 3. 可选但强烈推荐配置pnpm使用国内淘宝镜像大幅提升安装速度 pnpm config set registry https://registry.npmmirror.com/ # 同时设置npm镜像因为某些底层安装可能仍会调用npm npm config set registry https://registry.npmmirror.com/3.4 安装与配置RedisRedis的安装相对简单但配置和启动服务需要注意。# 1. 安装Redis sudo yum install -y redis # 2. 启动Redis服务并设置开机自启 sudo systemctl start redis sudo systemctl enable redis # 3. 检查Redis运行状态 sudo systemctl status redis # 看到 active (running) 字样说明启动成功 # 4. 可选进行简单连接测试 redis-cli ping # 如果返回 PONG说明Redis服务正常。实操心得有时候Redis默认配置只监听本地回环地址127.0.0.1如果你的应用和Redis在同一台服务器这没问题。但如果未来需要考虑分布式部署可能需要修改/etc/redis.conf中的bind配置。不过对于本次单机部署保持默认即可。3.5 安装Chromium及相关依赖Puppeteer在安装时会自动下载一个Chromium但在Linux服务器上这个自动下载经常因为网络或依赖问题失败。我们选择先通过系统包管理器安装一个基础版本让Puppeteer“有东西可用”这通常更稳定。# 通过EPEL仓库安装Chromium和无头化所需的库 sudo yum install -y chromium-headless Xvfb libXcomposite libXcursor libXdamage libXext libXi libXtst cups-libs libXScrnSaver libXrandr alsa-lib pango atk at-spi2-atk gtk3XvfbX Virtual Framebuffer是一个非常重要的工具。它可以在内存中模拟一个显示服务器让那些需要图形界面的程序如Chromium在无屏幕的服务器上也能运行。虽然Puppeteer的“无头模式”本身不需要显示但某些底层图形操作仍然依赖一个X Server环境Xvfb就提供了这个虚拟环境。4. 部署Miao-Yunzai本体克隆、安装与配置基础环境全部就绪现在可以请出主角了。4.1 获取项目代码选择一个合适的目录来存放你的机器人比如在用户家目录下创建一个projects文件夹。# 回到你的普通用户家目录 cd ~ # 创建一个项目目录 mkdir -p projects cd projects # 克隆Miao-Yunzai的仓库。请务必使用项目官方或你信任的源地址。 # 这里假设官方仓库地址实际请替换为正确的Git地址。 git clone --depth1 https://gitee.com/yoimiya-kokomi/miao-yunzai.git # 如果上面的地址无法访问可以尝试GitHub镜像或其他国内镜像源。 # 进入项目目录 cd miao-yunzai--depth1参数表示只克隆最近一次提交的历史可以加快克隆速度节省空间。对于部署来说这完全足够。4.2 安装项目依赖这是最考验网络和环境的步骤。我们使用之前安装好的pnpm。# 在项目根目录下执行 pnpm install这个命令会读取项目根目录下的package.json文件并安装所有dependencies和devDependencies中列出的包。由于我们配置了淘宝镜像速度应该比较快但依赖数量可能很多需要耐心等待几分钟。踩坑记录pnpm install过程中最常见的错误是某些“原生模块”编译失败例如canvas、puppeteer等。这些模块在安装时需要用C编译器编译本地代码。如果你在前面的步骤中已经安装了Development Tools和openssl-devel等通常可以解决。如果仍报错错误信息通常会明确指出缺少哪个头文件.h文件你可以根据错误信息搜索并安装对应的-devel包。例如如果提示node-gyp错误可以尝试全局安装node-gyp并重新配置sudo npm install -g node-gyp。4.3 核心配置文件解析与修改Miao-Yunzai的配置通常集中在几个文件中我们需要根据实际情况调整。config/config/bot.yaml(或类似名称)这是机器人的主配置文件。# 示例配置具体字段请以项目实际文件为准 bot: qq: 123456789 # 这里填写你用来作为机器人的QQ号 password: # 密码但强烈不建议明文填写。通常留空采用扫码登录。 platform: 2 # 登录协议1为手机协议2为平板协议。平板协议更稳定推荐使用。 log_level: info # 日志级别 redis: host: 127.0.0.1 # Redis地址本地就是127.0.0.1 port: 6379 # Redis端口默认6379 password: # 如果Redis设置了密码在此填写 db: 0 # 使用的数据库编号最重要的就是bot.qq和bot.platform。密码栏留空启动后会提示扫码登录。config/config/other.yaml(或package.json中的脚本)查看启动命令。 通常项目会在package.json的scripts部分定义启动命令例如scripts: { start: node app.js, login: node app.js --login }首次启动我们通常需要运行登录命令来扫码。注意事项配置文件中的QQ号请使用一个专门的小号不要使用自己的主号。同时了解并遵守相关平台的使用规范。配置文件的路径和名称可能因Miao-Yunzai的具体版本而异请以克隆下来的项目内的实际文件和文档为准。5. 首次启动与QQ登录跨越最后一道关卡配置完成后就可以尝试启动机器人了。首次启动的核心任务是完成QQ的登录认证。5.1 启动并扫码登录在项目根目录下运行登录命令# 根据项目说明通常是以下命令之一 pnpm run login # 或 node app.js --login # 或直接运行项目提供的登录脚本运行后控制台会输出大量日志。重点关注其中是否包含一个二维码的ASCII艺术图形或者一条包含二维码图片的本地文件路径如http://localhost:端口/二维码。情况一控制台显示二维码直接在终端里可能很难扫描。你可以尝试调整终端字体大小或者使用支持显示图片的终端工具如某些SSH客户端的高级版本。情况二控制台输出一个本地HTTP链接例如扫码登录地址http://127.0.0.1:端口号/xxx。由于服务器没有浏览器你需要通过端口转发或本地代理来访问这个链接。端口转发推荐在你本地电脑的SSH客户端中设置一个本地端口转发。例如将服务器的3300端口转发到你本地的3300端口。# 在你本地电脑的终端执行Windows可使用Git Bash ssh -L 3300:127.0.0.1:3300 your_usernameyour_server_ip然后在你本地电脑的浏览器中访问http://127.0.0.1:3300就能看到服务器上生成的二维码页面了。临时公网访问有风险如果服务器有公网IP且防火墙开放了端口可以临时修改启动配置让服务监听0.0.0.0而非127.0.0.1这样你就能通过http://服务器IP:端口直接访问。完成后务必改回以免暴露服务。用你的手机QQ注意必须是机器人账号对应的手机QQ扫描这个二维码。扫码后手机QQ会提示你授权登录确认即可。5.2 登录成功确认与后台运行扫码授权成功后服务器控制台会输出“登录成功”或类似的提示信息。此时机器人已经在线并可以开始响应指令了。但是当前进程是在SSH会话中前台运行的。一旦你关闭SSH窗口这个进程就会终止机器人就掉线了。我们需要让它在后台持续运行。使用PM2进行进程管理最推荐 PM2是一个专业的Node.js进程管理器可以守护进程、自动重启、查看日志。# 全局安装PM2 sudo pnpm install -g pm2 # 或者使用npm: sudo npm install -g pm2 # 使用PM2启动你的机器人假设启动命令是 node app.js cd ~/projects/miao-yunzai pm2 start app.js --name miao-yunzai # 设置PM2开机自启 pm2 startup # 执行上面命令后它会输出一行类似 sudo env PATH...的命令复制并执行它。 pm2 save现在机器人就在后台运行了。常用命令pm2 status查看所有进程状态。pm2 logs miao-yunzai查看该进程的实时日志。pm2 stop miao-yunzai停止进程。pm2 restart miao-yunzai重启进程。使用系统服务Systemd 对于追求与系统集成度更高的用户可以创建一个systemd服务文件。sudo vim /etc/systemd/system/miao-yunzai.service写入以下内容根据你的实际路径修改[Unit] DescriptionMiao-Yunzai QQ Bot Afternetwork.target redis.service [Service] Typesimple Userbotuser # 替换为你的普通用户名 WorkingDirectory/home/botuser/projects/miao-yunzai ExecStart/usr/bin/node /home/botuser/projects/miao-yunzai/app.js Restarton-failure RestartSec10 [Install] WantedBymulti-user.target然后启用并启动服务sudo systemctl daemon-reload sudo systemctl enable miao-yunzai sudo systemctl start miao-yunzai sudo systemctl status miao-yunzai6. 进阶配置与插件管理让机器人更强大基础机器人运行起来后它可能只是一个“骨架”。Yunzai-Bot的强大之处在于其丰富的插件生态。6.1 安装与管理插件Miao-Yunzai的插件通常也是独立的Git仓库。安装方式一般是在项目的plugins目录下进行克隆。# 进入项目的插件目录 cd ~/projects/miao-yunzai/plugins # 示例安装一个名为“example-plugin”的插件 git clone --depth1 https://gitee.com/some-author/example-plugin.git # 克隆后回到项目根目录重启机器人以使插件生效 cd .. pm2 restart miao-yunzai重要提示插件的安全性至关重要只从可信的来源如官方插件商店、知名开发者仓库安装插件。随意的插件可能包含恶意代码泄露你的机器人账号甚至服务器权限。6.2 配置文件热重载与调试很多插件和机器人核心配置都支持热重载即修改配置文件后无需重启整个机器人通过发送特定指令就能重新加载。查看帮助向机器人发送#帮助或#菜单通常会列出所有可用指令其中可能包含#更新、#重载等管理命令。查看日志当机器人行为异常或插件报错时第一时间查看日志。# 如果使用PM2 pm2 logs miao-yunzai --lines 100 # 或者直接查看项目目录下的日志文件通常位于 logs/ 文件夹内。 tail -f ~/projects/miao-yunzai/logs/最新的日志文件.log日志是排查问题的生命线错误信息、堆栈跟踪都从这里来。6.3 性能监控与维护机器人长期运行需要关注其资源占用。# 查看Node.js进程资源占用 pm2 monit # 或者使用系统工具 top -u botuser # 查看对应用户的进程 htop # 如果已安装一个更友好的交互式进程查看器 # 检查Redis内存使用 redis-cli info memory如果发现内存占用持续增长内存泄漏可能需要定期重启机器人或者检查是否有插件存在内存问题。7. 故障排查与常见问题实录即使按照步骤操作也难免会遇到问题。这里汇总一些典型问题及其解决思路。7.1 登录相关问题问题现象可能原因排查与解决思路二维码不显示或链接无法访问1. 端口被防火墙拦截2. 服务未正确监听3. Puppeteer启动Chromium失败1. 检查服务器防火墙firewall-cmd或iptables是否放行了对应端口。2. 检查启动日志看是否有Server running on...提示。3. 检查日志中是否有Chromium启动失败的错误。尝试手动安装Chromium如前文所述并设置环境变量PUPPETEER_EXECUTABLE_PATH/usr/bin/chromium-browser。扫码后提示“版本过低”或登录失败登录协议platform选择不当在bot.yaml中将platform从1手机改为2平板或反之尝试。平板协议通常更稳定。扫码后提示“网络错误”或超时1. 服务器网络不稳定2. 账号被风控1. 检查服务器到腾讯服务器的网络连通性。2. 更换登录IP重启服务器或使用其他网络或更换QQ号尝试。新号或长期不登录的号容易被风控。7.2 依赖安装与启动报错问题现象可能原因排查与解决思路pnpm install失败提示node-gyp错误缺少编译原生模块的系统依赖确保已安装完整的开发工具链sudo yum groupinstall -y Development Tools以及openssl-devel,python3等。具体看错误信息缺什么就装什么-devel包。启动时报错Cannot find module xxx依赖未安装完整或node_modules损坏1. 删除整个node_modules目录和pnpm-lock.yaml文件rm -rf node_modules pnpm-lock.yaml2. 清除pnpm缓存pnpm store prune3. 重新安装pnpm installPuppeteer启动Chromium时报错缺少Chromium或系统库1. 确认已通过yum安装chromium-headless及相关库见3.5节。2. 尝试在启动命令前添加环境变量export PUPPETEER_SKIP_CHROMIUM_DOWNLOADtrue和export PUPPETEER_EXECUTABLE_PATH/usr/bin/chromium-browser然后重启。7.3 运行中常见问题问题现象可能原因排查与解决思路机器人偶尔无响应或响应慢1. 服务器资源CPU/内存不足2. Redis连接问题3. 网络延迟1. 使用top命令查看资源占用。考虑升级服务器配置或优化插件。2. 检查Redis服务状态systemctl status redis查看日志/var/log/redis/redis.log。3. 检查服务器网络状况。插件加载失败1. 插件本身有bug2. 插件依赖未安装3. 与核心或其他插件冲突1. 查看机器人日志找到具体错误信息。2. 尝试单独禁用该插件重命名插件目录或移出plugins文件夹看是否恢复正常。3. 到插件作者的仓库页面查看Issue或文档。PM2管理下进程意外退出1. 程序未捕获的异常导致崩溃2. 内存溢出OOM被系统杀死1. 查看PM2日志pm2 logs miao-yunzai --error。2. 查看系统日志sudo journalctl -xe或 dmesg7.4 安全与维护建议权限最小化永远不要使用root用户直接运行机器人。使用普通用户并严格控制项目目录的权限。定期备份定期备份你的config配置文件目录和重要的数据目录。Redis的数据文件默认在/var/lib/redis/dump.rdb也可以定期备份。关注更新关注Miao-Yunzai项目仓库和所用插件的更新及时修复安全漏洞和获取新功能。更新前务必在测试环境进行并备份现有数据。日志管理日志文件会随时间增长定期清理或使用日志轮转工具如logrotate进行管理避免占满磁盘空间。整个部署过程从系统准备到机器人稳定运行就像搭建一个精密的仪器。每一步都有其作用每一个错误信息都是线索。遇到问题时保持耐心仔细阅读日志善用搜索引擎和项目社区的讨论大部分问题都能找到解决方案。