Spaces:
Running
Running
| title: VPS Linux | |
| emoji: 🐨 | |
| colorFrom: red | |
| colorTo: green | |
| sdk: docker | |
| pinned: false | |
| license: mit | |
| # Simplified Linux VPS on Hugging Face Spaces | |
| 这是一个用于在 Hugging Face Spaces 上运行简化版 Linux VPS 的配置模板。它基于轻量级的 Debian Bookworm Slim，预装了基本的开发工具和 `ttyd` 网页终端，允许你在浏览器中直接访问命令行。 | |
| 此环境配置了 `sudo` 权限，方便你在运行时安装所需的软件（如 OpenClaw）。 | |
| **新特性：采用 Nginx + oauth2-proxy 架构，支持稳定的 GitHub/Google OAuth 登录与 WebAssembly 游戏预览。** | |
| ## 🚀 快速开始 | |
| ### 1. 创建 Hugging Face Space | |
| 1. 登录 Hugging Face。 | |
| 2. 点击右上角的头像 -> **New Space**。 | |
| 3. 输入 Space 名称（例如 `my-linux-vps`）。 | |
| 4. **Select the Space SDK**: 选择 **Docker**。 | |
| 5. **Docker Template**: 选择 **Blank**。 | |
| 6. 点击 **Create Space**。 | |
| ### 2. 上传文件 | |
| 将本仓库中的所有文件（`Dockerfile`, `README.md`, `start.sh`, `nginx.conf`, `oauth2-proxy.cfg`, `build_wasm.sh`）上传到你的 Space 仓库中。 | |
| ### 3. 配置鉴权环境变量 (重要!) | |
| 在 Space 的 **Settings** -> **Variables and secrets** 中添加以下环境变量： | |
| | 变量名 | 描述 | 示例 | | |
| |--------|------|------| | |
| | `ALLOWED_USERS` | **必填**。允许登录的 GitHub 用户名或 Email，逗号分隔。 | `yourgithubuser,your@email.com` | | |
| | `OAUTH2_PROXY_CLIENT_ID` | OAuth Client ID (GitHub 或 Google) | `Ov23li...` | | |
| | `OAUTH2_PROXY_CLIENT_SECRET` | OAuth Client Secret | `a1b2c3...` | | |
| | `OAUTH2_PROXY_COOKIE_SECRET` | Cookie 加密密钥 (16/24/32字节) | `python3 -c 'import os,base64; print(base64.b64encode(os.urandom(16)).decode())'` 生成一个 | | |
| **回调地址配置**: | |
| * GitHub App Callback URL: `https://<你的Space地址>/oauth2/callback` | |
| * Google Client Redirect URI: `https://<你的Space地址>/oauth2/callback` | |
| ### 4. 访问 VPS | |
| 配置好环境变量后，Space 会自动重启。 | |
| 点击 **App** 标签页，你会看到 GitHub/Google 登录页面。登录成功后即可进入终端。 | |
| ## 🛠️ 功能特性 | |
| - **OAuth 鉴权**: 使用 oauth2-proxy，安全稳定，支持 Session 管理。 | |
| - **白名单机制**: 仅允许 `ALLOWED_USERS` 中的用户登录，拒绝陌生人访问。 | |
| - **Nginx 反代**: 高性能反向代理，处理静态文件和 WebSocket。 | |
| - **Web 终端**: 访问根路径 `/`，使用 `ttyd` 管理 VPS。 | |
| - **WASM 游戏预览**: 访问 `/game`，预览编译好的 WebAssembly 游戏。 | |
| - **WASM 编译环境**: 预装 Emscripten (emsdk)。 | |
| ## 🎮 如何编译 OpenClaw 为 WASM | |
| 1. 登录终端。 | |
| 2. 运行 `./build_wasm.sh`。 | |
| 3. 如果编译成功，访问 `https://<你的Space地址>/game` 即可玩游戏。 | |
| ## ⚠️ 安全警告 | |
| - 此 VPS 拥有 root 权限。 | |
| - 请务必正确设置 `ALLOWED_USERS`，否则虽然能登录，但可能被 oauth2-proxy 拒绝（如果未设置则可能开放给所有人，具体取决于配置）。 | |