Improve HF wrapper landing and proxy docs

.env.example

@@ -0,0 +1,50 @@
+# ── Server ───────────────────────────────────────────────────────────────────
+# PORT=8080
+# Hugging Face Spaces: the wrapper listens on :7860 and proxies to the upstream app.
+# Minimum HF Secrets: CLAUDE_SESSION_KEYS, CLAUDE_API_KEY, ADMIN_PASS.
+# DB/Redis are not required for HF Simple mode.
+
+# ── Mode ─────────────────────────────────────────────────────────────────────
+# Simple mode: set CLAUDE_SESSION_KEYS to skip PostgreSQL entirely.
+# Separate multiple keys with commas.
+# CLAUDE_SESSION_KEYS=sk-ant-sid01-xxx,sk-ant-sid01-yyy
+
+# ── PostgreSQL ────────────────────────────────────────────────────────────────
+# Used by both the claude2api service and the postgres container.
+DB_HOST=postgres
+DB_PORT=5432
+DB_USER=claude2api
+DB_PASS=change_me_please        # ← REQUIRED: set a strong password
+DB_NAME=claude2api
+
+# ── Redis ─────────────────────────────────────────────────────────────────────
+# REDIS_PASS must match the password set in docker-compose.yml (redis container).
+REDIS_PASS=redis_secret         # ← REQUIRED: set a strong password
+REDIS_URL=redis://:redis_secret@redis:6379/0   # keep in sync with REDIS_PASS
+
+# ── Residential Proxy (leave empty to connect directly) ───────────────────────
+PROXY_HOST=
+PROXY_PORT=3010
+PROXY_USER=
+PROXY_PASS=
+PROXY_REGION=US
+
+# ── Admin Dashboard ───────────────────────────────────────────────────────────
+# ADMIN_PASS is a startup input. Even if upstream runtime lets you change some settings
+# in the admin UI, that does not mean Hugging Face Secrets or this file were updated.
+# Verified against the current upstream image in Simple mode: API key changes can take
+# effect in-process, but restart falls back to env/Secrets, and admin password is not
+# currently exposed here as a durable runtime setting.
+ADMIN_USER=admin
+ADMIN_PASS=change_me_please     # ← REQUIRED: change before going live
+
+# ── Rate Limiting ─────────────────────────────────────────────────────────────
+CLAUDE_DAILY_LIMIT=0    # 0 = unlimited
+MAX_RETRIES=3
+COOLDOWN_MINUTES=5
+
+# ── API Key Protection (optional) ─────────────────────────────────────────────
+# Startup default for protected API routes. If changed from the upstream admin UI,
+# the new value may apply only to the current running process unless upstream-backed
+# persistence is configured and verified.
+# CLAUDE_API_KEY=sk-your-api-key

Dockerfile

@@ -1,5 +1,12 @@
-FROM pushzx/claude2api:latest
+FROM pushzx/claude2api:latest AS upstream
 
-ENV LISTEN_ADDR=:7860
+FROM nginx:1.27-alpine
+
+COPY --from=upstream /claude2api /usr/local/bin/claude2api
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY static/index.html /usr/share/nginx/html/index.html
+COPY entrypoint.sh /entrypoint.sh
 
 EXPOSE 7860
+
+ENTRYPOINT ["/bin/sh", "/entrypoint.sh"]

README.md

@@ -14,6 +14,16 @@ Claude.ai Web → Anthropic API 兼容代理。将 Claude.ai 账号会话转换
 
 ## Hugging Face Spaces
 
+### 当前包装层职责
+
+当前 `Dockerfile` 不再直接把 `pushzx/claude2api:latest` 暴露到 `:7860`，而是改成了：
+
+- `/`：wrapper 提供的静态 landing page
+- 除 `/`、`/index.html`、`/favicon.ico` 外的其他路径：反向代理到上游 `claude2api`
+- 容器对外固定监听 `:7860`，上游进程在容器内监听 `127.0.0.1:8080`
+
+这也是旧版根路径看起来像 `404 page not found` 的原因：之前只是原样暴露上游镜像，而上游本身没有自定义 `/` 首页。
+
 ### 推荐模式
 
 Hugging Face Spaces 推荐先使用 **Simple 模式**。Spaces 只运行单容器，当前仓库中的 `postgres`、`redis`、`watchtower` 仅适用于 `docker-compose.yml` 的本地 / VPS 部署，不直接用于 HF。
@@ -26,9 +36,10 @@ Hugging Face Spaces 推荐先使用 **Simple 模式**。Spaces 只运行单容
 
 ### 推荐 Variables
 
-- `LISTEN_ADDR=:7860`
 - `ADMIN_USER=admin`
 
+通常不需要为 HF Space 手动设置 `LISTEN_ADDR=:7860`；`7860` 现在由 wrapper 前置层负责，上游在容器内固定监听 `127.0.0.1:8080`。
+
 ### 可选 Secrets
 
 - `PROXY_HOST`
@@ -47,12 +58,17 @@ Hugging Face Spaces 推荐先使用 **Simple 模式**。Spaces 只运行单容
 
 - `config.yaml` 不参与此服务配置，运行时参数全部来自环境变量
 - 若仅提供 `CLAUDE_SESSION_KEYS`，可跳过 PostgreSQL / Redis
-- 若需要管理面板持久化能力，应改用外部 PostgreSQL / Redis，而不是复用 compose sidecar
+- Private Space 的 Hugging Face 访问控制，与应用自身的 `CLAUDE_API_KEY` 是两层独立鉴权
+- HF Secrets 是启动时输入，不会被管理页面反向写回
+- 若需要管理面板持久化能力，应改用上游支持的外部 PostgreSQL / Redis，而不是复用 compose sidecar
+- 本地针对 `pushzx/claude2api:latest` 的 Simple 模式验证结果：管理接口可在当前进程内更新 `api_key`，但当前 UI / API 没有生效地修改 `ADMIN_PASS`；容器重启后 `api_key` 会回退到环境变量值
+- 因此“持久化配置优先于 HF Secrets / env”不能由 wrapper 保证，只有在上游运行时验证成立后才能当作正式能力描述
 - 对外开放时，建议始终设置 `CLAUDE_API_KEY`
 
 ### 部署后验证
 
 ```bash
+curl https://<space>.hf.space/
 curl https://<space>.hf.space/health
 
 curl https://<space>.hf.space/v1/messages \
@@ -65,6 +81,8 @@ curl https://<space>.hf.space/v1/messages \
   }'
 ```
 
+如果 Space 设为 private，先确认请求方已经通过 Hugging Face 侧访问控制；随后再按上游应用的 `CLAUDE_API_KEY` 语义访问 API。
+
 ---
 
 ## 快速部署

entrypoint.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+set -eu
+
+nginx -t
+
+LISTEN_ADDR="127.0.0.1:8080" /usr/local/bin/claude2api &
+upstream_pid=$!
+
+nginx -g 'daemon off;' &
+nginx_pid=$!
+
+terminate() {
+  kill -TERM "$upstream_pid" "$nginx_pid" 2>/dev/null || true
+}
+
+trap terminate INT TERM
+
+while :; do
+  if ! kill -0 "$upstream_pid" 2>/dev/null; then
+    wait "$upstream_pid" || true
+    kill -TERM "$nginx_pid" 2>/dev/null || true
+    wait "$nginx_pid" || true
+    exit 1
+  fi
+
+  if ! kill -0 "$nginx_pid" 2>/dev/null; then
+    wait "$nginx_pid" || true
+    kill -TERM "$upstream_pid" 2>/dev/null || true
+    wait "$upstream_pid" || true
+    exit 1
+  fi
+
+  sleep 1
+done

nginx.conf

@@ -0,0 +1,55 @@
+upstream claude2api_upstream {
+    server 127.0.0.1:8080;
+    keepalive 32;
+}
+
+server {
+    listen 7860;
+    listen [::]:7860;
+    server_name _;
+
+    charset utf-8;
+    client_max_body_size 50m;
+
+    location = / {
+        root /usr/share/nginx/html;
+        try_files /index.html =404;
+        add_header Cache-Control "no-store";
+    }
+
+    location = /index.html {
+        root /usr/share/nginx/html;
+        add_header Cache-Control "no-store";
+    }
+
+    location = /favicon.ico {
+        return 204;
+    }
+
+    location /v1/messages {
+        proxy_pass http://claude2api_upstream;
+        proxy_http_version 1.1;
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Connection "";
+    }
+
+    location / {
+        proxy_pass http://claude2api_upstream;
+        proxy_http_version 1.1;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Connection "";
+    }
+}

static/index.html

@@ -0,0 +1,410 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Claude2API</title>
+    <style>
+      :root {
+        --bg: #0b0908;
+        --bg-soft: #151210;
+        --panel: rgba(24, 20, 18, 0.82);
+        --panel-strong: rgba(34, 28, 25, 0.92);
+        --line: rgba(241, 231, 220, 0.11);
+        --line-strong: rgba(241, 231, 220, 0.2);
+        --text: #f1e7dc;
+        --muted: #b7a898;
+        --accent: #e3c9a5;
+        --accent-strong: #f3e0c4;
+        --shadow: 0 28px 84px rgba(0, 0, 0, 0.42);
+        --radius: 30px;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      html {
+        color-scheme: dark;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        color: var(--text);
+        font-family: "Helvetica Neue", "Segoe UI", ui-sans-serif, sans-serif;
+        background:
+          radial-gradient(circle at 14% 12%, rgba(227, 201, 165, 0.14), transparent 24%),
+          radial-gradient(circle at 88% 10%, rgba(140, 98, 59, 0.18), transparent 18%),
+          linear-gradient(180deg, #15110f 0%, var(--bg-soft) 38%, var(--bg) 100%);
+      }
+
+      body::before {
+        content: "";
+        position: fixed;
+        inset: 0;
+        pointer-events: none;
+        opacity: 0.08;
+        background-image: linear-gradient(rgba(255, 255, 255, 0.03) 1px, transparent 1px);
+        background-size: 100% 3px;
+        mix-blend-mode: soft-light;
+      }
+
+      a {
+        color: inherit;
+        text-decoration: none;
+      }
+
+      code,
+      pre {
+        font-family: "JetBrains Mono", "SFMono-Regular", ui-monospace, monospace;
+      }
+
+      h1,
+      h2 {
+        font-family: "Baskerville", "Times New Roman", Georgia, serif;
+        letter-spacing: -0.04em;
+      }
+
+      .page {
+        width: min(1080px, calc(100vw - 28px));
+        margin: 0 auto;
+        padding: 22px 0 34px;
+      }
+
+      .frame {
+        position: relative;
+        overflow: hidden;
+        border: 1px solid var(--line);
+        border-radius: var(--radius);
+        background: linear-gradient(180deg, rgba(35, 29, 25, 0.94), rgba(19, 16, 14, 0.93));
+        box-shadow: var(--shadow);
+        backdrop-filter: blur(18px);
+      }
+
+      .frame::after {
+        content: "";
+        position: absolute;
+        inset: auto -10% 0;
+        height: 1px;
+        background: linear-gradient(90deg, transparent, rgba(243, 224, 196, 0.22), transparent);
+      }
+
+      .masthead {
+        display: grid;
+        grid-template-columns: minmax(0, 1.2fr) minmax(280px, 0.8fr);
+        gap: 22px;
+        padding: 32px;
+      }
+
+      .tag {
+        display: inline-flex;
+        align-items: center;
+        padding: 8px 14px;
+        border-radius: 999px;
+        border: 1px solid rgba(227, 201, 165, 0.16);
+        background: rgba(227, 201, 165, 0.08);
+        color: var(--accent);
+        font-size: 11px;
+        font-weight: 700;
+        letter-spacing: 0.18em;
+        text-transform: uppercase;
+      }
+
+      h1 {
+        margin: 18px 0 12px;
+        font-size: clamp(3rem, 8vw, 5.6rem);
+        line-height: 0.92;
+      }
+
+      .lede {
+        max-width: 680px;
+        margin: 0;
+        color: var(--muted);
+        font-size: 1.03rem;
+        line-height: 1.86;
+      }
+
+      .actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 12px;
+        margin-top: 28px;
+      }
+
+      .button {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-width: 150px;
+        min-height: 46px;
+        padding: 0 18px;
+        border-radius: 999px;
+        border: 1px solid var(--line);
+        background: rgba(255, 255, 255, 0.04);
+        color: var(--text);
+        font-size: 14px;
+        font-weight: 600;
+        transition:
+          transform 0.16s ease,
+          border-color 0.16s ease,
+          background 0.16s ease;
+      }
+
+      .button:hover {
+        transform: translateY(-1px);
+        border-color: var(--line-strong);
+      }
+
+      .button.primary {
+        border-color: transparent;
+        background: linear-gradient(135deg, var(--accent-strong), var(--accent));
+        color: #1a140f;
+      }
+
+      .rail {
+        display: grid;
+        gap: 12px;
+        align-content: start;
+      }
+
+      .glance {
+        padding: 18px;
+        border-radius: 22px;
+        border: 1px solid var(--line);
+        background: rgba(255, 255, 255, 0.03);
+      }
+
+      .glance span {
+        display: block;
+        margin-bottom: 8px;
+        color: var(--muted);
+        font-size: 11px;
+        font-weight: 700;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+      }
+
+      .glance strong {
+        display: block;
+        font-size: 1rem;
+        line-height: 1.65;
+      }
+
+      .content {
+        display: grid;
+        gap: 18px;
+        margin-top: 18px;
+      }
+
+      .section {
+        padding: 26px 28px;
+      }
+
+      .section-head {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: flex-end;
+        justify-content: space-between;
+        gap: 12px;
+        margin-bottom: 18px;
+      }
+
+      .section-head h2 {
+        margin: 0;
+        font-size: 2rem;
+      }
+
+      .section-head p,
+      .note,
+      .route p,
+      .aside p {
+        margin: 0;
+        color: var(--muted);
+        line-height: 1.78;
+      }
+
+      .routes {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(210px, 1fr));
+        gap: 14px;
+      }
+
+      .route,
+      .aside {
+        padding: 18px;
+        border-radius: 22px;
+        border: 1px solid var(--line);
+        background: rgba(255, 255, 255, 0.03);
+      }
+
+      .route h3 {
+        margin: 0 0 10px;
+        font-size: 1.06rem;
+      }
+
+      .route code,
+      .aside code {
+        color: var(--accent-strong);
+      }
+
+      .split {
+        display: grid;
+        grid-template-columns: minmax(0, 1.08fr) minmax(0, 0.92fr);
+        gap: 18px;
+      }
+
+      .code {
+        margin: 0;
+        padding: 18px;
+        overflow: auto;
+        border-radius: 22px;
+        border: 1px solid var(--line);
+        background: #0e0a08;
+        color: #f6ecdf;
+        line-height: 1.72;
+      }
+
+      .aside-stack {
+        display: grid;
+        gap: 14px;
+      }
+
+      .note {
+        margin-top: 16px;
+      }
+
+      @media (max-width: 900px) {
+        .masthead,
+        .split {
+          grid-template-columns: 1fr;
+        }
+      }
+
+      @media (max-width: 720px) {
+        .page {
+          width: min(100vw - 18px, 1080px);
+          padding-top: 14px;
+        }
+
+        .masthead,
+        .section {
+          padding: 22px;
+        }
+
+        h1 {
+          font-size: clamp(2.6rem, 13vw, 4.2rem);
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main class="page">
+      <section class="frame masthead">
+        <div>
+          <div class="tag">Hugging Face wrapper</div>
+          <h1>Claude2API</h1>
+          <p class="lede">
+            Claude.ai sessions, surfaced as an Anthropic-compatible API. This root page exists to
+            make the Space legible at first glance; the actual admin dashboard, health probe, and
+            API behavior still come from the upstream <code>claude2api</code> runtime.
+          </p>
+          <div class="actions">
+            <a class="button primary" href="/admin">Open Admin</a>
+            <a class="button" href="/health">Health</a>
+          </div>
+        </div>
+
+        <aside class="rail">
+          <div class="glance">
+            <span>Root</span>
+            <strong>Static landing page served by the wrapper.</strong>
+          </div>
+          <div class="glance">
+            <span>Runtime</span>
+            <strong>All non-root routes pass through to the upstream service.</strong>
+          </div>
+          <div class="glance">
+            <span>Access</span>
+            <strong>Private Space auth and app-level API keys can both apply.</strong>
+          </div>
+        </aside>
+      </section>
+
+      <div class="content">
+        <section class="frame section">
+          <div class="section-head">
+            <div>
+              <h2>Where to go</h2>
+            </div>
+            <p>
+              The wrapper fixes the root experience only. It does not replace upstream routing,
+              persistence, or configuration semantics.
+            </p>
+          </div>
+
+          <div class="routes">
+            <article class="route">
+              <h3><code>/admin</code></h3>
+              <p>Upstream dashboard for accounts, model mapping, proxy settings, and API key changes.</p>
+            </article>
+            <article class="route">
+              <h3><code>/health</code></h3>
+              <p>Direct passthrough to the upstream health endpoint, kept simple for probes and checks.</p>
+            </article>
+            <article class="route">
+              <h3><code>/v1/messages</code></h3>
+              <p>Anthropic-compatible request path. Auth and streaming semantics remain upstream-defined.</p>
+            </article>
+          </div>
+        </section>
+
+        <section class="frame section">
+          <div class="section-head">
+            <div>
+              <h2>Quick request</h2>
+            </div>
+            <p>
+              Use the Space URL as the base URL. If the Space is private, Hugging Face must allow the
+              request before the app can evaluate its own token checks.
+            </p>
+          </div>
+
+          <div class="split">
+            <pre class="code"><code>curl https://YOUR-SPACE.hf.space/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $CLAUDE_API_KEY" \
+  -d '{
+    "model": "claude-sonnet-4-6",
+    "max_tokens": 128,
+    "messages": [
+      {"role": "user", "content": "hello"}
+    ]
+  }'</code></pre>
+
+            <div class="aside-stack">
+              <div class="aside">
+                <p>
+                  Runtime edits made in <code>/admin</code> do not mean Hugging Face Secrets were
+                  updated. Treat wrapper config, Secrets, and any upstream persistence layer as
+                  separate concerns.
+                </p>
+              </div>
+              <div class="aside">
+                <p>
+                  This page intentionally avoids live status, mutable controls, and any secret-derived
+                  values. It is an entrance, not a console.
+                </p>
+              </div>
+            </div>
+          </div>
+
+          <p class="note">
+            For stable persisted settings after restart, rely on upstream-supported storage and verify
+            the behavior explicitly instead of assuming the wrapper can override startup precedence.
+          </p>
+        </section>
+      </div>
+    </main>
+  </body>
+</html>