hai-deploy

name	hai-deploy
description	使用 @h-ai/deploy 进行自动化部署：Vercel 部署 + 基础设施开通（Neon/Upstash/R2/Resend/Aliyun）；当需求涉及应用部署、环境配置、凭证管理或云服务开通时使用。

hai-deploy

能力契约

项目	契约
能力	使用 @h-ai/deploy 进行自动化部署：Vercel 部署 + 基础设施开通（Neon/Upstash/R2/Resend/Aliyun）；当需求涉及应用部署、环境配置、凭证管理或云服务开通时使用。
适用场景	当任务与 hai-deploy 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时
输入	用户目标、仓库与运行环境上下文、现有配置、授权范围和质量门禁
输出	与目标匹配的配置/代码/文档或审查结论，以及可复现的验证结果
限制	不扩张用户授权，不输出或固化密钥，不跳过失败门禁，不假定外部服务状态

@h-ai/deploy 提供自动化部署能力，将 SvelteKit 应用部署到 Vercel，并自动开通 PostgreSQL (Neon)、Redis (Upstash)、S3 (Cloudflare R2)、邮件 (Resend)、短信 (阿里云) 等基础设施服务。

---

运行环境

⚠️ Node.js CLI / 服务端模块。 通过 hai deploy CLI 命令或在 Node.js 脚本中使用。

---

适用场景

• 一键部署 SvelteKit 应用到 Vercel
• 自动开通 PostgreSQL、Redis、S3 等云服务
• 管理部署凭证（~/.hai/credentials.yml）
• 扫描应用依赖，自动检测所需服务
• CLI 部署流程（hai deploy）

---

使用步骤

1. 配置

# config/_deploy.yml
provider:
  type: vercel
  token: ${HAI_DEPLOY_VERCEL_TOKEN}

services:
  db:
    provisioner: neon
    apiKey: ${HAI_DEPLOY_NEON_API_KEY}
  cache:
    provisioner: upstash
    email: ${HAI_DEPLOY_UPSTASH_EMAIL}
    apiKey: ${HAI_DEPLOY_UPSTASH_API_KEY}
  storage:
    provisioner: cloudflare-r2
    accountId: ${HAI_DEPLOY_CF_ACCOUNT_ID}
    apiToken: ${HAI_DEPLOY_CF_API_TOKEN}
  email:
    provisioner: resend
    apiKey: ${HAI_DEPLOY_RESEND_API_KEY}
  sms:
    provisioner: aliyun
    accessKeyId: ${HAI_DEPLOY_ALIYUN_ACCESS_KEY_ID}
    accessKeySecret: ${HAI_DEPLOY_ALIYUN_ACCESS_KEY_SECRET}

2. 初始化与关闭

import { deploy } from '@h-ai/deploy'

deploy.credentials.load()

await deploy.init({
  provider: { type: 'vercel', token: 'vel_xxx' },
  services: {
    db: { provisioner: 'neon', apiKey: 'neon_xxx' },
  },
})

// 使用后关闭
await deploy.close()

3. 扫描应用

const scanResult = await deploy.scan('./apps/my-app')
if (scanResult.success) {
  const { appName, isSvelteKit, requiredServices } = scanResult.data
}

4. 开通基础设施

const provResults = await deploy.provisionAll('my-project')
if (provResults.success) {
  for (const prov of provResults.data) {
    // prov.envVars 包含需要注入的环境变量
  }
}

5. 完整部署

const result = await deploy.deployApp('./apps/my-app', {
  projectName: 'my-project',
  skipProvision: false,
  skipBuild: false,
})
if (result.success) {
  // result.data.url — 部署地址
  // result.data.deploymentId — 部署 ID
  // result.data.envVarsSet — 已设置的环境变量列表
}

---

核心 API

方法	签名	说明
deploy.credentials.load	() => HaiResult<string[]>	加载凭证到 process.env
deploy.credentials.save	(key: string, value: string) => HaiResult<void>	保存单个凭证
deploy.credentials.saveAll	(entries: Record<string, string>) => HaiResult<void>	批量保存凭证
deploy.credentials.getPath	() => string	获取凭证文件路径
deploy.init	(config: DeployConfigInput) => Promise<HaiResult<void>>	初始化模块
deploy.close	() => Promise<void>	关闭模块
deploy.scan	(appDir: string) => Promise<HaiResult<ScanResult>>	扫描应用（不依赖 init）
deploy.provisionAll	(projectName: string) => Promise<HaiResult<ProvisionResult[]>>	开通所有服务
deploy.deployApp	(appDir: string, options?) => Promise<HaiResult<DeployResult>>	完整部署
deploy.config	DeployConfig | null	当前配置
deploy.isInitialized	boolean	初始化状态

---

凭证管理

所有凭证操作都通过 deploy.credentials.* 访问，模块入口不再单独导出自由函数。

deploy.credentials.*() 与 deploy.scan() 都不依赖 deploy.init()，可用于 CLI 在读取 _deploy.yml 之前准备环境。

---

错误码 — HaiDeployError

错误码	code	说明
HaiDeployError.DEPLOY_FAILED	hai:deploy:001	部署失败（通用）
HaiDeployError.PROJECT_CREATE_FAILED	hai:deploy:002	平台项目创建失败
HaiDeployError.BUILD_FAILED	hai:deploy:003	应用构建失败
HaiDeployError.UPLOAD_FAILED	hai:deploy:004	构建产物上传失败
HaiDeployError.AUTH_REQUIRED	hai:deploy:005	未认证
HaiDeployError.AUTH_FAILED	hai:deploy:006	认证失败
HaiDeployError.PROVISION_FAILED	hai:deploy:007	基础设施开通失败
HaiDeployError.ADAPTER_MISSING	hai:deploy:008	SvelteKit adapter 未安装
HaiDeployError.SCAN_FAILED	hai:deploy:009	应用扫描失败
HaiDeployError.NOT_INITIALIZED	hai:deploy:010	模块未初始化
HaiDeployError.ENV_VAR_FAILED	hai:deploy:011	环境变量设置失败
HaiDeployError.UNSUPPORTED_TYPE	hai:deploy:012	不支持的类型
HaiDeployError.CONFIG_ERROR	hai:deploy:013	配置错误
HaiDeployError.CREDENTIAL_ERROR	hai:deploy:014	凭证读写失败

---

CLI 命令

# 部署当前目录
hai deploy

# 部署指定应用
hai deploy ./apps/admin-console

# 跳过基础设施开通
hai deploy --skip-provision

# 跳过构建
hai deploy --skip-build

# 自定义项目名
hai deploy --project-name my-custom-name

---

常见模式

仅部署（跳过基础设施）

await deploy.deployApp('./apps/my-app', { skipProvision: true })

仅开通基础设施

await deploy.init(config)
const result = await deploy.provisionAll('my-project')
// 手动使用 result.data 中的环境变量
await deploy.close()

自定义部署流程

import { deploy } from '@h-ai/deploy'

// Provider 通过 init 配置自动创建，不需要手动导入
await deploy.init({
  provider: { type: 'vercel', token: 'vel_xxx' },
})

// 使用 deploy API 部署
const result = await deploy.deployApp('./apps/my-app')

---

相关 Skills

• hai-core — 配置加载、日志、HaiResult 类型
• hai-reldb — 数据库（Neon PostgreSQL）
• hai-cache — 缓存（Upstash Redis）