lywsvip/prompt-optimizer
1
0
Fork 0
mirror of https://github.com/linshenkx/prompt-optimizer.git synced 2026-05-08 06:28:50 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
develop
prompt-optimizer/docs/archives/122-docker-api-proxy/experience.md
linshen 0717550400 docs(archives): 添加 Docker API代理功能实现文档 
- 新增 122-docker-api-proxy 目录，包含项目概述、技术实现、开发经验等文档- 详细介绍了 Docker 环境下的 API 代理解决方案，包括架构设计、关键技术要点、实施步骤等
- 提供了完整的开发经验和最佳实践总结，为类似项目提供了参考
- 更新了档案总表，增加了 122号项目的记录
- 移除了旧的架构对比和关键修复文档，精简了工作空间资料
2025-08-17 15:23:56 +08:00

6.4 KiB
Raw Permalink Blame History

开发经验总结

🎯 核心经验

架构设计经验

  1. 简化优先原则

    • 在受信环境中，优先选择简单可维护的方案
    • 避免过度工程化，nginx本地转发比动态代理更可靠
    • 职责分离：nginx负责转发，Node.js负责业务逻辑

  2. 零依赖实现价值

    • 提高安全性：减少供应链攻击风险
    • 提高可维护性：只依赖Node.js内置模块
    • 提高稳定性：避免第三方库的版本冲突

  3. 渐进式开发方法

    • 先实现基础功能，再添加高级特性
    • 每个阶段都有明确的验证标准
    • 及时测试，避免问题积累

🛠️ 技术实现经验

流式响应处理

  1. nginx配置关键点

    proxy_buffering off;
proxy_request_buffering off;
add_header X-Accel-Buffering no always;
    • 必须关闭所有缓冲，确保实时透传
    • X-Accel-Buffering no是关键配置

  2. Node.js流处理

    const stream = Readable.fromWeb(upstreamRes.body);
stream.pipe(res);
    • 使用Readable.fromWeb()正确处理Web Streams
    • 直接pipe到响应，避免内存积累

错误处理最佳实践

  1. 智能错误分类

    • 超时：504 Gateway Timeout
    • DNS解析失败：502 Bad Gateway
    • 连接被拒绝：502 Bad Gateway
    • 其他错误：500 Internal Server Error

  2. 用户友好错误消息

    • 避免技术术语，使用通俗易懂的描述
    • 提供可能的解决建议
    • 保持错误消息的一致性

  3. 请求追踪系统

    • 为每个请求生成唯一ID
    • 在日志中关联请求ID和错误
    • 便于问题排查和性能监控

超时策略设计

  1. 差异化超时

    • 流式请求：5分钟（LLM生成需要时间）
    • 普通请求：2分钟（快速失败）
    • 支持环境变量配置

  2. 超时处理

    • 及时清理定时器，避免内存泄漏
    • 返回明确的超时错误码
    • 记录超时事件用于监控

🚫 避坑指南

常见错误

  1. CORS头重复设置

    • 问题：nginx和Node.js同时设置CORS头
    • 解决：统一由Node.js处理，nginx不设置
    • 教训：明确职责分工，避免重复配置

  2. 流式响应缓冲

    • 问题：nginx默认缓冲导致流式响应延迟
    • 解决：关闭所有相关缓冲配置
    • 教训：流式响应需要特殊配置

  3. HEAD请求处理

    • 问题：HEAD请求不应该有响应体
    • 解决：特殊处理HEAD请求，只返回头部
    • 教训：严格遵循HTTP规范

  4. 超时时间设置

    • 问题：统一超时不适合所有场景
    • 解决：根据请求类型差异化设置
    • 教训：考虑实际使用场景的差异

设计陷阱

  1. 过度安全防护

    • 在受信环境中，过度的安全措施可能影响功能
    • 应该根据实际部署环境选择合适的安全级别
    • 可以预留安全增强的扩展点

  2. 复杂配置追求

    • nginx动态代理虽然功能强大，但配置复杂
    • 简单的本地转发更可靠、易维护
    • 选择方案时要考虑维护成本

  3. 依赖管理

    • 外部依赖增加了复杂性和风险
    • 在可能的情况下，优先使用内置功能
    • 每个依赖都要考虑其必要性

🔄 架构设计经验

方案选择思路

  1. 需求分析

    • 功能需求：支持普通和流式请求
    • 性能需求：低延迟、高并发
    • 维护需求：简单配置、易于调试

  2. 方案对比

    • nginx动态代理：功能强大但配置复杂
    • nginx本地转发：简单可靠，易于维护
    • 选择标准：在满足需求的前提下，选择最简单的方案

  3. 架构演进

    • 从复杂到简单的演进过程
    • 通过实践验证方案的可行性
    • 及时调整架构设计

集成策略

  1. 前端集成

    • 复用现有的环境检测模式
    • 保持与Vercel代理一致的用户体验
    • 使用视觉区分（颜色主题）

  2. 后端集成

    • 在LLM服务中添加Docker代理支持
    • 保持接口的一致性
    • 完善类型定义

  3. 构建集成

    • 确保所有包都能正确构建
    • TypeScript类型检查通过
    • 及时验证集成效果

🎯 可复用经验

代理服务实现模式

  1. 零依赖HTTP代理

    • 使用Node.js内置http模块
    • 正确处理各种HTTP方法
    • 实现完整的错误处理

  2. 流式数据透传

    • 使用Readable.fromWeb()处理Web Streams
    • 配置nginx关闭缓冲
    • 实现实时数据传输

  3. 请求追踪系统

    • 生成唯一请求ID
    • 记录完整的请求生命周期
    • 便于问题排查和性能监控

环境集成模式

  1. Docker服务集成

    • 使用supervisord管理多个进程
    • 配置nginx转发到内部服务
    • 实现服务间的协调

  2. 前端环境检测

    • 实现可用性检测接口
    • 缓存检测结果避免重复请求
    • 根据环境动态显示功能

  3. 配置管理

    • 支持环境变量配置
    • 提供合理的默认值
    • 实现配置的持久化

📊 性能优化经验

关键优化点

  1. 减少延迟

    • 使用本地转发避免DNS解析
    • 关闭不必要的缓冲
    • 实现快速错误处理

  2. 资源管理

    • 及时清理定时器和连接
    • 避免内存泄漏
    • 监控资源使用情况

  3. 并发处理

    • Node.js天然支持高并发
    • 避免阻塞操作
    • 实现合理的超时策略

监控和调试

  1. 日志设计

    • 记录关键信息：时间戳、请求ID、IP、耗时
    • 使用结构化日志格式
    • 区分不同级别的日志

  2. 错误追踪

    • 为每个错误分配唯一ID
    • 记录错误的完整上下文
    • 实现错误的分类和统计

  3. 性能监控

    • 记录响应时间分布
    • 监控错误率变化
    • 跟踪资源使用情况

🚀 后续改进方向

可选增强功能

  1. 安全增强

    • URL白名单验证
    • 请求频率限制
    • 请求大小限制

  2. 监控增强

    • 集成专业监控工具
    • 实现告警机制
    • 提供监控仪表板

  3. 性能优化

    • 连接池管理
    • 缓存策略优化
    • 负载均衡支持

架构演进

  1. 微服务化

    • 将代理服务独立部署
    • 实现服务发现机制
    • 支持水平扩展

  2. 配置中心

    • 集中管理配置
    • 支持动态配置更新
    • 实现配置版本管理

这些经验为类似的代理服务开发提供了完整的参考，特别是在Docker环境下的API代理实现。

Reference in New Issue View Git Blame Copy Permalink