Skip to content

implementation.md

Latest commit

 

History

History
231 lines (186 loc) · 6.61 KB

implementation.md

File metadata and controls

231 lines (186 loc) · 6.61 KB

技术实现详解

🔧 架构设计

整体架构

前端应用 → nginx (80) → Node Proxy (3001) → 外部LLM API

设计理念

基于Docker受信环境假设，采用简化优先的设计原则：

  • 重点关注功能实现而非复杂安全防护
  • 避免nginx动态代理的复杂性
  • 零依赖实现，提高可维护性

架构优势

  • ✅ 避免nginx动态代理的DNS解析问题
  • ✅ 配置简单，易于维护
  • ✅ 适合Docker容器的受信环境
  • ✅ 职责清晰：nginx负责转发，Node.js负责代理逻辑

🐛 问题诊断与解决

核心技术挑战

1. nginx动态代理复杂性

问题：nginx动态代理需要复杂的DNS解析和变量处理 解决方案：采用nginx本地转发 + Node.js代理的简化架构

location /api/proxy {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
}

2. 流式响应透传

问题：SSE流式响应需要实时透传，不能缓冲 解决方案：

  • nginx配置：proxy_buffering off、X-Accel-Buffering no
  • Node.js实现：使用Readable.fromWeb()正确处理流

3. CORS头重复设置

问题：nginx和Node.js同时设置CORS头导致重复 解决方案：统一由Node.js处理CORS，nginx不设置

4. 超时策略优化

问题：LLM流式请求可能需要很长时间，统一超时不合理 解决方案：差异化超时策略

  • 流式请求：5分钟超时
  • 普通请求：2分钟超时
  • 支持环境变量配置

📝 实施步骤

阶段1：基础代理功能实现

  1. 创建Node.js代理服务

    • 零依赖实现，只使用内置模块
    • 支持所有HTTP方法
    • 基础错误处理

  2. 配置nginx转发

    • 添加/api/proxy和/api/stream路径
    • 本地转发到127.0.0.1:3001
    • 基础CORS配置

  3. Docker集成

    • 修改supervisord.conf添加node-proxy进程
    • 环境变量配置支持

阶段2：流式代理和UI集成

  1. 流式响应优化

    • nginx流式配置优化
    • Node.js使用Readable.fromWeb()处理流
    • 流式超时策略

  2. 前端UI集成

    • 环境检测逻辑
    • ModelManager.vue添加Docker代理选项
    • 国际化文本支持

  3. 数据持久化

    • ModelConfig接口添加useDockerProxy
    • 配置保存和加载逻辑

阶段3：错误处理与体验优化

  1. 增强错误处理

    • 智能错误分类：超时504、连接错误502、格式错误400
    • 用户友好错误消息
    • 请求追踪系统

  2. LLM服务集成

    • OpenAI服务添加Docker代理支持
    • Gemini服务添加Docker代理支持
    • 类型定义完善

  3. 端到端验证

    • 功能测试：基础代理、错误处理、流式响应
    • 性能测试：响应时间、内存使用、并发处理
    • 集成测试：前端UI、LLM服务、构建系统

🔍 调试过程

调试工具组合

  • Nginx access_log：记录/api/*专用日志
  • Node Proxy日志：详细的请求处理日志
  • 浏览器网络面板：前端请求状态检查

关键调试点

  1. CORS问题：确保只有Node.js设置CORS头
  2. 流式响应：检查nginx缓冲配置和Node.js流处理
  3. 超时处理：验证不同类型请求的超时策略
  4. 错误分类：确保错误码和消息的正确性

🧪 测试验证

功能测试用例

// 基础代理测试
GET /api/proxy?url=https://httpbin.org/get
期望：200状态码，正确的JSON响应

// 错误处理测试
GET /api/proxy?url=https://nonexistent-domain.com
期望：502状态码，友好错误消息

// 流式响应测试
GET /api/stream?url=https://httpbin.org/stream/5
期望：实时流式数据，无缓冲延迟

性能测试指标

  • 响应时间：6-7秒（httpbin.org正常延迟）
  • 内存使用：稳定，无内存泄漏
  • 并发处理：支持多个同时请求
  • 资源清理：定时器正确清理

集成测试验证

  • 前端UI：代理选项正确显示和保存
  • LLM服务：Docker代理配置正确传递
  • 构建系统：Core和UI包构建成功
  • 类型检查：TypeScript检查通过

🔧 核心代码实现

Node.js代理服务核心逻辑

// 零依赖实现，只使用内置模块
const http = require('http');
const { Readable } = require('stream');

// 流式响应处理
if (upstreamRes.headers['content-type']?.includes('text/event-stream')) {
    const stream = Readable.fromWeb(upstreamRes.body);
    stream.pipe(res);
}

// 智能错误处理
const handleError = (error, res, requestId) => {
    if (error.code === 'ENOTFOUND') {
        return sendError(res, 502, 'DNS resolution failed', requestId);
    }
    if (error.code === 'ECONNREFUSED') {
        return sendError(res, 502, 'Connection refused', requestId);
    }
    return sendError(res, 500, 'Internal server error', requestId);
};

nginx配置核心部分

# 基础代理配置
location /api/proxy {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
}

# 流式响应配置
location /api/stream {
    proxy_pass http://127.0.0.1:3001;
    proxy_buffering off;
    proxy_request_buffering off;
    add_header X-Accel-Buffering no always;
}

前端环境检测

export const checkDockerApiAvailability = async (): Promise<boolean> => {
    try {
        const response = await fetch('/api/docker-status');
        return response.ok;
    } catch {
        return false;
    }
};

📊 性能优化

关键优化点

  1. 流式透传：nginx关闭缓冲，Node.js使用Readable.fromWeb()
  2. 超时策略：差异化超时，流式5分钟，普通2分钟
  3. 错误处理：快速失败，避免长时间等待
  4. 资源清理：及时清理定时器和连接

监控指标

  • 请求追踪：唯一请求ID
  • 性能日志：响应时间、状态码、错误率
  • 资源使用：内存、CPU、连接数

🔒 安全考虑

当前安全措施

  • 受信环境假设：基于Docker容器的受信环境
  • 基础CORS配置：允许跨域访问
  • 错误信息过滤：避免泄露敏感信息

可选安全增强

  • URL白名单：限制可访问的目标域名
  • 请求频率限制：防止滥用
  • 请求大小限制：防止大文件攻击

🎯 技术亮点

  1. 零依赖实现：提高安全性和可维护性
  2. 架构简洁：避免复杂的nginx动态代理配置
  3. 流式透传：正确处理SSE流式响应
  4. 智能错误处理：用户友好的错误分类和消息
  5. 完整集成：前端UI、LLM服务、类型定义全面支持

这个实现为Docker部署环境提供了完整、可靠、易维护的API代理解决方案。