在 Hugging Face Spaces 上免费部署 NapCat QQ 机器人框架

特性

特性 说明
完全免费 基于 HF Spaces 免费 CPU 实例
数据持久化 登录态自动备份到 HF Dataset，重启不丢失
自动保活 支持 GitHub Actions 定时 ping，防止 Space 休眠
分离备份 NapCat 配置、QQ 配置、插件分开备份，恢复更可靠

使用前须知

  • HF Spaces 服务器位于美国，QQ 登录存在异地风控风险
  • 首次登录需扫码，后续重启通过备份恢复 session
  • 仅适合个人学习或测试使用，生产环境建议使用国内服务器

准备工作

  • Hugging Face 账号
  • QQ 号码
  • GitHub 账号（可选，用于保活）

部署步骤

第一步：创建备份 Dataset

  1. HF 主页右上角头像 -> New Dataset
  2. 填写名称（如 napcat-backup），可见性选 Private
  3. 点击 Create
  4. 记录仓库名：你的用户名/napcat-backup

第二步：获取 HF Token

  1. HF 设置页 -> Access Tokens -> New token
  2. 权限选 Write
  3. 复制并保存 Token

第三步：创建 Space

  1. HF 主页 -> New Space
  2. SDK 选 Docker
  3. 可见性选 Public 或 Private
  4. 点击 Create

第四步：上传文件

将以下文件上传到你的 Space (要解压哈3个文件！）

https://pan.346247.xyz/file/AstrBot/napcat-on-huggingface-main.zip

部署步骤

第五步：配置环境变量

在 Space 的 Settings -> Variables and secrets 中添加必要的环境变量。

所有含敏感信息的变量务必设为 Secret。

变量名 类型 说明
HF_TOKEN Secret 第二步获取的 HF Token
DATASET_REPO Secret 备份仓库名，如 yourname/napcat-backup

连接地址

用途 地址
WebUI https://用户名-space名.hf.space
正向 WebSocket ws://用户名-space名.hf.space/3001/
HTTP 上报 http://用户名-space名.hf.space/5700/
调试 WebSocket ws://用户名-space名.hf.space/api/Debug/ws/

调试 WebSocket 说明

连接调试 WebSocket 需要附带临时 token：

ws://用户名-space名.hf.space/api/Debug/ws?token=xxxxxx

容器已内置保活进程，会在启动后自动获取 token 并维持连接，通常无需手动操作。

请在 WebUI 中访问实时调试（/webui/debug/ws），页面会自动显示当前 token 和完整连接地址。

配置保活

HF 免费 Space 超过 48 小时无访问会自动休眠。

你可以在这篇文章找到对应方法AstrBot配置指南 | min的小窝

备份说明

每次重启时自动从 HF Dataset 恢复，运行期间每 30 分钟自动备份一次。

文件 内容
napcat.zip NapCat 配置文件
qq.zip QQ 登录态、设备信息（已排除缓存）
plugins.zip NapCat 插件数据

常见问题

Q: 每次重启都需要重新扫码吗？

不需要。只要 QQ 没有踢掉设备，备份恢复后可直接复用 session。

Q: HF Space 会收费吗？

免费 CPU 实例完全免费，只有升级到 GPU 或付费 Persistent Storage 才会产生费用。本方案均不使用付费功能。

Q: 连接不稳定怎么办？

优先使用正向 WebSocket（/3001/），无法连接时可改用调试端口（/api/Debug/ws/）。

Q: QQ 登录被风控怎么办？

HF 服务器 IP 在美国，QQ 可能触发异地登录保护。建议使用小号，或换用国内服务器部署。