feat: add HA infrastructure, CI/CD pipeline, and Redis/Celery hardening
- 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
This commit is contained in:
zhangtuo
89
backend/docs/ha_runbook.md
Normal file
89
backend/docs/ha_runbook.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# HA 部署与验证 Runbook（Phase 3 MVP）
|
||||
|
||||
本文档对应 `docker-compose.ha.yml`，用于本地/测试环境验证高可用基础能力。
|
||||
|
||||
## 1. 启动方式
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.ha.yml up -d
|
||||
```
|
||||
|
||||
说明：
|
||||
- 基础业务服务仍来自 `docker-compose.yml`。
|
||||
- `docker-compose.ha.yml` 覆盖了 `db`、`redis`，并新增 `db-replica`、`postgres-backup`、`redis-replica`、`redis-sentinel-*`。
|
||||
|
||||
## 2. 核心环境变量建议
|
||||
|
||||
在 `backend/.env`（或 shell 环境）中至少配置：
|
||||
|
||||
```env
|
||||
# PostgreSQL
|
||||
POSTGRES_USER=dreamweaver
|
||||
POSTGRES_PASSWORD=dreamweaver_password
|
||||
POSTGRES_DB=dreamweaver_db
|
||||
POSTGRES_REPMGR_PASSWORD=repmgr_password
|
||||
|
||||
# Redis Sentinel
|
||||
REDIS_SENTINEL_ENABLED=true
|
||||
REDIS_SENTINEL_NODES=redis-sentinel-1:26379,redis-sentinel-2:26379,redis-sentinel-3:26379
|
||||
REDIS_SENTINEL_MASTER_NAME=mymaster
|
||||
REDIS_SENTINEL_DB=0
|
||||
REDIS_SENTINEL_SOCKET_TIMEOUT=0.5
|
||||
|
||||
# 可选：若 Sentinel/Redis 设置了密码
|
||||
REDIS_SENTINEL_PASSWORD=
|
||||
|
||||
# 备份周期，默认 86400 秒（1 天）
|
||||
BACKUP_INTERVAL_SECONDS=86400
|
||||
```
|
||||
|
||||
## 3. 健康检查
|
||||
|
||||
### 3.1 PostgreSQL 主从
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.ha.yml ps
|
||||
docker exec -it dreamweaver_db_primary psql -U dreamweaver -d dreamweaver_db -c "select now();"
|
||||
docker exec -it dreamweaver_db_replica psql -U dreamweaver -d dreamweaver_db -c "select pg_is_in_recovery();"
|
||||
```
|
||||
|
||||
期望：
|
||||
- 主库可读写；
|
||||
- 从库 `pg_is_in_recovery()` 返回 `t`。
|
||||
|
||||
### 3.2 Redis Sentinel
|
||||
|
||||
```bash
|
||||
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel masters
|
||||
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel replicas mymaster
|
||||
```
|
||||
|
||||
期望：
|
||||
- `mymaster` 存在；
|
||||
- 至少 1 个 replica 被发现。
|
||||
|
||||
### 3.3 备份任务
|
||||
|
||||
```bash
|
||||
docker exec -it dreamweaver_postgres_backup sh -c "ls -lh /backups"
|
||||
```
|
||||
|
||||
期望：
|
||||
- `/backups` 下出现 `.dump` 文件；
|
||||
- 旧于 7 天的备份会被自动清理。
|
||||
|
||||
## 4. 故障切换演练（最小）
|
||||
|
||||
```bash
|
||||
# 模拟 Redis 主节点故障
|
||||
docker stop dreamweaver_redis_master
|
||||
|
||||
# 等待 Sentinel 选主后查看
|
||||
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel get-master-addr-by-name mymaster
|
||||
```
|
||||
|
||||
提示：应用与 Celery 已支持 Sentinel 配置。若未启用 Sentinel，仍可回退到 `REDIS_URL` / `CELERY_BROKER_URL` / `CELERY_RESULT_BACKEND` 直连模式。
|
||||
|
||||
## 5. 当前已知限制（下一步）
|
||||
|
||||
- PostgreSQL 侧当前仅完成主从拓扑，读写分离（PgBouncer/路由）待后续迭代。
|
||||
@@ -19,25 +19,25 @@
|
||||
目前 `backend`, `backend-admin`, `worker`, `celery-beat` 重复构建 4 次，浪费资源且镜像版本可能不一致。
|
||||
|
||||
- **Action Items**:
|
||||
- [ ] 修改 `backend/Dockerfile` 为通用基础镜像。
|
||||
- [ ] 更新 `docker-compose.yml`，定义 `backend-base` 服务或使用 `image` 标签共享镜像。
|
||||
- [ ] 确保所有 Python 服务共用同一构建产物，仅启动命令不同。
|
||||
- [x] 修改 `backend/Dockerfile` 为通用基础镜像。
|
||||
- [x] 更新 `docker-compose.yml`，定义 `backend-base` 服务或使用 `image` 标签共享镜像。
|
||||
- [x] 确保所有 Python 服务共用同一构建产物，仅启动命令不同。
|
||||
|
||||
### 2.2 修复 Provider 缓存与限流 (High Priority)
|
||||
内存缓存 (`TTLCache`, `_latency_cache`) 在多进程/多实例下失效。
|
||||
|
||||
- **Action Items**:
|
||||
- [ ] 引入 Redis 作为共享缓存后端。
|
||||
- [ ] 重构 `_load_provider_cache`，将 Provider 配置缓存至 Redis。
|
||||
- [ ] 重构 `stories.py` 中的限流逻辑，使用 `redis-cell` 或简单的 Redis 计数器替代 `TTLCache`。
|
||||
- [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**:
|
||||
- [ ] 创建 `app/services/story_service.py`，迁移生成、润色、PDF生成等核心逻辑。
|
||||
- [ ] 创建 `app/schemas/story_schema.py`，迁移 Pydantic 模型（`GenerateRequest`, `StoryResponse` 等）。
|
||||
- [ ] API 层 `stories.py` 仅保留路由定义和依赖注入，调用 Service 层。
|
||||
- [x] 创建 `app/services/story_service.py`，迁移生成、润色、PDF生成等核心逻辑。
|
||||
- [x] 创建 `app/schemas/story_schemas.py`，迁移 Pydantic 模型（`GenerateRequest`, `StoryResponse` 等）。
|
||||
- [x] API 层 `stories.py` 仅保留路由定义和依赖注入，调用 Service 层。
|
||||
|
||||
---
|
||||
|
||||
@@ -68,6 +68,17 @@ Redis 单点故障将导致 Celery 任务全盘停摆。
|
||||
- [ ] 部署 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. 长期架构演进 (季度规划)
|
||||
|
||||
Reference in New Issue
Block a user