240 lines
5.5 KiB
Markdown
240 lines
5.5 KiB
Markdown
# Cosmo 后端配置说明
|
||
|
||
## 配置文件结构
|
||
|
||
```
|
||
backend/
|
||
├── .env # 实际配置文件（不提交到 Git）
|
||
├── .env.example # 配置模板（提交到 Git）
|
||
├── app/
|
||
│ └── config.py # 配置管理（Pydantic Settings）
|
||
└── scripts/
|
||
├── create_db.py # 创建数据库
|
||
├── init_db.py # 初始化表结构
|
||
└── setup.sh # 一键初始化脚本
|
||
```
|
||
|
||
## 配置项说明
|
||
|
||
### 1. PostgreSQL 数据库配置
|
||
|
||
```bash
|
||
DATABASE_HOST=localhost # 数据库主机
|
||
DATABASE_PORT=5432 # 数据库端口
|
||
DATABASE_NAME=cosmo_db # 数据库名称
|
||
DATABASE_USER=postgres # 数据库用户名
|
||
DATABASE_PASSWORD=postgres # 数据库密码
|
||
DATABASE_POOL_SIZE=20 # 连接池大小
|
||
DATABASE_MAX_OVERFLOW=10 # 连接池最大溢出数
|
||
```
|
||
|
||
**默认配置**：
|
||
- 账号和密码一致：`postgres/postgres`
|
||
- 本地数据库：`localhost:5432`
|
||
- 数据库名称：`cosmo_db`
|
||
|
||
### 2. Redis 缓存配置
|
||
|
||
```bash
|
||
REDIS_HOST=localhost # Redis 主机
|
||
REDIS_PORT=6379 # Redis 端口
|
||
REDIS_DB=0 # Redis 数据库编号（0-15）
|
||
REDIS_PASSWORD= # Redis 密码（留空表示无密码）
|
||
REDIS_MAX_CONNECTIONS=50 # 最大连接数
|
||
```
|
||
|
||
**默认配置**：
|
||
- 本地 Redis：`localhost:6379`
|
||
- 无密码认证
|
||
- 使用 0 号数据库
|
||
|
||
### 3. 应用配置
|
||
|
||
```bash
|
||
APP_NAME=COSMO - Deep Space Explorer
|
||
API_PREFIX=/api
|
||
CORS_ORIGINS=["*"] # 开发环境允许所有来源
|
||
CACHE_TTL_DAYS=3 # NASA API 缓存天数
|
||
```
|
||
|
||
### 4. 文件上传配置
|
||
|
||
```bash
|
||
UPLOAD_DIR=upload # 上传目录
|
||
MAX_UPLOAD_SIZE=10485760 # 最大文件大小（10MB）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 确保服务运行
|
||
|
||
确保本机已安装并启动 PostgreSQL 和 Redis：
|
||
|
||
```bash
|
||
# 检查 PostgreSQL
|
||
psql -U postgres -c "SELECT version();"
|
||
|
||
# 检查 Redis
|
||
redis-cli ping # 应返回 PONG
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
配置文件 `.env` 已经创建好了，默认配置如下：
|
||
- PostgreSQL: `postgres/postgres@localhost:5432/cosmo_db`
|
||
- Redis: `localhost:6379`（无密码）
|
||
|
||
如需修改，直接编辑 `backend/.env` 文件。
|
||
|
||
### 3. 安装依赖
|
||
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 4. 初始化数据库
|
||
|
||
```bash
|
||
# 方式一：使用一键脚本（推荐）
|
||
chmod +x scripts/setup.sh
|
||
./scripts/setup.sh
|
||
|
||
# 方式二：手动执行
|
||
python scripts/create_db.py # 创建数据库
|
||
python scripts/init_db.py # 初始化表结构
|
||
```
|
||
|
||
### 5. 启动服务
|
||
|
||
```bash
|
||
# 开发模式（自动重载）
|
||
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
|
||
# 或者直接运行
|
||
python app/main.py
|
||
```
|
||
|
||
访问：
|
||
- API 文档：http://localhost:8000/docs
|
||
- 健康检查：http://localhost:8000/health
|
||
|
||
## 配置验证
|
||
|
||
启动服务后，访问健康检查端点验证配置：
|
||
|
||
```bash
|
||
curl http://localhost:8000/health
|
||
```
|
||
|
||
正常响应示例：
|
||
```json
|
||
{
|
||
"status": "healthy",
|
||
"redis": {
|
||
"connected": true,
|
||
"used_memory_human": "1.2M",
|
||
"connected_clients": 2
|
||
},
|
||
"database": "connected"
|
||
}
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### PostgreSQL 连接失败
|
||
|
||
**问题**：`Connection refused` 或 `password authentication failed`
|
||
|
||
**解决方案**：
|
||
1. 确保 PostgreSQL 正在运行
|
||
2. 检查 `.env` 中的账号密码是否正确
|
||
3. 验证用户权限：
|
||
```bash
|
||
psql -U postgres -c "SELECT current_user;"
|
||
```
|
||
|
||
### Redis 连接失败
|
||
|
||
**问题**：Redis 连接失败但服务继续运行
|
||
|
||
**说明**：
|
||
- Redis 连接失败时，应用会自动降级为仅使用内存缓存
|
||
- 不影响核心功能，但会失去跨进程缓存能力
|
||
- 日志会显示警告：`⚠ Redis connection failed`
|
||
|
||
**解决方案**：
|
||
1. 确保 Redis 正在运行：`redis-cli ping`
|
||
2. 检查 Redis 端口：`lsof -i :6379`
|
||
3. 重启 Redis：
|
||
- macOS: `brew services restart redis`
|
||
- Linux: `sudo systemctl restart redis`
|
||
|
||
### 数据库已存在
|
||
|
||
**问题**：`database "cosmo_db" already exists`
|
||
|
||
**说明**：这是正常提示，不是错误。
|
||
|
||
**解决方案**：
|
||
- 如果需要重置数据库，先删除再创建：
|
||
```bash
|
||
psql -U postgres -c "DROP DATABASE cosmo_db;"
|
||
python scripts/create_db.py
|
||
python scripts/init_db.py
|
||
```
|
||
|
||
## 生产环境配置
|
||
|
||
生产环境建议修改以下配置：
|
||
|
||
```bash
|
||
# 安全配置
|
||
CORS_ORIGINS=["https://yourdomain.com"] # 限制跨域来源
|
||
|
||
# 数据库优化
|
||
DATABASE_POOL_SIZE=50 # 增加连接池大小
|
||
DATABASE_MAX_OVERFLOW=20
|
||
|
||
# Redis 密码
|
||
REDIS_PASSWORD=your_secure_password # 设置 Redis 密码
|
||
```
|
||
|
||
## 配置管理最佳实践
|
||
|
||
1. **不要提交 `.env` 文件到 Git**
|
||
- `.env` 已在 `.gitignore` 中
|
||
- 只提交 `.env.example` 作为模板
|
||
|
||
2. **使用环境变量覆盖**
|
||
```bash
|
||
export DATABASE_PASSWORD=new_password
|
||
python app/main.py
|
||
```
|
||
|
||
3. **多环境配置**
|
||
```bash
|
||
.env.development # 开发环境
|
||
.env.production # 生产环境
|
||
.env.test # 测试环境
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **FastAPI** - Web 框架
|
||
- **SQLAlchemy 2.0** - ORM（异步模式）
|
||
- **asyncpg** - PostgreSQL 异步驱动
|
||
- **Redis** - 缓存层
|
||
- **Pydantic Settings** - 配置管理
|
||
|
||
## 数据库设计
|
||
|
||
详细的数据库表结构设计请参考 [`DATABASE_SCHEMA.md`](./DATABASE_SCHEMA.md)。
|
||
|
||
主要数据表：
|
||
- `celestial_bodies` - 天体基本信息
|
||
- `positions` - 位置历史（时间序列）
|
||
- `resources` - 资源文件管理
|
||
- `static_data` - 静态天文数据
|
||
- `nasa_cache` - NASA API 缓存
|