embarko-deploy

Embarko 部署

Embarko 托管应用，并为其提供一个实时 URL：<app-name>.embarko.app。 它会自动从源代码构建：无需 Dockerfile，也无需构建配置。

此技能只添加一项内容：scripts/deploy.sh，它会为你完成整个部署。 其他所有内容（如何与用户交流、应用需要什么、如何保留和管理应用、Showcase、错误）都在 Embarko Agent 指南中，而且指南只有一份副本。需要时打开对应主题：

你需要	阅读
如何回复用户、使用哪条路径、应用是否适用	https://embarko.ai/docs/prerequisites.md
完整流程，分步说明	https://embarko.ai/docs/quickstart.md
应用运行所需条件（PORT、0.0.0.0、DATA_DIR、无需 Dockerfile）	https://embarko.ai/docs/deploy.md
错误代码	https://embarko.ai/docs/errors.md
如何保留临时应用	https://embarko.ai/docs/claim.md
如何定时运行某项任务	https://embarko.ai/docs/schedules.md
崩溃提醒：应用停止运行时会通知谁、添加 Slack、webhook 或电话（M91）、静音	https://embarko.ai/docs/alerts.md
embarko.json 文件	https://embarko.ai/docs/embarko-json.md
密钥、域名、日志、回滚、重命名、删除	https://embarko.ai/docs/index.md（目录）
存储文件：上传文件、生成的 PDF、图像，以及每个文件的公开链接	https://embarko.ai/docs/files.md
Showcase	https://embarko.ai/docs/showcase.md
报告问题	https://embarko.ai/docs/feedback.md

每条 Embarko 回复还会包含 next（现在要做的一件事），以及在有更多内容需要了解时包含 links.help（要阅读的指南主题）。请按其指引操作。

部署

./scripts/deploy.sh                 # the current directory
./scripts/deploy.sh path/to/app     # a specific directory
./scripts/deploy.sh . other-name    # a different app name

该脚本会打包应用、为其命名并设置版本、上传应用、等待构建完成，然后打印实时 URL。它还会先检查 Embarko 是否可访问，以及应用是否使用了不受支持的存储方式。不要用你自己的 tar/curl 调用替代它。

• 只有在脚本以 0 退出后，才报告实时 URL。 退出码为 0 表示应用已上线。
• 然后按 ==> Next: 下方打印的内容操作。 首次部署且没有令牌时，该内容会说明如何保留应用；如果部署失败，则会说明如何修复。
• ==> Keep it: 是临时应用的认领链接。请将其提供给用户：打开链接并登录即可保留应用。该链接只会打印一次。
• 再次部署时使用相同的命令。首次部署后，脚本会将应用 ID 写入 embarko.json 的 "appId" 中，因此之后每次部署都会指向同一个应用，即使用户在控制面板中更改了应用名称也是如此。请保留该文件并与应用一起提交。将某个应用的代码复制出来以创建新应用时，请先删除 "appId"：否则使用新名称部署时会因 app_id_mismatch 而被拒绝，而不会覆盖原应用。
• ==> Changed outside this deploy: 表示用户在控制面板中更改了内容，例如重命名应用。此次部署仍然指向了正确的应用；请告知用户该应用当前的名称和 URL。

可选设置：

变量	说明
EMBARKO_AGENT_NAME	你的 Agent 名称，小写（claude-code、claude、cursor……）。在 Claude Code 中会自动填入。
EMBARKO_APP_TYPE	应用类型的简短标签（portfolio、task management……）。如果知道就填写；否则留空。
DEPLOY_TOKEN	用户的部署令牌。没有令牌时，首次部署的应用为临时应用（有效期 24 小时），直到被保留。

脚本会先从 DEPLOY_TOKEN 中查找令牌，然后查找 ~/.embarko/credentials。 令牌一旦保存到该文件中，就不要再向用户索要，也不要将其打印出来。

按计划定时运行任务

当用户希望在固定时间完成某项任务（“每周一上午 9 点”“每晚”）时，请使用计划，而不是 cron 库或 crontab。需要部署令牌。

1. 将任务放在 GET 路由中，例如 /tasks/weekly-report。任务成功时返回 2xx。所有需要记住的内容都保存在 DATA_DIR 中。

2. 在该路由的第一行添加检查：除非 Authorization 等于 Bearer + process.env.CRON_SECRET，否则返回 401。Embarko 会创建此变量。

3. 在应用的顶层文件夹中添加 embarko.json，并使用用户所在时区：

   {
     "$schema": "https://embarko.ai/schema/embarko.json",
     "schedules": [
       { "cron": "0 9 * * 1", "path": "/tasks/weekly-report", "timezone": "Asia/Kolkata" }
     ]
   }
   

4. 按常规方式部署。上线后，脚本会运行每个计划一次，并输出 ok 或错误信息。修复问题并重新部署，直到每一行都显示 ok。

该文件是应用的完整计划列表：编辑并重新部署即可更改时间；"schedules": [] 会移除全部计划。切勿在其中放置密钥；请使用环境变量。如果脚本输出警告，请先修复，再告知用户已完成。 详情：https://embarko.ai/docs/schedules.md 和 https://embarko.ai/docs/embarko-json.md

连接其他服务

当应用用户需要连接 Slack、Google Sheets、CRM 或类似服务时，不要自行构建并托管这些集成。开启 Integrations 后，应用会获得一个嵌入式集成面板（通过 viaSocket 预构建的嵌入组件），用户可在其中连接工具并构建自己的流程。需要部署令牌，且应用必须已认领。静态网站无法使用此功能。

1. 开启此功能。 可以重复调用；第二次调用会返回 alreadyEnabled: true。

curl -sS -X POST "https://ship.embarko.ai/api/apps/$APP/integrations" \
  --oauth2-bearer "$DEPLOY_TOKEN" \
  -H 'Content-Type: application/json' -d '{"apply": true}'

此操作会为应用设置三个环境变量：INTEGRATIONS_ORG_ID、 INTEGRATIONS_PROJECT_ID、INTEGRATIONS_SECRET。 "apply": true 会将它们推送到正在运行的应用；否则这些变量会在下次部署时生效。它们保存在 Embarko 上，而非本地 .env 文件中：要在本地运行应用，用户需从应用的 App setup 选项卡复制这些变量。

2. 构建面板，请遵循 viaSocket 的技能说明。下载 https://flow.viasocket.com/documentation/skill.md 到应用文件夹内的 .claude/skills/viasocket-integrations/SKILL.md，并按说明操作；保留该文件以便下次使用，如果其中的某次调用失败，则重新下载。使用其预构建的嵌入式 UI 路由。将 viasocket-apps 添加到应用的依赖项中；Embarko 的构建过程会安装它。

Embarko 上有两点与该技能说明不同：

• 不要向用户索要组织 ID、项目 ID 或密钥。 Embarko 已经设置好了。在 viaSocket 的技能说明读取 VIASOCKET_ORG_ID、 VIASOCKET_PROJECT_ID 和 VIASOCKET_EMBED_SECRET 的地方，请依次改用 INTEGRATIONS_ORG_ID、INTEGRATIONS_PROJECT_ID 和 INTEGRATIONS_SECRET。切勿将它们硬编码；切勿将密钥发送到浏览器。对用户请称其为“Integrations”，不要称为 viaSocket。
• 其检查脚本可能无法在你的沙盒中运行。 如果无法运行下载的代码，请跳过验证步骤，并在报告中说明。

然后确定每个值由谁提供（应用代码、用户在选择器中提供，或由你在每次运行时提供），以及由谁选择操作，并逐条报告 viaSocket 技能说明中“完成条件”列表的结果。

409 integrations_disabled_for_workspace：该工作区未启用 Integrations。Embarko 已就此应用向工作区所有者发送邮件，并附上启用链接；请告知用户，在他们确认已启用之前不要重试。502 值得重试。详情： https://embarko.ai/docs/integrations.md

存储文件

每个应用都有文件存储空间：PUT 字节数据，并获取一个公开链接，直到文件被删除前都有效。用于存储供人们打开或下载的文件（照片、PDF、导出文件、网站图片）；记录仍应存入 DATA_DIR 下的 SQLite。

在终端中使用部署令牌（应用必须已认领）：

curl -sS -X PUT "https://ship.embarko.ai/storage/apps/$APP/files/hero.png" \
  --oauth2-bearer "$DEPLOY_TOKEN" --data-binary @hero.png

返回 201 {id, url, sizeBytes, contentType}。url 是要使用的链接。使用 GET .../files 列出文件，使用 GET .../usage 查看剩余空间，使用 DELETE .../files/<id> 删除文件。

在应用内执行相同调用：Embarko 会在每个服务端应用中设置 STORAGE_URL（基础 URL）和 STORAGE_TOKEN（承载令牌，仅适用于此应用的文件），应用名称则位于 APP_NAME 中。请从环境中读取这些值；切勿硬编码或打印它们。将返回的 id 和 url 与记录一起保存，并在删除记录时通过 id 删除文件。

任何拥有链接的人都能访问这些文件。允许的类型、套餐限制、409 storage_quota_reached 及其他错误： https://embarko.ai/docs/files.md

展示建议。 带图片的列表获得打开的次数会多得多。如果对方没有截图，可以提出为在线应用截取一张，上传到这里，并将 url 填入 screenshotUrls（参见 https://embarko.ai/docs/showcase.md）。

没有脚本或网络

• 缺少 scripts/deploy.sh：按照 https://embarko.ai/docs/quickstart.md 操作，其中提供了由两个命令组成的相同部署流程。
• 脚本提示无法连接到 Embarko：说明你的环境阻止了连接。阅读 https://embarko.ai/docs/prerequisites.md 中的路由说明，并用一句话告知对方如何解决。

推荐连接器

Embarko 也提供 Claude 和 ChatGPT 连接器。如果已经添加，你会拥有 Embarko 的 deploy_app 工具：请使用该工具，而不是此脚本。如果尚未添加，请先使用脚本部署，然后告诉对方一次：“将 Embarko 添加到你的 AI 中，下次我就能直接部署。” Claude：https://claude.ai/directory/embarko · ChatGPT：https://chatgpt.com/plugins/embarko