首页 / 架构图 / 本地开发

本地开发测试指南

开发机环境搭建、联调测试、部署上线全流程

1. 环境概览

工具 版本 用途
Node.jsv20.20.0Worker + 前端运行时
npm10.8.2包管理
wrangler4.80.0Worker 本地开发/部署
Python3.12.3videoop 流水线
FFmpeg6.1.1视频压缩/预览生成

目录结构

/workspace/
  ├── videoworker/    # Cloudflare Worker API (Hono + TypeScript)
  ├── videoagt/       # Next.js 前端
  ├── videoop/        # Python 视频采集处理流水线
  ├── dev.sh          # 一键启动脚本
  └── architecture.html

2. 快速启动

2.1 一键启动全栈联调

cd /workspace
./dev.sh all

这会同时启动 Worker API (localhost:8787) 和前端 (localhost:3000)，
前端自动指向本地 Worker，形成完整的本地联调环境。

2.2 单独启动

# 只启动 Worker API
./dev.sh worker

# 只启动前端 (默认连线上 Worker)
./dev.sh frontend

# 查看运行状态
./dev.sh status

# 停止所有服务
./dev.sh stop

3. 各组件详细说明

3.1 Worker API (videoworker)

cd /workspace/videoworker

# 安装依赖 (首次)
npm install

# 初始化本地 D1 数据库 (首次)
for f in schema/migrations/*.sql; do
  npx wrangler d1 execute video-db --local --file="$f"
done

# 启动本地开发服务器
npx wrangler dev --local --port 8787

wrangler dev 本地模式提供：

注意：本地 D1 和线上 D1 是完全隔离的。本地测试数据不影响生产。

3.2 前端 (videoagt)

cd /workspace/videoagt

# 启动开发服务器
npm run dev

API 指向控制：

场景.env.local 设置效果
连接线上 Worker NEXT_PUBLIC_API_URL=https://videoserver.mhana.top 使用线上数据，真实环境测试
连接本地 Worker NEXT_PUBLIC_API_URL=http://localhost:8787 纯本地联调，不影响线上

./dev.sh all 会自动将前端指向本地 Worker，无需手动改 .env.local。

3.3 视频流水线 (videoop)

cd /workspace/videoop

# 激活虚拟环境
source .venv/bin/activate

# 单次运行 (采集处理一批视频)
python main.py

# 持续监控模式
python main.py --watch

# 服务模式 (轮询 D1 命令总线，生产用)
python main.py --server

三种运行模式对比：

模式命令行为适用场景
默认 python main.py 单次执行，完成后退出 本地开发测试
Watch --watch 持续循环采集 本地长时间测试
Server --server 轮询 D1 命令总线，等待 Admin 页面指令 生产环境 (PM2)

.env 中的 WORKERS_API_URL 决定 videoop 与哪个 Worker 通信：
本地测试设为 http://localhost:8787，生产设为 https://videoserver.mhana.top

4. 测试场景

4.1 前端 + Worker 联调

1
启动全栈 
./dev.sh all
2
浏览器打开 http://localhost:3000

注册/登录测试账号，浏览 feed，播放视频

3
观察 Worker 日志

终端里 wrangler dev 会输出每个请求的日志，方便调试路由/参数/错误

4.2 Worker API 单独测试

# 启动 Worker
./dev.sh worker

# 测试健康检查
curl http://localhost:8787/api/health

# 测试登录
curl -X POST http://localhost:8787/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"xxx"}'

# 测试 feed (需要 JWT)
TOKEN="your_jwt_token_here"
curl http://localhost:8787/api/feed \
  -H "Authorization: Bearer $TOKEN"

# 测试管理端点
curl http://localhost:8787/api/admin/pipeline/status \
  -H "Authorization: Bearer $TOKEN"

4.3 videoop 本地采集测试

# 确保 .env 中 WORKERS_API_URL 指向本地或线上 Worker

# 单次运行，观察采集→处理→上传全流程
cd /workspace/videoop
source .venv/bin/activate
python main.py

# 查看本地处理产物
ls -la data/downloads/
ls -la data/processed/

4.4 VIP 线路端到端测试

VIP 功能需要真实的 VIP 服务器，本地 Worker 无法完全模拟。推荐方式：

  1. 前端连接线上 Worker（NEXT_PUBLIC_API_URL=https://videoserver.mhana.top）
  2. 使用 VIP 账号登录（如 admin 或 boy）
  3. 观察 feed 返回的 vip_video_url 是否指向 vip.mhana.top
  4. 浏览器直接访问 VIP URL，验证视频能播放

5. 本地 vs 线上 对比

对比项 本地开发 (wrangler dev) 线上生产 (Cloudflare)
D1 数据库 本地 SQLite 文件 (空库) Cloudflare D1 (真实数据)
R2 存储 本地文件模拟 (空) Cloudflare R2 (57k+ 视频)
KV 本地模拟 Cloudflare KV
VIP 服务器 不可用 (需直连真实服务器) vip.mhana.top
数据隔离 完全隔离，随便折腾 真实用户数据
热更新 保存即生效 需 wrangler deploy

6. 代码改动 → 上线流程

6.1 修改 videoworker (Worker API)

1
本地 wrangler dev 开发测试
2
确认无误后提交推送 
cd /workspace/videoworker
git add -A && git commit -m "feat: xxx"
git push
3
部署到 Cloudflare 
CLOUDFLARE_API_TOKEN=cnnV6XiokPNh1ptMdNB-C3TuSk15tL4x5y5RFPxd npx wrangler deploy

6.2 修改 videoagt (前端)

1
本地 next dev 开发测试
2
提交推送 
cd /workspace/videoagt
git add -A && git commit -m "feat: xxx"
git push
3
部署到 Cloudflare Pages 
cd /workspace/videoagt
CLOUDFLARE_API_TOKEN=cnnV6XiokPNh1ptMdNB-C3TuSk15tL4x5y5RFPxd npm run deploy

6.3 修改 videoop (流水线)

1
本地 python main.py 测试
2
提交推送 
cd /workspace/videoop
git add -A && git commit -m "feat: xxx"
git push
3
VIP 服务器拉取并重启 
ssh -p 14028 root@137.175.4.97
cd /opt/videoop && git pull origin master
pm2 restart videoop

7. 常见问题

Q: wrangler dev 报端口占用

# 查找占用进程
ss -tlnp | grep :8787
# 或换端口
npx wrangler dev --local --port 8788

Q: 本地 D1 没有数据怎么测试 feed?

本地 D1 是空库，需要先插入测试数据：

# 手动插入测试视频
npx wrangler d1 execute video-db --local --command \
  "INSERT INTO media (id, r2_key, preview_key, thumb_key, title, duration, file_size, status) \
   VALUES ('test-1', 'videos/test-1', 'previews/test-1.webp', 'thumbs/test-1.jpg', \
   '测试视频', 30, 1000000, 'active')"

# 或者从线上导出部分数据到本地 (高级用法)
npx wrangler d1 export video-db --remote --output=dump.sql
npx wrangler d1 execute video-db --local --file=dump.sql

Q: videoop 本地运行报 Telegram session 错误

Telegram session 文件 (videoop_session.session) 绑定了特定设备。 本机的 session 文件和 VIP 服务器的是独立的，不要混用。 如果本机没有 session，需要重新认证一次：

cd /workspace/videoop
source .venv/bin/activate
python auth_telegram.py

Q: 前端页面空白 / API 报 CORS 错误

检查 Worker 的 ALLOWED_ORIGINS 是否包含 http://localhost:3000。 当前 wrangler.toml 中已配置。如果用了其他端口，需要手动添加。

Q: dev.sh 启动脚本说明

./dev.sh worker     # 只启动 Worker API (localhost:8787)
./dev.sh frontend   # 只启动前端 (localhost:3000，连线上 Worker)
./dev.sh all        # 全栈联调 (前端自动连本地 Worker)
./dev.sh pipeline   # 单次运行 videoop
./dev.sh status     # 查看运行状态
./dev.sh stop       # 停止所有服务
本地开发测试指南 — 更新于 2026-04-06