docs: document real IP header modes

README.md

@@ -144,7 +144,7 @@ Compose 在 `environment` 中显式列出了全部配置，不依赖 `.env` 文
 | --- | --- | --- |
 | `MUSIC_PASSWORD` | 空 | 单密码认证；空值关闭认证 |
 | `MUSIC_ALLOWED_HOSTS` | `localhost,127.0.0.1,::1` | 接受的 HTTP Host |
-| `MUSIC_REAL_IP_HEADER` | `remote` | 登录封禁使用的客户端 IP 来源 |
+| `MUSIC_REAL_IP_HEADER` | `remote` | 登录失败限流使用的客户端 IP 来源；支持 `remote`、`x-forwarded-for`、`cf-connecting-ip` |
 | `MUSIC_TRUSTED_PROXY_SUBNETS` | 空 | 有权提供真实 IP 的代理网段 |
 | `MUSIC_FFMPEG_MAX_SESSIONS` | `2` | FFmpeg 与 ffprobe 总并发 |
 | `MUSIC_MEDIA_AUX_RESERVED_SESSIONS` | `1` | 专供 metadata/封面的辅助进程槽；必须小于总并发 |
@@ -163,6 +163,31 @@ Compose 在 `environment` 中显式列出了全部配置，不依赖 `.env` 文
 | `MUSIC_OPUS_BITRATE` | `160` | Opus 转码码率，单位 kbps |
 | `MUSIC_BOLTDB_PATH` | `/data/tags.db` | 标签数据库路径 |
 
+### 客户端 IP 来源
+
+`MUSIC_REAL_IP_HEADER` 决定登录失败应归属于哪个客户端 IP：
+
+- `remote`（默认）：始终使用 TCP 直连对端，忽略所有真实 IP
+  头。直连部署或不能确认代理行为时使用。
+- `x-forwarded-for`：仅当 TCP 对端命中
+  `MUSIC_TRUSTED_PROXY_SUBNETS` 时读取 `X-Forwarded-For`，从右向左
+  剥离可信代理地址，并使用第一个不可信地址。
+- `cf-connecting-ip`：仅当 TCP 对端可信时读取唯一且合法的
+  `CF-Connecting-IP`，适合正确配置的 Cloudflare Tunnel。
+
+后两种模式遇到不可信对端、空可信代理列表、缺失或非法头部时，都会
+安全回退到 TCP 直连对端。例如：
+
+```yaml
+environment:
+  MUSIC_REAL_IP_HEADER: "x-forwarded-for"
+  MUSIC_TRUSTED_PROXY_SUBNETS: "REPLACE_WITH_ACTUAL_PROXY_CIDR"
+```
+
+只应信任 ShuffleMuse 实际看到的代理来源网段。不要把代理或 Docker
+网桥加入 `MUSIC_AUTH_WHITELIST_SUBNETS`：认证白名单始终按 TCP
+直连对端判断，加入代理会让所有经该代理到达的用户免登录。
+
 所有变量、默认值、校验规则和代理配置见[配置与安全](docs/CONFIGURATION.md)。
 
 ## 本地开发