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 账号（仅后台开启时需要）

访问

• 前端：http://localhost:5173
• 后端 API：http://localhost:8000
• Swagger 文档：http://localhost:8000/docs

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 有效且配额充足。