Deploy from App

.dockerignore

@@ -0,0 +1,14 @@
+.git
+.gitignore
+.venv
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.log
+llmdoc/
+__MACOSX/
+dist/
+.tmp-runtime-stage/
+.tmp-runtime/
+.tmp-bootstrap/

CONFIG.md

@@ -0,0 +1,116 @@
+# 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` 是否正确

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PORT=7860 \
+    SCRIPT_ENTRY=openai.py \
+    SCRIPT_WORKDIR=app \
+    SCRIPT_EXTRACT_DIR=/opt/runtime \
+    SCRIPT_TMP_DIR=/opt/runtime/.tmp
+
+WORKDIR /app
+
+COPY requirements.txt /app/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r /app/requirements.txt
+
+COPY . /app
+
+EXPOSE 7860
+
+CMD ["python", "bootstrap.py"]

README.md

@@ -1,7 +1,7 @@
 ---
-title: Zai
-emoji: 🏢
-colorFrom: yellow
+title: Zv2
+emoji: 🌖
+colorFrom: green
 colorTo: blue
 sdk: docker
 pinned: false

bootstrap.py

@@ -0,0 +1,198 @@
+"""
+Runtime bootstrapper.
+
+Goal:
+- Keep the Docker image stable (only runtime deps + this bootstrapper).
+- At container startup, optionally download a zip payload, extract it, then run the entry script.
+
+Security notes:
+- Running remote code is risky. Prefer pinning with SCRIPT_ZIP_SHA256.
+- Extraction is protected against ZipSlip path traversal.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import subprocess
+import sys
+import time
+import urllib.request
+import uuid
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _e(name: str, default: str | None = None) -> str | None:
+    v = os.getenv(name)
+    if v is None or v == "":
+        return default
+    return v
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _safe_extract_zip(zip_path: Path, dest_dir: Path) -> None:
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_real = dest_dir.resolve()
+
+    with zipfile.ZipFile(zip_path) as zf:
+        for info in zf.infolist():
+            # Guard against ZipSlip: normalize and ensure within dest.
+            target = dest_dir / info.filename
+            try:
+                target_real = target.resolve()
+            except FileNotFoundError:
+                # Parent may not exist yet; resolve the parent.
+                target_real = (dest_dir / Path(info.filename).as_posix()).resolve()
+
+            if dest_real not in target_real.parents and target_real != dest_real:
+                raise RuntimeError(f"Unsafe zip entry path: {info.filename}")
+
+        zf.extractall(dest_dir)
+
+
+@dataclass(frozen=True)
+class BootstrapConfig:
+    zip_url: str | None
+    zip_sha256: str | None
+    allow_unverified: bool
+    extract_base: Path
+    tmp_dir: Path
+    entry_relpath: str
+    download_timeout_s: float
+    bearer_token: str | None
+    header_kv: str | None
+
+
+def _load_config() -> BootstrapConfig:
+    zip_url = _e("SCRIPT_ZIP_URL")
+    zip_sha256 = _e("SCRIPT_ZIP_SHA256")
+    allow_unverified = _e("ALLOW_UNVERIFIED_ZIP", "0") == "1"
+    extract_base = Path(_e("SCRIPT_EXTRACT_DIR", "/opt/runtime") or "/opt/runtime")
+    tmp_dir = Path(_e("SCRIPT_TMP_DIR", str(extract_base / ".tmp")) or str(extract_base / ".tmp"))
+
+    # Where to run inside the extracted payload.
+    # Recommended: zip contains folder "app/" with openai.py inside.
+    workdir = _e("SCRIPT_WORKDIR", "app") or ""
+    entry = _e("SCRIPT_ENTRY", "openai.py") or "openai.py"
+    entry_relpath = str(Path(workdir) / entry) if workdir else entry
+
+    download_timeout_s = float(_e("SCRIPT_DOWNLOAD_TIMEOUT", "60") or "60")
+
+    # Auth/header options:
+    # - SCRIPT_ZIP_TOKEN: bearer token
+    # - HF_TOKEN: commonly present on Spaces; used as fallback
+    bearer_token = _e("SCRIPT_ZIP_TOKEN") or _e("HF_TOKEN")
+    # - SCRIPT_ZIP_HEADER: raw "Key: Value" header line, optional
+    header_kv = _e("SCRIPT_ZIP_HEADER")
+
+    return BootstrapConfig(
+        zip_url=zip_url,
+        zip_sha256=zip_sha256,
+        allow_unverified=allow_unverified,
+        extract_base=extract_base,
+        tmp_dir=tmp_dir,
+        entry_relpath=entry_relpath,
+        download_timeout_s=download_timeout_s,
+        bearer_token=bearer_token,
+        header_kv=header_kv,
+    )
+
+
+def _download_zip(cfg: BootstrapConfig, out_path: Path) -> None:
+    assert cfg.zip_url
+    req = urllib.request.Request(cfg.zip_url, method="GET")
+    if cfg.bearer_token:
+        req.add_header("Authorization", f"Bearer {cfg.bearer_token}")
+    if cfg.header_kv and ":" in cfg.header_kv:
+        k, v = cfg.header_kv.split(":", 1)
+        req.add_header(k.strip(), v.strip())
+
+    with urllib.request.urlopen(req, timeout=cfg.download_timeout_s) as resp:
+        status = getattr(resp, "status", None)
+        if status is None and hasattr(resp, "getcode"):
+            status = resp.getcode()
+        if isinstance(status, int) and status >= 400:
+            raise RuntimeError(f"Download failed: HTTP {status}")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        with out_path.open("wb") as f:
+            shutil.copyfileobj(resp, f)
+
+
+def _atomic_replace_dir(tmp_dir: Path, target_dir: Path) -> None:
+    if target_dir.exists():
+        shutil.rmtree(target_dir, ignore_errors=True)
+    target_dir.parent.mkdir(parents=True, exist_ok=True)
+    tmp_dir.rename(target_dir)
+
+
+def main() -> int:
+    cfg = _load_config()
+
+    # Where the extracted payload will live.
+    current_dir = cfg.extract_base / "current"
+
+    if cfg.zip_url:
+        if not cfg.zip_sha256 and not cfg.allow_unverified:
+            raise RuntimeError(
+                "SCRIPT_ZIP_URL is set but SCRIPT_ZIP_SHA256 is missing. "
+                "Set SCRIPT_ZIP_SHA256 (recommended) or ALLOW_UNVERIFIED_ZIP=1."
+            )
+
+        cfg.tmp_dir.mkdir(parents=True, exist_ok=True)
+        td_path = cfg.tmp_dir / f"bootstrap_{uuid.uuid4().hex}"
+        td_path.mkdir(parents=True, exist_ok=True)
+        try:
+            zip_path = td_path / "payload.zip"
+
+            t0 = time.time()
+            print(f"[bootstrap] downloading zip from SCRIPT_ZIP_URL to {zip_path}", flush=True)
+            _download_zip(cfg, zip_path)
+            print(f"[bootstrap] download done in {time.time() - t0:.2f}s size={zip_path.stat().st_size}", flush=True)
+
+            if cfg.zip_sha256:
+                got = _sha256_file(zip_path)
+                want = cfg.zip_sha256.lower().strip()
+                if got != want:
+                    raise RuntimeError(f"SHA256 mismatch: got={got} want={want}")
+                print("[bootstrap] sha256 verified", flush=True)
+            else:
+                print("[bootstrap] sha256 not provided; running unverified payload", flush=True)
+
+            tmp_extract = cfg.extract_base / f".extract_tmp_{uuid.uuid4().hex}"
+            if tmp_extract.exists():
+                shutil.rmtree(tmp_extract, ignore_errors=True)
+
+            print(f"[bootstrap] extracting zip to {tmp_extract}", flush=True)
+            _safe_extract_zip(zip_path, tmp_extract)
+            _atomic_replace_dir(tmp_extract, current_dir)
+            print(f"[bootstrap] extracted to {current_dir}", flush=True)
+        finally:
+            shutil.rmtree(td_path, ignore_errors=True)
+
+    else:
+        raise RuntimeError(
+            "SCRIPT_ZIP_URL is required in this HF deployment. "
+            "Set SCRIPT_ZIP_URL and SCRIPT_ZIP_SHA256 (recommended)."
+        )
+
+    entry_path = (current_dir / cfg.entry_relpath).resolve()
+    if not entry_path.exists():
+        raise RuntimeError(f"Entry script not found: {entry_path} (SCRIPT_WORKDIR/SCRIPT_ENTRY)")
+
+    print(f"[bootstrap] starting: {sys.executable} {entry_path}", flush=True)
+    proc = subprocess.run([sys.executable, str(entry_path)], cwd=str(entry_path.parent))
+    return int(proc.returncode)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

requirements.txt

@@ -0,0 +1,4 @@
+fastapi
+uvicorn
+httpx
+httpcore