Fabric应用包括静态内容托管服务,该服务可生成、打包和与后端 API 一起为前端应用程序提供服务。 启用静态托管时,CLI会将你构建的资产部署到Fabric中,并提供托管URL。 你可以要求用户登录并获得查看 Fabric 应用的权限,或者允许匿名访问托管资产。
先决条件
- 具有前端应用程序的Fabric应用项目(例如 React、Vue 或 vanilla TypeScript)。
- 生成静态输出的生成命令(例如,
npm run build) 。
静态托管的工作原理
在启用静态托管的情况下进行部署时,CLI 将执行以下步骤:
- 运行您已配置的构建命令(例如,
npm run build)。 - 验证输出文件夹是否存在并包含文件。
- 将所有文件打包到压缩的 ZIP 存档中(最大为 100 MB)。
- 将存档上传到Fabric应用主机。
- 应用配置好的访问设置并返回托管URL。
配置静态托管
在您的 staticHosting 文件中,在 services 下添加一个 rayfin/rayfin.yml 部分:
services:
staticHosting:
enabled: true
folder: dist
buildCommand: npm run build
indexDocument: index.html
assetAccess: protected
配置选项
| Option | 必需 | 默认 | 说明 |
|---|---|---|---|
enabled |
是的 | — | 将其设置为true以启用静态托管。 |
folder |
是的 | — | 包含生成的静态文件的输出文件夹,相对于 root. |
root |
不 | 项目根目录 | 前端项目的根目录,相对于项目根目录。 |
buildCommand |
不 | — | 打包之前要运行的 Shell 命令(例如, npm run build)。 |
indexDocument |
不 | — | 用于目录请求的默认文档(例如 index.html, )。 |
assetAccess |
不 |
protected 对于非交互式部署 |
控制对托管资产的访问。 使用 protected 要求登录并获得查看 Fabric 应用的权限,或使用 public 允许匿名访问。 |
配置对托管资产的访问
将 assetAccess 设置为以下值之一:
-
protected- 要求用户登录并拥有查看 Fabric 应用的权限,才能获取托管资产。 -
public- 允许任何拥有托管 URL 的人在无需登录的情况下检索托管资产。
受保护托管控制对 Fabric Apps 所提供的静态文件的访问。 它不能取代你应用或API中的认证和授权。
如果尚未配置 assetAccess,首次进行交互式 npx rayfin up 部署时,系统会提示你选择一种访问设置。 非交互式部署使用 protected 并将该设置保存为 rayfin.yml。
部署后要更改访问设置,请更新 assetAccess,然后运行完整部署:
npx rayfin up
npx rayfin up staticapp deploy 命令只更新内容。 它不会赋予新的 assetAccess 数值。
使用单独的前端目录的示例
如果前端代码位于子目录中:
services:
staticHosting:
enabled: true
root: frontend
folder: dist
buildCommand: npm run build
indexDocument: index.html
assetAccess: protected
此配置将输出路径解析为 <project-root>/frontend/dist.
部署静态内容
完整部署
运行 npx rayfin up时,静态内容会自动作为完整堆栈部署的一部分进行部署:
npx rayfin up
CLI 将生成前端、打包输出,并将其与后端配置一起上传。 部署后,CLI 会输出托管 URL,并将其作为 .env.fabric-* 写入你的 VITE_RAYFIN_HOSTING_URL 文件。
独立静态部署
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
assetAccess: protected
在本地测试
在部署之前,请在本地验证静态生成是否正常工作:
构建你的前端:
npm run build检查输出文件夹是否包含预期文件:
ls dist使用本地静态服务器提供生成的文件:
npx serve dist打开服务器打印的 URL,并验证应用程序是否正确加载。
排查部署问题
找不到静态文件夹
如果 CLI 报告静态文件夹不存在:
- 验证
folder中的rayfin.yml路径是否正确,以及它是否是相对于root的相对路径(如果未设置root,则相对于项目根目录)。 - 确保生成命令成功运行,并在预期目录中生成输出。
空静态文件夹
空输出文件夹通常意味着生成命令失败或未生成输出。 手动运行生成命令以检查错误:
npm run build
部署超出大小限制
如果 ZIP 超过 100 MB:
- 检查构建输出中是否包含不必要的文件(源映射、开发资源)。
- 配置捆绑程序以排除生产版本中的源映射。
- 将大型二进制文件移动到Fabric应用存储。
未配置远程终结点
该 npx rayfin up staticapp deploy 命令需要现有的远程部署。 首先运行 npx rayfin up 以配置远程端点,然后在后续更新中使用 staticapp deploy。