Fabric 应用的静态内容托管

Fabric应用包括静态内容托管服务，该服务可生成、打包和与后端 API 一起为前端应用程序提供服务。 启用静态托管后，CLI 会将生成的资产部署到Fabric并提供一个公共 URL，用户可以在其中访问应用程序。

先决条件

  • 具有前端应用程序的Fabric应用项目（例如 React、Vue 或 vanilla TypeScript）。
  • 生成静态输出的生成命令（例如， npm run build） 。

静态托管的工作原理

在启用静态托管的情况下进行部署时，CLI 将执行以下步骤：

  1. 运行您已配置的构建命令（例如，npm run build）。
  2. 验证输出文件夹是否存在并包含文件。
  3. 将所有文件打包到压缩的 ZIP 存档中（最大为 100 MB）。
  4. 将存档上传到Fabric应用主机。
  5. 返回可访问应用程序的公共托管 URL。

配置静态托管

在您的 rayfin/rayfin.yml 文件中，在 services 下添加一个 staticHosting 部分：

services:
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

配置选项

Option 必需 默认 说明
enabled 是的 — 将其设置为true以启用静态托管。
folder 是的 — 包含生成的静态文件的输出文件夹，相对于 root.
root 不 项目根目录 前端项目的根目录，相对于项目根目录。
buildCommand 不 — 打包之前要运行的 Shell 命令（例如， npm run build）。
indexDocument 不 — 用于目录请求的默认文档（例如 index.html， ）。

使用单独的前端目录的示例

如果前端代码位于子目录中：

services:
  staticHosting:
    enabled: true
    root: frontend
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

此配置将输出路径解析为 <project-root>/frontend/dist.

部署静态内容

完整部署

运行 npx rayfin up时，静态内容会自动作为完整堆栈部署的一部分进行部署：

npx rayfin up

CLI 将生成前端、打包输出，并将其与后端配置一起上传。 部署后，CLI 会输出托管 URL，并将其作为 VITE_RAYFIN_HOSTING_URL 写入你的 .env.fabric-* 文件。

独立静态部署

staticapp deploy使用子命令仅重新部署静态内容，而无需重新运行完整部署：

npx rayfin up staticapp deploy

仅当更改了前端代码并且需要更快的迭代周期时，此命令非常有用。

跳过生成步骤

如果已生成前端，并且想要在不重新生成的情况下部署现有输出：

npx rayfin up staticapp deploy --skip-build

启用详细日志记录

在部署期间显示详细的输出：

npx rayfin up staticapp deploy --verbose

身份验证回调配置

启用静态托管和身份验证后，Rayfin CLI 会根据托管 URL 自动注册身份验证回调 URI。

例如，如果托管 URL 为 https://example.webapp.com，CLI 将添加以下回调 URI：

services:
  auth:
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
      - https://example.webapp.com/auth/callback

无需手动配置身份验证回调 URI - CLI 会更新配置并在部署期间推送配置。

部署大小限制

  • 压缩的 ZIP 存档不得超过 100 MB。
  • CLI 使用最大压缩来最大程度地减少上传大小。
  • 如果生成输出超出限制，请通过以下方式优化资产：
    • 从生产版本中排除源映射。
    • 压缩或删除大型图像和视频。
    • 将二进制文件移动到Fabric应用存储，而不是捆绑这些文件。

完整示例

启用了静态托管、身份验证和数据服务的完整 rayfin.yml 配置：

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
    fabric:
      enabled: true
  data:
    enabled: true
    dialect: mssql
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

在本地测试

在部署之前，请在本地验证静态生成是否正常工作：

  1. 构建你的前端：

    npm run build

  2. 检查输出文件夹是否包含预期文件：

    ls dist

  3. 使用本地静态服务器提供生成的文件：

    npx serve dist

  4. 打开服务器打印的 URL，并验证应用程序是否正确加载。

排查部署问题

找不到静态文件夹

如果 CLI 报告静态文件夹不存在：

  • 验证 rayfin.yml 中的 folder 路径是否正确，以及它是否是相对于 root 的相对路径（如果未设置 root，则相对于项目根目录）。
  • 确保生成命令成功运行，并在预期目录中生成输出。

空静态文件夹

空输出文件夹通常意味着生成命令失败或未生成输出。 手动运行生成命令以检查错误：

npm run build

部署超出大小限制

如果 ZIP 超过 100 MB：

  • 检查构建输出中是否包含不必要的文件（源映射、开发资源）。
  • 配置捆绑程序以排除生产版本中的源映射。
  • 将大型二进制文件移动到Fabric应用存储。

未配置远程终结点

该 npx rayfin up staticapp deploy 命令需要现有的远程部署。 首先运行 npx rayfin up 以配置远程端点，然后在后续更新中使用 staticapp deploy。

相关内容

  • Last updated on