dreamweaver/README.md

# 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
```

## 快速开始
### 后端
```bash
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
```

### 前端
```bash
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` 是覆盖文件，不能单独使用。

### 常用命令

#### 开发模式（单机）
```bash
docker compose -f docker-compose.yml up -d
```

#### 开发 + HA（主从/哨兵演练）
```bash
docker compose -f docker-compose.yml -f docker-compose.ha.yml up -d
```

#### 生产模式（预构建镜像）
```bash
docker compose -f docker-compose.prod.yml up -d
```

#### 生产 + HA
```bash
docker compose -f docker-compose.prod.yml -f docker-compose.ha.yml up -d
```

#### 查看状态 / 日志
```bash
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
```

#### 停止并清理（含卷）
```bash
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 部署示例（推荐）：
```bash
export REGISTRY=my-registry.example.com/
export TAG=2026.02.12
docker compose -f docker-compose.prod.yml up -d
```

Windows PowerShell 示例：
```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) 准备配置
```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env，至少配置 SECRET_KEY、OAuth/API Key 等
```

#### 2) 启动（非 HA）
```bash
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）
```bash
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) 运行状态检查
```bash
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f backend
```
HA 场景使用：
```bash
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) 版本升级
```bash
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) 版本回滚
```bash
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 有效且配额充足。