使用 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: npx -y @microsoft/create-rayfin@latest --project-name rayfin-app-ws --template blankapp
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

脚手架命令提供项目名称和模板，用于非交互式执行。 代理可以询问提供任何剩余的工作区或部署设置。 部署前查看生成文件和命令输出。

从CLI创建一个新应用

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

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

默认 blankapp 模板解析为 通用应用。 它创建一个新的 npm 工作区，后端配置位于 rayfin/，前端代码位于 packages/frontend/，运行时数据定义位于 packages/data/，共享契约位于 packages/shared/。 数据在你选择加入之前是被禁用的。

转到项目目录：

cd my-app

小窍门

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

npx rayfin init .

审核生成的项目

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

  • rayfin/rayfin.yml 存储应用服务和部署设置。
  • rayfin/.env 存储 CLI 使用的环境值。
  • packages/frontend/ 包含界面和前端构建。
  • packages/data/ 包含运行时实体类和模式注册。
  • packages/shared/ 包含面向客户的记录和架构契约。

必要时启用持久化应用数据：

npm run pack:add -- data-modeling

该功能可启用 Data，并添加起始数据和共享定义。 添加文件前请先在 rayfin/rayfin.yml 中检查 services.data.path 和 services.staticHosting.path。 其他模板可以使用平面根 src/ 和 rayfin/data/ 布局;那些布局是替代方案，不是通用应用默认布局。

CLI将活跃部署值保存在 rayfin/.env 中，并在 rayfin/.deployments.json 中记录部署。 公共 RAYFIN_PUBLIC_* 值映射到前端生成的 .env.local 中；使用 npx rayfin env --framework vite 重新生成它，而无需部署。

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

在本地运行应用

启动本地开发环境：

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

初始化器在配置后使用 services.functions.path，检测工作区位置（如 packages/functions），或保留现有的平面 rayfin/functions 包。 用 --path <relative-path> 来显式选择位置。

已启用的功能需要 services.functions.auth.type: application。 通过 ctx.Tokens.* 进行的外部调用使用应用身份及其权限，而非调用用户的外部资源权限。 在当前的 Fabric 应用中，这个身份就是应用项目的所有者。 授权它访问每个资源。 相比之下，ctx.getDataClient() 使用调用的 Rayfin 令牌，并保留调用者的数据策略。

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 application
authentication to connect to Azure AI Foundry and Azure DevOps. Grant the
app identity the required resource permissions, and preserve the caller's
Rayfin data policies when using ctx.getDataClient().

有关身份和部署的详细信息，请参见 使用函数 和 将函数连接到外部资源。

排查常见问题

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

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

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

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

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

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

后续步骤

  • 上次更新时间为