| # HF Space 配置说明 |
|
|
| ## 1. 部署模式 |
|
|
| 当前 `_hf` 目录采用以下模式： |
|
|
| - Docker 镜像只包含运行环境和 `bootstrap.py` |
| - 不内嵌业务脚本（`openai.py` / `main.py` / `claude_compat.py`） |
| - 容器启动时通过环境变量下载 zip 脚本包并运行 |
|
|
| 如果未配置下载地址，启动会直接失败（这是预期行为）。 |
|
|
| ## 2. 必填环境变量 |
|
|
| - `SCRIPT_ZIP_URL` |
| - 脚本 zip 下载地址 |
| - 例如对象存储直链、带鉴权的下载地址 |
|
|
| - `SCRIPT_ZIP_SHA256`（推荐） |
| - zip 文件的 SHA256 校验值 |
| - 与 `build_runtime_zip.py` 输出一致 |
|
|
| 说明： |
|
|
| - 若不使用 `SCRIPT_ZIP_SHA256`，必须设置 `ALLOW_UNVERIFIED_ZIP=1` |
| - 生产环境强烈建议始终校验 SHA256 |
|
|
| ## 3. 入口与解压相关变量 |
|
|
| - `SCRIPT_EXTRACT_DIR`（默认 `/opt/runtime`） |
| - zip 解压后的运行根目录 |
|
|
| - `SCRIPT_TMP_DIR`（默认 `/opt/runtime/.tmp`） |
| - 下载与中间临时文件目录 |
|
|
| - `SCRIPT_WORKDIR`（默认 `app`） |
| - 入口脚本所在目录（相对于解压根目录） |
|
|
| - `SCRIPT_ENTRY`（默认 `openai.py`） |
| - 入口脚本文件名 |
|
|
| 默认入口等价于： |
|
|
| - `/opt/runtime/current/app/openai.py` |
|
|
| 如果你的 zip 结构不同，请调整 `SCRIPT_WORKDIR` 和 `SCRIPT_ENTRY`。 |
|
|
| ## 4. 鉴权相关变量（按需） |
|
|
| - `SCRIPT_ZIP_TOKEN` |
| - 下载时自动添加 `Authorization: Bearer <token>` |
|
|
| - `SCRIPT_ZIP_HEADER` |
| - 自定义单个请求头，格式：`Key: Value` |
|
|
| ## 5. 应用运行变量（建议） |
|
|
| - `PORT=7860` |
| - `POOL_MIN_SIZE=1` |
| - `POOL_MAX_SIZE=4` |
| - `ALLOW_UNVERIFIED_ZIP=0` |
|
|
| 可选： |
|
|
| - `LOG_LEVEL=INFO` |
| - `HTTP_DEBUG=0` |
| - `POOL_INIT_BLOCKING=0` |
|
|
| ## 6. zip 包内容要求 |
|
|
| 默认需要包含以下路径： |
|
|
| - `app/openai.py` |
| - `app/main.py` |
| - `app/claude_compat.py` |
|
|
| 你也可以自定义结构，但必须与 `SCRIPT_WORKDIR` + `SCRIPT_ENTRY` 对齐。 |
|
|
| ## 7. 生成 zip 包 |
|
|
| 在项目根目录执行： |
|
|
| ```bash |
| python build_runtime_zip.py |
| ``` |
|
|
| 输出： |
|
|
| - `dist/runtime-payload.zip` |
| - `sha256=<...>` |
|
|
| 将 zip 上传到可下载地址后，把对应 URL 和 SHA256 填到 HF Space Variables。 |
|
|
| ## 8. HF Space 最小配置清单 |
|
|
| 建议至少配置： |
|
|
| - `SCRIPT_ZIP_URL=<your zip url>` |
| - `SCRIPT_ZIP_SHA256=<sha256>` |
| - `PORT=7860` |
| - `POOL_MIN_SIZE=1` |
| - `POOL_MAX_SIZE=4` |
|
|
| ## 9. 常见问题排查 |
|
|
| - 启动报 `SCRIPT_ZIP_URL is required` |
| - 未配置 `SCRIPT_ZIP_URL` |
|
|
| - 启动报 `SHA256 mismatch` |
| - `SCRIPT_ZIP_SHA256` 与实际 zip 不一致，重新计算并更新 |
|
|
| - 启动报 `Entry script not found` |
| - zip 内路径与 `SCRIPT_WORKDIR` / `SCRIPT_ENTRY` 不匹配 |
|
|
| - 下载 401/403 |
| - 检查 `SCRIPT_ZIP_TOKEN` 或 `SCRIPT_ZIP_HEADER` 是否正确 |
|
|
