Polish README for simple-mode HF deployment

README.md

@@ -12,31 +12,52 @@ pinned: false
 
 当前 Space：<https://ohmyapi-c2api.hf.space>
 
-这是一个基于 `pushzx/claude2api:latest` 的 Hugging Face Docker Space 包装层。它的目标很克制：
+这是一个围绕 `pushzx/claude2api:latest` 的 Hugging Face Docker Space 包装层。目标很克制：
 
-- 让根路径 `/` 直接进入管理登录页 `/admin/login`
+- 让根路径 `/` 直接进入真实可用的管理登录页 `/admin/login`
 - 保持 `/admin`、`/health`、`/v1/*` 等能力继续由上游 `claude2api` 提供
-- 不在 wrapper 层伪造持久化配置语义
+- wrapper 只处理入口体验与反代，不在外层伪造持久化配置语义
 
-## 当前访问行为
+## 当前部署状态
 
-当前 Space 是 **public Space**，不是 private Space。
+当前线上状态已经收敛为 **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`
 
-- Hugging Face 本身**不会**先拦住外部访问者
-- 任何人都可以直接访问 `https://ohmyapi-c2api.hf.space/`
-- 当前根路径会被 wrapper 直接 `302` 到 `/admin/login`
-- API 是否需要鉴权，取决于上游 `claude2api` 是否读取到了 `CLAUDE_API_KEY`
+这样收敛的原因很明确：simple mode 已经稳定可用，而当前上游镜像的 DB-only 路径对 Neon / Supabase 这类强制 TLS 的托管 PostgreSQL 仍未验证通过，不能在这里把它写成现成功能。
+
+## 当前访问行为
+
+public Space 的含义是：**入口默认公开**，不是 **Secrets 自动公开**。
 
 当前线上已验证：
 
 - `/` → `302 /admin/login`
 - `/admin/login` 可正常打开
 - `/health` 返回 `200`
-- `/v1/models` 可正常访问
 - `/v1/messages` 未带正确 token 时返回 `401 Invalid API key`
-- 带正确 app token 时，`claude-sonnet-4-6` 已成功完成一次实际调用
+- 带正确 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 环境变量能直接生效
 
@@ -47,7 +68,7 @@ Hugging Face 对 Docker Space 的处理方式不是“把变量写进仓库文
 - **Variables**
 - **Secrets**
 
-作为真实的运行时环境变量注入到容器进程里。
+直接注入成容器进程的真实运行时环境变量。
 
 对这个仓库来说，等价于容器启动时直接拿到了例如：
 
@@ -59,7 +80,7 @@ ADMIN_PASS=...
 CLAUDE_SESSION_KEYS=...
 ```
 
-所以只要上游 `claude2api` 在启动时是通过 `os.Getenv(...)` 之类的方式读配置，它就会直接生效，不需要额外写入 `.env`、`config.yaml` 或别的文件。
+因此，只要上游 `claude2api` 在启动时通过 `os.Getenv(...)` 或等价方式读取配置，它就会直接生效，不需要额外写入 `.env`、`config.yaml` 或其它文件。
 
 ### 当前已确认的 Space Variables
 
@@ -72,9 +93,9 @@ ADMIN_USER=admin
 
 Secrets 不会被 Hugging Face API 直接回显，但从线上行为可以确认至少存在并已生效：
 
-- `CLAUDE_API_KEY`：因为未带 token 调用 `/v1/messages` 会返回 `401 Invalid API key`
-- `CLAUDE_SESSION_KEYS`：因为模型已能实际完成调用
-- `ADMIN_PASS`：因为管理页已处于登录保护下
+- `CLAUDE_API_KEY`
+- `CLAUDE_SESSION_KEYS`
+- `ADMIN_PASS`
 
 ## 当前 wrapper 做了什么
 
@@ -92,73 +113,45 @@ Secrets 不会被 Hugging Face API 直接回显，但从线上行为可以确认
 - 现在用户访问根路径时，会直接进入真实可用的登录入口
 - 同时不需要去改上游镜像源码
 
-## 当前是否配置了 PostgreSQL 持久化存储
+## 当前为什么不启用 PostgreSQL 持久化
 
 ### 结论
 
 **按当前已验证状态，不能认为这个 Space 已经配置并启用了 PostgreSQL 持久化存储。**
 
-虽然你提供了这个 Neon 连接串：
-
-```text
-postgresql://neondb_owner:npg_EhvAUwfT1Q0s@ep-late-sun-a4w4w406-pooler.us-east-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require
-```
-
-但就目前线上可确认的信息来看，还不能据此得出“当前 Space 正在用 PostgreSQL 持久化”的结论。
+更准确地说：当前线上已经明确收敛为 **simple mode only**，不是“正在尝试 DB-only 但尚未成功”。
 
 ### 原因
 
-1. 当前 wrapper 仓库本身并没有把这个连接串写入任何被跟踪文件。
-2. Hugging Face 公开可读到的 Variables 里没有 `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASS` / `DB_NAME`。
-3. Secrets 无法通过公开 API 直接读出，所以我不能仅靠外部观察断言你已经把 Neon 连接串拆分后放进了 Space Secrets。
-4. 当前线上已观察到的配置行为更像是：
-   - 上游成功读取了 `CLAUDE_SESSION_KEYS`
-   - 并使用 simple mode 就能完成调用
-5. 之前的运行时验证还显示：
-   - admin UI 中修改的 `api_key` 只在当前进程有效
-   - 重启后回退到启动环境变量值
-   这也**不支持**“当前已经有稳定的持久化配置优先层”这一判断。
-
-### 如果要真正启用 PostgreSQL
-
-需要满足两个条件：
+1. 只要存在 `CLAUDE_SESSION_KEYS`，上游就可以走 simple mode，并且当前已验证可稳定提供 API 能力。
+2. 当前 Hugging Face Space runtime 已确认 `storage.current = None` 且 `storage.requested = None`，因此容器内本地 PostgreSQL 不能视为正式持久化层。
+3. 对当前上游镜像的排查显示，DB-only 路径很可能会把 PostgreSQL DSN 拼成：
 
-1. 上游 `claude2api` 本身支持通过环境变量连接外部 PostgreSQL
-2. 你把对应数据库配置真实放进了 Hugging Face Space Secrets / Variables
+   ```text
+   host=%s port=%s user=%s password=%s dbname=%s sslmode=disable
+   ```
 
-按这个仓库现有文档，通常是：
+   这会与 Neon / Supabase 这类强制 TLS 的托管 PostgreSQL 冲突。
+4. 因此，即使文档里存在“可连接外部数据库”的描述，也不能把它等同于“当前镜像已支持外部托管 PG 持久化”。
 
-```env
-DB_HOST=ep-late-sun-a4w4w406-pooler.us-east-1.aws.neon.tech
-DB_PORT=5432
-DB_USER=neondb_owner
-DB_PASS=...实际密码...
-DB_NAME=neondb
-```
+### 为什么 local PostgreSQL 不能当成 HF 持久化
 
-注意：
+如果你打算在 Hugging Face Space 容器里直接放一个“本地 PostgreSQL”，要先明确一件事：**默认情况下，这不等于可靠持久化。**
 
-- 不能直接把完整连接串当成 `DB_HOST`
-- 当前 `.env.example` / README 的接口更偏向拆分字段，而不是单个 `DATABASE_URL`
-- 如果上游源码实际上不支持 Neon 这种外部 PG 持久化路径，或者虽然支持 PG 但启动优先级仍是 env 覆盖 runtime state，那么依然达不到你想要的“persisted-first”语义
+原因是：
 
-## 关于 admin password / auth token 持久化的当前结论
+1. Docker Space 默认使用的是容器自身的可写层，而不是天然持久卷。
+2. 如果没有单独申请 Hugging Face persistent storage，并把数据库目录明确挂到持久路径，本地 PG 数据在 restart / rebuild / redeploy 后都可能丢失。
+3. 当前这个 Space 没有启用 persistent storage，因此“容器内本地 PG”不能当成正式配置持久化方案。
 
-目前已做过的验证结论是：
+因此：
 
-- `api_key` 可以在当前运行期通过管理接口更新，并立即影响鉴权结果
-- 但容器重启后，会回退到启动时环境变量 / HF Secrets 的值
-- `admin_pass` 目前看**不能**通过现有 settings 路径真正更新生效
-
-所以当前更准确的理解是：
-
-- Hugging Face Secrets / Variables = **启动配置源**
-- 上游 admin UI 的部分设置 = **运行期状态修改**
-- 两者目前**不是**一个可自动回写、可稳定持久继承的统一配置层
+- 本地 PG 更适合临时调试，不适合承担当前 Space 的正式配置持久化
+- 真正需要稳定持久化时，应优先使用外部 PostgreSQL，或者先补齐 HF persistent storage，再验证上游是否支持对应的数据目录语义
 
 ## 当前推荐的线上配置思路
 
-如果你只是想把 Space 稳定跑起来：
+如果你只是想把 Space 稳定跑起来，当前推荐就是保持 simple mode：
 
 ### 必要 Secrets
 
@@ -173,22 +166,51 @@ LISTEN_ADDR=:7860
 ADMIN_USER=admin
 ```
 
-### 如果后续要尝试 PostgreSQL 持久化
+### 当前不启用的配置
+
+以下 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`：
 
-请单独把它当成一次上游运行时验证任务，而不是继续在 wrapper 层假设它已经存在。
+- `claude-opus-4-5`
+- `claude-opus-4-6`
+- `claude-3-opus-20240229`
 
-建议验证顺序：
+这也说明一件事：**`/v1/models` 返回的是“当前镜像声明支持的模型列表”，真正能否调用仍然取决于当前 session / account 的实际可用性。**
 
-1. 在 Space Secrets / Variables 中补齐真实 DB 配置
-2. 重启 Space
-3. 通过 admin UI 修改一个可观测配置
-4. 再次重启 Space
-5. 验证该配置是否仍然生效
-6. 验证生效值到底来自：
-   - PostgreSQL 持久化层
-   - 还是 HF Secrets / env
+## 关于 admin password / auth token 持久化的当前结论
+
+目前已做过的验证结论是：
+
+- `api_key` 可以在当前运行期通过管理接口更新，并立即影响鉴权结果
+- 但容器重启后，会回退到启动时环境变量 / HF Secrets 的值
+- `admin_pass` 目前看**不能**通过现有 settings 路径真正更新并持久生效
 
-只有这组验证跑通后，才能把“已启用 PostgreSQL 持久化”写成正式能力。
+所以当前更准确的理解是：
+
+- Hugging Face Secrets / Variables = **启动配置源**
+- 上游 admin UI 的部分设置 = **运行期状态修改**
+- 两者目前**不是**一个可自动回写、可稳定持久继承的统一配置层
 
 ## 当前仓库文件职责
 
@@ -203,7 +225,9 @@ ADMIN_USER=admin
 ```bash
 curl -I https://ohmyapi-c2api.hf.space/
 curl https://ohmyapi-c2api.hf.space/health
-curl https://ohmyapi-c2api.hf.space/v1/models
+
+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" \
@@ -215,4 +239,4 @@ curl https://ohmyapi-c2api.hf.space/v1/messages \
   }'
 ```
 
-如果最后一条返回正常消息体，就说明当前公开 Space、app token、以及 Claude session 这三层链路都已经打通。
+如果最后一条返回正常消息体，就说明当前公开 Space、app token、以及 Claude session 这三层链路都已经打通。