miniogate

miniogate 是一个用 Python 实现的 MinIO / S3 兼容 HTTP 代理。当前实现刻意收敛在第一阶段目标：面向后端客户端做 SigV4 透明转发，优先兼容 io.minio.client。

当前范围

• 保留原始请求方法、原始 path 和原始 query。
• 原样透传 Authorization 和 x-amz-* 等签名相关请求头。
• 默认保留客户端 Host，让下游 MinIO 能按原请求语义验签。
• 以流式方式转发请求体和响应体，不把整个对象读进内存。
• 原样返回下游状态码、响应头和响应体，不包装 MinIO 错误。
• 输出访问日志，记录客户端地址、方法、原始目标、状态码、耗时、上游地址和关键请求头。

当前不做的事情

• 不对下游 MinIO 重新签名。
• 不处理浏览器访问、CORS 或控制台代理。
• 不支持 virtual-host-style 路由。
• 不做请求改写、权限策略、多租户身份转换。

项目结构

• src/miniogate：代理服务实现。
• tests/test_proxy.py：协议级透明性测试，直接抓原始 HTTP 请求行。
• tests/java：基于 io.minio.client 的 Docker 烟测。成功后会保留对象，并打印实际创建的对象名。
• docker-compose.yml：本地开发和测试用编排文件。

当前默认环境

当前 docker-compose.yml 默认假定：

• 你的宿主机上已经有 MinIO 在运行。
• 宿主机 MinIO 地址是 http://host.docker.internal:9000。
• 凭证是：
  • access key = admin
  • secret key = miniopass

如果你的本地 MinIO 地址或凭证不同，请修改 docker-compose.yml 里的环境变量。

开发运行

启动代理服务：

docker compose up --build -d miniogate

代理默认监听：

http://localhost:8080

并转发到宿主机上的 MinIO：

http://host.docker.internal:9000

查看代理日志：

docker compose logs -f miniogate

停止服务：

docker compose down

测试

运行 Python 协议级测试：

docker compose run --rm python-tests

运行 Java 烟测：

docker compose run --rm java-smoke

Java 烟测会：

• 通过 miniogate 访问你的 MinIO。
• 自动创建 smoke-bucket（如果不存在）。
• 上传一个小对象，并验证 statObject。
• 对小对象做一次范围读取，验证 Range 场景。
• 上传一个大于 5 MiB 的对象，覆盖 multipart 上传路径。
• 对 multipart 对象做一次跨分片边界的范围读取。
• 保留该对象，方便你在自己的 MinIO 中直接查看结果。
• 在控制台输出实际创建的对象路径。

当前默认测试对象前缀是：

TEST_OBJECT_PREFIX=smoke-object

实际对象名会自动拼接时间戳，例如：

smoke-object-1743230000000.txt

部署

构建运行镜像：

docker build -t miniogate:local .

连接现有 MinIO 运行：

docker run --rm -p 8080:8080 \
  -e MINIOGATE_UPSTREAM_BASE=http://minio.example.internal:9000 \
  miniogate:local

环境变量

• MINIOGATE_UPSTREAM_BASE：下游 MinIO 地址，例如 http://host.docker.internal:9000。
• MINIOGATE_BIND_HOST：监听地址，默认 0.0.0.0。
• MINIOGATE_BIND_PORT：监听端口，默认 8080。
• MINIOGATE_CONNECT_TIMEOUT_SECONDS：连接下游的超时时间，默认 5.0 秒。
• MINIOGATE_LOG_LEVEL：日志级别，默认 INFO。

日志说明

代理当前会输出访问日志，包含这些关键信息：

• 客户端地址
• 请求方法
• 原始请求目标
• 响应状态码
• 请求耗时
• 下游上游地址
• Host
• Content-Length
• User-Agent
• 异常信息

下一步建议测试项

• multipart upload 全流程。
• presigned URL 透传行为。
• 大对象上传、下载和慢连接场景。
• Range、HEAD、条件请求。
• Expect: 100-continue。
• 带特殊字符对象名的真实 Java SDK 请求。