From 9a852a4a125f5187e4307d6778423bcd79331500 Mon Sep 17 00:00:00 2001 From: xiaoxia Date: Thu, 23 Jul 2026 23:15:38 +0800 Subject: [PATCH] =?UTF-8?q?docs(#780):=20=E8=A1=A5=E9=BD=90.env.example?= =?UTF-8?q?=E7=BC=BA=E5=A4=B1=E7=9A=8430+=E9=85=8D=E7=BD=AE=E9=A1=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 梳理所有配置文件（shared/api/worker），完整列出全部环境变量： - 新增：数据库连接池配置（pool_size/max_overflow/timeout/recycle） - 新增：Celery broker/backend 配置 - 新增：Worker 并发/子进程数 配置 - 新增：OSS 直传大小/过期时间 配置 - 新增：豆包大模型（Doubao）配置 - 新增：CosyVoice 克隆模型配置 - 新增：渲染引擎选择（RENDER_ENGINE） - 新增：邮件投递开关 / SMTP TLS / API 端口等零散配置 - 每个配置补充用途注释和默认值说明 - 顶部增加配置读取优先级说明 --- .env.example | 222 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 180 insertions(+), 42 deletions(-) diff --git a/.env.example b/.env.example index 60efca990..01139df98 100755 --- a/.env.example +++ b/.env.example @@ -1,60 +1,198 @@ -# 小虾 SaaS 环境变量配置 +# ============================================================ +# 小虾 SaaS 环境变量完整配置 +# ============================================================ +# 本文件列出所有可配置的环境变量及默认值。 +# 复制为 .env 后按需修改；生产环境务必覆盖所有密钥类配置。 +# +# 配置读取规则（pydantic-settings，大小写不敏感）： +# 1. 系统环境变量（最高优先级） +# 2. .env.{APP_ENV} 文件（如 .env.staging） +# 3. .env 文件 +# 4. 代码中的默认值（最低优先级） +# ============================================================ -# ==================== 应用配置 ==================== -APP_NAME=小虾 SaaS -APP_BASE_URL=http://localhost:3000 + +# ==================== 应用基本配置 ==================== + +# 应用名称 +APP_NAME=xiaoxia-saas + +# 应用版本号（展示用，代码中已内置默认） +APP_VERSION=0.1.61 + +# 环境标识：development / staging / production +# 决定读取 .env.{APP_ENV} 还是 .env，也影响部分配置的严格校验 APP_ENV=development -# ==================== 数据库配置 ==================== -DATABASE_URL=postgresql://xiaoxia_user:your_password@localhost:5432/xiaoxia_saas - -# 开发环境：使用内存数据库（不需要 PostgreSQL） -USE_IN_MEMORY_DB=true - -# 生产环境：使用 PostgreSQL -# USE_IN_MEMORY_DB=false - -# ==================== Redis 配置 ==================== -REDIS_URL=redis://localhost:6379/0 - -# ==================== JWT 配置 ==================== -JWT_SECRET_KEY=your-super-secret-key-change-this-in-production-min-32-chars -JWT_ALGORITHM=HS256 -JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30 -JWT_REFRESH_TOKEN_EXPIRE_DAYS=30 - -# ==================== 邮件配置 ==================== -SMTP_HOST=smtp.gmail.com -SMTP_PORT=587 -SMTP_USER=your-email@gmail.com -SMTP_PASSWORD=your-app-specific-password -SMTP_FROM_EMAIL=noreply@xiaoxia-saas.com -SMTP_FROM_NAME=小虾 SaaS - -# ==================== 环境配置 ==================== -ENVIRONMENT=development +# 是否开启 Debug 模式（开发环境 true，生产环境 false） DEBUG=true -# ==================== CORS 配置 ==================== -# 逗号分隔的域名列表（Settings 读取 CORS_ORIGINS_RAW） -CORS_ORIGINS_RAW=http://localhost:3000,http://localhost:5173 +# 应用基础 URL，用于生成认证邮件、回调链接等 +APP_BASE_URL=http://localhost:3000 + +# API 服务监听地址（容器内绑定，外部暴露由 Docker/Nginx 控制） +API_HOST=0.0.0.0 + +# API 服务监听端口 +API_PORT=8000 + +# 是否自动创建数据库表结构（开发环境可开启，生产环境用 alembic migration） +AUTO_CREATE_SCHEMA=false + + +# ==================== 数据库配置 ==================== + +# 数据库连接串（格式：postgresql+psycopg://user:password@host:port/dbname） +DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas + +# 连接池大小（常驻连接数） +DATABASE_POOL_SIZE=20 + +# 连接池最大溢出连接数（pool_size + max_overflow = 最大并发连接数） +DATABASE_MAX_OVERFLOW=10 + +# 获取连接超时时间（秒） +DATABASE_POOL_TIMEOUT=30 + +# 连接回收时间（秒），防止数据库端主动断开导致的死连接 +DATABASE_POOL_RECYCLE=3600 + +# 是否使用内存数据库（SQLite，仅开发/测试可用；生产务必 false） +USE_IN_MEMORY_DB=false + + +# ==================== Redis 配置 ==================== + +# Redis 连接 URL（格式：redis://[:password@]host:port/db） +REDIS_URL=redis://localhost:6379/0 + +# 是否使用 Redis 存储 Session（多实例部署时必须开启；开发可用内存存储） +ENABLE_REDIS_SESSIONS=false + + +# ==================== Celery 任务队列 ==================== + +# Celery Broker（任务分发），默认用 Redis db0 +CELERY_BROKER_URL=redis://localhost:6379/0 + +# Celery Result Backend（任务结果存储），默认用 Redis db1 +CELERY_RESULT_BACKEND=redis://localhost:6379/1 + + +# ==================== Worker 配置 ==================== + +# Worker 进程名称 +WORKER_NAME=xiaoxia-saas-worker + +# Worker 并发数（同时执行的任务数） +WORKER_CONCURRENCY=4 + +# 每个子进程最多处理多少任务后重启（防止内存泄漏） +WORKER_MAX_TASKS_PER_CHILD=1000 + + +# ==================== JWT 认证配置 ==================== + +# JWT 签名密钥 — 生产环境必须设置为强随机字符串（至少32字符） +# 内置不安全值会被拒绝：secret / changeme / password / your-secret-key 等 +JWT_SECRET_KEY=your-super-secret-key-change-this-in-production-min-32-chars + +# JWT 签名算法 +JWT_ALGORITHM=HS256 + +# Access Token 过期时间（分钟） +JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30 + +# Refresh Token 过期时间（天） +JWT_REFRESH_TOKEN_EXPIRE_DAYS=30 + + +# ==================== 邮件配置 ==================== + +# 是否启用邮件投递（关闭时邮件内容打印到日志，开发调试用） +ENABLE_EMAIL_DELIVERY=false + +# SMTP 服务器地址 +SMTP_HOST=smtp.gmail.com + +# SMTP 端口 +SMTP_PORT=587 + +# SMTP 用户名 +SMTP_USER=your-email@gmail.com + +# SMTP 密码 / 应用专用密码 +SMTP_PASSWORD=your-app-specific-password + +# 发件人邮箱 +SMTP_FROM_EMAIL=noreply@xiaoxia-saas.com + +# 发件人显示名称 +SMTP_FROM_NAME=小虾 SaaS + +# 是否启用 TLS +SMTP_USE_TLS=true + # ==================== 阿里云 OSS 配置 ==================== + +# OSS 区域 endpoint OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com + +# OSS Access Key ID — 非开发环境必须设置 OSS_ACCESS_KEY_ID=your-access-key-id + +# OSS Access Key Secret — 非开发环境必须设置 OSS_ACCESS_KEY_SECRET=your-access-key-secret + +# OSS Bucket 名称 OSS_BUCKET_NAME=xiaoxia-autocut -# ==================== CosyVoice 语音合成配置 ==================== -# 注意：base_url 只需写到 /api/v1，具体路径由代码拼接 -# 模型: cosyvoice-v3-flash (推荐，支持系统音色，性价比高) -# cosyvoice-v3-plus (高质量，系统音色少) -# cosyvoice-v3.5-flash / cosyvoice-v3.5-plus (仅支持克隆/设计音色，无系统音色) -# 音色: v3系列系统音色带 _v3 后缀，如 longxiaochun_v3, longxiaoxia_v3, longanyang (无后缀) -# 注意：COSYVOICE_* 变量由 packages/shared/config.py 的 SharedSettings 读取 +# 直传最大文件大小（MB） +OSS_DIRECT_UPLOAD_MAX_MB=2000 + +# 直传签名有效期（秒） +OSS_DIRECT_UPLOAD_EXPIRE_SECONDS=900 + + +# ==================== CORS 配置 ==================== + +# 允许跨域的前端域名列表，逗号分隔 +CORS_ORIGINS_RAW=http://localhost:3000,http://localhost:5173,http://localhost:8000 + + +# ==================== 渲染引擎配置 ==================== + +# 渲染引擎选择： +# legacy — 旧 VideoComposeService（稳定，功能完整） +# unified — 新 UnifiedRenderService（新架构，部分场景仍在验证） +RENDER_ENGINE=legacy + + +# ==================== CosyVoice 语音合成 ==================== +# 阿里云百灵语音合成服务 +# 模型选择： +# cosyvoice-v3-flash — 推荐，系统音色多，性价比高 +# cosyvoice-v3-plus — 高质量，系统音色少 +# cosyvoice-v3.5-flash / cosyvoice-v3.5-plus — 仅支持克隆/设计音色，无系统音色 +# 音色：v3 系列系统音色带 _v3 后缀，如 longxiaochun_v3 / longxiaoxia_v3 / longanyang + COSYVOICE_API_KEY=your-cosyvoice-api-key COSYVOICE_BASE_URL=https://dashscope.aliyuncs.com/api/v1 COSYVOICE_MODEL=cosyvoice-v3-flash COSYVOICE_VOICE=longxiaochun_v3 COSYVOICE_SAMPLE_RATE=22050 COSYVOICE_FORMAT=mp3 + +# 音色克隆模型名（固定为 voice-enrollment，通常不需修改） +COSYVOICE_CLONE_MODEL=voice-enrollment + + +# ==================== 豆包大模型（火山引擎方舟） ==================== +# 用于 AI 文案生成、智能剪辑等需要大模型能力的场景 + +DOUBAO_API_KEY=your-doubao-api-key +DOUBAO_MODEL=doubao-seed-1-6-250615 +DOUBAO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3 +DOUBAO_TIMEOUT=30 +DOUBAO_MAX_RETRIES=2 -- 2.54.0