docs: document egress modes and host lists (#557)

Documents the settings changed by https://github.com/go-gitea/gitea/pull/39426: `EGRESS_MODE`, the `[migrations]` `ALLOWED_HOST_LIST`/`BLOCKED_HOST_LIST` replacing `ALLOWED_DOMAINS`, `BLOCKED_DOMAINS` and `ALLOW_LOCALNETWORKS`, and the host list syntax with ports, CGNAT and reserved addresses. Also fixes the `socks://` examples, Go only speaks `socks5://`.

_Written by Claude._

---------

Co-authored-by: Lunny Xiao <[email protected]>
Co-authored-by: TheFox0x7 <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/557
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>
This commit is contained in:
authored and silverwind committed 2026-09-30 11:42:29 +00:00
1 parent c28356267d
commit 6934d56056
6 files changed
+92 -68

No files matched your search

@@ -681,17 +681,16 @@ Gitea 创建以下非唯一队列:
- `QUEUE_LENGTH`: **1000**: 钩子任务队列长度。编辑此值时要小心。
- `DELIVER_TIMEOUT`: **5**: 发送 Webhook 的交付超时时间(秒)。
- `ALLOWED_HOST_LIST`: **external**: 出于安全原因,Webhook 仅能调用允许的主机。以逗号分隔的列表。
- `ALLOWED_HOST_LIST`: **_empty_**: 出于安全原因,Webhook 仅能调用允许的主机。以逗号分隔的列表。在默认的 `[security]` `EGRESS_MODE = lax` 下仅限制私有地址。
- 内置网络:
- `loopback`:IPv4 的 127.0.0.0/8 和 IPv6 的 ::1/128,包括 localhost。
- `private`:RFC 1918(10.0.0.0/8,172.16.0.0/12,192.168.0.0/16)和 RFC 4193(FC00::/7)。也称为 LAN/Intranet。
- `external`:一个有效的非私有单播 IP,您可以访问公共互联网上的所有主机。
- `*`:允许所有主机。
- `private`:RFC 1918(10.0.0.0/8,172.16.0.0/12,192.168.0.0/16)、RFC 4193(FC00::/7)和 RFC 6598 CGNAT(100.64.0.0/10)。也称为 LAN/Intranet。
- CIDR 列表:IPv4 的 `1.2.3.0/8` 和 IPv6 的 `2001:db8::/32`
- 通配符主机:`*.mydomain.com`,`192.168.100.*`
- 通配符主机:`*.mydomain.com`
- 链路本地和云元数据等保留地址会被拒绝。
- `SKIP_TLS_VERIFY`: **false**: 允许不安全的证书。
- `PAGING_NUM`: **10**: 一页中显示的 Webhook 历史事件数量。
- `PROXY_URL`: **_empty_**: 代理服务器 URL,支持 http://、https://、socks://,留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供,将使用全局代理设置。
- `PROXY_URL`: **_empty_**: 代理服务器 URL,支持 http://、https://、socks5://,留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供,将使用全局代理设置。
- `PROXY_HOSTS`: **_empty_**: 需要代理的主机名的逗号分隔列表。支持通配符模式 (\*);使用 \*\* 来匹配所有主机。如果未提供,将使用全局代理设置。
## 邮件 (`mailer`)
@@ -1277,9 +1276,8 @@ ALLOW_DATA_URI_IMAGES = true
- `MAX_ATTEMPTS`:**3**: 每次 http/https 请求的最大尝试次数(用于迁移)。
- `RETRY_BACKOFF`:**3**: 每次 http/https 请求重试的退避时间(秒)。
- `ALLOWED_DOMAINS`:**_empty_**: 允许迁移仓库的域名允许列表,默认为空。这意味着允许外部网址。多个域名可以用逗号分隔。支持通配符:`github.com, *.github.com`。
- `BLOCKED_DOMAINS`:**_empty_**: 阻止迁移仓库的域名阻止列表,默认为空。多个域名可以用逗号分隔。当 `ALLOWED_DOMAINS` 不为空时,此选项优先级较高,用于拒绝域名。支持通配符。
- `ALLOW_LOCALNETWORKS`:**false**: 允许 RFC 1918、RFC 1122、RFC 4632 和 RFC 4291 中定义的私有地址。如果域名被 `ALLOWED_DOMAINS` 允许,此选项将被忽略。
- `ALLOWED_HOST_LIST`:**_empty_**: 迁移和镜像可以访问的主机,格式与 `[security]` 的 `ALLOWED_HOST_LIST` 相同。私有和回环地址需要内置或 CIDR 条目。取代已弃用的 `ALLOWED_DOMAINS` 和 `ALLOW_LOCALNETWORKS`。
- `BLOCKED_HOST_LIST`:**_empty_**: 迁移和镜像禁止访问的主机。取代已弃用的 `BLOCKED_DOMAINS`。
- `SKIP_TLS_VERIFY`:**false**: 允许跳过 TLS 验证。
## 联邦(`federation`)
@@ -1509,14 +1507,14 @@ MINIO_BUCKET_LOOKUP_TYPE = auto
## 代理 (`proxy`)
- `PROXY_ENABLED`: **false**: 启用代理,如果为 true,所有通过 HTTP 向外部的请求都将受到影响,如果为 false,即使环境设置了 http_proxy/https_proxy 也不会使用
- `PROXY_URL`: **_empty_**: 代理服务器地址,支持 http://, https//, socks://,为空则不启用代理而使用环境变量中的 http_proxy/https_proxy
- `PROXY_URL`: **_empty_**: 代理服务器地址,支持 http://, https://, socks5://,为空则不启用代理而使用环境变量中的 http_proxy/https_proxy
- `PROXY_HOSTS`: **_empty_**: 逗号分隔的多个需要代理的网址,支持 \* 号匹配符号, \*\* 表示匹配所有网站
i.e.
```ini
PROXY_ENABLED = true
PROXY_URL = socks://127.0.0.1:1080
PROXY_URL = socks5://127.0.0.1:1080
PROXY_HOSTS = *.github.com
```