From cb424640a2435a0b2279923b0b7e19bb82a5c840 Mon Sep 17 00:00:00 2001 From: silverwind <2021+silverwind@noreply.gitea.com> Date: Fri, 23 Oct 2026 22:44:51 +0000 Subject: [PATCH] docs: document Forwarded header and client port for REVERSE_PROXY_LIMIT (#560) Document https://github.com/go-gitea/gitea/pull/39190, which reads the RFC 7239 `Forwarded` header when `X-Forwarded-For` is absent and keeps the forwarded client port. - `REVERSE_PROXY_LIMIT`: list `X-Real-IP`, `X-Forwarded-For` and `Forwarded` in the order they are read, and where the client port comes from, also in zh-cn and zh-tw - Reverse proxies: require the proxy to set `X-Real-IP`, since Caddy, Apache and HAProxy pass a client-sent one through by default, and mention `X-Real-Port` for logging the client port Co-authored-by: Lunny Xiao Reviewed-on: https://gitea.com/gitea/docs/pulls/560 Reviewed-by: Lunny Xiao --- docs/administration/config-cheat-sheet.md | 3 ++- docs/administration/reverse-proxies.md | 1 + i18n/zh-cn/docs/current/administration/config-cheat-sheet.md | 3 ++- i18n/zh-tw/docs/current/administration/config-cheat-sheet.md | 3 ++- 4 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/administration/config-cheat-sheet.md b/docs/administration/config-cheat-sheet.md index f08ac133..b9bbd9b8 100644 --- a/docs/administration/config-cheat-sheet.md +++ b/docs/administration/config-cheat-sheet.md @@ -595,7 +595,8 @@ And the following unique queues: authentication provided email. - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy authentication provided full name. -- `REVERSE_PROXY_LIMIT`: **1**: Interpret X-Forwarded-For header or the X-Real-IP header and set this as the remote IP for the request. +- `REVERSE_PROXY_LIMIT`: **1**: Interpret the X-Real-IP, X-Forwarded-For or Forwarded header, in that order, and set this as the remote IP for the request. + The client port is taken from the header value or, with X-Real-IP, from X-Real-Port. Number of trusted proxy count. Set to zero to not use these headers. - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all. - `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`. diff --git a/docs/administration/reverse-proxies.md b/docs/administration/reverse-proxies.md index b1f75c58..7619ee0d 100644 --- a/docs/administration/reverse-proxies.md +++ b/docs/administration/reverse-proxies.md @@ -16,6 +16,7 @@ aliases: 4. Make sure `Host` and `X-Forwarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited. 5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work. 6. Gitea uses a WebSocket connection at `/-/ws` for real-time updates like the notification counter. Make sure the reverse-proxy talks HTTP/1.1 and forwards the `Upgrade` and `Connection` headers, see the examples below. Without it, Gitea falls back to periodic polling. +7. Make sure the reverse-proxy sets the `X-Real-IP` header, otherwise Gitea uses a client-sent value. For example `header_up X-Real-IP {remote_host}` in Caddy's `reverse_proxy`, `RequestHeader set X-Real-IP "expr=%{REMOTE_ADDR}"` in Apache or `http-request set-header X-Real-IP %[src]` in HAProxy. To log the client port, also set `X-Real-Port`, for example `proxy_set_header X-Real-Port $remote_port;` in nginx. ### Use a sub-path diff --git a/i18n/zh-cn/docs/current/administration/config-cheat-sheet.md b/i18n/zh-cn/docs/current/administration/config-cheat-sheet.md index 89aa7487..0af01319 100644 --- a/i18n/zh-cn/docs/current/administration/config-cheat-sheet.md +++ b/i18n/zh-cn/docs/current/administration/config-cheat-sheet.md @@ -524,7 +524,8 @@ Gitea 创建以下非唯一队列： - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理认证的 HTTP 头部名称，用于提供用户信息。 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理认证的 HTTP 头部名称，用于提供邮箱信息。 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: 反向代理认证的 HTTP 头部名称，用于提供全名信息。 -- `REVERSE_PROXY_LIMIT`: **1**: 解释 X-Forwarded-For 标头或 X-Real-IP 标头，并将其设置为请求的远程 IP。 +- `REVERSE_PROXY_LIMIT`: **1**: 按顺序解释 X-Real-IP、X-Forwarded-For 或 Forwarded 标头，并将其设置为请求的远程 IP。 + 客户端端口取自标头值，或在使用 X-Real-IP 时取自 X-Real-Port。 可信代理计数。设置为零以不使用这些标头。 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: 逗号分隔的受信任代理服务器的 IP 地址和网络列表。使用 `*` 来信任全部。 - `DISABLE_GIT_HOOKS`: **true**: 设置为 `false` 以允许具有 Git 钩子权限的用户创建自定义 Git 钩子。 diff --git a/i18n/zh-tw/docs/current/administration/config-cheat-sheet.md b/i18n/zh-tw/docs/current/administration/config-cheat-sheet.md index 3196edd3..3223a169 100644 --- a/i18n/zh-tw/docs/current/administration/config-cheat-sheet.md +++ b/i18n/zh-tw/docs/current/administration/config-cheat-sheet.md @@ -529,7 +529,8 @@ Gitea 建立以下非唯一隊列： - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理認證的 HTTP 頭部名稱，用於提供使用者資訊。 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理認證的 HTTP 頭部名稱，用於提供郵箱資訊。 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: 反向代理認證的 HTTP 頭部名稱，用於提供全名資訊。 -- `REVERSE_PROXY_LIMIT`: **1**: 解釋 X-Forwarded-For 標頭或 X-Real-IP 標頭，並將其設定為請求的遠程 IP。 +- `REVERSE_PROXY_LIMIT`: **1**: 依序解釋 X-Real-IP、X-Forwarded-For 或 Forwarded 標頭，並將其設定為請求的遠程 IP。 + 客戶端連接埠取自標頭值，或在使用 X-Real-IP 時取自 X-Real-Port。 可信代理計數。設定為零以不使用這些標頭。 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: 逗號分隔的受信任代理伺服器的 IP 地址和網路列表。使用 `*` 來信任全部。 - `DISABLE_GIT_HOOKS`: **true**: 設定為 `false` 以允許具有 Git 鉤子權限的使用者建立自訂 Git 鉤子。