reader_pro/docs/技术侧落地方案.md

技术侧落地方案

目标

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

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

本文默认当前项目栈为：

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

1. 安全整改

目标

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

当前问题

• config.py 写有默认数据库密码
• 默认管理员账号 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 化、配额限流和缓存优化，这几项直接决定你能不能放心开放给用户使用。