使用 Rayfin CLI 创建Fabric应用

本教程介绍如何使用 Rayfin CLI 创建项目、在本地运行项目并将其部署到Fabric。 无论是新应用，还是后续对架构或前端的更新，你都使用相同的 CLI 工作流。

在本教程中，你将了解：

  • 从模板创建Fabric应用项目。
  • 在本地启动应用。
  • 从 CLI 登录到Fabric。
  • 将应用部署到Fabric工作区。
  • 验证部署状态。

先决条件

  • 访问Fabric。
  • 具有参与者、成员或管理员权限的Fabric工作区。
  • 已在你的租户中启用的 Fabric 应用工作负载。
  • 已安装 Node.js 和 npm。

创建一个带有AI提示的应用

请使用以下提示，使用 GitHub Copilot 或其他编码代理来创建、探索、运行、定制和部署 Fabric 应用：

Set up a new Fabric App project called "rayfin-app-ws".

1. Run: npm create @microsoft/rayfin@latest
2. Open the scaffolded project directory.
3. Explore the project structure and understand the Rayfin app framework.
4. Run: npm run dev
5. Make changes to the app based on my instructions.
6. When ready, deploy with: npx rayfin up

代理会交互式运行命令，并请求任何必要的项目或工作区设置。 部署前查看生成文件和命令输出。 如果尚未启用 Fabric Apps 工作负载，请让 Fabric 管理员在 >>>工作负载 中启用 Fabric Apps（预览）。

从CLI创建一个新应用

若要从模板搭建新应用，请使用 npm create：

npm create @microsoft/rayfin@latest -- my-app --workspace <workspacename>

此命令使用应用模板、 rayfin 配置和前端源代码创建新的项目文件夹。

转到项目目录：

cd my-app

小窍门

如果已有空项目文件夹或现有源代码，请使用 npx rayfin init 而不是 npm create。

npx rayfin init .

审核生成的项目

完成脚手架搭建后，项目会包含你开始开发所需的文件：

  • rayfin/rayfin.yml 存储应用服务和部署设置。
  • rayfin/.env 存储 CLI 使用的环境值。
  • rayfin/data/ 包含您的数据模型文件。
  • 前端应用位于所选模板创建的根项目结构中。

有关详细的逐文件细分，请参阅 “了解项目结构”。

在本地运行应用

启动本地开发环境：

npx rayfin dev

此命令启动基架应用的前端开发服务器，并将后端部署到Fabric。 若要确认应用正确启动，请打开终端中显示的本地 URL。

将应用部署到 Fabric

在应用程序中生成更多功能。 测试更改后，请再次部署到Fabric。

npx rayfin up

若要预览部署而不进行更改，请运行：

npx rayfin up --dry-run

验证部署

检查当前的部署状态：

npx rayfin up status

对于计算机可读响应，请使用 JSON 输出：

npx rayfin up status --json

成功部署后，CLI 将打印已部署项的托管应用 URL 和Fabric门户链接。

仅部署数据库或静态内容

如果仅更改了数据模型，则无需完全重新部署即可应用数据库更改：

npx rayfin up db apply

如果仅更改了前端代码，请重新部署静态资产：

npx rayfin up staticapp deploy

添加函数

函数是运行在 Fabric 应用内服务器上的 TypeScript 函数。 使用不该在浏览器中运行的逻辑函数，如处理秘密、访问特权数据以及代表登录用户调用下游服务。

npx rayfin functions init

GitHub Copilot 可以生成和更新所需的文件和组件。 你也可以让代理运行应用，本地调试功能，然后部署应用。 例如，您可以使用以下提示词，通过函数构建 AI 拉取请求审核助手：

Build an app that lets me view all pull requests for the repository
<repoURL>, chat with my Azure AI Foundry agent <agentName> to review
pull requests, and post review comments. Use functions with delegated
authentication to connect to Azure AI Foundry and Azure DevOps.

排查常见问题

登录失败或部署返回 401 或 403

再次运行 npx rayfin login ，然后重试 npx rayfin up。

你需要检查 CLI 将执行什么操作

在部署更改之前，请运行 npx rayfin up --dry-run。

应用已部署，但你只是更改了架构

若要独立推送架构更改，请使用 npx rayfin up db apply。 如果执行破坏性更改，例如更改列的类型或删除列，此命令将失败。 若要强制更改，可以使用 --force 标志。 此操作可能是一项重大更改。

后续步骤

  • 上次更新时间为