# 技术侧落地方案

## 目标

本文档用于把当前项目从“可运行”推进到“可公开发布、可持续运维、可支持收费”的技术形态。重点覆盖以下模块：

- 安全整改
- Docker 化部署
- 配额和限流
- 用量统计
- 异步任务队列
- 更稳定的缓存策略
- 管理员后台完善
- 监控和日志

本文默认当前项目栈为：

- 后端：`FastAPI`
- 前端：`PDF.js + 自定义页面`
- 数据库：`MySQL`
- TTS：本地 `Kororo ONNX` 上游服务

## 1. 安全整改

### 目标

让项目达到最基本的公开部署和收费使用标准，避免明显的密码、权限、接口暴露问题。

### 当前问题

- [config.py](/home/service/reader_pro/config.py:1) 写有默认数据库密码
- 默认管理员账号 `admin/admin`
- 密码哈希仍为简单 `sha256`
- `CORS = *`
- Cookie `secure=False`
- 缺少上传、登录、生成接口限流

### 落地方案

#### 1. 配置安全

改为环境变量加载：

- 新增 `.env.example`
- 所有数据库、Cookie、TTS 上游地址改为环境变量
- 正式环境禁止提交真实 `.env`

建议变量：

- `READER_PRO_DB_HOST`
- `READER_PRO_DB_PORT`
- `READER_PRO_DB_USER`
- `READER_PRO_DB_PASSWORD`
- `READER_PRO_DB_NAME`
- `READER_PRO_TTS_API_BASE_URL`
- `READER_PRO_SESSION_SECRET`
- `READER_PRO_ALLOWED_ORIGINS`

#### 2. 认证安全

- 密码哈希改为 `bcrypt` 或 `argon2`
- 默认不创建弱口令管理员
- 第一次启动通过初始化命令创建管理员
- 登录失败增加限次和冷却

建议实现：

- 新增 `scripts/create_admin.py`
- 仅在初始化阶段人工创建管理员

#### 3. 接口安全

- 上传接口限制文件大小
- 生成接口限制请求频率
- 管理接口仅管理员可访问
- 增加基础审计日志

#### 4. 浏览器安全

- HTTPS 环境下 Cookie 使用 `secure=True`
- 设置 `httponly=True`
- 设置 `samesite=lax` 或更严格
- CORS 不再默认全开放

### 分阶段实现

#### 第一阶段

- 环境变量改造
- 去除默认密码
- 去除默认弱口令管理员
- 升级密码哈希

#### 第二阶段

- 登录和生成接口限流
- 文件上传大小限制
- 基础审计日志

## 2. Docker 化部署

### 目标

降低部署成本，提高可复现性，方便开源用户试用，也方便后续商业托管和私有部署。

### 推荐结构

建议至少提供以下文件：

- `Dockerfile`
- `docker-compose.yml`
- `.env.example`
- `deploy/nginx.conf`
- `deploy/systemd/` 或部署说明

### 落地方式

#### 1. 后端镜像

封装 FastAPI 服务：

- 安装 Python 依赖
- 暴露服务端口
- 使用 `uvicorn` 或 `gunicorn + uvicorn worker`

建议：

- 开发环境可用 `uvicorn`
- 生产环境建议 `gunicorn`

#### 2. 依赖服务

初期 `docker-compose.yml` 建议包括：

- `app`
- `mysql`
- `redis`
- `tts`，如果本地 TTS 也能容器化则一起封装

#### 3. 存储卷

需要挂载的数据目录：

- `static/files/`
- `audio_cache/`
- 日志目录

#### 4. 反向代理

建议由 `Nginx` 负责：

- HTTPS
- 静态资源缓存
- 请求体大小限制
- 基础限流

### 分阶段实现

#### 第一阶段

- 单机 `docker-compose`
- 一条命令启动

#### 第二阶段

- Nginx 反向代理
- 数据卷标准化
- 生产部署说明

## 3. 配额和限流

### 目标

防止免费用户滥用资源，控制 TTS 成本，并为收费功能提供边界。

### 推荐设计

配额和限流分开设计：

- 配额：用户每天/月总可用量
- 限流：单位时间内请求频率限制

### 配额维度建议

- 每日生成字符数
- 每日生成次数
- 单次最大文本长度
- 同时进行中的任务数

### 用户等级建议

- 匿名用户：禁止使用或仅试用
- 免费用户：低配额
- Pro 用户：中高配额
- 团队用户：更高配额

### 数据设计建议

建议新增数据表：

- `plan`
- `user_plan`
- `usage_daily`
- `usage_monthly`

核心字段：

- `user_id`
- `usage_date`
- `tts_chars`
- `tts_requests`
- `audio_seconds`

### 限流实现建议

初期可以基于：

- 用户 ID
- IP
- 接口路径

可用方式：

- Redis 计数器
- Nginx 限流
- 应用层中间件

推荐策略：

- 登录接口：防爆破
- 注册接口：防批量注册
- `/generate`：防刷资源
- 上传接口：防大文件和频繁上传

### 分阶段实现

#### 第一阶段

- 每日字符配额
- 单次文本长度限制
- 登录和生成接口限流

#### 第二阶段

- 月度配额
- 套餐绑定
- 后台可调额度

## 4. 用量统计

### 目标

支撑配额、后台运营、问题定位和商业化决策。

### 最低可用统计项

- 日活用户数
- 生成请求数
- 生成字符数
- 音频总时长
- 缓存命中率
- 失败率
- 平均生成耗时

### 数据来源

建议在每次 TTS 请求完成后记录：

- 用户 ID
- 文档 ID 或文件名
- 文本长度
- 是否命中缓存
- 音频时长
- 请求开始和结束时间
- 结果状态

### 建议表结构

- `tts_request_log`
- `usage_daily`
- `system_metrics_snapshot`

### 后台可展示内容

- 今日生成量
- 本月生成量
- 用户排行
- 峰值时段
- 缓存命中率
- 错误统计

### 分阶段实现

#### 第一阶段

- 请求日志表
- 每日汇总表
- 管理员后台可查看基础统计

#### 第二阶段

- 趋势图
- 导出 CSV
- 套餐使用率和续费辅助数据

## 5. 异步任务队列

### 目标

避免长文本生成阻塞接口，提高并发稳定性，便于后续扩容。

### 什么时候必须上任务队列

以下场景建议引入：

- 整页或长段落生成
- 多用户同时生成
- 需要重试机制
- 需要任务状态反馈

### 推荐架构

建议引入：

- `Redis` 作为 broker
- `Celery` 或 `RQ` 作为任务队列

如果你想保持轻量，早期建议：

- `RQ + Redis`

如果后续需要复杂任务流和计划任务：

- `Celery + Redis`

### 任务拆分建议

- 短句请求：可同步返回
- 长文本请求：进入队列异步处理
- 预热缓存：后台异步任务
- 清理缓存：定时任务

### 用户体验建议

前端展示：

- 任务提交成功
- 当前状态：排队中、处理中、已完成、失败
- 可轮询或 WebSocket 更新状态

### 分阶段实现

#### 第一阶段

- 长文本进入队列
- 返回 `task_id`
- 前端轮询任务状态

#### 第二阶段

- 重试机制
- 优先级队列
- 失败重放

## 6. 更稳定的缓存策略

### 目标

降低重复生成成本，提升起播速度，提高系统稳定性。

### 当前缓存方向是正确的

目前已有 `audio_cache/`，说明项目已经具备成本控制基础，但需要进一步规范化。

### 推荐缓存策略

#### 1. 句级缓存优先

缓存 key 建议由以下内容组成：

- 文本内容
- voice
- speed
- 模型版本
- 音频格式

这样相同句子可直接复用。

#### 2. 缓存层级

- L1：内存元数据缓存
- L2：磁盘音频缓存
- L3：可选对象存储缓存

#### 3. 缓存元数据表

建议增加：

- `audio_cache_index`

字段建议：

- `cache_key`
- `file_path`
- `text_length`
- `voice`
- `speed`
- `hit_count`
- `created_at`
- `last_hit_at`

#### 4. 清理策略

- 按最近最少使用清理
- 按总容量阈值清理
- 按过期时间清理

#### 5. 预生成策略

适合热门文档：

- 翻页后预生成下一句
- 用户停留当前页时预生成后续句子

### 分阶段实现

#### 第一阶段

- 统一缓存 key 规则
- 建立缓存索引表
- 加入命中统计

#### 第二阶段

- LRU 清理
- 热点句预生成
- 后台缓存维护任务

## 7. 管理员后台完善

### 目标

让后台不只是“用户管理入口”，而是一个可用于运营、限额、排错、客服支持的管理系统。

### 当前应补的能力

- 用户列表
- 用户状态管理
- 套餐管理
- 用量查询
- 请求日志查看
- 任务查看
- 缓存查看
- 系统运行状态查看

### 推荐后台页面模块

#### 1. 仪表盘

- 今日活跃用户
- 今日生成次数
- 缓存命中率
- 当前排队任务数
- 错误数

#### 2. 用户管理

- 用户列表
- 搜索用户
- 重置密码
- 启用/禁用
- 查看套餐和使用量

#### 3. 套餐和配额管理

- 创建套餐
- 绑定用户套餐
- 调整配额
- 查看剩余额度

#### 4. 请求与任务中心

- 查看最近生成任务
- 查看失败任务
- 手动重试
- 查看耗时

#### 5. 缓存管理

- 缓存容量
- 命中率
- 热门缓存项
- 手动清理

### 分阶段实现

#### 第一阶段

- 用户管理
- 基础统计
- 用量查看

#### 第二阶段

- 套餐与任务管理
- 缓存管理
- 系统健康页

## 8. 监控和日志

### 目标

让系统在真实用户环境中可观测，能快速发现瓶颈和异常。

### 日志建议

至少分为：

- 应用日志
- 错误日志
- TTS 请求日志
- 管理员操作日志

### 关键日志字段

- 请求时间
- 用户 ID
- 接口路径
- 文件名
- 字符数
- 缓存是否命中
- 耗时
- 状态码
- 错误信息

### 监控建议

至少监控：

- CPU
- 内存
- 磁盘
- 请求量
- 错误率
- 平均响应时间
- TTS 队列长度
- 缓存目录容量

### 推荐实现方式

初期轻量方案：

- `Prometheus + Grafana`
- `Loki` 或文件日志

更轻量的第一阶段：

- 结构化日志写文件
- 定时脚本采样系统指标
- 后台展示最近指标

### 告警建议

建议对以下情况告警：

- TTS 连续失败
- 队列积压过多
- CPU 长时间满载
- 缓存磁盘接近上限
- 数据库连接失败

### 分阶段实现

#### 第一阶段

- 结构化日志
- 日志分级
- 后台显示最近错误

#### 第二阶段

- Prometheus 指标
- Grafana 面板
- 基础告警

## 推荐实施顺序

如果按当前项目现实情况推进，建议顺序如下：

1. 安全整改
2. Docker 化部署
3. 配额和限流
4. 用量统计
5. 稳定缓存策略
6. 异步任务队列
7. 管理员后台完善
8. 监控和日志

## 建议里程碑

### 里程碑一：可公开部署

- 安全整改完成
- Docker 部署完成
- 限流与基础日志完成

### 里程碑二：可控试运营

- 配额和统计完成
- 缓存策略增强
- 后台可查看关键数据

### 里程碑三：可收费运营

- 队列机制完成
- 管理后台完善
- 监控和告警完善

## 总结

技术侧的重点不是一次把所有系统做重，而是先把“安全、部署、可控成本、可观测”补齐。对于你当前这个 CPU TTS 场景，最优先的是安全整改、Docker 化、配额限流和缓存优化，这几项直接决定你能不能放心开放给用户使用。