cosmo_backend/CONFIG.md

# 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 缓存