xiaoxia-saas/docs/CONFIGURATION.md

# 环境配置指南

## 环境类型

小虾 SaaS 支持三种环境：

- **Development（开发环境）**：本地开发使用
- **Staging（测试环境）**：用于测试和预发布
- **Production（生产环境）**：正式生产环境

---

## 配置文件

### 1. `.env.example` - 配置模板
包含所有可配置项的示例，用于参考和初始化。

### 2. `.env` - 开发环境配置（本地）
本地开发时使用，不提交到 Git。

### 3. `.env.staging` - Staging 环境配置
测试环境配置，可以提交到 Git。

### 4. `.env.production` - 生产环境配置
生产环境配置，**敏感信息需要单独管理，不要提交到 Git**。

---

## 使用方法

### 方法 1：使用环境变量指定环境

```bash
# 开发环境（默认）
python -m uvicorn apps.api.main:app --reload

# Staging 环境
export APP_ENV=staging
python -m uvicorn apps.api.main:app --host 0.0.0.0 --port 8000

# 生产环境
export APP_ENV=production
python -m uvicorn apps.api.main:app --host 0.0.0.0 --port 8000
```

### 方法 2：直接指定配置文件

```bash
# 使用 .env.staging
cp .env.staging .env
python -m uvicorn apps.api.main:app

# 使用 .env.production
cp .env.production .env
python -m uvicorn apps.api.main:app
```

---

## 配置项说明

### 基础配置
- `APP_ENV`: 环境类型（development / staging / production）
- `APP_NAME`: 应用名称
- `DEBUG`: 是否启用调试模式

### API 配置
- `API_HOST`: API 监听地址
- `API_PORT`: API 端口
- `API_PREFIX`: API 路由前缀（如 /api/v1）

### 数据库配置
- `DATABASE_URL`: PostgreSQL 连接字符串
- `DATABASE_POOL_SIZE`: 连接池大小
- `DATABASE_MAX_OVERFLOW`: 最大溢出连接数
- `DATABASE_POOL_TIMEOUT`: 连接池超时时间（秒）
- `DATABASE_POOL_RECYCLE`: 连接回收时间（秒）

### Redis 配置
- `REDIS_URL`: Redis 连接字符串
- `REDIS_MAX_CONNECTIONS`: 最大连接数

### Celery 配置
- `CELERY_BROKER_URL`: Celery broker URL
- `CELERY_RESULT_BACKEND`: Celery result backend URL
- `CELERY_WORKER_CONCURRENCY`: Worker 并发数
- `CELERY_WORKER_MAX_TASKS_PER_CHILD`: 每个 worker 最大任务数

### OSS / 生成文件配置
- `OSS_ENDPOINT`: 阿里云 OSS endpoint
- `OSS_ACCESS_KEY_ID`: OSS AccessKey ID（未配置时上传类 OSS 操作不可用）
- `OSS_ACCESS_KEY_SECRET`: OSS AccessKey Secret
- `OSS_BUCKET_NAME`: OSS bucket 名称
- `GENERATED_FILES_URL_PREFIX`: 本地生成文件公开前缀，默认 `/generated-files`

说明：历史 MinIO 配置已退役；staging 当前支持 OSS 未配置时的本地 generated-files fallback。

### 日志配置
- `LOG_LEVEL`: 日志级别（DEBUG / INFO / WARNING / ERROR / CRITICAL）
- `LOG_FORMAT`: 日志格式（json / text）
- `LOG_FILE`: 日志文件路径

### CORS 配置
- `CORS_ORIGINS`: 允许的跨域来源（逗号分隔）
- `CORS_ALLOW_CREDENTIALS`: 是否允许携带凭证

### 安全配置
- `SECRET_KEY`: 应用密钥（用于 JWT 签名等）
- `ACCESS_TOKEN_EXPIRE_MINUTES`: 访问令牌过期时间
- `REFRESH_TOKEN_EXPIRE_DAYS`: 刷新令牌过期天数

---

## 生产环境最佳实践

### 1. 不要硬编码敏感信息
❌ 不要这样：
```python
DATABASE_URL = "postgresql://user:password@localhost/db"
```

✅ 应该这样：
```python
from app.core.config import get_settings
settings = get_settings()
database_url = settings.database_url
```

### 2. 使用环境变量覆盖
生产环境的敏感配置应该通过环境变量注入：

```bash
export DATABASE_URL="postgresql://user:secure_password@prod-db/db"
export JWT_SECRET_KEY="very-long-random-string"
export OSS_ACCESS_KEY_SECRET="another-secure-key"
```

### 3. 使用密钥管理工具
推荐使用：
- Docker Secrets
- Kubernetes Secrets
- AWS Secrets Manager
- HashiCorp Vault

### 4. 生产环境配置检查清单

- [ ] `DEBUG=false`
- [ ] `JWT_SECRET_KEY` 使用随机字符串（至少 32 字符）
- [ ] 数据库使用强密码
- [ ] OSS 凭证已配置，或明确保持本地 generated-files fallback
- [ ] `CORS_ORIGINS` 只包含信任的域名
- [ ] 日志级别设置为 `INFO` 或 `WARNING`
- [ ] 数据库连接池配置合理
- [ ] 启用 HTTPS（由 Nginx/网关层负责）

---

## Docker 部署配置

### Canonical Docker compose 中使用环境文件

```yaml
services:
  api:
    image: xiaoxia-saas-api:latest
    env_file:
      - .env.production
    environment:
      - DATABASE_URL=${DATABASE_URL}  # 从环境变量覆盖
```

### Gitea Actions 部署脚本

在 `.gitea/workflows/deploy.yml` 中：

```yaml
- name: Deploy to production
  run: |
    # 复制环境配置
    cp .env.production /var/lib/xiaoxia-saas-production/.env
    
    # 启动服务
    cd /var/lib/xiaoxia-saas-production/repo
    docker compose -f infra/docker/compose.yml up -d
```

---

## 配置验证

### 查看当前配置

```python
from app.core.config import get_settings

settings = get_settings()
print(f"Environment: {settings.app_env}")
print(f"Debug mode: {settings.debug}")
print(f"Database: {settings.database_url}")
print(f"Is production: {settings.is_production}")
```

### 配置测试脚本

```bash
# 测试开发环境配置
python -c "from app.core.config import get_settings; s=get_settings(); print(s.app_env)"

# 测试 staging 环境配置
APP_ENV=staging python -c "from app.core.config import get_settings; s=get_settings(); print(s.app_env)"

# 测试生产环境配置
APP_ENV=production python -c "from app.core.config import get_settings; s=get_settings(); print(s.app_env)"
```

---

## 常见问题

### Q: 为什么我的配置没有生效？
A: 检查：
1. 环境变量 `APP_ENV` 是否正确设置
2. 配置文件 `.env.{环境}` 是否存在
3. 环境变量名是否正确（大小写不敏感）
4. 是否重启了服务

### Q: 如何在 Docker 中使用环境配置？
A: 使用 `env_file` 或 `environment` 指定配置：
```yaml
services:
  api:
    env_file: .env.production
```

### Q: 生产环境如何保护敏感配置？
A: 
1. 不要提交 `.env.production` 到 Git
2. 使用 Docker Secrets 或 Kubernetes Secrets
3. 通过 CI/CD 注入环境变量
4. 使用密钥管理工具（Vault, AWS Secrets Manager 等）

---

## 相关文档

- [部署文档](DEPLOYMENT.md)
- [API 文档](API.md)
- [开发指南](DEVELOPMENT.md)