iflow-local-proxy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# iFlow Local Proxy - 本地安全反代（单账号模式）
+
+仅绑定 `127.0.0.1` 的 iFlow API 反向代理，内置多层防封保护机制。**仅支持单个账号**。
+
+## 特性
+
+- **🔒 仅本地访问** - 绑定 127.0.0.1，外部网络完全不可达
+- **🛡️ 熔断器** - 收到 434 (AK blocked) 立即停止所有请求，避免连续触发封禁
+- **⏱️ 请求节流** - 最小间隔 + 随机抖动，模拟自然使用节奏
+- **📋 模型白名单** - 只允许请求已确认存在的模型，避免无效请求触发风控
+- **🔑 HMAC 签名** - 每个请求携带签名，完全模拟官方 CLI 行为
+- **🔄 自动刷新** - OAuth / Cookie 凭据自动续期
+- **👤 单账号模式** - 仅使用一个账号，设置新账号自动覆盖旧的
+
+## 安装
+
+### 方式一: npm 全局安装（推荐）
+```bash
+npm install -g iflow-local-proxy
+```
+
+安装后直接使用:
+```bash
+# 启动代理
+iflow-local-proxy
+
+# OAuth 手机号登录
+iflow-local-proxy login
+
+# 指定端口
+iflow-local-proxy --port 9000
+
+# 指定配置文件
+iflow-local-proxy --config /path/to/config.yaml
+```
+
+### 方式二: npx 免安装运行
+```bash
+npx iflow-local-proxy
+npx iflow-local-proxy login
+```
+
+### 方式三: 源码运行
+```bash
+git clone <repo-url>
+cd iflow-local-proxy
+npm install
+npm start
+```
+
+## 添加凭据
+
+### 方式一: 设置 API Key（最简单）
+```bash
+curl -X POST http://127.0.0.1:8318/api/account/set-key ^
+  -H "Content-Type: application/json" ^
+  -d "{\"apiKey\": \"sk-xxx\", \"name\": \"my-account\"}"
+```
+
+### 方式二: OAuth 登录
+```bash
+npm run login
+# 或通过 API:
+# POST http://127.0.0.1:8318/api/login/oauth
+```
+
+### 方式三: Cookie 登录
+```bash
+curl -X POST http://127.0.0.1:8318/api/account/set-cookie ^
+  -H "Content-Type: application/json" ^
+  -d "{\"cookie\": \"BXAuth=xxx;\", \"name\": \"cookie-account\"}"
+```
+
+> **注意**: 单账号模式下，设置新账号会自动删除旧账号。
+
+## API 端点
+
+### 代理端点 (兼容 OpenAI / Anthropic)
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/v1/models` | 模型列表 |
+| POST | `/v1/chat/completions` | OpenAI 格式聊天 |
+| POST | `/v1/messages` | Anthropic 格式聊天 |
+| POST | `/v1/messages/count_tokens` | Token 计数 |
+
+### 管理端点
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/` | 服务状态概览 |
+| GET | `/api/status` | 详细状态 |
+| GET | `/api/account` | 查看当前账号 |
+| POST | `/api/account/set-key` | 设置 API Key (覆盖) |
+| POST | `/api/account/set-cookie` | Cookie 登录 (覆盖) |
+| POST | `/api/account/refresh` | 手动刷新凭据 |
+| DELETE | `/api/account` | 删除当前账号 |
+| GET | `/api/circuit-breaker` | 熔断器状态 |
+| POST | `/api/circuit-breaker/reset` | 重置熔断器 |
+| POST | `/api/login/oauth` | 启动 OAuth 登录 (覆盖) |
+
+## 防封保护机制
+
+### 1. 熔断器 (Circuit Breaker)
+- 收到 **434 (AK blocked)** 响应 → 立即暂停所有请求（默认 1 小时）
+- 连续 3 次 434 → 永久熔断（需手动 `POST /api/circuit-breaker/reset`）
+- 暂停期间所有请求返回 503，不会发送到上游
+
+### 2. 请求节流 (Throttler)
+- 每个请求之间至少间隔 2s + 0~1s 随机抖动
+- 每分钟最多 20 个请求（硬上限）
+- 超出限制时请求排队等待，不会直接拒绝
+
+### 3. 模型白名单
+- 只允许向白名单中的模型发送请求
+- 请求不存在的模型会被本地拦截，不会发到上游
+- 可在 `config.yaml` 中配置
+
+### 4. HMAC 签名
+- 每个请求自动携带 `x-iflow-signature` / `x-iflow-timestamp` / `session-id`
+- 完全模拟官方 iFlow-Cli 行为
+
+## 配置客户端
+
+### Claude Code
+```bash
+claude config set --global apiProvider "openai"
+claude config set --global apiBaseUrl "http://127.0.0.1:8318"
+claude config set --global apiKey "any-key"
+claude config set --global model "deepseek-r1"
+```
+
+### Cline (VS Code 插件)
+- API Provider: OpenAI Compatible
+- Base URL: `http://127.0.0.1:8318/v1`
+- API Key: 任意值
+- Model: 选择白名单中的模型
+
+### OpenAI SDK
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://127.0.0.1:8318/v1", api_key="any")
+response = client.chat.completions.create(
+    model="deepseek-r1",
+    messages=[{"role": "user", "content": "hello"}]
+)
+```
+
+## 配置说明
+
+参见 [config.yaml](config.yaml) 中的详细注释。

package/bin/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * iflow-local-proxy CLI 入口
+ *
+ * 用法:
+ *   iflow-local-proxy              启动代理服务
+ *   iflow-local-proxy login        OAuth 手机号登录
+ *   iflow-local-proxy --help       显示帮助
+ *   iflow-local-proxy --version    显示版本
+ */
+
+import { fileURLToPath, pathToFileURL } from 'url';
+import path from 'path';
+import fs from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+// 读版本号
+const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8'));
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+iflow-local-proxy v${pkg.version}
+iFlow 本地安全反代 - 仅绑定 127.0.0.1，内置熔断器/限速/签名
+
+用法:
+  iflow-local-proxy                启动代理服务
+  iflow-local-proxy login          OAuth 手机号登录
+  iflow-local-proxy --config <path> 指定配置文件路径
+
+选项:
+  --config <path>   指定配置文件 (默认: ./config.yaml 或 ~/.iflow-local-proxy/config.yaml)
+  --port <port>     覆盖配置中的端口号
+  -v, --version     显示版本号
+  -h, --help        显示帮助
+
+详细文档: https://www.npmjs.com/package/iflow-local-proxy
+`);
+  process.exit(0);
+}
+
+// 处理 --port 覆盖
+const portIdx = args.indexOf('--port');
+if (portIdx !== -1 && args[portIdx + 1]) {
+  process.env.IFLOW_PORT = args[portIdx + 1];
+}
+
+if (command === 'login') {
+  // 加载 OAuth CLI 登录
+  await import(pathToFileURL(path.join(PKG_ROOT, 'src', 'auth', 'oauth-cli.js')).href);
+} else if (!command || command.startsWith('-')) {
+  // 默认: 启动代理服务
+  await import(pathToFileURL(path.join(PKG_ROOT, 'src', 'index.js')).href);
+} else {
+  console.error(`未知命令: ${command}`);
+  console.error('运行 iflow-local-proxy --help 查看帮助');
+  process.exit(1);
+}

package/config.yaml

@@ -0,0 +1,56 @@
+# ========================================
+# iFlow 本地安全反代 - 配置文件
+# ========================================
+
+# 服务端口（仅绑定 127.0.0.1，外部不可访问）
+port: 8318
+
+# 凭据存储目录
+auth-dir: "~/.iflow-local-proxy"
+
+# ========================================
+# 防封保护策略
+# ========================================
+protection:
+  # 请求最小间隔（毫秒），避免被识别为高频刷API
+  min-request-interval: 2000
+
+  # 请求间隔随机抖动范围（毫秒），叠加在 min-interval 之上使请求间隔更自然
+  jitter-max: 1000
+
+  # 每分钟最大请求数（硬上限）
+  max-requests-per-minute: 20
+
+  # 熔断器：收到 434 (AK blocked) 后立即停止所有请求
+  circuit-breaker:
+    enabled: true
+    # 收到 434 后暂停时间（秒），期间所有请求直接拒绝
+    pause-duration: 3600
+    # 连续 434 次数阈值，超过此数则永久熔断（需手动恢复）
+    max-consecutive-434: 3
+
+  # 模型白名单（只允许请求已确认存在的模型，避免因请求无效模型被风控）
+  # 留空则不限制（不建议）
+  model-whitelist:
+    - "deepseek-r1"
+    - "deepseek-v3"
+    - "deepseek-v3.1"
+    - "deepseek-v3.2"
+    - "deepseek-v3.2-chat"
+    - "deepseek-v3.2-reasoner"
+    - "glm-4.6"
+    - "glm-4.7"
+    - "glm-5"
+    - "qwen3-32b"
+    - "qwen3-235b"
+    - "qwen3-max"
+    - "qwen3-coder-plus"
+    - "kimi-k2"
+    - "kimi-k2.5"
+    - "minimax-m2"
+    - "minimax-m2.5"
+
+# 日志级别: debug | info | warn | error
+log-level: "info"
+
+# 注: 本项目为单账号模式，不支持多账号轮换

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "iflow-local-proxy",
+  "version": "1.0.0",
+  "description": "iFlow 本地安全反代 - 仅绑定 127.0.0.1，内置熔断器/限速/签名，最大程度规避封禁风险",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "iflow-local-proxy": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "config.yaml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "login": "node src/auth/oauth-cli.js"
+  },
+  "keywords": [
+    "iflow",
+    "proxy",
+    "openai",
+    "anthropic",
+    "api",
+    "reverse-proxy",
+    "local"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "express": "^4.21.0",
+    "uuid": "^9.0.0",
+    "yaml": "^2.4.0"
+  },
+  "license": "MIT"
+}