Xiaoxia AI
216 lines
4.0 KiB
Markdown
216 lines
4.0 KiB
Markdown
# 数据库切换指南
|
||
|
||
## 📚 概述
|
||
|
||
小虾 SaaS 支持两种数据存储方式：
|
||
1. **InMemory（内存数据库）** - 开发和测试环境
|
||
2. **PostgreSQL** - 生产环境
|
||
|
||
通过环境变量 `USE_IN_MEMORY_DB` 控制。
|
||
|
||
---
|
||
|
||
## 🔄 快速切换
|
||
|
||
### 方式 1: 环境变量
|
||
|
||
在 `.env` 文件中设置：
|
||
|
||
```env
|
||
# 使用内存数据库（开发/测试）
|
||
USE_IN_MEMORY_DB=true
|
||
|
||
# 使用 PostgreSQL（生产）
|
||
USE_IN_MEMORY_DB=false
|
||
DATABASE_URL=postgresql://user:pass@localhost:5432/xiaoxia_saas
|
||
```
|
||
|
||
### 方式 2: 启动时指定
|
||
|
||
```bash
|
||
# 使用内存数据库
|
||
USE_IN_MEMORY_DB=true uvicorn apps.api.main:app --reload
|
||
|
||
# 使用 PostgreSQL
|
||
USE_IN_MEMORY_DB=false uvicorn apps.api.main:app --reload
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 InMemory 数据库
|
||
|
||
**特点：**
|
||
- ✅ 无需安装 PostgreSQL
|
||
- ✅ 无需数据库迁移
|
||
- ✅ 快速启动
|
||
- ✅ 适合开发和测试
|
||
- ❌ 重启后数据丢失
|
||
- ❌ 不适合生产环境
|
||
|
||
**使用场景：**
|
||
- 本地开发
|
||
- 单元测试
|
||
- 集成测试
|
||
- 快速原型验证
|
||
|
||
**启动：**
|
||
```bash
|
||
# 设置环境变量
|
||
export USE_IN_MEMORY_DB=true
|
||
|
||
# 启动服务
|
||
uvicorn apps.api.main:app --reload
|
||
```
|
||
|
||
---
|
||
|
||
## 🗄️ PostgreSQL 数据库
|
||
|
||
**特点：**
|
||
- ✅ 数据持久化
|
||
- ✅ 支持事务
|
||
- ✅ 生产就绪
|
||
- ✅ 支持并发
|
||
- ❌ 需要安装 PostgreSQL
|
||
- ❌ 需要运行数据库迁移
|
||
|
||
**使用场景：**
|
||
- 生产环境
|
||
- 预发布环境
|
||
- 需要数据持久化的场景
|
||
|
||
**设置步骤：**
|
||
|
||
1. **安装 PostgreSQL**
|
||
```bash
|
||
# Ubuntu
|
||
sudo apt-get install postgresql
|
||
|
||
# macOS
|
||
brew install postgresql
|
||
```
|
||
|
||
2. **创建数据库**
|
||
```bash
|
||
sudo -u postgres psql
|
||
CREATE DATABASE xiaoxia_saas;
|
||
CREATE USER xiaoxia_user WITH PASSWORD 'your_password';
|
||
GRANT ALL PRIVILEGES ON DATABASE xiaoxia_saas TO xiaoxia_user;
|
||
\q
|
||
```
|
||
|
||
3. **运行 Alembic 迁移**
|
||
```bash
|
||
alembic upgrade head
|
||
```
|
||
|
||
4. **配置环境变量**
|
||
```env
|
||
USE_IN_MEMORY_DB=false
|
||
DATABASE_URL=postgresql://xiaoxia_user:password@localhost:5432/xiaoxia_saas
|
||
```
|
||
|
||
5. **启动服务**
|
||
```bash
|
||
uvicorn apps.api.main:app --reload
|
||
```
|
||
|
||
---
|
||
|
||
## 🐳 Docker 环境
|
||
|
||
### Canonical Docker Compose（自动配置 PostgreSQL）
|
||
|
||
```bash
|
||
# 自动启动 PostgreSQL 和应用
|
||
WEB_PORT=3001 docker compose -f infra/docker/compose.yml up -d --build
|
||
|
||
# 查看日志
|
||
docker compose -f infra/docker/compose.yml logs -f api
|
||
```
|
||
|
||
`infra/docker/compose.yml` 是当前唯一有效 compose 入口；根目录 `docker-compose.yml` 已退役。
|
||
|
||
---
|
||
|
||
## 🧪 测试环境
|
||
|
||
### 单元测试（推荐 InMemory）
|
||
|
||
```python
|
||
# tests/conftest.py
|
||
import os
|
||
os.environ['USE_IN_MEMORY_DB'] = 'true'
|
||
```
|
||
|
||
### 集成测试（可选 PostgreSQL）
|
||
|
||
```bash
|
||
# 使用 PostgreSQL 进行集成测试
|
||
USE_IN_MEMORY_DB=false pytest tests/integration -v
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 实现原理
|
||
|
||
依赖注入容器根据配置自动选择：
|
||
|
||
```python
|
||
# apps/api/app/dependencies.py
|
||
@property
|
||
def user_repository(self):
|
||
if settings.USE_IN_MEMORY_DB:
|
||
return InMemoryUserRepository()
|
||
else:
|
||
return PostgresUserRepository(settings.DATABASE_URL)
|
||
```
|
||
|
||
**优点：**
|
||
- 业务逻辑无需改动
|
||
- 切换透明
|
||
- 测试隔离
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **数据不兼容**
|
||
- InMemory 和 PostgreSQL 之间无法直接迁移数据
|
||
- 切换前请备份重要数据
|
||
|
||
2. **性能差异**
|
||
- InMemory 更快（无 I/O）
|
||
- PostgreSQL 支持更大数据量
|
||
|
||
3. **并发支持**
|
||
- InMemory 不支持多进程
|
||
- PostgreSQL 支持多进程和集群
|
||
|
||
4. **环境一致性**
|
||
- 开发环境建议使用 InMemory
|
||
- 生产环境必须使用 PostgreSQL
|
||
|
||
---
|
||
|
||
## 🚀 最佳实践
|
||
|
||
1. **开发流程**
|
||
```
|
||
开发（InMemory） → 测试（InMemory） → 预发布（PostgreSQL） → 生产（PostgreSQL）
|
||
```
|
||
|
||
2. **配置管理**
|
||
- 使用 `.env` 文件管理配置
|
||
- 不要提交 `.env` 到版本控制
|
||
- 使用 `.env.example` 作为模板
|
||
|
||
3. **数据库迁移**
|
||
- 所有 schema 变更都要有迁移脚本
|
||
- 迁移脚本要幂等（可多次执行）
|
||
- 测试迁移脚本后再应用到生产
|
||
|
||
---
|
||
|
||
**最后更新:** 2026-06-17
|