Hugging Face's logo

Spaces:
GGSheng
/
test
Running

App Files Community
test / README_zh.md
GGSheng's picture
GGSheng
feat: deploy Gemma 4 to hf space
55ba4a3 verified
preview code
|
raw
history blame contribute delete
15.2 kB
metadata 
title: OpenClaw HF Space
emoji: 🦞
colorFrom: blue
colorTo: indigo
sdk: docker
sdk_version: 29.0.4
app_port: 7860
app_file: mian.py
pinned: false

OpenClaw HF Space 部署工具（中文版）

Languages: English · 简体中文 部署指南: English · 中文部署指南

本项目提供在 Hugging Face Space 上部署 OpenClaw 的完整解决方案。

功能特性

  • 基于 ubuntu:24.04 构建 OpenClaw 容器镜像
  • 默认通过 BT Panel（宝塔面板）管理服务，端口 7860
  • OpenClaw Gateway 运行在独立端口 18789（默认）
  • 默认使用第三方 OpenAI 兼容接口（base_url + api_key），通过环境变量注入
  • OpenClaw 配置和工作目录存储在 /root/.openclaw
  • 启动时自动从 Hugging Face Dataset 恢复状态
  • 通过 cron 定时备份 OpenClaw 数据到 Hugging Face Dataset
  • 增量备份 + 动态备份策略 + AES-256-CBC 加密 + 大文件分卷
  • 备份看门狗（兜底保障，cron 失效时自动触发备份）
  • SSH 服务自动守护（看门狗监控自愈 + 自动生成主机密钥）
  • CCMR（Claude Code Model Router）支持，自动配置 10 个平台 API Key
  • 多数据集恢复支持（可从不同 Dataset 恢复）
  • 预装工具：python3、uv、vim、neovim、chromium（Chrome for Testing）、gh、hf、opencode、codex、claude（Claude Code CLI）、@larksuite/cli、sshx
  • 内置 DDNS-GO，支持动态 DNS 更新（非关键功能，安装失败不影响构建）

项目结构

  • Dockerfile: Space 运行时镜像
  • scripts/openclaw-entrypoint.sh: 主启动流程（恢复、配置生成、cron 设置、gateway 启动）
  • scripts/hf-entrypoint.sh: HF Spaces 容器入口（PID 1，管理 supervisord + SSH + PM2 + BT Panel）
  • scripts/supervisord.conf: Supervisord 配置，管理 cron、backup-watchdog、openclaw-gateway、ccmr-gateway
  • openclaw_hf/backup.py: 备份/恢复实现（全量/增量、加密、分卷、动态策略、断点续传）
  • scripts/openclaw-backup-cron.sh: Cron 备份任务入口
  • scripts/openclaw-backup-watchdog.sh: 备份看门狗，兜底保障自动触发备份
  • scripts/openclaw-backup-health.sh: 备份健康检查与自动修复
  • scripts/openclaw-restore.sh: 启动恢复入口
  • scripts/openclaw-gateway-ctl: Gateway 进程管理（start/stop/restart/reload）
  • scripts/openclaw-env-sync.sh: 从 HF API 同步环境变量
  • scripts/update-env-from-secrets.sh: 从 HF API 获取最新环境变量
  • scripts/bt_install_panel_custom.sh: BT Panel 安装脚本
  • scripts/bootstrap-hf.sh: 交互式引导脚本（macOS/Linux）
  • scripts/bootstrap-hf.ps1: 交互式引导脚本（Windows PowerShell）
  • scripts/rebuild-space.sh: 强制推送最新代码到 Space 并触发重建
  • scripts/delete-backups.sh: 批量清理 Dataset 中的旧备份
  • scripts/delete-hf.py: HF 资源删除工具（Space/Dataset/文件/存储）
  • scripts/find-largest-backup.py: 查找 Dataset 中最佳备份
  • scripts/ssh_service_watchdog.sh: SSH 服务看门狗（进程监控 + 自动恢复）
  • scripts/check_ssh_health.sh: SSH 健康检查脚本（Docker HEALTHCHECK 使用）
  • scripts/ssh-agent-autostart.sh: SSH Agent 自动启动和加载密钥
  • scripts/optimize_ssh.sh: SSH 配置优化
  • scripts/save-env.sh: 保存环境变量到 /etc/profile.d
  • scripts/hf-storage.sh / scripts/hf-storage.py: HuggingFace 公共存储工具
  • scripts/ccmr-setup.sh: CCMR 配置生成脚本
  • scripts/ccmr-wrapper.sh: CCMR Supervisor 启动包装（文件热加载 + 崩溃恢复）
  • scripts/server.js: PID 1 存活 HTTP 服务
  • pm2/ecosystem.config.js: PM2 配置文件（可选扩展）
  • tests/test_backup.py: 备份模块单元测试
  • tests/test_entrypoint_config.py: Gateway 配置生成行为单元测试

必填变量（Space Settings）

在 Hugging Face Space 的 Settings -> Variables and secrets 中配置：

  • 变量: OPENCLAW_BACKUP_DATASET_REPO: 备份目标 Dataset，格式 username/dataset-name
  • 密钥: HF_TOKEN: 用于向 Dataset 写入备份（必须对该 Dataset 有写权限）
  • 密钥: OPENCLAW_GATEWAY_TOKEN: Gateway 令牌（建议填写；留空则自动生成 32 位随机值）
  • 密钥: OPENCLAW_GATEWAY_PASSWORD: Gateway 密码（可选；留空则自动生成 16 位随机值）

使用 ./scripts/bootstrap-hf.sh 或 ./scripts/bootstrap-hf.ps1 时，这些值会自动配置到目标 Space。

BT Panel 变量

  • BT_PANEL_PORT（默认: 7860）: BT Panel 监听端口
  • BT_PANEL_USERNAME（默认: btadmin）: BT Panel 用户名，必须以小写字母开头，只能包含小写字母和数字，长度 3-32 位
  • BT_PANEL_PASSWORD: BT Panel 密码，留空则自动生成
  • BT_PANEL_SAFE_PATH: BT Panel 安全入口路径（默认: lauer3912）
  • BT_PANEL_TIMEZONE（默认: Asia/Shanghai）: BT Panel 时区

SSH 服务

容器内置 SSH 服务守护体系，确保 SSH 持续可用：

  • 自动启动: 入口点自动生成主机密钥、清理残留 PID、启动 sshd
  • SSH 看门狗 (ssh_service_watchdog.sh): 每 30 秒监控 sshd 进程，异常时自动恢复
  • 多级修复: 配置损坏→使用备份配置→生成最小配置→自动重装 openssh-server
  • 指数退避: 连续失败时逐步增加等待时间，避免频繁重试
  • 健康检查 (check_ssh_health.sh): 配合 Docker HEALTHCHECK 使用
  • SSH Agent 自动加载: 自动启动 ssh-agent 并加载 /root/.ssh/ 下的私钥
  • ROOT 密码: 通过 ROOT_PASSWORD 环境变量设置

CCMR（Claude Code Model Router）

集成 CCMR 网关，通过 Supervisor 管理，支持热加载：

  • 自动配置: 设置 CCMR_*_API_KEY 环境变量即可启用
  • 10 个 API Key 支持: DeepSeek、通义千问、Kimi、智谱 GLM、MiniMax（CN/Global）、MiMo（SGP/CN/AMS/PAYG）
  • 文件热加载: 编辑 /root/.env.d/ccmr.env 后立即生效，无需重启
  • 崩溃恢复: Supervisor 自动重启 CCMR 进程

可选 LLM 变量（全有或全无）

只有在需要 OpenClaw 预配置自定义第三方模型时才设置这三个：

  • 变量: OPENCLAW_LLM_BASE_URL: 第三方 base URL（如 OpenAI 兼容的 /v1）
  • 变量: OPENCLAW_LLM_MODEL: 第三方模型 ID
  • 密钥: OPENCLAW_LLM_API_KEY: 第三方 API key

三者任一缺失则跳过自定义模型生成，此时仍可在容器内通过 sshx 配置 LLM。

常用可选变量

变量 默认值 说明
OPENCLAW_VERSION latest OpenClaw 版本，用于 Docker 安装步骤
OPENCLAW_GATEWAY_PORT 18789 Gateway 监听端口（避免与 BT Panel 的 7860 冲突）
OPENCLAW_GATEWAY_BIND lan Gateway 绑定方式（lan/local）
OPENCLAW_STATE_DIR /root/.openclaw OpenClaw 状态目录
OPENCLAW_USER root Gateway 和 cron 任务的运行时用户
OPENCLAW_GROUP root 运行时用户组
OPENCLAW_CONFIG_PATH /root/.openclaw/openclaw.json Gateway 配置文件路径
OPENCLAW_WORKSPACE_DIR /root/.openclaw/workspace 工作目录
OPENCLAW_BACKUP_CRON */10 * * * * 备份 cron 表达式（默认每 10 分钟）
OPENCLAW_BACKUP_SOURCE_DIR /root/.openclaw 备份/恢复基础目录
OPENCLAW_BACKUP_ROOT_*_DIR 各有默认值 额外备份目录（config、codex、claude、agents、ssh、npm、lark-cli）
OPENCLAW_BACKUP_PATH_PREFIX backups 备份路径前缀
OPENCLAW_BACKUP_KEEP_COUNT 24 保留的最新备份数量
OPENCLAW_BACKUP_ENCRYPTION_ENABLED false 启用 AES-256-CBC 加密备份
OPENCLAW_BACKUP_SPLIT_SIZE 500M 大文件分卷大小
OPENCLAW_INCREMENTAL_BACKUP true 启用增量备份
OPENCLAW_DYNAMIC_BACKUP true 启用动态备份策略
OPENCLAW_FULL_BACKUP_INTERVAL_HOURS 1 强制全量备份间隔
OPENCLAW_MAX_INCREMENTAL_BACKUPS 15 增量备份次数上限
OPENCLAW_RESTORE_TIMEOUT 5400 恢复超时（秒，默认 90 分钟）
WATCHDOG_INTERVAL 600 备份看门狗检查间隔（秒）
MAX_BACKUP_AGE_MINUTES 30 备份最大间隔（分钟）
FORCE_BACKUP_INTERVAL 14400 强制备份间隔（秒）
OPENCLAW_SSHX_AUTO_START false 设为 true 启动时自动后台运行 sshx
OPENCLAW_GATEWAY_AUTH_MODE token 认证模式（token/password）
OPENCLAW_GATEWAY_CONTROLUI_ALLOW_INSECURE_AUTH false 允许不安全认证
OPENCLAW_GATEWAY_CONTROLUI_DANGEROUSLY_DISABLE_DEVICE_AUTH false 禁用设备配对（强烈不建议在公网开启）
ROOT_PASSWORD lauer3912 SSH root 用户密码
CCMR_ENABLED false 启用 Claude Code Model Router
CCMR_PORT 8080 CCMR 网关端口

快速部署

从仓库根目录运行交互式引导脚本：

./scripts/bootstrap-hf.sh

powershell -ExecutionPolicy ByPass -File .\scripts\bootstrap-hf.ps1

bootstrap-hf.sh / bootstrap-hf.ps1 会执行以下操作：

  1. 检查/安装 hf CLI
  2. 解析 HF 认证状态（未登录则提示输入 HF_TOKEN 并登录；已登录则询问是否使用当前用户）
  3. 询问 space_name、dataset_name、OPENCLAW_VERSION、Gateway 令牌/密码及可选 LLM 配置
  4. 自动生成 OPENCLAW_GATEWAY_TOKEN（32 位）和 OPENCLAW_GATEWAY_PASSWORD（16 位）
  5. 创建私有 Space + Dataset 并上传仓库
  6. 自动配置 Space 的 Variables and secrets
  7. 显示部署设置并要求确认
  8. 输出 Hugging Face Space 页面地址、应用地址和 /healthz 健康检查地址

如自动生成了令牌/密码，脚本结束时会自动显示。

Hugging Face Space 保活策略

Space 保活策略取决于硬件套餐：

  • 免费 cpu-basic：Space 在不活跃后进入休眠（约 48 小时），无法配置为永久运行
  • 付费硬件：Space 默认持续运行。在 Settings -> Hardware 中将 Sleep time 设为 Never 可实现真正的 24/7 可用性
  • 付费硬件节能模式：设置自定义 Sleep time（如 3600 秒），实现自动休眠和自动唤醒

Space URL 构成：

  • Space Repo ID 格式: <owner>/<space_name>（示例: username/openclaw-hf）
  • 公开运行时地址: https://<owner>-<space_name>.hf.space
  • 健康检查地址: https://<owner>-<space_name>.hf.space/healthz

定时健康检查保持活跃：

*/12 * * * * HF_TOKEN=hf_xxx /path/to/repo/scripts/check-space-health.sh username/openclaw-hf >/dev/null || true

注意：

  • 私有 Space 的 https://<owner>-<space_name>.hf.space/healthz 返回 Hub 404，这是正常的访问控制行为
  • 私有 Space 请求需要包含 Authorization: Bearer <HF_TOKEN>

备份/恢复流程

恢复流程

启动时从 Dataset 自动恢复，容器重启或重建时必定执行：

  • openclaw-state -> OPENCLAW_BACKUP_SOURCE_DIR（默认 /root/.openclaw）
  • root-config -> OPENCLAW_BACKUP_ROOT_CONFIG_DIR（默认 /root/.config）
  • root-codex -> OPENCLAW_BACKUP_ROOT_CODEX_DIR（默认 /root/.codex）
  • root-claude -> OPENCLAW_BACKUP_ROOT_CLAUDE_DIR（默认 /root/.claude）
  • root-agents -> OPENCLAW_BACKUP_ROOT_AGENTS_DIR（默认 /root/.agents）
  • root-ssh -> OPENCLAW_BACKUP_ROOT_SSH_DIR（默认 /root/.ssh）
  • root-env -> OPENCLAW_BACKUP_ROOT_ENV_DIR（默认 /root/.env.d）
  • root-npm -> OPENCLAW_BACKUP_ROOT_NPM_DIR（默认 /root/.npm）
  • root-lark-cli -> OPENCLAW_BACKUP_ROOT_LARK_CLI_DIR（默认 /root/.lark-cli）

支持多数据集恢复：设置 OPENCLAW_RESTORE_DATASET_REPO 可以从不同 Dataset 恢复。

备份流程

  • 定时备份：根据 OPENCLAW_BACKUP_CRON（默认每 10 分钟）执行
  • 增量备份（默认开启）：全量备份后只备份变化文件，大幅减少数据量
  • 动态备份策略（默认开启）：根据文件大小和变化率自动调整压缩级别和分卷策略
  • 手动强制全备份：python3 backup.py backup --force-full 可跳过增量检查强制执行全量备份
  • AES-256-CBC 加密：可选开启，加密后的备份可安全存储在公开 Dataset
  • 大文件分卷：默认 500MB 分卷，避免单文件过大导致上传失败
  • 断点续传：上传过程中创建 checkpoint 文件，中断后可恢复
  • 关机备份：容器收到停止信号时，执行最后一次备份后再退出
  • 保留策略：上传后只保留最新的 OPENCLAW_BACKUP_KEEP_COUNT（默认 24 个）带时间戳的备份归档，自动删除更旧的

备份看门狗

openclaw-backup-watchdog.sh 作为备份系统的兜底保障：

  • 即使 cron 失效，看门狗也会在超过 MAX_BACKUP_AGE_MINUTES（默认 30 分钟）无备份时自动触发
  • 每 FORCE_BACKUP_INTERVAL（默认 4 小时）强制执行一次备份
  • 使用文件锁防止并发执行
  • 连续失败时自动退避

在容器内使用 sshx

sshx 已预装在镜像中。

  1. 通过环境变量自动启动：

    OPENCLAW_SSHX_AUTO_START=true

    启用后入口脚本会在后台启动 sshx，输出直接发送到容器 stdout/stderr

  2. 在容器内手动启动：

    sshx

  3. 通过 OpenClaw 终端/工具启动：

    nohup sshx >/proc/1/fd/1 2>/proc/1/fd/2 &

  4. 使用完毕后及时关闭：

    pgrep -fa sshx
pkill -TERM -f '(^|/)sshx($| )'

本地测试 

python3 -m unittest discover -s tests -p 'test_*.py'

CI/CD

向 main 分支提交 Pull Request 后，GitHub Actions CI 会自动运行（.github/workflows/pr-ci.yml）：

  • 单元测试：python3 -m unittest discover -s tests -p 'test_*.py'
  • Docker 镜像构建：docker build（通过 Buildx），使用 OPENCLAW_VERSION=latest

架构说明

容器启动顺序（hf-entrypoint.sh 作为 PID 1）：

PID 1 (node hf-server.js)
├── supervisord (后台)
│   ├── cron
│   ├── backup-watchdog
│   ├── openclaw-gateway (via openclaw-entrypoint.sh)
│   │   └── openclaw (gateway 进程管理器)
│   └── ccmr-gateway (via ccmr-wrapper.sh, 启用时)
├── sshd
├── ssh_service_watchdog.sh (SSH 看门狗)
├── PM2 (可选，ecosystem.config.js 有配置时)
└── BT Panel

进程管理使用 Supervisord 管理后台服务，原因：

  • Supervisord 是为"进程管理者"设计的，适合 PID 1 下运行
  • 信号传递正确，SIGTERM 能正确传递给子进程
  • 相比 PM2 更轻量，职责单一

关键启动步骤：

  1. supervisord 后台启动，管理 cron/backup-watchdog/openclaw-gateway/ccmr-gateway
  2. 生成 SSH 主机密钥，启动 sshd + SSH 看门狗
  3. 等待 openclaw-gateway 完成备份恢复
  4. 可选启动 PM2 管理附加进程
  5. 启动 BT Panel
  6. node hf-server.js 作为 PID 1 前台进程接管容器生命周期

License

MIT. See LICENSE.