Comp AI CRM 生产部署完整指南:三大服务+Postgres 上 Vercel 的 8 个避坑清单

原创2026-09-22 22:20:511,958 阅读
文章标签:人工智能AI AgentCRM企业应用后端前端工具调用

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 个真实踩坑记录。

Comp AI CRM 公司列表页与 Agent 标签页的产品截图,展示 AI Agent 自动填充 CRM 记录

部署架构总览:三个独立部署 + 一个 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(连接池地址)

一句话描述 Agent 即可自动化的 Comp AI CRM Agent 构建界面

关键点:

  • 前端通过 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/。

一键安装步骤:本地先跑通再谈生产

生产部署的最大误区是跳过本地验证。正确顺序:

  1. cp .env.example .env —— 这是唯一的配置文件,.env.example 本身就是完整文档,每个变量都有注释。
  2. docker compose up -d 起 Postgres。
  3. bun run db:migrate && bun run db:seed(seed 可跳过,会生成一套可看的演示管道)。
  4. 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。

Comp AI CRM 的核心能力:记录自动填充、Agent 自建 Agent、自主预约跟进

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 个真实踩坑点

  1. vercel env pull 默认写 .env.local,且它是最后加载、优先级最高的文件。拉一次生产凭据,之后所有本地进程"完美运行"地指向生产库——仓库里 2026-08-01 就有十一条迁移从一台笔记本落到了 Neon。对策:vercel env pull .env.vercel,永远别落到 .env.local。
  2. 登录重定向死循环 = 两个进程的 BETTER_AUTH_SECRET 不一致(API 签 Cookie、app 验 Cookie)。历史上还出现过四个分包各自 .env 漂移出同类故障——本项目规则是全仓库只有根目录一份 .env,严禁分包私配。
  3. OAuth 回调地址必须基于 API_URL 构造,绝不能用 APP_URL。/api/auth/callback/* 只存在于 API 服务;用 APP_URL 拼出的 redirect_uri 会在 provider 侧报 "redirect_uri did not match",且这个错误在把 APP_URL 指到隧道/内网主机之前完全不显现。
  4. vercel deploy 会上传工作树,.gitignore 拦不住它。仓库已用 .vercelignore 挡掉 .env*、.vercel/output、node_modules 等;如果你 fork 部署,确认这个文件还在,否则本地 .env 会被打进构建容器,Next.js 把 localhost:3001 内联进浏览器 bundle——部署成功、页面能开,所有请求却飞向访问者自己的机器。
  5. 本地 eve dev 不会按 cron 跑调度:任务行照常写入、界面显示 Queued,但 dispatch 永远不会被触发。这不是生产问题(eve start 和 Vercel 都会跑调度),本地验证队列时要跑 bun run --filter=agent dispatch 手动排空。另外 AGENT_URL 本地要用 127.0.0.1 而不是 localhost——eve dev 只监听 IPv4。
  6. Turborepo 会藏变量:新增环境变量有三个落脚点——.env.example、API 的 apps/api/src/config/env.validation.ts、根 turbo.json 的 globalPassThroughEnv。第三个最容易漏:Turborepo 对未声明的变量直接传 undefined 且毫无报错。曾因此 MICROSOFT_CLIENT_ID 上线后登录按钮"安静地消失"。注意用 passThroughEnv 而非 env(后者把密钥当缓存键)。
  7. 修改 packages/ 下代码不会重启 API。bun --watch 拒绝监视项目目录外的文件,改完 packages/auth 或 packages/db 必须手动重启 API——曾因此排查"scope 正确但进程里是旧的"浪费一小时。
  8. 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 原文)。

登录后查看全文
crm