最近在折腾QQ机器人发现很多教程要么环境配置复杂要么依赖本地电脑运行一旦关机机器人就下线了。为了打造一个7x24小时稳定运行的QQ机器人我决定将云崽机器人部署到云服务器上。本文将手把手带你从零开始在服务器上搭建一个功能强大的QQ云崽机器人涵盖从服务器选购、环境配置、机器人核心部署到插件扩展的全流程。无论你是想为社群提供自动化服务还是想学习机器人开发这篇保姆级教程都能让你快速上手。1. 背景与核心概念为什么选择服务器部署QQ机器人在开始动手之前我们先理清几个核心概念这有助于理解整个搭建过程。QQ机器人指能够自动登录QQ账号模拟用户行为实现消息收发、群管理、智能问答等功能的程序。它并非官方产品而是基于第三方协议实现的自动化工具。云崽机器人 (Yunzai-Bot)这是一个基于 Node.js 开发并深度依赖于go-cqhttp客户端的机器人框架。它本身不直接处理QQ协议而是通过go-cqhttp这个“桥梁”与QQ服务器通信。云崽机器人提供了丰富的插件生态可以轻松实现查天气、抽卡、聊天、游戏等娱乐和管理功能在社群中非常流行。为什么要在服务器上部署稳定性与持久性服务器尤其是云服务器通常提供99.9%以上的在线率保证机器人24小时不间断运行不受个人电脑开关机影响。性能与资源服务器拥有公网IP和稳定的网络环境消息收发更及时。同时其计算资源CPU、内存也更为充裕可以运行更复杂的插件。便于管理与维护可以通过SSH远程登录服务器进行配置、更新和查看日志管理起来比本地环境更加专业和方便。技术架构简述 整个系统可以理解为两层通信层由go-cqhttp负责。它伪装成一个QQ客户端处理登录、消息接收与发送等底层协议通信并以HTTP或WebSocket等形式将消息事件转发给上层应用。应用层由Yunzai-Bot负责。它接收来自go-cqhttp的消息事件根据配置的插件进行逻辑处理如解析命令、调用API、生成回复再将回复内容通过go-cqhttp发送出去。我们的任务就是在服务器上搭建并配置好这两层让它们协同工作。2. 环境准备与服务器选择“工欲善其事必先利其器”。搭建前我们需要准备好运行环境。2.1 服务器选择与配置对于QQ机器人来说对服务器配置要求并不高初期学习或小规模使用以下配置足够CPU1核 或 2核内存1GB 或 2GB推荐2GB运行更流畅硬盘20GB SSD 或以上带宽1Mbps ~ 5Mbps按需选择主要影响文件下载和插件更新速度操作系统Ubuntu 20.04/22.04 LTS或CentOS 7/8本文以Ubuntu 22.04为例因其软件源更新对新手更友好地域选择国内服务器如阿里云、腾讯云、华为云网络延迟更低访问QQ服务器更稳定。重要提示请确保你的服务器有公网IP并且安全组/防火墙规则放行了后续需要用到的端口如SSH的22端口以及机器人内部通信的端口。2.2 本地工具准备你需要准备以下工具来连接和管理服务器SSH客户端用于远程连接服务器。Windows推荐使用PuTTY或Windows Terminal内置OpenSSH。macOS/Linux直接使用系统自带的终端Terminal。代码/文件编辑器用于在本地查看和编辑配置文件再上传到服务器。Visual Studio Code (VSCode)配合Remote - SSH插件可以直接在本地编辑服务器上的文件非常方便。一个可用的QQ号用于登录机器人。强烈建议使用小号避免主号因使用非官方客户端而导致风险。2.3 服务器基础环境配置购买并启动服务器后首先通过SSH连接到你的服务器。# 连接命令示例将 your_server_ip 替换为你的服务器公网IP ssh rootyour_server_ip连接成功后我们进行一些基础配置。更新系统软件包sudo apt update sudo apt upgrade -y安装必要的编译工具和软件 云崽机器人基于Node.js我们需要安装Node.js运行环境以及Git、屏幕管理工具等。# 安装 Git、curl、wget、screen 等工具 sudo apt install -y git curl wget screen # 安装 Node.js (使用 NodeSource 仓库安装 LTS 版本如 v18.x) curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs # 验证安装 node -v npm -v如果输出类似v18.19.0和9.x.x的版本号说明安装成功。安装并配置PM2进程管理工具可选但强烈推荐 PM2可以守护你的机器人进程崩溃后自动重启并方便地查看日志。# 全局安装 PM2 sudo npm install -g pm2 # 设置 PM2 开机自启动 pm2 startup # 执行上述命令后它会输出一行命令类似于 # sudo env PATH$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u root --hp /root # 你需要复制这行命令并执行它。 pm2 save环境准备就绪接下来我们开始部署核心组件。3. 部署 go-cqhttp机器人的“手脚”go-cqhttp是机器人与QQ服务器通信的客户端。我们需要下载、配置并运行它。3.1 下载与解压进入一个你准备存放机器人文件的目录例如/opt。cd /opt # 从 GitHub Release 下载最新版本的 go-cqhttp # 请访问 https://github.com/Mrs4s/go-cqhttp/releases 查看最新版本号 # 以 v1.1.0 为例下载 Linux amd64 版本 wget https://github.com/Mrs4s/go-cqhttp/releases/download/v1.1.0/go-cqhttp_linux_amd64.tar.gz # 解压 tar -zxvf go-cqhttp_linux_amd64.tar.gz # 进入解压后的目录 cd go-cqhttp3.2 生成初始配置文件首次运行go-cqhttp会生成配置文件。# 给予执行权限 chmod x go-cqhttp # 首次运行选择通信方式。我们通常选择 0 (HTTP通信) 或 3 (反向WebSocket)。 # 这里以更通用的 HTTP 为例。 ./go-cqhttp程序会提示你选择通信方式输入0然后回车。接着它会生成config.yml配置文件并退出。3.3 配置 config.yml现在我们来编辑这个核心配置文件。# 使用 nano 或 vim 编辑配置文件 nano config.yml你需要关注并修改以下几个关键部分# 账号配置 account: uin: 123456789 # 填写你的机器人QQ号 password: # 密码留空或填写。建议留空首次登录会提示扫码或短信验证。 encrypt: false # 是否启用密码加密首次使用建议 false status: 0 # 在线状态0-在线 1-离开 2-隐身 3-勿扰 4-忙碌 5-Q我吧 6-听歌中 relogin: # 重连设置 delay: 3 # 重连延迟单位秒 interval: 0 # 重连间隔0为关闭 max-times: 0 # 最大重连次数0为无限 # 心跳设置 heartbeat: interval: 5 # 心跳频率单位秒 # 消息上报设置 (重点) message: post-format: string # 上报格式string 或 array # 这里配置云崽机器人接收消息的地址 # 假设云崽运行在本机的 3000 端口 servers: - http://127.0.0.1:3000/cqhttp/event # 上报事件地址 - http://127.0.0.1:3000/cqhttp/message # 上报消息地址 (根据云崽版本可能需要) # 反向WS配置如果云崽使用WS连接则启用下面的配置并注释掉上面的 servers # - ws-reverse: # universal: ws://127.0.0.1:3000/cqhttp/ws # reconnect-interval: 5000 # api-endpoint: ws://127.0.0.1:3000/cqhttp/api # HTTP 通信设置 (重点) servers: - http: host: 127.0.0.1 # 监听地址保持 localhost 即可 port: 5700 # 监听端口云崽需要通过这个端口向 go-cqhttp 发送指令 timeout: 5 middlewares: : *default # 引用默认中间件 post: # 上报地址与上面的 message.servers 对应 - url: http://127.0.0.1:3000/cqhttp/event # 上报事件 - url: http://127.0.0.1:3000/cqhttp/message # 上报消息配置要点account.uin务必填写正确的机器人QQ号。message和servers.http.post部分这是go-cqhttp将收到的QQ消息转发给云崽机器人 (Yunzai-Bot) 的配置。127.0.0.1:3000是假设云崽将在本机3000端口运行。servers.http.port: 5700这是go-cqhttp提供的API端口。云崽机器人需要通过这个端口调用go-cqhttp的API来发送消息、踢人等。保存并退出编辑器在nano中按CtrlX然后按Y再回车。3.4 首次运行与登录配置完成后再次运行go-cqhttp。# 在 screen 会话中运行防止SSH断开后进程终止 screen -S go-cqhttp ./go-cqhttp # 按 CtrlA, 再按 D 可以脱离当前screen会话程序会在后台运行。 # 重新连接会话命令screen -r go-cqhttp如果是首次登录且密码留空或未配置设备锁程序会提示扫码登录将提示的二维码链接复制到浏览器打开或用手机QQ扫描。短信验证根据提示选择短信验证输入手机收到的验证码。登录成功后控制台会显示“登录成功”等信息。此时go-cqhttp已在后台运行监听5700端口并等待云崽机器人连接。先不要关闭它。4. 部署 Yunzai-Bot机器人的“大脑”现在我们来部署云崽机器人本体。4.1 克隆项目与安装依赖打开一个新的SSH终端窗口或者新建一个screen会话。# 回到 /opt 目录或你喜欢的目录 cd /opt # 克隆 Yunzai-Bot V3 版本目前最活跃的分支 git clone --depth1 https://gitee.com/yoimiya-kokomi/Yunzai-Bot.git # 进入项目目录 cd Yunzai-Bot # 安装 pnpm (推荐使用比 npm 更快更节省空间) npm install -g pnpm # 使用 pnpm 安装项目依赖此过程可能较慢 pnpm install4.2 配置 Yunzai-Bot云崽的配置文件位于config/config/qq.yaml旧版本可能在config/qq.yaml。我们需要配置它让它知道如何连接go-cqhttp。# 如果 config/config 目录不存在先运行一次机器人会生成 # 我们先复制一份示例配置 cp config/default_config/qq.yaml config/config/qq.yaml # 编辑配置文件 nano config/config/qq.yaml关键配置项如下# QQ配置 qq: # 机器人QQ号必须与 go-cqhttp 中配置的 uin 一致 123456789: # go-cqhttp 的 HTTP API 地址和端口 host: 127.0.0.1 port: 5700 # 鉴权令牌如果 go-cqhttp 的 config.yml 中设置了 access_token这里需要填写一致 token: # 重连设置 reconn_interval: 5000 # 是否启用 enable: true # 可以配置多个QQ号 # 另一个QQ号: # host: ...配置要点qq:下的123456789需要替换为你的机器人QQ号。host和port必须指向正在运行的go-cqhttp服务127.0.0.1:5700。token需要与go-cqhttp的config.yml中access-token设置一致如果设置了的话初期可不设。保存并退出。4.3 首次运行与插件安装现在可以尝试启动云崽了。# 在项目根目录下启动 node app或者使用我们之前安装的 PM2 来启动这样更稳定pm2 start app.js --name yunzai-bot # 查看日志 pm2 logs yunzai-bot如果一切正常云崽控制台会输出连接go-cqhttp成功的日志并且go-cqhttp的控制台也会显示反向WebSocket连接成功或HTTP上报成功的消息。安装基础插件 纯净的云崽只有核心框架需要安装插件来实现功能。最常用的插件是Yunzai-Bot的官方插件集。# 在 Yunzai-Bot 根目录下执行 # 安装喵喵插件 (Miao-Plugin)提供原神等游戏查询功能 git clone --depth1 https://gitee.com/yoimiya-kokomi/miao-plugin.git ./plugins/miao-plugin/ # 安装完成后重启云崽机器人以使插件生效 # 如果使用 PM2 pm2 restart yunzai-bot重启后向机器人QQ号或它所在的群发送#帮助如果能看到插件生成的帮助菜单说明机器人已成功运行并加载了插件5. 进阶配置与优化基础功能跑通后我们可以进行一些优化让机器人更稳定、更安全、功能更强大。5.1 使用反向WebSocket通信推荐我们之前配置的是HTTP通信。实际上反向WebSocketReverse WebSocket是更推荐的方式它建立了持久连接延迟更低。修改go-cqhttp配置 (config.yml)message: # 注释掉或删除之前的 servers 配置 # - http://... # 启用反向WS - ws-reverse: universal: ws://127.0.0.1:3000/cqhttp/ws # 云崽的WS地址 api: ws://127.0.0.1:3000/cqhttp/api # API调用地址 (部分功能需要) event: ws://127.0.0.1:3000/cqhttp/event # 事件上报地址 reconnect-interval: 5000 # 如果云崽配置了 token这里也需要填写 # access-token: 你的token修改Yunzai-Bot配置 (qq.yaml) 确保host和port配置正确。对于WS连接云崽V3版本通常能自动适配。更关键的是检查云崽的config/config/bot.yaml如果存在或框架本身的WS服务是否启用。一般来说保持默认即可。修改后重启go-cqhttp和Yunzai-Bot。5.2 使用PM2进行进程守护我们已经用PM2启动了云崽同样地也应该用PM2管理go-cqhttp。# 进入 go-cqhttp 目录 cd /opt/go-cqhttp # 使用 PM2 启动 go-cqhttp并指定名称和日志文件 pm2 start ./go-cqhttp --name go-cqhttp # 设置开机自启动 (之前已为pm2本身设置过现在保存当前进程列表) pm2 save # 查看所有由 PM2 管理的进程状态 pm2 status # 查看某个进程的日志 pm2 logs go-cqhttp # 或 pm2 logs yunzai-bot5.3 安装更多插件云崽的生态非常丰富你可以安装各种插件来扩展功能。聊天插件如chatgpt-plugin需API KEY让机器人接入AI对话。管理插件如guoba-plugin锅巴插件提供Web图形化管理界面。其他游戏插件如xiaoyao-cvs-plugin提供其他游戏查询。安装方式类似都是在plugins目录下克隆插件仓库然后重启机器人。注意事项仔细阅读每个插件的README可能需要额外的配置或API密钥。插件冲突同时安装功能相似的插件可能导致冲突建议按需安装。插件更新定期进入插件目录执行git pull进行更新。5.4 配置数据备份与恢复机器人的数据如用户签到数据、插件配置通常存放在Yunzai-Bot目录下的data文件夹。定期备份这个文件夹至关重要。你可以编写一个简单的Shell脚本用crontab定时任务进行备份。# 创建备份脚本例如 /opt/backup_bot.sh nano /opt/backup_bot.sh脚本内容#!/bin/bash # 备份脚本 BACKUP_DIR/opt/backups SOURCE_DIR/opt/Yunzai-Bot/data DATE$(date %Y%m%d_%H%M%S) # 创建备份目录 mkdir -p $BACKUP_DIR # 打包压缩备份 tar -czf $BACKUP_DIR/yunzai_data_$DATE.tar.gz -C $SOURCE_DIR . # 删除7天前的备份文件 find $BACKUP_DIR -name yunzai_data_*.tar.gz -mtime 7 -delete echo Backup completed at $DATE赋予执行权限并添加到定时任务chmod x /opt/backup_bot.sh # 编辑 crontab每天凌晨3点执行备份 crontab -e # 在末尾添加一行 0 3 * * * /opt/backup_bot.sh /opt/backup.log 216. 常见问题与排查思路 (FAQ)在部署和运行过程中你可能会遇到以下问题。这里提供一个排查清单。问题现象可能原因排查步骤与解决方案go-cqhttp 登录失败1. 账号密码错误。2. 设备锁未验证。3. 网络环境被风控服务器IP。1. 确认账号密码或使用扫码/短信登录。2. 在手机QQ上检查设备锁暂时关闭或验证。3. 尝试更换服务器IP或使用家用网络IP首次登录后再迁移到服务器通过备份session.token文件。go-cqhttp 启动后立即退出1. 配置文件config.yml格式错误。2. 端口被占用。1. 使用./go-cqhttp -t测试配置文件语法。2. 检查5700等端口是否被其他程序占用netstat -tlnp | grep :5700。Yunzai-Bot 启动报错提示连接失败1.go-cqhttp未运行。2.qq.yaml中配置的host或port错误。3. 防火墙/安全组阻止了本地回环(127.0.0.1)或端口通信。1. 检查go-cqhttp进程是否存活pm2 status或ps aux | grep go-cqhttp。2. 核对qq.yaml和go-cqhttp的config.yml确保QQ号、IP、端口一致。3. 服务器本地防火墙一般不影响127.0.0.1但可检查sudo ufw status。机器人收不到消息或无法回复1. 通信方式配置错误HTTP/WS。2. 云崽插件未正确加载。3. 消息上报地址 (post.url) 错误。1. 确认go-cqhttp的message上报地址和云崽的接收地址匹配。查看双方日志是否有连接成功和消息上报记录。2. 在云崽控制台输入#全部插件检查所需插件是否在列表中。3. 确保config.yml中的post.url指向正确的云崽地址和路径。PM2 管理的进程无故停止1. 进程崩溃内存溢出、错误。2. 系统资源不足。3. PM2 配置问题。1. 查看详细日志pm2 logs app_name --lines 100。2. 检查服务器内存和CPU使用率htop或free -h。3. 可以尝试增加PM2的自动重启策略pm2 ecosystem生成配置文件进行细化设置。插件安装后功能不生效1. 插件安装路径错误。2. 插件需要额外配置或依赖。3. 插件与当前Yunzai版本不兼容。1. 确认插件克隆到了plugins目录下的独立文件夹内。2. 仔细阅读插件的README.md或config.js文件。3. 查看云崽启动日志是否有插件加载失败的报错。尝试更新插件或Yunzai版本。服务器磁盘空间不足日志文件、缓存、备份文件过多。1. 定期清理日志pm2 flush。2. 清理node_modules缓存在项目目录运行pnpm store prune。3. 检查并删除旧的备份文件。通用排查命令pm2 logs查看所有PM2进程日志。pm2 monit可视化监控进程状态。journalctl -u pm2-root查看PM2的系统服务日志如果以systemd方式安装。netstat -tlnp查看端口监听情况。tail -f /path/to/log/file实时跟踪日志文件。7. 最佳实践与安全建议将机器人部署在公网服务器上安全和稳定是第一要务。使用非root用户运行 长期使用root用户运行应用存在安全风险。建议创建一个专用用户来运行机器人。# 创建新用户如 botuser sudo adduser botuser # 将项目目录的所有权赋予新用户 sudo chown -R botuser:botuser /opt/Yunzai-Bot /opt/go-cqhttp # 切换到新用户 sudo su - botuser # 后续所有操作都在此用户下进行妥善保管 session 文件go-cqhttp登录成功后会在其目录下生成session.token等文件。备份好这些文件下次更换服务器或重装时直接复制这些文件过去可以免去再次扫码登录的麻烦。配置访问令牌 (Access Token) 在生产环境中务必在go-cqhttp的config.yml中设置access-token并在云崽的qq.yaml中配置相同的token。这可以防止未授权的应用调用你的机器人API。# go-cqhttp config.yml default-middlewares: access-token: YourStrongTokenHere123!限制 go-cqhttp 的监听地址 在config.yml的servers.http部分确保host是127.0.0.1本地回环而不是0.0.0.0所有接口。这样go-cqhttp的API端口5700就不会暴露在公网上。定期更新与维护定期执行git pull更新Yunzai-Bot和插件。关注go-cqhttp的Release页面及时更新以修复协议漏洞。使用pnpm update或npm update更新Node.js依赖需谨慎可能引入不兼容。监控资源使用 使用pm2 monit或简单的crontab脚本监控机器人的CPU和内存占用。如果发现内存泄漏占用持续增长需要排查问题插件或考虑定时重启。遵守平台规则合理使用 明确了解使用QQ机器人的风险。避免高频发送消息、加入过多群聊、发布违规内容等行为以防账号被限制。使用机器人应以辅助管理和娱乐为主。至此一个部署在云服务器上的、功能可扩展的QQ云崽机器人已经搭建完成。从环境准备、核心组件部署、插件安装到故障排查和优化建议我们完成了一个完整的闭环。这套架构不仅适用于云崽其原理go-cqhttp 机器人框架也适用于其他基于QQ协议的机器人项目。