README.md

---
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](https://turso.tech/) 并创建一个新数据库 (如 `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](https://huggingface.co/)。
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 仓库。

如果您在本地：
```bash
# 克隆您的 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. 填入以下配置：

```yaml
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/` 目录中。