Remote Storage Proxy 镜像文档

1. 镜像概述和主要用途

Remote Storage Proxy 是一个轻量级的远程存储代理服务，用于统一管理和转发对各类远程存储服务的访问请求。本镜像基于最新主干构建（latest trunk build），提供对主流存储协议的代理能力，支持请求缓存、协议转换和访问控制，适用于需要简化多存储系统集成或优化远程存储访问的场景。

2. 核心功能和特性

核心功能

• 多后端存储支持：兼容 S3、FTP、WebDAV、NFS 等主流存储协议。
• 请求缓存：本地缓存远程存储数据，减少重复请求，提升访问速度。
• 协议转换：支持不同存储协议间的透明转换（如 HTTP 转 FTP、S3 转 WebDAV）。
• 访问控制：基于 IP、用户角色或 API Key 的请求过滤与权限管理。
• 高可用：支持多实例部署，通过负载均衡实现服务高可用。

主要特性

• 轻量级设计：基于 Go 语言开发，容器镜像体积小（<50MB），资源占用低。
• 动态配置：支持运行时更新后端存储配置，无需重启服务。
• 监控集成：暴露 Prometheus 指标接口，支持监控代理服务性能与状态。
• 日志审计：详细记录存储访问日志，支持 JSON 格式输出与日志分级。

3. 使用场景和适用范围

典型使用场景

• 企业存储统一接入：作为多存储系统（如 S3、企业网盘、本地 NAS）的统一访问入口，简化业务系统集成。
• 边缘缓存加速：边缘设备访问云端存储时，通过本地缓存减少网络延迟与带宽消耗。
• 存储访问审计：对远程存储访问进行集中日志记录与权限控制，满足合规审计需求。
• 协议转换网关：将 legacy 系统的 FTP 请求转换为 S3 请求，实现存储系统平滑迁移。
• 开发测试模拟：在测试环境中模拟各类远程存储服务，无需依赖真实后端。

适用范围

• 企业 IT 架构：适用于中大型企业的混合存储环境统一管理。
• 边缘计算：边缘节点与云端存储的中间层代理。
• 云原生应用：作为 Kubernetes 集群内的存储访问代理组件。
• 开发测试：快速搭建模拟远程存储服务的测试环境。

4. 使用方法和配置说明

4.1 基本使用（docker run）

最简启动命令

docker run -d \
  --name remote-storage-proxy \
  -p 8080:8080 \
  -e REMOTE_STORAGE_URL="s3://my-s3-bucket.s3.amazonaws.com" \
  -e STORAGE_TYPE="s3" \
  -e AUTH_ACCESS_KEY="AKIAEXAMPLE" \
  -e AUTH_SECRET_KEY="secret" \
  remote-storage-proxy:latest-trunk

带缓存配置的启动命令

docker run -d \
  --name remote-storage-proxy \
  -p 8080:8080 \
  -v /host/cache/dir:/app/cache \  # 挂载本地缓存目录
  -e REMOTE_STORAGE_URL="webdav://example.com/remote" \
  -e STORAGE_TYPE="webdav" \
  -e AUTH_USERNAME="user" \
  -e AUTH_PASSWORD="pass" \
  -e CACHE_ENABLED="true" \
  -e CACHE_SIZE="20GB" \          # 缓存最大容量
  -e CACHE_TTL="3600" \           # 缓存过期时间（秒）
  remote-storage-proxy:latest-trunk

4.2 Docker Compose 配置示例

version: "3.8"

services:
  remote-storage-proxy:
    image: remote-storage-proxy:latest-trunk
    container_name: remote-storage-proxy
    restart: always
    ports:
      - "8080:8080"  # 代理服务端口
      - "9090:9090"  # Prometheus 指标端口
    environment:
      - REMOTE_STORAGE_URL="s3://prod-bucket.s3.cn-north-1.amazonaws.com.cn"
      - STORAGE_TYPE="s3"
      - AUTH_ACCESS_KEY="${S3_ACCESS_KEY}"  # 从环境变量读取敏感信息
      - AUTH_SECRET_KEY="${S3_SECRET_KEY}"
      - CACHE_ENABLED="true"
      - CACHE_SIZE="50GB"
      - LOG_LEVEL="info"
      - METRICS_ENABLED="true"
      - METRICS_PORT="9090"
    volumes:
      - ./cache:/app/cache  # 持久化缓存数据
      - ./config:/app/config  # 挂载自定义配置文件（可选）
    networks:
      - storage-network

networks:
  storage-network:
    driver: bridge

4.3 配置参数说明

4.3.1 环境变量配置

4.3.2 配置文件（可选）

若需复杂配置（如多后端路由、细粒度访问控制），可通过挂载配置文件实现。配置文件支持 YAML 格式，默认路径为 /app/config/config.yaml。

配置文件示例（多后端路由）：

proxies:
  - name: "s3-proxy"
    path_prefix: "/s3"  # 访问路径前缀，如 /s3/object.txt 转发至 S3
    storage_type: "s3"
    remote_url: "s3://prod-bucket.s3.amazonaws.com"
    auth:
      access_key: "${S3_ACCESS_KEY}"
      secret_key: "${S3_SECRET_KEY}"
    cache:
      enabled: true
      size: "30GB"
      ttl: 7200

  - name: "ftp-proxy"
    path_prefix: "/ftp"  # 访问路径前缀，如 /ftp/file.txt 转发至 FTP
    storage_type: "ftp"
    remote_url: "[***]"
    auth:
      username: "ftp-user"
      password: "ftp-pass"
    cache:
      enabled: false

使用配置文件启动：

docker run -d \
  --name remote-storage-proxy \
  -p 8080:8080 \
  -v ./config.yaml:/app/config/config.yaml \  # 挂载自定义配置文件
  remote-storage-proxy:latest-trunk

5. 注意事项

1. 版本稳定性：latest-trunk 标签为开发主干构建，可能包含未稳定特性，生产环境建议使用特定版本标签（如 v1.2.0）。
2. 敏感信息安全：认证密钥（如 AUTH_SECRET_KEY）建议通过 Docker Secrets 或环境变量注入，避免明文存储在配置文件中。
3. 缓存持久化：若启用缓存，建议通过 volume 挂载宿主机目录，避免容器重启后缓存丢失。
4. 网络策略：确保容器网络可访问 REMOTE_STORAGE_URL 配置的远程存储服务（如开放对应端口、配置 VPC 网络策略）。
5. 性能调优：高并发场景下，可调整 MAX_CONCURRENT_REQUESTS 与缓存大小，避免资源瓶颈。