第 1 课
clone、.env 与 docker compose 起栈
在本机 clone 仓库、填写 .env，并用 docker compose 拉起 SupoClip，打开 localhost:3107。
学习位置仅保存在当前浏览器，有效期 180 天。
图文讲义
clone、.env 与 docker compose 起栈
本课按 SupoClip 官方 README「Quick Start」、docs/setup.md、QUICKSTART.md 与 自托管教程 整理。
目标：在本机 clone 仓库、写好.env、用 Docker Compose 拉起整栈，浏览器打开 **http://localhost:3107**。
主要来源：supoclip.com · GitHub FujiwaraChoki/supoclip
你将得到什么
- 本机可访问的 SupoClip 前端：
http://localhost:3107 - 后端 API：
http://localhost:8000（交互文档/docs） - 一组 healthy 的 Docker 服务（frontend / backend / worker / postgres / redis）
.env里至少配好转写密钥 + 一个 LLM 提供商
课前准备
- 已安装 Docker Desktop（或带 Compose 的 Docker Engine）与 Git。可用
docker info确认守护进程在跑。 - 准备密钥（官方 Required credentials）：
- AssemblyAI API Key（默认转写路径）：https://www.assemblyai.com/
- 至少一个 LLM：Google / OpenAI / Anthropic / OpenRouter 之一的 Key，或本机 Ollama（无云 Key）
- 磁盘与网络：首次
docker compose up --build会拉 Python/Node 依赖，官方自托管文估计约 5–10 分钟（视网速与 CPU）。 - 本课走 自托管（默认
SELF_HOST=true），不启用 Stripe 计费。
端口提醒（重要）： 官方模板
FRONTEND_PORT=3107。旧.env若没有该键，宿主机端口可能是 3001。不要默认去开localhost:3000——那不是当前文档里的地址。
一、SupoClip 是什么（30 秒）
SupoClip 是开源 AI 剪辑工具（AGPL-3.0）：喂入长视频（播客、访谈、VOD），由 LLM 选出 3–7 个更适合传播的片段，做人脸居中竖裁、词级字幕、钩子标题，可选 B-roll。你可以：
| 方式 | 说明 |
|---|---|
| 托管站 | https://www.supoclip.com/ — 免运维 |
| 自托管 | Docker Compose（本课） |
| iOS | App Store 上的 SupoClip |
| MCP / REST | 仓库 mcp/ 与 Settings 里的 API Key |
本课只做自托管起栈；下一课在本机 UI 里提交第一个任务。
二、clone 并复制环境文件
在终端执行（官方原文可直接抄）：
git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env
对照结果：
- 当前目录是
supoclip，且存在.env（由.env.example复制而来）。 ls docker-compose.yml（或compose.yaml）能看到 Compose 文件。
三、编辑 `.env`：必填键
用编辑器打开根目录 .env。下面给一套最小可用的云端配置（与 README Quick Start / docs/setup.md 示例一致；密钥请换成你自己的，课程里只用占位符）：
ASSEMBLY_AI_API_KEY=YOUR_ASSEMBLY_AI_API_KEY
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY
# 本地也建议改掉占位密钥（自托管教程：openssl rand -base64 32）
BETTER_AUTH_SECRET=YOUR_BETTER_AUTH_SECRET
# 若日后改成托管计费模式才强依赖；本地自托管可先占位
BACKEND_AUTH_SECRET=YOUR_BACKEND_AUTH_SECRET
生成随机密钥（官方自托管教程写法）：
openssl rand -base64 32
把输出分别填进 BETTER_AUTH_SECRET（以及你决定填写的其他 secret 字段）。
换其他 LLM（任选其一，与密钥成对）
官方要求：LLM 的前缀必须和你填的 Key 对应，否则任务会在分析阶段失败。
OpenAI：
LLM=openai:gpt-4
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
Anthropic：
LLM=anthropic:claude-3-5-sonnet-20241022
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
Google（README 示例）：
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY
Ollama（本机，无云 Key）：
LLM=ollama:gpt-oss:20b
# Docker Desktop 常可留空，容器经 host.docker.internal 访问宿主机 Ollama
# OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
详细本地 Whisper + Ollama 网络说明见官方：https://www.supoclip.com/blog/self-host-supoclip-docker#local
可选但常见
| 变量 | 作用 |
|---|---|
FRONTEND_PORT=3107 | 宿主机前端端口（模板默认） |
PEXELS_API_KEY=... | 开启 AI B-roll（没有则 UI 会提示不可用） |
SELF_HOST=true | 默认自托管：关计费、无限本机生成次数 |
BACKEND_CPU_ONLY=true | 模板默认：CPU 版 Torch（含 Apple Silicon 场景） |
对照结果：
.env里ASSEMBLY_AI_API_KEY（若用 AssemblyAI）非空、无多余空格。LLM=与对应*_API_KEY（或 Ollama）成对出现。=两侧没有意外空格（QUICKSTART 排错要点）。
四、启动整栈
推荐：官方 start 脚本
./start.sh
脚本会检查 .env 与 Docker、构建镜像并启动服务（QUICKSTART）。
或手动 Compose（官网首页 / setup.md）
docker compose up -d --build
# 若本机只有旧版 CLI，也可用：
# docker-compose up -d --build
首次构建可能要数分钟。跟日志：
docker compose logs -f
# 或只看后端 / worker：
# docker compose logs -f backend
# docker compose logs -f worker
另开一个终端看健康状态：
docker compose ps
对照结果（成功时你会看到）：
docker compose ps里至少这些服务在跑且多为 healthy（setup.md）：supoclip-frontendsupoclip-backendsupoclip-workersupoclip-postgressupoclip-redis
- 浏览器打开 http://localhost:3107 能看到首页（不是「无法连接」）。
- http://localhost:8000/docs 能打开 FastAPI 文档；可选再测：
curl -f http://localhost:8000/health
若前端连不上：用 docker compose port frontend 3107 看实际映射端口；旧部署可能是 3001（troubleshooting.md）。不要死磕 3000。
Compose 起了什么（便于排错）
| 服务 | 角色 | 宿主机端口（默认） |
|---|---|---|
| frontend | Next.js + 鉴权代理 | 3107 |
| backend | FastAPI | 8000 |
| worker | ARQ：下载 / 转写 / 分析 / 渲染 | 无对外端口 |
| postgres | 用户与任务数据 | （容器内） |
| redis | 队列与进度 | 6379（常绑本机） |
自托管博客还提到可选 mcp（9100）；不用 MCP 时可 docker compose stop mcp。本课验收以核心五服务为准。
五、首启检查清单（setup.md First-Run Checklist 前半）
- 打开 http://localhost:3107
- 能进入注册 / 登录页（Better Auth，邮箱密码）
docker compose ps无持续 Restarting- 改过
.env后若行为异常，按官方：
docker compose down
docker compose up -d --build
警告：
docker compose down -v会删掉 named volumes（数据库与上传）——本地实验才用。
六、常见起栈失败（本课够用）
| 现象 | 先查 |
|---|---|
| 容器起不来 | docker info；docker compose logs -f；.env 是否缺失 |
| 前端页面空白 / 连不上 | 端口是 3107 还是 3001？docker compose port frontend 3107 |
| Login Invalid Origin | NEXT_PUBLIC_APP_URL / BETTER_AUTH_URL 必须与浏览器地址完全一致（含协议与端口；localhost ≠ 127.0.0.1） |
| Apple Silicon 很慢 | 官方说明 backend/worker 走 linux/amd64 模拟；BACKEND_CPU_ONLY=true 避免下 NVIDIA 包，但不启用 Apple GPU |
本课小结
| 步骤 | 命令/动作 | 成功信号 |
|---|---|---|
| Clone | git clone + cp .env.example .env | 有 .env |
| 密钥 | AssemblyAI + LLM 成对；改 BETTER_AUTH_SECRET | 无空占位（你已替换） |
| 起栈 | ./start.sh 或 docker compose up -d --build | ps healthy |
| 打开 | 浏览器 3107；可选 8000/docs | 首页可访问 |
下一课：注册账号 → 粘贴 YouTube / 上传视频 → 跟进度 → 下载首批 9:16 字幕片，并对照「缺 AssemblyAI / LLM Key」时的失败表现。
来源
- https://www.supoclip.com/
- https://github.com/FujiwaraChoki/supoclip
- https://raw.githubusercontent.com/FujiwaraChoki/supoclip/main/README.md
- https://raw.githubusercontent.com/FujiwaraChoki/supoclip/main/QUICKSTART.md
- https://github.com/FujiwaraChoki/supoclip/blob/main/docs/setup.md
- https://www.supoclip.com/blog/self-host-supoclip-docker
