pppy/s3-nginx-proxy

s3-nginx-proxy ![dev chat]([***]

一个功能丰富的基于NGINX的Amazon S3代理，可在Docker和Kubernetes中运行。

核心功能与特性

• 私有存储桶认证
• 多存储桶支持
• 每个存储桶多域名（共享缓存）
• 多区域支持
• 基于HTTP状态的缓存时长控制
• 配置更新后自动重载（生产环境同样支持）
• 单键缓存清除支持（使用HTTP DELETE方法）
• Cloudflare缓存清除支持
• 第三方S3提供商支持
• 可观测性（兼容Prometheus）

使用场景与适用范围

适用于需要通过NGINX反向代理访问Amazon S3或第三方S3兼容存储服务的场景，尤其适合需要缓存优化、多域名/多存储桶管理及访问控制的生产环境，支持Docker和Kubernetes部署。

使用方法与配置说明

权限配置

推荐为每个s3-nginx-proxy部署创建一个AWS IAM用户。然后附加仅授予其对所需存储桶的GetObject权限的策略，例如：

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::thepoon.ppy.sh/*"
    }
  ]
}

授予过多权限可能导致安全风险（例如列出整个存储桶内容）。请谨慎操作！

Docker部署

1. 编辑./data/etc/proxy-config/virtualhosts.json和./data/etc/proxy-config/cache.json以匹配您的需求设置。
2. 将AWS凭证放入./data/etc/proxy-config/secrets.json（参见./data/etc/proxy-config/secrets.json.example中的模板）。
3. 使用docker-compose up -d启动NGINX和配置生成器容器。

Kubernetes部署（Helm）

Helm chart 可在 https://github.com/ppy/helm-charts/tree/master/osu/s3-nginx-proxy 获取

缓存清除配置

可使用HTTP DELETE方法从缓存中清除单个文件。

默认情况下，所有人均可无需认证执行此操作。
可通过在缓存配置中设置purgeAuthorizationKey并使用HTTP Authorization头来启用认证。

Cloudflare缓存清除

如果在s3-nginx-proxy前部署了Cloudflare，还可通过其API清除Cloudflare CDN上的文件。

可通过在缓存配置中设置以下变量启用：

• purgeCloudflareApiToken：必须是启用清除功能的令牌。
  前往您的账户API密钥页面，创建一个在所需区域启用Zone > Cache Purge > Purge权限的自定义令牌。
• purgeCloudflareZoneId：可在Cloudflare控制台的域名主页找到。

第三方S3提供商支持

若使用Amazon S3，S3端点会根据region属性计算。对于其他提供商，可使用upstream代替。

例如，纽约3区的DigitalOcean Spaces的端点为nyc3.digitaloceanspaces.com。

请注意，使用第三方提供商可能无法享受Amazon S3细粒度权限带来的额外安全性（可能导致存储桶列表公开！）。

可观测性

可在metrics.json中启用Prometheus兼容的指标端点。
暴露的指标包括：

• nginx_http_requests_total：HTTP请求总数（计数器）
• nginx_http_request_duration_seconds：HTTP请求延迟（直方图）
• nginx_http_connections：HTTP连接数（ gauge ）
• nginx_upstream_cache_status：按上游缓存状态分类的HTTP请求数（计数器）

重大变更

2022.705.0

密钥已移至./data/etc/proxy-config/secrets.json，且每个密钥集的键需要添加到虚拟主机配置中（参见默认的./data/etc/proxy-config/virtualhosts.json）。

贡献指南

该项目目前非常基础，类似于最小可行产品。
计划功能包括缓存清除能力（全量和特定键）以及更多配置选项。

可通过向本仓库提交拉取请求进行贡献。我们希望通过bounty系统对较大贡献给予荣誉和奖励。如果不确定可以帮助做什么，请查看https://github.com/ppy/s3-nginx-proxy/issues%E3%80%82

请注意，虽然我们已有某些标准，但并非一成不变。如果您对代码结构、使用的库或贡献流程有任何问题，请提出。我们欢迎所有反馈，以使该项目的贡献过程尽可能顺畅。

许可证

osu!客户端代码、框架和服务器端组件均根据MIT许可证授权。详情请参见许可证文件。简而言之，只要在任何软件/源代码副本中包含原始版权和许可声明，您可以进行任何操作。

请注意，这不包括在任何软件、资源、广告或促销中使用"osu!"或"ppy"品牌，因为这受商标法保护。