Comp AI CRM 生产部署完整指南:三大服务+Postgres 上 Vercel 的 8 个避坑清单
Comp AI CRM 生产部署完整指南:三大服务+Postgres 上 Vercel 的 8 个避坑清单
Comp AI CRM 是一个专为 AI Agent 设计的开源 CRM(Agentic-first),生产部署时需要同时跑起三大服务:Next.js 前端(apps/app)、NestJS API(apps/api)和研究 Agent(apps/agent),外加一个共享 Postgres。三者互相独立,唯一的"契约"是 DATABASE_URL 和 BETTER_AUTH_SECRET——不一致时不会报错,而是陷入登录重定向死循环。本文结合仓库里的 docs/setup.md、docs/environment.md 与 .env.example,给出一份新手可直接照做的部署步骤 + 8 个真实踩坑记录。
部署架构总览:三个独立部署 + 一个 Postgres
先建立心智模型。官方部署方式是:三个部署 + 一个 Postgres(见 README.md 的 Deploying 一节)。
| 服务 | 技术栈 | 本地端口 | Vercel 上的角色 |
|---|---|---|---|
前端 apps/app |
Next.js App Router | :3000 | Web 应用(RSC) |
API apps/api |
NestJS + tRPC | :3001 | Node serverless 函数,签发会话 Cookie |
Agent apps/agent |
eve(Vercel 的持久化 Agent 框架) | :2000 | 独立运行时,自带工作队列 |
| 数据库 | Postgres 17 | :5432 | Neon 等托管 Postgres(连接池地址) |
关键点:
- 前端通过 tRPC 调 API,路由类型是从 NestJS 生成器产出的,因此
apps/api/src/generated/server.ts是已提交进仓库的文件,构建时永远不要重新生成(生成器需要比 Vercel 构建镜像更新的 GLIBC)。需要时本地重新生成并随代码一起提交。 - Agent 是完全独立的一个进程,拥有自己的调度器(apps/agent/schedules/dispatch.ts),浏览器关掉它照样干活。
- 本地环境由 docker-compose.yml 提供 Postgres 17(用户/密码/库名均为
postgres/crm),迁移与种子脚本见 packages/db/prisma/migrations/。
一键安装步骤:本地先跑通再谈生产
生产部署的最大误区是跳过本地验证。正确顺序:
cp .env.example .env—— 这是唯一的配置文件,.env.example 本身就是完整文档,每个变量都有注释。docker compose up -d起 Postgres。bun run db:migrate && bun run db:seed(seed 可跳过,会生成一套可看的演示管道)。bun run dev—— 依赖dev:prepare,每次启动都会先补迁移、再重新生成 Prisma client,三个服务一次拉起(app :3000、api :3001、agent :2000)。
本地验证通过的标志:登录页出现你的 Google/Microsoft 按钮,Agent 启动日志打印能力清单(哪些 key 已开启)。
环境变量最小清单:必需项与可选项
三个进程共用仓库根目录这一份 .env(packages/env 负责向上查找加载);真实环境变量永远优先于文件,所以 Vercel 上直接配平台变量即可。
必填四项:
| 变量 | 说明 |
|---|---|
DATABASE_URL |
指向连接池地址;若池化,另配 DIRECT_DATABASE_URL(Vercel 构建跑 prisma migrate deploy 用的直连) |
BETTER_AUTH_SECRET |
openssl rand -base64 32 生成,三处部署必须一致 |
ALLOWED_SIGN_IN |
整个鉴权模型:逗号分隔的域名或单个邮箱,如 acme.com,contractor@gmail.com。留空 = 无人可登录(安全方向失败) |
API_URL / APP_URL |
两个服务的真实源(Origin),生产必配 |
成对规则:GOOGLE_CLIENT_ID/SECRET 与 MICROSOFT_CLIENT_ID/SECRET 都是"要么都设,要么都不设"——只设一半是登录到一半才失败的按钮(packages/auth/src/env.ts 会直接抛错)。Google 客户端同时负责登录 + Gmail/日历同步;Microsoft 同理负责 Outlook 邮件。
可选但强烈建议:
AGENT_BRIDGE_SECRET:同一值设进 app 和 agent 两个进程,开启联系人页面上的 Agent 对话面板,并授权 API→Agent 的 dispatch 唤醒调用。CRON_SECRET(≥16 字符):保护POST /internal/sync/mailboxes等定时路由,不设则拒绝运行(fail closed)。REDIS_URL:无它时缓存是单实例内存缓存,多实例部署下会"算错"速率限制。BLOB_READ_WRITE_TOKEN:没有它,联系人照片完全不落库(宁可显示首字母也不热链第三方 URL)。PERPLEXITY_API_KEY、GITHUB_TOKEN、AI_GATEWAY_API_KEY:各解锁 Agent 一项外部能力;Vercel 上模型走 AI Gateway OIDC,无需 key。
Vercel 上跑迁移:时机只有一个
这是本项目最有特色的设计,务必理解(出处:docs/setup.md):
- 迁移只在生产部署时跑。
apps/api/scripts/build-func.mjs在 crm-api 构建阶段执行prisma migrate deploy,且由VERCEL_ENV === "production"门控——schema 随 release PR 合并且部署时恰好前进一次,而不是每个预览分支各跑一遍。 - 预览部署共享生产库:
DATABASE_URL只有一个值。所以带新增迁移的分支预览,构建能过、但碰到新表的页面会 500。schema 变更必须先本地测(本地bun run dev会自动迁移)。 migrate deploy不是 schema 正确的证明:No pending migrations to apply只说明_prisma_migrations里有每一行的记录。仓库里出过一次事故:某人在笔记本上跑prisma db push直接塑形了生产库,迁移行被记为已应用但 SQL 根本没执行,一张表缺了列,之后每次部署都报告"无待应用",接口却持续 500。排查方法是prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script对账;防复发靠本地守卫 packages/db/scripts/require-local-db.ts——它拦截db:migrate/db:push/db:reset/db:seed,ALLOW_REMOTE_DB=1才能对远程库操作。
避坑清单:8 个真实踩坑点
vercel env pull默认写.env.local,且它是最后加载、优先级最高的文件。拉一次生产凭据,之后所有本地进程"完美运行"地指向生产库——仓库里 2026-08-01 就有十一条迁移从一台笔记本落到了 Neon。对策:vercel env pull .env.vercel,永远别落到.env.local。- 登录重定向死循环 = 两个进程的
BETTER_AUTH_SECRET不一致(API 签 Cookie、app 验 Cookie)。历史上还出现过四个分包各自.env漂移出同类故障——本项目规则是全仓库只有根目录一份.env,严禁分包私配。 - OAuth 回调地址必须基于
API_URL构造,绝不能用APP_URL。/api/auth/callback/*只存在于 API 服务;用APP_URL拼出的 redirect_uri 会在 provider 侧报 "redirect_uri did not match",且这个错误在把APP_URL指到隧道/内网主机之前完全不显现。 vercel deploy会上传工作树,.gitignore拦不住它。仓库已用 .vercelignore 挡掉.env*、.vercel/output、node_modules等;如果你 fork 部署,确认这个文件还在,否则本地.env会被打进构建容器,Next.js 把localhost:3001内联进浏览器 bundle——部署成功、页面能开,所有请求却飞向访问者自己的机器。- 本地
eve dev不会按 cron 跑调度:任务行照常写入、界面显示 Queued,但dispatch永远不会被触发。这不是生产问题(eve start和 Vercel 都会跑调度),本地验证队列时要跑bun run --filter=agent dispatch手动排空。另外AGENT_URL本地要用127.0.0.1而不是localhost——eve dev 只监听 IPv4。 - Turborepo 会藏变量:新增环境变量有三个落脚点——
.env.example、API 的 apps/api/src/config/env.validation.ts、根 turbo.json 的globalPassThroughEnv。第三个最容易漏:Turborepo 对未声明的变量直接传undefined且毫无报错。曾因此MICROSOFT_CLIENT_ID上线后登录按钮"安静地消失"。注意用passThroughEnv而非env(后者把密钥当缓存键)。 - 修改
packages/下代码不会重启 API。bun --watch拒绝监视项目目录外的文件,改完packages/auth或packages/db必须手动重启 API——曾因此排查"scope 正确但进程里是旧的"浪费一小时。 - Cron 精度依赖套餐:所有定时任务(邮箱同步每 5 分钟、汇率/遥测/归档清理各每日一次)声明在 apps/api/vercel.json;分钟级 schedule 需要 Pro 套餐,Hobby 上会静默退化为每日运行——功能不坏,但同步频率要心里有数。
Agent 面板报错速查
| 现象 | 原因 |
|---|---|
503 |
app 进程里没设 AGENT_BRIDGE_SECRET |
401 |
两个进程密钥不一致,或 turbo.json 的 passThroughEnv 漏配了这一对 |
502 |
Agent 没在跑,或 AGENT_URL 写错(记得带 http:// 协议头,启动时校验) |
排查 Agent 是否静默丢了工具文件:GET /eve/v1/info 返回全部清单,含 diagnostics 计数。注意 localDev() 接受任何回环请求,用 curl 127.0.0.1 验证桥接证明不了什么——要带 -H 'Host: agent.example.com'。
上线前检查清单
- [ ] 三个服务
DATABASE_URL同一值;BETTER_AUTH_SECRET三处一致 - [ ]
API_URL、APP_URL为真实源;跨子域时补AUTH_COOKIE_DOMAIN(父域) - [ ] Google/Microsoft 回调 URI 已加
https://<api-host>/api/auth/callback/... - [ ]
CRON_SECRET已设(≥16 字符),邮箱同步开始跑 - [ ] 本地
bun run --filter=api test与bun run --filter=agent test通过(后者需真实 Postgres) - ] 遥测如需关闭:
CRM_TELEMETRY_DISABLED="1"(或DO_NOT_TRACK=1),见 [docs/telemetry.md
延伸阅读:docs/setup.md(本地运行与桥接排障)、docs/environment.md(变量全景与成对规则)、docs/agent.md(Agent 双通道调度)、docs/api.md(API 侧部署注意)、README.md(Quick start 与 Deploying 原文)。


