CONFIG.md

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 包

在项目根目录执行：

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 是否正确