README.md

metadata

title: OpenSpace
emoji: 💻
colorFrom: yellow
colorTo: blue
sdk: docker
pinned: false
license: mit

OpenSpace 后端部署指南 (HuggingFace Space)

本目录 (Backend_HF) 包含了 OpenSpace 的核心执行引擎、Skill 进化逻辑以及 API 服务。它被设计为通过 Docker 容器部署在 HuggingFace Space 上，并使用 Turso 作为 Serverless 云端数据库以保证数据持久化。

🚀 部署到 HuggingFace Space

1. 准备工作

在部署后端之前，您需要完成以下服务的配置：

• Turso 数据库：
  1. 登录 Turso 并创建一个新数据库 (如 openspace-db)。
  2. 获取连接 URL (如 libsql://openspace-db-yourusername.turso.io)。
  3. 生成 Auth Token (通过 turso db tokens create openspace-db)。
• 大语言模型 API Key：OpenSpace 的进化引擎依赖 LLM（如 OpenAI、Anthropic 或其他兼容模型）。

2. 在 HuggingFace 创建 Space

1. 登录 HuggingFace。
2. 点击右上角头像，选择 **"New Space"**。
3. 填写 Space Name (例如 openspace-backend)。
4. License: 建议选择 MIT。
5. Select the Space SDK: 必须选择 Docker，然后选择 Blank 模板。
6. Space Hardware: 免费的 CPU basic (2 vCPU, 16GB RAM) 已经足够运行此后端服务。
7. Visibility (可见性):
   • **建议选择 Public (公开)**：如果您的前端部署在 EdgeOne 等外部平台，必须将 Space 设为 Public，否则前端的跨域 API 请求将被 HuggingFace 的鉴权层拦截拦截导致无法访问。
   • (注：虽然是 Public，但由于您的核心数据在外部的 Turso 数据库中，且您的前端有 Clerk 白名单保护，安全性是有保障的。为了防止他人滥刷 API，建议在 dashboard_server.py 中增加简单的 API_KEY 校验。)
8. 创建 Space。

3. 配置环境变量 (Secrets)

在新创建的 Space 页面，进入 Settings -> Variables and secrets。添加以下 Secrets (注意不是 Variables，因为这些是敏感信息)：

Secret Name	示例值	说明
TURSO_DATABASE_URL	libsql://your-db.turso.io	必填。Turso 数据库的连接地址。
TURSO_AUTH_TOKEN	ey...	必填。Turso 数据库的访问令牌。
OPENSPACE_API_KEY	your_secret_api_key_here	必填。用于保护您的 API 不被恶意调用。前端也需要配置此 Key。
OPENAI_API_KEY	sk-...	（根据需要）您使用的大语言模型的 API Key。支持 ANTHROPIC_API_KEY 等其他受 LiteLLM 支持的密钥。
PORT	7860	必填。HuggingFace Docker 默认暴露端口为 7860，请勿更改此值。

4. 推送代码触发部署

将此 Backend_HF 目录中的所有文件直接推送到您的 HuggingFace Space 仓库。

如果您在本地：

# 克隆您的 HF Space 仓库
git clone https://huggingface.co/spaces/your-username/openspace-backend

# 将 Backend_HF 里的文件复制进去
cp -r /path/to/Backend_HF/* openspace-backend/

# 提交并推送
cd openspace-backend
git add .
git commit -m "Deploy OpenSpace backend"
git push

推送完成后，HuggingFace 会自动读取根目录下的 Dockerfile，构建镜像并启动服务。当状态变为 Running 时，您的后端就部署成功了。

---

⏰ 防止休眠与自动备份 (GitHub Actions)

HuggingFace 的免费 Space 如果长时间无人访问，会自动进入 Sleeping 状态。同时，Turso 的免费数据库如果 10 天不活跃也会被深度归档。

为了保持服务 24/7 在线并定期备份高价值数据，强烈建议在您的 GitHub 仓库（存放本项目的私有仓库）中配置以下 GitHub Action：

1. 在您的 GitHub 仓库中创建文件 .github/workflows/keepalive_and_backup.yml。
2. 填入以下配置：

name: OpenSpace Sync & KeepAlive

on:
  schedule:
    - cron: '0 0,12 * * *' # 每天 UTC 0点和12点触发
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          
      - name: Install Dependencies
        run: pip install libsql-experimental
      
      - name: Ping HuggingFace Space
        # 将这里的 URL 替换为您自己的 HF Space 的实际域名
        run: curl -s -o /dev/null -w "%{http_code}" https://your-username-openspace-backend.hf.space/api/v1/health
        
      - name: Backup Core Data from Turso
        env:
          TURSO_DATABASE_URL: ${{ secrets.TURSO_DATABASE_URL }}
          TURSO_AUTH_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN }}
        run: |
          python -c '
          import os, json, libsql_experimental as sqlite3
          conn = sqlite3.connect(os.environ["TURSO_DATABASE_URL"], auth_token=os.environ["TURSO_AUTH_TOKEN"])
          cursor = conn.cursor()
          # Handle column mapping manually since libsql_experimental may not support row_factory
          def fetch_dicts(cur, query):
              cur.execute(query)
              cols = [c[0] for c in cur.description]
              return [dict(zip(cols, row)) for row in cur.fetchall()]
          records = fetch_dicts(cursor, "SELECT skill_id, name, description, category, total_selections, total_applied, total_completions FROM skill_records")
          lineage = fetch_dicts(cursor, "SELECT * FROM skill_lineage_parents")
          os.makedirs("backups", exist_ok=True)
          json.dump(records, open("backups/skill_records.json", "w"), ensure_ascii=False, indent=2)
          json.dump(lineage, open("backups/skill_lineage.json", "w"), ensure_ascii=False, indent=2)
          '
          
      - name: Commit and Push Backups
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git add backups/
          git diff --quiet && git diff --staged --quiet || (git commit -m "Auto-backup: Turso Core DB" && git push)

3. 在该 GitHub 仓库的 Settings -> Secrets and variables -> Actions 中，添加 TURSO_DATABASE_URL 和 TURSO_AUTH_TOKEN。

这样，GitHub Action 每天会自动访问您的 HF Space 防止其休眠，并将 Turso 中最有价值的技能树和元数据备份回 GitHub 的 backups/ 目录中。