---
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](file:///workspace/xtc-backend-hf/.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 私有仓库）

## 本地运行

```bash
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
```

访问：

- 健康检查：http://localhost:7860/health
- 后台：http://localhost:7860/admin
- API 文档：http://localhost:7860/docs

## 部署到 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 反代）

```javascript
// 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 小时一次）：

```toml
[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` 成功响应：

```json
{
  "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`。