xPdf Documentation

English

简体中文

English

简体中文

Appearance

xPdf Label API - 后台认证机制 ​

本文档描述三个接口的认证策略差异及 V3 优化缓存机制。

接口认证策略对比 ​

接口认证方式请求头适用场景
/api/v1/labelInternal Token (S2S)无需 (使用环境变量 XADMIN_TOKEN)系统间内部调用
/api/v2/label无认证无需测试/开发环境
/api/v3/labelBearer Token (User)Authorization: Bearer <user_token>面向终端用户

V1: 内部服务认证 (S2S) ​

流程:

  1. 服务端使用环境变量 XADMIN_TOKEN (系统级 Token)
  2. 同步调用 xAdmin /v1/verify 验证
  3. 验证通过后生成 PDF

配置:

  • 环境变量 XADMIN_TOKEN: 系统级 API Token
  • 环境变量 SKIP_XADMIN_VERIFY: 设置后跳过验证 (开发用)

V2: 无认证 ​

直接处理请求，不进行任何用户验证。仅用于测试和内部开发。

V3: 用户 Token + 优化缓存 ​

请求头要求 ​

http
Authorization: Bearer <user_token>

核心架构 ​

┌─────────────────────────────────────────────────────────────┐
│                     V3 认证流程                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  请求 ──► 提取 Token ──► 本地缓存检查                         │
│                              │                              │
│              ┌───────────────┴───────────────┐              │
│              ▼                               ▼              │
│         [缓存命中且有效]              [缓存未命中/过期/黑名单]   │
│              │                               │              │
│              ▼                               ▼              │
│     异步验证 (tokio::spawn)          同步验证 xAdmin          │
│              │                               │              │
│              ▼                               ├──►失败──► 403 │
│         直接通过                             │              │
│              │                               ▼              │
│              │                          更新缓存             │
│              └───────────────┬───────────────┘              │
│                              ▼                              │
│                        生成 PDF ──► 200 OK                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

缓存机制详情 ​

缓存结构 (内存 DashMap):

rust
struct UserCacheEntry {
    expires_at: Instant,    // 过期时间 (5分钟)
    blacklisted: bool,      // 是否在黑名单
}

缓存策略:

场景处理方式响应延迟
缓存命中且有效异步后台验证，立即通过< 1ms
缓存未命中同步调用 xAdmin 验证50-200ms
缓存过期同步调用 xAdmin 验证50-200ms
黑名单用户同步调用 xAdmin 验证50-200ms
验证失败标记黑名单，返回 403-

黑名单机制 ​

  • 触发条件: xAdmin 返回验证失败 (余额不足/Token 无效)
  • 作用: 强制后续请求走同步验证
  • 过期时间: 5 分钟 (与正常缓存相同)
  • 解除条件: 过期后重新同步验证通过

异步验证流程 ​

当缓存有效时:

  1. 主流程立即返回"认证通过"
  2. tokio::spawn 启动后台任务
  3. 后台任务调用 xAdmin 验证/上报使用量
  4. 若验证失败，标记用户至黑名单

xAdmin 验证接口 ​

请求:

http
POST https://api-xadmin.mawb.com/v1/verify
Authorization: Bearer <token>
Content-Type: application/json

{ "count": 5 }

响应:

  • 200 OK: 验证通过
  • 401 Unauthorized: Token 无效
  • 402 Payment Required: 余额不足
  • 403 Forbidden: 账户被禁用

架构差异: Server vs Worker ​

组件认证实现缓存存储异步机制
xpdf-server内存 DashMap进程内存tokio::spawn
xpdf-workerDurable Object (AuthDO)DO 状态ctx.waitUntil()

Worker (Cloudflare) 特殊机制 ​

  • AuthDO: Durable Object 实现状态持久化
  • Service Binding: 零延迟内部 RPC 调用 xAdmin
  • Alarm: 定时同步余额和使用量
  • Fail-Open: xAdmin 不可用时默认允许请求

环境变量配置 ​

变量作用默认值
XADMIN_TOKENV1 系统级 Tokencbc637dca6dc48ae83636ff75ef48575
SKIP_XADMIN_VERIFY设置后跳过所有验证未设置

性能对比 ​

特性V1 (同步)V3 (缓存)
首次请求延迟100-300ms100-300ms
后续请求延迟100-300ms< 5ms
xAdmin 压力高 (每次请求)低 (仅缓存未命中)
xAdmin 宕机影响服务不可用5分钟内可用

错误响应 ​

HTTP 状态码触发条件响应体
401 UnauthorizedAuthorization 头缺失或格式错误"Missing Authorization header"
403 ForbiddenxAdmin 验证失败"Authentication Failed or Quota Exceeded"
500 Internal Server ErrorxAdmin 服务不可用 (V1)"Authentication Service Unavailable"

📌 文档版本: 2026-01-04
📌 源文件: api.rs, optimized_v3_auth_design.md, endpoint_v3_auth_flow.md