AstrBot+NapCat 部署到 Hugging Face Space 完整教程

📋 目录

准备工作
创建 Hugging Face Space
Dockerfile 配置
AstrBot 配置
NapCat 配置
测试验证

本文为AIGC！

1. 准备工作

你需要准备：

Hugging Face 账号
QQ 账号（机器人用）
NapCat 已经部署在某个地方（或另一个 HF Space）

2. 创建 Hugging Face Space

登录 Hugging Face
点击右上角 New Space
填写信息：

字段	值
Space Name	`astrbot`（自定义）
SDK	Docker
Space Hardware	CPU basic（免费）
Visibility	Public 或 Private

点击 Create Space

3. Dockerfile 配置

在 Space 的 Files 页面，创建 Dockerfile：

FROM soulter/astrbot:latest

USER root

# 安装 nginx
RUN apt-get update && apt-get install -y nginx && rm -rf /var/lib/apt/lists/*

# 配置 nginx（路径转发：/ws → 6199，其他 → 6185）
RUN echo 'server { \
    listen 7860; \
    client_max_body_size 50M; \
    \
    location /health { \
        return 200 "OK\n"; \
        add_header Content-Type text/plain; \
    } \
    \
    location /ws { \
        proxy_pass http://127.0.0.1:6199; \
        proxy_http_version 1.1; \
        proxy_set_header Upgrade $http_upgrade; \
        proxy_set_header Connection "upgrade"; \
        proxy_set_header Host $host; \
        proxy_read_timeout 86400; \
    } \
    \
    location / { \
        proxy_pass http://127.0.0.1:6185; \
        proxy_set_header Host $host; \
        proxy_set_header X-Real-IP $remote_addr; \
    } \
}' > /etc/nginx/sites-enabled/default

# 启动脚本
RUN echo '#!/bin/bash\n\
nginx &\n\
cd /AstrBot && python main.py\n\
' > /entrypoint.sh && chmod +x /entrypoint.sh

EXPOSE 7860

ENTRYPOINT ["/entrypoint.sh"]

点击 Commit 保存，Space 会自动构建。

4. AstrBot 配置

4.1 首次访问

Space 构建完成后，点击 App 标签页，访问 AstrBot WebUI：

1	https://你的用户名-你的space名.hf.space

默认用户名和密码都是 astrbot

4.2 配置 LLM

进入 LLM 设置 → 提供商 → 添加你的 API Key（如 DeepSeek、OpenAI、SiliconFlow 等）

4.3 配置 OneBot 适配器

进入 机器人 → 创建机器人 → 选择 OneBot v11，填写：

字段	值
机器人名称	`NapCat`
反向 WebSocket 主机	`0.0.0.0`
反向 WebSocket 端口	`6199`
反向 WebSocket Token	自定义（如`M7zNCHAd5FjonZ8y`）

点击保存

5. NapCat 配置

5.1 在 NapCat WebUI 中添加 WebSocket 客户端

登录你的 NapCat WebUI，进入 网络配置 → 新建 → WebSocket 客户端：

字段	值
名称	`AstrBot`
URL	`wss://你的用户名-你的space名.hf.space/ws`
Token	与 AstrBot 填写的 Token 一致
消息格式	`Array`
心跳间隔	`30000`
重连间隔	`30000`

5.2 启用

勾选 保存时启用，点击保存。

6. 测试验证

6.1 检查连接状态

NapCat 日志 应该显示：

1	[INFO] [OneBot] [WebSocket Client] 反向WebSocket (wss://xxx.hf.space/ws) 已启动

AstrBot 日志 应该显示：

1	[INFO] [aiocqhttp] OneBot v11 适配器已连接

6.2 测试消息

用另一个 QQ 给你的机器人 QQ 发送 你好，机器人应该会回复喵。

如果没回复，发送 /llm 检查 LLM 是否开启。

📊 架构图

┌─────────────────────────────────────────────────────────┐
│                  Hugging Face Space                      │
│  ┌─────────────────────────────────────────────────┐   │
│  │                    Nginx (7860)                  │   │
│  │  /     → 127.0.0.1:6185 (WebUI)                 │   │
│  │  /ws   → 127.0.0.1:6199 (WebSocket)             │   │
│  └─────────────────────────────────────────────────┘   │
│                           │                             │
│                           ▼                             │
│  ┌─────────────────────────────────────────────────┐   │
│  │                    AstrBot                       │   │
│  │  WebUI: 0.0.0.0:6185                            │   │
│  │  WS:    0.0.0.0:6199                            │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ▲
                           │ wss://xxx.hf.space/ws
                           │
┌─────────────────────────────────────────────────────────┐
│                      NapCat                              │
│                 (任意地方部署)                            │
└─────────────────────────────────────────────────────────┘