first commit

CLAUDE.md

@@ -0,0 +1,181 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+这个文件为 Claude Code (claude.ai/code) 提供在此代码库中工作的指导。
+
+## 项目概述
+
+Claude Relay Service 是一个功能完整的 Claude API 中转服务，支持多账户管理、API Key 认证、代理配置和现代化 Web 管理界面。该服务作为客户端（如 SillyTavern）与 Anthropic API 之间的中间件，提供认证、限流、监控等功能。
+
+## 核心架构
+
+### 关键架构概念
+- **代理认证流**: 客户端用自建API Key → 验证 → 获取Claude账户OAuth token → 转发到Anthropic
+- **Token管理**: 自动监控OAuth token过期并刷新，支持10秒提前刷新策略
+- **代理支持**: 每个Claude账户支持独立代理配置，OAuth token交换也通过代理进行
+- **数据加密**: 敏感数据（refreshToken, accessToken）使用AES加密存储在Redis
+
+### 主要服务组件
+- **claudeRelayService.js**: 核心代理服务，处理请求转发和流式响应
+- **claudeAccountService.js**: Claude账户管理，OAuth token刷新和账户选择
+- **apiKeyService.js**: API Key管理，验证、限流和使用统计
+- **oauthHelper.js**: OAuth工具，PKCE流程实现和代理支持
+
+### 认证和代理流程
+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. 流式或非流式返回响应，记录使用统计
+
+### OAuth集成
+- **PKCE流程**: 完整的OAuth 2.0 PKCE实现，支持代理
+- **自动刷新**: 智能token过期检测和自动刷新机制
+- **代理支持**: OAuth授权和token交换全程支持代理配置
+- **安全存储**: claudeAiOauth数据加密存储，包含accessToken、refreshToken、scopes
+
+## 常用命令
+
+### 基本开发命令
+```bash
+# 安装依赖和初始化
+npm install
+npm run setup                  # 生成配置和管理员凭据
+npm run install:web           # 安装Web界面依赖
+
+# 开发和运行
+npm run dev                   # 开发模式（热重载）
+npm start                     # 生产模式
+npm test                      # 运行测试
+npm run lint                  # 代码检查
+
+# Docker部署
+docker-compose up -d          # 推荐方式
+docker-compose --profile monitoring up -d  # 包含监控
+
+# 服务管理
+npm run service:start:daemon  # 后台启动（推荐）
+npm run service:status        # 查看服务状态
+npm run service:logs          # 查看日志
+npm run service:stop          # 停止服务
+
+# CLI管理工具
+npm run cli admin             # 管理员操作
+npm run cli keys              # API Key管理
+npm run cli accounts          # Claude账户管理
+npm run cli status            # 系统状态
+```
+
+### 开发环境配置
+必须配置的环境变量：
+- `JWT_SECRET`: JWT密钥（32字符以上随机字符串）
+- `ENCRYPTION_KEY`: 数据加密密钥（32字符固定长度）
+- `REDIS_HOST`: Redis主机地址（默认localhost）
+- `REDIS_PORT`: Redis端口（默认6379）
+- `REDIS_PASSWORD`: Redis密码（可选）
+
+初始化命令：
+```bash
+cp config/config.example.js config/config.js
+cp .env.example .env
+npm run setup  # 自动生成密钥并创建管理员账户
+```
+
+## Web界面功能
+
+### OAuth账户添加流程
+1. **基本信息和代理设置**: 配置账户名称、描述和代理参数
+2. **OAuth授权**: 
+   - 生成授权URL → 用户打开链接并登录Claude Code账号
+   - 授权后会显示Authorization Code → 复制并粘贴到输入框
+   - 系统自动交换token并创建账户
+
+### 核心管理功能
+- **实时仪表板**: 系统统计、账户状态、使用量监控
+- **API Key管理**: 创建、配额设置、使用统计查看
+- **Claude账户管理**: OAuth账户添加、代理配置、状态监控
+- **系统日志**: 实时日志查看，多级别过滤
+
+## 重要端点
+
+### API转发端点
+- `POST /api/v1/messages` - 主要消息处理端点（支持流式）
+- `GET /api/v1/models` - 模型列表（兼容性）
+- `GET /api/v1/usage` - 使用统计查询
+- `GET /api/v1/key-info` - API Key信息
+
+### OAuth管理端点
+- `POST /admin/claude-accounts/generate-auth-url` - 生成OAuth授权URL（含代理）
+- `POST /admin/claude-accounts/exchange-code` - 交换authorization code
+- `POST /admin/claude-accounts` - 创建OAuth账户
+
+### 系统端点
+- `GET /health` - 健康检查
+- `GET /web` - Web管理界面
+- `GET /admin/dashboard` - 系统概览数据
+
+## 故障排除
+
+### OAuth相关问题
+1. **代理配置错误**: 检查代理设置是否正确，OAuth token交换也需要代理
+2. **授权码无效**: 确保复制了完整的Authorization Code，没有遗漏字符
+3. **Token刷新失败**: 检查refreshToken有效性和代理配置
+
+### 常见开发问题
+1. **Redis连接失败**: 确认Redis服务运行，检查连接配置
+2. **管理员登录失败**: 检查init.json同步到Redis，运行npm run setup
+3. **API Key格式错误**: 确保使用cr_前缀格式
+4. **代理连接问题**: 验证SOCKS5/HTTP代理配置和认证信息
+
+### 调试工具
+- **日志系统**: Winston结构化日志，支持不同级别
+- **CLI工具**: 命令行状态查看和管理
+- **Web界面**: 实时日志查看和系统监控
+- **健康检查**: /health端点提供系统状态
+
+## 开发最佳实践
+
+### 代码修改原则
+- 对现有文件进行修改时，首先检查代码库的现有模式和风格
+- 尽可能重用现有的服务和工具函数，避免重复代码
+- 遵循项目现有的错误处理和日志记录模式
+- 敏感数据必须使用加密存储（参考 claudeAccountService.js 中的加密实现）
+
+### 测试和质量保证
+- 运行 `npm run lint` 进行代码风格检查（使用 ESLint）
+- 运行 `npm test` 执行测试套件（Jest + SuperTest 配置）
+- 在修改核心服务后，使用 CLI 工具验证功能：`npm run cli status`
+- 检查日志文件 `logs/claude-relay-*.log` 确认服务正常运行
+- 注意：当前项目缺少实际测试文件，建议补充单元测试和集成测试
+
+### 常见文件位置
+- 核心服务逻辑：`src/services/` 目录
+- 路由处理：`src/routes/` 目录 
+- 中间件：`src/middleware/` 目录
+- 配置管理：`config/config.js`
+- Redis 模型：`src/models/redis.js`
+- 工具函数：`src/utils/` 目录
+
+### 重要架构决策
+- 所有敏感数据（OAuth token、refreshToken）都使用 AES 加密存储在 Redis
+- 每个 Claude 账户支持独立的代理配置，包括 SOCKS5 和 HTTP 代理
+- API Key 使用哈希存储，支持 `cr_` 前缀格式
+- 请求流程：API Key 验证 → 账户选择 → Token 刷新（如需）→ 请求转发
+- 支持流式和非流式响应，客户端断开时自动清理资源
+
+### 核心数据流和性能优化
+- **哈希映射优化**: API Key 验证从 O(n) 优化到 O(1) 查找
+- **智能 Usage 捕获**: 从 SSE 流中解析真实的 token 使用数据
+- **多维度统计**: 支持按时间、模型、用户的实时使用统计
+- **异步处理**: 非阻塞的统计记录和日志写入
+- **原子操作**: Redis 管道操作确保数据一致性
+
+### 安全和容错机制
+- **多层加密**: API Key 哈希 + OAuth Token AES 加密
+- **零信任验证**: 每个请求都需要完整的认证链
+- **优雅降级**: Redis 连接失败时的回退机制
+- **自动重试**: 指数退避重试策略和错误隔离
+- **资源清理**: 客户端断开时的自动清理机制