Jeff Gu
a7c65b9476
在此提交中，我们引入了多语言支持，允许用户根据其语言偏好查看界面文本。新增了国际化库（i18next）并在多个组件中实现了翻译功能，确保错误消息和界面文本能够根据用户的语言设置动态变化。这一改动旨在提升用户体验，使得应用能够服务更广泛的用户群体，增强可访问性和友好性。同时，更新了相关文档以指导开发者如何使用新的国际化功能。
85 lines
4.5 KiB
Markdown
85 lines
4.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
One API on Workers — 基于 Cloudflare Workers 的 AI 统一网关，支持多渠道管理、负载均衡、用量统计。将 OpenAI、Azure OpenAI、Claude、Gemini 等多家 AI 服务商统一为 OpenAI 兼容 API。
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
bun install # 安装所有依赖（Bun workspaces，根目录一次安装包含 frontend）
|
||
bun run dev # 同时启动 Vite 前端 (5173) + Worker 本地 (8788)
|
||
bun run dev:worker # 仅启动 Worker（使用 wrangler.local.jsonc）
|
||
bun run dev:web # 仅启动前端 Vite 开发服务器
|
||
bun run build # 构建前端到 public/（含 tsc 类型检查）
|
||
bun run deploy # 构建 + 部署到 Cloudflare
|
||
bun run cf-typegen # 生成 Cloudflare 绑定类型到 worker-configuration.d.ts
|
||
cd frontend && bun run lint # 前端 ESLint 检查
|
||
```
|
||
|
||
无专用测试框架。`bun run build` 作为基本类型检查；后端变更通过 `bun run dev` 启动后用管理界面的 API 测试页面验证。
|
||
|
||
## Architecture
|
||
|
||
### Tech Stack
|
||
|
||
- **Runtime**: Cloudflare Workers
|
||
- **Backend**: Hono + chanfana (OpenAPI) + Zod
|
||
- **Database**: Cloudflare D1 (SQLite)，自动迁移（`src/db/index.ts` 中 `ensureReady()` 懒初始化）
|
||
- **Analytics**: Cloudflare Analytics Engine（用量统计写入）
|
||
- **Frontend**: React 19 + Vite + TailwindCSS 4 + shadcn/ui + Zustand + TanStack Query + React Router 7
|
||
- **Package Manager**: Bun（workspaces monorepo：根目录 = Worker，`frontend/` = React UI）
|
||
|
||
### Request Flow
|
||
|
||
```
|
||
Client → src/index.ts (Hono app)
|
||
├─ /v1/* → providers/index.ts → UnifiedProxyEndpoint
|
||
│ 1. route-policy.ts: URL → RouteId（决定允许的渠道类型）
|
||
│ 2. channel-resolver.ts: 认证 token → 查可用渠道 → 按权重选取
|
||
│ 3. upstream-retry.ts: 执行请求，支持同渠道重试 + 跨渠道 fallback
|
||
│ 4. provider-registry.ts: 按 ChannelType 分发到具体 proxy 实现
|
||
├─ /api/admin/* → admin/index.ts（管理 API，需 x-admin-token 或 session 认证）
|
||
└─ 其他路径 → 前端静态资源 / Vite dev server 代理
|
||
```
|
||
|
||
### Key Modules
|
||
|
||
- **`src/providers/shared/`**: 核心代理逻辑 — 认证、渠道解析、负载均衡、重试、流式处理
|
||
- **`src/providers/*.ts`**: 各服务商代理实现（统一 `ProviderFetch` 接口）
|
||
- **`src/admin/`**: 管理 API（渠道/令牌/定价/计费/系统配置/认证/统计）
|
||
- **`src/billing.ts`**: 计费精度处理（`BILLING_RAW_SCALE = 1e9`，内部整数运算）
|
||
- **`src/channel-config.ts`**: 渠道配置标准化（`normalizeChannelConfig` / `sanitizeChannelConfig`）
|
||
- **`src/analytics/`**: Analytics Engine 写入 + Cloudflare GraphQL 查询
|
||
- **`type.d.ts`**: 全局类型定义（`CloudflareBindings`, `ChannelConfig`, `ApiTokenData` 等），不需要 import
|
||
|
||
### Frontend Structure
|
||
|
||
- **`frontend/src/pages/`**: 各页面组件（Dashboard、Channels、Tokens、Pricing、UsageLogs 等）
|
||
- **`frontend/src/api/client.ts`**: API 客户端，自动附加 admin token
|
||
- **`frontend/src/store/auth.ts`**: Zustand 认证状态管理
|
||
- **`frontend/src/components/ui/`**: shadcn/ui 基础组件
|
||
- **`frontend/src/lib/`**: 工具函数（计费格式化、渠道模型处理、本地缓存等）
|
||
- 构建输出到 `../public/`，由 Worker 的 `ASSETS` 绑定提供服务
|
||
|
||
### Database
|
||
|
||
D1 表：`channel_config`、`api_token`、`settings`、`admin_login_challenge`、`admin_session`、`admin_rate_limit`。Schema 定义在 `src/db/index.ts`，首次请求自动建表和迁移。版本号在 `src/constants.ts` 的 `DB_VERSION` 中管理。
|
||
|
||
### Configuration
|
||
|
||
- **`wrangler.jsonc`**: 生产部署配置
|
||
- **`wrangler.local.jsonc`**: 本地开发配置（含 `FRONTEND_DEV_SERVER_URL`）
|
||
- **`.dev.vars`**: 本地 secrets（`ADMIN_TOKEN`、`CF_API_TOKEN`、`CF_ACCOUNT_ID`）
|
||
- **`type.d.ts`**: `CloudflareBindings` 定义所有环境绑定
|
||
|
||
## Code Style
|
||
|
||
- 后端 TypeScript 缩进 4 空格，前端 TSX 缩进 2 空格
|
||
- 渠道类型使用字符串字面量（`"openai"`, `"azure-openai"`, `"claude"` 等），定义在 `type.d.ts` 的 `ChannelType`
|
||
- Admin API 路由命名：`src/admin/*_api.ts`
|
||
- Provider 文件命名：`src/providers/{type}-proxy.ts`
|
||
- 新增 Provider 需在 `src/providers/shared/provider-registry.ts` 注册，并在 `route-policy.ts` 的对应 RouteId 中添加类型
|