SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场applications

applications

部署与运维

查看项目

更新于 10-16 13:13

技能介绍

本技能用于在 TrueFoundry 平台上列出、检查和管理的应用程序及其部署。

用途

  • 列出、检查或管理已部署的应用程序及其部署历史。
  • 支持通过 API 清单为预构建镜像创建部署。

何时不使用

  • 用户想部署本地代码：优先使用 deploy 技能。
  • 用户想获取工作区/集群信息：优先使用 workspaces 技能。
  • 用户想删除应用：引导其前往 TrueFoundry UI（见下文）。

执行优先级

简单读取/列表操作优先使用 MCP 工具调用：tfy_applications_list、tfy_applications_list_deployments。若 MCP 服务器未配置或缺少工具，自动回退到通过 tfy-api.sh 直接调用 API。

重要：删除应用

删除操作不支持通过 CLI、API 或任何智能体工具完成。不要调用任何删除端点或尝试以编程方式删除应用。当用户请求删除应用时，不要先列出应用供其选择，而是直接回复控制台操作步骤：打开 TrueFoundry 控制台（TFY_BASE_URL），进入 Deployments 选择工作区，找到目标应用，点击三点菜单（⋮）→ Delete，确认删除。此操作不可逆，应用的 Pod、端点和部署历史将被永久移除。不要代替用户调用任何删除 API。

列出应用

使用直接 API 时，将 TFY_API_SH 设置为该技能 scripts/tfy-api.sh 的完整路径（各智能体的路径见 references/tfy-api-setup.md）。

工具调用方式：

  • tfy_applications_list()
  • tfy_applications_list(filters={"workspace_fqn": "my-cluster:my-workspace"})
  • tfy_applications_list(filters={"application_name": "my-app"})
  • tfy_applications_list(app_id="app-id-here")

直接 API 方式：

  • $TFY_API_SH GET /api/svc/v1/apps
  • $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=my-cluster:my-workspace'
  • $TFY_API_SH GET '/api/svc/v1/apps?applicationName=my-app'
  • $TFY_API_SH GET /api/svc/v1/apps/APP_ID

筛选参数：

  • workspace_fqn / workspaceFqn：按工作区 FQN 筛选
  • application_name / applicationName：按应用名筛选
  • cluster_id / clusterId：按集群筛选
  • application_type / applicationType：按类型筛选（service、job 等）
  • name_search_query / nameSearchQuery：按名称子串搜索

展示应用

以表格展示，使用 API 响应中的 updatedAt 作为“Last Deployed”（ISO 8601 时间戳，格式化为可读日期/时间），使用 kind 作为 Type，status 作为 Status。示例（工作区 my-cluster:my-workspace）：tfy-tool-server / service / RUNNING / 2026-02-10 14:30；data-pipeline / job / STOPPED / 2026-02-08 09:15。

列出部署

工具调用方式：

  • tfy_applications_list_deployments(app_id="app-id")
  • tfy_applications_list_deployments(app_id="app-id", deployment_id="dep-id")

直接 API 方式：

  • $TFY_API_SH GET /api/svc/v1/apps/APP_ID/deployments
  • $TFY_API_SH GET /api/svc/v1/apps/APP_ID/deployments/DEPLOYMENT_ID

通过 API 创建部署（高级，大多数用户应使用 deploy 技能）

适用场景：用户自带清单/JSON 并希望直接 API 部署；用户明确要求 API 部署而非 SDK/Python；用户想从预构建镜像部署（而非本地代码）。部署本地代码请使用 deploy 技能。

服务清单结构示例：kind 为 "Service" 或 "Job"，name 为唯一应用名，image.image_uri 为 Docker 镜像（如 nginx:latest、ghcr.io/org/app:v1.0），ports 为端口配置数组（port、protocol、expose），resources 为 CPU（核心数）与内存（MB）的请求/限制，env 为环境变量键值对（敏感值必须使用 tfy-secret:// 引用，禁止内联明文凭据），replicas 为最小/最大副本数，workspaceId 为部署目标工作区 ID（非 FQN）。

提交前安全要求：绝不在 manifest 的 env 中嵌入原始 API 密钥、密码或令牌；敏感环境变量一律使用 tfy-secret:// 引用；若用户提供原始凭据，提醒并建议先创建 TrueFoundry 密钥组（使用 secrets 技能）；不要要求用户直接在对话中粘贴密钥值。

创建部署前必须与用户确认：服务名称、镜像完整 URI、资源（CPU 请求/限制、内存请求/限制）、端口（暴露哪些端口、协议、是否暴露到互联网）、环境变量（敏感值仅接受 tfy-secret:// 引用）、副本数（最小/最大以支持自动扩缩）、工作区 ID。确认后再发起 API 调用。

工具调用方式：tfy_applications_create_deployment(manifest={...}, options={"workspace_id": "ws-id-here", "force_deploy": true})。使用工具调用时需要人工审批（HITL）。

直接 API 方式：$TFY_API_SH PUT /api/svc/v1/apps '{...}'。

常见部署模式

  • Web 服务（暴露到互联网并生成公共 URL）：host 必须匹配集群的 base_domains 之一。先查询：$TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID，找到 base_domains 中的通配符项（如 ".ml.your-org.truefoundry.cloud"），去掉 "." 得到基础域名，构造 host："{service-name}-{workspace-name}.{base_domain}"。若 host 不匹配集群基础域名，部署将失败并提示 "Provided host is not configured in cluster"。示例端口配置包含 port 8080、protocol TCP、expose true、host、app_protocol http。
  • 内部服务（不暴露）：端口 expose 为 false，副本数最小/最大均为 1。
  • 资源密集型服务：CPU 请求 1.0 限制 2.0，内存请求 2048MB 限制 4096MB。

成功标准

  • 用户可看到以清晰表格展示的已部署应用状态。
  • 不健康或已停止的部署能被识别，并给出可操作的后续步骤（检查日志、重新部署）。
  • 用户指定工作区时，结果已按正确的工作区筛选。
  • 用户可通过名称、ID 或工作区找到特定应用。
  • 用户请求更多信息时，能展示部署详情（副本、资源、镜像、端口）。

组合使用

  • 列出应用后：使用 logs 技能检查日志，使用 deploy 技能重新部署。
  • 部署后：使用本技能验证部署是否成功。
  • 检查作业：使用 jobs 技能查看作业运行详情。
  • 先找工作区：使用 workspaces 技能获取工作区 FQN 用于筛选。

错误处理

  • 未找到应用：检查工作区 FQN 是否正确、该工作区是否有已部署应用、API 密钥是否有权访问该工作区。
  • 应用未找到：应用 ID 不存在，先列出应用以找到正确 ID。
  • 权限被拒绝：无法访问该应用，检查 API 密钥权限。