在 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_TOKENSecret第二步获取的 HF Token
DATASET_REPOSecret备份仓库名，如 yourname/napcat-backup

连接地址

用途地址
WebUIhttps://用户名-space名.hf.space
正向 WebSocketws://用户名-space名.hf.space/3001/
HTTP 上报http://用户名-space名.hf.space/5700/
调试 WebSocketws://用户名-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.zipNapCat 配置文件
qq.zipQQ 登录态、设备信息（已排除缓存）
plugins.zipNapCat 插件数据

常见问题

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

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

Q: HF Space 会收费吗？

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

Q: 连接不稳定怎么办？

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

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

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