README.md

---

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 拒绝（如果未设置则可能开放给所有人，具体取决于配置）。