docs(#780): 补齐.env.example缺失的30+配置项 #790

Merged

xiaoxia merged 1 commits from docs/780-complete-env-example into develop 2026-07-23 23:54:59 +08:00

Conversation 2 Commits 1 Files Changed 1

+180 -42

xiaoxia commented 2026-07-23 23:16:34 +08:00

Owner

Copy Link

Copy Source

背景

#780 补充.env.example — 原来只有20几项，很多后端配置没列出来，新环境部署时容易漏。

改动

梳理了全部配置文件（packages/shared/config.py / apps/api/app/config.py / apps/worker/worker_app/core/config.py），完整列出所有环境变量，共 50+ 项：

新增配置分类

• 数据库连接池：pool_size / max_overflow / pool_timeout / pool_recycle / auto_create_schema
• Celery：broker_url / result_backend
• Worker：worker_name / concurrency / max_tasks_per_child
• OSS 进阶：direct_upload_max_mb / direct_upload_expire_seconds
• 豆包大模型：api_key / model / base_url / timeout / max_retries
• CosyVoice 补充：clone_model
• 渲染引擎：render_engine (legacy/unified)
• 邮件进阶：enable_email_delivery / smtp_use_tls
• 应用进阶：app_version / api_host / api_port

文档改进

• 顶部增加配置读取优先级说明
• 每个配置补充用途注释和默认值说明
• 密钥类配置标注生产环境必须修改

验证

• 纯文档改动，无代码逻辑变更
• 所有配置项均已对照代码中的默认值核实

## 背景 #780 补充.env.example — 原来只有20几项，很多后端配置没列出来，新环境部署时容易漏。 ## 改动 梳理了全部配置文件（packages/shared/config.py / apps/api/app/config.py / apps/worker/worker_app/core/config.py），完整列出所有环境变量，共 50+ 项： ### 新增配置分类 - 数据库连接池：pool_size / max_overflow / pool_timeout / pool_recycle / auto_create_schema - Celery：broker_url / result_backend - Worker：worker_name / concurrency / max_tasks_per_child - OSS 进阶：direct_upload_max_mb / direct_upload_expire_seconds - 豆包大模型：api_key / model / base_url / timeout / max_retries - CosyVoice 补充：clone_model - 渲染引擎：render_engine (legacy/unified) - 邮件进阶：enable_email_delivery / smtp_use_tls - 应用进阶：app_version / api_host / api_port ### 文档改进 - 顶部增加配置读取优先级说明 - 每个配置补充用途注释和默认值说明 - 密钥类配置标注生产环境必须修改 ## 验证 - 纯文档改动，无代码逻辑变更 - 所有配置项均已对照代码中的默认值核实

xiaoxia added 1 commit 2026-07-23 23:16:34 +08:00

docs(#780): 补齐.env.example缺失的30+配置项 ... 9a852a4a12

梳理所有配置文件（shared/api/worker），完整列出全部环境变量：
- 新增：数据库连接池配置（pool_size/max_overflow/timeout/recycle）
- 新增：Celery broker/backend 配置
- 新增：Worker 并发/子进程数 配置
- 新增：OSS 直传大小/过期时间 配置
- 新增：豆包大模型（Doubao）配置
- 新增：CosyVoice 克隆模型配置
- 新增：渲染引擎选择（RENDER_ENGINE）
- 新增：邮件投递开关 / SMTP TLS / API 端口等零散配置
- 每个配置补充用途注释和默认值说明
- 顶部增加配置读取优先级说明

auto-approve-bot commented 2026-07-23 23:26:47 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #790

⚠️ 问题（0个需要修改）

💡 建议（3个可选）

1. [.env.example: 14] 环境变量命名兼容性风险

   • 具体内容：原配置中使用了 ENVIRONMENT，新配置将其移除并改为 APP_ENV。请务必确认代码库中的配置加载逻辑（如 pydantic-settings 的 Settings 类）已同步更新为读取 APP_ENV，否则会导致生产环境判断失效或配置读取错误。

2. [.env.example: 55] 数据库默认值变更影响

   • 具体内容：USE_IN_MEMORY_DB 的默认值从 true 修改为 false。这意味着新开发者克隆代码后，若直接复制 .env.example 为 .env 启动项目，必须自行配置 PostgreSQL，否则将无法连接数据库。建议确认项目文档（如 README）中是否已包含本地数据库搭建指南，或考虑在 docker-compose.yml 中提供依赖服务。

3. [.env.example: 50] 数据库默认凭证安全性

   • 具体内容：DATABASE_URL 中硬编码了默认用户名和密码 postgres:postgres。虽然仅用于本地开发，但建议使用更具辨识度的占位符（如 db_user:db_password），以防止开发者误将此弱密码配置到测试或预发布环境。

✅ 良好实践

1. 文档注释详尽：配置文件顶部添加了详细的读取规则说明（pydantic-settings 优先级），且每个配置项均有注释说明用途和格式，极大提升了可维护性。
2. 安全提示明确：对密钥类配置（如 JWT_SECRET_KEY、OSS_KEYS）明确标注了“生产环境必须修改”及弱密钥拦截规则，有助于降低配置错误导致的安全风险。
3. 结构清晰：配置项按功能模块（应用、数据库、队列、第三方服务等）进行了清晰的分组和排版，易于查阅。

---

✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能无明显问题

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-07-23 15:26:47 | 模型:}

## 代码审查结果 - PR #790 ### ⚠️ 问题（0个需要修改） ### 💡 建议（3个可选） 1. **[.env.example: 14] 环境变量命名兼容性风险** - **具体内容**：原配置中使用了 `ENVIRONMENT`，新配置将其移除并改为 `APP_ENV`。请务必确认代码库中的配置加载逻辑（如 `pydantic-settings` 的 `Settings` 类）已同步更新为读取 `APP_ENV`，否则会导致生产环境判断失效或配置读取错误。 2. **[.env.example: 55] 数据库默认值变更影响** - **具体内容**：`USE_IN_MEMORY_DB` 的默认值从 `true` 修改为 `false`。这意味着新开发者克隆代码后，若直接复制 `.env.example` 为 `.env` 启动项目，必须自行配置 PostgreSQL，否则将无法连接数据库。建议确认项目文档（如 README）中是否已包含本地数据库搭建指南，或考虑在 `docker-compose.yml` 中提供依赖服务。 3. **[.env.example: 50] 数据库默认凭证安全性** - **具体内容**：`DATABASE_URL` 中硬编码了默认用户名和密码 `postgres:postgres`。虽然仅用于本地开发，但建议使用更具辨识度的占位符（如 `db_user:db_password`），以防止开发者误将此弱密码配置到测试或预发布环境。 ### ✅ 良好实践 1. **文档注释详尽**：配置文件顶部添加了详细的读取规则说明（pydantic-settings 优先级），且每个配置项均有注释说明用途和格式，极大提升了可维护性。 2. **安全提示明确**：对密钥类配置（如 JWT_SECRET_KEY、OSS_KEYS）明确标注了“生产环境必须修改”及弱密钥拦截规则，有助于降低配置错误导致的安全风险。 3. **结构清晰**：配置项按功能模块（应用、数据库、队列、第三方服务等）进行了清晰的分组和排版，易于查阅。 --- ✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能无明显问题 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-23 15:26:47 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia merged commit c6941a738c into develop 2026-07-23 23:54:59 +08:00

xiaoxia deleted branch docs/780-complete-env-example 2026-07-23 23:54:59 +08:00

gitea-actions bot commented 2026-07-23 23:57:05 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #790 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #790 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#790