| --- |
| title: Claude2API |
| emoji: 🔁 |
| colorFrom: purple |
| colorTo: indigo |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| # Claude2API — Hugging Face Space 说明 |
|
|
| 当前 Space：<https://ohmyapi-c2api.hf.space> |
|
|
| 这是一个围绕 `pushzx/claude2api:latest` 的 Hugging Face Docker Space 包装层。目标很克制： |
|
|
| - 让根路径 `/` 直接进入真实可用的管理登录页 `/admin/login` |
| - 保持 `/admin`、`/health`、`/v1/*` 等能力继续由上游 `claude2api` 提供 |
| - wrapper 只处理入口体验与反代，不在外层伪造持久化配置语义 |
|
|
| ## 当前部署状态 |
|
|
| 当前线上状态已经收敛为 **public Space + simple mode**。 |
|
|
| - Space 类型：**public Space** |
| - 运行模式：**simple mode** |
| - 当前不启用 DB-backed 持久化 |
| - 当前已从 Space Secrets 中移除：`DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASS`、`DB_NAME`、`PGSSLMODE` |
| - 当前根路径 `/` 会直接 `302` 到 `/admin/login` |
|
|
| 这样收敛的原因很明确：simple mode 已经稳定可用，而当前上游镜像的 DB-only 路径对 Neon / Supabase 这类强制 TLS 的托管 PostgreSQL 仍未验证通过，不能在这里把它写成现成功能。 |
|
|
| ## 当前访问行为 |
|
|
| public Space 的含义是：**入口默认公开**，不是 **Secrets 自动公开**。 |
|
|
| 当前线上已验证： |
|
|
| - `/` → `302 /admin/login` |
| - `/admin/login` 可正常打开 |
| - `/health` 返回 `200` |
| - `/v1/messages` 未带正确 token 时返回 `401 Invalid API key` |
| - 带正确 app token 时，`claude-sonnet-4-6` 已成功完成实际调用 |
| - `/v1/models` 可在带 token 的情况下返回模型列表 |
|
|
| ## public Space 的风险边界 |
|
|
| public Space 不会因为是 public 就把 Hugging Face Secrets 直接暴露出来，但它会让你的入口地址处于公网可探测状态。 |
|
|
| 这意味着： |
|
|
| - `https://ohmyapi-c2api.hf.space/` 这类地址任何人都能访问与探测 |
| - Hugging Face Space Secrets **不会**被页面或公开 API 直接回显 |
| - 真正更常见的泄露面是：把 token / session 写进仓库文件、前端页面、日志、导出的配置或本机历史文件 |
| - public Space 是否安全，关键不在于“是否 public”，而在于： |
| - app 自身接口是否强制鉴权 |
| - `CLAUDE_API_KEY` / `CLAUDE_SESSION_KEYS` 是否只保留在服务端运行时环境 |
| - 仓库与页面输出里是否完全不出现真实 secret |
|
|
| 换句话说，public Space **不会自动泄露 session**，但如果 app token 泄露、接口未加保护，别人就能直接消费你的服务。 |
|
|
| ## 为什么 Hugging Face 环境变量能直接生效 |
|
|
| 因为当前 Space 使用的是 **Docker SDK**。 |
|
|
| Hugging Face 对 Docker Space 的处理方式不是“把变量写进仓库文件”，而是在容器启动时把 Space Settings 里的： |
|
|
| - **Variables** |
| - **Secrets** |
|
|
| 直接注入成容器进程的真实运行时环境变量。 |
|
|
| 对这个仓库来说，等价于容器启动时直接拿到了例如： |
|
|
| ```env |
| ADMIN_USER=admin |
| LISTEN_ADDR=:7860 |
| CLAUDE_API_KEY=... |
| ADMIN_PASS=... |
| CLAUDE_SESSION_KEYS=... |
| ``` |
|
|
| 因此，只要上游 `claude2api` 在启动时通过 `os.Getenv(...)` 或等价方式读取配置，它就会直接生效，不需要额外写入 `.env`、`config.yaml` 或其它文件。 |
|
|
| ### 当前已确认的 Space Variables |
|
|
| 当前公开可读到的 Variables 是： |
|
|
| ```env |
| LISTEN_ADDR=:7860 |
| ADMIN_USER=admin |
| ``` |
|
|
| Secrets 不会被 Hugging Face API 直接回显，但从线上行为可以确认至少存在并已生效： |
|
|
| - `CLAUDE_API_KEY` |
| - `CLAUDE_SESSION_KEYS` |
| - `ADMIN_PASS` |
|
|
| ## 当前 wrapper 做了什么 |
|
|
| 当前 `Dockerfile` 不是直接把上游镜像原样暴露到 `:7860`，而是： |
|
|
| - 前置一个很薄的 nginx |
| - nginx 监听 `:7860` |
| - 上游 `claude2api` 在容器内监听 `127.0.0.1:8080` |
| - `/` 与 `/index.html` 直接跳转到 `/admin/login` |
| - 其余路径继续透传到上游 |
|
|
| 这样做的原因很简单： |
|
|
| - 旧版 root path 会显示 `404 page not found` |
| - 现在用户访问根路径时，会直接进入真实可用的登录入口 |
| - 同时不需要去改上游镜像源码 |
|
|
| ## 当前为什么不启用 PostgreSQL 持久化 |
|
|
| ### 结论 |
|
|
| **按当前已验证状态，不能认为这个 Space 已经配置并启用了 PostgreSQL 持久化存储。** |
|
|
| 更准确地说：当前线上已经明确收敛为 **simple mode only**，不是“正在尝试 DB-only 但尚未成功”。 |
|
|
| ### 原因 |
|
|
| 1. 只要存在 `CLAUDE_SESSION_KEYS`，上游就可以走 simple mode，并且当前已验证可稳定提供 API 能力。 |
| 2. 当前 Hugging Face Space runtime 已确认 `storage.current = None` 且 `storage.requested = None`，因此容器内本地 PostgreSQL 不能视为正式持久化层。 |
| 3. 对当前上游镜像的排查显示，DB-only 路径很可能会把 PostgreSQL DSN 拼成： |
|
|
| ```text |
| host=%s port=%s user=%s password=%s dbname=%s sslmode=disable |
| ``` |
|
|
| 这会与 Neon / Supabase 这类强制 TLS 的托管 PostgreSQL 冲突。 |
| 4. 因此，即使文档里存在“可连接外部数据库”的描述，也不能把它等同于“当前镜像已支持外部托管 PG 持久化”。 |
|
|
| ### 为什么 local PostgreSQL 不能当成 HF 持久化 |
|
|
| 如果你打算在 Hugging Face Space 容器里直接放一个“本地 PostgreSQL”，要先明确一件事：**默认情况下，这不等于可靠持久化。** |
|
|
| 原因是： |
|
|
| 1. Docker Space 默认使用的是容器自身的可写层，而不是天然持久卷。 |
| 2. 如果没有单独申请 Hugging Face persistent storage，并把数据库目录明确挂到持久路径，本地 PG 数据在 restart / rebuild / redeploy 后都可能丢失。 |
| 3. 当前这个 Space 没有启用 persistent storage，因此“容器内本地 PG”不能当成正式配置持久化方案。 |
|
|
| 因此： |
|
|
| - 本地 PG 更适合临时调试，不适合承担当前 Space 的正式配置持久化 |
| - 真正需要稳定持久化时，应优先使用外部 PostgreSQL，或者先补齐 HF persistent storage，再验证上游是否支持对应的数据目录语义 |
|
|
| ## 当前推荐的线上配置思路 |
|
|
| 如果你只是想把 Space 稳定跑起来，当前推荐就是保持 simple mode： |
|
|
| ### 必要 Secrets |
|
|
| - `CLAUDE_SESSION_KEYS` |
| - `CLAUDE_API_KEY` |
| - `ADMIN_PASS` |
|
|
| ### 当前 Variables |
|
|
| ```env |
| LISTEN_ADDR=:7860 |
| ADMIN_USER=admin |
| ``` |
|
|
| ### 当前不启用的配置 |
|
|
| 以下 DB 相关项当前视为**暂不启用**，不要再把它们当成线上必需配置： |
|
|
| - `DB_HOST` |
| - `DB_PORT` |
| - `DB_USER` |
| - `DB_PASS` |
| - `DB_NAME` |
| - `PGSSLMODE` |
|
|
| ## 当前已验证可调用的模型 |
|
|
| 带正确 app token 时，以下模型已通过真实 `/v1/messages` 请求验证，可以正常返回结果： |
|
|
| - `claude-sonnet-4-5` |
| - `claude-haiku-4-5` |
| - `claude-sonnet-4-6` |
| - `claude-haiku-4-6` |
| - `claude-3-5-sonnet-20241022` |
| - `claude-3-5-haiku-20241022` |
| - `claude-3-sonnet-20240229` |
| - `claude-3-haiku-20240307` |
|
|
| 以下模型虽然会出现在 `/v1/models` 列表里，但当前实测返回的是 `403 model_not_available`： |
|
|
| - `claude-opus-4-5` |
| - `claude-opus-4-6` |
| - `claude-3-opus-20240229` |
|
|
| 这也说明一件事：**`/v1/models` 返回的是“当前镜像声明支持的模型列表”，真正能否调用仍然取决于当前 session / account 的实际可用性。** |
|
|
| ## 关于 admin password / auth token 持久化的当前结论 |
|
|
| 目前已做过的验证结论是： |
|
|
| - `api_key` 可以在当前运行期通过管理接口更新，并立即影响鉴权结果 |
| - 但容器重启后，会回退到启动时环境变量 / HF Secrets 的值 |
| - `admin_pass` 目前看**不能**通过现有 settings 路径真正更新并持久生效 |
|
|
| 所以当前更准确的理解是： |
|
|
| - Hugging Face Secrets / Variables = **启动配置源** |
| - 上游 admin UI 的部分设置 = **运行期状态修改** |
| - 两者目前**不是**一个可自动回写、可稳定持久继承的统一配置层 |
|
|
| ## 当前仓库文件职责 |
|
|
| - `Dockerfile`：构建 HF Space 容器 |
| - `nginx.conf`：把根路径重定向到 `/admin/login`，并透传其他请求 |
| - `entrypoint.sh`：同时启动前置 nginx 和上游 `claude2api` |
| - `.env.example`：本地 / VPS 运行示例，不代表 HF Secrets 会被运行时回写 |
| - `docker-compose.yml`：本地 / VPS 参考，不会直接在 HF Space 中运行 |
|
|
| ## 最小验收命令 |
|
|
| ```bash |
| curl -I https://ohmyapi-c2api.hf.space/ |
| curl https://ohmyapi-c2api.hf.space/health |
| |
| curl https://ohmyapi-c2api.hf.space/v1/models \ |
| -H "Authorization: Bearer $CLAUDE_API_KEY" |
| |
| curl https://ohmyapi-c2api.hf.space/v1/messages \ |
| -H "Content-Type: application/json" \ |
| -H "Authorization: Bearer $CLAUDE_API_KEY" \ |
| -d '{ |
| "model": "claude-sonnet-4-6", |
| "max_tokens": 32, |
| "messages": [{"role": "user", "content": "Reply with exactly: ok"}] |
| }' |
| ``` |
|
|
| 如果最后一条返回正常消息体，就说明当前公开 Space、app token、以及 Claude session 这三层链路都已经打通。 |
