@ranger1/dx 0.1.80 → 0.1.81

package/README.md

@@ -181,6 +181,7 @@ dx 的命令由 `dx/config/commands.json` 驱动，并且内置了一些 interna
 
 - `internal: sdk-build`：SDK 生成/构建
 - `internal: backend-package`：后端打包
+- `internal: backend-artifact-deploy`：后端制品构建、上传与远端部署
 - `internal: start-dev`：开发环境一键启动
 - `internal: pm2-stack`：PM2 交互式服务栈（支持端口清理/缓存清理配置）
 
@@ -195,6 +196,7 @@ dx db generate
 dx db migrate --dev --name init
 dx db deploy --prod -Y
 dx deploy front --staging
+dx deploy backend --prod
 dx lint
 dx test e2e backend apps/backend/e2e/auth
 ```
@@ -284,6 +286,83 @@ dx test e2e backend apps/backend/e2e/auth
 - 需要的前置构建（例如 `shared`、`api-contracts`、OpenAPI 导出、后端构建等）应由项目自己的 Nx 依赖图（`dependsOn`/项目依赖）或 Vercel 的 `buildCommand` 负责。
 - 这样 dx deploy 不会强依赖 `apps/sdk` 等目录结构，更容易适配不同 monorepo。
 
+### backend 制品发布
+
+当 `dx/config/commands.json` 的 `deploy.backend.internal` 配置为 `backend-artifact-deploy` 时，`dx deploy backend` 走内置的后端制品发布流程，而不是 Vercel 部署。
+
+常用命令：
+
+```bash
+dx deploy backend --prod
+dx deploy backend --build-only
+dx deploy backend --prod --skip-migration
+```
+
+最小示例配置：
+
+```json
+{
+  "deploy": {
+    "backend": {
+      "internal": "backend-artifact-deploy",
+      "backendDeploy": {
+        "build": {
+          "app": "backend",
+          "distDir": "dist/backend",
+          "versionFile": "apps/backend/package.json",
+          "commands": {
+            "development": "npx nx build backend --configuration=development",
+            "staging": "npx nx build backend --configuration=production",
+            "production": "npx nx build backend --configuration=production"
+          }
+        },
+        "runtime": {
+          "appPackage": "apps/backend/package.json",
+          "rootPackage": "package.json",
+          "lockfile": "pnpm-lock.yaml",
+          "prismaSchemaDir": "apps/backend/prisma/schema",
+          "prismaConfig": "apps/backend/prisma.config.ts",
+          "ecosystemConfig": "ecosystem.config.cjs"
+        },
+        "artifact": {
+          "outputDir": "release/backend",
+          "bundleName": "backend-bundle"
+        },
+        "remote": {
+          "host": "deploy.example.com",
+          "port": 22,
+          "user": "deploy",
+          "baseDir": "/srv/example-app"
+        },
+        "startup": {
+          "mode": "pm2",
+          "serviceName": "backend"
+        },
+        "deploy": {
+          "keepReleases": 5,
+          "installCommand": "pnpm install --prod --no-frozen-lockfile --ignore-workspace",
+          "prismaGenerate": true,
+          "prismaMigrateDeploy": true
+        }
+      }
+    }
+  }
+}
+```
+
+固定远端目录协议：
+
+- `<baseDir>/releases/<version-name>`
+- `<baseDir>/current`
+- `<baseDir>/shared/.env.<environment>`
+- `<baseDir>/shared/.env.<environment>.local`
+- `<baseDir>/uploads/<bundle-file>`
+
+运行时制品约束：
+
+- 生成的 release `package.json` 默认只保留运行时依赖；如果应用把 `prisma` 放在 `devDependencies`，dx 会自动把它提升进 release 依赖，保证远端 `prisma generate` / `prisma migrate deploy` 可执行。
+- 打包前会递归扫描整个 staged payload；任意层级出现 `.env*` 文件都会直接失败，避免把环境文件误打进制品。
+
 ## 依赖关系约定
 
 dx 不负责管理「工程之间的构建依赖关系」。如果多个工程之间存在依赖（例如 `front/admin` 依赖 `shared` 或 `api-contracts`），必须由 Nx 的依赖图来表达并自动拉起：

package/codex/agents/fixer.toml

@@ -1,10 +1,7 @@
 model = "gpt-5.3-codex"
 model_reasoning_effort = "medium"
 approval_policy = "never"
-sandbox_mode = "workspace-write"
-
-[sandbox_workspace_write]
-network_access = true
+sandbox_mode = "danger-full-access"
 
 developer_instructions = '''
 你是 fix 代理。

package/codex/agents/spark.toml

@@ -1,10 +1,7 @@
 model = "gpt-5.3-codex"
 model_reasoning_effort = "medium"
 approval_policy = "never"
-sandbox_mode = "workspace-write"
-
-[sandbox_workspace_write]
-network_access = true
+sandbox_mode = "danger-full-access"
 
 developer_instructions = '''
 你是一个通用agent 根据输入的提示词，完整遵循他的要求执行任务
@@ -19,4 +16,3 @@ developer_instructions = '''
 prompt是一个文件路径并不存在时，必须返回结构化错误：{"error":"PROMPT_FILE_NOT_FOUND","detail":"<file_path>"}
 
 '''
-

package/lib/backend-artifact-deploy/artifact-builder.js

@@ -0,0 +1,240 @@
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { cp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, relative } from 'node:path'
+import { promisify } from 'node:util'
+import { execManager } from '../exec.js'
+import { basenameOrThrow, resolveWithinBase } from './path-utils.js'
+import { createRuntimePackage } from './runtime-package.js'
+
+const execFileAsync = promisify(execFile)
+
+function assertSafeNamePart(value, label) {
+  const text = String(value || '').trim()
+  if (!text || text.includes('/') || text.includes('\\') || text.includes('..')) {
+    throw new Error(`${label} 越界，已拒绝: ${text}`)
+  }
+  return text
+}
+
+function defaultNowTag() {
+  const now = new Date()
+  const pad = value => String(value).padStart(2, '0')
+  return [
+    now.getFullYear(),
+    pad(now.getMonth() + 1),
+    pad(now.getDate()),
+  ].join('') + `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+}
+
+async function defaultReadVersion(versionFile) {
+  const pkg = JSON.parse(await readFile(versionFile, 'utf8'))
+  return String(pkg.version || '').trim()
+}
+
+async function defaultRunBuild(build) {
+  if (!build?.command) {
+    throw new Error('缺少构建命令: build.command')
+  }
+  await execManager.executeCommand(build.command, {
+    app: build.app || undefined,
+  })
+}
+
+async function defaultPrepareOutputDir(outputDir) {
+  await mkdir(outputDir, { recursive: true })
+}
+
+async function copyIntoDir(source, destinationDir) {
+  if (!existsSync(source)) {
+    throw new Error(`缺少必需文件或目录: ${source}`)
+  }
+  await cp(source, destinationDir, { recursive: true })
+}
+
+async function defaultStageFiles({ config, stageDir, stagePlan }) {
+  await rm(stageDir, { recursive: true, force: true })
+  await mkdir(stageDir, { recursive: true })
+
+  for (const entry of await readdir(stagePlan.dist.source)) {
+    await copyIntoDir(join(stagePlan.dist.source, entry), join(stageDir, entry))
+  }
+
+  const appPackage = JSON.parse(await readFile(stagePlan.appPackage.source, 'utf8'))
+  const rootPackage = JSON.parse(await readFile(stagePlan.rootPackage.source, 'utf8'))
+  const runtimePackage = createRuntimePackage({ appPackage, rootPackage })
+  await writeFile(join(stageDir, stagePlan.runtimePackage.destination), `${JSON.stringify(runtimePackage, null, 2)}\n`)
+
+  await copyIntoDir(stagePlan.lockfile.source, join(stageDir, stagePlan.lockfile.destination))
+
+  if (stagePlan.prismaSchema) {
+    await mkdir(join(stageDir, dirname(stagePlan.prismaSchema.destination)), { recursive: true })
+    await copyIntoDir(stagePlan.prismaSchema.source, join(stageDir, stagePlan.prismaSchema.destination))
+  }
+  if (stagePlan.prismaConfig) {
+    await mkdir(join(stageDir, dirname(stagePlan.prismaConfig.destination)), { recursive: true })
+    await copyIntoDir(stagePlan.prismaConfig.source, join(stageDir, stagePlan.prismaConfig.destination))
+  }
+  if (stagePlan.ecosystemConfig) {
+    await copyIntoDir(stagePlan.ecosystemConfig.source, join(stageDir, stagePlan.ecosystemConfig.destination))
+  }
+}
+
+async function defaultAssertNoEnvFiles(stageDir) {
+  const envFiles = []
+  const queue = ['.']
+
+  while (queue.length > 0) {
+    const currentRelativeDir = queue.shift()
+    const currentDir = currentRelativeDir === '.' ? stageDir : join(stageDir, currentRelativeDir)
+    const entries = await readdir(currentDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const entryRelativePath =
+        currentRelativeDir === '.' ? entry.name : join(currentRelativeDir, entry.name)
+
+      if (entry.name.startsWith('.env')) {
+        envFiles.push(entryRelativePath.replace(/\\/g, '/'))
+      }
+
+      if (entry.isDirectory()) {
+        queue.push(entryRelativePath)
+      }
+    }
+  }
+
+  if (envFiles.length > 0) {
+    throw new Error(`制品目录包含 .env* 文件: ${envFiles.join(', ')}`)
+  }
+}
+
+async function defaultCreateInnerArchive({ stageDir, innerArchivePath }) {
+  await mkdir(dirname(innerArchivePath), { recursive: true })
+  await execFileAsync('tar', ['-czf', innerArchivePath, '.'], {
+    cwd: stageDir,
+  })
+}
+
+async function defaultWriteChecksum({ archivePath, checksumPath }) {
+  try {
+    const { stdout } = await execFileAsync('sha256sum', [archivePath])
+    await writeFile(checksumPath, stdout)
+  } catch {
+    const { stdout } = await execFileAsync('shasum', ['-a', '256', archivePath])
+    await writeFile(checksumPath, stdout)
+  }
+}
+
+async function defaultCreateBundle({ outputDir, bundlePath, innerArchivePath, checksumPath }) {
+  await execFileAsync(
+    'tar',
+    ['-czf', bundlePath, basename(innerArchivePath), basename(checksumPath)],
+    { cwd: outputDir },
+  )
+}
+
+export function createArtifactNames({ version, timeTag, bundleName }) {
+  const safeVersion = assertSafeNamePart(version, 'version')
+  const safeTimeTag = assertSafeNamePart(timeTag, 'timeTag')
+  const safeBundleName = assertSafeNamePart(bundleName, 'bundleName')
+  const versionName = `backend-v${safeVersion}-${safeTimeTag}`
+  const innerArchiveName = `${versionName}.tgz`
+  return {
+    versionName,
+    innerArchiveName,
+    checksumName: `${innerArchiveName}.sha256`,
+    bundleName: `${safeBundleName}-v${safeVersion}-${safeTimeTag}.tgz`,
+  }
+}
+
+export function createStagePlan(config) {
+  const projectRoot = config.projectRoot || '/'
+  const relativeToProject = targetPath =>
+    relative(projectRoot, targetPath).replace(/\\/g, '/').replace(/^repo\//, '')
+  const plan = {
+    dist: {
+      source: config.build.distDir,
+      destination: '.',
+    },
+    runtimePackage: {
+      destination: 'package.json',
+    },
+    lockfile: {
+      source: config.runtime.lockfile,
+      destination: 'pnpm-lock.yaml',
+    },
+    appPackage: {
+      source: config.runtime.appPackage,
+    },
+    rootPackage: {
+      source: config.runtime.rootPackage,
+    },
+  }
+
+  if (config.runtime.prismaSchemaDir) {
+    plan.prismaSchema = {
+      source: config.runtime.prismaSchemaDir,
+      destination: relativeToProject(config.runtime.prismaSchemaDir),
+    }
+  }
+  if (config.runtime.prismaConfig) {
+    plan.prismaConfig = {
+      source: config.runtime.prismaConfig,
+      destination: relativeToProject(config.runtime.prismaConfig),
+    }
+  }
+  if (config.runtime.ecosystemConfig) {
+    plan.ecosystemConfig = {
+      source: config.runtime.ecosystemConfig,
+      destination: basenameOrThrow(config.runtime.ecosystemConfig, 'runtime.ecosystemConfig'),
+    }
+  }
+
+  return plan
+}
+
+export async function buildBackendArtifact(config, deps = {}) {
+  const nowTag = deps.nowTag || defaultNowTag
+  const readVersion = deps.readVersion || defaultReadVersion
+  const runBuild = deps.runBuild || defaultRunBuild
+  const prepareOutputDir = deps.prepareOutputDir || defaultPrepareOutputDir
+  const stageFiles = deps.stageFiles || defaultStageFiles
+  const assertNoEnvFiles = deps.assertNoEnvFiles || defaultAssertNoEnvFiles
+  const createInnerArchive = deps.createInnerArchive || defaultCreateInnerArchive
+  const writeChecksum = deps.writeChecksum || defaultWriteChecksum
+  const createBundle = deps.createBundle || defaultCreateBundle
+  const version = await readVersion(config.build.versionFile)
+  const timeTag = nowTag()
+  const names = createArtifactNames({
+    version,
+    timeTag,
+    bundleName: config.artifact.bundleName,
+  })
+
+  const outputDir = resolveWithinBase(config.artifact.outputDir, '.', 'artifact.outputDir')
+  const stageDir = resolveWithinBase(outputDir, names.versionName, 'stageDir')
+  const innerArchivePath = resolveWithinBase(outputDir, names.innerArchiveName, 'innerArchivePath')
+  const checksumPath = resolveWithinBase(outputDir, names.checksumName, 'checksumPath')
+  const bundlePath = resolveWithinBase(outputDir, names.bundleName, 'bundlePath')
+
+  await runBuild(config.build)
+  await prepareOutputDir(outputDir)
+  await stageFiles({
+    config,
+    stageDir,
+    stagePlan: createStagePlan(config),
+  })
+  await assertNoEnvFiles(stageDir)
+  await createInnerArchive({ stageDir, innerArchivePath })
+  await writeChecksum({ archivePath: innerArchivePath, checksumPath })
+  await createBundle({ outputDir, bundlePath, innerArchivePath, checksumPath })
+
+  return {
+    version,
+    timeTag,
+    versionName: names.versionName,
+    bundlePath,
+    innerArchivePath,
+    checksumPath,
+  }
+}

package/lib/backend-artifact-deploy/config.js

@@ -0,0 +1,138 @@
+import { isAbsolute } from 'node:path'
+import { resolveWithinBase } from './path-utils.js'
+
+function requireString(value, fieldPath) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`缺少必填配置: ${fieldPath}`)
+  }
+  return value.trim()
+}
+
+function requirePositiveInteger(value, fieldPath) {
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`缺少必填配置: ${fieldPath}`)
+  }
+  return parsed
+}
+
+function resolveBuildCommand(buildConfig, environment) {
+  if (buildConfig?.commands && typeof buildConfig.commands === 'object') {
+    const selected = buildConfig.commands[environment]
+    if (!selected || typeof selected !== 'string' || selected.trim() === '') {
+      throw new Error(`缺少必填配置: build.commands.${environment}`)
+    }
+    return selected.trim()
+  }
+
+  return requireString(buildConfig?.command, 'build.command')
+}
+
+function resolveProjectPath(projectRoot, relativePath, fieldPath) {
+  return resolveWithinBase(projectRoot, requireString(relativePath, fieldPath), fieldPath)
+}
+
+function requireRemoteBaseDir(value, fieldPath) {
+  const baseDir = requireString(value, fieldPath)
+  if (!isAbsolute(baseDir)) {
+    throw new Error(`${fieldPath} 必须是绝对路径: ${baseDir}`)
+  }
+  if (!/^\/[A-Za-z0-9._/-]*$/.test(baseDir)) {
+    throw new Error(`${fieldPath} 包含非法字符: ${baseDir}`)
+  }
+  return baseDir.replace(/\/+$/, '') || '/'
+}
+
+export function resolveBackendDeployConfig({ cli, targetConfig, environment, flags = {} }) {
+  const deployConfig = targetConfig?.backendDeploy
+  if (!deployConfig || typeof deployConfig !== 'object') {
+    throw new Error('缺少必填配置: backendDeploy')
+  }
+
+  const buildConfig = deployConfig.build || {}
+  const runtimeConfig = deployConfig.runtime || {}
+  const artifactConfig = deployConfig.artifact || {}
+  const remoteConfig = deployConfig.remote || null
+  const startupConfig = deployConfig.startup || {}
+  const runConfig = deployConfig.deploy || {}
+  const buildOnly = Boolean(flags.buildOnly)
+  const startupMode = String(startupConfig.mode || 'pm2').trim()
+  const prismaGenerate = runConfig.prismaGenerate !== false
+  const prismaMigrateDeploy = runConfig.prismaMigrateDeploy !== false
+
+  const normalized = {
+    projectRoot: cli.projectRoot,
+    environment,
+    build: {
+      app: typeof buildConfig.app === 'string' && buildConfig.app.trim() ? buildConfig.app.trim() : null,
+      command: resolveBuildCommand(buildConfig, environment),
+      distDir: resolveProjectPath(cli.projectRoot, buildConfig.distDir, 'build.distDir'),
+      versionFile: resolveProjectPath(cli.projectRoot, buildConfig.versionFile, 'build.versionFile'),
+    },
+    runtime: {
+      appPackage: resolveProjectPath(cli.projectRoot, runtimeConfig.appPackage, 'runtime.appPackage'),
+      rootPackage: resolveProjectPath(cli.projectRoot, runtimeConfig.rootPackage, 'runtime.rootPackage'),
+      lockfile: resolveProjectPath(cli.projectRoot, runtimeConfig.lockfile, 'runtime.lockfile'),
+      prismaSchemaDir: runtimeConfig.prismaSchemaDir
+        ? resolveProjectPath(cli.projectRoot, runtimeConfig.prismaSchemaDir, 'runtime.prismaSchemaDir')
+        : null,
+      prismaConfig: runtimeConfig.prismaConfig
+        ? resolveProjectPath(cli.projectRoot, runtimeConfig.prismaConfig, 'runtime.prismaConfig')
+        : null,
+      ecosystemConfig: runtimeConfig.ecosystemConfig
+        ? resolveProjectPath(cli.projectRoot, runtimeConfig.ecosystemConfig, 'runtime.ecosystemConfig')
+        : null,
+    },
+    artifact: {
+      outputDir: resolveProjectPath(cli.projectRoot, artifactConfig.outputDir, 'artifact.outputDir'),
+      bundleName: requireString(artifactConfig.bundleName, 'artifact.bundleName'),
+    },
+    remote: buildOnly
+      ? null
+      : {
+          host: requireString(remoteConfig?.host, 'remote.host'),
+          port: remoteConfig?.port == null ? 22 : requirePositiveInteger(remoteConfig.port, 'remote.port'),
+          user: requireString(remoteConfig?.user, 'remote.user'),
+          baseDir: requireRemoteBaseDir(remoteConfig?.baseDir, 'remote.baseDir'),
+        },
+    startup: {
+      mode: startupMode,
+      serviceName:
+        typeof startupConfig.serviceName === 'string' && startupConfig.serviceName.trim()
+          ? startupConfig.serviceName.trim()
+          : null,
+      entry:
+        typeof startupConfig.entry === 'string' && startupConfig.entry.trim()
+          ? startupConfig.entry.trim()
+          : null,
+    },
+    deploy: {
+      keepReleases:
+        runConfig.keepReleases == null ? 5 : requirePositiveInteger(runConfig.keepReleases, 'deploy.keepReleases'),
+      installCommand: requireString(
+        runConfig.installCommand || 'pnpm install --prod --no-frozen-lockfile --ignore-workspace',
+        'deploy.installCommand',
+      ),
+      prismaGenerate,
+      prismaMigrateDeploy,
+      skipMigration: Boolean(flags.skipMigration),
+    },
+  }
+
+  if (!['pm2', 'direct'].includes(normalized.startup.mode)) {
+    throw new Error('缺少必填配置: startup.mode')
+  }
+  if (normalized.startup.mode === 'pm2') {
+    requireString(normalized.startup.serviceName, 'startup.serviceName')
+    requireString(normalized.runtime.ecosystemConfig, 'runtime.ecosystemConfig')
+  } else {
+    requireString(normalized.startup.entry, 'startup.entry')
+  }
+
+  if (normalized.deploy.prismaGenerate || normalized.deploy.prismaMigrateDeploy) {
+    requireString(normalized.runtime.prismaSchemaDir, 'runtime.prismaSchemaDir')
+    requireString(normalized.runtime.prismaConfig, 'runtime.prismaConfig')
+  }
+
+  return normalized
+}

package/lib/backend-artifact-deploy/path-utils.js

@@ -0,0 +1,18 @@
+import { basename, resolve, sep } from 'node:path'
+
+export function resolveWithinBase(baseDir, targetPath, label = 'path') {
+  const absoluteBase = resolve(baseDir)
+  const absoluteTarget = resolve(absoluteBase, targetPath)
+  if (absoluteTarget !== absoluteBase && !absoluteTarget.startsWith(`${absoluteBase}${sep}`)) {
+    throw new Error(`${label} 越界，已拒绝: ${absoluteTarget}`)
+  }
+  return absoluteTarget
+}
+
+export function basenameOrThrow(filePath, label = 'path') {
+  const name = basename(String(filePath || '').trim())
+  if (!name || name === '.' || name === '..') {
+    throw new Error(`无效的 ${label}: ${filePath}`)
+  }
+  return name
+}

package/lib/backend-artifact-deploy/remote-phases.js

@@ -0,0 +1,13 @@
+export function createRemotePhaseModel(payload) {
+  return [
+    { phase: 'lock', payload },
+    { phase: 'extract', payload },
+    { phase: 'env', payload },
+    { phase: 'install', payload },
+    { phase: 'prisma-generate', payload },
+    { phase: 'prisma-migrate', payload },
+    { phase: 'switch-current', payload },
+    { phase: 'startup', payload },
+    { phase: 'cleanup', payload },
+  ]
+}

package/lib/backend-artifact-deploy/remote-result.js

@@ -0,0 +1,42 @@
+function parseResultLine(line) {
+  if (!line.startsWith('DX_REMOTE_RESULT=')) return null
+  return JSON.parse(line.slice('DX_REMOTE_RESULT='.length))
+}
+
+function getLastPhase(output = '') {
+  const lines = String(output).split('\n')
+  let phase = 'cleanup'
+  for (const line of lines) {
+    if (line.startsWith('DX_REMOTE_PHASE=')) {
+      phase = line.slice('DX_REMOTE_PHASE='.length).trim() || phase
+    }
+  }
+  return phase
+}
+
+export function parseRemoteResult({ stdout = '', stderr = '', exitCode = 0 }) {
+  const allLines = `${stdout}\n${stderr}`.trim().split('\n').filter(Boolean)
+  for (let index = allLines.length - 1; index >= 0; index -= 1) {
+    const parsed = parseResultLine(allLines[index])
+    if (parsed) return parsed
+  }
+
+  if (exitCode === 0) {
+    return {
+      ok: true,
+      phase: getLastPhase(stdout),
+      message: 'ok',
+      rollbackAttempted: false,
+      rollbackSucceeded: null,
+    }
+  }
+
+  const message = [stderr, stdout].filter(Boolean).join('\n').trim() || 'remote execution failed'
+  return {
+    ok: false,
+    phase: getLastPhase(`${stdout}\n${stderr}`),
+    message,
+    rollbackAttempted: false,
+    rollbackSucceeded: null,
+  }
+}

package/lib/backend-artifact-deploy/remote-script.js

@@ -0,0 +1,337 @@
+function escapeShell(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+export function buildRemoteDeployScript(phaseModel = []) {
+  const payload = phaseModel[0]?.payload || {}
+  const remote = payload.remote || {}
+  const runtime = payload.runtime || {}
+  const startup = payload.startup || {}
+  const deploy = payload.deploy || {}
+  const environment = String(payload.environment || 'production')
+  const baseDir = String(remote.baseDir || '.')
+  const releaseDir = `${baseDir}/releases/${payload.versionName || 'unknown'}`
+  const currentLink = `${baseDir}/current`
+  const uploadsDir = `${baseDir}/uploads`
+  const uploadedBundlePath = String(payload.uploadedBundlePath || '')
+  const envFileName = `.env.${environment}`
+  const envLocalFileName = `.env.${environment}.local`
+  const prismaSchema = runtime.prismaSchemaDir ? `./${runtime.prismaSchemaDir}` : ''
+  const prismaConfig = runtime.prismaConfig ? `./${runtime.prismaConfig}` : ''
+  const ecosystemConfig = runtime.ecosystemConfig ? `./${runtime.ecosystemConfig}` : './ecosystem.config.cjs'
+  const installCommand = String(deploy.installCommand || 'pnpm install --prod --no-frozen-lockfile --ignore-workspace')
+  const startupEntry = String(startup.entry || '')
+  const startupMode = String(startup.mode || 'pm2')
+  const serviceName = String(startup.serviceName || 'backend')
+  const keepReleases = Number(deploy.keepReleases || 5)
+  const shouldGenerate = deploy.prismaGenerate !== false
+  const shouldMigrate = deploy.prismaMigrateDeploy !== false && deploy.skipMigration !== true
+
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+APP_ROOT=${escapeShell(baseDir)}
+UPLOADS_DIR=${escapeShell(uploadsDir)}
+ARCHIVE=${escapeShell(uploadedBundlePath)}
+RELEASE_DIR=${escapeShell(releaseDir)}
+CURRENT_LINK=${escapeShell(currentLink)}
+ENV_NAME=${escapeShell(environment)}
+ENV_FILE_NAME=${escapeShell(envFileName)}
+ENV_LOCAL_FILE_NAME=${escapeShell(envLocalFileName)}
+PRISMA_SCHEMA=${escapeShell(prismaSchema)}
+PRISMA_CONFIG=${escapeShell(prismaConfig)}
+ECOSYSTEM_CONFIG=${escapeShell(ecosystemConfig)}
+INSTALL_COMMAND=${escapeShell(installCommand)}
+START_MODE=${escapeShell(startupMode)}
+SERVICE_NAME=${escapeShell(serviceName)}
+START_ENTRY=${escapeShell(startupEntry)}
+KEEP_RELEASES=${keepReleases}
+SHOULD_GENERATE=${shouldGenerate ? '1' : '0'}
+SHOULD_MIGRATE=${shouldMigrate ? '1' : '0'}
+
+LOCK_FILE="$APP_ROOT/.deploy.lock"
+LOCK_DIR="$APP_ROOT/.deploy.lock.d"
+SHARED_DIR="$APP_ROOT/shared"
+RELEASES_DIR="$APP_ROOT/releases"
+PREVIOUS_CURRENT_TARGET=""
+BUNDLE_TEMP_DIR=""
+INNER_ARCHIVE=""
+INNER_ARCHIVE_SHA256_FILE=""
+VERSION_NAME=""
+DOTENV_BIN=""
+PRISMA_BIN=""
+CURRENT_PHASE="init"
+RESULT_EMITTED=0
+ROLLBACK_ATTEMPTED=false
+ROLLBACK_SUCCEEDED=null
+MIGRATION_EXECUTED=0
+
+emit_result() {
+  local ok="$1"
+  local phase="$2"
+  local message="$3"
+  local rollback_attempted="$4"
+  local rollback_succeeded="$5"
+  if [[ "$RESULT_EMITTED" -eq 1 ]]; then
+    return
+  fi
+  RESULT_EMITTED=1
+  message="\${message//\\\\/\\\\\\\\}"
+  message="\${message//\"/\\\\\"}"
+  message="\${message//$'\\n'/\\\\n}"
+  printf 'DX_REMOTE_RESULT={"ok":%s,"phase":"%s","message":"%s","rollbackAttempted":%s,"rollbackSucceeded":%s}\\n' \\
+    "$ok" "$phase" "$message" "$rollback_attempted" "$rollback_succeeded"
+}
+
+cleanup() {
+  rm -rf "$BUNDLE_TEMP_DIR" 2>/dev/null || true
+  if [[ -n "$LOCK_DIR" ]]; then
+    rmdir "$LOCK_DIR" 2>/dev/null || true
+  fi
+}
+
+on_error() {
+  local code=$?
+  emit_result false "$CURRENT_PHASE" "phase failed (exit $code)" "$ROLLBACK_ATTEMPTED" "$ROLLBACK_SUCCEEDED"
+  exit "$code"
+}
+
+trap cleanup EXIT
+trap on_error ERR
+
+validate_path_within_base() {
+  local base="$1"
+  local target="$2"
+  case "$target" in
+    "$base"/*|"$base") ;;
+    *)
+      echo "目标路径越界: $target" >&2
+      exit 1
+      ;;
+  esac
+}
+
+validate_archive_entries() {
+  local archive="$1"
+  local entry
+  local tar_line
+  local link_target
+
+  while IFS= read -r entry; do
+    if [[ "$entry" == /* ]]; then
+      echo "包含绝对路径条目: $entry" >&2
+      exit 1
+    fi
+    if [[ "$entry" =~ (^|/)\\.\\.(/|$) || "$entry" =~ \\.\\.\\\\ ]]; then
+      echo "包含可疑路径条目: $entry" >&2
+      exit 1
+    fi
+  done < <(tar -tzf "$archive")
+
+  while IFS= read -r tar_line; do
+    if [[ "$tar_line" == *" -> "* ]]; then
+      link_target="\${tar_line##* -> }"
+      if [[ "$link_target" == /* ]]; then
+        echo "包含可疑链接目标: $link_target" >&2
+        exit 1
+      fi
+      if [[ "$link_target" =~ (^|/)\\.\\.(/|$) || "$link_target" =~ \\.\\.\\\\ ]]; then
+        echo "包含可疑链接目标: $link_target" >&2
+        exit 1
+      fi
+    fi
+  done < <(tar -tvzf "$archive")
+}
+
+find_single_bundle_file() {
+  local bundle_dir="$1"
+  local pattern="$2"
+  shopt -s nullglob
+  local matches=("$bundle_dir"/$pattern)
+  shopt -u nullglob
+  if [[ "\${#matches[@]}" -ne 1 ]]; then
+    return 1
+  fi
+  printf '%s\\n' "\${matches[0]}"
+}
+
+sha256_check() {
+  local checksum_file="$1"
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum -c "$checksum_file"
+    return
+  fi
+  local checksum expected file
+  checksum="$(awk '{print $1}' "$checksum_file")"
+  file="$(awk '{print $2}' "$checksum_file")"
+  expected="$(shasum -a 256 "$file" | awk '{print $1}')"
+  [[ "$checksum" == "$expected" ]]
+}
+
+run_with_env() {
+  local cwd="$1"
+  shift
+  (
+    cd "$cwd"
+    APP_ENV="$ENV_NAME" "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- "$@"
+  )
+}
+
+attempt_pm2_restore() {
+  if [[ -z "$PREVIOUS_CURRENT_TARGET" || ! -e "$PREVIOUS_CURRENT_TARGET/$ECOSYSTEM_CONFIG" ]]; then
+    ROLLBACK_SUCCEEDED=false
+    return
+  fi
+  if (
+    cd "$PREVIOUS_CURRENT_TARGET"
+    APP_ENV="$ENV_NAME" "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
+      pm2 start "$ECOSYSTEM_CONFIG" --only "$SERVICE_NAME" --update-env
+    pm2 save
+  ); then
+    ROLLBACK_SUCCEEDED=true
+  else
+    ROLLBACK_SUCCEEDED=false
+  fi
+}
+
+CURRENT_PHASE="lock"
+echo "DX_REMOTE_PHASE=lock"
+mkdir -p "$RELEASES_DIR" "$SHARED_DIR" "$UPLOADS_DIR"
+validate_path_within_base "$APP_ROOT" "$ARCHIVE"
+validate_path_within_base "$APP_ROOT" "$RELEASE_DIR"
+
+PREVIOUS_CURRENT_TARGET="$(readlink "$CURRENT_LINK" 2>/dev/null || true)"
+
+if command -v flock >/dev/null 2>&1; then
+  exec 9>"$LOCK_FILE"
+  flock -n 9
+else
+  mkdir "$LOCK_DIR"
+fi
+
+CURRENT_PHASE="extract"
+echo "DX_REMOTE_PHASE=extract"
+validate_archive_entries "$ARCHIVE"
+BUNDLE_TEMP_DIR="$(mktemp -d "$APP_ROOT/.bundle-extract.XXXXXX")"
+tar -xzf "$ARCHIVE" -C "$BUNDLE_TEMP_DIR" --strip-components=1
+
+INNER_ARCHIVE="$(find_single_bundle_file "$BUNDLE_TEMP_DIR" 'backend-v*.tgz')"
+INNER_ARCHIVE_SHA256_FILE="$(find_single_bundle_file "$BUNDLE_TEMP_DIR" 'backend-v*.tgz.sha256')"
+VERSION_NAME="$(basename "$INNER_ARCHIVE" .tgz)"
+validate_path_within_base "$RELEASES_DIR" "$RELEASE_DIR"
+
+(cd "$BUNDLE_TEMP_DIR" && sha256_check "$(basename "$INNER_ARCHIVE_SHA256_FILE")")
+validate_archive_entries "$INNER_ARCHIVE"
+rm -rf "$RELEASE_DIR"
+mkdir -p "$RELEASE_DIR"
+tar -xzf "$INNER_ARCHIVE" -C "$RELEASE_DIR" --strip-components=1
+
+CURRENT_PHASE="env"
+echo "DX_REMOTE_PHASE=env"
+if [[ ! -f "$SHARED_DIR/$ENV_FILE_NAME" ]]; then
+  echo "未找到基础环境文件: $SHARED_DIR/$ENV_FILE_NAME" >&2
+  exit 1
+fi
+if [[ ! -f "$SHARED_DIR/$ENV_LOCAL_FILE_NAME" ]]; then
+  echo "未找到本地覆盖环境文件: $SHARED_DIR/$ENV_LOCAL_FILE_NAME" >&2
+  exit 1
+fi
+ln -sfn "$SHARED_DIR/$ENV_FILE_NAME" "$RELEASE_DIR/$ENV_FILE_NAME"
+ln -sfn "$SHARED_DIR/$ENV_LOCAL_FILE_NAME" "$RELEASE_DIR/$ENV_LOCAL_FILE_NAME"
+
+CURRENT_PHASE="install"
+echo "DX_REMOTE_PHASE=install"
+command -v node >/dev/null 2>&1
+command -v pnpm >/dev/null 2>&1
+if [[ "$START_MODE" == "pm2" ]]; then
+  command -v pm2 >/dev/null 2>&1
+fi
+(
+  cd "$RELEASE_DIR"
+  bash -lc "$INSTALL_COMMAND"
+)
+
+DOTENV_BIN="$RELEASE_DIR/node_modules/.bin/dotenv"
+if [[ ! -x "$DOTENV_BIN" ]]; then
+  echo "缺少可执行文件: $DOTENV_BIN" >&2
+  exit 1
+fi
+
+if [[ "$SHOULD_GENERATE" == "1" ]]; then
+  CURRENT_PHASE="prisma-generate"
+  echo "DX_REMOTE_PHASE=prisma-generate"
+  PRISMA_BIN="$RELEASE_DIR/node_modules/.bin/prisma"
+  if [[ ! -x "$PRISMA_BIN" ]]; then
+    echo "缺少可执行文件: $PRISMA_BIN" >&2
+    exit 1
+  fi
+  run_with_env "$RELEASE_DIR" "$PRISMA_BIN" generate --schema="$PRISMA_SCHEMA" --config="$PRISMA_CONFIG"
+fi
+
+if [[ "$SHOULD_MIGRATE" == "1" ]]; then
+  CURRENT_PHASE="prisma-migrate"
+  echo "DX_REMOTE_PHASE=prisma-migrate"
+  PRISMA_BIN="$RELEASE_DIR/node_modules/.bin/prisma"
+  if [[ ! -x "$PRISMA_BIN" ]]; then
+    echo "缺少可执行文件: $PRISMA_BIN" >&2
+    exit 1
+  fi
+  run_with_env "$RELEASE_DIR" "$PRISMA_BIN" migrate deploy --schema="$PRISMA_SCHEMA" --config="$PRISMA_CONFIG"
+  MIGRATION_EXECUTED=1
+fi
+
+CURRENT_PHASE="switch-current"
+echo "DX_REMOTE_PHASE=switch-current"
+ln -sfn "$RELEASE_DIR" "$CURRENT_LINK"
+
+CURRENT_PHASE="startup"
+echo "DX_REMOTE_PHASE=startup"
+if [[ "$START_MODE" == "pm2" ]]; then
+  if ! (
+    cd "$CURRENT_LINK"
+    pm2 delete "$SERVICE_NAME" || true
+    APP_ENV="$ENV_NAME" "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
+      pm2 start "$ECOSYSTEM_CONFIG" --only "$SERVICE_NAME" --update-env
+    pm2 save
+  ); then
+    if [[ "$MIGRATION_EXECUTED" -eq 0 && -n "$PREVIOUS_CURRENT_TARGET" ]]; then
+      ROLLBACK_ATTEMPTED=true
+      ln -sfn "$PREVIOUS_CURRENT_TARGET" "$CURRENT_LINK"
+      attempt_pm2_restore
+    fi
+    emit_result false "startup" "pm2 startup failed" "$ROLLBACK_ATTEMPTED" "$ROLLBACK_SUCCEEDED"
+    exit 1
+  fi
+else
+  if ! (
+    cd "$CURRENT_LINK"
+    APP_ENV="$ENV_NAME" "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
+      node "$START_ENTRY"
+  ); then
+    emit_result false "startup" "direct startup failed" false null
+    exit 1
+  fi
+  emit_result true "startup" "direct mode attached" false null
+  exit 0
+fi
+
+CURRENT_PHASE="cleanup"
+echo "DX_REMOTE_PHASE=cleanup"
+release_count=0
+shopt -s nullglob
+release_dirs=("$RELEASES_DIR"/*)
+shopt -u nullglob
+while IFS= read -r old_release; do
+  release_count=$((release_count + 1))
+  if [[ "$release_count" -gt "$KEEP_RELEASES" ]]; then
+    rm -rf "$old_release"
+  fi
+done < <(
+  if [[ "\${#release_dirs[@]}" -gt 0 ]]; then
+    ls -1dt "\${release_dirs[@]}"
+  fi
+)
+
+emit_result true "cleanup" "ok" false null
+`
+}

package/lib/backend-artifact-deploy/remote-transport.js

@@ -0,0 +1,118 @@
+import { spawn } from 'node:child_process'
+import { basename, relative } from 'node:path'
+import { buildRemoteDeployScript } from './remote-script.js'
+import { createRemotePhaseModel } from './remote-phases.js'
+import { parseRemoteResult } from './remote-result.js'
+
+function runProcess(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      ...options,
+    })
+
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', chunk => {
+      stdout += String(chunk)
+    })
+    child.stderr.on('data', chunk => {
+      stderr += String(chunk)
+    })
+    child.on('error', reject)
+    child.on('close', exitCode => resolve({ stdout, stderr, exitCode }))
+  })
+}
+
+function escapeShellArg(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+function normalizeRemoteBaseDir(baseDir) {
+  return String(baseDir).replace(/\/+$/, '') || '/'
+}
+
+export function buildEnsureRemoteBaseDirsCommand(baseDir) {
+  const normalizedBaseDir = normalizeRemoteBaseDir(baseDir)
+  const directories = ['releases', 'shared', 'uploads'].map(name => `${normalizedBaseDir}/${name}`)
+  return `mkdir -p ${directories.map(escapeShellArg).join(' ')}`
+}
+
+async function defaultEnsureRemoteBaseDirs(remote) {
+  const target = `${remote.user}@${remote.host}`
+  const args = [
+    '-p',
+    String(remote.port || 22),
+    target,
+    buildEnsureRemoteBaseDirsCommand(remote.baseDir),
+  ]
+  const result = await runProcess('ssh', args)
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr || `ssh mkdir failed (${result.exitCode})`)
+  }
+}
+
+async function defaultUploadBundle(remote, bundlePath) {
+  const target = `${remote.user}@${remote.host}:${remote.baseDir}/uploads/${basename(bundlePath)}`
+  const result = await runProcess('scp', ['-P', String(remote.port || 22), bundlePath, target])
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr || `scp failed (${result.exitCode})`)
+  }
+}
+
+async function defaultRunRemoteScript(remote, script) {
+  const target = `${remote.user}@${remote.host}`
+  return new Promise((resolve, reject) => {
+    const child = spawn('ssh', ['-p', String(remote.port || 22), target, 'bash -s'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', chunk => {
+      stdout += String(chunk)
+    })
+    child.stderr.on('data', chunk => {
+      stderr += String(chunk)
+    })
+    child.on('error', reject)
+    child.on('close', exitCode => resolve({ stdout, stderr, exitCode }))
+    child.stdin.write(script)
+    child.stdin.end()
+  })
+}
+
+function createRemotePayload(config, bundle) {
+  const toReleaseRelativePath = targetPath => {
+    if (!targetPath) return null
+    if (!config.projectRoot) return targetPath
+    return relative(config.projectRoot, targetPath).replace(/\\/g, '/')
+  }
+
+  return {
+    environment: config.environment,
+    versionName: bundle.versionName,
+    uploadedBundlePath: `${config.remote.baseDir}/uploads/${basename(bundle.bundlePath)}`,
+    remote: config.remote,
+    runtime: {
+      prismaSchemaDir: toReleaseRelativePath(config.runtime.prismaSchemaDir),
+      prismaConfig: toReleaseRelativePath(config.runtime.prismaConfig),
+      ecosystemConfig: config.runtime.ecosystemConfig ? basename(config.runtime.ecosystemConfig) : null,
+    },
+    startup: config.startup,
+    deploy: config.deploy,
+  }
+}
+
+export async function deployBackendArtifactRemotely(config, bundle, deps = {}) {
+  const ensureRemoteBaseDirs = deps.ensureRemoteBaseDirs || defaultEnsureRemoteBaseDirs
+  const uploadBundle = deps.uploadBundle || defaultUploadBundle
+  const runRemoteScript = deps.runRemoteScript || defaultRunRemoteScript
+
+  await ensureRemoteBaseDirs(config.remote)
+  await uploadBundle(config.remote, bundle.bundlePath)
+  const payload = createRemotePayload(config, bundle)
+  const phaseModel = createRemotePhaseModel(payload)
+  const script = buildRemoteDeployScript(phaseModel)
+  const commandResult = await runRemoteScript(config.remote, script)
+  return parseRemoteResult(commandResult)
+}

package/lib/backend-artifact-deploy/rollback.js

@@ -0,0 +1,5 @@
+export function shouldAttemptRollback({ migrationExecuted, startupMode }) {
+  if (migrationExecuted) return false
+  if (startupMode === 'direct') return false
+  return true
+}

package/lib/backend-artifact-deploy/runtime-package.js

@@ -0,0 +1,41 @@
+const UNSUPPORTED_LOCAL_DEP_PATTERN = /^(workspace:|file:|link:)/
+const REQUIRED_DEPENDENCIES_FROM_DEV = ['prisma']
+
+function assertSupportedDependencies(dependencies = {}) {
+  for (const [name, version] of Object.entries(dependencies)) {
+    if (typeof version !== 'string') continue
+    if (UNSUPPORTED_LOCAL_DEP_PATTERN.test(version)) {
+      throw new Error(`检测到不支持的本地依赖引用: ${name} -> ${version}`)
+    }
+  }
+}
+
+export function createRuntimePackage({ appPackage, rootPackage }) {
+  const runtimeDependencies = { ...(appPackage?.dependencies || {}) }
+  const appDevDependencies = appPackage?.devDependencies || {}
+
+  for (const dependencyName of REQUIRED_DEPENDENCIES_FROM_DEV) {
+    if (!runtimeDependencies[dependencyName] && appDevDependencies[dependencyName]) {
+      runtimeDependencies[dependencyName] = appDevDependencies[dependencyName]
+    }
+  }
+
+  assertSupportedDependencies(runtimeDependencies)
+
+  const runtimePackage = {
+    name: appPackage?.name,
+    version: appPackage?.version,
+    dependencies: runtimeDependencies,
+  }
+
+  if (appPackage?.private !== undefined) runtimePackage.private = appPackage.private
+  if (appPackage?.type) runtimePackage.type = appPackage.type
+  if (rootPackage?.packageManager) runtimePackage.packageManager = rootPackage.packageManager
+
+  const nodeEngine = rootPackage?.engines?.node || appPackage?.engines?.node
+  if (nodeEngine) {
+    runtimePackage.engines = { node: nodeEngine }
+  }
+
+  return runtimePackage
+}

package/lib/backend-artifact-deploy.js

@@ -0,0 +1,32 @@
+import { buildBackendArtifact } from './backend-artifact-deploy/artifact-builder.js'
+import { resolveBackendDeployConfig } from './backend-artifact-deploy/config.js'
+import { deployBackendArtifactRemotely } from './backend-artifact-deploy/remote-transport.js'
+
+export async function runBackendArtifactDeploy({
+  cli,
+  target,
+  args,
+  environment,
+  deps = {},
+}) {
+  const resolveConfig = deps.resolveConfig || resolveBackendDeployConfig
+  const buildArtifact = deps.buildArtifact || buildBackendArtifact
+  const deployRemotely =
+    deps.deployRemotely || deployBackendArtifactRemotely
+
+  const targetConfig = cli?.commands?.deploy?.[target]
+  const config = resolveConfig({
+    cli,
+    targetConfig,
+    environment,
+    flags: cli?.flags || {},
+    args,
+  })
+
+  const bundle = await buildArtifact(config, deps)
+  if (cli?.flags?.buildOnly) {
+    return bundle
+  }
+
+  return deployRemotely(config, bundle, deps)
+}

package/lib/cli/commands/deploy.js

@@ -95,7 +95,20 @@ export async function handleDeploy(cli, args) {
     return
   }
 
-  const environment = selectedEnvs[0] || 'staging'
+  const targetConfig = cli.commands.deploy?.[normalizedTarget]
+  const isBackendArtifactDeploy = targetConfig?.internal === 'backend-artifact-deploy'
+  const environment = selectedEnvs[0] || (isBackendArtifactDeploy ? 'development' : 'staging')
+
+  if (isBackendArtifactDeploy) {
+    const { runBackendArtifactDeploy } = await import('../../backend-artifact-deploy.js')
+    await runBackendArtifactDeploy({
+      cli,
+      target: normalizedTarget,
+      args,
+      environment,
+    })
+    return
+  }
 
   cli.ensureRepoRoot()
 

package/lib/cli/flags.js

@@ -38,6 +38,8 @@ export const FLAG_DEFINITIONS = {
     { flag: '--fix' },
   ],
   deploy: [
+    { flag: '--build-only' },
+    { flag: '--skip-migration' },
     { flag: '--webhook-path', expectsValue: true },
     { flag: '--webhook-dry-run' },
     { flag: '--strict-webhook' },
@@ -99,6 +101,12 @@ export function parseFlags(args = []) {
       case '--all':
         flags.all = true
         break
+      case '--build-only':
+        flags.buildOnly = true
+        break
+      case '--skip-migration':
+        flags.skipMigration = true
+        break
       default:
         break
     }

package/lib/cli/help.js

@@ -20,9 +20,9 @@ export function showHelp() {
     '    target: backend, shared, front, admin, mobile, all, sdk, affected (默认: all)',
     '    环境标志: --dev, --staging, --prod, --test, --e2e（未指定时默认 --dev）',
     '',
-    '  deploy <target> [环境标志]  部署前端到 Vercel',
-    '    target: front, admin, merchant, telegram-bot, all',
-    '    环境标志: --dev, --staging, --prod（默认 --staging）',
+    '  deploy <target> [环境标志]  部署前端到 Vercel 或后端制品到远端主机',
+    '    target: front, admin, merchant, telegram-bot, all, backend',
+    '    环境标志: --dev, --staging, --prod（默认: Vercel 目标为 --staging；backend 制品发布目标默认 --dev）',
     '',
     '  install                  安装依赖（使用 frozen-lockfile 确保版本一致）',
     '',
@@ -95,6 +95,8 @@ export function showHelp() {
     '  dx test e2e backend apps/backend/e2e/activity/activity.admin.e2e-spec.ts  # 运行单个E2E测试文件',
     '  dx test e2e backend apps/backend/e2e/activity/activity.admin.e2e-spec.ts -t "should list all activity definitions"  # 运行特定测试用例',
     '  dx deploy front --staging # 部署前端到 Vercel（staging）',
+    '  dx deploy backend --prod  # 构建 backend 制品并上传/部署到远端主机',
+    '  dx deploy backend --build-only # 仅构建 backend 制品，不执行远端部署',
     '  dx worktree make 88       # 为issue #88创建worktree',
     '  dx worktree del 88        # 删除issue #88的worktree',
     '  dx worktree del 88 89 90 -Y  # 批量删除多个worktree（非交互式）',
@@ -194,8 +196,14 @@ script 子命令:
   dx deploy <target> [环境标志] [选项]
 
   参数说明:
-  target: front, admin, merchant, telegram-bot, all
-  环境标志: --dev、--staging、--prod（默认 --staging）
+  target: front, admin, merchant, telegram-bot, all, backend
+  环境标志:
+    - Vercel 目标默认 --staging
+    - backend 制品发布目标默认 --dev
+
+  backend 制品发布（target=backend）:
+    --build-only               仅本地构建并打包制品，不上传不远端部署
+    --skip-migration           远端部署时跳过 prisma migrate deploy
 
   Telegram Webhook（仅 target=telegram-bot 生效）:
     --webhook-path <path>       对外 webhook 路径（默认 /api/webhook）
@@ -212,6 +220,8 @@ script 子命令:
   dx deploy telegram-bot --prod --webhook-dry-run             # 仅打印，不实际调用 Telegram
   dx deploy telegram-bot --dev --no-strict-webhook            # 开发环境显式降级为仅告警
   dx deploy all --staging             # 串行部署 front + admin + merchant
+  dx deploy backend --prod            # 构建 backend 制品并部署到远端主机
+  dx deploy backend --build-only      # 仅构建 backend 制品
 `)
       return
 

package/lib/vercel-deploy.js

@@ -236,10 +236,38 @@ export async function deployPrebuiltWithFallback(options) {
     baseArgs,
     env,
     cwd,
-    run = runVercel
+    run = runVercel,
+    cleanupArchiveParts = () => {},
+    onMissingFiles = () => {},
   } = options || {}
-  const result = await run(baseArgs, { env, cwd })
-  return { usedArchive: false, result }
+
+  try {
+    const result = await run(baseArgs, { env, cwd })
+    return { usedArchive: false, result }
+  } catch (error) {
+    if (!isMissingFilesError(error)) {
+      throw error
+    }
+
+    onMissingFiles(error)
+    cleanupArchiveParts()
+
+    const archiveArgs = []
+    let inserted = false
+    for (const arg of baseArgs || []) {
+      archiveArgs.push(arg)
+      if (!inserted && arg === '--prebuilt') {
+        archiveArgs.push('--archive=tgz')
+        inserted = true
+      }
+    }
+    if (!inserted) {
+      archiveArgs.push('--archive=tgz')
+    }
+
+    const result = await run(archiveArgs, { env, cwd })
+    return { usedArchive: true, result }
+  }
 }
 
 export async function deployToVercel(target, options = {}) {
@@ -251,6 +279,8 @@ export async function deployToVercel(target, options = {}) {
     run = runVercel
   } = options
 
+  process.exitCode = undefined
+
   // 校验环境参数
   if (!ALLOWED_ENVIRONMENTS.includes(environment)) {
     logger.error(`不支持的部署环境: ${environment}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranger1/dx",
-  "version": "0.1.80",
+  "version": "0.1.81",
   "type": "module",
   "license": "MIT",
   "repository": {