Merge branch 'develop' into main

将 develop 分支累积的 51 个提交合入 main,涵盖完整的架构重构与
可观测性建设,作为下一阶段对外发布的稳定基线。

## 主要变更

### 架构重构
- 将单体 tts_server.go (778 行) 拆分为模块化目录:adapter/volcano、
  controller、dto、middleware、router、setting、telemetry、metrics
- 引入 OpenAI /v1/audio/speech 兼容接口,火山引擎作为后端适配器
- 统一以 main.go 作为入口,集中启动顺序与信号处理

### 火山 TTS 适配器
- 重构请求/响应/合成为独立文件 (request.go / response.go /
  synthesis.go / audio.go),namespace 修正为 UnidirectionalTTS
- 适配 v3 模型参数与音色复刻路由
- 兼容上游 sentence 字段对象/字符串两种形态,处理 event 字段缺失
- 新增请求诊断日志,便于排障

### 可观测性
- 自研轻量 telemetry 库 (counter/gauge/histogram/labels/registry)
- 暴露 Prometheus 格式指标,内置 /metrics 端点
- 限流与并发中间件仅统计 /v1/ 路由,避免监控路径污染计数
- 新增 health.html 监控面板,分组展示请求、延迟、限流、字节数等

### 中间件
- CORS:支持 ALLOWED_ORIGINS 白名单,日志优化
- 限流:令牌桶 + 并发控制,带可观测埋点
- 安全/鉴权:API Key 校验、请求体大小限制
- Logger:统一请求日志,修复中文乱码与换行

### 配置与启动
- setting/config.go 集中环境变量管理,启动时打印配置摘要
- 配置文件切换到 .env.example,支持音频格式/采样率/调试日志开关

### 文档与构建
- README 重写,补充 BYTEDANCE_TTS_DEBUG 调试日志小节,移除 1.0 旧内容
- Go 版本升级 1.23 -> 1.26
- 新增 Dockerfile / docker-compose.yml,镜像构建与编排
- 补充 .dockerignore / .gitignore,清理 BOM 头与废弃 tts-api.exe

### 修复
- 修复 response.go switch 大括号结构错误、synthesis.go 类型不匹配
- 修复请求体过大时的处理、冗余代码与日志乱码
- 限流/并发中间件跳过非 /v1/ 路由,避免监控路径污染计数

.dockerignore

@@ -1,8 +1,7 @@
 *.exe
 *.md
 .env
-.env.*
+.env.example
-!.env.example
 .git
 .gitignore
 tts_api_architecture.html

.env.example

@@ -51,17 +51,6 @@ BYTEDANCE_TTS_SAMPLE_RATE=24000
 # OpenAI兼容接口的API密钥(可选,多个用逗号分隔)
 OPENAI_TTS_API_KEY=your_openai_compatible_key_here
 
-# 反代拓扑配置(0-10)。控制 X-Forwarded-For 解析方式,影响 IP 限流的 key。
-# 不设置 / 0:启发式模式(默认)—— 从 XFF 链尾扫描,跳过私有 IP,返回第一个公网 IP
-#             适合 90% 部署(单跳/多跳/直出),无需了解精确跳数
-# N (N>0)  :精确模式 —— 精准到真实 client IP,需要正确配置跳数
-#             N=1:单跳反代(client → nginx → 本服务)
-#             N=2:双跳反代(client → CDN → nginx → 本服务,如 Cloudflare + nginx)
-#             N=3:三跳,以此类推
-# 直出部署(无反代):无需配置,XFF 分支不会执行
-# 详见 README "反代拓扑与 X-Forwarded-For 解析"章节
-# TRUSTED_PROXY_HOPS=
-
 # CORS 跨域白名单(逗号分隔;开发环境可设 *;空则拒绝所有跨域)
 # ALLOWED_ORIGINS=https://example.com,https://app.example.com
 

.gitignore

@@ -1,4 +1,4 @@
-# Go build cache
+# Go build cache
 .gocache/
 *.exe
 *.test
@@ -11,12 +11,4 @@
 Thumbs.db
 
 # Logs
-*.log
+*.log
-
-# Secrets (do NOT commit local .env files; keep .env.example tracked as template)
-.env
-.env.*
-!.env.example
-
-# Local-only working notes (use task board for shared tracking)
-TODO.md

README.md

@@ -80,86 +80,9 @@ tts-api.exe
 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
 | `OPENAI_TTS_API_KEY` | OpenAI 兼容接口的 API Key(逗号分隔支持多个) | 无(不鉴权) |
-| `TRUSTED_PROXY_HOPS` | X-Forwarded-For 解析模式(0=启发式/默认,>0=精确 N 跳) | `0`(启发式) |
 | `PORT` | 服务监听端口 | `8080` |
 | `ALLOWED_ORIGINS` | CORS 跨域白名单(逗号分隔,调试可设 `*`;空则拒绝所有跨域) | 无 |
 
-### 反代拓扑与 X-Forwarded-For 解析
-
-当服务部署在反代(nginx / caddy / CDN)后面时,反代会通过 `X-Forwarded-For`(XFF)头传递真实客户端 IP。本服务通过 `TRUSTED_PROXY_HOPS` 环境变量控制 XFF 解析方式,支持两种模式。
-
-#### 何时需要关心这个配置
-
-| 部署方式 | 是否需要配置 |
-|---|---|
-| 服务直接暴露公网 IP(无反代)| ❌ 不适用,跳过本节 |
-| 服务前有 1 个反代(nginx / caddy)| ❌ 不必配置,启发式模式自动处理 |
-| 服务前有 2 跳以上反代(CDN + 自建反代)| ⚠️ 启发式模式"够用",需要精准按真实 client 限流时再设 |
-
-> **直出部署(无反代)的用户**:本节不适用,跳过阅读。`TRUSTED_PROXY_HOPS` 在你的部署下不会被读取。
-
-#### 启发式模式(默认 / `TRUSTED_PROXY_HOPS=0`)
-
-从 XFF 链尾向前扫描,**跳过私有 IP,返回第一个公网 IP**。
-
-适用场景:单跳反代(最常见)、多跳含公网代理(CDN + nginx)。
-
-**行为示例**:
-
-| XFF 链 | 启发式返回 | 备注 |
-|---|---|---|
-| `1.2.3.4` | `1.2.3.4` | 单跳,真实 client |
-| `fake, 1.2.3.4` | `1.2.3.4` | 攻击者伪造首值,跳过 fake |
-| `1.2.3.4, 5.6.7.8, 10.0.0.1` | `5.6.7.8` | 多跳,返回最末公网 IP(CDN 边缘) |
-| `1.2.3.4, 192.168.1.1` | `1.2.3.4` | 链尾是私有 IP,跳过 |
-
-**优点**:零配置,大多数部署自动正确。
-
-**限制**:多跳 CDN 场景下,限流粒度为"按 CDN 边缘 IP"而非"按真实 client"。攻击者填满某 CDN 边缘配额可能影响该 CDN 下的其他用户——但无法伪造身份、无法越权。
-
-#### 精确模式(`TRUSTED_PROXY_HOPS=N`,N > 0)
-
-从 XFF 链尾倒数第 N+1 个位置取值,即"信任最近 N 跳反代,取该信任链之前那一跳的 IP"。
-
-适用场景:多跳 CDN + 反代,且需要精准按真实 client 限流。
-
-**N 的确定方法**:统计客户端到本服务之间的反代跳数。
-
-| 拓扑 | 跳数 | 配置 |
-|---|---|---|
-| `client → nginx → 本服务` | 1 | `TRUSTED_PROXY_HOPS=1` |
-| `client → Cloudflare → nginx → 本服务` | 2 | `TRUSTED_PROXY_HOPS=2` |
-| `client → CDN → WAF → nginx → 本服务` | 3 | `TRUSTED_PROXY_HOPS=3` |
-
-**行为对比**(以 `client(1.2.3.4) → CDN(203.0.113.5) → nginx(10.0.0.1) → 本服务` 为例,XFF 链 = `1.2.3.4, 203.0.113.5`):
-
-| `TRUSTED_PROXY_HOPS` | 返回 | 评价 |
-|---|---|---|
-| 0(默认启发式)| `203.0.113.5` | CDN 边缘 IP,限流粒度粗 |
-| 1(数到 nginx,未穿透)| `203.0.113.5` | 配置不当,与默认相同 |
-| 2(穿透到真实 client)| `1.2.3.4` | 精准到真实 client ✓ |
-| 3(超出实际跳数)| `directIP`(链长不足保护)| 配置错误,需修正 |
-
-#### 为什么两种模式都从链尾扫描
-
-XFF 链的第一个值是**客户端可控**的:攻击者可以发送任意 `X-Forwarded-For: 1.2.3.4`,若反代用追加模式(如 nginx 默认的 `$proxy_add_x_forwarded_for`),链尾才会追加真实 IP。
-
-若代码取首值,攻击者每次换伪造 IP 即可绕过 IP 限流,也可伪装成受害 IP 把其配额耗尽(间接 DoS)。两种模式都从链尾扫描,天然免疫这种攻击。
-
-#### 验证当前模式
-
-启动期日志会显示当前模式:
-
-```
-TRUSTED_PROXY_HOPS 未设置,使用默认启发式模式(XFF 链尾第一个公网 IP)
-# 或
-已配置 TRUSTED_PROXY_HOPS=0(启发式模式,等同默认)
-# 或
-已配置 TRUSTED_PROXY_HOPS=2(精确模式,信任 2 跳反代)
-```
-
-也可在 `GetClientIP` 临时加 `log.Printf` 打印解析结果,或写一个 Go 测试用例(参见 DEBT-1 单元测试任务)来覆盖不同 XFF 链场景。生产环境不要保留 debug 日志。
-
 ### Resource ID 说明
 
 | Resource ID | 模型说明 |

VULNERABILITY_REPORT.md

@@ -1,197 +0,0 @@
-# 漏洞报告 — Volcano-Engine-TTS-UI
-
-## 元信息
-
-| 项目 | 内容 |
-|---|---|
-| 目标 | ByteDance TTS v3 → OpenAI 兼容接口适配器(Go) |
-| 审查范围 | 全部 12 个包、约 2400 行源码(不含 health.html 前端静态页) |
-| 审查方式 | 人工代码审查 + `go build` / `go vet`(均通过) |
-| 分支/提交 | develop @ 78c7200 |
-| 报告日期 | 2026 年 8 月 25 日  |
-| 严重度分级 | 🔴 高(必须修复)/ 🟠 中(建议修复)/ 🟡 低(视部署环境)/ ⚪ 信息(记录备查) |
-
----
-
-## 漏洞清单(按严重度)
-
-| 编号 | 严重度 | 标题 | 位置 | 一句话影响 |
-|---|---|---|---|---|
-| VUL-004 | 🔴 高 | `.env` 未被 `.gitignore` 忽略,凭据可能入库/入镜像 | `.gitignore` | API Key 随 git 提交或 Docker 镜像层泄露 |
-| VUL-001 | 🟠 中 | aac/flac 响应 Content-Type 与数据不一致 | controller/tts.go、adapter/volcano/synthesis.go | 客户端按 AAC 解码 MP3 数据,播放失败 |
-| VUL-003 | 🟠 中 | `X-Forwarded-For` 信任链可伪造 IP 绕过限流 | middleware/ratelimit.go | 反代追加模式下限流失效 |
-| VUL-002 | 🟡 低 | transport 层错误不进入 `UpstreamErrors` 指标 | metrics/metrics.go、adapter/volcano/synthesis.go | 网络故障在监控上不可见 |
-| VUL-005 | 🟡 低 | 日志注入:客户端可控内容原样写入日志 | middleware/logger.go、controller/tts.go | 可伪造日志行 |
-| VUL-006 | 🟡 低 | `/metrics`、`/health`、`/dashboard` 无鉴权 | router/router.go | 公网暴露时泄漏运行细节(设计权衡) |
-| VUL-007 | 🟡 低 | `OPENAI_TTS_API_KEY` 未设置时鉴权完全关闭 | middleware/auth.go | 公网直连即无访问控制(设计权衡) |
-| VUL-008 | ⚪ 信息 | speed 超范围静默截断 | adapter/volcano/request.go | 0.25~0.5x、2.0~4.0x 实际被 clamp,无提示 |
-| VUL-009 | ⚪ 信息 | WAV 输出采样率依赖配置而非上游实际值 | adapter/volcano/audio.go | 配置错误导致音频变速 |
-
----
-
-## VUL-004 🔴 高 — `.env` 未被忽略,凭据可能入库/入镜像
-
-**位置**: `.gitignore`(全文件仅忽略构建产物与编辑器文件)
-
-**描述**: README 与 `.env.example` 均指导用户执行 `cp .env.example .env` 后填入火山 API Key。但 `.gitignore` **没有包含 `.env`**。任何按此流程操作并执行 `git add .` / `git commit` 的用户,都会把含 `BYTEDANCE_TTS_API_KEY`、`OPENAI_TTS_API_KEY` 的文件提交进仓库历史(即使之后删除,历史中仍可找回)。Dockerfile 第 8 行 `COPY . .` 同样会把 `.env` 拷入镜像层。
-
-**影响**: 火山账号 API Key 泄露 → 冒用额度、产生费用、音色资源被盗用。密钥一旦进入 git 历史或镜像层即视为已泄露,只能吊销重建。
-
-**修复建议**:
-```gitignore
-# Secrets
-.env
-.env.*
-!.env.example
-```
-
-**验证**: 当前工作区无 `.env` 文件,仓库历史也未发现已提交的 `.env`(已核查 `git log` 提交列表无该文件),属"配置隐患"而非"已泄露"。
-
----
-
-## VUL-001 🟠 中 — aac/flac 响应 Content-Type 与真实数据不一致
-
-**位置**: controller/tts.go:196-212(`contentTypeFor`)、adapter/volcano/synthesis.go:59-63、118-119
-
-**描述**: 客户端请求 `response_format: "aac"`(或 `flac`)时,调用链为:
-
-```
-resolveClientFormat("aac") → "aac"(白名单放行)
-synthesis: opts.Format = "mp3"(上游降级,正确)
-synthesis: finalFormat = clientFormat = "aac"(错误,保留客户端格式)
-controller: Content-Type = contentTypeFor("aac") = "audio/aac"(错误)
-```
-
-实际响应字节是 **MP3**,但 `Content-Type` 是 `audio/aac`。
-
-**影响**: 客户端(浏览器 `<audio>`、播放器 SDK)按 AAC 解码器处理 MP3 流,轻则播放失败/杂音,重则解码崩溃。README 声称"降级到 mp3",但响应头未同步降级。
-
-**修复建议**(二选一):
-1. `synthesis.go` 在降级后把 `finalFormat` 置为实际上游格式(`mp3`);
-2. `contentTypeFor` 对 `aac`/`flac` 直接返回 `audio/mpeg`。
-
-推荐方案 1(响应头应反映真实数据)。
-
----
-
-## VUL-003 🟠 中 — X-Forwarded-For 信任链可伪造 IP 绕过限流
-
-**位置**: middleware/ratelimit.go:129-150(`GetClientIP`)
-
-**描述**: `GetClientIP` 在直连 IP 为私有地址(即判定为反代)时,信任 `X-Forwarded-For` 的**第一个**值,其次信任 `X-Real-IP`。若反代(nginx 等)使用追加模式(`$proxy_add_x_forwarded_for`),攻击者发送 `X-Forwarded-For: 1.2.3.4`,反代追加真实 IP 后请求头为 `1.2.3.4, 真实IP`,代码取 `1.2.3.4`。
-
-**影响**:
-- 攻击者每次请求携带不同伪造 IP,即可绕过 100 次/分钟的 IP 限流(限流 key 由该函数返回值决定);
-- 可伪装成受害 IP 请求,把受害 IP 的限流配额耗尽(间接 DoS)。
-
-**前提**: 服务必须部署在反代之后(反代 IP 为私有)。直接公网直连时直连 IP 非私有,不走信任分支,不受影响。
-
-**修复建议**(任一):
-1. 反代配置覆盖而非追加:`proxy_set_header X-Forwarded-For $remote_addr`;
-2. 代码改取 `XFF` **最后一个**值(追加模式下最后一个为真实来源);
-3. 部署时用 `X-Real-IP` 且确保反代覆盖该头,代码优先信任 `X-Real-IP`。
-
----
-
-## VUL-002 🟡 低 — transport 层错误不进入 UpstreamErrors 指标
-
-**位置**: metrics/metrics.go:134-136、adapter/volcano/synthesis.go:90-92、112
-
-**描述**: `UpstreamFinished` 中 `if errCode != 0 { UpstreamErrors.Inc(...) }`。传输错误(连接失败、DNS 失败、读流失败)时调用方传入的 `errCode` 均为 0:
-
-- `client.PostStream` 失败 → `UpstreamFinished(..., 0)` → 不计
-- `ParseStream` 读流错误 → `UpstreamError{Code: 0}` → 不计
-
-而 `codeLabel`(metrics/metrics.go:148-158)明确设计了 `code == 0 → "transport"` 分类,**该分类永远不会被触发**。
-
-**影响**: 上游网络故障时 `tts_upstream_errors_total` 不增长,`/metrics` 与监控面板无法发现"火山接口连不上"类故障,只能从日志人工发现。
-
-**修复建议**: 将 transport 错误单独计数,例如 `if errCode != 0 || status == "transport_error" { UpstreamErrors.Inc(Labels{"code": codeLabel(errCode)}) }`。
-
----
-
-## VUL-005 🟡 低 — 日志注入
-
-**位置**: middleware/logger.go:26、adapter/volcano/synthesis.go:100(`Message` 拼入上游响应体)
-
-**描述**: 访问日志直接拼接 `r.RequestURI`(客户端可控,URL 中可含 `\n`/`\r`);上游非 200 响应体 `rawBody` 拼入错误日志。Go `log` 不做转义,原样输出。
-
-**影响**: 攻击者可在请求 URL 中注入换行符,伪造服务端日志行(如伪造"合成成功"记录、注入误导信息),干扰排障;无代码执行风险。
-
-**修复建议**(低优先): 对 RequestURI 做换行转义(`strings.NewReplacer("\n", "\\n", "\r", "\\r")`)。
-
----
-
-## VUL-006 🟡 低 — 监控端点无鉴权(设计权衡)
-
-**位置**: router/router.go:21-31
-
-**描述**: `/health`、`/metrics`、`/dashboard` 均不鉴权(README 明示,与 Prometheus 抓取场景对齐)。
-
-**影响**: 若公网直接暴露,任何人可查看 `/metrics`(含 speaker/model/format 业务标签、请求计数、上游错误聚合)与 `/dashboard`(运行状态、配置检查结果)。不涉及凭据,但为侦察提供信息。
-
-**判定**: 属于明确的设计决策,个人/内网使用可接受;公网部署建议通过反代鉴权(如 basic auth)保护 `/metrics`。
-
----
-
-## VUL-007 🟡 低 — 未配置 OPENAI_TTS_API_KEY 时鉴权完全关闭
-
-**位置**: middleware/auth.go:20-22、setting/config.go:64-79
-
-**描述**: `ValidateAPIKey` 在 `setting.Auth.APIKeys` 为空时直接返回 `true`(全部放行)。该变量仅在 `OPENAI_TTS_API_KEY` 设置后才会填充。
-
-**影响**: 公网直接暴露且未配置该环境变量时,任何人均可无限制调用 TTS 合成,消耗火山额度。
-
-**判定**: 属设计行为(内网可信),README 已有说明。公网部署必须配置该变量,或由反代承担鉴权。
-
----
-
-## VUL-008 ⚪ 信息 — speed 超范围静默截断
-
-**位置**: adapter/volcano/request.go:89-101、controller/tts.go:132-141
-
-**描述**: README 声明 `speed` 支持 0.25~4.0;controller 按此范围 clamp,但火山 `speech_rate` 仅支持 [-50, 100](即 0.5x~2.0x)。`0.25~0.5x` 与 `2.0~4.0x` 区间会被二次 clamp 截断,且无任何客户端提示。
-
-**影响**: 用户请求 0.25x 实际得到 0.5x 语速,表现与预期不符。
-
-**修复建议**: README 修正文档范围,或对超范围请求返回 400 而非静默截断。
-
----
-
-## VUL-009 ⚪ 信息 — WAV 采样率依赖配置而非上游实际值
-
-**位置**: adapter/volcano/audio.go:32-39、controller/tts.go:121
-
-**描述**: `WrapWAVHeader` 使用 `opts.SampleRate`(环境变量 `BYTEDANCE_TTS_SAMPLE_RATE`,默认 24000)写 WAV 头。若上游实际返回的 PCM 采样率与配置不一致(配置错误或上游忽略该参数),WAV 头与数据不匹配。
-
-**影响**: 音频以错误速率播放(变速/变调)。
-
-**判定**: 正常配置下无影响;配置异常时表现为"音频怪声",README 第 3 条已有排查指引。
-
----
-
-## 安全加固建议(非漏洞)
-
-1. **Docker 环境变量**: compose 中密钥通过 `environment` 明文传递,进程环境可见(`/proc/<pid>/environ`)。生产可改用 Docker Secrets 或启动时注入。
-2. **TLS**: 当前 HTTP 明文,建议生产经反代(nginx/caddy)终结 TLS,或服务前挂证书。
-3. **依赖固定**: go.mod 仅锁定 `gorilla/mux v1.8.1`(2018 年发布),建议 `go get -u` 检查是否存在已知 CVE 的新版本,或至少 `go mod verify`。
-
-## 工程债务(非安全,记录备查)
-
-| 项目 | 说明 |
-|---|---|
-| 零单元测试 | 全部 12 个包无 `_test.go`;流解析(曾有 4 次 bug 修复)、WAV 拼头、speech_rate 转换、限流窗口、Prometheus 转义均无自动化回归保护 |
-| 死代码 | `ratelimit_middleware.go` 整文件未引用;`auth.go:InitAPIKeys`、`cors.go:InitCORSConfig` 为未被调用的 no-op;`dto.ByteDanceTTSConfig` + `setting/config.go:311` 占位引用 |
-| 冗余代码 | `resolveClientFormat`(controller/tts.go:49-52)两分支同值;`common.MaxResponseTimes`/`MaxErrors` 常量未使用 |
-| 云盘占用 | 注释表明 `ratelimit_middleware.go` 因"云盘同步被永久占用"无法删除,仓库位于云盘目录,git 操作与文件删除存在异常风险 |
-
-## 已核查无风险项
-
-- ✅ API Key 比较使用 `subtle.ConstantTimeCompare`,无时序侧信道
-- ✅ 启动日志与 `/health` 对 API Key 脱敏(`maskAPIKey`)
-- ✅ 请求体上限 1MB、文本上限 5000 字、model 名长度/字符校验
-- ✅ 并发信号量 + IP 限流仅对 `/v1/` 生效,监控路径豁免;CORS 预检不消耗配额
-- ✅ telemetry label key 注册时锁定,当前 cardinality 可控(无客户端可控高基数标签)
-- ✅ 上游连接池复用、超时(30s)与 context 取消正确传播
-- ✅ 优雅退出(SIGINT/SIGTERM → 5s 内 Shutdown)
-- ✅ 无 `_test.go` 之外的明显并发竞态:全局配置启动期写入后只读,共享状态均有锁

adapter/volcano/synthesis.go

@@ -116,14 +116,7 @@ func Synthesis(
 	duration := time.Since(started)
 
 	finalData := parsed.AudioData
-	// finalFormat 反映真实输出格式(用于 controller 写 Content-Type):
-	//   - wav 走 pcm 上游 + 本地拼头,对外仍是 wav
-	//   - aac/flac 在上方已被上游降级为 mp3,真实输出也是 mp3
-	//   - 其余与 clientFormat 一致
 	finalFormat := clientFormat
-	if clientFormat != "wav" {
-		finalFormat = opts.Format
-	}
 	sampleRate := opts.SampleRate
 	if clientFormat == "wav" {
 		wav, wrapErr := WrapWAVHeader(parsed.AudioData, opts.SampleRate)

middleware/ratelimit.go

@@ -4,15 +4,12 @@ import (
 	"log"
 	"net"
 	"net/http"
-	"os"
-	"strconv"
 	"strings"
 	"sync"
 	"time"
 
 	"github.com/volcano-tts/tts-api/common"
 	"github.com/volcano-tts/tts-api/metrics"
-	"github.com/volcano-tts/tts-api/setting"
 )
 
 type RateLimiter struct {
@@ -26,57 +23,15 @@ type RateLimiter struct {
 var (
 	GlobalRateLimiter *RateLimiter
 	ConcurrencySem    chan struct{}
-	// trustedProxyHops controls how X-Forwarded-For (XFF) is parsed when the
-	// direct connection comes from a private IP (i.e., we're behind a reverse
-	// proxy). Two modes are supported, switched by this single value:
-	//
-	//   HEURISTIC MODE (trustedProxyHops == 0, the default):
-	//     Walk XFF from the end, return the first PUBLIC IP. Skips private
-	//     and loopback hops automatically. Works for ~90% of deployments
-	//     without the operator needing to know the exact number of proxy
-	//     hops. Trade-off in multi-hop: rate limiting is per-CDN-edge rather
-	//     than per-real-client, which is "good enough" for abuse protection
-	//     but not for fine-grained per-user quotas.
-	//
-	//   PRECISE MODE (trustedProxyHops > 0):
-	//     Count back N hops from the end of XFF and return that value. Gives
-	//     precise per-real-client rate limiting even in multi-hop setups
-	//     (e.g., Cloudflare + nginx). Operator MUST set this to the number
-	//     of trusted reverse proxies between this service and the client.
-	//
-	// Both modes walk from the END of the XFF chain. The first value is
-	// client-controllable; trusting it would let attackers bypass IP rate
-	// limiting by sending a forged X-Forwarded-For header.
-	trustedProxyHops = 0
 )
 
 func InitRateLimiter() {
-	switch v := os.Getenv("TRUSTED_PROXY_HOPS"); {
-	case v == "":
-		log.Printf("TRUSTED_PROXY_HOPS 未设置,使用默认启发式模式(XFF 链尾第一个公网 IP)")
-	default:
-		n, err := strconv.Atoi(v)
-		switch {
-		case err != nil || n < 0 || n > 10:
-			log.Printf("警告: TRUSTED_PROXY_HOPS=%q 无效(需 0-10 的整数),回退到默认启发式模式", v)
-		case n == 0:
-			// "0" 或 "00" 等被 Atoi 解析为 0 的形式都归到启发式模式,
-			// 避免日志出现"精确模式, 信任 0 跳"这种自相矛盾的输出。
-			log.Printf("已配置 TRUSTED_PROXY_HOPS=%d(启发式模式,等同默认)", n)
-		default:
-			trustedProxyHops = n
-			log.Printf("已配置 TRUSTED_PROXY_HOPS=%d(精确模式,信任 %d 跳反代)", n, n)
-		}
-	}
 	GlobalRateLimiter = &RateLimiter{
 		requests: make(map[string][]time.Time),
 		limit:    common.RateLimitRequests,
 		window:   common.RateLimitWindow,
 	}
 	ConcurrencySem = make(chan struct{}, common.MaxConcurrentRequests)
-
-	// 同步到 setting 包,供 LogStartupSummary 展示
-	setting.TrustedProxyHops = trustedProxyHops
 }
 
 func (rl *RateLimiter) Allow(key string) bool {
@@ -178,37 +133,10 @@ func GetClientIP(r *http.Request) string {
 	}
 
 	if isPrivateIP(directIP) {
-		// Parse X-Forwarded-For when there's a reverse proxy in front (direct
-		// connection is from a private IP). Both modes walk from the END of
-		// the chain so that the client-controllable first value cannot be
-		// used to spoof a different client IP for rate limit bypass.
 		if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
-			parts := strings.Split(xff, ",")
+			ip := strings.TrimSpace(strings.Split(xff, ",")[0])
-			if trustedProxyHops > 0 {
+			if net.ParseIP(ip) != nil {
-				// PRECISE MODE: count back N hops from end. Real client IP
+				return ip
-				// sits at index (len(parts) - N). Walk backwards to skip
-				// any malformed values; if chain is shorter than expected,
-				// fall through to the first valid IP in the chain.
-				target := len(parts) - trustedProxyHops
-				if target < 0 {
-					target = 0
-				}
-				for i := target; i >= 0; i-- {
-					ip := strings.TrimSpace(parts[i])
-					if net.ParseIP(ip) != nil {
-						return ip
-					}
-				}
-			} else {
-				// HEURISTIC MODE (default): walk from end, return first
-				// PUBLIC IP. Skips private/loopback hops that come from
-				// internal proxies between the public-facing proxy and us.
-				for i := len(parts) - 1; i >= 0; i-- {
-					ip := strings.TrimSpace(parts[i])
-					if parsed := net.ParseIP(ip); parsed != nil && !isPrivateIP(ip) {
-						return ip
-					}
-				}
 			}
 		}
 		if xri := strings.TrimSpace(r.Header.Get("X-Real-IP")); xri != "" {

middleware/ratelimit_middleware.go.tmp

@@ -0,0 +1,32 @@
+package middleware
+
+import (
+	"log"
+	"net/http"
+)
+
+func RateLimit(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		clientIP := GetClientIP(r)
+		if !GlobalRateLimiter.Allow(clientIP) {
+			log.Printf("警告: 已超过IP速率限制，拒绝请求 - 客户端IP: %s", clientIP)
+			SendJSONError(w, http.StatusTooManyRequests, "Rate limit exceeded. Please try again later.", "rate_limit_error", "rate_limit_exceeded")
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func ConcurrencyLimit(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		select {
+		case ConcurrencySem <- struct{}{}:
+			defer func() { <-ConcurrencySem }()
+			next.ServeHTTP(w, r)
+		default:
+			log.Printf("警告: 已达到最大并发请求数限制，拒绝请求 - 客户端IP: %s", GetClientIP(r))
+			SendJSONError(w, http.StatusServiceUnavailable, "Server is busy, maximum concurrent requests reached. Please try again later.", "concurrency_limit_error", "max_concurrent_requests")
+			return
+		}
+	})
+}

middleware/ratelimit_test.go

@@ -1,229 +0,0 @@
-package middleware
-
-import (
-	"net/http/httptest"
-	"testing"
-)
-
-// TestGetClientIP 覆盖 XFF 解析在两种模式下的关键场景。
-// 表驱动测试,每个 case 独立设置 trustedProxyHops,验证 GetClientIP 输出。
-func TestGetClientIP(t *testing.T) {
-	tests := []struct {
-		name       string
-		mode       int    // 0=启发式, N>0=精确 N 跳
-		remoteAddr string // 直连 IP:port
-		xff        string // X-Forwarded-For 头(空则不设)
-		xri        string // X-Real-IP 头(空则不设)
-		want       string
-	}{
-		// === 直出部署(directIP 是公网,XFF 分支不进)===
-		{
-			name:       "直出_无XFF",
-			mode:       0,
-			remoteAddr: "1.2.3.4:5678",
-			want:       "1.2.3.4",
-		},
-		{
-			name:       "直出_XFF被忽略",
-			mode:       0,
-			remoteAddr: "1.2.3.4:5678",
-			xff:        "fake",
-			want:       "1.2.3.4", // 公网直连不走 XFF 分支
-		},
-		{
-			name:       "直出_精确模式也不走XFF",
-			mode:       2,
-			remoteAddr: "1.2.3.4:5678",
-			xff:        "fake, 5.6.7.8",
-			want:       "1.2.3.4",
-		},
-
-		// === 单跳反代 ===
-		{
-			name:       "单跳_启发式",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4",
-			want:       "1.2.3.4",
-		},
-		{
-			name:       "单跳_精确N1",
-			mode:       1,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4",
-			want:       "1.2.3.4",
-		},
-
-		// === 攻击者伪造首值 ===
-		{
-			name:       "伪造_启发式跳过fake",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "fake, 1.2.3.4",
-			want:       "1.2.3.4",
-		},
-		{
-			name:       "伪造_精确N1也跳过fake",
-			mode:       1,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "fake, 1.2.3.4",
-			want:       "1.2.3.4", // target=1, 跳过 fake 取 real
-		},
-		{
-			name:       "伪造_多个假值前缀",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "fake1, fake2, 1.2.3.4",
-			want:       "1.2.3.4", // 从尾扫,只看最后一个
-		},
-
-		// === 多跳 CDN+nginx ===
-		{
-			name:       "多跳_启发式返回CDN边缘",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4, 203.0.113.5",
-			want:       "203.0.113.5", // 链尾公网=CDN 边缘
-		},
-		{
-			name:       "多跳_精确N2返回真实client",
-			mode:       2,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4, 203.0.113.5",
-			want:       "1.2.3.4", // 倒数第2=真实 client
-		},
-		{
-			name:       "多跳_精确N1不够穿透",
-			mode:       1,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4, 203.0.113.5",
-			want:       "203.0.113.5", // 数到 nginx,没穿透到 client
-		},
-
-		// === 链尾私有 IP ===
-		{
-			name:       "链尾私有_启发式跳过",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4, 10.0.0.1",
-			want:       "1.2.3.4", // 跳过私有取公网
-		},
-		{
-			name:       "链尾私有_精确N1取末值",
-			mode:       1,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4, 10.0.0.1",
-			want:       "10.0.0.1", // 精确模式不跳私有
-		},
-
-		// === X-Real-IP 兜底 ===
-		{
-			name:       "无XFF_走XRI",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xri:        "1.2.3.4",
-			want:       "1.2.3.4",
-		},
-		{
-			name:       "XFF全非法_走XRI",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "not_ip, also_not",
-			xri:        "1.2.3.4",
-			want:       "1.2.3.4",
-		},
-		{
-			name:       "XRI被XFF优先_但XFF全非法",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "not_an_ip",
-			xri:        "1.2.3.4",
-			want:       "1.2.3.4",
-		},
-
-		// === 全部私有 IP(启发式无解)===
-		{
-			name:       "全私有_启发式回退directIP",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "192.168.1.1, 172.16.0.1",
-			want:       "10.0.0.1", // 全跳私有,走 directIP
-		},
-
-		// === 畸形/空 XFF ===
-		{
-			name:       "畸形XFF_启发式跳过畸形",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "not_an_ip, 1.2.3.4",
-			want:       "1.2.3.4",
-		},
-		{
-			name:       "全空XFF_回退directIP",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "  ,  ,  ",
-			want:       "10.0.0.1",
-		},
-		{
-			name:       "XFF带前后空格",
-			mode:       0,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "  1.2.3.4  ,  5.6.7.8  ",
-			want:       "5.6.7.8", // TrimSpace 处理
-		},
-
-		// === 精确模式 N 超出链长 ===
-		{
-			name:       "精确N超出链长_回退到首值",
-			mode:       5,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4",
-			want:       "1.2.3.4", // target<0 保护,取首个合法
-		},
-		{
-			name:       "精确N等于链长_取首值",
-			mode:       1,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4",
-			want:       "1.2.3.4", // target=0
-		},
-		{
-			name:       "精确N大于链长_取首值",
-			mode:       2,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4",
-			want:       "1.2.3.4", // target<0,fall back
-		},
-
-		// === 精确模式链中含畸形 ===
-		{
-			name:       "精确N1_链中畸形回退到首值",
-			mode:       1,
-			remoteAddr: "10.0.0.1:5678",
-			xff:        "1.2.3.4, not_ip",
-			want:       "1.2.3.4", // target=1(not_ip 失败)→ i=0(1.2.3.4 成功)
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			trustedProxyHops = tt.mode
-			r := httptest.NewRequest("GET", "/", nil)
-			r.RemoteAddr = tt.remoteAddr
-			if tt.xff != "" {
-				r.Header.Set("X-Forwarded-For", tt.xff)
-			}
-			if tt.xri != "" {
-				r.Header.Set("X-Real-IP", tt.xri)
-			}
-			got := GetClientIP(r)
-			if got != tt.want {
-				t.Errorf("GetClientIP() = %q, want %q", got, tt.want)
-			}
-		})
-	}
-
-	// 重置为默认,避免影响其他测试或运行时行为
-	trustedProxyHops = 0
-}

setting/config.go

@@ -46,12 +46,6 @@ type ServerConfig struct {
 
 var Server ServerConfig
 
-// TrustedProxyHops 由 middleware.InitRateLimiter 在启动期写入,
-// 表示当前 XFF 解析模式:0=启发式,N>0=精确 N 跳。
-// setting.LogStartupSummary 读这个字段以展示运行期配置,
-// 不直接调用 middleware(避免循环 import)。
-var TrustedProxyHops int
-
 // InitAllConfigs 集中初始化所有配置,启动期调用一次。
 func InitAllConfigs() {
 	InitServerConfig()
@@ -263,12 +257,6 @@ func LogStartupSummary() {
 		log.Printf("ALLOWED_ORIGINS: 已配置 %d 个允许的跨域来源白名单", len(CORS.Origins))
 	}
 
-	if h := TrustedProxyHops; h == 0 {
-		log.Printf("TRUSTED_PROXY_HOPS: 启发式模式(默认,XFF 链尾第一个公网 IP)")
-	} else {
-		log.Printf("TRUSTED_PROXY_HOPS: 精确模式,信任 %d 跳反代", h)
-	}
-
 	log.Printf("火山 TTS 必填项状态:")
 	type ttsCheck struct {
 		name  string