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

镜像概述和主要用途

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

核心功能和特性

核心功能

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

调试增强特性

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

使用场景和适用范围

适用场景

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

适用范围

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

使用方法和配置说明

获取镜像

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

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

基本运行命令

简单启动（默认配置）

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

带调试配置启动

bash
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

环境变量配置

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

环境变量名	描述	默认值	是否必填
`LOG_LEVEL`	日志级别（debug/info/warn/error）	`info`	否
`PROXY_PORT`	代理服务监听端口	`8080`	否
`REMOTE_STORAGE_TYPE`	远程存储类型（s3/gcs/azure）	-	是
`REMOTE_STORAGE_ENDPOINT`	远程存储服务端点 URL	-	是
`DEBUG_ENDPOINT_ENABLE`	是否启用调试接口（true/false）	`true`	否
`METRICS_PORT`	性能指标暴露端口	`9090`	否
`CACHE_SIZE_MB`	本地缓存大小（MB）	`1024`	否

配置文件挂载

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

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

bash
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