Fabric 앱 문제 해결

Fabric Apps 프로젝트를 개발하거나 배포할 때 발생하는 일반적인 문제를 진단합니다. 이 문서에서는 로그인, 로컬 서비스, 스키마 변경, 정적 호스팅 및 CLI 관련 문제를 다룹니다.

배포 문제

401 또는 403 오류로 배포 실패

증상: 실행 npx rayfin up 하면 인증 오류가 반환됩니다.

원인: 인증 세션이 만료되었거나 로그인하지 않았습니다.

Solution:

배포를 다시 인증하고 다시 시도합니다.

npx rayfin login
npx rayfin up

정적 배포가 크기 제한을 초과합니다.

증상: 크기 제한 오류로 정적 콘텐츠 배포가 실패합니다.

원인: 압축된 보관 파일은 100MB를 초과합니다.

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 인증이 5분 후에 실패합니다.

원인: Fabric 포털이 플로우가 만료되기 전에 넘김 코드를 반환하지 않았습니다.

Solution:

앱의 returnOrigin 출처와 일치하는지 확인하고, 팝업을 닫은 뒤 다시 로그인 과정을 시작하세요.

Fabric SSO가 원점 불일치를 보고합니다

증상: Fabric SSO 핸드오프가 응답의 출처가 일치하지 않아 응답을 거부합니다.

원인: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을 포함하거나 FabricAuthOptions에서 fabricEmbedded: true을 설정합니다.

Fabric 인증은 상태 불일치를 보고합니다

증상: 응답 상태가 요청 상태와 일치하지 않아 로그인 실패.

원인: 응답은 만료된 플로우나 이전 로그인 시도에 해당합니다.

Solution:

Fabric 팝업을 닫고 로그인 흐름을 다시 시작하세요. 이전 시도에서 콜백 URL이나 상태 값을 재사용하지 마세요.

데이터 모델 문제

데이터 API는 배포 후 내부 서버 오류를 반환합니다

증상:npx rayfin up 또는 npx rayfin up db apply 성공했지만, GraphQL 또는 REST 데이터 API가 내부 서버 오류를 반환합니다.

원인: Microsoft SQL Server에서 @text()이 없는 max 필드는 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
```

전체 워크플로우는 ' 스키마 변경 적용 및 검증'을 참조하세요.

API에 표시되지 않는 관계

증상: 쿼리할 때는 관련 엔터티 필드를 사용할 수 없습니다.

원인: 탐색 데코레이터가 없거나 스키마가 적용되지 않았습니다.

Solution:

관계 데코레이터가 있는지 확인합니다.
```
@one(() => Notebook) notebook?: Notebook;
```
스키마를 다시 적용합니다.

권한 부여 정책이 작동하지 않음

증상: 사용자는 볼 수 없는 레코드에 액세스할 수 있습니다.

원인: 정책 식이 잘못되거나 클레임 이름이 일치하지 않습니다.

Solution:

정책이 올바른 클레임 이름(, sub, email)role을 사용하는지 확인합니다.
```
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을 확인하세요. 시스템 전체에 설치된 버전을 보여줍니다. Rayfin CLI 패키지에서 npm uninstall -g를 사용해 전역 버전을 삭제하고 로컬 버전을 사용하세요.

비밀 관리 문제

비밀 명령어가 프롬프트를 표시하지 않습니다

증상: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
```

비밀 값이 셸 기록에 남지 않도록 하고, secret.txt 또는 .\secrets.env를 소스 제어에 커밋하지 마세요.

비밀 명령이 권한 거부를 반환함

증상:npx rayfin secret set 또는 npx rayfin secret list 권한 오류를 반환합니다.

원인: 앱이 배포되지 않았거나, 로그인한 계정이 대상 Fabric 작업 공간에 접근할 수 없습니다.

Solution:

앱을 프로비저닝하기 위해 실행하세요 npx rayfin up .
작업 공간에 접근할 수 있는 계정을 실행 npx rayfin login 하고 선택하세요.
비밀 명령을 다시 시도하세요.

자세한 내용은 함수 비밀 관리(Manage function secrets)를 참조하세요.

빌드 및 패키징 문제

빌드 명령 실패

증상: 빌드 명령에서 출력을 생성하지 않아 정적 호스팅 배포가 실패합니다.

원인: 빌드 오류 또는 잘못 구성된 빌드 명령입니다.

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:

원격 데이터베이스 스키마에 수동으로 변경한 모든 것을 앱 코드의 스키마와 일치하도록 되돌리세요.
코딩 에이전트가 앱 코드에서 지원되지 않는 스키마 변경을 했다면, 그 변경을 되돌리도록 지시하세요.
스키마 적용 명령을 다시 실행하세요:
```
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 리포지토리에서 확인하세요.
자세한 로그 및 재현 단계를 사용하여 버그 보고서를 제출합니다.

피드백

이 페이지가 도움이 되었나요?

2026-09-29 에 마지막으로 업데이트됨

Fabric 앱 문제 해결

배포 문제

401 또는 403 오류로 배포 실패

정적 배포가 크기 제한을 초과합니다.

정적 배포에는 원격 엔드포인트가 없습니다

인증 문제

인증 토큰 획득 실패

로그인 후 세션이 유지되지 않음

Fabric SSO 팝업이 차단됨

Fabric 인증 시간이 초과됨

Fabric SSO가 원점 불일치를 보고합니다

initEmbeddedAuth() null를 반환합니다

Fabric 인증은 상태 불일치를 보고합니다

데이터 모델 문제

데이터 API는 배포 후 내부 서버 오류를 반환합니다

데이터 서비스는 방언이 필요합니다

배포 후 새 엔터티를 사용할 수 없습니다

API에 표시되지 않는 관계

권한 부여 정책이 작동하지 않음

오래된 API 응답

CLI 문제

명령을 찾을 수 없음

CLI 버전 불일치

CLI 전역 및 로컬 버전 불일치

비밀 관리 문제

비밀 명령어가 프롬프트를 표시하지 않습니다

비밀 명령이 권한 거부를 반환함

빌드 및 패키징 문제

빌드 명령 실패

빈 정적 폴더

데이터베이스 문제

데이터베이스 스키마 적용 실패

연결이 거부되었습니다.

다시 시작한 후 데이터 손실

알려진 제한 사항

도움받기

관련 콘텐츠

피드백

추가 리소스

`initEmbeddedAuth()` `null`를 반환합니다