Fabric Apps 项目将后台配置、数据模型和前端代码分开。 具体布局取决于模板。 默认 blankapp 模板解析为 Universal App，这是一个拥有独立前端、数据和共享包的 npm 工作区。
文件夹布局
默认的通用应用支架结构如下：
your-project/
├── rayfin/
│ ├── .env
│ ├── rayfin.yml
│ └── tsconfig.json
├── packages/
│ ├── frontend/
│ │ ├── src/
│ │ └── package.json
│ ├── data/
│ │ └── src/index.ts
│ └── shared/
│ └── src/index.ts
├── package.json
├── tsconfig.json
└── README.md
| Location | 所有权 |
|---|---|
rayfin/ |
后端配置和当前环境的值。 |
packages/frontend/ |
浏览器界面、客户端初始化和前端构建。 |
packages/data/ |
带装饰器的运行时实体类和架构注册。 |
packages/shared/ |
与前端共享的同构记录契约和模式类型。 不要在这里放后端专用代码。 |
基础脚手架中的数据被禁用。 当应用需要持久记录时启用：
npm run pack:add -- data-modeling
该功能增加了起始实体和共享契约，并启用了数据服务。 关于实体创作和MSSQL方言配置，请参见 定义数据模型。
Flat-template 替代方案
一些模板和现有应用使用平面布局，前端代码位于 root src/ 中，实体位于 rayfin/data/ 中，模式类型映射位于 rayfin/data/schema.ts 中。 这种布局依然有效。 不要移动文件或创建重复包来匹配另一个模板。 阅读 rayfin/rayfin.yml 中的服务路径，找到你的项目实际构建的目录。
关键配置文件
rayfin/rayfin.yml
rayfin/rayfin.yml 文件是Fabric应用后端的主配置文件。 它控制哪些服务在本地开发期间运行，并支持动态配置值的环境变量内插。
默认工作区使用显式服务路径。 以下示例展示了为需要数据库的应用启用“数据”后的这些路径：
id: my-app
name: my-app
version: 1.0.0
services:
auth:
enabled: true
allowedRedirectUris:
- http://localhost:5173
fabric:
enabled: true
externalEntraExchange: true
password:
enabled: false
data:
enabled: true
dialect: mssql
path: packages/data
buildCommand: npm run build
staticHosting:
enabled: true
path: packages/frontend
folder: dist
buildCommand: npm run build:fabric
indexDocument: index.html
assetAccess: protected
服务 path 值是相对于项目根的。 构建命令在已解析的服务目录中运行。 函数初始化还会在选择工作区包（如 packages/functions）时记录 services.functions.path。 扁平项目可以使用现有的 rayfin/functions 位置。 参见 使用函数。
配置包括以下关键字段：
顶级字段
| 领域 | 类型 | 必需 | 说明 |
|---|---|---|---|
id |
string |
是的 | 用作 Docker Compose 项目名称和 Fabric 项目标识符的 slug（短标识）。 |
name |
string |
是的 | 便于阅读的项目显示名称。 |
version |
string |
是的 | Project版本（semver）。 |
services |
object |
是的 | 服务配置块。 |
services.data
| 领域 | 类型 | 默认 | 说明 |
|---|---|---|---|
enabled |
boolean |
false |
启用数据服务。 |
dialect |
string |
— | 在 Fabric 中将 mssql 用于 SQL 数据库。 启用数据时为必填项。 |
path |
string |
— | 相对于项目根的数据包目录，例如 packages/data。 平面模板可以使用 rayfin/data。 |
buildCommand |
string |
— | 为配置的数据包构建命令。 |
services.auth
| 领域 | 类型 | 默认 | 说明 |
|---|---|---|---|
enabled |
boolean |
false |
启用身份验证服务。 |
expiryInMinutes |
number |
— | JWT 令牌在几分钟内过期。 |
customClaims |
Record<string, string> |
— | 添加到已签发 JWT 中的自定义声明。 |
scopes |
string[] |
— | OAuth 范围（例如 ["read:data", "write:data"]）。 |
refreshToken.lifetimeInDays |
number |
— | 刷新令牌有效期（天数）。 |
allowedRedirectUris |
string[] |
["http://localhost:5173"] |
允许用于身份验证回调的重定向 URI。 |
services.auth.password
| 领域 | 类型 | 默认 | 说明 |
|---|---|---|---|
enabled |
boolean |
true |
为本地开发启用电子邮件和密码身份验证 |
services.auth.fabric
| 领域 | 类型 | 默认 | 说明 |
|---|---|---|---|
enabled |
boolean |
false |
启用Fabric中转身份验证（Microsoft Entra ID SSO）。 |
externalEntraExchange |
boolean |
— | 在目标环境支持时，启用直接委派Entra令牌交换和外部父主机认证。 |
services.staticHosting
| 领域 | 类型 | 默认 | 说明 |
|---|---|---|---|
enabled |
boolean |
false |
启用静态内容托管。 |
path |
string |
— | 前端包目录相对于项目根节点。 |
root |
string |
— | 旧版前端根，用于扁平配置。 |
folder |
string |
"dist" |
包含相对于已解析前端路径构建的静态资产的目录。 |
buildCommand |
string |
— | 打包之前要运行的 Shell 命令（例如， npm run build）。 |
indexDocument |
string |
— | 为根路径提供的默认文档（例如， index.html）。 |
小窍门
所有字符串值都支持使用 ${VAR} 和 ${VAR:-default} 语法进行环境变量插值。 变量从 rayfin/.env 和 Shell 环境中解析。
rayfin/.env
该 rayfin/.env 文件包含当前运行时和部署值，并通过插值向 rayfin.yml 提供值。 CLI 为当前活动的后端写入框架中立的 RAYFIN_PUBLIC_* 值。 只有带有该前缀的变量才会投影到生成的前端环境文件中。 绝不要把敏感信息放进 RAYFIN_PUBLIC_* 变量里。
不要将 rayfin/.env 纳入版本控制。 使用 rayfin/.env.example 记录带有占位符的预期变量。
rayfin/.deployments.json
部署注册表记录了项目部署的后端 URL、托管 URL、项 ID 和工作区 ID。 它不是一个前端环境文件。 不要将其纳入源代码管理。 使用 npx rayfin up list 列出已记录的部署，使用 npx rayfin up switch <name> 切换当前活动部署并重新生成其环境值。
rayfin/tsconfig.json
模板为其自身布局提供 TypeScript 配置。 Workspace 包有自己的配置和项目引用；平面模板可以通过 rayfin/tsconfig.json 编译实体。 保留脚手架的引用，使用其构建和类型检查脚本，而不要假定只有单一根级编译流程。
数据模型文件
保持运行时注册和面向客户端的类型与你所选的布局保持一致。
工作空间实体与共享契约
在通用应用中，packages/data/src/ 下的文件定义了装饰实体类。 在由 schema 导出的 packages/data/src/index.ts 数组中注册运行时类。
保持匹配的记录接口以及 packages/shared/src/index.ts 中的 UniversalAppSchema 类型。 前端是从这个契约 @rayfin-app/shared 导入，而不是导入装饰过的后端类。
平面模板实体
在平面模板中，rayfin/data/*.ts定义实体，rayfin/data/schema.ts将实体名称映射为client.data.<Entity>的类型。 按照模板提供的注册机制操作。
生成的产物
rayfin/.temp/
该 rayfin/.temp/ 文件夹包含运行开发服务器时创建的生成的后端项目。 如果后端似乎正在使用过时的架构或配置，请停止并重启开发堆栈以重新生成这些文件。
Important
不要将 .temp/ 文件夹提交到存储库。 将其添加到 .gitignore 文件。
前端结构
默认前端位于 packages/frontend/src/。 扁平模板可以使用根 src/。
services.staticHosting.path 设置用于标识前端包。
当前环境与框架映射
rayfin dev 和 rayfin up 从 .env.local 生成框架特定的 rayfin/.env 值。 对于嵌套前端，文件写成 services.staticHosting.path，例如 packages/frontend/.env.local;平面项目使用项目根。
源位于rayfin/.env |
Vite 输出在 .env.local 中 |
.env.local 中的 Next.js 输出 |
|---|---|---|
RAYFIN_PUBLIC_API_URL |
VITE_RAYFIN_API_URL |
NEXT_PUBLIC_RAYFIN_API_URL |
RAYFIN_PUBLIC_PUBLISHABLE_KEY |
VITE_RAYFIN_PUBLISHABLE_KEY |
NEXT_PUBLIC_RAYFIN_PUBLISHABLE_KEY |
RAYFIN_PUBLIC_ITEM_ID |
VITE_FABRIC_ITEM_ID |
NEXT_PUBLIC_FABRIC_ITEM_ID |
RAYFIN_PUBLIC_WORKSPACE_ID |
VITE_FABRIC_WORKSPACE_ID |
NEXT_PUBLIC_FABRIC_WORKSPACE_ID |
RAYFIN_PUBLIC_PORTAL_URL |
VITE_FABRIC_PORTAL_URL |
NEXT_PUBLIC_FABRIC_PORTAL_URL |
在 rayfin/.env 中编辑源值，而不是生成的文件。 无需部署即可重新生成：
npx rayfin env --framework vite
可使用 --framework nextjs 或 --framework plain 用于其他支持的映射。 使用 --output <dir> 选择输出目录，或使用 --show 检查公共映射而无需写入。 不要将生成的 .env.local 文件纳入源代码控制。
迁移旧的环境布局
较早的项目可能包含 .env.fabric 或 .env.fabric-<workspace> 文件。 这些文件不是当前布局中的活动环境文件。 运行 npx rayfin up 以使用当前环境的工作流程。 查看任何迁移消息，并根据需要将自定义值复制到 rayfin/.env 中。 部署注册表取代了每个工作区的环境文件。 不要将新应用配置为依赖它们。