① 选你的目标（30 秒）
| 目标 | 要不要 Key | 做什么 |
|---|---|---|
| 只体验流程 | 不要 | 复制 .env，直接启动 → 自动 Mock |
| 本地真实 AI | 要 1 个 Gemini Key | 填 GEMINI_API_KEY 即可 |
| 正式上线 | 要 | 强密码 + AI Key + C2PA |
② 复制配置文件（1 分钟）
Copy-Item .env.example .env
生产环境使用 deploy/docker/.env.production.example 作为模板。
③ 拿 API Key（2 分钟）
Gemini（文本 + 图像 + 配音 + 视频，推荐先只配这个）
- 打开 Google AI Studio → API Keys
- 登录 Google 账号 → Create API key
- 复制 Key（以
AIza开头）
GEMINI_API_KEY=AIzaSy...你的密钥... PROVIDER_MODE=auto
Veo 视频与 Gemini 共用同一 Key，不必再申请第二个。
可灵 Kling（视频备选，可选）
- 打开 可灵开发者控制台
- 创建 API Key → 复制 Access Key + Secret Key（Secret 只显示一次）
KLING_ACCESS_KEY=你的AccessKey KLING_SECRET_KEY=你的SecretKey
④ 填到哪里（1 分钟）
方式 A · 平台 .env（全站共用）
编辑项目根目录 .env，保存后重启 API + Worker：
docker compose restart api worker
方式 B · 网页 BYOK（个人自带密钥）
个人设置 → 企业 BYOK → 选类型 → 粘贴 Key → 保存 → 校验
| BYOK 类型 | 填什么 |
|---|---|
| 文本 / 图像 / 配音 | Gemini API Key |
| 视频 / 原生音视频 | Gemini Key（Veo）或 Kling Bearer Token |
⑤ 验证（1 分钟）
curl http://localhost:8000/health
- 登录 → 新建项目 → 导入剧本 → 发起生成
- 打开任务中心，状态应为
succeeded - BYOK：设置页点「校验」应通过
生产环境额外必改项
| 变量 | 要求 |
|---|---|
JWT_SECRET | 32 位以上随机串 |
DEFAULT_ADMIN_PASSWORD | 强密码 |
OBJECT_STORAGE_* | 改掉默认 minioadmin |
C2PA_SIGNING_KEY_PATH | 生成证书后填入 |
常见问题
| 现象 | 处理 |
|---|---|
| 还是 Mock | 重启 worker；检查 Key 无空格；PROVIDER_MODE 不是 mock |
| 任务不跑 | 确认 Worker 容器/进程在运行 |
| 402 额度不足 | 管理员后台加额度 |
| 视频 401 | Key 无效 / 未开通付费 / Kling 余额不足 |