README.md

---
title: Amazon Q to OpenAI API
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# Amazon Q to OpenAI API Bridge

将 Amazon Q Developer 转换为 OpenAI 兼容的 API 服务，支持流式和非流式响应。

## ✨ 核心特性

- **OpenAI 兼容接口** - 完全兼容 OpenAI Chat Completions API（`/v1/chat/completions`）
- **账号管理系统** - 支持多账号管理，启用/禁用控制，自动令牌刷新
- **智能统计监控** - 自动统计成功/失败次数，错误超阈值自动禁用账号
- **设备授权登录** - 通过 URL 快速登录并自动创建账号（5分钟超时）
- **智能负载均衡** - 从启用的账号中随机选择，实现简单的负载分配
- **HTTP 代理支持** - 可配置代理服务器，支持所有 HTTP 请求
- **API Key 白名单** - 可选的访问控制，支持开发模式
- **现代化前端** - 美观的 Web 控制台，标签页布局，支持账号管理和 Chat 测试
- **自动重试机制** - Token 过期时自动刷新并重试请求

## 🚀 快速开始

### 1. 安装依赖

```bash
# 创建虚拟环境
python -m venv .venv

# Windows
.venv\Scripts\activate
pip install -r requirements.txt

# Linux/macOS
source .venv/bin/activate
pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
# 复制示例配置
cp .env.example .env

# 编辑 .env 文件
# OPENAI_KEYS="key1,key2,key3"  # 可选，留空则为开发模式
# MAX_ERROR_COUNT=100            # 错误次数阈值
# HTTP_PROXY="http://127.0.0.1:7890"  # HTTP代理（可选）
```

**配置说明：**
- `OPENAI_KEYS` 为空或未设置：开发模式，不校验 Authorization
- `OPENAI_KEYS` 设置后：仅白名单中的 key 可访问 API
- API Key 仅用于访问控制，不映射到特定账号
- `MAX_ERROR_COUNT`：账号连续失败次数超过此值将自动禁用（默认100）
- `HTTP_PROXY`：HTTP代理地址，留空则不使用代理

### 3. 启动服务

```bash
python -m uvicorn app:app --reload --port 8000
```

访问：
- 🏠 Web 控制台：http://localhost:8000/
- 💚 健康检查：http://localhost:8000/healthz

## 📖 使用指南

### 账号管理

#### 方式一：Web 控制台（推荐）

访问 http://localhost:8000/ 使用可视化界面管理账号：
- 查看所有账号及状态
- 创建/删除/编辑账号
- 启用/禁用账号
- 刷新 Token
- URL 登录（设备授权）

#### 方式二：REST API

**创建账号**
```bash
curl -X POST http://localhost:8000/v2/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "label": "我的账号",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "refreshToken": "your-refresh-token",
    "enabled": true
  }'
```

**列出所有账号**
```bash
curl http://localhost:8000/v2/accounts
```

**更新账号（切换启用状态）**
```bash
curl -X PATCH http://localhost:8000/v2/accounts/{account_id} \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

**刷新 Token**
```bash
curl -X POST http://localhost:8000/v2/accounts/{account_id}/refresh
```

**删除账号**
```bash
curl -X DELETE http://localhost:8000/v2/accounts/{account_id}
```

### URL 登录（设备授权）

快速添加账号的最简单方式：

1. **启动登录流程**
```bash
curl -X POST http://localhost:8000/v2/auth/start \
  -H "Content-Type: application/json" \
  -d '{"label": "新账号", "enabled": true}'
```

返回：
```json
{
  "authId": "xxx",
  "verificationUriComplete": "https://...",
  "userCode": "ABCD-1234",
  "expiresIn": 600,
  "interval": 1
}
```

2. **在浏览器中打开 `verificationUriComplete` 完成登录**

3. **等待并创建账号**（最多5分钟）
```bash
curl -X POST http://localhost:8000/v2/auth/claim/{authId}
```

成功后自动创建并启用账号。

### OpenAI 兼容 API

#### 非流式请求

```bash
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4",
    "stream": false,
    "messages": [
      {"role": "system", "content": "你是一个乐于助人的助手"},
      {"role": "user", "content": "你好，请讲一个简短的故事"}
    ]
  }'
```

#### 流式请求（SSE）

```bash
curl -N -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4",
    "stream": true,
    "messages": [
      {"role": "user", "content": "讲一个笑话"}
    ]
  }'
```

#### Python 示例

```python
import openai

client = openai.OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="your-api-key"  # 如果配置了 OPENAI_KEYS
)

response = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[
        {"role": "user", "content": "你好"}
    ]
)

print(response.choices[0].message.content)
```

## 🔐 授权与账号选择

### 授权机制
- **开发模式**（`OPENAI_KEYS` 未设置）：不校验 Authorization
- **生产模式**（`OPENAI_KEYS` 已设置）：必须提供白名单中的 key

### 账号选择策略
- 从所有 `enabled=1` 的账号中**随机选择**
- API Key 不映射到特定账号
- 无可用账号时返回 401

### Token 刷新
- 请求时若账号缺少 accessToken，自动刷新
- 上游返回 401/403 时，自动刷新并重试一次
- 可手动调用刷新接口

## 📁 项目结构

```
.
├── app.py                          # FastAPI 主应用
├── auth_flow.py                    # 设备授权登录
├── replicate.py                    # Amazon Q 请求复刻
├── requirements.txt                # Python 依赖
├── .env.example                    # 环境变量示例
├── .gitignore                      # Git 忽略规则
├── data.sqlite3                    # SQLite 数据库（自动创建）
├── frontend/
│   └── index.html                  # Web 控制台
└── templates/
    └── streaming_request.json      # 请求模板
```

## 🛠️ 技术栈

- **后端**: FastAPI + Python 3.8+
- **数据库**: SQLite3
- **前端**: 纯 HTML/CSS/JavaScript
- **认证**: AWS OIDC 设备授权流程

## 🔧 高级配置

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OPENAI_KEYS` | API Key 白名单（逗号分隔） | 空（开发模式） |
| `MAX_ERROR_COUNT` | 错误次数阈值，超过自动禁用账号 | 100 |
| `HTTP_PROXY` | HTTP代理地址（如 http://127.0.0.1:7890） | 空（不使用代理） |

### 数据库结构

```sql
CREATE TABLE accounts (
    id TEXT PRIMARY KEY,
    label TEXT,
    clientId TEXT,
    clientSecret TEXT,
    refreshToken TEXT,
    accessToken TEXT,
    other TEXT,                    -- JSON 格式的额外信息
    last_refresh_time TEXT,
    last_refresh_status TEXT,
    created_at TEXT,
    updated_at TEXT,
    enabled INTEGER DEFAULT 1,     -- 1=启用, 0=禁用
    error_count INTEGER DEFAULT 0, -- 连续错误次数
    success_count INTEGER DEFAULT 0 -- 成功请求次数
);
```

### 账号统计与自动禁用

系统会自动统计每个账号的请求结果：
- **成功**：返回至少1个有效字符，`success_count+1`，`error_count`重置为0
- **失败**：未返回有效字符或出错，`error_count+1`
- **自动禁用**：当`error_count >= MAX_ERROR_COUNT`时，账号自动设置为`enabled=0`

这确保了有问题的账号不会持续影响服务质量。

## 🐛 故障排查

### 401 Unauthorized
- 检查 `OPENAI_KEYS` 配置
- 确认至少有一个 `enabled=1` 的账号
- 验证账号的 clientId/clientSecret/refreshToken 正确

### Token 刷新失败
- 检查网络连接
- 验证 refreshToken 是否过期
- 查看账号的 `last_refresh_status` 字段

### 无响应/超时
- 检查 Amazon Q 服务可达性
- 查看服务日志排查错误

## 📝 API 端点

### 账号管理
- `POST /v2/accounts` - 创建账号
- `GET /v2/accounts` - 列出所有账号
- `GET /v2/accounts/{id}` - 获取账号详情
- `PATCH /v2/accounts/{id}` - 更新账号
- `DELETE /v2/accounts/{id}` - 删除账号
- `POST /v2/accounts/{id}/refresh` - 刷新 Token

### 设备授权
- `POST /v2/auth/start` - 启动登录流程
- `GET /v2/auth/status/{authId}` - 查询登录状态
- `POST /v2/auth/claim/{authId}` - 等待并创建账号

### OpenAI 兼容
- `POST /v1/chat/completions` - Chat Completions API

### 其他
- `GET /` - Web 控制台
- `GET /healthz` - 健康检查

## 📄 许可证

本项目仅供学习和测试使用。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！