--- title: Claude2API emoji: 🔁 colorFrom: purple colorTo: indigo sdk: docker app_port: 7860 pinned: false --- # Claude2API — Hugging Face Space 说明 当前 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 这三层链路都已经打通。