安装云崽机器人

本教程适配 CentOS 7/8、Ubuntu 20.04/22.04 主流 Linux 服务器，部署最新版 Miao-Yunzai（云崽v3）原神QQ机器人，全程手动纯净部署，无一键脚本捆绑，包含环境配置、源码部署、登录使用、后台常驻、开机自启、报错修复，新手可直接照搬操作。

核心环境要求：Node.js ≥16.x、Redis 数据库、Git、Chromium（图片渲染依赖）

一、前期准备

1. 一台可联网的 Linux 服务器（国内服务器无需特殊网络，境外服务器直接使用）

2. 服务器开放 22端口（SSH连接），无需额外开放其他端口

3. 拥有服务器 root 或管理员权限账号

4. 准备一个可正常登录的 QQ 账号（建议小号，避免主号风控）

二、系统依赖更新与基础组件安装

根据你的系统选择对应命令，更新系统依赖并安装必备工具

1. Ubuntu/Debian 系统

sudo apt update && sudo apt upgrade -y
sudo apt install -y git wget curl gnupg2 chromium-browser

2. CentOS 7/8 系统

yum update -y
yum install -y git wget curl chromium

作用：安装 Git（拉取源码）、curl/wget（下载工具）、chromium（云崽图片渲染核心依赖，无此组件会报错无法生成图片）

三、安装 Node.js 18.x（稳定适配版本）

云崽 v3 强制要求 Node.js 16 及以上，推荐安装 18.x 长期稳定版，兼容性最佳

# 导入Node.js官方源
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
# Ubuntu安装
apt install -y nodejs
# CentOS安装
yum install -y nodejs

安装完成后验证版本，输出版本号即成功

node -v
npm -v

全局安装 pnpm 包管理器（云崽推荐依赖工具）

npm install -g pnpm

四、安装 Redis 数据库

云崽依赖 Redis 缓存数据、保存插件配置、签到数据，必须安装且开机自启

1. Ubuntu 安装 Redis

sudo apt install -y redis-server
# 设置开机自启并启动
systemctl enable --now redis-server

2. CentOS 安装 Redis

yum install -y redis
systemctl enable --now redis

验证 Redis 运行状态，显示 active(running) 即为正常

systemctl status redis

五、拉取云崽源码并安装依赖

统一使用 Gitee 镜像源码（国内服务器下载速度快、无超时报错）

# 拉取云崽源码
git clone https://gitee.com/yoimiya-kokomi/Miao-Yunzai.git
# 进入项目目录
cd Miao-Yunzai
# 安装项目全部依赖
pnpm install

等待依赖安装完成（约1-3分钟），无红色报错、终端停留在新命令行即为成功

六、首次启动机器人并登录QQ

1. 启动程序

node app

2. 登录方式（二选一，优先推荐扫码）

方式1：扫码登录（推荐，风控最低）

终端会输出二维码链接，复制链接到浏览器打开，使用机器人QQ扫码登录即可

方式2：账号密码+滑块验证

输入QQ账号、密码后触发滑块验证，可使用滑动验证工具辅助通过，避免登录失败

登录成功标志：终端提示「登录成功，当前账号：XXX」，无报错信息

登录完成后按 Ctrl+C 临时关闭程序，配置后台常驻

七、配置后台永久运行（PM2 守护进程）

直接运行 node app 关闭终端就会掉线，使用 PM2 实现后台常驻、意外掉线自动重启

1. 安装 PM2 进程管理器

npm install pm2 -g

2. PM2 启动云崽

# 在Miao-Yunzai目录下执行
pm2 start app.js --name yunzai

3. 设置开机自启

# 生成开机自启配置
pm2 startup
# 按照终端提示执行对应命令（不同系统命令不同，直接复制粘贴）
# 保存当前进程列表
pm2 save

4. 常用 PM2 管理命令

# 查看运行状态
pm2 status
# 查看实时日志
pm2 logs yunzai
# 重启机器人
pm2 restart yunzai
# 停止机器人
pm2 stop yunzai

八、Chromium 路径报错修复（高频问题）

部分服务器会出现「未找到Chromium」「图片渲染失败」报错，手动配置浏览器路径即可解决

# 查找Chromium安装路径
which chromium
# Ubuntu系统返回：/usr/bin/chromium-browser
# CentOS系统返回：/usr/bin/chromium

编辑云崽配置文件，填入对应路径

vim ./config/config/bot.yaml

找到 chromium_path 配置项，删除注释，粘贴上面查询到的路径，按 ESC，输入 :wq 保存退出，重启云崽即可生效

九、插件安装与更新

1. 更新云崽本体

cd ~/Miao-Yunzai
git pull
pnpm install
pm2 restart yunzai

2. 安装第三方插件

将插件文件夹放入 Miao-Yunzai/plugins 目录，重启机器人即可自动加载

pm2 restart yunzai

十、常见报错解决方案

1. Redis 连接失败

原因：Redis未启动或未开机自启

解决：执行 systemctl restart redis重启服务，重新设置开机自启

2. 依赖安装失败、node版本过低

解决：卸载旧版本Node.js，重新安装18.x版本，重新执行 pnpm install

3. QQ登录风控、频繁掉线

解决：使用小号登录，优先扫码登录，避免频繁重启机器人，关闭服务器IP多设备登录

4. 无法生成图片、空白图

解决：确认Chromium安装成功，正确配置bot.yaml中的浏览器路径，重启程序

十一、机器人使用说明

1. 机器人登录成功后，将QQ号拉入QQ群，即可正常使用

2. 发送 #帮助 查看全部功能指令

3. 发送 #更新 在线更新本体，发送 #插件更新 更新全部插件

4. 管理员可通过后台日志查看机器人运行状态，排查异常问题