Hugging Face's logo

Spaces:
a3216
/
xtc-backend
Running

App Files Community
xtc-backend / README.md
a3216's picture
a3216
deploy: initial release to Hugging Face Spaces
36fae79
preview code
|
Raw
History Blame Contribute Delete
9.34 kB
metadata 
title: XTC Backend
emoji: 🚀
colorFrom: gray
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

XTC Backend (Hugging Face 版)

从 Netlify 版迁移而来的 OpenAI / Gemini 兼容网关，部署到 Hugging Face Spaces。

重要：本目录是迁移重写版，原 Netlify 后端代码保留在 ../openai-gemini-main-master/ 作为备用，未被覆盖。

目录结构 

xtc-backend-hf/
├── Dockerfile              # HF Spaces Docker 镜像
├── requirements.txt        # Python 依赖
├── .env.example            # 环境变量样例
├── app/
│   ├── main.py             # FastAPI 应用装配
│   ├── config.py           # 环境变量配置（pydantic-settings）
│   ├── errors.py           # 统一错误模型（兼容前端契约）
│   ├── auth.py             # access_key + JWT 临时令牌
│   ├── database.py         # SQLite 初始化
│   ├── cache.py            # 模型列表 TTL 缓存
│   ├── http_client.py      # httpx 全局连接池
│   ├── admin_html.py       # 后台 HTML（占位版）
│   ├── api/                # FastAPI 路由
│   │   ├── health.py       # /health
│   │   ├── openai_compat.py# /v1/chat/completions /v1/embeddings /v1/models
│   │   ├── xtc.py          # /v1/xtc/providers /v1/xtc/models /v1/xtc/chat
│   │   ├── pseudo_stream.py# /v1/xtc/chat/pseudo/start /v1/xtc/chat/pseudo/poll
│   │   ├── image_fix.py    # /v1/xtc/image/fix/test
│   │   ├── admin.py        # /admin/api/*
│   │   ├── logs.py         # /logs/api/*（合并原 xtc-log-receiver）
│   │   └── _common.py      # 共享工具
│   ├── adapters/           # 上游适配器
│   │   ├── gemini_api.py   # Gemini 总入口
│   │   ├── openai.py       # OpenAI 兼容透传
│   │   └── gemini/         # Gemini→OpenAI 转换子模块
│   │       ├── messages.py # messages ↔ contents
│   │       ├── config.py   # generation params
│   │       ├── tools.py    # tools / tool_choice
│   │       ├── response.py # 非流式响应转换
│   │       └── stream.py   # 流式 chunk 转换
│   ├── providers/          # 厂商解析与策略
│   │   ├── resolver.py     # 解析厂商
│   │   ├── keypool.py      # 多密钥轮询（持久化）
│   │   └── policy.py       # 白/黑名单 + glob
│   ├── media/imagefix.py   # 图片修正（Pillow）
│   ├── models/config.py    # Provider / AppConfig 数据模型
│   ├── services/           # 业务服务
│   │   ├── config_store.py # 配置存储（SQLite + HF Hub 同步）
│   │   └── pseudo_store.py # 伪流式会话存储
│   └── utils/              # 工具
│       ├── thought.py      # 思考链抽取
│       └── sse.py          # SSE 解析
└── README.md

与原 Netlify 版的差异

简化（砍掉的复杂度）

简化项 原因
环境变量配厂商（XTC_PROVIDER_1_* ... XTC_PROVIDER_12_*） 后端有数据库，Admin API 直接写
配置加密 XTC_CONFIG_CRYPT_KEY / enc:v1: HF Secrets 加密 + 私有 Hub 仓库 + 容器内 SQLite 已够安全
XTC_CONFIG_ENV_ONLY / XTC_ADMIN_REQUIRE_KEY_ON_PAGE 改用 JWT 登录态
XTC_ACCESS_SHORT_KEY / XTC_ACCESS_PIN JWT 令牌已足够
多平台入口（6 个） 只跑 HF Docker
Edge 路径 /edge/* 无 Edge 概念
runtimeEnv + process.env + Deno.env 三段式 只用 os.environ

保留（兼容契约，前端零改动）

  • OpenAI 兼容三件套：/v1/chat/completions、/v1/embeddings、/v1/models
  • XTC 简化接口：/v1/xtc/providers、/v1/xtc/models、/v1/xtc/chat、/v1/xtc/chat/pseudo/*、/v1/xtc/image/fix/test
  • 错误响应格式：{ ok:false, error:{ code, message, status, retryable, hint, upstream?, details? } }
  • 错误码集合：bad_request/unauthorized/forbidden/not_found/request_timeout/quota_exceeded/internal_error/service_unavailable/upstream_timeout/model_disabled/server_misconfigured
  • 图片修正三模式：mirror_h / rotate_180 / mirror_h_rotate_180
  • 流式协议：OpenAI SSE、stream_mode: simple、伪流式
  • 响应头：x-xtc-provider / x-xtc-model / x-xtc-image-fix-mode
  • Admin API 全部端点

新增

  • HF Hub 仓库配置同步（HF_TOKEN + HF_CONFIG_REPO）
  • JWT 临时令牌（替代内存 Map，多实例可用）
  • 多密钥 RR 计数器持久化到 SQLite
  • 伪流式会话存 SQLite（替代 Netlify Blobs）
  • 日志接收合并进主服务（/logs/api/*）
  • 用量统计表（usage_log）
  • 审计日志表（audit_log）

环境变量

参考 .env.example。必填：

  • XTC_ADMIN_KEY：后台登录密钥
  • XTC_ACCESS_KEY：前端长期密钥
  • XTC_JWT_SECRET：JWT 签名密钥（签发临时令牌用）

可选种子（首次启动初始化）：

  • GEMINI_API_KEY / GEMINI_API_KEYS（逗号分隔多 key）
  • OPENAI_API_KEY / OPENAI_API_KEYS
  • OPENAI_BASE_URL

可选 HF Hub 同步：

  • HF_TOKEN：访问 Hub 仓库的令牌
  • HF_CONFIG_REPO：仓库名（如 your-username/xtc-config，建议设为 dataset 私有仓库）

本地运行 

cd xtc-backend-hf
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install pillow-heif  # 可选，HEIC 解码

# 配置环境变量
cp .env.example .env
# 编辑 .env 设置 XTC_ADMIN_KEY / XTC_ACCESS_KEY / XTC_JWT_SECRET

# 启动
uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload

访问：

部署到 Hugging Face Spaces

  1. 在 HF 创建一个 Docker SDK 类型的 Space（私有推荐）
  2. 在 Space Settings → Repository secrets 添加环境变量：
    • XTC_ADMIN_KEY、XTC_ACCESS_KEY、XTC_JWT_SECRET
    • 可选：GEMINI_API_KEY、OPENAI_API_KEY、HF_TOKEN、HF_CONFIG_REPO
  3. 把本目录所有文件上传到 Space 仓库根目录（或用 GitHub Actions 同步）
  4. HF 自动构建并启动，访问 https://<space-name>.hf.space

国内访问与保活（Cloudflare Workers 反代） 

// CF Workers 脚本
addEventListener("fetch", e => e.respondWith(handle(e.request)));
addEventListener("scheduled", e => e.waitUntil(keepalive()));

const UPSTREAM = "https://your-space.hf.space";

async function handle(req) {
  const url = new URL(req.url);
  const upstream = new URL(UPSTREAM + url.pathname + url.search);
  const resp = await fetch(upstream, {
    method: req.method, headers: req.headers, body: req.body,
  });
  return new Response(resp.body, resp);
}

async function keepalive() {
  try { await fetch(UPSTREAM + "/health"); } catch (e) {}
}

在 wrangler.toml 配置 Cron Triggers（每 24 小时一次）：

[triggers]
crons = ["0 */24 * * *"]

接口契约速查

OpenAI 兼容 

POST /v1/chat/completions     # 头部 Authorization: Bearer <key> 或 x-xtc-access-key
POST /v1/embeddings
GET  /v1/models

XTC 简化 

GET  /v1/xtc/providers                        # { ok, defaultProviderId, providers[], count }
GET  /v1/xtc/models?provider=&all=1           # { ok, provider, models[], count }
POST /v1/xtc/chat                             # 见下方字段
POST /v1/xtc/chat/pseudo/start                # { ok, session_id, provider, model }
GET|POST /v1/xtc/chat/pseudo/poll             # { ok, status, deltas[], cursor, expires_in_sec }
POST /v1/xtc/image/fix/test                   # 返回 PNG 二进制

/v1/xtc/chat 成功响应：

{
  "ok": true,
  "provider": "gemini",
  "model": "gemini-2.5-flash",
  "thought": "...",
  "text": "...",
  "raw": "...",
  "usage": {},
  "warning": "（可选）图片修正失败提示",
  "image_fix_mode": "mirror_h",
  "image_fixed": true,
  "image_fix_failed_count": 0,
  "image_camera_facing": "front"
}

Admin API 

POST   /admin/api/login
POST   /admin/api/xtc-access-token
GET    /admin/api/tokens                       # 新增
POST   /admin/api/tokens/revoke                # 新增
GET    /admin/api/config
PUT    /admin/api/config
GET    /admin/api/providers
POST   /admin/api/providers
DELETE /admin/api/providers?id=
GET    /admin/api/provider-models?id=
POST   /admin/api/provider-settings
POST   /admin/api/default-provider
POST   /admin/api/test-chat

日志（合并自 xtc-log-receiver） 

POST /logs/api/log
POST /logs/api/log/batch
GET  /logs/api/stats?hours=24                  # admin
GET  /logs/api/logs?hours=24&level=&limit=     # admin

后续阶段

本版仅完成 MVP（核心接口迁移），后续阶段：

  1. 阶段 2：Vue 3 SPA 重写后台（替换占位 HTML），加用量统计仪表盘、模型策略可视化
  2. 阶段 3：HF Hub 多实例同步增强、Webhook 通知、速率限制
  3. 阶段 4：会话持久化、文件解析（PDF/Word）、模型路由策略、RAG

详见 ../openai-gemini-main-master/迁移到HuggingFace分析报告.md。