-
🎉 v0.2.1 — 安全加固 & 可观测性补全
StableDocker Publish / build-and-push (push) Canceled after 0ssun released this
2026-08-27 14:52:11 +08:00 | 49 commits to main since this release
对全 12 个包、约 2400 行代码完成系统性安全审计，修复 9 项漏洞（高 1 / 中 2 / 低 4 / 信息 2），补全传输层错误监控，修复音频格式响应头不一致问题，并将版本号从硬编码改为构建时注入。
⚠️ 重大变更 (升级必读)
X-Forwarded-For 默认行为变化
TRUSTED_PROXY_HOPS默认值从1（精确模式）改为0（启发式模式）。部署方式 影响 单跳反代（client → nginx → 本服务） 行为完全相同，无需任何改动 多跳 CDN（client → CDN → nginx → 本服务） 限流粒度从"真实 client IP"变为"CDN 边缘 IP"。如需精准按真实 client 限流，请显式设置 TRUSTED_PROXY_HOPS=2直出部署（无反代） 无影响，XFF 分支不执行 启动日志会显示当前 XFF 解析模式，可用于验证。
🔒 安全修复
编号 等级 问题 修复方式 VUL-004 🔴 高 .gitignore未忽略.env，git add .会将火山 API Key 提交进 git 历史.gitignore/.dockerignore新增 Secrets 规则，拦截.env及.env.*变体，保留.env.example模板VUL-001 🟡 中 请求 aac/flac格式时，响应Content-Type为audio/aac/audio/flac，但实际字节流是降级后的 MP3，客户端解码失败finalFormat改为反映真实输出格式，非 wav 时取上游实际格式VUL-003 🟡 中 X-Forwarded-For取首值，攻击者可伪造 IP 绕过 IP 限流重写为启发式/精确双模式，两种模式均从链尾扫描，天然免疫伪造。默认启发式模式零配置适配 90% 部署场景 VUL-002 🟢 低 transport 层错误（DNS/连接/TLS 失败、WAV 头拼装失败等）不进入 UpstreamErrors指标，网络故障在监控上完全不可见错误判断从 errCode != 0改为status != "ok"，transport / request / wrap / stream 错误首次进入监控VUL-005 🟢 低 攻击者可在请求 URL 或上游错误响应中注入 \n/\r伪造日志行访问日志 RequestURI和上游错误体均转义换行符VUL-006 🟢 低 /metrics/health/dashboard无鉴权，公网部署暴露业务指标和配置状态文档新增「公网部署：监控端点无鉴权」章节，含三端点风险表 + nginx basic auth 配置示例 VUL-007 🟢 低 未设置 OPENAI_TTS_API_KEY时鉴权完全关闭，公网部署任何人可调用消耗火山额度文档三处强化：环境变量表加 🔴 公网必设标记、API 使用说明顶部警示、新增「公网部署安全清单」章节 VUL-008 ⚪ 信息 speed参数超火山实际范围（0.5~2.0）时被静默截断，客户端无感知文档修正为「客户端接受 0.25 4.0，火山实际生效 0.52.0，超出静默截断」VUL-009 ⚪ 信息 WAV 头的采样率直接取配置值，若与上游实际 PCM 采样率不一致会导致音频变速变调 文档给 BYTEDANCE_TTS_SAMPLE_RATE加风险提示
✨ 功能改进
构建时版本号注入
/health端点的version字段不再硬编码，改为通过ldflags在构建时注入：- Release 构建：显示干净 semver（如
v0.2.1） - 开发构建：显示
git describe输出 + commit hash（如v0.2.0-5-g4abcd5） - 本地默认：
dev
Dockerfile 已配套
ARG VERSION/ARG COMMIT，CI/CD 可直接传入。新增
TRUSTED_PROXY_HOPS环境变量控制 XFF 解析模式：
值 模式 说明 不设置 / 0启发式（默认） 从 XFF 链尾扫描，跳过私有 IP，返回第一个公网 IP。适合 90% 部署 N（N > 0）精确模式 从 XFF 链尾倒数第 N+1 个位置取值，精准到真实 client IP。N=1 单跳反代，N=2 CDN+反代，以此类推
🧪 测试 & 代码质量
- 新增 24 个表驱动测试用例（
middleware/ratelimit_test.go），覆盖直出/单跳/多跳/伪造/畸形/精确 N 边界，全部通过 - 清理死代码约 30 行（7 个文件），含从未被引用的
ratelimit_middleware.go、空初始化函数、未使用类型和常量 - 新增
VULNERABILITY_REPORT.md，完整记录 9 项漏洞详情、8 条已核查无风险项、工程债务记录和安全加固建议
📦 下载
平台 文件 说明 Windows x64 tts-api.exe由 release 维护者上传，直接双击或命令行运行 Docker ghcr.io/Blue-Ink-Studio/Volcano-Engine-TTS-UI:v0.2.1推荐，amd64/arm64 双架构 源码 Source code (zip)/(tar.gz)服务器 git pull后go build即可
🚀 升级步骤
- 拉取最新代码或镜像
- 检查反代拓扑：如果是多跳 CDN 部署且需要精准按真实 client 限流，设置
TRUSTED_PROXY_HOPS=2（或对应跳数）；单跳/直出无需改动 - 确认
.env未被提交：执行git status检查，如有.env请加入.gitignore并从 git 历史移除 - 重启服务，查看启动日志中的 XFF 模式提示和版本号
- 验证：访问
/health确认version显示为v0.2.1
📊 变更统计
- Commits：11
- 变更文件：22
- 新增代码：+738 行
- 删除代码：-118 行
- 新增测试：24 个用例
Downloads
- Release 构建：显示干净 semver（如