# Writifyai-2api

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

## Basic Information

- **Project Name**: Writifyai-2api
- **Description**: 无头浏览器 (Headless Browser) · 无需 Cookie 自动持久化 · 匿名与反检测 · 自动绕过 Vercel/CF 人机验证 · 原生流式 API 转换 · Docker 一键部署
- **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-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WritifyAI-2API (v2.2) - 自主进化版 🚀

<p align="center">
  <strong>一份宣言 📜，一份蓝图 🗺️，一份深度报告 🔬，一份保姆级教程 🧑‍🏫。</strong>
</p>

<p align="center">
  <a href="https://github.com/lzA6/Writifyai-2api/stargazers"><img src="https://img.shields.io/github/stars/lzA6/Writifyai-2api?style=social" alt="GitHub Stars"></a>
  <a href="https://github.com/lzA6/Writifyai-2api/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lzA6/Writifyai-2api" alt="License"></a>
  <a href="https://hub.docker.com/r/lza6/writifyai-2api"><img src="https://img.shields.io/docker/pulls/lza6/writifyai-2api?label=docker%20pulls&logo=docker" alt="Docker Pulls"></a>
</p>

---

## 📜 一份宣言：告别手动，拥抱自主

> "一个工具的最高境界，是让你忘记它的存在。" —— lzA6 架构师的顿悟

我们是否曾被无尽的`抓包`、`复制Cookie`、`配置Token`所困扰？我们是否曾为服务的突然`失效`、凭证的无情`过期`而感到沮丧？我们是否曾梦想，能有一个"一劳永逸"的解决方案？

今天，这个梦想照进了现实。

`WritifyAI-2API` v2.2 不再是一个被动的中转工具。它是一个拥有"生命"的、**自主的**、**自愈的**服务。它是一个数字世界的"园丁"，默默地为你打理一切，让你能专注于创造本身。

**我们的核心哲学**：**"一次部署，永久运行"**。你启动它，然后忘记它。它会像一个忠诚的伙伴，在后台为你处理所有繁琐的细节。这不仅仅是代码，这是一种对"简单"和"优雅"的极致追求。我们相信，最好的技术，是让你感受不到技术。

---

## ✨ 核心特性 (Core Features)

-   **零配置启动 (Zero-Config Start)**: **无需手动抓包！无需配置 Cookie/Token！** 启动服务，然后去泡杯咖啡 ☕️，一切都会自动准备就绪。
-   **自主工作单元池 (Autonomous Worker Pool)**: 内置一个"数字劳工"团队（基于 Playwright 无头浏览器），它们会 24/7 模拟真实用户行为，动态创建并维护包含有效凭证的"工作单元"。
-   **高并发与负载均衡 (High Concurrency & Load Balancing)**: 自动创建并管理一个工作单元池（默认5个），像一个聪明的交通调度员，将请求智能分发到不同的匿名会话上，轻松应对流量高峰 🌊。
-   **自愈与容错 (Self-Healing & Fault Tolerance)**: 当某个会话凭证失效时，系统会像壁虎断尾一样，果断将其从池中移除，并立即"再生"一个新的健康会话进行补充，保证服务的持续可用性 💪。
-   **企业级安全 (Enterprise-Grade Security)**: 内置 `API_MASTER_KEY` 认证，像一个忠诚的守卫，保护你的 API 服务不被滥用。
-   **实时状态监控 (Real-time Status Monitoring)**: 提供 `/status` 端点，让你能像拥有"透视眼"一样，实时查看工作池状态、可用会话数和健康状况。
-   **一键部署 (One-Click Deployment)**: 提供终极简化的 Docker Compose 配置，真正实现"一次点击，服务启动"的魔法体验 ✨。

---

## 🗺️ 一份蓝图：架构与数据流

> "不理解架构的开发者，如同没有地图的探险家。"

为了让你能清晰地洞察本项目的内在逻辑，我们为你绘制了这份蓝图。

### 项目文件结构 (Project File Structure)

```
📂 Writifyai-2api/
├── 📄 .env.example         # 环境变量模板文件
├── 📄 .gitignore           # Git 忽略文件配置
├── 📄 Dockerfile           # Docker 镜像构建的"蓝图"
├── 📄 README.md            # 就是你正在阅读的这份史诗级文档
├── 📄 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 的抽象基类
        ├── 📄 worker_manager.py # "数字劳工"的管理者
        └── 📄 writifyai_provider.py # 对接 Writify.ai 的核心逻辑
```

### 架构图 (Architecture Diagram)

```mermaid
flowchart TD
    A["👨‍💻 用户请求<br>OpenAI API 格式"]
    B{"🌐 Nginx<br>端口: ${NGINX_PORT}"}
    C["🚀 FastAPI 应用<br>main.py"]
    D["🧠 WritifyAIProvider<br>writifyai_provider.py"]
    E["🤖 WorkerManager<br>worker_manager.py"]
    F["☁️ 上游 Writify.ai API"]
    
    A --> B
    B --> C
    C --> D
    D -- "1. 请求可用Worker" --> E
    E -- "2. 提供健康Worker" --> D
    D -- "3. 使用Worker凭证<br>发起请求" --> F
    F -- "4. 返回响应数据" --> D
    D -- "5. 格式化响应<br>返回给用户" --> C
    C --> B
    B --> A

    subgraph "后台自主运行系统"
        G["🔄 池维护任务"] -- "监控池状态" --> E
        E -- "Worker数量不足" --> H["🏭 创建新Worker"]
        H -- "启动Playwright<br>无头浏览器" --> I["🌍 访问 writify.ai"]
        I -- "获取有效Cookie & Nonce" --> H
        H -- "Worker创建成功" --> E
        H -- "Worker创建失败" --> J["❌ 记录错误"]
    end

    style A fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style B fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style C fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    style D fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style E fill:#ffecb3,stroke:#ff6f00,stroke-width:2px
    style F fill:#e0f2f1,stroke:#004d40,stroke-width:2px
    style G fill:#fce4ec,stroke:#880e4f,stroke-width:2px
    style H fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style I fill:#e8eaf6,stroke:#283593,stroke-width:2px
    style J fill:#ffebee,stroke:#b71c1c,stroke-width:2px
```

---

## 🔬 一份深度报告：技术原理剖析

> "知其然，更要知其所以然。"

### 核心技术栈 (Core Tech Stack)

-   **Python 3.10**: 稳定、高效的编程语言。
-   **FastAPI**: 现代、高性能的 Python Web 框架，为速度而生。
-   **Playwright**: 微软出品的浏览器自动化库，是我们实现"自主进化"的魔法棒 🪄。
-   **Docker & Docker Compose**: 容器化技术，实现环境隔离和一键部署。
-   **Nginx**: 高性能反向代理服务器，负责负载均衡和流量分发。
-   **Httpx**: 现代、异步的 HTTP 客户端，用于与上游 API 高效通信。

### 关键技术点解释 (Key Tech Explained)

#### 1. Playwright 自主工作单元 (Autonomous Worker Unit)
-   **这是什么? (What is it?)**: 这是整个项目的灵魂。一个"工作单元"就是一个模拟的、拥有独立身份（Cookie + Nonce）的匿名用户会话。
-   **它是如何工作的? (How it works?)**:
    -   **`worker_manager.py`**: 这是"劳务派遣中心"。它在后台运行一个 `asyncio` 异步任务。
    -   **启动无头浏览器**: 它会启动一个看不见的 Chromium 浏览器。**大白话**：就像在服务器里开了一个隐身的 Chrome。
    -   **创建浏览器上下文**: `browser.new_context()`，这相当于在 Chrome 里开了一个"无痕模式"窗口，拥有自己独立的 Cookie 和缓存，与其他窗口完全隔离。
    -   **模拟访问与 API 调用**: 在这个"无痕窗口"里，它先访问网站首页 `https://writify.ai/tool/ai-chat/`，让网站服务器种下（Set-Cookie）必要的初始 Cookie。然后，它执行一段 JavaScript 代码 (`page.evaluate`)，调用 `/start_session` API，获取到 `restNonce`。
    -   **凭证提取与封装**: 它从这个"无痕窗口"里，把所有的 Cookie 和刚刚获取的 `restNonce` 打包，创建一个 `Worker` 对象。
    -   **入池待命**: 将这个新鲜出炉的 `Worker` 对象放入一个 `deque`（一个高效的队列）中，等待被调用。
-   **难度评级**: ★★★★★ (困难)
-   **搜索路径**: 这个方法的灵感来源于解决"动态 Token/Cookie 刷新"的通用问题。你可以通过搜索 `python playwright auto refresh cookie`、`fastapi background task playwright` 等关键词，在 Stack Overflow 和 Playwright 官方文档中找到类似的实现思路。

#### 2. 智能容错与自愈 (Intelligent Fault Tolerance)
-   **这是什么?**: 一种让服务在遇到问题时能"自己救自己"的机制。
-   **它是如何工作的?**:
    -   当 `WritifyAIProvider` 使用一个 `Worker` 发起请求，但上游返回了错误（比如 HTTP 5xx）或者网络超时，它会认为这个 `Worker` 的凭证可能"病了"。
    -   它会调用 `worker_manager.retire_worker()`，将这个"生病"的 `Worker` 从工作池中"开除"。
    -   后台的 `_maintain_pool` 任务会定期（每10秒）检查池子里的"工人数"，发现"员工"数量少于预设值（`WORKER_POOL_SIZE`），就会立即触发 `_create_worker` 流程，招聘"新员工"入池。
-   **大白话**: 就像一个餐厅，服务员（Worker）不小心打碎了盘子（请求失败），经理（Provider）会让他先去休息（retire），然后立马从门口等候的队伍里叫一个新的服务员进来补上（create），保证餐厅正常运转。

#### 3. 流式与非流式响应分离 (Stream/Non-Stream Separation)
-   **这是什么?**: 针对客户端请求的 `stream: true` 和 `stream: false` 两种模式，提供两种不同的、最优的处理逻辑。
-   **它是如何工作的?**:
    -   **`_stream_response_generator`**: 当 `stream: true` 时调用。它使用 `httpx.stream()`，像一根水管，持续地从上游接收数据块，并实时地转发给客户端，实现打字机效果。
    -   **`_non_stream_response`**: 当 `stream: false` 时调用。它也使用 `httpx.stream()`，但它会把所有数据块在内部拼接成一个完整的字符串 `full_content`，然后一次性返回一个完整的 JSON 对象。
-   **大白话**: 流式就像看直播，内容是源源不断地来的。非流式就像下载一部电影，你必须等它全部下载完才能看。我们为这两种场景分别优化了处理方式。

---

## 🧐 项目现状与未来展望

### 现阶段完成了什么？(What's Done?)

-   ✅ **核心自主架构**: 实现了基于 Playwright 的 Worker Pool，完成了凭证的自动获取和管理。
-   ✅ **生产级服务**: 提供了兼容 OpenAI 的 `/v1/chat/completions` 和 `/v1/models` 端点。
-   ✅ **高可用性**: 实现了 Worker 的失败回收和自动补充机制。
-   ✅ **易用性**: 实现了零配置启动和一键化 Docker 部署。

### 项目的优缺点 (Pros and Cons)

#### 👍 优点 (Pros)

-   **极致的便利性**: 用户无需任何抓包和配置，真正做到"开箱即用"。
-   **高稳定性与鲁棒性**: 动态凭证和自愈机制，让服务能抵抗上游的短期失效。
-   **高并发能力**: Worker Pool 设计，天然支持多用户同时请求。

#### 👎 缺点 (Cons)

-   **资源消耗**: 运行一个无头浏览器实例需要相对更多的 CPU 和内存（`shm_size: '1gb'`）。
-   **启动速度**: 首次构建和启动时，安装浏览器依赖会花费几分钟时间。
-   **上游依赖**: 强依赖 `writify.ai` 的前端和 API 结构，如果对方网站大改版，本项目需要同步更新。

### 未来要怎么发展？(Future Roadmap)

> "我们的征途是星辰大海。"

#### 待实现的技术路径 (To-Do List)

1.  **可视化管理面板 (★★★★☆)**
    -   **要做什么?**: 开发一个简单的 Web UI（可以用 Streamlit 或集成到 FastAPI），可以实时查看 Worker 池状态、请求日志、统计数据，甚至在线热更新配置（如 `WORKER_POOL_SIZE`）。
    -   **技术路径**:
        -   在 `main.py` 中增加新的 HTML 模板路由。
        -   通过 WebSocket 将 `worker_manager` 的状态实时推送到前端。
        -   前端使用简单的 JavaScript 或 htmx 来渲染数据。

2.  **更智能的 Worker 回收策略 (★★★☆☆)**
    -   **要做什么?**: 当前是"失败一次就开除"，可以优化为"连续失败 N 次"或"失败率超过 X%"再回收，避免因网络抖动误杀健康的 Worker。
    -   **技术路径**:
        -   在 `Worker` 类中增加一个时间戳列表，记录每次失败的时间。
        -   修改 `retire_worker` 方法，实现更复杂的判断逻辑。

3.  **支持多地域出口 IP (★★★★★)**
    -   **要做什么?**: 对于大规模部署，可以集成代理池，让每个 Playwright Worker 通过不同的代理 IP 访问上游，彻底避免因 IP 被限制的风险。
    -   **技术路径**:
        -   在 `config.py` 中增加代理配置。
        -   在 `_create_worker` 中，为 `browser.new_context()` 传入 `proxy` 参数。
        -   需要一个可靠的代理服务提供商。

---

## 🧑‍🏫 一份保姆级教程：让魔法发生

> "授人以鱼，不如授人以渔。但在这里，我们直接给你一座全自动的渔场。"

### 懒人一键部署 (For Impatient Geniuses)

我们为你准备了能在多种环境中一键部署的方案。

#### 1. 使用 Docker (推荐)

这是最简单、最可靠的方式，我们已经为你铺平了所有道路。

**准备工作**:
1.  安装  [Docker](https://www.docker.com/get-started) 和  [Docker Compose](https://docs.docker.com/compose/install/)。
2.  克隆本项目：
    ```bash
    git clone https://github.com/lzA6/Writifyai-2api.git
    cd Writifyai-2api
    ```

**部署步骤**:
1.  **创建 `.env` 文件**:
    将 `.env.example` 复制一份并重命名为 `.env`。你可以根据需要修改里面的 `API_MASTER_KEY` 和 `NGINX_PORT`。
    ```bash
    cp .env.example .env
    ```

2.  **启动服务**:
    ```bash
    docker-compose up -d --build
    ```
    第一次启动会像"天地初开"一样，需要一些时间来下载依赖和构建环境。请耐心等待，魔法正在酝酿...

3.  **验证服务**:
    启动后，服务将在你设置的 `NGINX_PORT`（默认为 `8088`）上可用。打开浏览器或使用 `curl` 访问状态端点：
    ```bash
    curl -H "Authorization: Bearer sk-writify-default-key" http://localhost:8088/status
    ```
    当你看到类似下面的输出，并且 `pool_size` 大于 0 时，恭喜你，你的自主 API 工厂已正式投产！
    ```json
    {
      "pool_size": 5,
      "target_pool_size": 5,
      "workers": [
        "<Worker nonce='5419ef2b...' failed=0>",
        "<Worker nonce='5419ef2b...' failed=0>",
        ...
      ],
      "total_created": 5,
      "total_failed_creations": 0
    }
    ```

#### 2. 一键部署到云端 (Render.com)

你可以使用 Render 平台免费部署此服务

**注意**: 在 Render 配置中，请确保将启动命令设置为 `uvicorn main:app --host 0.0.0.0 --port $PORT`。

### 如何使用 (How to Use)

API 端点与 OpenAI 完全兼容，你可以无缝对接到任何支持 OpenAI API 的客户端。

-   **API 地址**: `http://<你的服务器IP>:${NGINX_PORT}`
-   **API Key**: 你在 `.env` 中设置的 `API_MASTER_KEY`
-   **模型名称**: 在请求体中通过 `model` 参数指定。

**cURL 示例:**
```bash
curl -X POST http://localhost:8088/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-writify-default-key" \
-d '{
    "model": "chatbot-b7j5gh",
    "messages": [
        {"role": "user", "content": "你好，用一种充满哲学思辨的语气，告诉我这个项目是如何工作的。"}
    ],
    "stream": true
}'
```

---

## ⚖️ 一份协议书：开源许可

本项目基于 **Apache License 2.0** 许可。

这意味着你可以自由地使用、修改和分发这个项目，无论是个人用途还是商业用途，只需遵守许可协议的条款即可。我们相信，开放和共享是推动技术进步的最佳方式。

```
Copyright 2025 lzA6

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

---

## ✨ 一份邀请函：成为"创世纪"的一员

> "独行者速，众行者远。"

这不仅仅是一个项目，更是一次对传统 API 代理模式的颠覆性探索。它证明了通过巧妙的架构设计，我们可以创造出更智能、更省心的工具。

如果你对自主系统、Web 自动化、高性能架构充满热情，如果你也认同我们的哲学，我们诚挚地邀请你：

-   ⭐ **给这个项目一个 Star！** 这是对我们工作最大的肯定。
-   💡 在 Issues [[4]](https://github.com/lzA6/Writifyai-2api/issues) 中**提出你的想法和建议**，哪怕只是一个疯狂的念头。
-   💪 **贡献你的代码**，无论是修复一个 bug，还是实现一个未来展望中的新功能，你都将成为这段史诗的一部分。

让我们一起，构建真正智能、无需操心的下一代 API 服务，将开源的精神传递下去！

---

## 🔗 参考资料 (References)

[1] [Docker 安装指南](https://www.docker.com/get-started)  
[2] [Docker Compose 安装指南](https://docs.docker.com/compose/install/)  
[3] [Render 部署按钮](https://render.com/images/deploy-to-render-button.svg)  
[4] [项目 Issues 页面](https://github.com/lzA6/Writifyai-2api/issues)

---

**WritifyAI-2API** - 让技术为你工作，而不是你为技术工作。🚀