xiaoxia/xiaoxia-saas

Fork 0

Files

T

Xiaoxia AI ccb7e1e57a refactor(storage): retire minio runtime naming

2026-06-21 11:20:55 +08:00

6.1 KiB

Raw Permalink Blame History

环境配置指南

环境类型

小虾 SaaS 支持三种环境：

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

配置文件

1. `.env.example` - 配置模板

包含所有可配置项的示例，用于参考和初始化。

2. `.env` - 开发环境配置（本地）

本地开发时使用，不提交到 Git。

3. `.env.staging` - Staging 环境配置

测试环境配置，可以提交到 Git。

4. `.env.production` - 生产环境配置

生产环境配置，敏感信息需要单独管理，不要提交到 Git。

使用方法

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

# 开发环境（默认）
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：直接指定配置文件

# 使用 .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. 不要硬编码敏感信息

❌ 不要这样：

DATABASE_URL = "postgresql://user:password@localhost/db"

✅ 应该这样：

from app.core.config import get_settings
settings = get_settings()
database_url = settings.database_url

2. 使用环境变量覆盖

生产环境的敏感配置应该通过环境变量注入：

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 中使用环境文件

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

Gitea Actions 部署脚本

在 .gitea/workflows/deploy.yml 中：

- 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

配置验证

查看当前配置

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}")

配置测试脚本

# 测试开发环境配置
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: 检查：

环境变量 APP_ENV 是否正确设置
配置文件 .env.{环境} 是否存在
环境变量名是否正确（大小写不敏感）
是否重启了服务

Q: 如何在 Docker 中使用环境配置？

A: 使用 env_file 或 environment 指定配置：

services:
  api:
    env_file: .env.production

Q: 生产环境如何保护敏感配置？

不要提交 .env.production 到 Git
使用 Docker Secrets 或 Kubernetes Secrets
通过 CI/CD 注入环境变量
使用密钥管理工具（Vault, AWS Secrets Manager 等）

6.1 KiB Raw Permalink Blame History Unescape Escape