reader_pro/docs/技术侧-实施清单.md

技术侧实施清单

目标

本文档将技术侧方案拆成可执行清单，按优先级和阶段推进，适合直接排期。

第一阶段：可公开部署

1. 安全整改

• 将数据库配置迁移到环境变量
• 新增 .env.example
• 删除代码中的默认数据库密码
• 移除默认 admin/admin
• 引入 bcrypt 或 argon2
• 增加管理员初始化脚本
• 限制 CORS 来源
• 生产环境启用 secure cookie

2. 基础工程化

• 编写 Dockerfile
• 编写 docker-compose.yml
• 配置 MySQL 容器
• 配置 Redis 容器
• 规范数据卷目录
• 编写部署说明文档

3. 日志与健康检查

• 新增统一日志格式
• 为请求生成 request_id
• 增加 /api/health
• 记录 TTS 请求耗时
• 记录异常日志

第一阶段验收标准

• 项目可通过 docker compose up 启动
• 无敏感配置硬编码
• 默认无弱口令管理员
• 健康检查可返回数据库和 TTS 状态

第二阶段：可控试运营

4. 数据结构升级

• 新增 plan
• 新增 user_plan
• 新增 usage_daily
• 新增 tts_request_log
• 新增 audio_cache_index

5. 配额和限流

• 定义免费版默认配额
• 定义 Pro 版默认配额
• 接口增加单次文本长度限制
• 接口增加每日字符限制
• 登录接口增加限流
• 生成接口增加限流

6. 用量统计

• 每次生成记录请求日志
• 每次成功生成累计 usage_daily
• 增加用户用量查询接口
• 增加后台基础统计接口

7. 缓存增强

• 统一缓存 key 规则
• 缓存写入时同步索引表
• 缓存命中时更新命中次数
• 增加缓存命中率统计

第二阶段验收标准

• 免费用户超额后会被正确拦截
• 后台可看到今日生成量
• 系统可统计缓存命中率
• 日志可追踪一次生成请求

第三阶段：可收费运营

8. 异步任务队列

• 选型 RQ 或 Celery
• 增加 async_task
• 长文本改为异步任务
• 返回 task_id
• 提供任务状态查询接口
• 失败任务支持重试

9. 管理员后台完善

• 增加仪表盘统计页
• 增加套餐管理页
• 增加用户套餐分配能力
• 增加 TTS 日志查看页
• 增加任务查看与重试页
• 增加缓存概览页

10. 监控与告警

• 采集 CPU、内存、磁盘指标
• 采集队列长度
• 采集错误率
• 搭建 Grafana 面板
• 增加基础告警规则

第三阶段验收标准

• 长文本不会阻塞主接口
• 管理员可查看任务状态和失败原因
• 系统可以看到资源占用和错误趋势

推荐工期

第 1 周

• 安全整改
• .env 改造
• 基础日志

第 2 周

• Docker 化
• 健康检查
• 部署文档

第 3 周

• 数据表扩展
• 配额和限流
• 用量统计

第 4 周

• 缓存索引
• 后台统计
• 基础运营能力

第 5-6 周

• 异步任务
• 管理后台增强

第 7-8 周

• 监控告警
• 压测与问题修复

风险提示

需要优先避免的问题

• 一边收费一边仍然使用弱密码体系
• 没有配额就开放大量生成
• 没有日志导致问题无法排查
• 没有缓存索引导致缓存失控

总结

技术实施建议先做“安全、部署、配额、日志”，再做“缓存、统计、后台”，最后做“任务队列和监控”。这个顺序能保证你尽快得到一个可公开、可控、可收费的系统，而不是先把架构做重。