AI工程化实践：MCP+Supabase+ImageKit构建生产级视频平台-育师

1. 项目概述：这不是一个“玩具Demo”，而是一次真实工程能力的全链路压力测试

你看到标题里写着“用Claude Code从零构建YouTube克隆”，别急着点叉——这绝不是那种“三行HTML+一个iframe就叫克隆”的PPT式项目。我去年带团队做过三个视频平台类项目，从内部知识库系统到面向百万用户的教育中台，最后落地的都不是“能跑就行”，而是“上线即扛压”。这次用Claude Code做YouTube克隆，核心目的只有一个：验证AI编程助手在真实复杂业务场景下的工程闭环能力边界。它不追求UI像素级复刻，但必须覆盖用户注册、视频上传、转码分发、推荐流生成、实时评论、权限控制、计费埋点这七个硬核模块。关键词里的Supabase不是当数据库凑数的，它是整个后端服务的中枢神经；ImageKit不是简单图床，它承担着封面图智能裁剪、缩略图多尺寸自动生成、CDN缓存策略调度三重职责；MCP更不是个时髦标签——它是整个系统与外部AI模型交互的协议层，决定了你调用本地Qwen还是远程Claude时，API结构、错误码、流式响应格式、token计费逻辑是否统一可插拔。我实测过，如果跳过MCP直接硬编码调用不同模型，光是处理stream chunk的边界条件（比如chunk里混入换行符、JSON未闭合、空格分隔符错位）就能让你debug三天。这个项目真正考验的，是你能不能把AI生成的代码，像拧螺丝一样嵌进生产级架构里，而不是让它浮在demo表面。

2. 整体架构设计与技术选型逻辑：为什么是这套组合，而不是别的？

2.1 核心决策链：从“能用”到“敢用”的三次筛选

很多初学者看到“Claude Code”第一反应是“哦，就是个AI写代码的”，然后立刻去装插件、敲命令。但我在实际交付中发现，AI编程工具的价值不在“生成速度”，而在“生成质量的可控性”。我们对技术栈的选型不是拍脑袋，而是沿着一条清晰的决策链走下来的：

第一筛：能否脱离中心化大模型依赖？
YouTube克隆最怕什么？不是并发高，而是某天早上醒来发现API Key失效、Rate Limit突降为0、或者模型返回格式突然变更。所以必须把AI能力“协议化”。MCP（Model Communication Protocol）就是这个解法——它定义了一套标准化的HTTP接口规范（POST /v1/chat/completions），要求所有接入模型（无论本地LMStudio的Qwen、云端Claude、还是Docker里跑的DeepSeek）都必须遵循相同的请求体结构、响应字段、错误码体系。我们实测过，用MCP封装后，切换模型只需改一行配置，连前端调用逻辑都不用动。这比硬编码调用每个模型的私有API省了至少70%的适配成本。
第二筛：数据层能否支撑“读写分离+实时同步”？
视频平台的核心矛盾是：用户上传视频（写密集）和千万人同时刷首页（读密集）必须解耦。Supabase胜出的关键在于它把PostgreSQL的强一致性 + Realtime API的WebSocket推送 + Row Level Security（RLS）策略三者无缝缝合。举个例子：用户A上传视频后，Supabase自动触发函数生成缩略图URL并写入videos表；与此同时，首页Feed流服务通过Realtime监听videos表的INSERT事件，立刻推送给关注了A的用户。整个过程不用写一行Kafka或Redis Pub/Sub代码。而如果选Firebase，你得自己实现RLS规则来防止用户B删掉A的视频——这在生产环境是致命风险。
第三筛：媒体资产能否实现“零运维分发”？
ImageKit被选中不是因为它便宜，而是它解决了三个隐形痛点：
1. 智能裁剪：用户上传一张16:9横屏视频封面，但手机端需要1:1正方形、PC端需要4:3，ImageKit的/f_auto,c_fill,g_auto,w_300,h_300参数能自动识别人脸位置并居中裁剪，比自己搭FFmpeg集群省下2个运维人力；
2. 动态水印：VIP用户上传的视频，封面图需叠加半透明“VIP”角标，ImageKit支持URL参数实时添加水印，无需预生成多版本图片；
3. CDN穿透：当用户投诉“视频加载慢”，我们能直接在ImageKit后台查看每个CDN节点的缓存命中率、TCP连接耗时，定位是源站问题还是边缘节点故障——这是自建MinIO+Cloudflare做不到的深度可观测性。

提示：不要被“Supabase免费额度够用”误导。我们压测发现，当单日视频上传量超5000条时，Supabase的Realtime连接数会触发限频。解决方案是提前在supabase/functions/里写一个轻量级Edge Function，把高频的“点赞数更新”事件聚合后批量写入，把Realtime只留给真正需要秒级推送的场景（如直播弹幕）。

2.2 技术栈协同关系：它们不是并列组件，而是咬合齿轮

很多人把Supabase、ImageKit、MCP当成独立工具堆砌，但实际部署中它们是深度咬合的。以“用户上传视频”这个最基础操作为例，完整链路如下：

前端调用/api/upload（Vercel Edge Function）获取临时上传凭证；
凭证包含ImageKit的upload_preset和Supabase Storage的bucket_id；
用户直传视频到ImageKit，成功后ImageKit回调/api/on-upload-success；
该回调函数解析ImageKit返回的original_url，用MCP协议调用本地Qwen模型生成视频标题和标签（输入：视频帧截图+音频ASR文本）；
将生成结果连同ImageKit的thumbnail_url一起写入Supabase的videos表；
Supabase RLS策略自动限制：只有videos.owner_id = auth.uid()的用户才能UPDATE该记录；
同时触发Supabase的on_video_created函数，向Redis发布消息，触发推荐算法重新计算该视频的初始权重。

看到没？MCP在这里不是“锦上添花”，而是让AI能力成为可编排的原子操作；ImageKit不只是存储，更是AI任务的触发器；Supabase也不只是数据库，而是整个业务逻辑的协调中枢。这种深度耦合，才是“克隆”而非“模仿”的本质。

2.3 Claude Code的真实定位：它不是程序员，而是高级CRUD工程师

必须破除一个迷思：Claude Code不会帮你设计微服务拆分，也不会写分布式事务补偿逻辑。它的核心价值在将已知模式规模化复用。我们给Claude Code的指令模板是：“你是一个有5年Node.js经验的后端工程师，正在为YouTube克隆项目编写[具体模块]，请严格遵循：1. 使用Supabase JS Client v2；2. 所有SQL查询必须用RLS策略校验；3. 图片URL必须通过ImageKit CDN域名；4. AI调用必须走MCP代理端口3001”。这样生成的代码，80%能直接合并进主干。但关键的“如何设计视频分片上传的断点续传逻辑”、“怎么用WebAssembly加速客户端视频抽帧”，Claude Code给的方案全是伪代码，必须人工重写。我的经验是：把Claude Code当高级代码补全工具，而不是架构师。它擅长把‘已知正确’的模式快速铺开，但‘未知领域’的攻坚还得靠人。

3. 核心模块实现详解：从登录到推荐流，每一步都踩过坑

3.1 认证与权限系统：Supabase Auth不是开箱即用，而是要亲手拧紧每一颗螺丝

Supabase Auth提供邮箱密码、Google、GitHub三种登录方式，但直接用默认配置上线等于裸奔。我们重构了认证流程：

邮箱验证强制化：
默认情况下，用户注册后Supabase会发验证邮件，但用户不点链接也能登录。我们在auth.users表上启用RLS策略：
```
CREATE POLICY "users_must_be_verified" ON auth.users FOR SELECT USING (email_confirmed_at IS NOT NULL);
```
并在登录后检查user.email_confirmed_at，未验证则重定向到验证页。实测发现，跳过这步会导致垃圾账号注册量暴增300%，因为Bot能绕过前端验证码直接调用Supabase Auth API。
角色分级控制：
YouTube需要区分普通用户、UP主、审核员、管理员。我们没用Supabase内置的raw_user_meta_data，而是在profiles表新增role字段（enum: 'user' | 'creator' | 'moderator' | 'admin'），并通过RLS策略绑定：
```
-- 普通用户只能读自己的profile CREATE POLICY "profiles_read_own" ON public.profiles FOR SELECT USING (auth.uid() = id); -- 审核员可以读所有profile，但不能改role字段 CREATE POLICY "profiles_read_all_for_moderator" ON public.profiles FOR SELECT USING ( EXISTS (SELECT 1 FROM public.profiles p WHERE p.id = auth.uid() AND p.role = 'moderator') );
```
关键细节：role字段的UPDATE权限被完全禁止，必须通过Supabase Function调用update_user_role()来修改，该函数内嵌审批流（如：审核员升职需2名管理员签名）。
会话安全加固：
Supabase默认JWT有效期24小时，但我们把supabase.auth.signOut()改为调用/api/logout端点，该端点执行两件事：1. 调用Supabaseauth.admin.deleteUser()删除当前会话；2. 在Redis中设置blacklist:${jwt_id}过期时间=JWT剩余有效期。这样即使JWT被盗，也能在1秒内失效。测试时发现，不加这步的话，用户在手机端登出后，网页端仍能用旧Token访问API达24小时。

注意：Supabase Auth的onAuthStateChange事件在页面刷新时会触发两次（一次初始化，一次状态变更）。我们用sessionStorage临时存储last_auth_event时间戳，过滤掉100ms内的重复事件，避免重复跳转。

3.2 视频上传与处理流水线：ImageKit + FFmpeg + MCP的三角协作

用户上传视频不是“点上传→等完成”这么简单，而是一条精密流水线：

前端分片上传：
使用@uppy/core+@uppy/aws-s3-multipart，但目标不是AWS S3，而是ImageKit的multipart接口。关键配置：

const uppy = new Uppy({ restrictions: { maxFileSize: 2 * 1024 * 1024 * 1024, // 2GB allowedFileTypes: ['video/*'] } }).use(AwsS3Multipart, { limit: 5, // 同时上传5个分片 companionUrl: '/api/upload', // 我们的Vercel函数，返回ImageKit upload credentials getChunkSize: () => 5 * 1024 * 1024 // 5MB分片 });

这里companionUrl必须是我们自己写的函数，因为ImageKit需要upload_preset和signature，而signature需用ImageKit密钥动态生成（不能前端硬编码）。

ImageKit回调处理：
ImageKit上传成功后POST到/api/on-upload-success，携带file.url（原始视频URL）、file.name、file.size。我们在这个端点做三件事：
- 用FFmpeg WebAssembly（@ffmpeg/ffmpeg）在浏览器端截取前3秒生成封面图（避免服务端转码延迟）；
- 调用MCP代理http://localhost:3001/v1/chat/completions，发送视频元数据（时长、分辨率、ASR文本）请求AI生成标题；
- 将结果写入Supabasevideos表，并触发on_video_created函数。

服务端异步转码：
不是所有视频都能直接播放。我们用Supabase Functions调用cloudflare-workers执行FFmpeg转码：

// supabase/functions/transcode/index.ts export default async function transcode(event: any) { const { videoId, originalUrl } = event.queryStringParameters; // 下载originalUrl → 转码为h.264+AAC → 上传到ImageKit → 更新videos表 const transcodedUrl = await ffmpegTranscode(originalUrl); await supabase.from('videos').update({ transcoded_url: transcodedUrl, status: 'ready' }).eq('id', videoId); }

关键技巧：转码失败时，Supabase Function会自动重试3次，每次间隔指数退避（1s→2s→4s），避免雪崩。

3.3 推荐流生成：不是算法黑箱，而是可解释的规则引擎

YouTube的推荐算法当然复杂，但我们的克隆版采用“规则+轻量模型”混合架构，确保可审计、可调试：

冷启动阶段（新用户/新视频）：
用Supabase的pg_trgm扩展做相似度匹配。例如，新视频A的标题含“React Hooks”，系统自动查找videos表中标题含“React”且views > 1000的视频B、C，将B、C的标签（如#frontend #javascript）作为A的初始标签。SQL实现：
```
SELECT id, title, tags FROM videos WHERE views > 1000 AND title % 'React Hooks' ORDER BY similarity(title, 'React Hooks') DESC LIMIT 5;
```
热启动阶段（用户有行为）：
构建用户兴趣向量：
- 每个标签（#react）映射为128维向量（用Sentence-BERT预训练）；
- 用户观看时长>60%的视频，其标签向量加权求和（权重=观看时长/总时长）；
- 最终向量存入Redis，Key为user_vector:${userId}。
  推荐时，用Redis的GEORADIUS命令（把向量当地理坐标）找最近邻，比暴力遍历快100倍。
MCP赋能的实时优化：
当用户连续跳过3个推荐视频，前端触发/api/feedback?skip=3，后端用MCP调用Qwen模型分析跳过原因：
```
{ "messages": [ {"role": "system", "content": "你是一个视频推荐专家，请根据用户跳过行为分析原因"}, {"role": "user", "content": "用户跳过[视频1:前端教程]、[视频2:Vue教学]、[视频3:TypeScript入门]，历史偏好：React, Next.js, Tailwind"} ] }
```
模型返回{"reason": "内容过于基础，用户已是高级开发者", "action": "提升推荐内容难度等级"}，系统立即调整该用户的向量权重，降低初级标签权重。

实操心得：不要迷信“AI生成推荐”。我们上线后发现，纯AI推荐的CTR（点击率）比规则引擎低12%，因为AI容易过度个性化导致信息茧房。最终方案是：70%流量走规则引擎，30%流量走AI探索，用Supabase的ab_test表记录每个用户的分流结果，AB测试持续优化。

3.4 实时评论系统：Supabase Realtime不是万能胶，而是要配阻尼器

Supabase Realtime能秒级推送评论，但直接用会出大问题：

消息风暴防护：
热门视频下1秒涌入200条评论，Realtime会一次性推送200条消息，前端渲染卡顿。解决方案：在Supabase Function里加缓冲层——评论先写入comments_buffer表，由Worker每100ms批量读取并合并为一条消息（含count: 200），再通过Realtime推送。这样前端每秒只收1条消息，渲染压力下降95%。

敏感词过滤：
不能依赖前端JS过滤（易绕过）。我们在on_comment_insert触发器里调用MCP：

CREATE OR REPLACE FUNCTION filter_comment() RETURNS TRIGGER AS $$ DECLARE is_blocked BOOLEAN; BEGIN -- 调用MCP服务检测 SELECT (response::json->>'blocked')::boolean INTO is_blocked FROM http_post( 'http://localhost:3001/v1/moderate', json_build_object('text', NEW.content)::text, 'application/json' ); IF is_blocked THEN RAISE EXCEPTION 'Comment contains banned words'; END IF; RETURN NEW; END; $$ LANGUAGE plpgsql;

这里http_post是Supabase的http扩展，必须提前启用。

防刷机制：
单个IP地址1分钟内最多发5条评论。我们用Redis的INCR+EXPIRE实现：
```
# key: comment_rate_limit:192.168.1.1 INCR comment_rate_limit:192.168.1.1 EXPIRE comment_rate_limit:192.168.1.1 60
```
如果返回值>5，则拒绝插入。注意：Redis的INCR是原子操作，比数据库行锁更高效。

4. MCP协议深度实践：不止是API代理，而是AI能力的抽象层

4.1 MCP服务器搭建：为什么不用现成MCP Server，而要自己写？

网络上能找到mcp-server开源项目，但我们放弃它，原因很现实：

协议兼容性陷阱：
官方MCP Spec v0.5要求/v1/chat/completions响应必须包含usage.prompt_tokens字段，但LMStudio的Qwen模型返回的是usage.input_tokens。强行用现成Server会导致前端解析失败。我们自己写的MCP Proxy（Node.js）做了字段映射：

// mcp-proxy/routes/chat.js app.post('/v1/chat/completions', async (req, res) => { const { model, messages } = req.body; let response; if (model === 'qwen') { response = await callLMStudio(messages); // 返回{ usage: { input_tokens: 123 } } response.usage.prompt_tokens = response.usage.input_tokens; // 强制转换 } res.json(response); });

这种“脏活”现成Server不会帮你干。

流式响应的可靠性：
MCP要求流式响应（Content-Type: text/event-stream）必须按data: {...}\n\n格式，但不同模型SDK的chunk分隔符不一致。LMStudio用\n，Claude用\n\n，DeepSeek用<|eot_id|>。我们的Proxy统一转换为标准格式：

const stream = await fetch(`http://localhost:1234/v1/chat/completions`, { method: 'POST', body: JSON.stringify(req.body) }); stream.body.pipeThrough(new TextDecoderStream()) .pipeThrough(new TransformStream({ transform(chunk, controller) { // 将各种分隔符统一为 data: {json}\n\n const lines = chunk.split(/\r?\n/); lines.forEach(line => { if (line.trim() && !line.startsWith(':')) { controller.enqueue(`data: ${line}\n\n`); } }); } })) .pipeTo(res);

这段代码解决了90%的流式兼容问题。

4.2 MCP客户端集成：在Supabase Function里调用AI的正确姿势

Supabase Functions运行在隔离环境中，不能直接访问localhost。我们必须把MCP Proxy部署到公网（如Railway），然后在Function里调用：

// supabase/functions/generate-title/index.ts import { createClient } from '@supabase/supabase-js'; const supabase = createClient( process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE_KEY! ); export default async function generateTitle(event: any) { const { videoId, frames, audioText } = event.queryStringParameters; // 调用公网MCP Proxy const mcpResponse = await fetch('https://mcp-proxy-production.up.railway.app/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen', messages: [{ role: 'user', content: `基于以下信息生成YouTube视频标题（中文，≤60字）：\n视频帧描述：${frames}\n音频文字：${audioText}` }] }) }); const result = await mcpResponse.json(); const title = result.choices?.[0]?.message?.content || '未生成标题'; // 更新Supabase await supabase.from('videos').update({ title }).eq('id', videoId); }

关键细节：

超时控制：MCP调用设signal: AbortSignal.timeout(10000)，10秒无响应则放弃，避免Function卡死；
错误降级：如果MCP返回503，自动fallback到规则引擎（如提取audioText中的名词短语作为标题）；
Token计费：在MCP Proxy里记录每次调用的prompt_tokens+completion_tokens，写入ai_usage表，用于后续成本分摊。

4.3 MCP与本地模型的深度绑定：LMStudio不是摆设，而是可控的算力单元

LMStudio跑在开发机上，但生产环境必须保证稳定性：

进程守护：
用pm2管理LMStudio进程：

pm2 start "lmstudio --port 1234 --model /models/qwen2-7b.Q4_K_M.gguf" --name "lmstudio-qwen" pm2 startup # 开机自启 pm2 save # 保存进程列表

避免手动启动后忘记，导致MCP Proxy调用失败。

模型热切换：
LMStudio支持运行多个模型，但端口固定。我们用Nginx做反向代理：

upstream qwen { server localhost:1234; } upstream deepseek { server localhost:1235; } location /v1/qwen/ { proxy_pass http://qwen; } location /v1/deepseek/ { proxy_pass http://deepseek; }

这样MCP Proxy只需改URL路径就能切换模型，无需重启。

GPU显存监控：
LMStudio的--gpu-layers 50参数决定多少层放GPU，但显存不足时会OOM。我们写了个监控脚本：

# monitor-gpu.sh while true; do free_mem=$(nvidia-smi --query-gpu=memory.free --format=csv,noheader,nounits | head -1) if [ $free_mem -lt 2000 ]; then echo "GPU memory low: ${free_mem}MB, restarting LMStudio" pm2 restart lmstudio-qwen fi sleep 30 done

这个脚本救了我们三次——有次用户上传4K视频触发AI分析，LMStudio占满显存后僵死。

5. 常见问题与实战排查指南：那些文档里不会写的血泪教训

5.1 “Claude Code无法生成可用代码”的根本原因与解法

现象：Claude Code在VS Code里提示“Generating...”，然后输出一堆语法错误的代码。这不是模型问题，而是上下文污染：

问题根源：
VS Code的Claude Code插件会把当前文件的全部内容（包括注释、TODO、甚至console.log）作为上下文喂给模型。如果你的video-upload.ts里有// TODO: implement retry logic，模型会以为这是需求，生成一堆不存在的retry函数，反而破坏原有逻辑。
解法：
在VS Code设置里关闭claudeCode.includeCurrentFileInContext，改为手动选择代码块。右键选中async function uploadVideo(file: File)函数体，再按快捷键触发Claude Code。实测准确率从42%提升到89%。

进阶技巧：
创建.clauderc配置文件：

{ "context": { "include": ["src/lib/supabase.ts", "src/lib/imagekit.ts"], "exclude": ["**/*.test.ts", "**/node_modules/**"] } }

这样Claude Code只看核心依赖，不看测试文件和node_modules。

5.2 Supabase Realtime连接中断的12种可能及定位方法

Supabase Realtime用WebSocket，但中断原因五花八门：

现象	可能原因	快速定位命令
页面加载后Realtime不触发	前端未调用`supabase.channel('videos').on(...).subscribe()`	浏览器Console执行`supabase.realtime.channels`看channel列表
连接几秒后自动断开	Nginx默认`proxy_read_timeout 60`，WebSocket心跳超时	`curl -v ws://your-domain.com/realtime/v1/websocket`看HTTP状态码
仅移动端断连	iOS Safari的WebSocket在后台标签页会被系统休眠	在`visibilitychange`事件里手动reconnect
高并发时大量断连	Supabase免费计划限制100个Realtime连接	`supabase.rpc('get_connection_count')`查当前连接数

最隐蔽的问题：Cloudflare WAF拦截。我们曾遇到Realtime连接被CF返回403 Forbidden，原因是WAF规则把WebSocket Upgrade请求误判为攻击。解决方案：在Cloudflare Rules里添加if (http.request.uri.path == "/realtime/v1/websocket") then skip WAF。

5.3 ImageKit URL失效的三大陷阱

ImageKit的URL带签名，但失效原因常被忽略：

时钟不同步：
ImageKit签名验证依赖服务器时间。如果Vercel Function的系统时间比ImageKit服务器快2分钟，签名即失效。解决方案：在Vercel Dashboard里开启“Use UTC time for all functions”。
URL编码错误：
ImageKit要求/image/upload/v1680000000/sample.jpg中的/必须URL编码为%2F，但很多SDK自动编码两次。我们用encodeURIComponent(url).replace(/%2F/g, '/')手动修复。
CDN缓存污染：
用户上传同名文件（如cover.jpg），ImageKit会覆盖原文件，但CDN仍缓存旧版本。解决方案：在URL后加时间戳参数?t=${Date.now()}，或启用ImageKit的cache_buster功能。

5.4 MCP流式响应卡顿的终极诊断法

前端fetch().then(res => res.body.getReader())卡住不动？按顺序排查：

确认MCP Proxy是否真在流式响应：
curl -N "http://localhost:3001/v1/chat/completions" -H "Content-Type: application/json" -d '{"model":"qwen","messages":[{"role":"user","content":"hello"}]}'
如果没看到data: {...}\n\n持续输出，问题在Proxy层。
检查Node.js流背压：
在MCP Proxy里加res.socket.setNoDelay(true)禁用Nagle算法，避免小包合并延迟。
浏览器限制：
Chrome对单个域名的HTTP/1.1连接数限制为6。如果同时开6个Tab调用MCP，第7个会排队。解决方案：用fetch的keepalive: true或升级到HTTP/2。

最后分享一个独家技巧：在MCP Proxy里加X-MCP-Duration响应头，记录从收到请求到发出第一个chunk的时间。我们发现，LMStudio首次加载模型时，这个时间高达8秒。于是我们在服务启动时预热：curl -X POST http://localhost:1234/v1/chat/completions -d '{"messages":[{"role":"user","content":"warmup"}]}'，把冷启动成本摊到服务启动阶段。

这个YouTube克隆项目跑通后，我们把它拆解成12个可复用的模块（Auth、Upload、Transcode、Recommend、Comment等），每个模块都封装成独立的Supabase Project Template。现在新项目启动，工程师只需supabase init --template youtube-core，30分钟就能拿到生产级骨架。Claude Code在这里的角色，不是替代工程师，而是把工程师从重复劳动中解放出来，去解决真正需要人类判断的问题——比如，当AI生成的视频标题不够吸引人时，怎么设计A/B测试来验证文案效果。这才是技术该有的样子。