Unvus Docs

Appearance

Firo 트러블슈팅 가이드 ​

일반적인 문제 해결 ​

1. Firo 초기화 실패 ​

문제: "Failed to initialize Firo" 오류 ​

Caused by: java.lang.RuntimeException: Azure Blob Storage initialization failed

해결 방법:

  1. Azure 설정 확인:

    properties
    # 필수 속성들이 모두 설정되어 있는지 확인
firo.azure.connection-string=DefaultEndpointsProtocol=https;AccountName=...
firo.azure.container=your-container-name

  2. Connection String 유효성 검증:

    • Azure Portal에서 Storage Account의 Access Keys 확인
    • Connection String이 정확히 복사되었는지 확인
    • 특수문자나 줄바꿈이 포함되지 않았는지 확인

  3. Container 존재 여부 확인:

    • Azure Storage에서 지정된 Container가 생성되어 있는지 확인
    • Container 이름이 정확한지 확인 (대소문자 구분)

문제: "Azure connection string is required" 오류 ​

java.lang.IllegalArgumentException: Azure connection string is required but not provided

해결 방법:

  • firo.azure.connection-string 속성이 설정되어 있는지 확인
  • 속성 값이 비어있지 않은지 확인

2. S3 관련 문제 ​

문제: S3 Adapter 초기화 실패 ​

com.amazonaws.services.s3.model.AmazonS3Exception: The AWS Access Key Id you provided does not exist

해결 방법:

  1. AWS 인증 정보 확인:

    properties
    firo.s3.access-key=AKIA...  # 올바른 Access Key
firo.s3.secret-key=...      # 올바른 Secret Key
firo.s3.region=us-west-2    # 올바른 리전
firo.s3.bucket=your-bucket  # 존재하는 버킷명

  2. IAM 권한 확인:

    • 필요한 S3 권한이 있는지 확인 (GetObject, PutObject, DeleteObject, ListBucket)
    • IAM 정책이 올바르게 설정되었는지 확인

  3. 버킷 존재 확인:

    • 지정된 버킷이 올바른 리전에 생성되어 있는지 확인

3. MyBatis 관련 문제 ​

문제: "Result Maps collection does not contain value" 오류 ​

org.apache.ibatis.builder.IncompleteElementException: Could not find result map

해결 방법:

  1. Type Alias 충돌 확인:

    • 외부 프로젝트와 Firo의 Type Alias가 충돌하지 않는지 확인
    • Firo는 Firo 접두사를 가진 Type Alias를 사용합니다

  2. 패키지 설정 확인:

    properties
    # 이 설정은 필요하지 않습니다 (Firo가 자동 관리)
# mybatis.type-aliases-package=com.unvus.firo.core.module.service.domain

  3. Mapper XML 확인:

    • Mapper XML에서 올바른 Type Alias를 사용하고 있는지 확인

4. 파일 업로드 문제 ​

문제: 파일 업로드 시 권한 오류 ​

java.nio.file.AccessDeniedException: /var/uploads/temp/

해결 방법:

  1. 디렉토리 권한 확인:

    bash
    sudo chown -R your-user:your-group /var/uploads/
sudo chmod -R 755 /var/uploads/

  2. 디렉토리 존재 확인:

    bash
    mkdir -p /var/uploads/temp/

  3. 설정 확인:

    properties
    firo.directory.base-dir=/var/uploads/
firo.directory.tmp-dir=/var/uploads/temp/

문제: 파일 크기 제한 오류 ​

org.springframework.web.multipart.MaxUploadSizeExceededException

해결 방법:

properties
# Spring Boot 파일 업로드 크기 제한 설정
spring.servlet.multipart.max-file-size=100MB
spring.servlet.multipart.max-request-size=100MB

5. Bean 충돌 문제 ​

문제: "Parameter 0 of constructor required a single bean, but 2 were found" ​

Parameter 0 of constructor in com.unvus.firo.core.module.service.FiroService required a single bean of type 'com.unvus.firo.core.module.repository.FiroFileRepository', but 2 were found

해결 방법:

  1. 데이터베이스 타입 명시:

    properties
    # JPA 사용 시
firo.db.type=jpa

# MyBatis 사용 시  
firo.db.type=mybatis

  2. 조건부 Bean 로딩 확인:

    • firo.db.type 설정에 따라 하나의 Repository 구현체만 로드됩니다
    • 설정이 누락되면 기본적으로 JPA가 사용됩니다

문제: "Unable to read meta-data for class FiroAzureConfiguration" ​

java.lang.IllegalStateException: Unable to read meta-data for class com.unvus.firo.web.config.FiroAzureConfiguration

해결 방법:

  1. Azure 의존성 확인:

    gradle
    dependencies {
    implementation 'com.azure:azure-storage-blob:12.25.0'
}

  2. Azure 설정 누락 허용:

    • Azure 설정이 없어도 Firo는 정상적으로 초기화됩니다
    • Azure를 사용하지 않는 경우 관련 설정을 제거하세요

  3. 조건부 로딩 확인:

    • Azure 클래스가 classpath에 있을 때만 Configuration이 로드됩니다

6. 설정 관련 문제 ​

문제: "Property 'firo.db.type' not found" 오류 ​

해결 방법:

properties
# 데이터베이스 타입 설정 (기본값: jpa)
firo.db.type=jpa  # 또는 mybatis

문제: Bean 생성 실패 ​

No qualifying bean of type 'com.unvus.firo.core.module.service.FiroService'

해결 방법:

  1. Auto Configuration 확인:

    • @EnableAutoConfiguration 또는 @SpringBootApplication이 있는지 확인

  2. 의존성 확인:

    gradle
    dependencies {
    implementation 'com.unvus.firo:firo-core:1.2.0-SNAPSHOT'
    implementation 'com.unvus.firo:firo-jpa:1.2.0-SNAPSHOT'  // 또는 firo-mybatis
    implementation 'com.unvus.firo:firo-web:1.2.0-SNAPSHOT'
}

7. 정적 리소스 문제 ​

문제: "No static resource attach-direct/view/default" 오류 ​

해결 방법:

  1. 엔드포인트 확인:

    GET /assets/firo/attach-direct/view/{refDomain}/{refCategory}?path={filePath}
GET /assets/firo/attach-direct/view/default?path={filePath}  # default 경로
GET /assets/firo/attach-direct/download/{refDomain}/{refCategory}?path={filePath}

  2. 도메인/카테고리 등록 확인:

    java
    @PostConstruct
public void setupFiroDomains() {
    FiroDomain defaultDomain = FiroDomain.builder("default").build();
    defaultDomain.addCategory("default");
    FiroRegistry.add(defaultDomain);
}

  3. 파일 경로 확인:

    • 파일이 실제로 존재하는지 확인
    • 권한이 올바르게 설정되어 있는지 확인
    • SecureAccessFunc을 통한 접근 제어 확인

8. iflex 1.8.0 호환성 문제 ​

문제: iflex와 함께 사용 시 초기화 실패 ​

해결 방법:

  1. Firo 활성화 설정:

    properties
    # Firo 활성화 (기본값: true)
firo.enabled=true

# 데이터베이스 타입 명시
firo.db.type=mybatis  # iflex는 주로 MyBatis 사용

  2. 의존성 순서 확인:

    gradle
    dependencies {
    implementation 'com.unvus.firo:firo-core:1.2.0-SNAPSHOT'
    implementation 'com.unvus.firo:firo-mybatis:1.2.0-SNAPSHOT'
    // iflex 의존성은 firo 이후에 추가
}

  3. Auto Configuration 확인:

    • @EnableAutoConfiguration이 활성화되어 있는지 확인
    • Firo Configuration이 올바르게 로드되는지 확인

9. 로깅 설정 ​

디버깅을 위한 로깅 설정:

properties
# Firo 관련 로깅
logging.level.com.unvus.firo=DEBUG

# MyBatis 쿼리 로깅 (MyBatis 사용 시)
logging.level.com.unvus.firo.mybatis.mapper=DEBUG

# JPA 쿼리 로깅 (JPA 사용 시)
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

# 파일 업로드 관련 로깅
logging.level.org.springframework.web.multipart=DEBUG

7. 성능 최적화 ​

대용량 파일 처리 ​

properties
# 임시 파일 위치 설정 (충분한 디스크 공간 확보)
firo.directory.tmp-dir=/var/tmp/firo/

# JVM 메모리 설정
-Xmx2g -XX:+UseG1GC

데이터베이스 연결 풀 최적화 ​

properties
# HikariCP 설정 (JPA 사용 시)
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=20000

지원 및 문의 ​

추가적인 문제가 발생하면 다음을 확인하세요:

  1. 로그 분석: DEBUG 레벨 로그를 활성화하여 상세한 오류 정보 확인
  2. 설정 검증: 모든 필수 설정이 올바르게 되어 있는지 확인
  3. 의존성 확인: 올바른 버전의 의존성을 사용하고 있는지 확인
  4. 환경 확인: 개발/테스트/프로덕션 환경별 설정이 적절한지 확인