TTS 服务

✨ 功能特点

🏗️ 架构概览

后端服务 (Go)

前端应用 (React)

🚀 快速开始

方式一:Docker 部署(推荐)

# 拉取并运行完整服务(前端 + 后端)
docker run -d -p 8080:8080 --name=tts zuoban/zb-tts

方式二:本地开发

后端开发

# 构建应用程序
go build -o tts ./cmd/api
# 运行应用程序
./tts
# 或使用配置文件运行
./tts -config ./configs/config.yaml

前端开发

# 进入前端目录
cd frontend
# 安装依赖
npm install
# 启动开发服务器(默认端口 3000)
npm run dev
# 构建生产版本
npm run build

Docker Compose 开发

# 启动完整开发环境(前端 + 后端)
docker-compose -f docker-compose.dev.yml up --build

方式三:Cloudflare Worker 部署

📚 API 文档

v1 API(推荐使用)

健康检查

curl "http://localhost:8080/api/v1/health"

获取配置信息

curl "http://localhost:8080/api/v1/config"

获取语音列表

# 方式 1:Bearer Token 认证(推荐)
curl -H "Authorization: Bearer YOUR_TTS_API_KEY" \
 "http://localhost:8080/api/v1/voices"
# 方式 2:Query 参数认证
curl "http://localhost:8080/api/v1/voices?api_key=YOUR_TTS_API_KEY"

文本转语音

# 方式 1:GET 请求 + Query 参数认证
curl "http://localhost:8080/api/v1/tts?text=你好,世界&voice=zh-CN-XiaoxiaoNeural&api_key=YOUR_TTS_API_KEY" \
 -o output.mp3
# 方式 2:POST 请求 + Bearer Token 认证(推荐)
curl -X POST "http://localhost:8080/api/v1/tts" \
 -H "Authorization: Bearer YOUR_TTS_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "text": "你好,世界",
 "voice": "zh-CN-XiaoxiaoNeural",
 "rate": 20,
 "pitch": 10,
 "style": "cheerful"
 }' -o output.mp3
# 方式 3:POST 请求 + 请求体中的 api_key
curl -X POST "http://localhost:8080/api/v1/tts" \
 -H "Content-Type: application/json" \
 -d '{
 "text": "你好,世界",
 "voice": "zh-CN-XiaoxiaoNeural",
 "rate": 20,
 "pitch": 10,
 "style": "cheerful",
 "api_key": "YOUR_TTS_API_KEY"
 }' -o output.mp3

兼容性 API

原版 TTS API

# 无认证(如果配置了 API Key 则需要认证)
curl "http://localhost:8080/tts?t=你好,世界&v=zh-CN-XiaoxiaoNeural" -o output.mp3
# 使用 Query 参数认证
curl "http://localhost:8080/tts?t=你好,世界&v=zh-CN-XiaoxiaoNeural&api_key=YOUR_TTS_API_KEY" -o output.mp3

OpenAI 兼容 API

# 方式 1:Bearer Token 认证(推荐)
curl -X POST "http://localhost:8080/v1/audio/speech" \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_TTS_API_KEY" \
 -d '{
 "model": "tts-1",
 "input": "你好,世界!",
 "voice": "zh-CN-XiaoxiaoNeural",
 "speed": 0.5
 }' -o output.mp3
# 方式 2:请求体中包含 api_key
curl -X POST "http://localhost:8080/v1/audio/speech" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "tts-1",
 "input": "你好,世界!",
 "voice": "zh-CN-XiaoxiaoNeural",
 "speed": 0.5,
 "api_key": "YOUR_TTS_API_KEY"
 }' -o output.mp3

📱 阅读集成

网络导入步骤

⚙️ 配置选项

环境变量配置

后端环境变量

# 服务配置
SERVER_PORT=8080 # 服务端口
CORS_ALLOWED_ORIGINS=* # 允许的 CORS 源
# TTS 服务配置
TTS_API_KEY=your_api_key # 统一的 API 密钥(TTS 和 OpenAI 兼容接口)
TTS_REGION=eastasia # Azure 区域
TTS_MAX_CONCURRENT=20 # 最大并发数

前端环境变量

# 在 frontend 目录下设置
VITE_API_BASE_URL=http://localhost:8080 # API 基础 URL
VITE_APP_TITLE="TTS 服务" # 应用标题
VITE_NODE_ENV=development # 环境标识

配置文件详解

server:
 port: 8080 # 服务监听端口
 read_timeout: 60 # HTTP 读取超时时间(秒)
 write_timeout: 60 # HTTP 写入超时时间(秒)
 base_path: "" # API 基础路径前缀
tts:
 region: "eastasia" # Azure 语音服务区域
 default_voice: "zh-CN-XiaoxiaoNeural" # 默认语音
 default_rate: "0" # 默认语速,范围 -100 到 100
 default_pitch: "0" # 默认语调,范围 -100 到 100
 default_format: "audio-24khz-48kbitrate-mono-mp3" # 默认音频格式
 max_text_length: 65535 # 最大文本长度
 request_timeout: 30 # 请求 Azure 服务的超时时间(秒)
 max_concurrent: 20 # 最大并发请求数
 segment_threshold: 300 # 文本分段阈值
 min_sentence_length: 200 # 最小句子长度
 max_sentence_length: 300 # 最大句子长度
 api_key: 'your_api_key' # TTS API 密钥
 # OpenAI 到微软 TTS 中文语音的映射
 voice_mapping:
 alloy: "zh-CN-XiaoyiNeural" # 中性女声
 echo: "zh-CN-YunxiNeural" # 年轻男声
 fable: "zh-CN-XiaochenNeural" # 儿童声
 onyx: "zh-CN-YunjianNeural" # 成熟男声
 nova: "zh-CN-XiaohanNeural" # 活力女声
 shimmer: "zh-CN-XiaomoNeural" # 温柔女声
# 注意:OpenAI 兼容接口使用 tts.api_key,不需要单独配置
ssml:
 preserve_tags: # SSML 标签保留配置
 - name: break
 pattern: <break\s+[^>]*/>
 - name: speak
 pattern: <speak>|</speak>
 - name: prosody
 pattern: <prosody\s+[^>]*>|</prosody>
 # ... 更多 SSML 标签配置

Docker 配置示例

# 使用自定义端口
docker run -d -p 9000:9000 -e SERVER_PORT=9000 --name=tts zuoban/zb-tts
# 使用配置文件
docker run -d -p 8080:8080 \
 -v /path/to/config.yaml:/configs/config.yaml \
 --name=tts zuoban/zb-tts
# 设置环境变量
docker run -d -p 8080:8080 \
 -e TTS_API_KEY=your_key \
 -e TTS_REGION=eastasia \
 --name=tts zuoban/zb-tts

🛠️ 本地构建与运行

系统要求

从源码构建

# 克隆仓库
git clone https://github.com/zuoban/tts.git
cd tts
# 后端构建
go mod download
go build -o tts ./cmd/api
# 前端构建
cd frontend
npm install
npm run build
cd ..
# 运行后端服务
./tts

开发脚本

后端开发

# 运行测试
go test ./...
# 整理依赖
go mod tidy
# 验证依赖
go mod verify
# 多平台构建(需要 Docker Buildx)
./script/build.sh

前端开发

cd frontend
# 启动开发服务器(默认端口 3000)
npm run dev
# 代码检查
npm run lint
# 自动修复 linting 问题
npm run lint:fix
# TypeScript 类型检查
npm run type-check
# 清理构建文件
npm run clean
# 预览构建结果
npm run preview

🧪 故障排除

常见问题

1. CORS 错误

2. API 请求失败

3. 前端构建失败

cd frontend
npm install # 更新依赖
# 检查 Node.js 版本(需要 18+)
node --version

4. 配置文件找不到

调试工具

📄 项目结构

tts/
├── cmd/api/ # 后端应用程序入口点
├── internal/ # 私有应用程序代码
│ ├── config/ # 配置管理
│ ├── http/ # HTTP 层
│ │ ├── handlers/ # HTTP 请求处理器
│ │ ├── middleware/ # 中间件
│ │ ├── routes/ # 路由配置
│ │ └── server/ # HTTP 服务器实现
│ ├── models/ # 数据模型定义
│ ├── tts/ # TTS 服务层
│ └── utils/ # 工具函数
├── frontend/ # React 前端应用
│ ├── src/
│ │ ├── components/ # React 组件
│ │ │ ├── ui/ # 通用 UI 组件
│ │ │ ├── audio/ # 音频相关组件
│ │ │ │ ├── FavoriteVoices.tsx # 收藏声音组件
│ │ │ │ ├── HistoryList.tsx # 历史记录组件
│ │ │ │ └── AudioPlayer.tsx # 音频播放器组件
│ │ │ └── layout/ # 布局组件
│ │ ├── pages/ # 页面组件
│ │ │ ├── Home.tsx # 首页(包含收藏功能)
│ │ │ └── VoiceLibrary.tsx # 声音库页面
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── services/ # API 服务层
│ │ │ ├── api.ts # TTS API 服务
│ │ │ └── favorites.ts # 收藏功能服务
│ │ ├── types/ # TypeScript 类型定义
│ │ │ ├── index.ts # 核心类型(包含收藏相关类型)
│ │ └── utils/ # 工具函数
│ └── dist/ # 构建输出目录
├── configs/ # 配置文件
├── script/ # 构建脚本
├── workers/ # Cloudflare Worker 代码
└── docs/ # 文档

🤝 贡献

📄 许可证