排查 Fabric 应用问题

诊断开发或部署Fabric应用项目时的常见问题。本文介绍登录、本地服务、架构更改、静态托管和 CLI 的问题。

部署问题

部署失败，出现 401 或 403 错误

症状： 运行 npx rayfin up 将返回身份验证错误。

原因： 身份验证会话已过期或未登录。

Solution:

重新进行身份验证并重试部署：

npx rayfin login
npx rayfin up

静态部署超出大小限制

症状： 静态内容部署失败，并出现大小限制错误。

原因： 压缩存档超过 100 MB。

Solution:

通过以下方式减少生成输出大小：

从生产版本中排除源映射
优化或删除大型图像和视频
将二进制文件移动到存储，而不是将它们捆绑在一起
验证你的打包工具配置是否排除了开发产物

静态部署没有远程端点

症状： 运行 npx rayfin up staticapp deploy 报告显示没有配置远程端点。

原因：纯静态部署会更新现有部署。它无法配置初始的远程应用。

Solution:

执行一次完整部署：

npx rayfin up

配置完成后，后续仅静态更新请使用 npx rayfin up staticapp deploy。

身份验证问题

获取身份验证令牌失败

症状：npx rayfin login或者其他需要身份验证的 CLI 命令显示 Failed to acquire authentication token 或凭据存储错误。

原因： CLI未登录，或者环境不提供操作系统支持的凭证存储。

Solution:

再次登录：

npx rayfin login

对于没有凭证存储的受限本地开发环境，你可以启用加密备份：

npx rayfin login --encryption-fallback-enabled

Warning

加密备份将令牌缓存存储为明文。只在可信的开发环境中使用它。不要在生产环境或共享环境中使用它。

症状： 身份验证后，用户将立即注销。

原因： 客户端未使用正确的基 URL 或可发布密钥进行配置。

Solution:

RayfinClient验证配置是否与后端匹配：

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Symptom： 浏览器在登录期间阻止Fabric门户窗口。

原因：ensureSignedInWithFabric() 不是从用户手势处理程序调用的。

Solution:

从同步事件处理程序调用函数：

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

Fabric 认证超时

症状：Fabric认证五分钟后失败。

原因：Fabric 门户在流量结束前没有返回交接代码。

Solution:

确认与 returnOrigin 你应用的来源相符，关闭弹窗，重新开始登录流程。

Fabric SSO 提示源不匹配

症状：Fabric SSO handoff拒绝响应，因为响应的来源不匹配。

原因：returnOrigin，allowedRedirectUris或者fabricPortalUrl与应用和Fabric门户运行的环境不匹配。

Solution:

将 returnOrigin 设置为你的应用的基础源。
确认起源出现在 services.auth.allowedRedirectUris。
请使用Fabric门户URL访问正确的生产、预览或开发环境。
更改npx rayfin up后，运行rayfin.yml。

更多信息请参见配置认证重定向URI。

`initEmbeddedAuth()` 返回 `null`

症状： 嵌入认证不会创建会话。

原因：SDK 没有检测到应用运行在 Fabric 内部。

Solution:

在应用URL中包含 ?fabricEmbedded=true ，或设置 fabricEmbedded: true 为 FabricAuthOptions。

Fabric认证报告状态不匹配

症状： 登录失败是因为响应状态与请求状态不匹配。

原因： 该响应属于已过期的流程或先前的登录尝试。

Solution:

关闭 Fabric 弹窗，重新开始登录流程。不要重复使用之前尝试时的回调URL或状态值。

数据模型问题

部署后，Data API 返回内部服务器错误

症状：npx rayfin up 或 npx rayfin up db apply 成功，但GraphQL或REST数据API返回内部服务器错误。

原因：在 Microsoft SQL Server 上，没有 max 的 @text() 字段会生成 NVARCHAR(MAX) 列，这可能会阻止 GraphQL 架构生成。

Solution:

为每个受影响的文本字段添加明确的最大长度：

@text({ max: 200 })
title!: string;

然后复习并应用模式变更：

npx rayfin up db apply --force

Caution

在使用 --force 之前，请先检查所有已报告的操作。该选项可能导致永久性数据丢失。

数据服务需要方言

症状： 部署失败，并返回 HTTP 400 响应，并报告 Dialect is required when Data module is enabled。

原因：services.data.enabled 是 true，但 rayfin.yml 不定义方言。

Solution:

配置 Microsoft SQL Server：

services:
  data:
    enabled: true
    dialect: mssql

部署后新实体不可用

症状： 部署成功，但对新实体或更改实体的查询失败，或者表现得好像该实体不存在。

原因： 数据库模式可能仍在应用，或者前端使用了过时的生成类型或缓存配置。

Solution:

查看部署情况：
```
npx rayfin up status
```
等部署状态良好时再说。
刷新或重建前端。
如果实体仍然失败，则明确应用该模式：
```
npx rayfin up db apply
```

完整工作流程请参见 “应用并验证schema更改”。

API 中未显示的关系

症状： 查询时，相关实体字段不可用。

原因： 导航修饰器缺失或未应用架构。

Solution:

验证关系修饰器是否存在：

@one(() => Notebook) notebook?: Notebook;

重新应用架构。

授权策略不起作用

症状： 用户可以访问他们不应看到的记录。

原因： 策略表达式不正确或声明名称不匹配。

Solution:

验证策略是否使用正确的声明名称（sub，， emailrole）：
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
记录解码的 JWT 以验证声明值是否与代码匹配。

陈旧的 API 响应

症状： 前端在架构更改后返回过时的数据形状。

原因： 生成的配置已缓存。

Solution:

停止后端服务。
删除 .temp/ 中的 rayfin/ 目录：
```
rm -rf rayfin/.temp/
```
重启服务并重新应用架构。

CLI 问题

找不到命令

症状： 运行 npx rayfin 返回“找不到命令”。

原因： CLI 未安装或 npm 不在 PATH 中。

Solution:

验证是否已安装 Node.js 和 npm：
```
node --version
npm --version
```
重新安装依赖项：
```
npm install
```

CLI 版本不匹配

症状： CLI 命令在更新后失败，出现意外错误。

原因： 缓存的 CLI 版本已过时。

Solution:

更新并重新安装：

npm update --save
npm install
npx rayfin --version

CLI 全局版本与本地版本不匹配

症状： CLI 命令失败，项目出现意外错误。

原因： CLI 版本的全局和本地安装，它们不匹配。

解决方案：验证本地版本 npm list @microsoft/rayfin-cli。这里显示的是当前项目的 node_modules 中的版本。检查全局版本 npm list -g @microsoft/rayfin-cli。这显示了系统范围内安装的版本。将 npm uninstall -g 与 Rayfin CLI 包一起使用，以移除全局版本并改用本地版本。

秘密管理问题

隐藏命令不会弹出提示

症状：npx rayfin secret set <NAME> 在未提示输入值的情况下退出。

原因： 标准输入不是交互式终端，或者 CI 环境变量设置为 true。该命令使用一个带掩蔽的交互提示符。

Solution:

请使用以下支持的非交互式秘密创建替代方案之一：

通过将密钥值通过管道传递给命令来设置一个密钥：
```
Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin
```

从环境文件中设置多个秘密：

npx rayfin secret set --env-file .\secrets.env

不要让敏感值出现在 shell 历史记录中，也不要将 secret.txt 或 .\secrets.env 提交到源代码管理中。

隐藏命令返回“权限被拒绝”

症状：npx rayfin secret set 或者 npx rayfin secret list 返回权限错误。

原因：应用未部署，或者登录账户无法访问目标Fabric工作区。

Solution:

运行 npx rayfin up 以配置应用。
运行 npx rayfin login 并选择一个有权限访问工作区的账户。
重试秘密命令。

欲了解更多信息，请参见 “管理函数秘密”。

构建和打包问题

生成命令失败

症状： 静态托管部署失败，因为生成命令未生成任何输出。

原因： 构建错误或配置不当的构建命令。

Solution:

手动运行生成命令：
```
npm run build
```
修复报告的任何错误。
验证输出文件夹是否包含文件。

空静态文件夹

症状： 静态部署失败，出现“空文件夹”错误。

原因： 配置 folder 的路径不正确。

Solution:

验证 folder 中的 rayfin.yml 路径是否与您的构建输出匹配：

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

数据库问题

数据库模式应用失败

症状：运行 npx rayfin up db apply 或 npx rayfin up db apply --force 失败。

原因：远程数据库中的模式和应用代码中定义的模式不同步。应用代码是 Fabric 应用的真实来源。

不要通过Fabric门户、SQL Server Management Studio（SSMS）、Visual Studio Code的SQL Server扩展或其他SQL工具修改远程数据库模式。以下对数据实体中列的更改不被支持：

重新命名一栏。
更改列的数据类型。
移除一根柱子。

支持添加列。删除或修改现有列可能会破坏应用及其在 Fabric 上的部署。

Solution:

将任何手动更改还原到远程数据库模式，使其与应用代码中的模式匹配。
如果编码代理在应用代码中做了不支持的模式更改，指示代理还原该更改。
再次运行schema apply命令：
```
npx rayfin up db apply
```
对于列重命名， --force 可能允许模式更新完成：
```
npx rayfin up db apply --force
```
Caution

使用 --force 可能会导致永久数据丢失。在继续前，请审查拟议的操作，并确认您已接受数据丢失风险。

连接被拒绝

症状： 数据操作失败并出现连接错误。

原因： 数据库容器未运行或运行状况检查失败。

Solution:

查看容器日志：
```
docker compose logs -f
```
重启服务。

重启后数据丢失

症状： 停止和启动服务后，数据将消失。

原因：存储卷已使用 --purge 删除。

Solution:

使用 --down 而不是 --purge 保留数据。

已知的限制

有关当前限制和建议的解决方法，请参阅：

count() 在 fluent GraphQL 客户端上不可用 - 使用 results.length。
不支持多对多关系——使用显式连接实体。
会话对象不透明- 检查 isAuthenticated 或 user 属性。
启用或禁用身份验证 rayfin.yml后，重启后端。

获取帮助

如果问题仍然存在：

查看 Fabric 应用文档。
检查 GitHub 存储库是否存在已知问题。
提交包含详细日志和复制步骤的 bug 报告。

反馈

此页面是否有帮助？

上次更新时间为 2026-09-29

排查 Fabric 应用问题

部署问题

部署失败，出现 401 或 403 错误

静态部署超出大小限制

静态部署没有远程端点

身份验证问题

获取身份验证令牌失败

登录后会话未持久化

Fabric SSO 弹出窗口被阻止

Fabric 认证超时

Fabric SSO 提示源不匹配

initEmbeddedAuth() 返回 null

Fabric认证报告状态不匹配

数据模型问题

部署后，Data API 返回内部服务器错误

数据服务需要方言

部署后新实体不可用

API 中未显示的关系

授权策略不起作用

陈旧的 API 响应

CLI 问题

找不到命令

CLI 版本不匹配

CLI 全局版本与本地版本不匹配

秘密管理问题

隐藏命令不会弹出提示

隐藏命令返回“权限被拒绝”

构建和打包问题

生成命令失败

空静态文件夹

数据库问题

数据库模式应用失败

连接被拒绝

重启后数据丢失

已知的限制

获取帮助

相关内容

反馈

其他资源

`initEmbeddedAuth()` 返回 `null`