本地开发

本节说明如何在开发机上启动完整 MemShare 栈。

前置依赖

推荐启动顺序

1. 基础设施

PostgreSQL：创建数据库并配置 DATABASE_URL。

MinIO（本地 S3 兼容）：

# 示例：Docker 启动 MinIO
docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"

创建 bucket memshare，与 api/.env 中 R2_* 变量对齐。

2. api

cd api
cp .env.example .env
pnpm install
pnpm generate    # prisma generate
pnpm dev         # http://localhost:8080

• OpenAPI：http://localhost:8080/api/doc
• Swagger UI：http://localhost:8080/api/ui
• 健康检查：http://localhost:8080/vi/health

确保 WORKER_API_KEY 与 worker 侧一致。

3. speech

cd speech
cp .env.example .env   # 配置 ARK_API_KEY（可选）
uv sync
uv run speech          # http://localhost:8000

Whisper 模型默认路径：~/.cache/whisper-cpp/models/ggml-large-v3-turbo.bin

验证：curl http://localhost:8000/health

4. worker

cd worker
cp .env.example .env
pnpm install
pnpm dev

.env 关键项：

MEMSHARE_API_BASE_URL=http://localhost:8080/api
WORKER_API_KEY=change-me
SPEECH_SERVICE_URL=http://localhost:8000

5. native

cd native
cp .env.example .env   # 配置 API 地址
pnpm install
pnpm start             # Expo Dev Client

native 需要 node-linker=hoisted（见 .npmrc）。在真机或模拟器上运行 Expo Dev Client。

文档站点

cd docs
pnpm install
pnpm dev               # Next.js + Nextra

端到端验证

1. 在 App 登录（better-auth）
2. 添加本地视频或 YouTube 链接
3. 观察 worker 日志：任务领取 → Speech 调用 → 字幕写入
4. 打开播放器，确认字幕随处理进度出现
5. 再次添加相同内容，验证去重与字幕复用

各子项目文档

常见问题

Worker 轮询报 fetch failed

确认 api 已启动且 MEMSHARE_API_BASE_URL 正确（含 /api 前缀）。

Speech 首段等待很久

Whisper 大模型首次加载与长音频首段识别耗时较长，属正常现象。观察 worker 日志 [speech] 已收到 N 段。

YouTube 下载失败

安装 yt-dlp 并配置 YTDLP_COOKIES_FROM_BROWSER，或检查网络环境。

native pnpm 依赖异常

确认 .npmrc 中 node-linker=hoisted，删除 node_modules 后重装。