Files

zhangtuo c82d408ea1 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

2026-02-28 14:57:02 +08:00

6.7 KiB

Raw Blame History

DreamWeaver

AI 驱动的儿童故事生成应用，面向 3-8 岁儿童提供个性化童话创作。

技术栈

后端：FastAPI、SQLAlchemy (async)、PostgreSQL，OAuth (GitHub/Google)
AI：文本生成、图像生成、语音合成（可替换适配器）
前端：Vue 3、TypeScript、Pinia、Vue Router、Vite

仓库结构

backend/
  app/               # 后端代码
  alembic/           # 数据库迁移
  pyproject.toml
  .env.example
frontend/
  src/               # 前端代码
  package.json

快速开始

后端

cd backend
python -m venv .venv
.\.venv\Scripts\activate  # Linux/Mac: source .venv/bin/activate
pip install -e .

cp .env.example .env      # 填写 SECRET_KEY、DATABASE_URL、各 API Key

# 运行数据库迁移（先配置好 DATABASE_URL）
alembic upgrade head

# 启动
uvicorn app.main:app --reload --port 8000

前端

cd frontend
npm install
npm run dev

前端常用环境变量（可放 .env.development）：

VITE_API_BASE：后端地址，例如 http://localhost:8000
VITE_ADMIN_USER / VITE_ADMIN_PASS：管理后台 Basic Auth 账号（仅后台开启时需要）

访问

Docker Compose 使用说明

本项目包含 3 个 compose 文件：

docker-compose.yml：开发基线，包含本地构建（build）配置，适合日常开发调试。
docker-compose.prod.yml：生产基线，使用预构建镜像（不本地构建），适合部署环境。
docker-compose.ha.yml：HA 覆盖层，提供 PostgreSQL 主从、Redis 主从 + Sentinel、备份任务。

使用选择

本地开发：使用 docker-compose.yml
生产部署：使用 docker-compose.prod.yml
需要高可用：在上面任一基线上叠加 docker-compose.ha.yml

注意：docker-compose.ha.yml 是覆盖文件，不能单独使用。

常用命令

开发模式（单机）

docker compose -f docker-compose.yml up -d

开发 + HA（主从/哨兵演练）

docker compose -f docker-compose.yml -f docker-compose.ha.yml up -d

生产模式（预构建镜像）

docker compose -f docker-compose.prod.yml up -d

生产 + HA

docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml up -d

查看状态 / 日志

docker compose -f docker-compose.yml -f docker-compose.ha.yml ps
docker compose -f docker-compose.yml -f docker-compose.ha.yml logs -f backend

停止并清理（含卷）

docker compose -f docker-compose.yml -f docker-compose.ha.yml down -v

`docker-compose.prod.yml` 镜像标签

docker-compose.prod.yml 使用以下镜像格式：

${REGISTRY:-}dreamweaver-backend:${TAG:-latest}
${REGISTRY:-}dreamweaver-frontend:${TAG:-latest}
${REGISTRY:-}dreamweaver-admin-frontend:${TAG:-latest}

Linux 部署示例（推荐）：

export REGISTRY=my-registry.example.com/
export TAG=2026.02.12
docker compose -f docker-compose.prod.yml up -d

Windows PowerShell 示例：

$env:REGISTRY="my-registry.example.com/"
$env:TAG="2026.02.12"
docker compose -f docker-compose.prod.yml up -d

Linux 服务器部署流程（推荐）

以下流程适用于 Ubuntu/CentOS 等 Linux 服务器：

1) 准备配置

cp backend/.env.example backend/.env
# 编辑 backend/.env，至少配置 SECRET_KEY、OAuth/API Key 等

2) 启动（非 HA）

export REGISTRY=my-registry.example.com/
export TAG=2026.02.12
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

3) 启动（HA）

export REGISTRY=my-registry.example.com/
export TAG=2026.02.12
docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml pull
docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml up -d

4) 运行状态检查

docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f backend

HA 场景使用：

docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml ps
docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml logs -f backend

5) 版本升级

export TAG=2026.02.13
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

HA 场景同理，在命令中额外叠加 -f docker-compose.ha.yml。

6) 版本回滚

export TAG=2026.02.12
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

供应商路由与管理后台

路由按配置顺序尝试：TEXT_PROVIDERS（默认 text_primary）、IMAGE_PROVIDERS（默认 image_primary）、TTS_PROVIDERS（默认 tts_primary）。失败会自动切换下一个。
管理后台（默认关闭）：ENABLE_ADMIN_CONSOLE=true 时启用，接口在 /admin/providers（CRUD）和 /admin/providers/reload。鉴权使用 Basic Auth，账号密码由 ADMIN_USERNAME/ADMIN_PASSWORD 设置（请覆盖默认值）。
建议后台放在受保护子域并在反代层加 Basic Auth/IP 白名单；生产环境默认关闭。
前端最小管理页：/admin/providers，仅后台开启时可用，使用上面的 Basic Auth 调用。

数据库迁移（Alembic）

运行迁移：alembic upgrade head
生成新迁移：alembic revision -m "message" --autogenerate 迁移脚本位于 backend/alembic/versions/，包含 providers 表和 stories.mode 字段。

主要 API

方法	路径	说明
GET	`/auth/github/signin`	GitHub 登录
GET	`/auth/google/signin`	Google 登录
GET	`/auth/session`	当前会话
POST	`/api/generate`	生成/润色故事
POST	`/api/image/generate/{id}`	生成封面图
GET	`/api/audio/{id}`	获取 TTS 音频
GET	`/api/stories`	获取故事列表（分页）
GET	`/api/stories/{id}`	获取故事详情
DELETE	`/api/stories/{id}`	删除故事
GET	`/admin/providers`	Provider 列表（需后台开启 + 管理员）

环境变量

常用项（详见 backend/.env.example）：

SECRET_KEY（必填）：JWT 签名密钥
DATABASE_URL（必填）：PostgreSQL 连接串
OAuth：GITHUB_CLIENT_ID/SECRET，GOOGLE_CLIENT_ID/SECRET
AI Keys：TEXT_API_KEY，TTS_API_BASE，TTS_API_KEY，IMAGE_API_KEY
Provider 列表：TEXT_PROVIDERS，IMAGE_PROVIDERS，TTS_PROVIDERS
管理后台：ENABLE_ADMIN_CONSOLE，ADMIN_USERNAME，ADMIN_PASSWORD

注意

生产务必使用强随机 SECRET_KEY，并关闭 ENABLE_ADMIN_CONSOLE（或放在受保护子域/内网）。
路由会按配置/DB 顺序尝试供应商并失败切换，请确保各 Key 有效且配额充足。

6.7 KiB Raw Blame History Unescape Escape