✨ easemate-2api ✨

将 easemate.ai 转换为兼容 OpenAI 格式 API 的高性能、无头稳定版代理

---

🌌 "我们站在巨人的肩膀上，不是为了复制他们的身高，而是为了看得更远。开源，就是为下一个眺望者，搭建更高的阶梯。"

欢迎来到 easemate-2api 的世界！这不仅仅是一个代码仓库，更是一个关于"连接"、"模拟"与"创造"的实验。我们相信技术的魅力在于打破壁垒，将强大的能力以更简单、更通用的方式赋予每一个人。

🎯 项目概述

简单来说，easemate-2api 实现了一个非常"酷"的功能：

它像一个不知疲倦的数字员工，7x24小时 在后台为你打开浏览器，登录并操作 easemate.ai 网站。然后，它巧妙地将网站上的聊天操作，转换成一个标准的、开发者们都非常熟悉的 OpenAI API 格式。

这意味着什么？ 🤔

这意味着，任何支持 OpenAI API 的应用程序、软件或代码，现在都可以无缝对接 easemate.ai 提供的多种强大模型（如 Llama 3.1, Claude 3 Haiku, GPT-4o-mini 等），而无需对你现有的工具做任何修改！

这就像给你的所有 AI 工具装上了一个"万能转换插头"，让它们瞬间拥有了接入新世界的能力。

---

💖 核心价值

方面	优点 ✨	注意事项 ⚠️
便利性	一键接入，即插即用。无需研究 easemate.ai 的私有接口，直接使用你最熟悉的 OpenAI 客户端。	需要运行一个后台服务，相比直接调用云端 API，多了一层维护成本。
成本效益	充分利用 easemate.ai 可能提供的免费或低成本模型访问额度，极大降低 AI 应用开发和测试成本。	依赖于 easemate.ai 的前端策略，如果网站进行重大改版，项目可能需要更新。
模型多样性	让你现有的工具瞬间解锁 easemate.ai 支持的多种前沿模型，轻松切换，对比测试。	无法保证 100% 的稳定性。由于是模拟浏览器操作，网络波动或目标网站的临时不可用都可能影响服务。
学习与探索	这是一个绝佳的学习案例，涵盖了浏览器自动化、网络请求拦截、反向代理、API 格式转换等多种有趣技术。	项目的"模拟"本质决定了它是一个"非官方"解决方案，存在被目标网站反制措施影响的风险。

---

🏗️ 项目架构

系统架构图

graph TB
    subgraph "客户端应用"
        A[你的应用] --> B[OpenAI 客户端]
    end

    subgraph "easemate-2api 服务"
        B --> C[Nginx 反向代理]
        C --> D[FastAPI 应用]
        D --> E[EaseMateProvider]
        
        E --> F[Playwright<br>浏览器自动化]
        E --> G[curl_cffi<br>请求伪装]
        E --> H[asyncio.Queue<br>数据缓冲]
        
        F --> I[浏览器实例]
        G --> J[网络请求拦截]
        H --> K[流式数据转换]
    end

    subgraph "目标服务"
        J --> L[easemate.ai 网站]
        I --> L
    end

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style D fill:#e8f5e8
    style E fill:#fff3e0
    style F fill:#ffebee
    style G fill:#fce4ec

Loading

文件结构

📂 easemate-2api/
├── .dockerignore         # Docker 构建忽略文件
├── .env                  # 环境配置文件（需从模板创建）
├── .env.example          # 环境配置模板
├── Dockerfile            # Docker 镜像构建定义
├── docker-compose.yml    # 服务编排配置
├── main.py               # FastAPI 应用入口
├── nginx.conf            # Nginx 反向代理配置
├── requirements.txt      # Python 依赖列表
└── 📂 app/
    ├── 📂 core/
    │   ├── __init__.py
    │   └── config.py     # 配置管理
    ├── 📂 providers/
    │   ├── __init__.py
    │   ├── base_provider.py    # Provider 基类
    │   └── easemate_provider.py # EaseMate 核心实现
    └── 📂 utils/
        └── sse_utils.py  # SSE 流式数据处理

---

🧠 技术原理深度解析

1. 整体架构流程

[你的应用]
    ↓ (OpenAI API 请求)
[Nginx 反向代理]
    ↓ (路由到 FastAPI)
[FastAPI 应用 (main.py)]
    ↓ (调用 Provider)
[EaseMateProvider]
    ├── [Playwright] → 模拟浏览器操作
    ├── [curl_cffi] → 伪装并转发请求  
    └── [asyncio.Queue] → 缓冲流式数据
        ↓
[easemate.ai 网站]

2. 核心技术实现

a. Playwright：持久化浏览器会话 🎭

• 技术原理：使用 launch_persistent_context 创建带持久化数据的浏览器上下文
• 核心优势：登录一次后，Cookie、缓存等信息保存在 browser_data 文件夹，避免重复登录
• 代码位置：app/providers/easemate_provider.py → initialize_browser 方法

b. 请求拦截与伪装：curl_cffi 的魔法 🕵️

• 关键技术：page.route() 拦截 + curl_cffi 重放请求
• 解决痛点：绕过 TLS/JA3 指纹检测
  • JA3 指纹：每个浏览器在 HTTPS 握手时有独特的"指纹"
  • curl_cffi 能完美模拟 Chrome 浏览器的指纹特征
• 代码位置：app/providers/easemate_provider.py → handle_route 函数

c. FastAPI Lifespan：优雅的生命周期管理 🎶

• 技术特性：使用 @asynccontextmanager 管理应用生命周期
• 工作流程：
  • 启动时：全局初始化浏览器实例
  • 运行时：复用浏览器实例处理请求
  • 关闭时：优雅释放资源
• 代码位置：main.py → lifespan 函数

d. Docker & Nginx：容器化部署 🏰

• Docker：解决环境依赖问题，确保一致性
• Nginx：反向代理 + 负载均衡 + 流式传输优化

---

🚀 快速开始

环境要求

• Docker & Docker Compose
• 至少 2GB 可用内存

部署步骤

第 1 步：获取项目

git clone https://github.com/lzA6/easemate-2api.git
cd easemate-2api

第 2 步：配置环境

cp .env.example .env

编辑 .env 文件：

# API 主密钥，请修改为复杂密码！
API_MASTER_KEY=sk-your-super-secret-key-here

# 设备 UUID，通常保持默认即可
EASEMATE_DEVICE_UUID=eb0f5222701cbd6e67799c0cb99ec32b

# 外部访问端口（在 docker-compose.yml 中配置）
# NGINX_PORT=8089

安全提示：在生产环境中务必设置复杂的 API_MASTER_KEY！

第 3 步：启动服务

docker-compose up --build -d

查看启动日志：

docker-compose logs -f

当看到 浏览器初始化完成，应用准备就绪。 时表示启动成功。

使用示例

测试 API

curl -X POST http://localhost:8089/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-super-secret-key-here" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user", 
        "content": "用 Python 写一个 Hello World 程序"
      }
    ],
    "stream": true
  }'

获取支持的模型列表

curl http://localhost:8089/v1/models \
  -H "Authorization: Bearer sk-your-super-secret-key-here"

集成到现有项目

Python 示例

import openai

client = openai.OpenAI(
    base_url="http://localhost:8089/v1",
    api_key="sk-your-super-secret-key-here"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好，请介绍一下你自己"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

JavaScript 示例

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8089/v1',
  apiKey: 'sk-your-super-secret-key-here',
});

const stream = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

---

🔭 未来规划

短期目标 🎯

• 智能会话管理：自动检测会话过期并重新登录
• 增强错误处理：提供更友好的错误信息和重试机制
• 性能优化：实现浏览器上下文池，提高并发处理能力

长期愿景 🌌

• 多平台支持：抽象 Provider 接口，支持更多 AI 平台
• 动态模型发现：自动扫描并更新可用模型列表
• Web 管理界面：提供可视化服务状态监控和管理功能

贡献指南 🤝

我们欢迎各种形式的贡献！无论是提交 Issue、修复 Bug、增加新功能，还是优化文档，都是对社区的宝贵支持。

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/AmazingFeature
3. 提交更改：git commit -m 'Add some AmazingFeature'
4. 推送分支：git push origin feature/AmazingFeature
5. 提交 Pull Request

---

📜 开源协议

本项目采用 Apache 2.0 开源协议。你可以自由地使用、修改和分发代码，无论是个人项目还是商业产品，只需遵守协议中的相关条款。

---

Made with ❤️ and a lot of ☕ by the open-source community.