基础设施与环境配置方案

1. 文档目的

本文档用于定义课程内核重构阶段的基础设施基线和环境配置方案。

2. 当前推荐基础设施

2.1 本地开发

• Node.js >= 20.9
• pnpm >= 10
• PostgreSQL
• Redis
• MinIO
• 至少一个可用 LLM provider

2.2 测试 / 预发

• 与生产同构的 PostgreSQL / Redis / 对象存储
• 固定样例课程回放能力
• 任务队列和日志接入能力

2.3 生产

• PostgreSQL
• Redis
• S3 或兼容对象存储
• 结构化日志
• provider key 分环境隔离

3. 推荐技术基线

第一阶段推荐：

• Web / API：TypeScript
• 任务队列：Redis + BullMQ
• 主数据库：PostgreSQL
• 对象存储：MinIO / S3
• 流式：SSE

4. 环境分层

4.1 local

目标：

• 最快启动开发
• 可独立跑通 P0 样例课程

建议内容：

• .env.local
• Docker 启动 PostgreSQL / Redis / MinIO

4.2 test

目标：

• 稳定跑协议校验、任务测试和样例回放

建议内容：

• .env.test
• 固定测试 bucket / queue / db schema

4.3 production

目标：

• 多环境隔离
• 密钥治理
• 稳定日志和任务观测

5. 配置分类

5.1 应用配置

• APP_BASE_URL
• APP_ENV
• LOG_LEVEL

5.2 数据配置

• DATABASE_URL
• REDIS_URL
• S3_ENDPOINT
• S3_BUCKET
• S3_ACCESS_KEY
• S3_SECRET_KEY

5.3 Provider 配置

• OPENAI_API_KEY
• OPENAI_BASE_URL
• 图像 / 视频 / TTS / ASR / Search 对应密钥

5.4 任务配置

• 队列名
• 默认重试次数
• 超时阈值
• 并发限制

6. 密钥治理

1. 密钥不进入课程协议
2. 密钥不写入课程资产
3. .env* 与运行时配置分层
4. provider key 按环境隔离

7. 对象存储策略

对象存储用于保存：

• 图片
• 视频
• 音频
• 导出文件
• 大体积中间产物

数据库只保存：

• 资源引用
• 元数据
• 访问 Key

8. 日志与观测

当前至少要求：

• requestId
• jobId
• stageId
• unitId
• sceneId
• step
• provider

统一采用结构化日志，便于后续审计与问题追踪。

9. 本地启动建议

本地推荐统一使用容器拉起以下依赖：

• PostgreSQL
• Redis
• MinIO

避免不同机器各自安装和各自配置。

10. 结论

当前环境和基础设施目标不是“企业级全量治理”，而是：

• 先让开发环境一致
• 先让任务、存储、资源边界稳定
• 先支撑 P0 正向主链跑通

后续再逐步增强生产级治理和平台级观测。