跳到主要内容

项目与部署约定

xdb-paas-deploy.yaml 告诉平台如何构建和运行项目。通常由 xdbapp link 根据项目自动生成，再由本地 AI 或开发者检查。

支持的运行环境​

Runtime当前版本适用项目
static平台静态 Runtime；前端构建使用 Node.js 22HTML / CSS / JavaScript，以及 React、Vue、Vite 等构建后的静态产物
nodejsNode.js 22.xExpress、Fastify、NestJS 等 Node.js 后端或全栈项目
pythonPython 3.11.xFlask、FastAPI 等 Python 后端或全栈项目

平台会在上述版本范围内更新安全补丁。当前不支持 PHP、Java、Go 后端和自定义 Dockerfile；如果现有项目使用其他后端语言，请先联系信多帮 CSM 确认方案，不应为接入而擅自重写项目，也不能只修改配置文件伪装成 Node.js 或 Python 项目。

runtime 是每个发布版本自己的配置，不是应用创建后永久固定的类型。同一个应用可以在后续版本采用另一种受支持的运行方式；先生成新 Preview 验证，再正式上线。旧正式版在此期间继续运行。改变运行方式不会回退、清空或自动迁移应用数据库。

Node.js 示例​

version: 1
runtime: nodejs
build: npm run build
start: npm run start
port: 8080
health_check: /healthz
database:
  provider: mysql
  migrate_command: npm run db:migrate
jobs:
  - name: daily-summary
    schedule: "0 9 * * 1-5"
    command: npm run jobs:daily-summary
    timezone: Asia/Shanghai
    timeout_seconds: 300
delayed_jobs:
  - name: order-timeout
    command: npm run jobs:order-timeout
    timeout_seconds: 300

Python 示例​

version: 1
runtime: python
build: python -m compileall .
start: python -m uvicorn app:app --host 0.0.0.0 --port 8080
port: 8080
health_check: /healthz
database:
  provider: mysql
  migrate_command: python -m alembic upgrade head

静态项目示例​

version: 1
runtime: static
build: npm run build
public_dir: dist

没有构建步骤的 HTML 项目可以省略 build，并把 public_dir 指向页面所在目录。

必须满足的约定​

  • Node.js 22 / Python 3.11 应用监听环境变量 PORT，默认值为 8080；
  • health_check 应快速返回 HTTP 2xx，且不要依赖耗时的第三方请求；
  • 平台数据库只通过 DATABASE_URL 读取；
  • Preview 与 Production 的数据库和环境变量相互隔离；
  • deploy 会在隔离环境中对 Preview 执行 migrate_command，失败时本次发布失败；
  • promote --yes 会在切换流量前对 Production 执行同一 migrate_command，失败时保留原生产版本；
  • migration 必须可重复执行并允许新旧应用版本短期共用同一套结构；代码回滚不会反向修改数据库；
  • 不要提供 Dockerfile，平台会使用统一的运行环境完成构建和隔离。

migrate_command 必须是无需交互、成功后自动退出的命令。所需工具、数据库驱动、migration 文件和锁文件必须包含在项目上传内容中，不能依赖开发电脑全局安装的软件。SQL 文件的目录组织、Node.js/Python 示例和完整上线流程见数据库与本地代理。

服务端定时任务​

Node.js/Python 应用可在 jobs 中配置最多 20 个任务。平台负责调度，不要在 Web 进程中自行常驻 cron、setInterval 无限循环或第二个进程管理器。

字段必填说明
name是应用内唯一，使用小写字母、数字、_、-，且以字母开头
schedule是标准五段 cron：分钟、小时、日、月、星期
command是在已发布镜像中执行的命令，不能包含换行
timezone否默认 Asia/Shanghai
timeout_seconds否10–3600 秒，默认 900 秒

任务只运行当前 Production Deployment，使用独立 gVisor Job，并自动注入当前 Production 环境变量和 DATABASE_URL。同一任务同一分钟只会领取一次；输出和失败原因进入 Runtime 日志与审计。任务命令必须保证重复执行安全。静态应用不能配置服务端定时任务。

一次性延迟任务​

订单超时提醒、延迟回访等“业务事件发生后只执行一次”的工作，应声明在 delayed_jobs，再由 Production 后端通过 SDK 投递；不要为每一条业务记录动态创建 cron，也不要把任意 shell 命令交给接口。

字段必填说明
name是应用内唯一的任务名；不能与 jobs 重名
command是在已发布镜像中执行的固定命令，不能包含换行
timeout_seconds否10–3600 秒，默认 900 秒

平台只接受当前 Production 清单已经声明的任务名。每个 App 最多同时等待 100 个延迟任务，最长预约 30 天，单次参数最多 32 KiB；任务使用独立 gVisor Job、当前 Production 环境变量和数据库。执行时注入：

  • XDB_PAAS_JOB_ID：本次任务的唯一 ID，用于业务幂等；
  • XDB_PAAS_JOB_NAME：清单中的任务名；
  • XDB_PAAS_JOB_SCHEDULED_FOR：预约执行时间；
  • XDB_PAAS_JOB_PAYLOAD：JSON 格式参数。

延迟任务采用至少一次执行语义。处理器必须用 XDB_PAAS_JOB_ID 或自己的业务唯一键防止重复写入。平台在真正执行时使用当时的 Production 版本：如果新版已经删除同名任务，等待中的任务会明确失败，不会执行旧镜像中的任意命令。Preview 和静态应用不能投递；本地开发时直接运行任务处理命令并使用样例参数测试。

投递、查询和取消的 JavaScript/Python 示例见延迟任务 SDK。

实时连接与流式响应​

Node.js/Python Runtime 支持普通 HTTP、SSE 和 WebSocket。SSE 会边产生边发送，不等完整响应结束；WebSocket 沿用同一个 Production/Preview 路由、信多帮登录和角色权限，单条消息当前上限 1 MiB。应用无需绕过 Gateway，也不要自行暴露容器端口。

已归档的平台素材​

如果项目使用平台已经归档的 PNG/JPEG 设计素材，将返回的 64 位素材 ID 放入 assets，而不是把临时签名地址写进源码：

assets:
  - aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

上例 ID 仅用于展示格式，必须替换为实际存在的素材 ID；每个版本最多引用 100 个。页面可使用稳定路径 /__xdb/paas/assets/<素材ID>。平台按当前版本清单和应用权限读取，上线时核验并准备正式环境素材；缺失或未准备好的素材会阻止发布，不会静默换图。

素材归档单张上限 5 MiB，并计入 App Storage 总空间。当前归档上传由内部云开发工作区工具提供，普通本地 CLI 和托管 Runtime 尚未接入 SDK 素材上传流程；不要在浏览器中调用该上传方法。普通项目自己的图片可随源码发布，用户头像、附件和导出文件则使用App Storage。

构建期配置​

构建过程默认拿不到 Preview/Production Secret。需要在编译阶段使用的非敏感公开值，请通过 xdbapp env set <KEY> --scope build --public 配置，并使用 PUBLIC_、VITE_、NEXT_PUBLIC_ 或 NUXT_PUBLIC_ 前缀。不要把 Token、密码或 AppSecret 伪装成构建变量。

上传排除规则​

.xdbpaasignore 用于排除不应上传的文件。CLI 还会内置排除常见密钥、依赖目录和版本库文件。

单次源码上传包当前最大为 50 MiB。这个限制只针对上传包，不代表安装依赖后的运行镜像大小；完整的文件、临时目录、Storage 和数据库限制见资源与文件限制。

常见排除项包括：

.env
.env.*
node_modules/
.venv/
venv/
.git/
*.pem
*.key

不要为了让发布“看起来完整”而删除密钥排除规则。生产配置请使用xdbapp env。