From 87acac47e54754228555645fcdab313fdd4856a1 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Thu, 26 Feb 2026 14:23:07 -0800
Subject: [PATCH] add externalUrl

---
 Quick-Start-with-weed-mini.md | 11 +++++++++++
 S3-Configuration.md           | 18 ++++++++++++++++++
 S3-Nginx-Proxy.md             | 27 +++++++++++++++++++++++++++
 3 files changed, 56 insertions(+)

diff --git a/Quick-Start-with-weed-mini.md b/Quick-Start-with-weed-mini.md
index 4f97aad..24469ff 100644
--- a/Quick-Start-with-weed-mini.md
+++ b/Quick-Start-with-weed-mini.md
@@ -58,6 +58,17 @@ weed mini -dir=/path/to/data
 weed mini -dir=/data -master.port=9444 -s3.port=8334
 ```
 
+### S3 with Reverse Proxy
+
+If `weed mini` is behind a reverse proxy (e.g. Nginx, Cloudflare Tunnel), use the `-s3.externalUrl` flag to ensure S3 signature verification works correctly:
+
+```bash
+# SeaweedFS reachable externally at https://s3.example.com
+weed mini -dir=/data -s3.externalUrl=https://s3.example.com
+```
+
+For more configuration details, see the **[[S3 Nginx Proxy]]** page.
+
 ## S3 Credentials Setup
 
 ### Option 1: Environment Variables (Recommended)
diff --git a/S3-Configuration.md b/S3-Configuration.md
index 5e62c30..c1af77d 100644
--- a/S3-Configuration.md
+++ b/S3-Configuration.md
@@ -80,6 +80,24 @@ weed mini -s3.config=/path/to/s3.json
 | `Read:bucket1` | Read access to specific bucket |
 | `Write:bucket1` | Write access to specific bucket |
 
+## S3 with Reverse Proxy
+
+When SeaweedFS S3 is behind a reverse proxy (Nginx, HAProxy, AWS ALB, etc.), it needs to know the correct host and protocol to verify S3 signatures.
+
+By default, SeaweedFS automatically detects the following headers from your proxy:
+- `X-Forwarded-Host` (e.g. `s3.example.com`)
+- `X-Forwarded-Proto` (e.g. `https`)
+- `X-Forwarded-Port` (e.g. `443`)
+
+Alternatively, you can explicitly set the public-facing URL using the `externalUrl` flag. This is recommended for complex proxy setups or when you cannot easily modify proxy headers.
+
+```bash
+# Explicitly set the external S3 endpoint
+weed s3 -s3.externalUrl=https://s3.example.com
+```
+
+For detailed configuration examples, see the **[[S3 Nginx Proxy]]** page.
+
 ---
 
 ## Advanced IAM (`-s3.iam.config`)
diff --git a/S3-Nginx-Proxy.md b/S3-Nginx-Proxy.md
index ee7701c..00ba19c 100644
--- a/S3-Nginx-Proxy.md
+++ b/S3-Nginx-Proxy.md
@@ -5,6 +5,33 @@ For virtual-hosted style URL buckets, you'll need to add a [wildcard DNS record]
 
 Make sure the config sets the `X-Forwarded-Host` and optionally the `X-Forwarded-Port` if you are using a non-standard port. SeaweedFS will automatically combine these headers to reconstruct the correct host information for signature verification.
 
+## Explicit External URL for Signature Verification
+
+In scenarios where the reverse proxy cannot easily be configured to send the necessary headers, or in complex multi-hop environments, you can use the `-s3.externalUrl` flag to explicitly set the public-facing URL of the S3 service.
+
+When `-s3.externalUrl` is set, SeaweedFS will use the host and port from this URL for all S3 signature verification, ignoring incoming `Host` or `X-Forwarded-*` headers.
+
+### Usage Example
+
+```bash
+# SeaweedFS S3 is reachable externally at https://s3.example.com:9000
+weed s3 -s3.externalUrl=https://s3.example.com:9000
+```
+
+Alternatively, set the environment variable:
+```bash
+export WEED_S3_EXTERNAL_URL=https://s3.example.com:9000
+```
+
+This flag is also supported in `weed mini` and `weed filer`:
+```bash
+weed mini -s3.externalUrl=http://localhost:9000
+weed filer -s3 -s3.externalUrl=https://s3.mycorp.internal
+```
+
+### Why use this?
+AWS Signature V4 includes the `Host` header in the signed payload. If SeaweedFS is behind a proxy, the `Host` header it receives might be the internal address (e.g., `localhost:8333`), while the client signed the request with the external address (e.g., `s3.example.com`). Setting `-s3.externalUrl` ensures SeaweedFS uses the correct host for signature validation.
+
 ## Reverse Proxy with URL Path Prefixes
 
 SeaweedFS S3 API supports the `X-Forwarded-Prefix` header for scenarios where a reverse proxy strips URL path prefixes before forwarding requests. This is common when hosting the S3 API under a subpath like `/s3/` or `/api/s3/`.