diff --git a/Piper-TTS部署方案-Ubuntu.md b/Piper-TTS部署方案-Ubuntu.md
new file mode 100644
index 0000000..1a91baf
--- /dev/null
+++ b/Piper-TTS部署方案-Ubuntu.md
@@ -0,0 +1,260 @@
+# Piper TTS 部署方案（Ubuntu）
+
+## 1. 方案说明
+
+`spanish-diary` 的朗读采用双引擎策略：
+
+```text
+系统 Web Speech API 优先
+手机无 TTS 语音或浏览器不支持时
+自动回退到自建 Piper TTS
+```
+
+Piper 是轻量级本地神经网络 TTS，支持西班牙语、英语、中文，适合 CPU 服务器部署。
+
+本项目不会单独启动 Piper 服务，而是由 `spanish-diary` 后端直接调用 Piper 命令行生成 WAV，并按“语言 + 文本”缓存，避免重复生成。
+
+## 2. 安装基础依赖
+
+```bash
+sudo apt update
+sudo apt install -y python3-venv python3-pip espeak-ng
+```
+
+## 3. 安装 Piper
+
+```bash
+sudo mkdir -p /opt/piper
+sudo python3 -m venv /opt/piper/venv
+sudo /opt/piper/venv/bin/pip install --upgrade pip
+sudo /opt/piper/venv/bin/pip install piper-tts
+```
+
+验证：
+
+```bash
+/opt/piper/venv/bin/piper --help
+```
+
+## 4. 下载语音模型
+
+创建模型目录：
+
+```bash
+sudo mkdir -p /opt/piper/voices
+cd /opt/piper/voices
+```
+
+下载英语：
+
+```bash
+sudo curl -L -o en_US-lessac-medium.onnx https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx
+sudo curl -L -o en_US-lessac-medium.onnx.json https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json
+```
+
+下载西班牙语：
+
+```bash
+sudo curl -L -o es_ES-davefx-medium.onnx https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx
+sudo curl -L -o es_ES-davefx-medium.onnx.json https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx.json
+```
+
+下载中文：
+
+```bash
+sudo curl -L -o zh_CN-huayan-medium.onnx https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/zh/zh_CN/huayan/medium/zh_CN-huayan-medium.onnx
+sudo curl -L -o zh_CN-huayan-medium.onnx.json https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/zh/zh_CN/huayan/medium/zh_CN-huayan-medium.onnx.json
+```
+
+国内服务器如果无法访问 Hugging Face，可以把下载地址中的 `huggingface.co` 替换为 `hf-mirror.com`，例如：
+
+```text
+https://hf-mirror.com/rhasspy/piper-voices/resolve/v1.0.0/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx
+```
+
+## 5. 测试 Piper
+
+```bash
+echo 'Hola, buenos días' | /opt/piper/venv/bin/piper \
+  --model /opt/piper/voices/es_ES-davefx-medium.onnx \
+  --output_file /tmp/hola.wav
+```
+
+生成后检查：
+
+```bash
+ls -lh /tmp/hola.wav
+```
+
+英语和中文同理：
+
+```bash
+echo 'Good morning' | /opt/piper/venv/bin/piper --model /opt/piper/voices/en_US-lessac-medium.onnx --output_file /tmp/en.wav
+echo '早上好' | /opt/piper/venv/bin/piper --model /opt/piper/voices/zh_CN-huayan-medium.onnx --output_file /tmp/zh.wav
+```
+
+## 6. 配置 spanish-diary 后端
+
+`spanish-diary` 后端通过环境变量读取 Piper 配置：
+
+```text
+PIPER_BIN
+PIPER_MODELS_DIR
+TTS_CACHE_DIR
+```
+
+创建 systemd 配置覆盖文件：
+
+```bash
+sudo mkdir -p /etc/systemd/system/spanish-diary.service.d
+sudo tee /etc/systemd/system/spanish-diary.service.d/piper.conf > /dev/null <<'EOF'
+[Service]
+Environment=PIPER_BIN=/opt/piper/venv/bin/piper
+Environment=PIPER_MODELS_DIR=/opt/piper/voices
+Environment=TTS_CACHE_DIR=/opt/spanish-diary/server/data/tts_cache
+EOF
+```
+
+创建缓存目录并设置权限：
+
+```bash
+sudo mkdir -p /opt/spanish-diary/server/data/tts_cache
+sudo chown -R spanish-diary:spanish-diary /opt/spanish-diary/server/data
+```
+
+重新加载并重启：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart spanish-diary
+```
+
+## 7. 测试后端 TTS 接口
+
+先登录获取 Cookie：
+
+```bash
+curl -c /tmp/cookies.txt \
+  -X POST http://127.0.0.1:5000/api/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+```
+
+调用 TTS：
+
+```bash
+curl -b /tmp/cookies.txt \
+  -X POST http://127.0.0.1:5000/api/tts \
+  -H "Content-Type: application/json" \
+  -d '{"text":"Hola","lang":"es"}' \
+  --output /tmp/hola.wav
+```
+
+检查返回文件：
+
+```bash
+file /tmp/hola.wav
+ls -lh /tmp/hola.wav
+```
+
+支持语言：
+
+```text
+es：西班牙语
+en：英语
+zh：中文
+```
+
+## 8. 前端回退逻辑
+
+前端 `speech.js` 的行为：
+
+```text
+1. 浏览器支持 Web Speech API 且已加载系统语音
+   → 使用手机/电脑系统 TTS
+2. 浏览器不支持，或语音列表始终为空
+   → 调用 /api/tts 获取 Piper WAV
+3. 后端缓存相同文本
+   → 直接返回缓存音频，不重复生成
+```
+
+## 9. 缓存目录
+
+Piper 生成结果缓存在：
+
+```text
+/opt/spanish-diary/server/data/tts_cache
+```
+
+文件名格式：
+
+```text
+es_xxxxxxxxxxxxxxxxxxxxxxxx.wav
+en_xxxxxxxxxxxxxxxxxxxxxxxx.wav
+zh_xxxxxxxxxxxxxxxxxxxxxxxx.wav
+```
+
+清理缓存：
+
+```bash
+sudo systemctl stop spanish-diary
+sudo find /opt/spanish-diary/server/data/tts_cache -name '*.wav' -delete
+sudo systemctl start spanish-diary
+```
+
+## 10. 常见问题
+
+### 10.1 接口返回 503：Piper 未配置或未安装
+
+检查环境变量是否已写入 systemd：
+
+```bash
+systemctl cat spanish-diary | grep PIPER
+```
+
+检查 Piper 可执行文件：
+
+```bash
+ls -l /opt/piper/venv/bin/piper
+```
+
+### 10.2 提示模型不存在
+
+确认模型文件在 `/opt/piper/voices`：
+
+```bash
+ls -lh /opt/piper/voices
+```
+
+### 10.3 生成失败，提示 espeak-ng
+
+Piper 依赖 espeak-ng：
+
+```bash
+sudo apt install -y espeak-ng
+```
+
+### 10.4 缓存目录无权限
+
+```bash
+sudo mkdir -p /opt/spanish-diary/server/data/tts_cache
+sudo chown -R spanish-diary:spanish-diary /opt/spanish-diary/server/data
+sudo systemctl restart spanish-diary
+```
+
+### 10.5 浏览器中朗读没有声音
+
+- 确认已通过 `http://localhost:5000` 或域名访问，而不是本地 `file://`
+- 确认当前用户已登录
+- 手机系统有 TTS 语音包时优先使用系统语音；没有时自动回退 Piper
+
+## 11. 总结
+
+```text
+1. 安装 espeak-ng 和 piper-tts
+2. 下载 es/en/zh 三个 Piper 模型
+3. 配置 spanish-diary 的 PIPER_BIN、PIPER_MODELS_DIR、TTS_CACHE_DIR
+4. 重启 spanish-diary
+5. 前端系统 TTS 不可用时自动回退 Piper
+6. WAV 按文本哈希缓存，避免重复生成
+```