# how2solutions-2api

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

## Basic Information

- **Project Name**: how2solutions-2api
- **Description**: 轻量级 API 模拟 (非浏览器)、Nonce 一次性配置、原生 API 转 OpenAI 格式、伪流式输出、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-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🌉 how2solutions-2api: 您的私人 how2solutions.com to OpenAI 协议转换桥梁 🚀

![License](https://img.shields.io/github/license/lzA6/how2solutions-2api)
![Python Version](https://img.shields.io/badge/Python-3.10+-brightgreen.svg)
![Docker Support](https://img.shields.io/badge/Docker-Ready-blue.svg?logo=docker)
![GitHub Stars](https://img.shields.io/github/stars/lzA6/how2solutions-2api?style=social)

**一个将 `how2solutions.com` 的原生问答功能，巧妙伪装成 OpenAI 标准 API 格式的开源项目，让您心爱的应用无缝接入其知识库！**

</div>

---

## 📜 项目宣言

> "一个工具的最高境界，是让你忘记它的存在，只专注于你想要的结果。"

我们是否曾被无尽的`抓包`、`分析请求`、`模拟浏览器`所困扰？我们是否曾为`Cookie`的过期、`Nonce`的失效而感到沮丧？我们是否曾梦想，能有一个"一次配置，长期运行"的解决方案？

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

`how2solutions-2api` 不再是一个被动的中转工具。它是一个**稳定、高效、配置简单**的服务。它是一个数字世界的"翻译官"，默默地为你处理所有协议转换的细节，让你能专注于创造本身。

**我们的核心哲学**：**"专注核心，保持轻量"**。你只需进行一次简单的配置，它就会像一个忠诚的伙伴，在后台为你提供稳定可靠的服务。

---

## ✨ 核心特性

-   **🔄 一劳永逸的配置**: 仅需一次手动获取 `Nonce`，即可长期稳定运行
-   **🍃 极致轻量化**: 彻底告别资源消耗巨大的浏览器模拟，运行仅需极低资源
-   **⚡ 高并发与高性能**: 基于 FastAPI + Uvicorn 构建，闪电般的异步处理能力
-   **🎨 HTML 到 Markdown 实时转换**: 自动将 HTML 格式内容转换为排版精美的 Markdown
-   **⌨️ 伪流式输出**: 模拟"打字机"效果的流式输出，完美兼容 LobeChat、Cherry Studio 等客户端
-   **🛡️ 企业级安全**: 内置 `API_MASTER_KEY` 认证，保护你的 API 服务不被滥用
-   **🚀 一键部署**: 提供终极简化的 Docker Compose 配置

---

## 🗺️ 架构蓝图

### 项目文件结构

```
📂 how2solutions-2api/
├── 📄 .env                    # 私人配置文件
├── 📄 .env.example            # 环境变量模板
├── 📄 Dockerfile              # Docker 镜像构建配置
├── 📄 README.md               # 项目文档
├── 📄 docker-compose.yml      # 一键部署配置
├── 📄 main.py                 # FastAPI 应用主入口
├── 📄 nginx.conf              # Nginx 反向代理配置
├── 📄 requirements.txt        # Python 依赖列表
└── 📂 app/                    # 核心应用代码
    ├── 📂 core/               # 核心配置模块
    │   └── 📄 config.py       # 应用配置模型
    └── 📂 providers/          # 服务提供商模块
        ├── 📄 base_provider.py    # Provider 抽象基类
        └── 📄 how2solutions_provider.py  # 核心逻辑实现
```

### 系统架构图

```mermaid
flowchart TD
    A[👨‍💻 用户请求<br>LobeChat/Cherry Studio]
    B[🌐 Nginx 反向代理]
    C[🚀 FastAPI 应用]
    D[🧠 How2SolutionsProvider]
    E[☁️ how2solutions.com API]
    
    subgraph "您的 API 服务"
        B --> C
        C --> D
    end

    A --> B
    D -- "携带 Nonce 发起请求" --> E
    E -- "返回 HTML 格式数据" --> D
    D -- "HTML 转 Markdown" --> D
    D -- "模拟流式输出" --> C
    C --> B
    B --> A

    style A fill:#e1f5fe,stroke:#01579b
    style B fill:#f3e5f5,stroke:#4a148c
    style C fill:#e8f5e8,stroke:#1b5e20
    style D fill:#fff3e0,stroke:#e65100
    style E fill:#e0f2f1,stroke:#004d40
```

---

## 🔬 技术原理深度剖析

### 核心技术栈

-   **Python 3.10+**: 稳定高效的编程语言
-   **FastAPI**: 现代高性能 Web 框架
-   **Docker & Docker Compose**: 容器化部署方案
-   **Nginx**: 高性能反向代理
-   **Httpx**: 异步 HTTP 客户端
-   **Markdownify**: HTML 到 Markdown 转换
-   **BeautifulSoup4**: HTML 解析库

### 关键技术实现

#### 1. 固定认证与 URL 编码

**技术原理**:
- 采用模拟合法 API 请求的方式，替代复杂的浏览器模拟
- 使用 `urllib.parse.quote_plus` 处理中文字符编码
- 通过 `httpx.AsyncClient` 发送格式正确的 POST 请求

**实现效果**:
- 资源消耗降低 90% 以上
- 请求响应时间大幅缩短
- 系统稳定性显著提升

#### 2. HTML 到 Markdown 实时转换

**转换示例**:
```html
<!-- 输入 HTML -->
<h3>重要概念</h3>
<p>这是<strong>关键内容</strong>的解释</p>
<ul>
    <li>要点一</li>
    <li>要点二</li>
</ul>
```

```markdown
<!-- 输出 Markdown -->
### 重要概念
这是**关键内容**的解释
- 要点一
- 要点二
```

#### 3. 伪流式响应机制

**实现逻辑**:
```python
async def _pseudo_stream_generator(self, content: str):
    # 发送开始信号
    yield "data: {}\n\n".format(json.dumps({"choices": [{"delta": {"role": "assistant"}}]}))
    
    # 分块发送内容
    for i in range(0, len(content), 10):
        chunk = content[i:i+10]
        yield f"data: {json.dumps({'choices': [{'delta': {'content': chunk}}]})}\n\n"
        await asyncio.sleep(0.02)
    
    # 发送结束信号
    yield "data: [DONE]\n\n"
```

---

## 📊 项目现状与规划

### ✅ 已完成功能

-   **核心代理功能**: 稳定的协议转换服务
-   **生产级 API**: 兼容 OpenAI 的 `/v1/chat/completions` 和 `/v1/models` 端点
-   **卓越用户体验**: Markdown 转换 + 伪流式输出
-   **极简部署**: 零依赖 Docker 部署方案

### ⚖️ 项目优势与局限

#### 👍 优势
- **极简配置**: 一次设置，长期运行
- **资源友好**: 内存占用 < 100MB，CPU 使用率极低
- **完美兼容**: 支持所有主流 AI 客户端
- **输出优质**: 提供与官网一致的阅读体验

#### 👎 局限
- **手动更新**: Nonce 过期需要手动更新
- **上游依赖**: 依赖 how2solutions.com 的 API 结构稳定性

### 🚀 未来发展规划

#### 短期目标 (1-2个月)
1. **Nonce 自动续期** ★★★★☆
   - 轻量级 HTTP 客户端定期获取新 Nonce
   - 后台自动更新机制

2. **基础管理面板** ★★★☆☆
   - Web 界面更新 Nonce
   - 服务状态监控

#### 长期愿景 (3-6个月)
1. **多 Nonce 轮询** ★★★★☆
   - 支持 Nonce 池管理
   - 自动故障切换

2. **扩展性架构** ★★★★★
   - 插件化 Provider 系统
   - 支持更多知识库网站

---

## 🛠️ 快速开始指南

### 环境要求

- Docker & Docker Compose
- 或 Python 3.10+
- 有效的 how2solutions.com Nonce

### 一键部署方案

#### 方案一：Docker 部署 (推荐)

```bash
# 克隆项目
git clone https://github.com/lzA6/how2solutions-2api.git
cd how2solutions-2api

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入 HOW2SOLUTIONS_NONCE

# 启动服务
docker-compose up -d --build

# 查看日志
docker-compose logs -f
```

#### 方案二：Python 环境部署

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 启动服务
uvicorn main:app --host 0.0.0.0 --port 8000
```

### 获取 Nonce 教程

1. 打开浏览器开发者工具 (F12)
2. 访问 https://how2solutions.com
3. 在 Network 标签页中查找任意 API 请求
4. 在请求头中复制 `x-wp-nonce` 的值
5. 填入 `.env` 文件的 `HOW2SOLUTIONS_NONCE` 字段

### 客户端配置

**API 配置示例**:
```
API Base URL: http://localhost:8089
API Key: your_api_master_key
Model: how2solutions-ai
```

**cURL 测试命令**:
```bash
curl -X POST "http://localhost:8089/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_master_key" \
  -d '{
    "model": "how2solutions-ai",
    "messages": [
      {"role": "user", "content": "解释量子计算的基本原理"}
    ],
    "stream": true
  }'
```

---

## 🔧 故障排除

### 常见问题

**Q: 服务启动失败**
```
A: 检查 .env 文件格式，确保所有变量正确设置
```

**Q: API 返回认证错误**
```
A: Nonce 可能已过期，请重新获取并更新 .env 文件
```

**Q: 流式输出不工作**
```
A: 确保客户端请求中设置了 "stream": true
```

**Q: Docker 容器无法访问**
```
A: 检查防火墙设置和端口映射配置
```

### 日志查看

```bash
# Docker 环境
docker-compose logs -f

# 直接运行
tail -f uvicorn.log
```

---

## 🤝 贡献指南

我们欢迎所有形式的贡献！

### 如何贡献

1. **报告问题**
   - 在 Issues 中描述清晰的问题现象
   - 提供复现步骤和环境信息

2. **功能建议**
   - 详细描述功能需求和使用场景
   - 讨论技术实现方案

3. **代码贡献**
   - Fork 项目仓库
   - 创建功能分支
   - 提交 Pull Request

### 开发环境设置

```bash
git clone https://github.com/lzA6/how2solutions-2api.git
cd how2solutions-2api
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt  # 开发依赖
```

### 代码规范

- 遵循 PEP 8 编码规范
- 使用类型注解
- 添加适当的文档字符串
- 编写单元测试

---

## 📄 开源协议

本项目基于 **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 代理模式简化探索的实践。我们相信，通过深入分析和精准模拟，可以用最小的代价创造出稳定、高效且体验出色的解决方案。

如果您认同我们的理念，欢迎：

- ⭐ **给项目一个 Star** - 鼓励我们继续前行
- 💡 **提出建议** - 在 Issues 中分享您的想法
- 🔧 **贡献代码** - 共同完善这个项目
- 📢 **分享传播** - 让更多人受益

**相关链接**:
- [项目主页](https://github.com/lzA6/how2solutions-2api)
- [问题反馈](https://github.com/lzA6/how2solutions-2api/issues)
- [讨论区](https://github.com/lzA6/how2solutions-2api/discussions)

让我们一起构建更加优雅、智能的 API 服务解决方案！