c82d408ea1
- Add docker-compose.ha.yml for PostgreSQL/Redis HA setup with Patroni and Sentinel - Add docker-compose.prod.yml for production deployment - Add GitHub Actions CI/CD workflow (build.yml) - Add install.cmd for Windows one-click setup - Harden Redis connection with retry logic and health checks - Add Celery HA config with Redis Sentinel support - Add HA operations runbook - Update README with deployment and architecture docs - Move landing page spec to .claude/specs/design/ - Update memory intelligence PRD
110 lines
4.8 KiB
Markdown
110 lines
4.8 KiB
Markdown
# DreamWeaver 重构实施计划
|
||
|
||
## 1. 概述
|
||
|
||
本文档基于对当前架构的深入分析，制定了从稳定性、可维护性到可扩展性的分阶段重构计划。
|
||
|
||
**目标**：
|
||
- **短期**：解决单点故障风险，优化开发体验，清理关键技术债。
|
||
- **中期**：提升系统高可用能力，增强监控与可观测性。
|
||
- **长期**：架构演进，支持大规模并发与复杂业务场景。
|
||
|
||
---
|
||
|
||
## 2. 短期优化计划 (1-2周)
|
||
|
||
**重点**：消除即时风险，提升部署效率。
|
||
|
||
### 2.1 统一镜像构建 (High Priority)
|
||
目前 `backend`, `backend-admin`, `worker`, `celery-beat` 重复构建 4 次，浪费资源且镜像版本可能不一致。
|
||
|
||
- **Action Items**:
|
||
- [x] 修改 `backend/Dockerfile` 为通用基础镜像。
|
||
- [x] 更新 `docker-compose.yml`，定义 `backend-base` 服务或使用 `image` 标签共享镜像。
|
||
- [x] 确保所有 Python 服务共用同一构建产物，仅启动命令不同。
|
||
|
||
### 2.2 修复 Provider 缓存与限流 (High Priority)
|
||
内存缓存 (`TTLCache`, `_latency_cache`) 在多进程/多实例下失效。
|
||
|
||
- **Action Items**:
|
||
- [x] 引入 Redis 作为共享缓存后端。
|
||
- [x] 重构 `_load_provider_cache`，将 Provider 配置缓存至 Redis。
|
||
- [x] 重构 `stories.py` 中的限流逻辑，使用 `redis-cell` 或简单的 Redis 计数器替代 `TTLCache`。
|
||
|
||
### 2.3 拆分 `stories.py` (Medium Priority)
|
||
`app/api/stories.py` 超过 600 行，包含 API 定义、业务逻辑、验证逻辑，维护困难。
|
||
|
||
- **Action Items**:
|
||
- [x] 创建 `app/services/story_service.py`，迁移生成、润色、PDF生成等核心逻辑。
|
||
- [x] 创建 `app/schemas/story_schemas.py`，迁移 Pydantic 模型（`GenerateRequest`, `StoryResponse` 等）。
|
||
- [x] API 层 `stories.py` 仅保留路由定义和依赖注入，调用 Service 层。
|
||
|
||
---
|
||
|
||
## 3. 中期优化计划 (1-2月)
|
||
|
||
**重点**：高可用 (HA) 与系统韧性。
|
||
|
||
### 3.1 数据库高可用 (Critical)
|
||
当前 PostgreSQL 为单点，且 Admin/User 混合使用。
|
||
|
||
- **Action Items**:
|
||
- [ ] 部署 PostgreSQL 主从复制 (Master-Slave)。
|
||
- [ ] 配置 `PgBouncer` 或 SQLAlchemy 读写分离，减轻主库压力。
|
||
- [ ] 实施数据库自动备份策略 (如 `pg_dump` 定时上传 S3)。
|
||
|
||
### 3.2 消息队列高可用 (Critical)
|
||
Redis 单点故障将导致 Celery 任务全盘停摆。
|
||
|
||
- **Action Items**:
|
||
- [ ] 迁移至 Redis Sentinel 或 Redis Cluster 模式。
|
||
- [ ] 更新 Celery 配置以支持 Sentinel/Cluster 连接串。
|
||
|
||
### 3.3 增强可观测性 (Important)
|
||
目前仅有简单的日志，缺乏系统级指标。
|
||
|
||
- **Action Items**:
|
||
- [ ] 集成 Prometheus Client，暴露 `/metrics` 端点。
|
||
- [ ] 部署 Grafana + Prometheus，监控 API 延迟、QPS、Celery 队列积压情况。
|
||
- [ ] 完善 `ProviderMetrics`，增加可视化大盘，实时监控 AI 供应商的成本与成功率。
|
||
|
||
### 3.4 Phase 3 最小可执行任务清单 (MVP)
|
||
|
||
目标：在不大改业务代码的前提下，于一个迭代内完成高可用基础设施闭环。
|
||
|
||
- [x] PostgreSQL 主从：新增 `docker-compose.ha.yml`，包含 1 主 1 从与健康检查。
|
||
- [x] PostgreSQL 备份：新增每日备份任务（`pg_dump`）与 7 天保留策略。
|
||
- [x] Redis Sentinel：新增 1 主 2 哨兵最小拓扑，并验证故障切换。
|
||
- [x] Celery 连接：更新 Celery broker/result backend 配置，支持 Sentinel 连接串。
|
||
- [x] 回归验证：执行一次故事生成 + 异步任务链路（worker/beat）冒烟测试。
|
||
- [x] 运行手册：补充故障切换与恢复步骤文档（PostgreSQL/Redis/Celery）。
|
||
|
||
---
|
||
|
||
## 4. 长期架构演进 (季度规划)
|
||
|
||
**重点**：业务解耦与规模化。
|
||
|
||
### 4.1 统一 API 网关
|
||
- **当前**：前端直连后端端口，CORS 配置分散。
|
||
- **演进**：引入 Traefik 或 Nginx 作为统一网关，管理路由、SSL、全局限流、统一鉴权。
|
||
|
||
### 4.2 前端工程合并
|
||
- **当前**：User App 和 Admin Console 是完全独立的两个项目，但在组件和工具链上高度重复。
|
||
- **演进**：使用一种 Monorepo 策略或基于路由的单一应用策略，共享组件库和类型定义，减少维护成本。
|
||
|
||
### 4.3 事件驱动架构完善
|
||
- **当前**：部分业务逻辑耦合在 API 中。
|
||
- **演进**：扩展事件总线，将“阅读记录”、“成就解锁”、“通知推送”等非核心链路完全异步化，通过 Domain Events 解耦。
|
||
|
||
---
|
||
|
||
## 5. 实施路线图
|
||
|
||
| 阶段 | 时间估算 | 关键里程碑 |
|
||
| :--- | :--- | :--- |
|
||
| **Phase 1: 基础夯实** | Week 1-2 | Docker 构建优化上线，Redis 替代内存缓存。 |
|
||
| **Phase 2: 代码重构** | Week 3-4 | `stories.py` 拆分完成，Service 层建立。 |
|
||
| **Phase 3: 高可用建设** | Month 2 | 数据库与 Redis 实现主备/集群模式。 |
|
||
| **Phase 4: 监控体系** | Month 2 | Grafana 监控大盘上线，关键指标报警配置完毕。 |
|