Fabric 앱 문제 해결

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

배포 문제

401 또는 403 오류로 배포 실패

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

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

Solution:

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

npx rayfin login
npx rayfin up

데이터베이스 적용 시 파괴적 변경 사항이 보고됩니다

증상: 데이터 손실에 대한 경고가 있는 실행 npx rayfin up db apply 블록입니다.

원인: CLI에서 데이터를 삭제할 수 있는 스키마 변경(열 삭제, 테이블 이름 바꾸기)을 검색했습니다.

Solution:

나열된 작업을 신중하게 검토합니다. 데이터 손실을 수락하는 경우 다음을 사용합니다 --force.

npx rayfin up db apply --force

Caution

--force을(를) 사용하면 영구적인 데이터 손실을 초래할 수 있습니다. 계속하기 전에 작업을 확인합니다.

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

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

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

Solution:

다음과 같이 빌드 출력 크기를 줄입니다.

  • 프로덕션 빌드에서 원본 맵 제외
  • 큰 이미지 및 비디오 최적화 또는 제거
  • 이진 파일을 묶는 대신 스토리지로 이동
  • 번들러 구성을 확인하면 개발 아티팩트가 제외됩니다.

인증 문제

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

증상: 사용자는 인증 직후 로그아웃됩니다.

원인: 클라이언트가 올바른 기본 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,
});

Fabric SSO 팝업이 차단됨

Symptom: 브라우저는 로그인하는 동안 Fabric 포털 창을 차단합니다.

원인:ensureSignedInWithFabric() 사용자 제스처 처리기에서 호출되지 않았습니다.

Solution:

동기 이벤트 처리기에서 함수를 호출합니다.

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

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

데이터 모델 문제

API에 표시되지 않는 관계

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

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

Solution:

  1. 관계 데코레이터가 있는지 확인합니다.

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

  2. 스키마를 다시 적용합니다.

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

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

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

Solution:

  1. 정책이 올바른 클레임 이름(, sub, email)role을 사용하는지 확인합니다.

    policy: (claims, item) => claims.sub.eq(item.user_id)

  2. 디코딩된 JWT를 기록하여 클레임 값이 코드와 일치하는지 확인합니다.

오래된 API 응답

증상: 프런트 엔드는 스키마가 변경된 후 오래된 데이터 셰이프를 반환합니다.

원인: 생성된 구성이 캐시됩니다.

Solution:

  1. 백엔드를 중지하세요.

  2. 에서 .temp/ 디렉터리를 삭제합니다.rayfin/

    rm -rf rayfin/.temp/

  3. 서비스를 다시 시작하고 스키마를 다시 적용합니다.

CLI 문제

명령을 찾을 수 없음

증상: 실행하면 npx rayfin "명령을 찾을 수 없습니다."가 반환됩니다.

원인: CLI가 설치되지 않았거나 npm이 PATH에 없습니다.

Solution:

  1. Node.js 및 npm이 설치되어 있는지 확인합니다.

    node --version
npm --version

  2. 종속성을 다시 설치합니다.

    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를 사용해 전역 버전을 삭제하고 로컬 버전을 사용하세요.

빌드 및 패키징 문제

빌드 명령 실패

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

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

Solution:

  1. 수동으로 빌드 명령을 실행합니다.

    npm run build

  2. 보고된 오류를 수정합니다.

  3. 출력 폴더에 파일이 포함되어 있는지 확인합니다.

빈 정적 폴더

증상: "빈 폴더" 오류로 정적 배포가 실패합니다.

원인: 구성된 folder 경로가 잘못되었습니다.

Solution:

경로 folder 가 rayfin.yml 빌드 출력과 일치하는지 확인합니다.

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

데이터베이스 문제

연결이 거부되었습니다.

증상: 연결 오류로 데이터 작업이 실패합니다.

원인: 데이터베이스 컨테이너가 실행되고 있지 않거나 상태 검사에 실패했습니다.

Solution:

  1. 컨테이너 로그 검토:

    docker compose logs -f

  2. 서비스를 다시 시작합니다.

다시 시작한 후 데이터 손실

증상: 서비스를 중지하고 시작한 후 데이터가 사라집니다.

원인: 볼륨이 --purge와 함께 삭제되었습니다.

Solution:

데이터를 보존하려면 --purge 대신 --down를 사용합니다.

알려진 제한 사항

현재 제한 사항 및 권장 해결 방법은 다음을 참조하세요.

  • count()은(는) Fluent GraphQL 클라이언트에서 사용할 수 없습니다. 대신 results.length을(를) 사용하세요.
  • 다대다 관계는 지원되지 않습니다. 명시적 조인 엔터티를 사용하세요.
  • 세션 개체는 불투명합니다(확인 isAuthenticated 또는 user 속성).
  • 인증 rayfin.yml을 사용하거나 사용하지 않도록 설정한 후 백 엔드를 다시 시작합니다.

도움받기

문제가 지속되는 경우:

  1. Fabric 앱 설명서 검토합니다.
  2. 알려진 문제는 GitHub 리포지토리에서 확인하세요.
  3. 자세한 로그 및 재현 단계를 사용하여 버그 보고서를 제출합니다.

관련 콘텐츠

  • Last updated on