5分钟上手NGINX S3 Gateway：从安装到配置的完整教程

【免费下载链接】nginx-s3-gatewayNGINX S3 Gateway项目地址: https://gitcode.com/gh_mirrors/ng/nginx-s3-gateway

NGINX S3 Gateway 是一款高效的开源工具，能够帮助用户轻松实现通过 NGINX 反向代理访问 Amazon S3 或兼容 S3 的对象存储服务。本教程将带你快速掌握从安装到基础配置的全过程，让你在短时间内即可搭建起自己的 S3 网关服务。

📋 准备工作：核心配置参数解析

在开始安装前，我们需要先了解一些关键的配置参数，这些参数将直接影响 NGINX S3 Gateway 的运行效果。主要的必填参数如下：

• S3_BUCKET_NAME：指定要代理的 S3 桶名称，例如my-bucket
• AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY：AWS 账户的访问密钥，用于身份验证
• S3_REGION：S3 桶所在的区域，如us-east-1
• S3_SERVER：S3 服务的地址，AWS S3 通常为s3.<region>.amazonaws.com
• S3_STYLE：地址样式，推荐使用virtual-v2（适用于 AWS S3 和 S3 Express One Zone）

这些参数可以在项目提供的 settings.example 文件中找到参考示例，你可以根据自己的实际情况进行修改。

🚀 快速安装：三种常用部署方式

1. Docker 容器部署（推荐新手）

Docker 部署是最简单快捷的方式，只需执行以下命令即可：

# 克隆项目仓库 git clone https://gitcode.com/gh_mirrors/ng/nginx-s3-gateway cd nginx-s3-gateway # 复制并修改配置文件 cp settings.example settings # 编辑 settings 文件，填入你的配置信息 # 运行容器 docker run --env-file ./settings --publish 80:80 --name nginx-s3-gateway \ ghcr.io/nginxinc/nginx-s3-gateway/nginx-oss-s3-gateway:latest

如果你需要更高的安全性，可以选择非特权容器镜像，它使用非 root 用户运行并监听 8080 端口：

docker run --env-file ./settings --publish 80:8080 --name nginx-s3-gateway \ ghcr.io/nginxinc/nginx-s3-gateway/nginx-oss-s3-gateway:unprivileged-oss-20250718

2. 系统服务部署（适用于生产环境）

项目提供了一个便捷的安装脚本，可以将 NGINX S3 Gateway 安装为系统服务：

# 克隆项目仓库 git clone https://gitcode.com/gh_mirrors/ng/nginx-s3-gateway cd nginx-s3-gateway # 复制并修改配置文件 cp settings.example settings # 编辑 settings 文件，填入你的配置信息 # 执行安装脚本 sudo env $(cat settings) ./standalone_ubuntu_oss_install.sh

3. 手动构建镜像（适用于开发人员）

如果你需要自定义镜像，可以手动构建：

# 构建开源版镜像 docker build --file Dockerfile.oss --tag nginx-s3-gateway:oss . # 运行自定义镜像 docker run --env-file ./settings --publish 80:80 --name nginx-s3-gateway \ nginx-s3-gateway:oss

⚙️ 核心配置：打造专属网关服务

目录列表功能配置

启用目录列表功能可以让用户通过浏览器浏览 S3 桶中的文件。只需在配置文件中设置：

ALLOW_DIRECTORY_LIST=true

你还可以通过DIRECTORY_LISTING_PATH_PREFIX参数为列表中的链接添加路径前缀，这在通过反向代理部署时非常有用。例如，设置DIRECTORY_LISTING_PATH_PREFIX='main/'后，目录列表的链接会自动添加main/前缀。

图：NGINX S3 Gateway 目录列表路径前缀配置示意图，展示了通过 HAProxy 和 NGINX S3 Gateway 实现路径前缀添加的架构

静态网站托管配置

要将 S3 桶配置为静态网站托管，只需设置：

PROVIDE_INDEX_PAGE=true APPEND_SLASH_FOR_POSSIBLE_DIRECTORY=true

这样，当用户访问目录路径时，网关会自动尝试返回该目录下的index.html文件，并在必要时自动添加斜杠。

缓存策略优化

NGINX S3 Gateway 提供了强大的缓存功能，可以显著提升访问速度。主要的缓存配置参数包括：

• PROXY_CACHE_MAX_SIZE：缓存的最大大小，默认10g
• PROXY_CACHE_INACTIVE：缓存文件的非活动时间，默认60m
• PROXY_CACHE_SLICE_SIZE：Range 请求的缓存块大小，默认1m

你可以根据实际需求调整这些参数，以达到最佳的性能表现。

🔍 工作原理：了解网关内部流程

NGINX S3 Gateway 的核心功能是处理 AWS S3 的签名请求。其内部工作流程如下：

1. 接收客户端请求
2. 获取 AWS 凭证（从环境变量或 IAM 角色）
3. 生成 AWS 签名（支持 v2 和 v4 版本）
4. 将请求转发到 S3 服务
5. 处理并返回响应

图：NGINX S3 Gateway 签名流程详细示意图，展示了从认证请求到生成签名再到转发请求的完整过程

这个流程确保了所有对 S3 的请求都是安全且符合 AWS 签名规范的，同时通过 NGINX 的强大功能提供了额外的缓存和负载均衡能力。

📝 总结与下一步

通过本教程，你已经掌握了 NGINX S3 Gateway 的基本安装和配置方法。现在，你可以：

• 探索更多高级配置选项，如 CORS 设置、自定义 headers 等
• 尝试将网关部署到 Kubernetes 环境中，利用 deployments/ecs/cloudformation/s3gateway.yaml 等资源文件
• 学习如何使用 AWS IAM 角色代替静态凭证，提高安全性

NGINX S3 Gateway 为 S3 存储提供了灵活而强大的访问控制和性能优化能力，无论是用于静态网站托管、文件共享还是作为应用程序的后端存储，它都能满足你的需求。开始使用吧，体验 NGINX 带来的高效与稳定！

【免费下载链接】nginx-s3-gatewayNGINX S3 Gateway项目地址: https://gitcode.com/gh_mirrors/ng/nginx-s3-gateway