# gptde-2api

**Repository Path**: Chinese-tingfeng/gptde-2api

## Basic Information

- **Project Name**: gptde-2api
- **Description**: 自备 Cookie/凭证 (BYO Credentials) 、 轻量级请求模拟 (No Headless Browser) 、 原生流式 API 转换 (Native Streaming API) 、 Docker 一键部署 (One-Click Docker Deployment)
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gptde-2api 🚀 - 创世纪 v1.1

![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
![Docker Ready](https://img.shields.io/badge/docker-ready-brightgreen.svg)
![Architecture Standard](https://img.shields.io/badge/architecture-lzA6--2api--standard-orange.svg)

> **Repository**: https://github.com/lzA6/gptde-2api
>
> **本期网站：**
https://gptde.de/

---

## 📜 技术宣言：打破技术壁垒，实现AI平权

在这个AI技术飞速发展的时代，我们常常惊叹于技术的强大，却也被各种"访问壁垒"所限制。我们坚信，前沿技术应该像阳光和空气一样普惠大众。`gptde-2api` 正是这一信念的实践。

这不仅仅是一个代码项目，更是一次**技术平权**的尝试。我们的使命是将 `gptde.de` 网站强大的免费AI对话能力，从封闭的网页中解放出来，封装成开放、标准、高性能的API。

通过这个项目，我们希望学生、独立开发者和小团队都能**零成本、无障碍**地接入先进AI模型。这就是 `lzA6` 开源系列 `*-2api` 的核心哲学：**赋能、开放、简化**。

---

## 🗺️ 项目架构：理解系统的内在秩序

### 🌳 项目文件结构

```
gptde-2api/
├── .env                    # 🔑 敏感配置（切勿上传到GitHub！）
├── .env.example            # 📝 配置文件模板
├── Dockerfile              # 📦 Docker镜像构建配置
├── docker-compose.yml      # 🐳 服务编排配置
├── main.py                 # 🚀 FastAPI应用入口
├── nginx.conf              # 🚦 Nginx反向代理配置
├── README.md               # 📖 项目文档
└── app/
    ├── core/
    │   ├── __init__.py
    │   └── config.py       # ⚙️ 配置管理模块
    └── providers/
        ├── __init__.py
        ├── base_provider.py    # 🏛️ Provider抽象基类
        └── gptde_provider.py   # 🤖 gptde.de服务核心逻辑
```

### 🌐 系统架构与数据流转

以下是请求从发送到响应的完整流程：

```mermaid
sequenceDiagram
    participant C as 客户端应用
    participant N as Nginx代理
    participant F as FastAPI服务
    participant G as GptdeProvider
    participant R as gptde.de服务器

    C->>N: 发送OpenAI格式请求
    Note over N: 根据IP哈希进行<br/>会话粘滞
    N->>F: 转发请求
    F->>F: API密钥验证
    F->>G: 调用Provider处理
    G->>R: 携带Cookie发送请求
    R-->>G: 流式返回响应数据
    G-->>F: 转换数据格式
    F-->>N: 流式传输
    N-->>C: 实时显示响应内容
```

---

## 🔬 技术深度解析

### ✅ 已完成功能

- **API转换核心**: 将 `gptde.de` 网页聊天转换为兼容OpenAI `v1/chat/completions` 格式的API
- **流式响应**: 端到端异步流式处理，提供流畅的打字机体验
- **凭证管理**: 通过 `.env` 文件管理认证信息
- **一键部署**: 基于Docker和Nginx的生产级部署方案
- **安全加固**: 通过 `API_MASTER_KEY` 和反向代理提供基础安全保障

### 🧩 核心技术组件分析

| 技术组件 | 功能说明 | 技术细节 | 优化方向 |
|---------|----------|----------|----------|
| **FastAPI** | 高性能Python API框架 | 使用 `lifespan` 管理应用生命周期，`Depends` 处理依赖注入 | 可集成GraphQL提供更灵活查询 |
| **httpx.AsyncClient** | 异步HTTP客户端 | `client.stream()` 实现流式请求，`async for` 处理数据流 | 增加重试逻辑和熔断机制 |
| **Nginx ip_hash** | 负载均衡会话保持 | 基于IP地址的会话粘滞，确保用户请求路由到同一后端 | 在K8s环境中可使用Cookie-based会话 |
| **Pydantic-Settings** | 配置管理 | 自动从 `.env` 加载配置并进行类型验证 | 集成HashiCorp Vault管理密钥 |

### ⚖️ 项目优劣势分析

#### 👍 优势

1. **极致便利性** 💯: 无需逆向工程知识，一次配置即可获得免费GPT-4o-mini API服务
2. **生态兼容性** 🌍: 完全兼容OpenAI API标准，支持所有主流客户端
3. **生产就绪** 🚢: Docker-Compose一键部署，资源占用低，稳定性高
4. **高性能** ⚡: 全异步架构，支持高并发流式响应
5. **隐私安全** 🔐: 数据经过自有服务器，完全掌控API使用权

#### 👎 劣势

1. **上游依赖** 🔗: 服务稳定性依赖 `gptde.de` 的可用性和策略变化
2. **手动凭证更新** 🔄: Cookie会过期，需要手动更新配置
3. **法律风险** ⚖️: 属于"灰色地带"项目，请仅用于个人学习和非商业用途

---

## 🧑‍🏫 完整部署教程

### 第一步：环境准备

1. 确保系统已安装 [Docker Desktop](https://www.docker.com/get-started)
2. 克隆项目代码：
```bash
git clone https://github.com/lzA6/gptde-2api.git
cd gptde-2api
```

### 第二步：获取认证凭证

1. **打开目标网站**: 访问 `https://gptde.de/?via=topaitools`
2. **开启开发者工具**: 按 `F12` → 选择 **Network** 标签
3. **发起测试对话**: 在聊天框输入任意内容并发送
4. **提取关键信息**:
   - **Cookie**: 在 `admin-ajax.php` 请求的 Headers 中找到 `cookie` 字段
   - **Nonce**: 在 Payload 中找到 `_wpnonce` 字段
   - **Client ID**: 在 Payload 中找到 `wpaicg_chat_client_id` 字段

### 第三步：配置环境变量

1. 复制配置文件模板：
```bash
cp .env.example .env
```

2. 编辑 `.env` 文件，填入获取的凭证：
```env
API_MASTER_KEY=your_secret_key_here
COOKIE=your_cookie_here
NONCE=your_nonce_here
CLIENT_ID=your_client_id_here
NGINX_PORT=8089
```

### 第四步：启动服务

```bash
docker-compose up --build -d
```

### 第五步：验证服务

服务启动后，可通过以下配置连接：

- **API Base URL**: `http://localhost:8089`
- **API Key**: 在 `.env` 中设置的 `API_MASTER_KEY`
- **Model**: `gpt-4o-mini-2024-07-18`

---

## 🔭 未来发展蓝图

### 🎯 当前痛点与改进方向

1. **凭证自动续期** ⭐⭐⭐⭐⭐
   - 目标：实现"一次配置，永久运行"
   - 方案：集成 Playwright/Selenium 实现自动化登录和凭证刷新

2. **状态监控面板** ⭐⭐⭐⭐
   - 目标：提供可视化服务监控
   - 方案：使用 Streamlit 或 FastUI 构建管理仪表盘

3. **多账户负载均衡** ⭐⭐⭐⭐
   - 目标：提升并发能力和服务稳定性
   - 方案：实现智能凭证轮询和失败自动隔离

### 🚀 长期规划

- **智能Worker管理**: 基于失败率的动态凭证回收机制
- **动态模型发现**: 自动探测上游支持的模型列表
- **插件化架构**: 支持其他网站的Provider插件开发

---

## 💌 社区贡献指南

我们欢迎所有形式的贡献！无论你是：

- 🐛 提交Bug报告
- 💡 提出新功能建议
- 🔧 提交代码改进
- 📖 完善项目文档

**参与方式**:
1. 在 [Issues](https://github.com/lzA6/gptde-2api/issues) 提出问题或建议
2. [Fork](https://github.com/lzA6/gptde-2api/fork) 项目并提交 Pull Request
3. 为项目点亮 ⭐ Star 支持我们

---

## ⚖️ 许可证与免责声明

### 许可证
本项目基于 **Apache License 2.0** 开源协议发布。

**允许**:
- ✅ 商业和非商业使用
- ✅ 修改和分发
- ✅ 专利授权

**要求**:
- ⚠️ 保留原始版权声明
- ⚠️ 声明代码修改

**免责声明**:
> 本项目仅供学习和研究使用，请勿用于商业用途。使用者需自行承担因使用本项目而产生的所有风险和责任。我们不对上游服务的稳定性和可用性提供任何保证。

---

**如果这个项目对你有帮助，请给我们一个 ⭐ 支持！**