File size: 3,350 Bytes
21308ec 0216330 21308ec 0216330 9777c57 0216330 9777c57 4f54dc8 32d5f26 4f54dc8 140619f 4f54dc8 7472e7a 4f54dc8 32d5f26 7472e7a 0216330 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | ---
title: Opencode
emoji: ⚡
colorFrom: green
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
---
# OpenCode on Hugging Face Spaces
本 Space 通过 **Docker** 部署 [OpenCode](https://opencode.ai/) 的 HTTP API 服务（`opencode serve`），可在浏览器中调用 OpenCode 的接口。
## 使用方式
- **API 文档（OpenAPI 3.1）**：打开 Space 后访问 `/doc`，例如：
`https://huggingface.co/spaces/<你的用户名>/<Space 名>/doc`
- **健康检查**：`GET /global/health`
- 其余接口见 [OpenCode Server 文档](https://opencode.ai/docs/server/)，如会话、消息、文件、LSP/MCP 等。
## 密钥与配置（可选）
若需使用需认证的模型（如 OpenAI、Claude 等），请在 Space 的 **Settings → Repository secrets** 中配置相应环境变量；OpenCode 会读取常见命名（如 `OPENCODE_*` 或各 provider 的 API key 变量）。
服务端 HTTP Basic 认证可设置：
- `OPENCODE_SERVER_PASSWORD`（必填时启用认证；**请务必在 HF 的 Secrets 里设置，不要写进代码**）
- `OPENCODE_SERVER_USERNAME`（可选，默认 `opencode`）
启用 Basic Auth 后，客户端需要提供**用户名 + 密码**（这是 HTTP Basic 机制决定的，无法只要密码）。
默认用户名是 **`opencode`**，除非你设置了 `OPENCODE_SERVER_USERNAME`。
## 持久化存储（Dataset，免费）
采用 [HF 官方推荐的 Dataset 存储](https://huggingface.co/docs/hub/spaces-storage#dataset-storage)：会话等数据写入你名下的 **Dataset 仓库**，用免费仓库存储额度，重启后可恢复。
1. **新建一个 Dataset 仓库**
在 [Hub](https://huggingface.co/new-dataset) 创建，例如 `tao-shen/opencode-data`（可先空着）。
2. **在 Space 里配置**
- **Settings → Repository secrets**：新增 `HF_TOKEN`，值为你的 [Access Token](https://huggingface.co/settings/tokens)（需 **Write** 权限）。
- **Settings → Variables**：新增 `OPENCODE_DATASET_REPO`，值为 **repo_id**（如 `tao-shen/opencode-data`），或填完整 URL（如 `https://huggingface.co/datasets/tao-shen/opencode-data`）也会自动识别。
3. **行为**
- 启动时：从该 Dataset 拉取已有数据到 `~/.local/share/opencode`（若有）。
- 运行中：**有改动即同步**（inotify 监听，约 20 秒防抖后上传），不再按固定间隔。
- 未设置上述两个变量时，与之前一致：不恢复、不保存，重启后数据丢失。
## 直接使用外部存储（自建/本地跑容器时）
若你在**自己的机器或 VPS** 上跑本镜像，希望 OpenCode **直接读写**某块盘或网络存储（不经过 Dataset 同步）：
1. 把外部存储挂载到容器内某路径，例如 `/mnt/opencode-data`（NFS、云盘、本地卷均可）。
2. 设置环境变量：**`XDG_DATA_HOME=/mnt/opencode-data`**（可选再加 `XDG_CONFIG_HOME=/mnt/opencode-data/.config`）。
3. 启动容器。OpenCode 会直接读写该路径，无需 HF_TOKEN / Dataset，也不会跑任何同步脚本。
在 **Hugging Face Spaces** 里无法挂载自定义卷，因此「直接外部存储」仅适用于自建/本地部署。
## 参考
- [Spaces 配置说明](https://huggingface.co/docs/hub/spaces-config-reference)
- [OpenCode Server](https://opencode.ai/docs/server/)
|