无服务器部署 AstrBot：Hugging Face 免费方案

第一步，建个 Space#

打开 https://huggingface.co/new-space，名字随便起，SDK 记得选 Docker，不想被别人看到就勾 Private。建好之后可以去 Settings 里看一眼，免费的 CPU 档有个自动休眠的选项。

第二步，把代码推上去#

如果你本地已经有这个仓库，不用 clone 过去再拷文件，直接加一个远端就能推：

1
git clone https://github.com/MoYangking/Astrbot-Napcat-huggingface.git
2
cd Astrbot-Napcat-huggingface
3

4
git remote add hf https://<你的HF用户名>:<HF_TOKEN>@huggingface.co/spaces/<用户名>/<Space名>
5
git push --force hf main

Token 在 https://huggingface.co/settings/tokens 生成，权限选 Write 就行。

推完之后去 Space 页面点 Build，第一次构建大概二十分钟到四十分钟，别急着刷新，等它自己跑完。

第三步，配置备份#

在 Space 的 Settings → Variables and secrets 里加两个变量：

前提是你得先在 GitHub 建一个空的 Private 仓库，比如叫 astrbot-backup，PAT 在 https://github.com/settings/tokens 生成，勾上 repo 权限。

填完之后 Space 会自动重启。Sync 守护进程会把 AstrBot/data/ 每三分钟往备份仓库推一次，先 pull 再 commit 再 push，两边不会打架。这一对变量不配也能跑，但容器一重启数据就没了，到时候懂的都懂。

第四步，第一次登录#

访问 https://<space名>.hf.space/，有几个入口：

• / 是 AstrBot 控制台。新版首次登录账号固定是 astrbot，密码是随机生成打印在日志里的，去运行日志里搜 Initial password 就能看到。
• /admin/ui/ 是路由管理，默认密码 admin，建议进去改掉。
• /webui/ 是 NapCat 的界面，个人 QQ 号扫码登录用的，只用腾讯官方机器人可以跳过。

第五步，防休眠#

免费档四十八小时没访问就休眠，所以要定时去”戳”它一下。在仓库里加个 workflow，GitHub Actions 会替你每天戳三次：

1
name: Keep HF Space Alive
2
on:
3
  schedule:
4
    - cron: "0 */8 * * *"
5
  workflow_dispatch:
6
jobs:
7
  ping:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - run: curl -sS -o /dev/null -H "Authorization: Bearer ${{ secrets.HF_TOKEN }}" https://<你的space名>.hf.space/

然后在仓库的 Settings → Secrets → Actions 里加一个 HF_TOKEN 就行。一天三次请求，Actions 的免费额度完全够用。

一些要提前知道的局限#

踩过的坑#

第一个是 FROM ubuntu:latest，六月份之后 latest 已经指向 26.04 了，OpenResty 的 apt 源还没跟上，构建直接 404 失败。改成 FROM ubuntu:24.04 就好了。

第二个是浏览器打开 404。Space 第一次启动会下载两百来兆的 AstrBot 前端资源，下载没完成之前 / 就是 404，等下载到 100% 刷新一下就好，不是坏了。

第三个是没配备份那一对变量的话，AstrBot 和 NapCat 会卡三十分钟起不来——Sync 守护进程拿不到配置会崩，标记文件永远不写，其他服务就干等超时。我给守护进程加了”没配置就直接放行”的处理，已经合到仓库里了。

总的来说，无服务器方案的核心矛盾就是拿在线率换零成本。这套路子数据有 GitHub 兜底，唯一的妥协是休眠后的冷启动，对个人机器人来说这个妥协还算能接受。