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 包

在项目根目录执行：

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