第 21 章：部署上线：Vercel / Node 服务 / 环境变量
本章目标
这一章让项目可以在线访问。小册项目如果不能部署，简历和接单价值会打折。
部署前检查
上线前至少检查：
本地构建是否通过
环境变量是否完整
API Key 是否只在服务端使用
流式输出是否在目标平台可用
上传文件大小限制是否明确
向量库是否持久化
错误提示是否友好
日志是否可查看
Vercel 部署
Next.js 项目最方便的是 Vercel。
基本步骤：
推送 GitHub 仓库
导入 Vercel
配置环境变量
部署
测试线上接口
环境变量：
OPENAI_API_KEY=...
CHAT_MODEL=openai:gpt-5.4
EMBEDDING_MODEL=text-embedding-3-small
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=...
LANGSMITH_PROJECT=ai-kb-agent
Node 服务部署
如果不用 Vercel，也可以部署到服务器：
npm install
npm run build
npm run start
配合进程管理：
pm2 start npm --name ai-kb-agent -- run start
再用 Nginx 反向代理。
上传和向量库问题
Vercel 这类 Serverless 平台不适合把上传文件长期保存在本地磁盘。
生产建议：
- 文件存对象存储
- 元数据存数据库
- 向量存专业向量库或 pgvector
- 上传后异步处理 Embedding
小册第一版可以先用本地或内存方案教学，但要明确它不是生产架构。
环境变量管理
不要在代码里写：
const apiKey = "your-api-key";
统一从环境变量读取，并在启动时校验：
export function requiredEnv(name: string) {
const value = process.env[name];
if (!value) {
throw new Error(`Missing env: ${name}`);
}
return value;
}
上线后验证
准备一份上线检查表：
Chat 能正常回答
流式输出正常
上传文档正常
知识库问答能返回引用
错误 API Key 时提示合理
超长输入会被限制
匿名用户不能访问管理接口
日志能查到请求
实战任务
完成：
- 本地
npm run build - Vercel 环境变量配置
- 线上访问 Chat
- 线上测试 RAG
- 写一份部署说明
常见坑
本地能跑不代表线上能跑。尤其是文件系统、超时、流式响应和环境变量。
不要把内存向量库当成线上方案。服务重启就会丢数据。
不要把调试错误完整暴露给用户。
本章小结
部署让项目从练习变成作品。最后一章会讲如何把它包装成简历项目和副业案例。
