服务关系

本节描述各子项目的职责边界、端口、依赖关系与主要 API 契约。

服务一览

服务	默认端口	运行时	包管理	对外暴露
api	8080	Node.js 20+	pnpm	是（App + Worker）
speech	8000	Python 3.13+	uv	否（内网，Worker 调用）
worker	—	Node.js 20+	pnpm	否（主动轮询 API）
native	—	Expo	pnpm	—（移动客户端）

依赖关系图

api 依赖

PostgreSQL：用户、媒体、字幕全量数据
R2 / S3：音频对象存储（audio/{fileHash}.{ext}）
Infra 表：运行时配置（启动时 loadInfra() 加载）

speech 依赖

whisper.cpp（pywhispercpp）：本地语音转录
Sudachi + Ginza：日语分词与文节（仅 language=ja）
火山方舟 API（可选）：豆包翻译；可通过 TRANSLATION_ENABLED=false 关闭

worker 依赖

api：任务领取、状态回写、字幕写入
speech：POST /transcribe SSE 流
yt-dlp：YouTube 音频下载（youtube_download 任务）
R2：通过 API 预签名 URL 上传/下载音频

native 依赖

api：鉴权、媒体库、字幕读取
R2：通过预签名 URL 直传音频
本地模块：expo-media-processor-module 从视频提取音频

API 路由概览

用户侧（需登录）

方法	路径	说明
`GET`	`/api/media`	媒体库列表（支持 tag 筛选）
`POST`	`/api/media/upload-url`	获取音频上传预签名 URL（含去重）
`POST`	`/api/media`	登记本地文件媒体
`POST`	`/api/media/youtube`	通过 YouTube URL 添加
`GET`	`/api/media/{id}/subtitles/{language}`	分页获取字幕片段
`*`	`/api/auth/*`	better-auth 认证

Worker 侧（`X-Worker-Key`）

方法	路径	说明
`GET`	`/api/worker/jobs/next`	领取下一条待处理任务
`PATCH`	`/api/worker/jobs/{id}`	更新任务状态与日志
`POST`	`/api/worker/jobs/{id}/audio-upload-url`	YouTube 下载后获取上传 URL
`POST`	`/api/worker/jobs/{id}/audio`	登记已上传音频，触发转写
`POST`	`/api/worker/jobs/{id}/subtitles/segments`	流式追加字幕片段

Speech 服务

方法	路径	说明
`GET`	`/health`	健康检查
`POST`	`/transcribe`	上传音频，返回 SSE 事件流

SSE 事件类型：start → segment（多次）→ translation（每 10 段一批）→ done / error

环境变量对照

各服务需对齐以下关键配置：

变量	api	worker	speech	native
`DATABASE_URL`	✓
`R2_*`	✓
`WORKER_API_KEY`	✓	✓
`MEMSHARE_API_BASE_URL`		✓		✓
`SPEECH_SERVICE_URL`		✓
`ARK_API_KEY`			✓
`SUBTITLE_TARGET_LANGUAGE`		✓

Worker 额外支持 YTDLP_BIN、YTDLP_COOKIES_FROM_BROWSER 以应对 YouTube 下载限制。

通信时序（转写任务）

扩展建议

水平扩展 Worker：多个实例同时轮询；任务认领依赖 subtitleStatus: pending → processing 的原子更新，避免重复处理
Speech GPU 节点：Speech 为 CPU/GPU 密集型，可与 API 分离部署
R2 CDN：音频下载 URL 为预签名，可配合 CDN 加速 Worker 拉取

系统架构流程概览