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 数据库配置

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 缓存配置

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. 应用配置

APP_NAME=COSMO - Deep Space Explorer
API_PREFIX=/api
CORS_ORIGINS=["*"]            # 开发环境允许所有来源
CACHE_TTL_DAYS=3              # NASA API 缓存天数

4. 文件上传配置

UPLOAD_DIR=upload              # 上传目录
MAX_UPLOAD_SIZE=10485760       # 最大文件大小（10MB）

快速开始

1. 确保服务运行

确保本机已安装并启动 PostgreSQL 和 Redis：

# 检查 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. 安装依赖

cd backend
pip install -r requirements.txt

4. 初始化数据库

# 方式一：使用一键脚本（推荐）
chmod +x scripts/setup.sh
./scripts/setup.sh

# 方式二：手动执行
python scripts/create_db.py    # 创建数据库
python scripts/init_db.py      # 初始化表结构

5. 启动服务

# 开发模式（自动重载）
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

配置验证

启动服务后，访问健康检查端点验证配置：

curl http://localhost:8000/health

正常响应示例：

{
  "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. 验证用户权限：

   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

说明：这是正常提示，不是错误。

解决方案：

• 如果需要重置数据库，先删除再创建：

  psql -U postgres -c "DROP DATABASE cosmo_db;"
  python scripts/create_db.py
  python scripts/init_db.py
  

生产环境配置

生产环境建议修改以下配置：

# 安全配置
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. 使用环境变量覆盖

   export DATABASE_PASSWORD=new_password
   python app/main.py
   

3. 多环境配置

   .env.development    # 开发环境
   .env.production     # 生产环境
   .env.test           # 测试环境
   

技术栈

• FastAPI - Web 框架
• SQLAlchemy 2.0 - ORM（异步模式）
• asyncpg - PostgreSQL 异步驱动
• Redis - 缓存层
• Pydantic Settings - 配置管理

数据库设计

详细的数据库表结构设计请参考 DATABASE_SCHEMA.md。

主要数据表：

• celestial_bodies - 天体基本信息
• positions - 位置历史（时间序列）
• resources - 资源文件管理
• static_data - 静态天文数据
• nasa_cache - NASA API 缓存