From 1bd9002af9ad4263a028eed1caac83d8d7c8395f Mon Sep 17 00:00:00 2001 From: litongtongxue Date: Wed, 15 Oct 2025 01:03:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=9D=A2=E6=9B=B4=E6=96=B0=20?= =?UTF-8?q?CLAUDE.md=20=E6=96=87=E6=A1=A3=E4=BB=A5=E5=8F=8D=E6=98=A0?= =?UTF-8?q?=E6=9C=80=E6=96=B0=E4=BB=A3=E7=A0=81=E5=AE=9E=E7=8E=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 更新概要 本次更新全面审查了代码库，将严重过期的 CLAUDE.md 文档更新到与当前实现一致。 ## 主要更新内容 ### 1. 项目概述和架构 - 更新为多平台支持（8种账户类型） - 添加统一调度系统说明 - 补充权限控制、客户端限制、模型黑名单等新功能 ### 2. 服务组件 - 从5个服务扩展到30+个服务的完整列表 - 新增核心转发服务（8个） - 新增账户管理服务（10个） - 新增统一调度器（4个） - 新增核心功能服务（用户管理、定价、Webhook、LDAP等） ### 3. 环境变量配置 - 新增20+个重要环境变量说明 - 添加AWS Bedrock配置 - 添加用户管理、LDAP、Webhook配置说明 ### 4. API端点 - 更新为多路由支持（Claude、Gemini、OpenAI、Droid、Azure） - 新增用户管理端点 - 新增Webhook管理端点 - 新增系统指标端点 ### 5. Redis数据结构 - 扩展为8种账户类型的数据结构 - 添加用户管理、粘性会话、并发控制相关键 - 添加成本统计、Webhook配置相关键 ### 6. 故障排除 - 从4个问题扩展到13个常见问题 - 新增粘性会话、LDAP、Webhook、调度器等问题解决方案 ### 7. CLI工具 - 添加数据导入导出命令 - 添加数据迁移和修复命令 - 添加成本初始化和定价更新命令 ### 8. 新增功能概览章节 - 列出相比旧版本的所有新增功能 - 包括多平台支持、用户权限系统、统一调度、成本监控等 ## 技术细节 - 保持所有现有章节结构 - 使用 Prettier 格式化确保代码风格一致 - 基于实际代码审查（src/services/、src/routes/、config/等） - 确保所有端点、配置项、数据结构与代码实现一致 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 429 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 369 insertions(+), 60 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f57ed7d3..1eac1b03 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,34 +6,87 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 项目概述 -Claude Relay Service 是一个功能完整的 AI API 中转服务，支持 Claude 和 Gemini 双平台。提供多账户管理、API Key 认证、代理配置和现代化 Web 管理界面。该服务作为客户端（如 SillyTavern、Claude Code、Gemini CLI）与 AI API 之间的中间件，提供认证、限流、监控等功能。 +Claude Relay Service 是一个多平台 AI API 中转服务，支持 **Claude (官方/Console)、Gemini、OpenAI Responses (Codex)、AWS Bedrock、Azure OpenAI、Droid (Factory.ai)、CCR** 等多种账户类型。提供完整的多账户管理、API Key 认证、代理配置、用户管理、LDAP认证、Webhook通知和现代化 Web 管理界面。该服务作为客户端（如 Claude Code、Gemini CLI、Codex、Droid CLI、Cherry Studio 等）与 AI API 之间的中间件，提供认证、限流、监控、定价计算、成本统计等功能。 ## 核心架构 ### 关键架构概念 -- **代理认证流**: 客户端用自建API Key → 验证 → 获取Claude账户OAuth token → 转发到Anthropic +- **统一调度系统**: 使用 unifiedClaudeScheduler、unifiedGeminiScheduler、unifiedOpenAIScheduler、droidScheduler 实现跨账户类型的智能调度 +- **多账户类型支持**: 支持 claude-official、claude-console、bedrock、ccr、droid、gemini、openai-responses、azure-openai 等账户类型 +- **代理认证流**: 客户端用自建API Key → 验证 → 统一调度器选择账户 → 获取账户token → 转发到对应API - **Token管理**: 自动监控OAuth token过期并刷新，支持10秒提前刷新策略 -- **代理支持**: 每个Claude账户支持独立代理配置，OAuth token交换也通过代理进行 -- **数据加密**: 敏感数据（refreshToken, accessToken）使用AES加密存储在Redis +- **代理支持**: 每个账户支持独立代理配置，OAuth token交换也通过代理进行 +- **数据加密**: 敏感数据（refreshToken, accessToken, credentials）使用AES加密存储在Redis +- **粘性会话**: 支持会话级别的账户绑定，同一会话使用同一账户，确保上下文连续性 +- **权限控制**: API Key支持权限配置（all/claude/gemini/openai等），控制可访问的服务类型 +- **客户端限制**: 基于User-Agent的客户端识别和限制，支持ClaudeCode、Gemini-CLI等预定义客户端 +- **模型黑名单**: 支持API Key级别的模型访问限制 ### 主要服务组件 -- **claudeRelayService.js**: 核心代理服务，处理请求转发和流式响应 -- **claudeAccountService.js**: Claude账户管理，OAuth token刷新和账户选择 -- **geminiAccountService.js**: Gemini账户管理，Google OAuth token刷新和账户选择 -- **apiKeyService.js**: API Key管理，验证、限流和使用统计 +#### 核心转发服务 + +- **claudeRelayService.js**: Claude官方API转发，处理OAuth认证和流式响应 +- **claudeConsoleRelayService.js**: Claude Console账户转发服务 +- **geminiRelayService.js**: Gemini API转发服务 +- **bedrockRelayService.js**: AWS Bedrock API转发服务 +- **azureOpenaiRelayService.js**: Azure OpenAI API转发服务 +- **droidRelayService.js**: Droid (Factory.ai) API转发服务 +- **ccrRelayService.js**: CCR账户转发服务 +- **openaiResponsesRelayService.js**: OpenAI Responses (Codex) 转发服务 + +#### 账户管理服务 + +- **claudeAccountService.js**: Claude官方账户管理，OAuth token刷新和账户选择 +- **claudeConsoleAccountService.js**: Claude Console账户管理 +- **geminiAccountService.js**: Gemini账户管理，Google OAuth token刷新 +- **bedrockAccountService.js**: AWS Bedrock账户管理 +- **azureOpenaiAccountService.js**: Azure OpenAI账户管理 +- **droidAccountService.js**: Droid账户管理 +- **ccrAccountService.js**: CCR账户管理 +- **openaiResponsesAccountService.js**: OpenAI Responses账户管理 +- **openaiAccountService.js**: OpenAI兼容账户管理 +- **accountGroupService.js**: 账户组管理，支持账户分组和优先级 + +#### 统一调度器 + +- **unifiedClaudeScheduler.js**: Claude多账户类型统一调度（claude-official/console/bedrock/ccr） +- **unifiedGeminiScheduler.js**: Gemini账户统一调度 +- **unifiedOpenAIScheduler.js**: OpenAI兼容服务统一调度 +- **droidScheduler.js**: Droid账户调度 + +#### 核心功能服务 + +- **apiKeyService.js**: API Key管理，验证、限流、使用统计、成本计算 +- **userService.js**: 用户管理系统，支持用户注册、登录、API Key管理 +- **pricingService.js**: 定价服务，模型价格管理和成本计算 +- **costInitService.js**: 成本数据初始化服务 +- **webhookService.js**: Webhook通知服务 +- **webhookConfigService.js**: Webhook配置管理 +- **ldapService.js**: LDAP认证服务 +- **tokenRefreshService.js**: Token自动刷新服务 +- **rateLimitCleanupService.js**: 速率限制状态清理服务 +- **claudeCodeHeadersService.js**: Claude Code客户端请求头处理 + +#### 工具服务 + - **oauthHelper.js**: OAuth工具，PKCE流程实现和代理支持 +- **workosOAuthHelper.js**: WorkOS OAuth集成 +- **openaiToClaude.js**: OpenAI格式到Claude格式的转换 ### 认证和代理流程 -1. 客户端使用自建API Key（cr\_前缀格式）发送请求 -2. authenticateApiKey中间件验证API Key有效性和速率限制 -3. claudeAccountService自动选择可用Claude账户 -4. 检查OAuth access token有效性，过期则自动刷新（使用代理） -5. 移除客户端API Key，使用OAuth Bearer token转发请求 -6. 通过账户配置的代理发送到Anthropic API -7. 流式或非流式返回响应，记录使用统计 +1. 客户端使用自建API Key（cr\_前缀格式）发送请求到对应路由（/api、/claude、/gemini、/openai、/droid等） +2. **authenticateApiKey中间件**验证API Key有效性、速率限制、权限、客户端限制、模型黑名单 +3. **统一调度器**（如 unifiedClaudeScheduler）根据请求模型、会话hash、API Key权限选择最优账户 +4. 检查选中账户的token有效性，过期则自动刷新（使用代理） +5. 根据账户类型调用对应的转发服务（claudeRelayService、geminiRelayService等） +6. 移除客户端API Key，使用账户凭据（OAuth Bearer token、API Key等）转发请求 +7. 通过账户配置的代理发送到目标API（Anthropic、Google、AWS等） +8. 流式或非流式返回响应，捕获真实usage数据 +9. 记录使用统计（input/output/cache_create/cache_read tokens）和成本计算 +10. 更新速率限制计数器和并发控制 ### OAuth集成 @@ -42,6 +95,51 @@ Claude Relay Service 是一个功能完整的 AI API 中转服务，支持 Claud - **代理支持**: OAuth授权和token交换全程支持代理配置 - **安全存储**: claudeAiOauth数据加密存储，包含accessToken、refreshToken、scopes +## 新增功能概览（相比旧版本） + +### 多平台支持 + +- ✅ **Claude Console账户**: 支持Claude Console类型账户 +- ✅ **AWS Bedrock**: 完整的AWS Bedrock API支持 +- ✅ **Azure OpenAI**: Azure OpenAI服务支持 +- ✅ **Droid (Factory.ai)**: Factory.ai API支持 +- ✅ **CCR账户**: CCR凭据支持 +- ✅ **OpenAI兼容**: OpenAI格式转换和Responses格式支持 + +### 用户和权限系统 + +- ✅ **用户管理**: 完整的用户注册、登录、API Key管理系统 +- ✅ **LDAP认证**: 企业级LDAP/Active Directory集成 +- ✅ **权限控制**: API Key级别的服务权限（all/claude/gemini/openai） +- ✅ **客户端限制**: 基于User-Agent的客户端识别和限制 +- ✅ **模型黑名单**: API Key级别的模型访问控制 + +### 统一调度和会话管理 + +- ✅ **统一调度器**: 跨账户类型的智能调度系统 +- ✅ **粘性会话**: 会话级账户绑定，支持自动续期 +- ✅ **并发控制**: Redis Sorted Set实现的并发限制 +- ✅ **负载均衡**: 自动账户选择和故障转移 + +### 成本和监控 + +- ✅ **定价服务**: 模型价格管理和自动成本计算 +- ✅ **成本统计**: 详细的token使用和费用统计 +- ✅ **缓存监控**: 全局缓存统计和命中率分析 +- ✅ **实时指标**: 可配置窗口的实时统计（METRICS_WINDOW） + +### Webhook和通知 + +- ✅ **Webhook系统**: 事件通知和Webhook配置管理 +- ✅ **多URL支持**: 支持多个Webhook URL（逗号分隔） + +### 高级功能 + +- ✅ **529错误处理**: 自动识别Claude过载状态并暂时排除账户 +- ✅ **HTTP调试**: DEBUG_HTTP_TRAFFIC模式详细记录HTTP请求/响应 +- ✅ **数据迁移**: 完整的数据导入导出工具（含加密/脱敏） +- ✅ **自动清理**: 并发计数、速率限制、临时错误状态自动清理 + ## 常用命令 ### 基本开发命令 @@ -69,19 +167,47 @@ npm run service:logs # 查看日志 npm run service:stop # 停止服务 ### 开发环境配置 -必须配置的环境变量： + +#### 必须配置的环境变量 - `JWT_SECRET`: JWT密钥（32字符以上随机字符串） - `ENCRYPTION_KEY`: 数据加密密钥（32字符固定长度） - `REDIS_HOST`: Redis主机地址（默认localhost） - `REDIS_PORT`: Redis端口（默认6379） - `REDIS_PASSWORD`: Redis密码（可选） -初始化命令： +#### 新增重要环境变量（可选） +- `USER_MANAGEMENT_ENABLED`: 启用用户管理系统（默认false） +- `LDAP_ENABLED`: 启用LDAP认证（默认false） +- `LDAP_URL`: LDAP服务器地址（如 ldaps://ldap.example.com:636） +- `LDAP_TLS_REJECT_UNAUTHORIZED`: LDAP证书验证（默认true） +- `WEBHOOK_ENABLED`: 启用Webhook通知（默认true） +- `WEBHOOK_URLS`: Webhook通知URL列表（逗号分隔） +- `CLAUDE_OVERLOAD_HANDLING_MINUTES`: Claude 529错误处理持续时间（分钟，0表示禁用） +- `STICKY_SESSION_TTL_HOURS`: 粘性会话TTL（小时，默认1） +- `STICKY_SESSION_RENEWAL_THRESHOLD_MINUTES`: 粘性会话续期阈值（分钟，默认0） +- `METRICS_WINDOW`: 实时指标统计窗口（分钟，1-60，默认5） +- `MAX_API_KEYS_PER_USER`: 每用户最大API Key数量（默认1） +- `ALLOW_USER_DELETE_API_KEYS`: 允许用户删除自己的API Keys（默认false） +- `DEBUG_HTTP_TRAFFIC`: 启用HTTP请求/响应调试日志（默认false，仅开发环境） +- `PROXY_USE_IPV4`: 代理使用IPv4（默认true） +- `REQUEST_TIMEOUT`: 请求超时时间（毫秒，默认600000即10分钟） + +#### AWS Bedrock配置（可选） +- `CLAUDE_CODE_USE_BEDROCK`: 启用Bedrock（设置为1启用） +- `AWS_REGION`: AWS默认区域（默认us-east-1） +- `ANTHROPIC_MODEL`: Bedrock默认模型 +- `ANTHROPIC_SMALL_FAST_MODEL`: Bedrock小型快速模型 +- `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION`: 小型模型区域 +- `CLAUDE_CODE_MAX_OUTPUT_TOKENS`: 最大输出tokens（默认4096） +- `MAX_THINKING_TOKENS`: 最大思考tokens（默认1024） +- `DISABLE_PROMPT_CACHING`: 禁用提示缓存（设置为1禁用） + +#### 初始化命令 ```bash cp config/config.example.js config/config.js cp .env.example .env npm run setup # 自动生成密钥并创建管理员账户 -```` +``` ## Web界面功能 @@ -95,31 +221,82 @@ npm run setup # 自动生成密钥并创建管理员账户 ### 核心管理功能 -- **实时仪表板**: 系统统计、账户状态、使用量监控 -- **API Key管理**: 创建、配额设置、使用统计查看 -- **Claude账户管理**: OAuth账户添加、代理配置、状态监控 -- **系统日志**: 实时日志查看，多级别过滤 +- **实时仪表板**: 系统统计、账户状态、使用量监控、实时指标（METRICS_WINDOW配置窗口） +- **API Key管理**: 创建、配额设置、使用统计查看、权限配置、客户端限制、模型黑名单 +- **多平台账户管理**: + - Claude账户（官方/Console）: OAuth账户添加、代理配置、状态监控 + - Gemini账户: Google OAuth授权、代理配置 + - OpenAI Responses (Codex)账户: API Key配置 + - AWS Bedrock账户: AWS凭据配置 + - Azure OpenAI账户: Azure凭据和端点配置 + - Droid账户: Factory.ai API Key配置 + - CCR账户: CCR凭据配置 +- **用户管理**: 用户注册、登录、API Key分配（USER_MANAGEMENT_ENABLED启用时） +- **系统日志**: 实时日志查看，多级别过滤，HTTP调试日志（DEBUG_HTTP_TRAFFIC启用时） +- **Webhook配置**: Webhook URL管理、事件配置 - **主题系统**: 支持明亮/暗黑模式切换，自动保存用户偏好设置 +- **成本分析**: 详细的token使用和成本统计（基于pricingService） +- **缓存监控**: 解密缓存统计和性能监控 ## 重要端点 -### API转发端点 +### API转发端点（多路由支持） -- `POST /api/v1/messages` - 主要消息处理端点（支持流式） -- `GET /api/v1/models` - 模型列表（兼容性） +#### Claude服务路由 +- `POST /api/v1/messages` - Claude消息处理（支持流式） +- `POST /claude/v1/messages` - Claude消息处理（别名路由） +- `POST /v1/messages/count_tokens` - Token计数Beta API +- `GET /api/v1/models` - 模型列表 - `GET /api/v1/usage` - 使用统计查询 - `GET /api/v1/key-info` - API Key信息 +- `GET /v1/me` - 用户信息（Claude Code客户端需要） +- `GET /v1/organizations/:org_id/usage` - 组织使用统计 -### OAuth管理端点 +#### Gemini服务路由 +- `POST /gemini/v1/models/:model:generateContent` - 标准Gemini API格式 +- `POST /gemini/v1/models/:model:streamGenerateContent` - Gemini流式 +- `GET /gemini/v1/models` - Gemini模型列表 +- 其他Gemini兼容路由（保持向后兼容） +#### OpenAI兼容路由 +- `POST /openai/v1/chat/completions` - OpenAI格式转发（支持responses格式） +- `POST /openai/claude/v1/chat/completions` - OpenAI格式转Claude +- `POST /openai/gemini/v1/chat/completions` - OpenAI格式转Gemini +- `GET /openai/v1/models` - OpenAI格式模型列表 + +#### Droid (Factory.ai) 路由 +- `POST /droid/claude/v1/messages` - Droid Claude转发 +- `POST /droid/openai/v1/chat/completions` - Droid OpenAI转发 + +#### Azure OpenAI 路由 +- `POST /azure/...` - Azure OpenAI API转发 + +### 管理端点 + +#### OAuth和账户管理 - `POST /admin/claude-accounts/generate-auth-url` - 生成OAuth授权URL（含代理） - `POST /admin/claude-accounts/exchange-code` - 交换authorization code -- `POST /admin/claude-accounts` - 创建OAuth账户 +- `POST /admin/claude-accounts` - 创建Claude OAuth账户 +- 各平台账户CRUD端点（gemini、openai、bedrock、azure、droid、ccr） + +#### 用户管理（USER_MANAGEMENT_ENABLED启用时） +- `POST /users/register` - 用户注册 +- `POST /users/login` - 用户登录 +- `GET /users/profile` - 用户资料 +- `POST /users/api-keys` - 创建用户API Key + +#### Webhook管理 +- `GET /admin/webhook/configs` - 获取Webhook配置 +- `POST /admin/webhook/configs` - 创建Webhook配置 +- `PUT /admin/webhook/configs/:id` - 更新Webhook配置 +- `DELETE /admin/webhook/configs/:id` - 删除Webhook配置 ### 系统端点 -- `GET /health` - 健康检查 -- `GET /web` - Web管理界面 +- `GET /health` - 健康检查（包含组件状态、版本、内存等） +- `GET /metrics` - 系统指标（使用统计、uptime、内存） +- `GET /web` - 传统Web管理界面 +- `GET /admin-next/` - 新版SPA管理界面（主界面） - `GET /admin/dashboard` - 系统概览数据 ## 故障排除 @@ -138,17 +315,43 @@ npm run setup # 自动生成密钥并创建管理员账户 ### 常见开发问题 -1. **Redis连接失败**: 确认Redis服务运行，检查连接配置 -2. **管理员登录失败**: 检查init.json同步到Redis，运行npm run setup -3. **API Key格式错误**: 确保使用cr\_前缀格式 -4. **代理连接问题**: 验证SOCKS5/HTTP代理配置和认证信息 +1. **Redis连接失败**: 确认Redis服务运行，检查REDIS_HOST、REDIS_PORT、REDIS_PASSWORD配置 +2. **管理员登录失败**: 检查data/init.json存在，运行npm run setup重新初始化 +3. **API Key格式错误**: 确保使用cr\_前缀格式（可通过API_KEY_PREFIX配置修改） +4. **代理连接问题**: 验证SOCKS5/HTTP代理配置和认证信息，检查PROXY_USE_IPV4设置 +5. **粘性会话失效**: 检查Redis中session数据，确认STICKY_SESSION_TTL_HOURS配置，通过Nginx代理时需添加 `underscores_in_headers on;` +6. **LDAP认证失败**: + - 检查LDAP_URL、LDAP_BIND_DN、LDAP_BIND_PASSWORD配置 + - 自签名证书问题：设置 LDAP_TLS_REJECT_UNAUTHORIZED=false + - 查看日志中的LDAP连接错误详情 +7. **用户管理功能不可用**: 确认USER_MANAGEMENT_ENABLED=true，检查userService初始化 +8. **Webhook通知失败**: + - 确认WEBHOOK_ENABLED=true + - 检查WEBHOOK_URLS格式（逗号分隔） + - 查看logs/webhook-*.log日志 +9. **统一调度器选择账户失败**: + - 检查账户状态（status: 'active'） + - 确认账户类型与请求路由匹配 + - 查看粘性会话绑定情况 +10. **并发计数泄漏**: 系统每分钟自动清理过期并发计数（concurrency cleanup task），重启时也会自动清理 +11. **速率限制未清理**: rateLimitCleanupService每5分钟自动清理过期限流状态 +12. **成本统计不准确**: 运行 `npm run init:costs` 初始化成本数据，检查pricingService是否正确加载模型价格 +13. **缓存命中率低**: 查看缓存监控统计，调整LRU缓存大小配置 ### 调试工具 -- **日志系统**: Winston结构化日志，支持不同级别 -- **CLI工具**: 命令行状态查看和管理 -- **Web界面**: 实时日志查看和系统监控 -- **健康检查**: /health端点提供系统状态 +- **日志系统**: Winston结构化日志，支持不同级别，logs/目录下分类存储 + - `logs/claude-relay-*.log` - 应用主日志 + - `logs/token-refresh-error.log` - Token刷新错误 + - `logs/webhook-*.log` - Webhook通知日志 + - `logs/http-debug-*.log` - HTTP调试日志（DEBUG_HTTP_TRAFFIC=true时） +- **CLI工具**: 命令行状态查看和管理（npm run cli） +- **Web界面**: 实时日志查看和系统监控（/admin-next/） +- **健康检查**: /health端点提供系统状态（redis、logger、内存、版本等） +- **系统指标**: /metrics端点提供详细的使用统计和性能指标 +- **缓存监控**: cacheMonitor提供全局缓存统计和命中率分析 +- **数据导出工具**: npm run data:export 导出Redis数据进行调试 +- **Redis Key调试**: npm run data:debug 查看所有Redis键 ## 开发最佳实践 @@ -197,23 +400,57 @@ npm run setup # 自动生成密钥并创建管理员账户 ### 常见文件位置 -- 核心服务逻辑：`src/services/` 目录 -- 路由处理：`src/routes/` 目录 -- 中间件：`src/middleware/` 目录 -- 配置管理：`config/config.js` +- 核心服务逻辑：`src/services/` 目录（30+服务文件） +- 路由处理：`src/routes/` 目录（api.js、admin.js、geminiRoutes.js、openaiRoutes.js等13个路由文件） +- 中间件：`src/middleware/` 目录（auth.js、browserFallback.js、debugInterceptor.js等） +- 配置管理：`config/config.js`（完整的多平台配置） - Redis 模型：`src/models/redis.js` - 工具函数：`src/utils/` 目录 + - `logger.js` - 日志系统 + - `oauthHelper.js` - OAuth工具 + - `proxyHelper.js` - 代理工具 + - `sessionHelper.js` - 会话管理 + - `cacheMonitor.js` - 缓存监控 + - `costCalculator.js` - 成本计算 + - `rateLimitHelper.js` - 速率限制 + - `webhookNotifier.js` - Webhook通知 + - `tokenMask.js` - Token脱敏 + - `workosOAuthHelper.js` - WorkOS OAuth + - `modelHelper.js` - 模型工具 + - `inputValidator.js` - 输入验证 +- CLI工具：`cli/index.js` 和 `src/cli/` 目录 +- 脚本目录：`scripts/` 目录 + - `setup.js` - 初始化脚本 + - `manage.js` - 服务管理 + - `migrate-apikey-expiry.js` - API Key过期迁移 + - `fix-usage-stats.js` - 使用统计修复 + - `data-transfer.js` / `data-transfer-enhanced.js` - 数据导入导出 + - `update-model-pricing.js` - 模型价格更新 + - `test-pricing-fallback.js` - 价格回退测试 + - `debug-redis-keys.js` - Redis调试 - 前端主题管理：`web/admin-spa/src/stores/theme.js` - 前端组件：`web/admin-spa/src/components/` 目录 - 前端页面：`web/admin-spa/src/views/` 目录 +- 初始化数据：`data/init.json`（管理员凭据存储） +- 日志目录：`logs/`（各类日志文件） ### 重要架构决策 -- 所有敏感数据（OAuth token、refreshToken）都使用 AES 加密存储在 Redis -- 每个 Claude 账户支持独立的代理配置，包括 SOCKS5 和 HTTP 代理 -- API Key 使用哈希存储，支持 `cr_` 前缀格式 -- 请求流程：API Key 验证 → 账户选择 → Token 刷新（如需）→ 请求转发 -- 支持流式和非流式响应，客户端断开时自动清理资源 +- **统一调度系统**: 使用统一调度器（unifiedClaudeScheduler等）实现跨账户类型的智能调度，支持粘性会话、负载均衡、故障转移 +- **多账户类型支持**: 支持8种账户类型（claude-official、claude-console、bedrock、ccr、droid、gemini、openai-responses、azure-openai） +- **加密存储**: 所有敏感数据（OAuth token、refreshToken、credentials）都使用 AES 加密存储在 Redis +- **独立代理**: 每个账户支持独立的代理配置（SOCKS5/HTTP），包括OAuth授权流程 +- **API Key哈希**: 使用SHA-256哈希存储，支持自定义前缀（默认 `cr_`） +- **权限系统**: API Key支持细粒度权限控制（all/claude/gemini/openai等） +- **请求流程**: API Key验证（含权限、客户端、模型黑名单） → 统一调度器选择账户 → Token刷新（如需）→ 请求转发 → Usage捕获 → 成本计算 +- **流式响应**: 支持SSE流式响应，实时捕获真实usage数据，客户端断开时自动清理资源（AbortController） +- **粘性会话**: 基于请求内容hash的会话绑定，同一会话始终使用同一账户，支持自动续期 +- **自动清理**: 定时清理任务（过期Key、错误账户、临时错误、并发计数、速率限制状态） +- **缓存优化**: 多层LRU缓存（解密缓存、账户缓存），全局缓存监控和统计 +- **成本追踪**: 实时token使用统计（input/output/cache_create/cache_read）和成本计算（基于pricingService） +- **并发控制**: Redis Sorted Set实现的并发计数，支持自动过期清理 +- **客户端识别**: 基于User-Agent的客户端限制，支持预定义客户端（ClaudeCode、Gemini-CLI等） +- **错误处理**: 529错误自动标记账户过载状态，配置时长内自动排除该账户 ### 核心数据流和性能优化 @@ -235,36 +472,107 @@ npm run setup # 自动生成密钥并创建管理员账户 ### Redis 数据结构 -- **API Keys**: `api_key:{id}` (详细信息) + `api_key_hash:{hash}` (快速查找) -- **Claude 账户**: `claude_account:{id}` (加密的 OAuth 数据) -- **管理员**: `admin:{id}` + `admin_username:{username}` (用户名映射) -- **会话**: `session:{token}` (JWT 会话管理) -- **使用统计**: `usage:daily:{date}:{key}:{model}` (多维度统计) -- **系统信息**: `system_info` (系统状态缓存) +- **API Keys**: + - `api_key:{id}` - API Key详细信息（含权限、客户端限制、模型黑名单等） + - `api_key_hash:{hash}` - 哈希到ID的快速映射 + - `api_key_usage:{keyId}` - 使用统计数据 + - `api_key_cost:{keyId}` - 成本统计数据 +- **账户数据**（多类型）: + - `claude_account:{id}` - Claude官方账户（加密的OAuth数据） + - `claude_console_account:{id}` - Claude Console账户 + - `gemini_account:{id}` - Gemini账户 + - `openai_responses_account:{id}` - OpenAI Responses账户 + - `bedrock_account:{id}` - AWS Bedrock账户 + - `azure_openai_account:{id}` - Azure OpenAI账户 + - `droid_account:{id}` - Droid账户 + - `ccr_account:{id}` - CCR账户 +- **用户管理**: + - `user:{id}` - 用户信息 + - `user_email:{email}` - 邮箱到用户ID映射 + - `user_session:{token}` - 用户会话 +- **管理员**: + - `admin:{id}` - 管理员信息 + - `admin_username:{username}` - 用户名映射 + - `admin_credentials` - 管理员凭据（从data/init.json同步） +- **会话管理**: + - `session:{token}` - JWT会话管理 + - `sticky_session:{sessionHash}` - 粘性会话账户绑定 + - `session_window:{accountId}` - 账户会话窗口 +- **使用统计**: + - `usage:daily:{date}:{key}:{model}` - 按日期、Key、模型的使用统计 + - `usage:account:{accountId}:{date}` - 按账户的使用统计 + - `usage:global:{date}` - 全局使用统计 +- **速率限制**: + - `rate_limit:{keyId}:{window}` - 速率限制计数器 + - `rate_limit_state:{accountId}` - 账户限流状态 + - `overload:{accountId}` - 账户过载状态（529错误） +- **并发控制**: + - `concurrency:{accountId}` - Redis Sorted Set实现的并发计数 +- **Webhook配置**: + - `webhook_config:{id}` - Webhook配置 +- **系统信息**: + - `system_info` - 系统状态缓存 + - `model_pricing` - 模型价格数据（pricingService） ### 流式响应处理 -- 支持 SSE (Server-Sent Events) 流式传输 -- 自动从流中解析 usage 数据并记录 -- 客户端断开时通过 AbortController 清理资源 -- 错误时发送适当的 SSE 错误事件 +- 支持 SSE (Server-Sent Events) 流式传输，实时推送响应数据 +- 自动从SSE流中解析真实usage数据（input/output/cache_create/cache_read tokens） +- 客户端断开时通过 AbortController 清理资源和并发计数 +- 错误时发送适当的 SSE 错误事件（带时间戳和错误类型） +- 支持大文件流式传输（REQUEST_TIMEOUT配置超时时间） +- 禁用Nagle算法确保数据立即发送（socket.setNoDelay） +- 设置 `X-Accel-Buffering: no` 禁用Nginx缓冲 ### CLI 工具使用示例 ```bash -# 创建新的 API Key +# API Key管理 npm run cli keys create -- --name "MyApp" --limit 1000 +npm run cli keys list +npm run cli keys delete -- --id +npm run cli keys update -- --id --limit 2000 -# 查看系统状态 -npm run cli status +# 系统状态查看 +npm run cli status # 查看系统概况 +npm run status # 统一状态脚本 +npm run status:detail # 详细状态 -# 管理 Claude 账户 +# Claude账户管理 npm run cli accounts list npm run cli accounts refresh +npm run cli accounts add -- --name "Account1" + +# Gemini账户管理 +npm run cli gemini list +npm run cli gemini add -- --name "Gemini1" # 管理员操作 npm run cli admin create -- --username admin2 npm run cli admin reset-password -- --username admin +npm run cli admin list + +# 数据管理 +npm run data:export # 导出Redis数据 +npm run data:export:sanitized # 导出脱敏数据 +npm run data:export:enhanced # 增强导出（含解密） +npm run data:export:encrypted # 导出加密数据 +npm run data:import # 导入数据 +npm run data:import:enhanced # 增强导入 +npm run data:debug # 调试Redis键 + +# 数据迁移和修复 +npm run migrate:apikey-expiry # API Key过期时间迁移 +npm run migrate:apikey-expiry:dry # 干跑模式 +npm run migrate:fix-usage-stats # 修复使用统计 + +# 成本和定价 +npm run init:costs # 初始化成本数据 +npm run update:pricing # 更新模型价格 +npm run test:pricing-fallback # 测试价格回退 + +# 监控 +npm run monitor # 增强监控脚本 ``` # important-instruction-reminders @@ -273,3 +581,4 @@ Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (\*.md) or README files. Only create documentation files if explicitly requested by the User. +````