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

镜像概述和主要用途

本镜像为远程存储代理的调试版本，基于正式版远程存储代理构建，针对开发和测试场景优化。主要用于开发、测试阶段对远程存储代理的功能逻辑、数据流转、错误处理等进行调试分析，提供增强的日志输出、调试工具和性能分析能力，帮助开发人员快速定位和解决问题。

核心功能和特性

核心功能

• 实现远程存储代理基础功能，支持对S3、GCS、Azure Blob等主流远程存储服务的代理访问
• 提供请求转发、身份验证代理、数据缓存等核心代理能力

调试增强特性

• 详细日志记录：输出包含请求/响应头、 payload 摘要、错误堆栈、内部状态变更等调试级日志
• 调试接口暴露：内置 HTTP 调试端点（默认 /debug），支持查看当前连接状态、缓存命中率、请求队列等实时信息
• 性能指标收集：自动采集并暴露响应时间分布、吞吐量、错误率等性能指标（兼容 Prometheus 格式）
• 配置热更新：支持通过文件挂载或 API 动态更新配置，无需重启容器即可应用变更
• 故障注入工具：内置延迟注入、错误模拟（如随机 5xx 响应）等故障测试功能

使用场景和适用范围

适用场景

• 开发环境中调试远程存储代理的功能逻辑
• 测试环境中复现并排查生产环境中出现的代理访问问题
• 性能优化阶段分析代理瓶颈（如缓存策略、网络延迟）
• 新功能开发时验证代理与远程存储服务的兼容性

适用范围

• 开发人员、测试人员、运维调试人员
• 仅用于非生产环境（开发/测试/预发布），不建议在生产环境部署

使用方法和配置说明

获取镜像

通过 Docker Hub 或私有仓库拉取镜像：

docker pull [镜像仓库地址]/remote-storage-proxy:debug-latest

基本运行命令

简单启动（默认配置）

docker run -d \
  --name remote-storage-proxy-debug \
  -p 8080:8080 \
  [镜像仓库地址]/remote-storage-proxy:debug-latest

带调试配置启动

docker run -d \
  --name remote-storage-proxy-debug \
  -p 8080:8080 \
  -p 9090:9090 \  # 性能指标暴露端口
  -e LOG_LEVEL=debug \  # 开启调试级日志
  -e REMOTE_STORAGE_TYPE=s3 \  # 远程存储类型（s3/gcs/azure）
  -e REMOTE_STORAGE_ENDPOINT=[***] \  # 远程存储服务端点
  -e DEBUG_ENDPOINT_ENABLE=true \  # 启用调试接口
  -v $(pwd)/config.yaml:/app/config.yaml \  # 挂载自定义配置文件
  [镜像仓库地址]/remote-storage-proxy:debug-latest

环境变量配置

通过环境变量可快速配置核心参数，常用配置如下表：

配置文件挂载

如需自定义详细配置（如高级缓存策略、访问控制规则），可通过挂载配置文件实现：

1. 本地创建 config.yaml（参考官方配置模板）
2. 启动时挂载文件：

docker run -d \
  --name remote-storage-proxy-debug \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -e CONFIG_FILE=/app/config.yaml \  # 指定配置文件路径
  [镜像仓库地址]/remote-storage-proxy:debug-latest

调试功能使用

访问调试接口

启动后通过 http://<容器IP>:8080/debug 访问调试页面，可查看：

• 当前活跃连接列表及详细信息
• 最近 100 条请求的处理日志
• 缓存统计（命中/未命中次数、缓存项分布）

查看性能指标

通过 http://<容器IP>:9090/metrics 访问 Prometheus 格式指标，关键指标包括：

• proxy_request_duration_seconds：请求响应时间分布
• proxy_cache_hit_ratio：缓存命中率
• proxy_errors_total：按错误类型统计的错误总数

注意事项

• 调试版本默认开启所有调试功能，可能会增加资源消耗（CPU/内存/网络带宽），建议根据需求通过配置关闭不必要的调试特性
• 日志中可能包含敏感信息（如认证令牌、请求 payload），使用时需确保符合数据安全规范
• 不建议在生产环境使用，正式环境请使用非调试版本镜像