diff --git a/README.md b/README.md
index e267fbcd..9e358474 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,4 @@
-# Claude Relay Service (Antigravity Edition)
-
-> **二开维护：dadongwo**
->
-> 目标：让 `claude`（Claude Code CLI）与 Antigravity / Gemini 账户体系无缝对接，并提供可观测、可运维的稳定转发服务。
+# Claude Relay Service
> [!CAUTION]
> **安全更新通知**：v1.1.248 及以下版本存在严重的管理员认证绕过漏洞，攻击者可未授权访问管理面板。
@@ -13,169 +9,997 @@
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
+[](https://redis.io/)
[](https://www.docker.com/)
+[](https://github.com/Wei-Shaw/claude-relay-service/actions/workflows/auto-release-pipeline.yml)
+[](https://hub.docker.com/r/weishaw/claude-relay-service)
-**🔐 Claude Code 原生适配 · Antigravity 生态 · 多账户管理**
+**🔐 自行搭建Claude API中转服务，支持多账户管理**
+
+[English](README_EN.md) • [快速开始](https://pincc.ai/) • [演示站点](https://demo.pincc.ai/admin-next/login) • [公告频道](https://t.me/claude_relay_service)
---
-## 🌟 核心亮点
+## 💎 Claude/Codex 拼车服务推荐
-这是一个二开项目：在原版 CRS 基础上补齐 Claude Code 协议层兼容、完善 Antigravity OAuth 与路径分流，并增强稳定性与可观测性。
+
-### 1. 🚀 Claude Code 原生级兼容 (Killer Feature)
-无需任何魔法，让你的 `claude` 命令行工具像连接官方一样连接到本服务。
+| 平台 | 类型 | 服务 | 介绍 |
+|:---|:---|:---|:---|
+| **[pincc.ai](https://pincc.ai/)** | 🏆 **官方运营** | ✅ Claude Code
✅ Codex CLI | 项目直营，提供稳定的 Claude Code / Codex CLI 拼车服务 |
+| **[ctok.ai](https://ctok.ai/)** | 🤝 合作伙伴 | ✅ Claude Code
✅ Codex CLI | 社区认证，提供 Claude Code / Codex CLI 拼车 |
-- **Thinking Signature 伪造/缓存/恢复**：解决 Claude Code 3.7+ 对 `thoughtSignature` 的强校验，支持兜底签名策略与签名缓存。
-- **Tool Result 透传**：兼容 Base64 图片等复杂结构，避免转发丢失/格式错误。
-- **消息并发治理**：拆分 Claude Code 混合发送的 `tool_result + user_text`，按协议顺序转发。
-- **僵尸流看门狗**：SSE 连接 45 秒无有效数据自动断开，避免“假活着”导致会话/额度被占用。
-### 2. 🛡️ Antigravity & Gemini 深度集成
-- **Antigravity OAuth 支持**：新增 `gemini-antigravity` 账户类型，支持 OAuth 授权与权限校验。
-- **路径即路由 (Path-Based Routing)**:
- - `/antigravity/api` -> 自动路由到 Antigravity 账户池
- - `/gemini-cli/api` -> 自动路由到 Gemini 账户池
- - 告别在模型名前加前缀（如 `gemini/claude-3-5`）的混乱做法，Client 端只需改 Base URL 即可。
-- **额度与模型动态列表适配**：针对 Antigravity 的 `fetchAvailableModels` 做标准化展示（管理后台）与透传（接口）。
-
-### 3. ⚙️ 企业级稳定性
-- **智能重试与切换账号**：针对 Antigravity `429 Resource Exhausted`，自动清理会话并切换账号重试（流式/非流式均覆盖）。
-- **日志安全与轮转**：避免循环引用导致的进程崩溃，并对 Dump 文件进行大小控制与轮转。
-- **调试利器**：支持请求/响应/工具定义/上游请求与上游 SSE 响应的 JSONL 转储，便于复现与定位问题。
-
-## 📊 额度与模型查询 (Antigravity 专属)
-
-### 查看账户额度 / Quota
-本服务深度适配了 Antigravity 的实时配额查询接口 (v1internal:fetchAvailableModels)。
-
-1. 进入管理后台 -> **账号管理 (Claude 账户)**。
-2. 找到您的 `gemini-antigravity` 类型账户。
-3. 点击卡片右上角的 **"测试/刷新"** 按钮。
-4. 系统会自动拉取上游最新的配额信息（支持 Gemini Pro / Flash / Image 等不同分类），并将其标准化展示为百分比与重置时间。
-
-### 获取动态模型列表
-由于 Antigravity 的模型 ID 是动态更新的（如 `gemini-2.0-flash-exp`），本服务提供了透传查询接口。
-
-- **接口地址（Anthropic/Claude Code 路由）**: `GET /antigravity/api/v1/models`
-- **接口地址（OpenAI 兼容路由）**: `GET /openai/gemini/models`（或 `GET /openai/gemini/v1/models`）
-- **说明**: `/antigravity/api/v1/models` 会实时透传 Antigravity 上游 `fetchAvailableModels` 结果，确保看到当前账户可用的最新模型列表。
+
---
-## 🎮 快速开始指南
+## ⚠️ 重要提醒
-### 0. 环境要求
-- Node.js 18+（或使用 Docker）
-- Redis 6+/7+
+**使用本项目前请仔细阅读：**
-### 1. Claude Code (CLI) 配置
+🚨 **服务条款风险**: 使用本项目可能违反Anthropic的服务条款。请在使用前仔细阅读Anthropic的用户协议，使用本项目的一切风险由用户自行承担。
-无需修改代码，只需设置环境变量即可无缝切换后端。
+📖 **免责声明**: 本项目仅供技术学习和研究使用，作者不对因使用本项目导致的账户封禁、服务中断或其他损失承担任何责任。
-#### 方案 A: 使用 Antigravity 账户池 (推荐)
-适用于通过 Antigravity 渠道使用 Claude 模型 (如 `claude-opus-4-5` 等)。
-```bash
-# 1. 设置 Base URL 为 Antigravity 专用路径
-export ANTHROPIC_BASE_URL="http://你的服务器IP:3000/antigravity/api/"
+## 🤔 这个项目适合你吗？
-# 2. 设置 API Key (在后台创建，权限需包含 'all' 或 'gemini')
-export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxxxxxx"
+- 🌍 **地区限制**: 所在地区无法直接访问Claude Code服务？
+- 🔒 **隐私担忧**: 担心第三方镜像服务会记录或泄露你的对话内容？
+- 👥 **成本分摊**: 想和朋友一起分摊Claude Code Max订阅费用？
+- ⚡ **稳定性**: 第三方镜像站经常故障不稳定，影响效率 ？
-# 3. 指定模型名称 (直接使用短名，无需前缀！)
-export ANTHROPIC_MODEL="claude-opus-4-5"
+如果有以上困惑，那这个项目可能适合你。
-# 4. 启动
-claude
-```
+### 适合的场景
-#### 方案 B: 使用 Gemini 账户池 (Gemini Models)
-适用于直接调用 Google Gemini 模型 (如 `gemini-2.5-pro`)。
-
-```bash
-export ANTHROPIC_BASE_URL="http://你的服务器IP:3000/gemini-cli/api/"
-export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxxxxxx"
-export ANTHROPIC_MODEL="gemini-2.5-pro"
-claude
-```
-
-#### 方案 C: 标准 Claude 账户池
-适用于原版 Claude / Console / Bedrock 渠道。
-
-```bash
-export ANTHROPIC_BASE_URL="http://你的服务器IP:3000/api/"
-export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxxxxxx"
-claude
-```
+✅ **找朋友拼车**: 三五好友一起分摊Claude Code Max订阅
+✅ **隐私敏感**: 不想让第三方镜像看到你的对话内容
+✅ **技术折腾**: 有基本的技术基础，愿意自己搭建和维护
+✅ **稳定需求**: 需要长期稳定的Claude访问，不想受制于镜像站
+✅ **地区受限**: 无法直接访问Claude官方服务
---
-### 2. Gemini CLI 配置
+## 💭 为什么要自己搭？
-支持通过 Gemini 协议直接访问。
+### 现有镜像站可能的问题
-**方式一：通过 Gemini Assist API (推荐)**
+- 🕵️ **隐私风险**: 你的对话内容都被人家看得一清二楚，商业机密什么的就别想了
+- 🐌 **性能不稳**: 用的人多了就慢，高峰期经常卡死
+- 💰 **价格不透明**: 不知道实际成本
-```bash
-export CODE_ASSIST_ENDPOINT="http://你的服务器IP:3000/gemini"
-export GOOGLE_CLOUD_ACCESS_TOKEN="cr_xxxxxxxxxxxx" # 使用 CRS 的 API Key
-export GOOGLE_GENAI_USE_GCA="true"
-export GEMINI_MODEL="gemini-2.5-pro"
-gemini
-```
+### 自建的好处
+
+- 🔐 **数据安全**: 所有接口请求都只经过你自己的服务器，直连Anthropic API
+- ⚡ **性能可控**: 就你们几个人用，Max 200刀套餐基本上可以爽用Opus
+- 💰 **成本透明**: 用了多少token一目了然，按官方价格换算了具体费用
+- 📊 **监控完整**: 使用情况、成本分析、性能监控全都有
---
-## 📦 部署说明
+## 🚀 核心功能
-### Docker Compose (推荐)
+### 基础功能
+
+- ✅ **多账户管理**: 可以添加多个Claude账户自动轮换
+- ✅ **自定义API Key**: 给每个人分配独立的Key
+- ✅ **使用统计**: 详细记录每个人用了多少token
+
+### 高级功能
+
+- 🔄 **智能切换**: 账户出问题自动换下一个
+- 🚀 **性能优化**: 连接池、缓存，减少延迟
+- 📊 **监控面板**: Web界面查看所有数据
+- 🛡️ **安全控制**: 访问限制、速率控制、客户端限制
+- 🌐 **代理支持**: 支持HTTP/SOCKS5代理
+
+---
+
+## 📋 部署要求
+
+### 硬件要求（最低配置）
+
+- **CPU**: 1核心就够了
+- **内存**: 512MB（建议1GB）
+- **硬盘**: 30GB可用空间
+- **网络**: 能访问到Anthropic API（建议使用US地区的机器）
+- **建议**: 2核4G的基本够了，网络尽量选回国线路快一点的（为了提高速度，建议不要开代理或者设置服务器的IP直连）
+- **经验**: 阿里云、腾讯云的海外主机经测试会被Cloudflare拦截，无法直接访问claude api
+
+### 软件要求
+
+- **Node.js** 18或更高版本
+- **Redis** 6或更高版本
+- **操作系统**: 建议Linux
+
+### 费用估算
+
+- **服务器**: 轻量云服务器，一个月30-60块
+- **Claude订阅**: 看你怎么分摊了
+- **其他**: 域名（可选）
+
+---
+
+## 🚀 脚本部署（推荐）
+
+推荐使用管理脚本进行一键部署，简单快捷，自动处理所有依赖和配置。
+
+### 快速安装
```bash
-# 1. 初始化配置
-cp .env.example .env
+curl -fsSL https://pincc.ai/manage.sh -o manage.sh && chmod +x manage.sh && ./manage.sh install
+```
+
+### 脚本功能
+
+- ✅ **一键安装**: 自动检测系统环境，安装 Node.js 18+、Redis 等依赖
+- ✅ **交互式配置**: 友好的配置向导，设置端口、Redis 连接等
+- ✅ **自动启动**: 安装完成后自动启动服务并显示访问地址
+- ✅ **便捷管理**: 通过 `crs` 命令随时管理服务状态
+
+### 管理命令
+
+```bash
+crs install # 安装服务
+crs start # 启动服务
+crs stop # 停止服务
+crs restart # 重启服务
+crs status # 查看状态
+crs update # 更新服务
+crs uninstall # 卸载服务
+```
+
+### 安装示例
+
+```bash
+$ crs install
+
+# 会依次询问：
+安装目录 (默认: ~/claude-relay-service):
+服务端口 (默认: 3000): 8080
+Redis 地址 (默认: localhost):
+Redis 端口 (默认: 6379):
+Redis 密码 (默认: 无密码):
+
+# 安装完成后自动启动并显示：
+服务已成功安装并启动！
+
+访问地址：
+ 本地 Web: http://localhost:8080/web
+ 公网 Web: http://YOUR_IP:8080/web
+
+管理员账号信息已保存到: data/init.json
+```
+
+### 系统要求
+
+- 支持系统: Ubuntu/Debian、CentOS/RedHat、Arch Linux、macOS
+- 自动安装 Node.js 18+ 和 Redis
+- Redis 使用系统默认位置，数据独立于应用
+
+---
+
+## 📦 手动部署
+
+### 第一步：环境准备
+
+**Ubuntu/Debian用户：**
+
+```bash
+# 安装Node.js
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# 安装Redis
+sudo apt update
+sudo apt install redis-server
+sudo systemctl start redis-server
+```
+
+**CentOS/RHEL用户：**
+
+```bash
+# 安装Node.js
+curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
+sudo yum install -y nodejs
+
+# 安装Redis
+sudo yum install redis
+sudo systemctl start redis
+```
+
+### 第二步：下载和配置
+
+```bash
+# 下载项目
+git clone https://github.com/Wei-Shaw//claude-relay-service.git
+cd claude-relay-service
+
+# 安装依赖
+npm install
+
+# 复制配置文件（重要！）
cp config/config.example.js config/config.js
+cp .env.example .env
+```
-# 2. 编辑 .env（至少设置这两个）
-# JWT_SECRET=...（随机字符串）
-# ENCRYPTION_KEY=...（32位随机字符串）
+### 第三步：配置文件设置
-# 3. 启动
+**编辑 `.env` 文件：**
+
+```bash
+# 这两个密钥随便生成，但要记住
+JWT_SECRET=你的超级秘密密钥
+ENCRYPTION_KEY=32位的加密密钥随便写
+
+# Redis配置
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+
+```
+
+**编辑 `config/config.js` 文件：**
+
+```javascript
+module.exports = {
+ server: {
+ port: 3000, // 服务端口，可以改
+ host: '0.0.0.0' // 不用改
+ },
+ redis: {
+ host: '127.0.0.1', // Redis地址
+ port: 6379 // Redis端口
+ }
+ // 其他配置保持默认就行
+}
+```
+
+### 第四步：安装前端依赖并构建
+
+```bash
+# 安装前端依赖
+npm run install:web
+
+# 构建前端（生成 dist 目录）
+npm run build:web
+```
+
+### 第五步：启动服务
+
+```bash
+# 初始化
+npm run setup # 会随机生成后台账号密码信息，存储在 data/init.json
+# 或者通过环境变量预设管理员凭据：
+# export ADMIN_USERNAME=cr_admin_custom
+# export ADMIN_PASSWORD=your-secure-password
+
+# 启动服务
+npm run service:start:daemon # 后台运行
+
+# 查看状态
+npm run service:status
+```
+
+---
+
+## 🐳 Docker 部署
+
+### Docker compose
+
+#### 第一步：下载构建docker-compose.yml文件的脚本并执行
+```bash
+curl -fsSL https://pincc.ai/crs-compose.sh -o crs-compose.sh && chmod +x crs-compose.sh && ./crs-compose.sh
+```
+
+#### 第二步：启动
+```bash
docker-compose up -d
```
-### Node 方式（不使用 Docker）
+### Docker Compose 配置
+
+docker-compose.yml 已包含：
+
+- ✅ 自动初始化管理员账号
+- ✅ 数据持久化（logs和data目录自动挂载）
+- ✅ Redis数据库
+- ✅ 健康检查
+- ✅ 自动重启
+
+### 环境变量说明
+
+#### 必填项
+
+- `JWT_SECRET`: JWT密钥，至少32个字符
+- `ENCRYPTION_KEY`: 加密密钥，必须是32个字符
+
+#### 可选项
+
+- `ADMIN_USERNAME`: 管理员用户名（不设置则自动生成）
+- `ADMIN_PASSWORD`: 管理员密码（不设置则自动生成）
+- `LOG_LEVEL`: 日志级别（默认：info）
+- 更多配置项请参考 `.env.example` 文件
+
+### 管理员凭据获取方式
+
+1. **查看容器日志**
+
+ ```bash
+ docker logs claude-relay-service
+ ```
+
+2. **查看挂载的文件**
+
+ ```bash
+ cat ./data/init.json
+ ```
+
+3. **使用环境变量预设**
+ ```bash
+ # 在 .env 文件中设置
+ ADMIN_USERNAME=cr_admin_custom
+ ADMIN_PASSWORD=your-secure-password
+ ```
+
+---
+
+## 🎮 开始使用
+
+### 1. 打开管理界面
+
+浏览器访问：`http://你的服务器IP:3000/web`
+
+管理员账号：
+
+- 自动生成：查看 data/init.json
+- 环境变量预设：通过 ADMIN_USERNAME 和 ADMIN_PASSWORD 设置
+- Docker 部署：查看容器日志 `docker logs claude-relay-service`
+
+### 2. 添加Claude账户
+
+这一步比较关键，需要OAuth授权：
+
+1. 点击「Claude账户」标签
+2. 如果你担心多个账号共用1个IP怕被封禁，可以选择设置静态代理IP（可选）
+3. 点击「添加账户」
+4. 点击「生成授权链接」，会打开一个新页面
+5. 在新页面完成Claude登录和授权
+6. 复制返回的Authorization Code
+7. 粘贴到页面完成添加
+
+**注意**: 如果你在国内，这一步可能需要科学上网。
+
+### 3. 创建API Key
+
+给每个使用者分配一个Key：
+
+1. 点击「API Keys」标签
+2. 点击「创建新Key」
+3. 给Key起个名字，比如「张三的Key」
+4. 设置使用限制（可选）：
+ - **速率限制**: 限制每个时间窗口的请求次数和Token使用量
+ - **并发限制**: 限制同时处理的请求数
+ - **模型限制**: 限制可访问的模型列表
+ - **客户端限制**: 限制只允许特定客户端使用（如ClaudeCode、Gemini-CLI等）
+5. 保存，记下生成的Key
+
+### 4. 开始使用 Claude Code 和 Gemini CLI
+
+现在你可以用自己的服务替换官方API了：
+
+**Claude Code 设置环境变量：**
+
+默认使用标准 Claude 账号池：
```bash
-npm install
-cp .env.example .env
-cp config/config.example.js config/config.js
-npm run setup
-npm run service:start:daemon
+export ANTHROPIC_BASE_URL="http://127.0.0.1:3000/api/" # 根据实际填写你服务器的ip地址或者域名
+export ANTHROPIC_AUTH_TOKEN="后台创建的API密钥"
```
-### 管理面板
+**VSCode Claude 插件配置：**
-- 地址: `http://IP:3000/web`
-- 初始账号/密码：`npm run setup` 生成并写入 `data/init.json`（Docker 部署可通过容器日志定位）。
+如果使用 VSCode 的 Claude 插件，需要在 `~/.claude/config.json` 文件中配置：
+
+```json
+{
+ "primaryApiKey": "crs"
+}
+```
+
+如果该文件不存在，请手动创建。Windows 用户路径为 `C:\Users\你的用户名\.claude\config.json`。
+
+> 💡 **IntelliJ IDEA 用户推荐**：[Claude Code Plus](https://github.com/touwaeriol/claude-code-plus) - 将 Claude Code 直接集成到 IDE，支持代码理解、文件读写、命令执行。插件市场搜索 `Claude Code Plus` 即可安装。
+
+**Gemini CLI 设置环境变量：**
+
+**方式一（推荐）：通过 Gemini Assist API 方式访问**
+
+```bash
+CODE_ASSIST_ENDPOINT="http://127.0.0.1:3000/gemini" # 根据实际填写你服务器的ip地址或者域名
+GOOGLE_CLOUD_ACCESS_TOKEN="后台创建的API密钥"
+GOOGLE_GENAI_USE_GCA="true"
+GEMINI_MODEL="gemini-2.5-pro" # 如果你有gemini3权限可以填： gemini-3-pro-preview
+```
+
+> **认证**：只能选 ```Login with Google``` 进行认证，如果跳 Google请删除 ```~/.gemini/settings.json``` 后再尝试启动```gemini```。
+> **注意**：gemini-cli 控制台会提示 `Failed to fetch user info: 401 Unauthorized`，但使用不受任何影响。
+
+**方式二：通过 Gemini API 方式访问**
+
+
+```bash
+GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:3000/gemini" # 根据实际填写你服务器的ip地址或者域名
+GEMINI_API_KEY="后台创建的API密钥"
+GEMINI_MODEL="gemini-2.5-pro" # 如果你有gemini3权限可以填： gemini-3-pro-preview
+```
+
+> **认证**：只能选 ```Use Gemini API Key``` 进行认证，如果提示 ```Enter Gemini API Key``` 请直接留空按回车。如果一打开就跳 Google请删除 ```~/.gemini/settings.json``` 后再尝试启动```gemini```。
+
+> 💡 **进阶用法**：想在 Claude Code 中直接使用 Gemini 3 模型？请参考 [Claude Code 调用 Gemini 3 模型指南](docs/claude-code-gemini3-guide/README.md)
+
+**使用 Claude Code：**
+
+```bash
+claude
+```
+
+**使用 Gemini CLI：**
+
+```bash
+gemini # 或其他 Gemini CLI 命令
+```
+
+**Codex 配置：**
+
+在 `~/.codex/config.toml` 文件**开头**添加以下配置：
+
+```toml
+model_provider = "crs"
+model = "gpt-5.1-codex-max"
+model_reasoning_effort = "high"
+disable_response_storage = true
+preferred_auth_method = "apikey"
+
+[model_providers.crs]
+name = "crs"
+base_url = "http://127.0.0.1:3000/openai" # 根据实际填写你服务器的ip地址或者域名
+wire_api = "responses"
+requires_openai_auth = true
+env_key = "CRS_OAI_KEY"
+```
+
+在 `~/.codex/auth.json` 文件中配置API密钥为 null：
+
+```json
+{
+ "OPENAI_API_KEY": null
+}
+```
+
+环境变量设置：
+
+```bash
+export CRS_OAI_KEY="后台创建的API密钥"
+```
+
+> ⚠️ 在通过 Nginx 反向代理 CRS 服务并使用 Codex CLI 时，需要在 http 块中添加 underscores_in_headers on;。因为 Nginx 默认会移除带下划线的请求头（如 session_id），一旦该头被丢弃，多账号环境下的粘性会话功能将失效。
+
+**Droid CLI 配置：**
+
+Droid CLI 读取 `~/.factory/config.json`。可以在该文件中添加自定义模型以指向本服务的新端点：
+
+```json
+{
+ "custom_models": [
+ {
+ "model_display_name": "Opus 4.5 [crs]",
+ "model": "claude-opus-4-5-20251101",
+ "base_url": "http://127.0.0.1:3000/droid/claude",
+ "api_key": "后台创建的API密钥",
+ "provider": "anthropic",
+ "max_tokens": 64000
+ },
+ {
+ "model_display_name": "GPT5-Codex [crs]",
+ "model": "gpt-5-codex",
+ "base_url": "http://127.0.0.1:3000/droid/openai",
+ "api_key": "后台创建的API密钥",
+ "provider": "openai",
+ "max_tokens": 16384
+ },
+ {
+ "model_display_name": "Gemini-3-Pro [crs]",
+ "model": "gemini-3-pro-preview",
+ "base_url": "http://127.0.0.1:3000/droid/comm/v1/",
+ "api_key": "后台创建的API密钥",
+ "provider": "generic-chat-completion-api",
+ "max_tokens": 65535
+ },
+ {
+ "model_display_name": "GLM-4.6 [crs]",
+ "model": "glm-4.6",
+ "base_url": "http://127.0.0.1:3000/droid/comm/v1/",
+ "api_key": "后台创建的API密钥",
+ "provider": "generic-chat-completion-api",
+ "max_tokens": 202800
+ }
+ ]
+}
+```
+
+> 💡 将示例中的 `http://127.0.0.1:3000` 替换为你的服务域名或公网地址，并写入后台生成的 API 密钥（cr_ 开头）。
+
+### 5. 第三方工具API接入
+
+本服务支持多种API端点格式，方便接入不同的第三方工具（如Cherry Studio等）。
+
+#### Cherry Studio 接入示例
+
+Cherry Studio支持多种AI服务的接入，下面是不同账号类型的详细配置：
+
+**1. Claude账号接入：**
+
+```
+# API地址
+http://你的服务器:3000/claude
+
+# 模型ID示例
+claude-sonnet-4-5-20250929 # Claude Sonnet 4.5
+claude-opus-4-20250514 # Claude Opus 4
+```
+
+配置步骤：
+- 供应商类型选择"Anthropic"
+- API地址填入：`http://你的服务器:3000/claude`
+- API Key填入：后台创建的API密钥（cr_开头）
+
+**2. Gemini账号接入：**
+
+```
+# API地址
+http://你的服务器:3000/gemini
+
+# 模型ID示例
+gemini-2.5-pro # Gemini 2.5 Pro
+```
+
+配置步骤：
+- 供应商类型选择"Gemini"
+- API地址填入：`http://你的服务器:3000/gemini`
+- API Key填入：后台创建的API密钥（cr_开头）
+
+**3. Codex接入：**
+
+```
+# API地址
+http://你的服务器:3000/openai
+
+# 模型ID（固定）
+gpt-5 # Codex使用固定模型ID
+```
+
+配置步骤：
+- 供应商类型选择"Openai-Response"
+- API地址填入：`http://你的服务器:3000/openai`
+- API Key填入：后台创建的API密钥（cr_开头）
+- **重要**：Codex只支持Openai-Response标准
+
+
+**Cherry Studio 地址格式重要说明：**
+
+- ✅ **推荐格式**：`http://你的服务器:3000/claude`（不加结尾 `/`，让 Cherry Studio 自动加上 v1）
+- ✅ **等效格式**：`http://你的服务器:3000/claude/v1/`（手动指定 v1 并加结尾 `/`）
+- 💡 **说明**：这两种格式在 Cherry Studio 中是完全等效的
+- ❌ **错误格式**：`http://你的服务器:3000/claude/`（单独的 `/` 结尾会被 Cherry Studio 忽略 v1 版本）
+
+#### 其他第三方工具接入
+
+**接入要点：**
+
+- 所有账号类型都使用相同的API密钥（在后台统一创建）
+- 根据不同的路由前缀自动识别账号类型
+- `/claude/` - 使用Claude账号池
+- `/droid/claude/` - 使用Droid类型Claude账号池（只建议api调用或Droid Cli中使用）
+- `/gemini/` - 使用Gemini账号池
+- `/openai/` - 使用Codex账号（只支持Openai-Response格式）
+- `/droid/openai/` - 使用Droid类型OpenAI兼容账号池（只建议api调用或Droid Cli中使用）
+- 支持所有标准API端点（messages、models等）
+
+**重要说明：**
+
+- 确保在后台已添加对应类型的账号（Claude/Gemini/Codex）
+- API密钥可以通用，系统会根据路由自动选择账号类型
+- 建议为不同用户创建不同的API密钥便于使用统计
---
-## 🔧 调试与排障（可选）
+## 🔧 日常维护
-Dump 开关在 `.env.example` 中有完整说明。常用项：
+### 服务管理
-- `ANTHROPIC_DEBUG_REQUEST_DUMP=true`
-- `ANTHROPIC_DEBUG_RESPONSE_DUMP=true`
-- `ANTIGRAVITY_DEBUG_UPSTREAM_REQUEST_DUMP=true`
-- `ANTIGRAVITY_DEBUG_UPSTREAM_RESPONSE_DUMP=true`
-- `DUMP_MAX_FILE_SIZE_BYTES=10485760`
+```bash
+# 查看服务状态
+npm run service:status
+
+# 查看日志
+npm run service:logs
+
+# 重启服务
+npm run service:restart:daemon
+
+# 停止服务
+npm run service:stop
+```
+
+### 监控使用情况
+
+- **Web界面**: `http://你的域名:3000/web` - 查看使用统计
+- **健康检查**: `http://你的域名:3000/health` - 确认服务正常
+- **日志文件**: `logs/` 目录下的各种日志文件
+
+### 升级指南
+
+当有新版本发布时，按照以下步骤升级服务：
+
+```bash
+# 1. 进入项目目录
+cd claude-relay-service
+
+# 2. 拉取最新代码
+git pull origin main
+
+# 如果遇到 package-lock.json 冲突，使用远程版本
+git checkout --theirs package-lock.json
+git add package-lock.json
+
+# 3. 安装新的依赖（如果有）
+npm install
+
+# 4. 安装并构建前端
+npm run install:web
+npm run build:web
+
+# 5. 重启服务
+npm run service:restart:daemon
+
+# 6. 检查服务状态
+npm run service:status
+```
+
+**注意事项：**
+
+- 升级前建议备份重要配置文件（.env, config/config.js）
+- 查看更新日志了解是否有破坏性变更
+- 如果有数据库结构变更，会自动迁移
---
-## 🤝 维护与致谢
+## 🔒 客户端限制功能
-- **维护者**：dadongwo
-- **Upstream**：Claude Relay Service（原版项目，已在本分支移除与功能无关的广告信息并专注于功能增强）
+### 功能说明
+
+客户端限制功能允许你控制每个API Key可以被哪些客户端使用，通过User-Agent识别客户端，提高API的安全性。
+
+### 使用方法
+
+1. **在创建或编辑API Key时启用客户端限制**：
+ - 勾选"启用客户端限制"
+ - 选择允许的客户端（支持多选）
+
+2. **预定义客户端**：
+ - **ClaudeCode**: 官方Claude CLI（匹配 `claude-cli/x.x.x (external, cli)` 格式）
+ - **Gemini-CLI**: Gemini命令行工具（匹配 `GeminiCLI/vx.x.x (platform; arch)` 格式）
+
+3. **调试和诊断**：
+ - 系统会在日志中记录所有请求的User-Agent
+ - 客户端验证失败时会返回403错误并记录详细信息
+ - 通过日志可以查看实际的User-Agent格式，方便配置自定义客户端
+
+
+### 日志示例
+
+认证成功时的日志：
+
+```
+🔓 Authenticated request from key: 测试Key (key-id) in 5ms
+ User-Agent: "claude-cli/1.0.58 (external, cli)"
+```
+
+客户端限制检查日志：
+
+```
+🔍 Checking client restriction for key: key-id (测试Key)
+ User-Agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
+ Allowed clients: claude_code, gemini_cli
+🚫 Client restriction failed for key: key-id (测试Key) from 127.0.0.1, User-Agent: Mozilla/5.0...
+```
+
+### 常见问题处理
+
+**Redis连不上？**
+
+```bash
+# 检查Redis是否启动
+redis-cli ping
+
+# 应该返回 PONG
+```
+
+**OAuth授权失败？**
+
+- 检查代理设置是否正确
+- 确保能正常访问 claude.ai
+- 清除浏览器缓存重试
+
+**API请求失败？**
+
+- 检查API Key是否正确
+- 查看日志文件找错误信息
+- 确认Claude账户状态正常
+
+---
+
+## 🛠️ 进阶
+
+### 反向代理部署指南
+
+在生产环境中，建议通过反向代理进行连接，以便使用自动 HTTPS、安全头部和性能优化。下面提供两种常用方案： **Caddy** 和 **Nginx Proxy Manager (NPM)**。
+
+---
+
+## Caddy 方案
+
+Caddy 是一款自动管理 HTTPS 证书的 Web 服务器，配置简单、性能优秀，很适合不需要 Docker 环境的部署方案。
+
+**1. 安装 Caddy**
+
+```bash
+# Ubuntu/Debian
+sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+sudo apt update
+sudo apt install caddy
+
+# CentOS/RHEL/Fedora
+sudo yum install yum-plugin-copr
+sudo yum copr enable @caddy/caddy
+sudo yum install caddy
+```
+
+**2. Caddy 配置**
+
+编辑 `/etc/caddy/Caddyfile` ：
+
+```caddy
+your-domain.com {
+ # 反向代理到本地服务
+ reverse_proxy 127.0.0.1:3000 {
+ # 支持流式响应或 SSE
+ flush_interval -1
+
+ # 传递真实 IP
+ header_up X-Real-IP {remote_host}
+ header_up X-Forwarded-For {remote_host}
+ header_up X-Forwarded-Proto {scheme}
+
+ # 长读/写超时配置
+ transport http {
+ read_timeout 300s
+ write_timeout 300s
+ dial_timeout 30s
+ }
+ }
+
+ # 安全头部
+ header {
+ Strict-Transport-Security "max-age=31536000; includeSubDomains"
+ X-Frame-Options "DENY"
+ X-Content-Type-Options "nosniff"
+ -Server
+ }
+}
+```
+
+**3. 启动 Caddy**
+
+```bash
+sudo caddy validate --config /etc/caddy/Caddyfile
+sudo systemctl start caddy
+sudo systemctl enable caddy
+sudo systemctl status caddy
+```
+
+**4. 服务配置**
+
+Caddy 会自动管理 HTTPS，因此可以将服务限制在本地进行监听：
+
+```javascript
+// config/config.js
+module.exports = {
+ server: {
+ port: 3000,
+ host: '127.0.0.1' // 只监听本地
+ }
+}
+```
+
+**Caddy 特点**
+
+* 🔒 自动 HTTPS，零配置证书管理
+* 🛡️ 安全默认配置，启用现代 TLS 套件
+* ⚡ HTTP/2 和流式传输支持
+* 🔧 配置文件简洁，易于维护
+
+---
+
+## Nginx Proxy Manager (NPM) 方案
+
+Nginx Proxy Manager 通过图形化界面管理反向代理和 HTTPS 证书，並以 Docker 容器部署。
+
+**1. 在 NPM 创建新的 Proxy Host**
+
+Details 配置如下：
+
+| 项目 | 设置 |
+| --------------------- | ----------------------- |
+| Domain Names | relay.example.com |
+| Scheme | http |
+| Forward Hostname / IP | 192.168.0.1 (docker 机器 IP) |
+| Forward Port | 3000 |
+| Block Common Exploits | ☑️ |
+| Websockets Support | ❌ **关闭** |
+| Cache Assets | ❌ **关闭** |
+| Access List | Publicly Accessible |
+
+> 注意：
+> - 请确保 Claude Relay Service **监听 host 为 `0.0.0.0` 、容器 IP 或本机 IP**，以便 NPM 实现内网连接。
+> - **Websockets Support 和 Cache Assets 必须关闭**，否则会导致 SSE / 流式响应失败。
+
+**2. Custom locations**
+
+無需添加任何内容，保持为空。
+
+**3. SSL 设置**
+
+* **SSL Certificate**: Request a new SSL Certificate (Let's Encrypt) 或已有证书
+* ☑️ **Force SSL**
+* ☑️ **HTTP/2 Support**
+* ☑️ **HSTS Enabled**
+* ☑️ **HSTS Subdomains**
+
+**4. Advanced 配置**
+
+Custom Nginx Configuration 中添加以下内容：
+
+```nginx
+# 传递真实用户 IP
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+
+# 支持 WebSocket / SSE 等流式通信
+proxy_http_version 1.1;
+proxy_set_header Upgrade $http_upgrade;
+proxy_set_header Connection "upgrade";
+proxy_buffering off;
+
+# 长连接 / 超时设置（适合 AI 聊天流式传输）
+proxy_read_timeout 300s;
+proxy_send_timeout 300s;
+proxy_connect_timeout 30s;
+
+# ---- 安全性设置 ----
+# 严格 HTTPS 策略 (HSTS)
+add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+# 阻挡点击劫持与内容嗅探
+add_header X-Frame-Options "DENY" always;
+add_header X-Content-Type-Options "nosniff" always;
+
+# Referrer / Permissions 限制策略
+add_header Referrer-Policy "no-referrer-when-downgrade" always;
+add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
+
+# 隐藏服务器信息（等效于 Caddy 的 `-Server`）
+proxy_hide_header Server;
+
+# ---- 性能微调 ----
+# 关闭代理端缓存，确保即时响应（SSE / Streaming）
+proxy_cache_bypass $http_upgrade;
+proxy_no_cache $http_upgrade;
+proxy_request_buffering off;
+```
+
+**4. 启动和验证**
+
+* 保存后等待 NPM 自动申请 Let's Encrypt 证书（如果有）。
+* Dashboard 中查看 Proxy Host 状态，确保显示为 "Online"。
+* 访问 `https://relay.example.com`，如果显示绿色锁图标即表示 HTTPS 正常。
+
+**NPM 特点**
+
+* 🔒 自动申请和续期证书
+* 🔧 图形化界面，方便管理多服务
+* ⚡ 原生支持 HTTP/2 / HTTPS
+* 🚀 适合 Docker 容器部署
+
+---
+
+上述两种方案均可用于生产部署。
+
+---
+
+## 💡 使用建议
+
+### 账户管理
+
+- **定期检查**: 每周看看账户状态，及时处理异常
+- **合理分配**: 可以给不同的人分配不同的apikey，可以根据不同的apikey来分析用量
+
+### 安全建议
+
+- **使用HTTPS**: 强烈建议使用Caddy反向代理（自动HTTPS），确保数据传输安全
+- **定期备份**: 重要配置和数据要备份
+- **监控日志**: 定期查看异常日志
+- **更新密钥**: 定期更换JWT和加密密钥
+- **防火墙设置**: 只开放必要的端口（80, 443），隐藏直接服务端口
+
+---
+
+## 🆘 遇到问题怎么办？
+
+### 自助排查
+
+1. **查看日志**: `logs/` 目录下的日志文件
+2. **检查配置**: 确认配置文件设置正确
+3. **测试连通性**: 用 curl 测试API是否正常
+4. **重启服务**: 有时候重启一下就好了
+
+### 寻求帮助
+
+- **GitHub Issues**: 提交详细的错误信息
+- **查看文档**: 仔细阅读错误信息和文档
+- **社区讨论**: 看看其他人是否遇到类似问题
+
+---
+
+## ❤️ 赞助支持
+
+如果您觉得这个项目对您有帮助，请考虑赞助支持项目的持续开发。您的支持是我们最大的动力！
+
+
+
+
+ 
+
+
+
+
+  |
+  |
+
+
+
+
+
+**⭐ 觉得有用的话给个Star呗，这是对作者最大的鼓励！**
+
+**🤝 有问题欢迎提Issue，有改进建议欢迎PR**
+
+
diff --git a/README_EN.md b/README_EN.md
index e3e8cdbb..2eac90ca 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -1,5 +1,4 @@
-# Claude Relay Service (Antigravity Edition)
-
+# Claude Relay Service
> [!CAUTION]
> **Security Update**: v1.1.248 and below contain a critical admin authentication bypass vulnerability allowing unauthorized access to the admin panel.
@@ -8,117 +7,606 @@
-This fork focuses on:
-- Native compatibility for `claude` (Claude Code CLI)
-- Antigravity OAuth integration + path-based routing
-- Better stability for streaming (SSE) workloads
-- Optional request/response dumps for debugging
+[](https://opensource.org/licenses/MIT)
+[](https://nodejs.org/)
+[](https://redis.io/)
+[](https://www.docker.com/)
+
+**🔐 Self-hosted Claude API relay service with multi-account management**
+
+[中文文档](README.md) • [Preview](https://demo.pincc.ai/admin-next/login) • [Telegram Channel](https://t.me/claude_relay_service)
+
+
---
-## Highlights
+## ⭐ If You Find It Useful, Please Give It a Star!
-- **Claude Code protocol compatibility**: `thoughtSignature` fallback + cache, tool_result passthrough, and message ordering fixes.
-- **Antigravity OAuth**: account type `gemini-antigravity` with permission checks.
-- **Path-based routing (Anthropic Messages API)**:
- - `/api` -> Claude account pool (default)
- - `/antigravity/api` -> Antigravity OAuth account pool
- - `/gemini-cli/api` -> Gemini OAuth account pool
-- **Stability**:
- - Zombie stream watchdog (disconnect after 45s without valid data)
- - Auto retry + account switching for Antigravity `429 Resource Exhausted` (streaming and non-streaming)
-- **Observability**: JSONL dumps for request/response/tools/upstream (with size limit + rotation)
+> Open source is not easy, your Star is my motivation to continue updating 🚀
+> Join [Telegram Channel](https://t.me/claude_relay_service) for the latest updates
---
-## Quick Start
+## ⚠️ Important Notice
-### Requirements
-- Node.js 18+ (or Docker)
-- Redis 6+/7+
+**Please read carefully before using this project:**
-### Docker Compose (recommended)
+🚨 **Terms of Service Risk**: Using this project may violate Anthropic's terms of service. Please carefully read Anthropic's user agreement before use. All risks from using this project are borne by the user.
+📖 **Disclaimer**: This project is for technical learning and research purposes only. The author is not responsible for any account bans, service interruptions, or other losses caused by using this project.
+
+## 🤔 Is This Project Right for You?
+
+- 🌍 **Regional Restrictions**: Can't directly access Claude Code service in your region?
+- 🔒 **Privacy Concerns**: Worried about third-party mirror services logging or leaking your conversation content?
+- 👥 **Cost Sharing**: Want to share Claude Code Max subscription costs with friends?
+- ⚡ **Stability Issues**: Third-party mirror sites often fail and are unstable, affecting efficiency?
+
+If you have any of these concerns, this project might be suitable for you.
+
+### Suitable Scenarios
+
+✅ **Cost Sharing with Friends**: 3-5 friends sharing Claude Code Max subscription, enjoying Opus freely
+✅ **Privacy Sensitive**: Don't want third-party mirrors to see your conversation content
+✅ **Technical Tinkering**: Have basic technical skills, willing to build and maintain yourself
+✅ **Stability Needs**: Need long-term stable Claude access, don't want to be restricted by mirror sites
+✅ **Regional Restrictions**: Cannot directly access Claude official service
+
+### Unsuitable Scenarios
+
+❌ **Complete Beginner**: Don't understand technology at all, don't even know how to buy a server
+❌ **Occasional Use**: Use it only a few times a month, not worth the hassle
+❌ **Registration Issues**: Cannot register Claude account yourself
+❌ **Payment Issues**: No payment method to subscribe to Claude Code
+
+**If you're just an ordinary user with low privacy requirements, just want to casually play around and quickly experience Claude, then choosing a mirror site you're familiar with would be more suitable.**
+
+---
+
+## 💭 Why Build Your Own?
+
+### Potential Issues with Existing Mirror Sites
+
+- 🕵️ **Privacy Risk**: Your conversation content is completely visible to others, forget about business secrets
+- 🐌 **Performance Instability**: Slow when many people use it, often crashes during peak hours
+- 💰 **Price Opacity**: Don't know the actual costs
+
+### Benefits of Self-hosting
+
+- 🔐 **Data Security**: All API requests only go through your own server, direct connection to Anthropic API
+- ⚡ **Controllable Performance**: Only a few of you using it, Max $200 package basically allows you to enjoy Opus freely
+- 💰 **Cost Transparency**: Clear view of how many tokens used, specific costs calculated at official prices
+- 📊 **Complete Monitoring**: Usage statistics, cost analysis, performance monitoring all available
+
+---
+
+## 🚀 Core Features
+
+> 📸 **[Click to view interface preview](docs/preview.md)** - See detailed screenshots of the Web management interface
+
+### Basic Features
+- ✅ **Multi-account Management**: Add multiple Claude accounts for automatic rotation
+- ✅ **Custom API Keys**: Assign independent keys to each person
+- ✅ **Usage Statistics**: Detailed records of how many tokens each person used
+
+### Advanced Features
+- 🔄 **Smart Switching**: Automatically switch to next account when one has issues
+- 🚀 **Performance Optimization**: Connection pooling, caching to reduce latency
+- 📊 **Monitoring Dashboard**: Web interface to view all data
+- 🛡️ **Security Control**: Access restrictions, rate limiting
+- 🌐 **Proxy Support**: Support for HTTP/SOCKS5 proxies
+
+---
+
+## 📋 Deployment Requirements
+
+### Hardware Requirements (Minimum Configuration)
+- **CPU**: 1 core is sufficient
+- **Memory**: 512MB (1GB recommended)
+- **Storage**: 30GB available space
+- **Network**: Access to Anthropic API (recommend US region servers)
+- **Recommendation**: 2 cores 4GB is basically enough, choose network with good return routes to your country (to improve speed, recommend not using proxy or setting server IP for direct connection)
+
+### Software Requirements
+- **Node.js** 18 or higher
+- **Redis** 6 or higher
+- **Operating System**: Linux recommended
+
+### Cost Estimation
+- **Server**: Light cloud server, $5-10 per month
+- **Claude Subscription**: Depends on how you share costs
+- **Others**: Domain name (optional)
+
+---
+
+## 📦 Manual Deployment
+
+### Step 1: Environment Setup
+
+**Ubuntu/Debian users:**
```bash
-cp .env.example .env
-cp config/config.example.js config/config.js
+# Install Node.js
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
-# Edit .env at least:
-# JWT_SECRET=... (random string)
-# ENCRYPTION_KEY=... (32-char random string)
-
-docker-compose up -d
+# Install Redis
+sudo apt update
+sudo apt install redis-server
+sudo systemctl start redis-server
```
-### Node (no Docker)
+**CentOS/RHEL users:**
+```bash
+# Install Node.js
+curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
+sudo yum install -y nodejs
+
+# Install Redis
+sudo yum install redis
+sudo systemctl start redis
+```
+
+### Step 2: Download and Configure
```bash
+# Download project
+git clone https://github.com/Wei-Shaw/claude-relay-service.git
+cd claude-relay-service
+
+# Install dependencies
npm install
-cp .env.example .env
+
+# Copy configuration files (Important!)
cp config/config.example.js config/config.js
-npm run setup
-npm run service:start:daemon
+cp .env.example .env
```
-### Admin UI
+### Step 3: Configuration File Setup
-- URL: `http://:3000/web`
-- Initial credentials: generated by `npm run setup` and saved to `data/init.json` (Docker users can also inspect container logs).
+**Edit `.env` file:**
+```bash
+# Generate these two keys randomly, but remember them
+JWT_SECRET=your-super-secret-key
+ENCRYPTION_KEY=32-character-encryption-key-write-randomly
+
+# Redis configuration
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+```
+
+**Edit `config/config.js` file:**
+```javascript
+module.exports = {
+ server: {
+ port: 3000, // Service port, can be changed
+ host: '0.0.0.0' // Don't change
+ },
+ redis: {
+ host: '127.0.0.1', // Redis address
+ port: 6379 // Redis port
+ },
+ // Keep other configurations as default
+}
+```
+
+### Step 4: Start Service
+
+```bash
+# Initialize
+npm run setup # Will randomly generate admin account password info, stored in data/init.json
+
+# Start service
+npm run service:start:daemon # Run in background (recommended)
+
+# Check status
+npm run service:status
+```
---
-## Using with Claude Code (CLI)
+## 🎮 Getting Started
-### Antigravity pool (recommended)
+### 1. Open Management Interface
+
+Browser visit: `http://your-server-IP:3000/web`
+
+Default admin account: Look in data/init.json
+
+### 2. Add Claude Account
+
+This step is quite important, requires OAuth authorization:
+
+1. Click "Claude Accounts" tab
+2. If you're worried about multiple accounts sharing 1 IP getting banned, you can optionally set a static proxy IP
+3. Click "Add Account"
+4. Click "Generate Authorization Link", will open a new page
+5. Complete Claude login and authorization in the new page
+6. Copy the returned Authorization Code
+7. Paste to page to complete addition
+
+**Note**: If you're in China, this step may require VPN.
+
+### 3. Create API Key
+
+Assign a key to each user:
+
+1. Click "API Keys" tab
+2. Click "Create New Key"
+3. Give the key a name, like "Zhang San's Key"
+4. Set usage limits (optional)
+5. Save, note down the generated key
+
+### 4. Start Using Claude Code and Gemini CLI
+
+Now you can replace the official API with your own service:
+
+**Claude Code Set Environment Variables:**
+
+Default uses standard Claude account pool:
+
+```bash
+export ANTHROPIC_BASE_URL="http://127.0.0.1:3000/api/" # Fill in your server's IP address or domain
+export ANTHROPIC_AUTH_TOKEN="API key created in the backend"
+```
+
+**VSCode Claude Plugin Configuration:**
+
+If using VSCode Claude plugin, configure in `~/.claude/config.json`:
+
+```json
+{
+ "primaryApiKey": "crs"
+}
+```
+
+If the file doesn't exist, create it manually. Windows users path is `C:\Users\YourUsername\.claude\config.json`.
+
+**Gemini CLI Set Environment Variables:**
+
+**Method 1 (Recommended): Via Gemini Assist API**
+
+Each account enjoys 1000 requests per day, 60 requests per minute free quota.
+
+```bash
+CODE_ASSIST_ENDPOINT="http://127.0.0.1:3000/gemini" # Fill in your server's IP address or domain
+GOOGLE_CLOUD_ACCESS_TOKEN="API key created in the backend"
+GOOGLE_GENAI_USE_GCA="true"
+GEMINI_MODEL="gemini-2.5-pro"
+```
+
+> **Note**: gemini-cli console will show `Failed to fetch user info: 401 Unauthorized`, but this doesn't affect usage.
+
+**Method 2: Via Gemini API**
+
+Very limited free quota, easily triggers 429 errors.
+
+```bash
+GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:3000/gemini" # Fill in your server's IP address or domain
+GEMINI_API_KEY="API key created in the backend"
+GEMINI_MODEL="gemini-2.5-pro"
+```
+
+**Use Claude Code:**
```bash
-export ANTHROPIC_BASE_URL="http://:3000/antigravity/api/"
-export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxxxxxx"
-export ANTHROPIC_MODEL="claude-opus-4-5"
claude
```
-### Gemini pool
+**Use Gemini CLI:**
```bash
-export ANTHROPIC_BASE_URL="http://:3000/gemini-cli/api/"
-export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxxxxxx"
-export ANTHROPIC_MODEL="gemini-2.5-pro"
-claude
-```
-
-### Standard Claude pool
-
-```bash
-export ANTHROPIC_BASE_URL="http://:3000/api/"
-export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxxxxxx"
-claude
+gemini
```
---
-## Antigravity Quota & Models
+## 🔧 Daily Maintenance
-- Quota display: in Admin UI -> Accounts -> `gemini-antigravity` -> click **Test/Refresh**.
-- Dynamic models list:
- - Anthropic/Claude Code routing: `GET /antigravity/api/v1/models` (proxies Antigravity `fetchAvailableModels`)
- - OpenAI-compatible routing: `GET /openai/gemini/models` (or `GET /openai/gemini/v1/models`)
+### Service Management
+
+```bash
+# Check service status
+npm run service:status
+
+# View logs
+npm run service:logs
+
+# Restart service
+npm run service:restart:daemon
+
+# Stop service
+npm run service:stop
+```
+
+### Monitor Usage
+
+- **Web Interface**: `http://your-domain:3000/web` - View usage statistics
+- **Health Check**: `http://your-domain:3000/health` - Confirm service is normal
+- **Log Files**: Various log files in `logs/` directory
+
+### Upgrade Guide
+
+When a new version is released, follow these steps to upgrade the service:
+
+```bash
+# 1. Navigate to project directory
+cd claude-relay-service
+
+# 2. Pull latest code
+git pull origin main
+
+# If you encounter package-lock.json conflicts, use the remote version
+git checkout --theirs package-lock.json
+git add package-lock.json
+
+# 3. Install new dependencies (if any)
+npm install
+
+# 4. Restart service
+npm run service:restart:daemon
+
+# 5. Check service status
+npm run service:status
+```
+
+**Important Notes:**
+- Before upgrading, it's recommended to backup important configuration files (.env, config/config.js)
+- Check the changelog to understand if there are any breaking changes
+- Database structure changes will be migrated automatically if needed
+
+### Common Issue Resolution
+
+**Can't connect to Redis?**
+```bash
+# Check if Redis is running
+redis-cli ping
+
+# Should return PONG
+```
+
+**OAuth authorization failed?**
+- Check if proxy settings are correct
+- Ensure normal access to claude.ai
+- Clear browser cache and retry
+
+**API request failed?**
+- Check if API Key is correct
+- View log files for error information
+- Confirm Claude account status is normal
---
-## Debug Dumps (optional)
+## 🛠️ Advanced Usage
-See `.env.example` for the full list. Common toggles:
+### Reverse Proxy Deployment Guide
-- `ANTHROPIC_DEBUG_REQUEST_DUMP=true`
-- `ANTHROPIC_DEBUG_RESPONSE_DUMP=true`
-- `ANTIGRAVITY_DEBUG_UPSTREAM_REQUEST_DUMP=true`
-- `ANTIGRAVITY_DEBUG_UPSTREAM_RESPONSE_DUMP=true`
-- `DUMP_MAX_FILE_SIZE_BYTES=10485760`
+For production environments, it is recommended to use a reverse proxy for automatic HTTPS, security headers, and performance optimization. Two common solutions are provided below: **Caddy** and **Nginx Proxy Manager (NPM)**.
---
-## License
+## Caddy Solution
-This project is licensed under the [MIT License](LICENSE).
+Caddy is a web server that automatically manages HTTPS certificates, with simple configuration and excellent performance, ideal for deployments without Docker environments.
+**1. Install Caddy**
+
+```bash
+# Ubuntu/Debian
+sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+sudo apt update
+sudo apt install caddy
+
+# CentOS/RHEL/Fedora
+sudo yum install yum-plugin-copr
+sudo yum copr enable @caddy/caddy
+sudo yum install caddy
+```
+
+**2. Caddy Configuration**
+
+Edit `/etc/caddy/Caddyfile`:
+
+```caddy
+your-domain.com {
+ # Reverse proxy to local service
+ reverse_proxy 127.0.0.1:3000 {
+ # Support streaming responses or SSE
+ flush_interval -1
+
+ # Pass real IP
+ header_up X-Real-IP {remote_host}
+ header_up X-Forwarded-For {remote_host}
+ header_up X-Forwarded-Proto {scheme}
+
+ # Long read/write timeout configuration
+ transport http {
+ read_timeout 300s
+ write_timeout 300s
+ dial_timeout 30s
+ }
+ }
+
+ # Security headers
+ header {
+ Strict-Transport-Security "max-age=31536000; includeSubDomains"
+ X-Frame-Options "DENY"
+ X-Content-Type-Options "nosniff"
+ -Server
+ }
+}
+```
+
+**3. Start Caddy**
+
+```bash
+sudo caddy validate --config /etc/caddy/Caddyfile
+sudo systemctl start caddy
+sudo systemctl enable caddy
+sudo systemctl status caddy
+```
+
+**4. Service Configuration**
+
+Since Caddy automatically manages HTTPS, you can restrict the service to listen locally only:
+
+```javascript
+// config/config.js
+module.exports = {
+ server: {
+ port: 3000,
+ host: '127.0.0.1' // Listen locally only
+ }
+}
+```
+
+**Caddy Features**
+
+* 🔒 Automatic HTTPS with zero-configuration certificate management
+* 🛡️ Secure default configuration with modern TLS suites
+* ⚡ HTTP/2 and streaming support
+* 🔧 Concise configuration files, easy to maintain
+
+---
+
+## Nginx Proxy Manager (NPM) Solution
+
+Nginx Proxy Manager manages reverse proxies and HTTPS certificates through a graphical interface, deployed as a Docker container.
+
+**1. Create a New Proxy Host in NPM**
+
+Configure the Details as follows:
+
+| Item | Setting |
+| --------------------- | ------------------------ |
+| Domain Names | relay.example.com |
+| Scheme | http |
+| Forward Hostname / IP | 192.168.0.1 (docker host IP) |
+| Forward Port | 3000 |
+| Block Common Exploits | ☑️ |
+| Websockets Support | ❌ **Disable** |
+| Cache Assets | ❌ **Disable** |
+| Access List | Publicly Accessible |
+
+> Note:
+> - Ensure Claude Relay Service **listens on `0.0.0.0`, container IP, or host IP** to allow NPM internal network connections.
+> - **Websockets Support and Cache Assets must be disabled**, otherwise SSE / streaming responses will fail.
+
+**2. Custom locations**
+
+No content needed, keep it empty.
+
+**3. SSL Settings**
+
+* **SSL Certificate**: Request a new SSL Certificate (Let's Encrypt) or existing certificate
+* ☑️ **Force SSL**
+* ☑️ **HTTP/2 Support**
+* ☑️ **HSTS Enabled**
+* ☑️ **HSTS Subdomains**
+
+**4. Advanced Configuration**
+
+Add the following to Custom Nginx Configuration:
+
+```nginx
+# Pass real user IP
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+
+# Support WebSocket / SSE streaming
+proxy_http_version 1.1;
+proxy_set_header Upgrade $http_upgrade;
+proxy_set_header Connection "upgrade";
+proxy_buffering off;
+
+# Long connection / timeout settings (for AI chat streaming)
+proxy_read_timeout 300s;
+proxy_send_timeout 300s;
+proxy_connect_timeout 30s;
+
+# ---- Security Settings ----
+# Strict HTTPS policy (HSTS)
+add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+# Block clickjacking and content sniffing
+add_header X-Frame-Options "DENY" always;
+add_header X-Content-Type-Options "nosniff" always;
+
+# Referrer / Permissions restriction policies
+add_header Referrer-Policy "no-referrer-when-downgrade" always;
+add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
+
+# Hide server information (equivalent to Caddy's `-Server`)
+proxy_hide_header Server;
+
+# ---- Performance Tuning ----
+# Disable proxy caching for real-time responses (SSE / Streaming)
+proxy_cache_bypass $http_upgrade;
+proxy_no_cache $http_upgrade;
+proxy_request_buffering off;
+```
+
+**5. Launch and Verify**
+
+* After saving, wait for NPM to automatically request Let's Encrypt certificate (if applicable).
+* Check Proxy Host status in Dashboard to ensure it shows "Online".
+* Visit `https://relay.example.com`, if the green lock icon appears, HTTPS is working properly.
+
+**NPM Features**
+
+* 🔒 Automatic certificate application and renewal
+* 🔧 Graphical interface for easy multi-service management
+* ⚡ Native HTTP/2 / HTTPS support
+* 🚀 Ideal for Docker container deployments
+
+---
+
+Both solutions are suitable for production deployment. If you use a Docker environment, **Nginx Proxy Manager is more convenient**; if you want to keep software lightweight and automated, **Caddy is a better choice**.
+
+---
+
+## 💡 Usage Recommendations
+
+### Account Management
+- **Regular Checks**: Check account status weekly, handle exceptions promptly
+- **Reasonable Allocation**: Can assign different API keys to different people, analyze usage based on different API keys
+
+### Security Recommendations
+- **Use HTTPS**: Strongly recommend using Caddy reverse proxy (automatic HTTPS) to ensure secure data transmission
+- **Regular Backups**: Back up important configurations and data
+- **Monitor Logs**: Regularly check exception logs
+- **Update Keys**: Regularly change JWT and encryption keys
+- **Firewall Settings**: Only open necessary ports (80, 443), hide direct service ports
+
+---
+
+## 🆘 What to Do When You Encounter Problems?
+
+### Self-troubleshooting
+1. **Check Logs**: Log files in `logs/` directory
+2. **Check Configuration**: Confirm configuration files are set correctly
+3. **Test Connectivity**: Use curl to test if API is normal
+4. **Restart Service**: Sometimes restarting fixes it
+
+### Seeking Help
+- **GitHub Issues**: Submit detailed error information
+- **Read Documentation**: Carefully read error messages and documentation
+- **Community Discussion**: See if others have encountered similar problems
+
+---
+
+## 📄 License
+This project uses the [MIT License](LICENSE).
+
+---
+
+
+
+**⭐ If you find it useful, please give it a Star, this is the greatest encouragement to the author!**
+
+**🤝 Feel free to submit Issues for problems, welcome PRs for improvement suggestions**
+
+
\ No newline at end of file