xiaoxia-saas/docs/ci-env-vars.md

CI 必需环境变量清单

本文档整理小虾 SaaS 项目中所有从环境变量读取的配置项，明确哪些是 CI 测试必须的、哪些是可选的。 最后更新：2026-07-09

目录

• 一、配置来源说明
• 二、CI 必需环境变量（P0）
• 三、可选环境变量（有默认值）
• 四、测试专用环境变量
• 五、Worker 服务环境变量
• 六、当前 CI 配置对照

---

一、配置来源说明

项目的环境变量配置主要来自以下几处：

来源	文件路径	说明
API 主配置	apps/api/app/config.py	pydantic Settings 类，API 服务核心配置
Worker 配置	apps/worker/worker_app/core/config.py	pydantic WorkerSettings 类，Worker 服务配置
共享配置	packages/shared/config.py	pydantic SharedSettings 类，API + Worker 共享配置
直接读取	各模块中 os.environ / os.getenv	散落在各业务模块中的直接读取

注意：pydantic-settings 配置默认 case_sensitive=False，即环境变量名不区分大小写，但习惯上使用大写。

---

二、CI 必需环境变量（P0）

以下变量是 CI 运行测试必须配置的，缺失会导致测试启动失败或核心功能异常。

变量名	用途说明	默认值	影响范围
DATABASE_URL	数据库连接字符串	postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas	集成测试、 Alembic 迁移验证
USE_IN_MEMORY_DB	是否使用内存数据库（SQLite）	false	单元测试（设为 true 可跳过 PostgreSQL 依赖）
JWT_SECRET_KEY	JWT 签名密钥，无安全默认值，必须显式设置	None（启动校验失败）	所有涉及认证的 API 测试

说明：

• 单元测试通过 USE_IN_MEMORY_DB=true 使用 SQLite 内存数据库，无需 PostgreSQL
• 集成测试需要真实 PostgreSQL，需设置 DATABASE_URL
• JWT_SECRET_KEY 在测试文件中通过 os.environ.setdefault() 设置了测试用默认值，CI 中可不额外配置，但生产环境必须配置

---

三、可选环境变量（有默认值）

以下变量都有合理的默认值，CI 中可以不配置，使用默认值即可。

3.1 应用基础配置

变量名	用途说明	默认值
APP_NAME	应用名称	xiaoxia-saas
APP_VERSION	应用版本号	0.1.61 / unknown
ENVIRONMENT	运行环境标识	development
DEBUG	是否开启调试模式	true
APP_BASE_URL	应用基础 URL（用于生成邮件链接等）	http://localhost:3000
API_HOST	API 服务绑定地址	0.0.0.0
API_PORT	API 服务端口	8000
API_PREFIX	API 路由前缀	/api/v1
APP_ENV	环境标识（用于加载 .env.{env} 文件）	development
LOG_LEVEL	日志级别	INFO

3.2 数据库连接池配置

变量名	用途说明	默认值
DATABASE_POOL_SIZE	连接池大小	20
DATABASE_MAX_OVERFLOW	最大溢出连接数	10 (API) / 40 (Worker)
DATABASE_POOL_TIMEOUT	获取连接超时时间（秒）	30
DATABASE_POOL_RECYLE / DATABASE_POOL_RECYCLE	连接回收时间（秒）	3600
AUTO_CREATE_SCHEMA	是否自动创建表结构	false

3.3 Redis / Celery 配置

变量名	用途说明	默认值
REDIS_URL	Redis 连接地址	redis://localhost:6379/0
REDIS_MAX_CONNECTION	Redis 最大连接数	50
ENABLE_REDIS_SESSIONS	是否启用 Redis 会话存储	false
CELERY_BROKER_URL / BROKER_URL	Celery Broker 地址	redis://localhost:6379/0
CELERY_RESULT_BACKEND / RESULT_BACKEND	Celery 结果后端	redis://localhost:6379/1

3.4 JWT 配置

变量名	用途说明	默认值
JWT_ALGORITHM	JWT 签名算法	HS256（隐式默认）
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	Access Token 过期时间（分钟）	30（隐式默认）
JWT_REFRESH_TOKEN_EXPIRE_DAYS	Refresh Token 过期时间（天）	30（隐式默认）
JWT_SECRET_KEY_OLD	旧 JWT 密钥（用于密钥轮换）	None
SECRET_ROTATION_DAYS	密钥轮换建议天数	90

3.5 邮件配置

变量名	用途说明	默认值
ENABLE_EMAIL_DELIVERY	是否启用邮件发送	false
SMTP_HOST	SMTP 服务器地址	smtp.gmail.com
SMTP_PORT	SMTP 端口	587
SMTP_USER	SMTP 用户名	""（空）
SMTP_PASSWORD	SMTP 密码	""（空）
SMTP_FROM_EMAIL	发件人邮箱	""（空）
SMTP_FROM_NAME	发件人名称	小虾 SaaS
SMTP_USE_TLS	是否使用 TLS	true

3.6 OSS 阿里云存储配置

变量名	用途说明	默认值
OSS_ENDPOINT	OSS Endpoint	oss-cn-hangzhou.aliyuncs.com
OSS_ACCESS_KEY_ID	OSS Access Key ID	""（空）
OSS_ACCESS_KEY_SECRET	OSS Access Key Secret	""（空）
OSS_BUCKET_NAME	OSS Bucket 名称	xiaoxia-autocut
OSS_DIRECT_UPLOAD_MAX_MB / MAX_UPLOAD_SIZE_MB	直传最大文件大小（MB）	2000
OSS_DIRECT_UPLOAD_EXPIRE_SECONDS	直传签名过期时间（秒）	900

3.7 CosyVoice 语音合成配置

变量名	用途说明	默认值
COSYVOICE_API_KEY	CosyVoice API Key	""（空）
COSYVOICE_BASE_URL	CosyVoice API 地址	https://dashscope.aliyuncs.com/api/v1/services/aigc/text2audio
COSYVOICE_MODEL	CosyVoice 模型	cosyvoice-v1
COSYVOICE_VOICE	默认音色	longxiaochun
COSYVOICE_SAMPLE_RATE	采样率	22050
COSYVOICE_FORMAT	输出格式	mp3

3.8 CORS 配置

变量名	用途说明	默认值
CORS_ORIGINS_RAW	CORS 允许的源（逗号分隔）	http://localhost:3000,http://localhost:5173,http://localhost:8000

3.9 文件存储 / 生成文件配置

变量名	用途说明	默认值
GENERATED_FILES_DIR	生成文件本地存储目录	/app/generated
GENERATED_FILES_URL_PREFIX	生成文件访问 URL 前缀	/generated-files
VIDEO_OUTPUT_DIR	视频输出目录	{tempdir}/video_output
PUBLIC_API_BASE_URL	公开 API 基础 URL	https://api.xiaoxiajianji.com

3.10 监控 / 指标配置

变量名	用途说明	默认值
METRICS_AUTH_TOKEN	Prometheus 指标接口认证 Token	""（空，不启用认证）

3.11 内部 API 配置

变量名	用途说明	默认值
INTERNAL_API_KEYS	内部 API 调用密钥列表（逗号分隔）	""（空）

---

四、测试专用环境变量

以下变量仅在测试或冒烟测试脚本中使用。

变量名	用途说明	默认值	使用位置
SMOKE_TEST_PASSWORD	冒烟测试用的测试账号密码	changeme	scripts/smoke_*.py
MIGRATION_SINCE_REVISION	迁移安全检查的起始版本	None	scripts/check_migration_safety.py
MIGRATION_DIFF_AGAINST	迁移 diff 对比的目标分支/版本	None	scripts/check_migration_safety.py

---

五、Worker 服务环境变量

以下变量主要用于 Worker（Celery）服务，CI 的单元/集成测试通常不涉及。

变量名	用途说明	默认值
WORKER_NAME	Worker 名称	xiaoxia-saas-worker
WORKER_CONCURRENCY	Worker 并发数	4
WORKER_MAX_TASKS_PER_CHILD	每个子进程最大任务数	1000

---

六、当前 CI 配置对照

当前 .gitea/workflows/ci-cd.yml 中 validate job 配置的环境变量：

变量名	CI 配置值	是否必需	备注
DATABASE_URL	postgresql+psycopg://postgres:postgres@127.0.0.1:5432/xiaoxia_saas	✅ 是	Job 级别配置
USE_IN_MEMORY_DB	"false"（Job 级） / "true"（单元测试 step 级）	✅ 是	单元测试 step 覆盖为 true
JWT_SECRET_KEY	（未配置）	⚠️ 测试内置	测试文件中通过 setdefault 设置了测试密钥

6.1 CI 环境变量现状评估

• ✅ 数据库配置完备：DATABASE_URL + USE_IN_MEMORY_DB 已正确配置
• ✅ JWT 密钥：测试代码内置默认值，CI 可正常运行
• ⚠️ 缺少 Redis 配置：但当前测试不依赖 Redis，使用默认值即可
• ⚠️ 缺少邮件/OSS/语音配置：均为可选，CI 中使用空默认值不影响核心测试

6.2 建议后续补充

如果未来测试覆盖到以下功能，需要在 CI 中补充对应配置：

1. Redis 相关测试 → 配置 REDIS_URL
2. 邮件发送测试 → 配置 ENABLE_EMAIL_DELIVERY 及 SMTP 相关变量
3. OSS 上传测试 → 配置 OSS 相关变量（或使用 mock）
4. 语音合成测试 → 配置 CosyVoice 相关变量（或使用 mock）

---

附录：环境变量读取位置索引

pydantic Settings 类

• apps/api/app/config.py → Settings 类（API 主配置）
• apps/worker/worker_app/core/config.py → WorkerSettings 类（Worker 配置）
• packages/shared/config.py → SharedSettings 类（共享配置）

直接 os.environ / os.getenv 读取

变量名	文件位置
VIDEO_OUTPUT_DIR	apps/worker/video_processing/video_compose_service.py、apps/worker/worker_app/tasks/compose_video.py
INTERNAL_API_KEYS	apps/api/app/api/routes/auth.py
APP_ENV / ENV	apps/api/app/api/routes/auth.py、各 config.py 的 get_settings()
GENERATED_FILES_DIR	apps/worker/worker_app/tasks/generation.py、apps/api/main.py、scripts/cleanup_generated_files.py
GENERATED_FILES_URL_PREFIX	apps/worker/worker_app/tasks/generation.py、apps/api/main.py、apps/api/app/core/storage.py
PUBLIC_API_BASE_URL	apps/worker/worker_app/tasks/generation.py
METRICS_AUTH_TOKEN	apps/api/app/middleware/prometheus_metrics.py
APP_VERSION	apps/api/app/middleware/prometheus_metrics.py
SMOKE_TEST_PASSWORD	scripts/smoke_*.py
MIGRATION_SINCE_REVISION	scripts/check_migration_safety.py
MIGRATION_DIFF_AGAINST	scripts/check_migration_safety.py
DATABASE_URL	alembic/env.py