用途:把 ibl.ai 应用前端部署、发布、托管到 Web,走 ibl.ai 平台托管 API。平台持有组织的 Vercel 凭据,因此不需要 Vercel 账号、Vercel token 或 vercel CLI,只需 iblai.env 中已有的 DOMAIN、PLATFORM、TOKEN。托管 API 仅限管理员:授权部署的是平台运营方为组织签发的平台 API key(iblai.env 中的 TOKEN,以 Api-Token 发送);用户自己的登录 token 不是该 key,调用会返回 403。若 iblai.env 无 TOKEN,应向运营方索取,不要用个人 token 替代。
主要能力与流程:将应用打包为 zip,POST 到平台托管端点,轮询直到构建 READY。地址以部署响应中的 site_url 返回,即项目在平台共享域下选定的子域(类似选用户名),或为其配置的自定义域;默认公开。用同一 project slug 再次 POST 即重新部署,内容与线上完全一致时自动跳过。应读取 site_url 而非 url:url 是底层 *.vercel.app 主机,由 Vercel 生成并可能修订,在实时构建确认前为 null;site_url 是平台选定的地址,项目没有任何域时为 null,两者都不要从项目名推导。
目标选择:平台托管是默认方式,覆盖多数需求。若用户提到 server、on-prem、self-host、自有 VM、Docker、Kubernetes、air-gapped 或内部主机名,或项目已有 Dockerfile / docker-compose.yml / entrypoint.sh,应改用容器部署(见 references/docker-deploy.md)。无 package.json 或纯 HTML/JS 目录可考虑静态托管或容器。若目标涉及合规或数据驻留(学区、医疗、政府),不要替用户决定,应询问。首次部署后,需把 API 报告的 URL 加入组织允许的重定向来源(询问 ibl.ai 运营方),否则部署应用上的登录无法返回,localhost 也需要。
使用方式要点:读取 iblai.env(值可能含空格,不要 source)。平台用户名来自环境变量 IBLAI_USERNAME(ibl.ai 桌面应用会导出),否则取 iblai.env;不要用 USERNAME 变量名。BASE 为 https://api.$DOMAIN/dm/api/ai-mentor/orgs/$PLATFORM/users/$IBLAI_USERNAME。项目 slug 由 package.json 的 name 规范化得到,须匹配 ^a-z0-9?$(最长 64),保持稳定。zip 限制:≤50 MB、≤2000 文件、≤200 MB 解压后;平台会剥离 .git/、node_modules/、__MACOSX/、.DS_Store、iblai.env。静态模式(output: 'export')构建后加 SPA 重写文件并打包 out/ 内容;服务端模式打包应用源码,需从 .env.local 生成 .env.production 并做校验。首次部署需选定子域(小写字母、数字、连字符),未提供会被 400 拒绝;已占用返回 409。自定义域需组织已配置,未配置或他组织仍在使用会返回 400。轮询直到 READY/ERROR/PUSH_FAILED,约 10 分钟超时;PUSH_FAILED 看 push_error,ERROR 看 build_log_tail。若存在 src-tauri/tauri.conf.json 且 APP_URL 已知,可设置 build.devUrl。
限制:托管 API 仅管理员可用;无 Vercel 凭据、zip 错误或 deployment_hash 格式错误会返回 400;静态模式下 Next.js 每次构建生成新 build ID,去重通常不生效,服务端模式去重可靠。资料未提供收费、价格与平台支持范围等信息。