q2api

Amazon Q to API Bridge - Main Service

Star History

将 Amazon Q Developer 转换为兼容 OpenAI 和 Claude API 的服务，支持多账号管理、流式响应和智能负载均衡。

项目地址：

• GitHub: https://github.com/CassiopeiaCode/q2api
• Codeberg: https://codeberg.org/Korieu/amazonq2api

致谢：

• 感谢 amq2api 项目提供的 Claude 消息格式转换参考

✨ 核心特性

API 兼容性

• OpenAI Chat Completions API - 完全兼容 /v1/chat/completions 端点
• Claude Messages API - 完全兼容 /v1/messages 端点，支持流式和非流式
• Tool Use 支持 - 完整支持 Claude 格式的工具调用和结果返回
• System Prompt - 支持系统提示词和多模态内容（文本、图片）

账号管理

• 多账号支持 - 管理多个 Amazon Q 账号，灵活启用/禁用
• 自动令牌刷新 - 后台定时刷新过期令牌，请求时自动重试
• 智能统计 - 自动统计成功/失败次数，错误超阈值自动禁用
• 设备授权登录 - 通过 URL 快速登录并自动创建账号（5分钟超时）

负载与监控

• 随机负载均衡 - 从启用的账号中随机选择，均衡分配负载
• 健康检查 - 实时监控服务状态
• Web 控制台 - 美观的前端界面，支持账号管理和 Chat 测试

网络与安全

• HTTP 代理支持 - 可配置代理服务器，支持所有 HTTP 请求
• API Key 白名单 - 可选的访问控制，支持开发模式
• 持久化存储 - 支持 SQLite（默认）、PostgreSQL、MySQL 数据库

🚀 部署

方式一：Docker Compose

# 1. 复制环境变量配置
cp .env.example .env

# 2. 编辑 .env 文件（可选）
# 配置 OPENAI_KEYS、MAX_ERROR_COUNT 等

# 3. 启动服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f

# 5. 停止服务
docker-compose down

服务访问地址：

• 🏠 Web 控制台：http://localhost:8000/
• 💚 健康检查：http://localhost:8000/healthz
• 📘 API 文档：http://localhost:8000/docs

方式二：本地部署

1. 安装依赖

推荐使用 uv 进行环境管理和依赖安装。

# 安装 uv
pip install uv

# 创建虚拟环境并安装依赖
uv venv
uv pip install -r requirements.txt

2. 配置环境变量

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

# 根据需要编辑 .env 文件

.env 配置说明：

# 数据库连接URL（留空使用本地SQLite）
# PostgreSQL: DATABASE_URL="postgres://user:password@host:5432/dbname?sslmode=require"
# MySQL: DATABASE_URL="mysql://user:password@host:3306/dbname"
DATABASE_URL=""

# OpenAI 风格 API Key 白名单（仅用于授权，与账号无关）
# 多个用逗号分隔，例如：OPENAI_KEYS="key1,key2,key3"
# 留空则为开发模式，不校验 Authorization
OPENAI_KEYS=""

# Token 计数倍率（影响 /v1/messages/count_tokens 和 /v1/messages 的输入 token 统计）
# 默认值为 1.0，可根据实际需要调整（如设置为 1.5 表示返回 1.5 倍的 token 数）
TOKEN_COUNT_MULTIPLIER="1.0"

# 出错次数阈值，超过此值自动禁用账号
MAX_ERROR_COUNT=100

# HTTP代理设置（留空不使用代理）
# 例如：HTTP_PROXY="http://127.0.0.1:7890"
HTTP_PROXY=""

# 管理控制台开关（默认启用）
# 设置为 "false" 或 "0" 可禁用管理控制台和相关API端点
ENABLE_CONSOLE="true"

# 管理控制台登录密码（默认 "admin"）
# 用于访问管理控制台的密码，会话有效期为30天
ADMIN_PASSWORD="admin"

# 主服务端口（默认 8000）
PORT=8000

配置要点：

• OPENAI_KEYS 为空：开发模式，不校验 Authorization
• OPENAI_KEYS 设置后：仅白名单中的 key 可访问 API
• API Key 仅用于访问控制，不映射到特定账号
• 账号选择策略：从所有启用账号中随机选择
• ENABLE_CONSOLE 设为 false 或 0：禁用 Web 管理控制台和账号管理 API
• ADMIN_PASSWORD：管理控制台登录密码，默认为 "admin"，建议修改为强密码

3. 启动服务

# 启动服务 (带热重载)
uvicorn app:app --host 0.0.0.0 --port 8000 --reload

服务启动后，即可通过 http://localhost:8000 访问。该模式适用于开发，修改代码后服务会自动重启。

📖 使用指南

管理控制台登录

首次访问管理控制台需要登录：

1. 访问 http://localhost:8000/ 将自动跳转到登录页面
2. 输入管理员密码（默认为 admin，可通过 ADMIN_PASSWORD 环境变量配置）
3. 登录成功后，会话有效期为 30 天
4. 会话过期后需要重新登录

安全建议：

• 生产环境务必修改 ADMIN_PASSWORD 为强密码
• 登录凭证存储在浏览器 localStorage 中
• 所有管理 API 请求需要在 Authorization 头中携带会话 token

账号管理

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

登录管理控制台后，使用可视化界面：

• 查看所有账号及详细状态
• URL 登录（设备授权）快速添加账号
• 创建/删除/编辑账号
• 启用/禁用账号切换
• 手动刷新 Token
• Chat 功能测试

方式二：URL 登录（最简单）

快速添加账号的推荐方式：

1. 启动登录流程

   curl -X POST http://localhost:8000/v2/auth/start \
   -H "Content-Type: application/json" \
   -d '{"label": "我的账号", "enabled": true}'
   

2. 在浏览器中打开返回的 verificationUriComplete 完成登录

3. 等待并创建账号（最多5分钟）

   curl -X POST http://localhost:8000/v2/auth/claim/{authId}
   

成功后自动创建并启用账号，立即可用。

方式三：REST API 手动管理

注意： 所有管理 API 请求需要携带登录凭证（Authorization Bearer Token）

先登录获取 Token

# 登录并获取 token
TOKEN=$(curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{"password": "admin"}' \
  | jq -r '.token')

创建账号

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

列出所有账号

curl http://localhost:8000/v2/accounts \
  -H "Authorization: Bearer $TOKEN"

更新账号

curl -X PATCH http://localhost:8000/v2/accounts/{account_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"enabled": false}'

刷新 Token

curl -X POST http://localhost:8000/v2/accounts/{account_id}/refresh \
  -H "Authorization: Bearer $TOKEN"

删除账号

curl -X DELETE http://localhost:8000/v2/accounts/{account_id} \
  -H "Authorization: Bearer $TOKEN"

OpenAI 兼容 API

非流式请求

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）

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 示例

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)

Claude Messages API

本项目完整支持 Claude Messages API 格式，包括流式响应、工具调用、多模态内容等。

基础文本对话

curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "model": "claude-sonnet-4.5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

Python SDK 示例

from anthropic import Anthropic

client = Anthropic(
    base_url="http://localhost:8000/v1",
    api_key="your-api-key"
)

# 基础对话
message = client.messages.create(
    model="claude-sonnet-4.5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你好"}
    ]
)
print(message.content[0].text)

# 流式响应
with client.messages.stream(
    model="claude-sonnet-4.5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "写一首诗"}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

🔐 授权与账号选择

授权机制

• 开发模式（OPENAI_KEYS 未设置）：不校验 Authorization
• 生产模式（OPENAI_KEYS 已设置）：必须提供白名单中的 key

账号选择策略

• 默认策略：从所有 enabled=1 的账号中随机选择
• Lazy 号池策略：启用后，从排序后的前 N 个账号中随机选择，提高性能和账号利用率
• API Key 不映射到特定账号（与 AWS 账号解耦）
• 无可用账号时返回 401

Token 自动刷新

• 后台刷新：每5分钟检查一次，超过25分钟未刷新的令牌自动刷新
• 请求时刷新：若账号缺少 accessToken，自动刷新后重试
• 手动刷新：支持通过 API 或 Web 控制台手动刷新

🏗️ 架构设计

核心模块

• app.py - FastAPI 主应用，RESTful API 端点定义
• replicate.py - Amazon Q 请求复刻
• auth_flow.py - 设备授权登录
• claude_types.py - Claude API 类型定义
• claude_converter.py - Claude 到 Amazon Q 转换
• claude_parser.py - Event Stream 解析
• claude_stream.py - Claude SSE 流式处理

📁 项目结构

v2/
├── app.py                          # FastAPI 主应用
├── db.py                           # 数据库抽象层 (SQLite/PG/MySQL)
├── replicate.py                    # Amazon Q 请求复刻
├── auth_flow.py                    # 设备授权登录
├── claude_types.py                 # Claude API 类型定义
├── claude_converter.py             # Claude 到 Amazon Q 转换
├── claude_parser.py                # Event Stream 解析
├── claude_stream.py                # Claude SSE 流式处理
├── requirements.txt                # Python 依赖
├── .env.example                    # 环境变量示例
├── .env                            # 环境变量配置（需自行创建）
├── docker-compose.yml              # Docker Compose 配置
├── Dockerfile                      # Docker 镜像配置
├── data.sqlite3                    # SQLite 数据库（自动创建）
├── templates/
│   └── streaming_request.json      # Amazon Q 请求模板
├── frontend/
│   └── index.html                  # Web 控制台
└── scripts/
    ├── account_stats.py            # 账号统计脚本
    ├── retry_failed_accounts.py    # 重试失败账号脚本
    └── reset_accounts.py           # 重置账号脚本

🛠️ 技术栈

• 后端框架: FastAPI + Python 3.11+
• 数据库: SQLite3 (aiosqlite) / PostgreSQL (asyncpg) / MySQL (aiomysql)
• HTTP 客户端: httpx（支持异步和代理）
• Token 计数: tiktoken
• 前端: 纯 HTML/CSS/JavaScript（无依赖）
• 认证: AWS OIDC 设备授权流程

🔧 高级配置

环境变量

变量	说明	默认值	示例
DATABASE_URL	数据库连接URL	空（使用SQLite）	"postgres://user:pass@host:5432/db"
OPENAI_KEYS	API Key 白名单（逗号分隔）	空（开发模式）	"key1,key2"
TOKEN_COUNT_MULTIPLIER	Token 计数倍率	1.0	"1.5"
MAX_ERROR_COUNT	错误次数阈值	100	50
HTTP_PROXY	HTTP代理地址	空	"http://127.0.0.1:7890"
ENABLE_CONSOLE	管理控制台开关	"true"	"false"
ADMIN_PASSWORD	管理控制台登录密码	"admin"	"your-secure-password"
PORT	服务端口	8000	8080
DEBUG_MESSAGE_CONVERSION	消息转换调试日志	"false"	"true"
LAZY_ACCOUNT_POOL_ENABLED	是否启用 Lazy 号池	"false"	"true"
LAZY_ACCOUNT_POOL_SIZE	Lazy 号池大小（聊天）	20	50
LAZY_ACCOUNT_POOL_REFRESH_OFFSET	Lazy 号池刷新偏移量	10	20
LAZY_ACCOUNT_POOL_ORDER_BY	Lazy 号池排序字段	"created_at"	"success_count"
LAZY_ACCOUNT_POOL_ORDER_DESC	Lazy 号池是否降序	"false"	"true"

数据库结构

CREATE TABLE accounts (
    id TEXT PRIMARY KEY,                -- UUID
    label TEXT,                         -- 账号标签
    clientId TEXT,                      -- OIDC 客户端 ID
    clientSecret TEXT,                  -- OIDC 客户端密钥
    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     -- 成功请求次数
);

📝 完整 API 端点列表

管理员认证（需启用 ENABLE_CONSOLE）

• POST /api/login - 管理员登录，获取会话 token
• GET /login - 登录页面

账号管理（需启用 ENABLE_CONSOLE，需登录）

• POST /v2/accounts - 创建账号
• POST /v2/accounts/feed - 批量创建账号
• GET /v2/accounts - 列出所有账号
• GET /v2/accounts/{id} - 获取账号详情
• PATCH /v2/accounts/{id} - 更新账号
• DELETE /v2/accounts/{id} - 删除账号
• POST /v2/accounts/{id}/refresh - 刷新 Token

设备授权（需启用 ENABLE_CONSOLE，需登录）

• POST /v2/auth/start - 启动登录流程
• GET /v2/auth/status/{authId} - 查询登录状态
• POST /v2/auth/claim/{authId} - 等待并创建账号（最多5分钟）

OpenAI 兼容

• POST /v1/chat/completions - Chat Completions API

Claude 兼容

• POST /v1/messages - Messages API（支持流式、工具调用、多模态）
• POST /v1/messages/count_tokens - Token 计数接口（预先统计消息的 token 数量）

其他

• GET / - Web 控制台首页（需启用 ENABLE_CONSOLE，需登录）
• GET /healthz - 健康检查
• GET /docs - API 文档（Swagger UI）

🐛 故障排查

工具调用无限循环

现象： AI 重复调用相同的工具（如 git、bash 命令），无法停止

原因： 消息历史被错误合并，导致 AI 无法识别已执行的工具调用

解决方法：

1. 此问题已在最新版本中修复
2. 确保使用最新版本的代码
3. 如需调试，启用 DEBUG_MESSAGE_CONVERSION=true
4. 详见 修复文档

401 Unauthorized

可能原因：

• API Key 不在 OPENAI_KEYS 白名单中
• 没有启用的账号（enabled=1）

解决方法：

1. 检查 .env 中的 OPENAI_KEYS 配置
2. 访问 /v2/accounts 确认至少有一个启用的账号

Token 刷新失败

可能原因：

• refreshToken 已过期
• 网络连接问题

解决方法：

1. 查看账号的 last_refresh_status 字段
2. 检查网络连接和代理配置
3. 删除旧账号，通过 URL 登录重新添加

🚀 生产环境部署

Uvicorn 多进程模式

# 使用多个 worker 提高并发性能
python -m uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4

Nginx 反向代理

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # SSE 支持
        proxy_buffering off;
        proxy_cache off;
    }
}

🔒 安全建议

1. 生产环境必须修改 ADMIN_PASSWORD 为强密码
2. 生产环境必须配置 OPENAI_KEYS
3. 使用 HTTPS 反向代理（Nginx + Let's Encrypt）
4. 定期备份数据库（SQLite: data.sqlite3，或 PG/MySQL 数据库）
5. 限制数据库访问权限
6. 配置防火墙规则，限制访问来源
7. 管理控制台会话有效期为 30 天，建议定期重新登录

📄 许可证

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

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🙏 致谢

• amq2api - Claude 消息格式转换参考
• FastAPI - 现代 Python Web 框架
• Amazon Q Developer - 底层 AI 服务