{"owner":"Wei-Shaw","repo":"claude-relay-service","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## 项目概述\n\nClaude Relay Service — 多平台 AI API 中转服务，作为客户端与上游 AI API 之间的中间件。\n支持 Claude (官方/Console)、Gemini、OpenAI Responses、AWS Bedrock、Azure OpenAI、Droid、CCR 等账户类型。\n核心能力：多账户管理、API Key 认证、统一调度、代理配置、限流、成本统计。\n\n## 架构原则\n\n### Clean Architecture 分层映射\n\n| 层级 | 目录 | 职责 |\n|------|------|------|\n| **框架层** | `src/routes/`, `src/middleware/` | HTTP 路由、请求验证、响应格式化 |\n| **接口适配层** | `src/handlers/`, `src/services/openaiToClaude.js` | 请求/响应格式转换 |\n| **用例层** | `src/services/*Scheduler.js`, `*RelayService.js` | 调度逻辑、转发编排 |\n| **实体层** | `src/services/*AccountService.js`, `src/models/` | 账户管理、数据模型 |\n| **基础设施层** | `src/utils/`, `config/` | 日志、缓存、加密、代理 |\n\n### 开发原则\n\n- **依赖方向**: 外层 → 内层，内层不知道外层存在\n- **新增路由**: 只做参数提取和响应格式化，业务逻辑放 service\n- **新增服务**: 先确定属于哪一层，遵循该层职责边界\n- **格式转换**: 不同 API 格式的转换放 handlers 或专用转换服务\n- **数据访问**: 通过 `src/models/redis.js` 统一访问\n\n### 安全约束\n\n- 敏感数据（OAuth token、refreshToken、credentials）必须 AES 加密存储（参考 `claudeAccountService.js`）\n- API Key 使用 SHA-256 哈希存储，禁止明文\n- 每个请求必须经过完整认证链（API Key → 权限 → 客户端限制 → 模型黑名单）\n- 客户端断开时必须通过 AbortController 清理资源和并发计数\n- 日志中禁止输出完整 token，使用 `tokenMask.js` 脱敏\n\n## 项目结构\n\n```\nsrc/\n├── routes/              # HTTP 路由\n│   ├── api.js           # Claude API 主路由\n│   ├── admin/           # 管理后台路由（24个子文件）\n│   ├── geminiRoutes.js, standardGeminiRoutes.js\n│   ├── openaiRoutes.js, openaiClaudeRoutes.js, openaiGeminiRoutes.js\n│   ├── azureOpenaiRoutes.js, droidRoutes.js\n│   ├── userRoutes.js, webhook.js, unified.js, apiStats.js, web.js\n├── middleware/           # auth.js(认证/权限/限流), browserFallback.js\n├── handlers/             # geminiHandlers.js\n├── services/             # 业务服务\n│   ├── relay/                 # 各平台转发服务（9个）\n│   ├── account/               # 各平台账户管理（11个）\n│   ├── scheduler/             # 统一调度器（4个）\n│   ├── apiKeyService.js       # API Key 管理\n│   ├── pricingService.js      # 定价和成本\n│   └── ...                    # 其余 ~30 个业务服务\n├── models/redis.js       # Redis 数据模型\n├── utils/                # 35+ 工具文件（logger, proxy, oauth, cache, stream...）\nconfig/config.js          # 主配置\nscripts/                  # 运维脚本\ncli/                      # CLI 工具\nweb/admin-spa/            # Vue SPA 管理界面\ndata/init.json            # 管理员凭据\n```\n\n## 核心请求流程\n\n```\n客户端(cr_前缀Key) → 路由 → auth中间件(验证/权限/限流/模型黑名单)\n  → 统一调度器(选账户/粘性会话) → Token检查/刷新\n  → 转发服务(通过代理发送) → 上游API\n  → 流式/非流式响应 → Usage捕获 → 成本计算 → 返回客户端\n```\n\n关键机制：\n- **粘性会话**: 基于请求内容 hash 绑定账户，同一会话用同一账户\n- **并发控制**: Redis Sorted Set 实现，支持排队等待（非直接 429）\n- **529 处理**: 自动标记过载账户，配置时长内排除\n- **加密存储**: 敏感数据（OAuth token、credentials）AES 加密存于 Redis\n- **流式响应**: SSE 传输，实时捕获 usage，客户端断开时 AbortController 清理资源\n\n## 开发规范\n\n### 代码风格\n\n- **无分号**、**单引号**、**100字符行宽**、**尾逗号 none**、**箭头函数始终加括号**\n- 强制 `const`（`no-var`、`prefer-const`），严格相等（`eqeqeq`）\n- 下划线前缀变量 `_var` 可豁免 unused 检查\n- **必须使用 Prettier**: `npx prettier --write <file>`\n- 前端额外安装了 `prettier-plugin-tailwindcss`\n\n### 开发工作流\n\n1. **理解现有代码** → 读相关文件，了解现有模式\n2. **编写代码** → 重用已有服务和工具函数\n3. **格式化** → `npx prettier --write <修改的文件>`\n4. **检查** → `npm run lint`\n5. **测试** → `npm test`\n6. **验证** → `npm run cli status` 确认服务正常\n\n### 测试规范\n\n- 测试文件在 `tests/` 目录，命名 `*.test.js` 或 `*.spec.js`\n- 使用 `jest.mock()` 模拟依赖（logger、redis、services）\n- `beforeEach` 中 `jest.resetModules()`，`afterEach` 中 `jest.clearAllMocks()`\n\n### 前端要求\n\n- 技术栈：Vue 3 Composition API + Pinia + Element Plus + Tailwind CSS\n- 响应式设计：Tailwind CSS 响应式前缀（sm:、md:、lg:、xl:）\n- 暗黑模式：所有组件必须兼容，使用 `dark:` 前缀\n- 主题切换：`web/admin-spa/src/stores/theme.js` 的 `useThemeStore()`\n- 保持现有玻璃态设计风格\n\n暗黑模式配色对照：\n\n| 元素 | 明亮模式 | 暗黑模式 |\n|------|----------|----------|\n| 文本 | `text-gray-700` | `dark:text-gray-200` |\n| 背景 | `bg-white` | `dark:bg-gray-800` |\n| 边框 | `border-gray-200` | `dark:border-gray-700` |\n| 状态色 | `text-blue-500` / `text-green-600` / `text-red-500` | 保持一致 |\n\n### 代码修改原则\n\n- 先检查现有模式和风格，重用已有服务和工具函数\n- 敏感数据必须加密存储（参考 claudeAccountService.js）\n- 遵循现有的错误处理和日志记录模式\n\n## 常用命令\n\n```bash\nnpm install && npm run setup    # 初始化\nnpm run dev                     # 开发模式（nodemon 热重载，自动 lint）\nnpm start                       # 生产模式（先 lint 再启动）\nnpm run lint                    # ESLint 检查并自动修复\nnpm run lint:check              # ESLint 仅检查不修复\nnpm run format                  # Prettier 格式化所有后端文件\nnpm run format:check            # Prettier 仅检查格式\nnpm test                        # Jest 运行所有测试（tests/ 目录）\nnpm test -- <文件名>             # 运行单个测试，如: npm test -- pricingService\nnpm test -- --coverage          # 运行测试并生成覆盖率报告\nnpm run cli status              # 系统状态\nnpm run data:export             # 导出 Redis 数据\nnpm run data:debug              # 调试 Redis 键\n```\n\n### 前端命令\n\n```bash\nnpm run install:web             # 安装前端依赖\nnpm run build:web               # 构建前端（生成 dist）\ncd web/admin-spa && npm run dev # 前端开发模式（Vite HMR）\n```\n\n## 环境变量（必须）\n\n- `JWT_SECRET` — JWT 密钥（32字符+）\n- `ENCRYPTION_KEY` — AES 加密密钥（32字符固定）\n- `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` — Redis 连接\n\n其他可选环境变量见 `.env.example`。\n\n## 故障排除\n\n| 问题 | 排查方向 |\n|------|----------|\n| Redis 连接失败 | 检查 REDIS_HOST/PORT/PASSWORD |\n| 管理员登录失败 | 检查 data/init.json，运行 `npm run setup` |\n| API Key 格式错误 | 确保使用 `cr_` 前缀格式（可通过 API_KEY_PREFIX 配置） |\n| Token 刷新失败 | 检查 refreshToken 有效性和代理配置，查看 `logs/token-refresh-error.log` |\n| 调度器选账户失败 | 检查账户 status:'active'，确认类型与路由匹配，查看粘性会话绑定 |\n| 并发计数泄漏 | 系统每分钟自动清理，重启也会清理 |\n| 粘性会话失效 | 检查 Redis 中 session 数据，Nginx 代理需添加 `underscores_in_headers on` |\n| LDAP 认证失败 | 检查 LDAP_URL/BIND_DN/BIND_PASSWORD，自签名证书设 `LDAP_TLS_REJECT_UNAUTHORIZED=false` |\n| Webhook 通知失败 | 确认 WEBHOOK_ENABLED=true，检查 WEBHOOK_URLS 格式，查看 `logs/webhook-*.log` |\n| 成本统计不准确 | 运行 `npm run init:costs`，检查 pricingService 模型价格 |\n\n日志：`logs/` 目录。Web 界面 `/admin-next/` 可实时查看。\n\n# important-instruction-reminders\n\nDo what has been asked; nothing more, nothing less.\nNEVER create files unless they're absolutely necessary for achieving your goal.\nALWAYS prefer editing an existing file to creating a new one.\nNEVER proactively create documentation files (\\*.md) or README files. Only create documentation files if explicitly requested by the User.\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## 项目概述\n\nClaude Relay Service — 多平台 AI API 中转服务，作为客户端与上游 AI API 之间的中间件。\n支持 Claude (官方/Console)、Gemini、OpenAI Responses、AWS Bedrock、Azure OpenAI、Droid、CCR 等账户类型。\n核心能力：多账户管理、API Key 认证、统一调度、代理配置、限流、成本统计。\n\n## 架构原则\n\n### Clean Architecture 分层映射\n\n| 层级 | 目录 | 职责 |\n|------|------|------|\n| **框架层** | `src/routes/`, `src/middleware/` | HTTP 路由、请求验证、响应格式化 |\n| **接口适配层** | `src/handlers/`, `src/services/openaiToClaude.js` | 请求/响应格式转换 |\n| **用例层** | `src/services/*Scheduler.js`, `*RelayService.js` | 调度逻辑、转发编排 |\n| **实体层** | `src/services/*AccountService.js`, `src/models/` | 账户管理、数据模型 |\n| **基础设施层** | `src/utils/`, `config/` | 日志、缓存、加密、代理 |\n\n### 开发原则\n\n- **依赖方向**: 外层 → 内层，内层不知道外层存在\n- **新增路由**: 只做参数提取和响应格式化，业务逻辑放 service\n- **新增服务**: 先确定属于哪一层，遵循该层职责边界\n- **格式转换**: 不同 API 格式的转换放 handlers 或专用转换服务\n- **数据访问**: 通过 `src/models/redis.js` 统一访问\n\n### 安全约束\n\n- 敏感数据（OAuth token、refreshToken、credentials）必须 AES 加密存储（参考 `claudeAccountService.js`）\n- API Key 使用 SHA-256 哈希存储，禁止明文\n- 每个请求必须经过完整认证链（API Key → 权限 → 客户端限制 → 模型黑名单）\n- 客户端断开时必须通过 AbortController 清理资源和并发计数\n- 日志中禁止输出完整 token，使用 `tokenMask.js` 脱敏\n\n## 项目结构\n\n```\nsrc/\n├── routes/              # HTTP 路由\n│   ├── api.js           # Claude API 主路由\n│   ├── admin/           # 管理后台路由（24个子文件）\n│   ├── geminiRoutes.js, standardGeminiRoutes.js\n│   ├── openaiRoutes.js, openaiClaudeRoutes.js, openaiGeminiRoutes.js\n│   ├── azureOpenaiRoutes.js, droidRoutes.js\n│   ├── userRoutes.js, webhook.js, unified.js, apiStats.js, web.js\n├── middleware/           # auth.js(认证/权限/限流), browserFallback.js\n├── handlers/             # geminiHandlers.js\n├── services/             # 业务服务\n│   ├── relay/                 # 各平台转发服务（9个）\n│   ├── account/               # 各平台账户管理（11个）\n│   ├── scheduler/             # 统一调度器（4个）\n│   ├── apiKeyService.js       # API Key 管理\n│   ├── pricingService.js      # 定价和成本\n│   └── ...                    # 其余 ~30 个业务服务\n├── models/redis.js       # Redis 数据模型\n├── utils/                # 35+ 工具文件（logger, proxy, oauth, cache, stream...）\nconfig/config.js          # 主配置\nscripts/                  # 运维脚本\ncli/                      # CLI 工具\nweb/admin-spa/            # Vue SPA 管理界面\ndata/init.json            # 管理员凭据\n```\n\n## 核心请求流程\n\n```\n客户端(cr_前缀Key) → 路由 → auth中间件(验证/权限/限流/模型黑名单)\n  → 统一调度器(选账户/粘性会话) → Token检查/刷新\n  → 转发服务(通过代理发送) → 上游API\n  → 流式/非流式响应 → Usage捕获 → 成本计算 → 返回客户端\n```\n\n关键机制：\n- **粘性会话**: 基于请求内容 hash 绑定账户，同一会话用同一账户\n- **并发控制**: Redis Sorted Set 实现，支持排队等待（非直接 429）\n- **529 处理**: 自动标记过载账户，配置时长内排除\n- **加密存储**: 敏感数据（OAuth token、credentials）AES 加密存于 Redis\n- **流式响应**: SSE 传输，实时捕获 usage，客户端断开时 AbortController 清理资源\n\n## 开发规范\n\n### 代码风格\n\n- **无分号**、**单引号**、**100字符行宽**、**尾逗号 none**、**箭头函数始终加括号**\n- 强制 `const`（`no-var`、`prefer-const`），严格相等（`eqeqeq`）\n- 下划线前缀变量 `_var` 可豁免 unused 检查\n- **必须使用 Prettier**: `npx prettier --write <file>`\n- 前端额外安装了 `prettier-plugin-tailwindcss`\n\n### 开发工作流\n\n1. **理解现有代码** → 读相关文件，了解现有模式\n2. **编写代码** → 重用已有服务和工具函数\n3. **格式化** → `npx prettier --write <修改的文件>`\n4. **检查** → `npm run lint`\n5. **测试** → `npm test`\n6. **验证** → `npm run cli status` 确认服务正常\n\n### 测试规范\n\n- 测试文件在 `tests/` 目录，命名 `*.test.js` 或 `*.spec.js`\n- 使用 `jest.mock()` 模拟依赖（logger、redis、services）\n- `beforeEach` 中 `jest.resetModules()`，`afterEach` 中 `jest.clearAllMocks()`\n\n### 前端要求\n\n- 技术栈：Vue 3 Composition API + Pinia + Element Plus + Tailwind CSS\n- 响应式设计：Tailwind CSS 响应式前缀（sm:、md:、lg:、xl:）\n- 暗黑模式：所有组件必须兼容，使用 `dark:` 前缀\n- 主题切换：`web/admin-spa/src/stores/theme.js` 的 `useThemeStore()`\n- 保持现有玻璃态设计风格\n\n暗黑模式配色对照：\n\n| 元素 | 明亮模式 | 暗黑模式 |\n|------|----------|----------|\n| 文本 | `text-gray-700` | `dark:text-gray-200` |\n| 背景 | `bg-white` | `dark:bg-gray-800` |\n| 边框 | `border-gray-200` | `dark:border-gray-700` |\n| 状态色 | `text-blue-500` / `text-green-600` / `text-red-500` | 保持一致 |\n\n### 代码修改原则\n\n- 先检查现有模式和风格，重用已有服务和工具函数\n- 敏感数据必须加密存储（参考 claudeAccountService.js）\n- 遵循现有的错误处理和日志记录模式\n\n## 常用命令\n\n```bash\nnpm install && npm run setup    # 初始化\nnpm run dev                     # 开发模式（nodemon 热重载，自动 lint）\nnpm start                       # 生产模式（先 lint 再启动）\nnpm run lint                    # ESLint 检查并自动修复\nnpm run lint:check              # ESLint 仅检查不修复\nnpm run format                  # Prettier 格式化所有后端文件\nnpm run format:check            # Prettier 仅检查格式\nnpm test                        # Jest 运行所有测试（tests/ 目录）\nnpm test -- <文件名>             # 运行单个测试，如: npm test -- pricingService\nnpm test -- --coverage          # 运行测试并生成覆盖率报告\nnpm run cli status              # 系统状态\nnpm run data:export             # 导出 Redis 数据\nnpm run data:debug              # 调试 Redis 键\n```\n\n### 前端命令\n\n```bash\nnpm run install:web             # 安装前端依赖\nnpm run build:web               # 构建前端（生成 dist）\ncd web/admin-spa && npm run dev # 前端开发模式（Vite HMR）\n```\n\n## 环境变量（必须）\n\n- `JWT_SECRET` — JWT 密钥（32字符+）\n- `ENCRYPTION_KEY` — AES 加密密钥（32字符固定）\n- `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` — Redis 连接\n\n其他可选环境变量见 `.env.example`。\n\n## 故障排除\n\n| 问题 | 排查方向 |\n|------|----------|\n| Redis 连接失败 | 检查 REDIS_HOST/PORT/PASSWORD |\n| 管理员登录失败 | 检查 data/init.json，运行 `npm run setup` |\n| API Key 格式错误 | 确保使用 `cr_` 前缀格式（可通过 API_KEY_PREFIX 配置） |\n| Token 刷新失败 | 检查 refreshToken 有效性和代理配置，查看 `logs/token-refresh-error.log` |\n| 调度器选账户失败 | 检查账户 status:'active'，确认类型与路由匹配，查看粘性会话绑定 |\n| 并发计数泄漏 | 系统每分钟自动清理，重启也会清理 |\n| 粘性会话失效 | 检查 Redis 中 session 数据，Nginx 代理需添加 `underscores_in_headers on` |\n| LDAP 认证失败 | 检查 LDAP_URL/BIND_DN/BIND_PASSWORD，自签名证书设 `LDAP_TLS_REJECT_UNAUTHORIZED=false` |\n| Webhook 通知失败 | 确认 WEBHOOK_ENABLED=true，检查 WEBHOOK_URLS 格式，查看 `logs/webhook-*.log` |\n| 成本统计不准确 | 运行 `npm run init:costs`，检查 pricingService 模型价格 |\n\n日志：`logs/` 目录。Web 界面 `/admin-next/` 可实时查看。\n\n# important-instruction-reminders\n\nDo what has been asked; nothing more, nothing less.\nNEVER create files unless they're absolutely necessary for achieving your goal.\nALWAYS prefer editing an existing file to creating a new one.\nNEVER proactively create documentation files (\\*.md) or README files. Only create documentation files if explicitly requested by the User.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## 项目概述\n\nClaude Relay Service — 多平台 AI API 中转服务，作为客户端与上游 AI API 之间的中间件。\n支持 Claude (官方/Console)、Gemini、OpenAI Responses、AWS Bedrock、Azure OpenAI、Droid、CCR 等账户类型。\n核心能力：多账户管理、API Key 认证、统一调度、代理配置、限流、成本统计。\n\n## 架构原则\n\n### Clean Architecture 分层映射\n\n| 层级 | 目录 | 职责 |\n|------|------|------|\n| **框架层** | `src/routes/`, `src/middleware/` | HTTP 路由、请求验证、响应格式化 |\n| **接口适配层** | `src/handlers/`, `src/services/openaiToClaude.js` | 请求/响应格式转换 |\n| **用例层** | `src/services/*Scheduler.js`, `*RelayService.js` | 调度逻辑、转发编排 |\n| **实体层** | `src/services/*AccountService.js`, `src/models/` | 账户管理、数据模型 |\n| **基础设施层** | `src/utils/`, `config/` | 日志、缓存、加密、代理 |\n\n### 开发原则\n\n- **依赖方向**: 外层 → 内层，内层不知道外层存在\n- **新增路由**: 只做参数提取和响应格式化，业务逻辑放 service\n- **新增服务**: 先确定属于哪一层，遵循该层职责边界\n- **格式转换**: 不同 API 格式的转换放 handlers 或专用转换服务\n- **数据访问**: 通过 `src/models/redis.js` 统一访问\n\n### 安全约束\n\n- 敏感数据（OAuth token、refreshToken、credentials）必须 AES 加密存储（参考 `claudeAccountService.js`）\n- API Key 使用 SHA-256 哈希存储，禁止明文\n- 每个请求必须经过完整认证链（API Key → 权限 → 客户端限制 → 模型黑名单）\n- 客户端断开时必须通过 AbortController 清理资源和并发计数\n- 日志中禁止输出完整 token，使用 `tokenMask.js` 脱敏\n\n## 项目结构\n\n```\nsrc/\n├── routes/              # HTTP 路由\n│   ├── api.js           # Claude API 主路由\n│   ├── admin/           # 管理后台路由（24个子文件）\n│   ├── geminiRoutes.js, standardGeminiRoutes.js\n│   ├── openaiRoutes.js, openaiClaudeRoutes.js, openaiGeminiRoutes.js\n│   ├── azureOpenaiRoutes.js, droidRoutes.js\n│   ├── userRoutes.js, webhook.js, unified.js, apiStats.js, web.js\n├── middleware/           # auth.js(认证/权限/限流), browserFallback.js\n├── handlers/             # geminiHandlers.js\n├── services/             # 业务服务\n│   ├── relay/                 # 各平台转发服务（9个）\n│   ├── account/               # 各平台账户管理（11个）\n│   ├── scheduler/             # 统一调度器（4个）\n│   ├── apiKeyService.js       # API Key 管理\n│   ├── pricingService.js      # 定价和成本\n│   └── ...                    # 其余 ~30 个业务服务\n├── models/redis.js       # Redis 数据模型\n├── utils/                # 35+ 工具文件（logger, proxy, oauth, cache, stream...）\nconfig/config.js          # 主配置\nscripts/                  # 运维脚本\ncli/                      # CLI 工具\nweb/admin-spa/            # Vue SPA 管理界面\ndata/init.json            # 管理员凭据\n```\n\n## 核心请求流程\n\n```\n客户端(cr_前缀Key) → 路由 → auth中间件(验证/权限/限流/模型黑名单)\n  → 统一调度器(选账户/粘性会话) → Token检查/刷新\n  → 转发服务(通过代理发送) → 上游API\n  → 流式/非流式响应 → Usage捕获 → 成本计算 → 返回客户端\n```\n\n关键机制：\n- **粘性会话**: 基于请求内容 hash 绑定账户，同一会话用同一账户\n- **并发控制**: Redis Sorted Set 实现，支持排队等待（非直接 429）\n- **529 处理**: 自动标记过载账户，配置时长内排除\n- **加密存储**: 敏感数据（OAuth token、credentials）AES 加密存于 Redis\n- **流式响应**: SSE 传输，实时捕获 usage，客户端断开时 AbortController 清理资源\n\n## 开发规范\n\n### 代码风格\n\n- **无分号**、**单引号**、**100字符行宽**、**尾逗号 none**、**箭头函数始终加括号**\n- 强制 `const`（`no-var`、`prefer-const`），严格相等（`eqeqeq`）\n- 下划线前缀变量 `_var` 可豁免 unused 检查\n- **必须使用 Prettier**: `npx prettier --write <file>`\n- 前端额外安装了 `prettier-plugin-tailwindcss`\n\n### 开发工作流\n\n1. **理解现有代码** → 读相关文件，了解现有模式\n2. **编写代码** → 重用已有服务和工具函数\n3. **格式化** → `npx prettier --write <修改的文件>`\n4. **检查** → `npm run lint`\n5. **测试** → `npm test`\n6. **验证** → `npm run cli status` 确认服务正常\n\n### 测试规范\n\n- 测试文件在 `tests/` 目录，命名 `*.test.js` 或 `*.spec.js`\n- 使用 `jest.mock()` 模拟依赖（logger、redis、services）\n- `beforeEach` 中 `jest.resetModules()`，`afterEach` 中 `jest.clearAllMocks()`\n\n### 前端要求\n\n- 技术栈：Vue 3 Composition API + Pinia + Element Plus + Tailwind CSS\n- 响应式设计：Tailwind CSS 响应式前缀（sm:、md:、lg:、xl:）\n- 暗黑模式：所有组件必须兼容，使用 `dark:` 前缀\n- 主题切换：`web/admin-spa/src/stores/theme.js` 的 `useThemeStore()`\n- 保持现有玻璃态设计风格\n\n暗黑模式配色对照：\n\n| 元素 | 明亮模式 | 暗黑模式 |\n|------|----------|----------|\n| 文本 | `text-gray-700` | `dark:text-gray-200` |\n| 背景 | `bg-white` | `dark:bg-gray-800` |\n| 边框 | `border-gray-200` | `dark:border-gray-700` |\n| 状态色 | `text-blue-500` / `text-green-600` / `text-red-500` | 保持一致 |\n\n### 代码修改原则\n\n- 先检查现有模式和风格，重用已有服务和工具函数\n- 敏感数据必须加密存储（参考 claudeAccountService.js）\n- 遵循现有的错误处理和日志记录模式\n\n## 常用命令\n\n```bash\nnpm install && npm run setup    # 初始化\nnpm run dev                     # 开发模式（nodemon 热重载，自动 lint）\nnpm start                       # 生产模式（先 lint 再启动）\nnpm run lint                    # ESLint 检查并自动修复\nnpm run lint:check              # ESLint 仅检查不修复\nnpm run format                  # Prettier 格式化所有后端文件\nnpm run format:check            # Prettier 仅检查格式\nnpm test                        # Jest 运行所有测试（tests/ 目录）\nnpm test -- <文件名>             # 运行单个测试，如: npm test -- pricingService\nnpm test -- --coverage          # 运行测试并生成覆盖率报告\nnpm run cli status              # 系统状态\nnpm run data:export             # 导出 Redis 数据\nnpm run data:debug              # 调试 Redis 键\n```\n\n### 前端命令\n\n```bash\nnpm run install:web             # 安装前端依赖\nnpm run build:web               # 构建前端（生成 dist）\ncd web/admin-spa && npm run dev # 前端开发模式（Vite HMR）\n```\n\n## 环境变量（必须）\n\n- `JWT_SECRET` — JWT 密钥（32字符+）\n- `ENCRYPTION_KEY` — AES 加密密钥（32字符固定）\n- `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` — Redis 连接\n\n其他可选环境变量见 `.env.example`。\n\n## 故障排除\n\n| 问题 | 排查方向 |\n|------|----------|\n| Redis 连接失败 | 检查 REDIS_HOST/PORT/PASSWORD |\n| 管理员登录失败 | 检查 data/init.json，运行 `npm run setup` |\n| API Key 格式错误 | 确保使用 `cr_` 前缀格式（可通过 API_KEY_PREFIX 配置） |\n| Token 刷新失败 | 检查 refreshToken 有效性和代理配置，查看 `logs/token-refresh-error.log` |\n| 调度器选账户失败 | 检查账户 status:'active'，确认类型与路由匹配，查看粘性会话绑定 |\n| 并发计数泄漏 | 系统每分钟自动清理，重启也会清理 |\n| 粘性会话失效 | 检查 Redis 中 session 数据，Nginx 代理需添加 `underscores_in_headers on` |\n| LDAP 认证失败 | 检查 LDAP_URL/BIND_DN/BIND_PASSWORD，自签名证书设 `LDAP_TLS_REJECT_UNAUTHORIZED=false` |\n| Webhook 通知失败 | 确认 WEBHOOK_ENABLED=true，检查 WEBHOOK_URLS 格式，查看 `logs/webhook-*.log` |\n| 成本统计不准确 | 运行 `npm run init:costs`，检查 pricingService 模型价格 |\n\n日志：`logs/` 目录。Web 界面 `/admin-next/` 可实时查看。\n\n# important-instruction-reminders\n\nDo what has been asked; nothing more, nothing less.\nNEVER create files unless they're absolutely necessary for achieving your goal.\nALWAYS prefer editing an existing file to creating a new one.\nNEVER proactively create documentation files (\\*.md) or README files. Only create documentation files if explicitly requested by the User.\n","category":"root","tokens":1500}]}