远程存储代理调试版镜像文档

一、镜像概述与主要用途

本镜像为远程存储代理（Remote Storage Proxy）的调试版本，基于最新主干代码（trunk）构建。主要用途是作为远程存储服务的中间代理层，提供增强的调试能力，用于开发与测试阶段的请求转发、数据交互逻辑验证及问题排查。

二、核心功能与特性

2.1 核心功能

• 远程存储服务请求转发：支持HTTP/HTTPS协议的请求代理，实现客户端与远程存储服务的通信中转。
• 调试信息采集：实时捕获并记录代理过程中的请求头、响应体、传输耗时等详细数据。
• 主干功能预览：包含最新开发阶段的功能特性，支持验证未发布的功能逻辑。

2.2 调试特性

• 详细日志记录：默认开启DEBUG级别日志，输出请求转发路径、错误堆栈、数据校验结果等调试信息。
• 调试接口支持：提供独立调试端口，可通过HTTP接口查询实时代理状态、历史请求记录。
• 请求/响应监控：支持实时打印请求/响应内容（含二进制数据Hex格式展示），便于数据完整性校验。

三、使用场景与适用范围

3.1 适用场景

• 开发环境：调试远程存储交互逻辑，验证客户端请求格式、服务端响应处理是否符合预期。
• 测试环境：复现生产环境中难以排查的远程存储通信异常，通过调试日志定位问题根因。
• 功能验证：验证主干分支新功能（如断点续传、数据压缩、权限校验）的正确性。

3.2 适用范围

• 客户端类型：支持所有基于HTTP/HTTPS协议与远程存储交互的客户端（如S3 SDK、自定义存储客户端等）。
• 远程存储类型：兼容主流对象存储服务（如AWS S3、MinIO、阿里云OSS等）及自定义远程存储服务。

3.3 环境限制

• 禁止生产环境使用：调试功能会引入性能损耗（如详细日志IO、请求内容缓存），且调试接口存在安全风险。
• 依赖网络环境：需保证代理容器与客户端、远程存储服务之间网络互通。

四、使用方法与部署示例

4.1 基础环境要求

• Docker Engine 20.10+ 或 Docker Desktop 4.0+
• 可用内存 ≥ 512MB（调试日志及请求缓存会占用额外内存）

4.2 Docker Run 部署

bash
docker run -d \
  --name remote-storage-proxy-debug \
  -p 8080:8080 \  # 代理服务端口（客户端访问端口）
  -p 9000:9000 \  # 调试接口端口
  -v /local/logs:/app/logs \  # 挂载日志目录（持久化调试日志）
  -e REMOTE_STORAGE_URL="[***]" \  # 远程存储服务地址（必填）
  -e LOG_LEVEL="debug" \  # 日志级别（调试版默认debug，可选info/warn/error）
  -e DEBUG_PORT=9000 \  # 调试接口端口（需与-p映射一致）
  -e PROXY_TIMEOUT=30 \  # 代理请求超时时间（秒）
  remote-storage-proxy:debug-latest

4.3 Docker Compose 部署

创建 docker-compose.yml 文件：

yaml
version: '3.8'
services:
  proxy-debug:
    image: remote-storage-proxy:debug-latest
    container_name: remote-storage-proxy-debug
    ports:
      - "8080:8080"  # 代理服务端口
      - "9000:9000"  # 调试接口端口
    volumes:
      - ./logs:/app/logs  # 本地日志目录（需提前创建）
    environment:
      - REMOTE_STORAGE_URL=[***]  # 远程存储服务地址（必填）
      - LOG_LEVEL=debug  # 日志级别
      - DEBUG_PORT=9000  # 调试接口端口
      - PROXY_TIMEOUT=30  # 超时时间（秒）
      - ENABLE_REQUEST_LOG=true  # 是否记录完整请求内容（调试用）
    restart: unless-stopped  # 调试环境建议手动管理，避免异常重启掩盖问题

启动命令：

bash
docker-compose up -d

五、配置参数与环境变量

5.1 核心环境变量配置

5.2 调试接口使用示例

调试接口（默认http://<容器IP>:9000/debug）提供以下端点：

• GET /debug/status：查看代理服务状态（连接数、转发成功率、当前日志级别）。
• GET /debug/requests：获取最近请求历史（含请求头、响应码、耗时，需ENABLE_REQUEST_LOG=true）。
• GET /debug/logs：查看实时日志片段（最近100行）。

示例请求：

bash
curl http://localhost:9000/debug/requests  # 查看最近请求记录

六、注意事项

1. 性能影响：调试版默认开启全量日志和请求缓存，会增加CPU/内存/磁盘IO占用，建议测试环境限制并发量。
2. 安全性提示：调试接口（DEBUG_PORT）未启用身份验证和加密，请勿暴露在公网环境；生产环境需使用非调试版镜像。
3. 数据持久化：日志文件建议通过-v挂载至宿主机，避免容器删除后调试数据丢失。
4. 版本兼容性：基于主干构建，功能可能与稳定版存在差异，生产部署前需验证与稳定版的兼容性。
5. 资源限制：调试时若处理大文件传输，建议通过--memory和--cpus限制容器资源，避免影响主机其他服务。