본문으로 건너뛰기

자주 발생하는 문제

Multi-SaaS Kit 사용 시 자주 발생하는 문제와 해결 방법입니다.

설치 문제​

Composer 의존성 오류​

증상:

Your requirements could not be resolved to an installable set of packages.

원인:

  • PHP 버전 불일치
  • 패키지 버전 충돌

해결 방법:

  1. PHP 버전 확인

    php -v
    # 필요 버전: PHP 8.2+

  2. Composer 캐시 정리

    composer clear-cache
    composer install --no-cache

  3. Lock 파일 삭제 후 재설치

    rm composer.lock
    composer install

npm 패키지 설치 실패​

증상:

npm ERR! ERESOLVE unable to resolve dependency tree

해결 방법:

# node_modules 삭제 후 재설치
rm -rf node_modules package-lock.json
npm install

# 또는 legacy 모드 사용
npm install --legacy-peer-deps

실행 오류​

500 Internal Server Error​

증상:

  • 페이지 로딩 시 500 에러
  • 아무런 내용 없이 빈 화면

원인 파악:

  1. 로그 확인

    # Laravel 로그
    tail -f storage/logs/laravel.log

    # 또는 Docker 로그
    docker logs myapp-web -f

  2. 상세 에러 보기

    # .env에서 디버그 활성화 (개발 환경만)
    APP_DEBUG=true

일반적인 원인:

원인해결 방법
캐시 문제php artisan cache:clear
설정 캐시php artisan config:clear
뷰 캐시php artisan view:clear
권한 문제chmod -R 775 storage bootstrap/cache
.env 미설정cp .env.example .env && php artisan key:generate

Class Not Found​

증상:

Class "App\Some\Class" not found

해결 방법:

# Composer autoload 재생성
composer dump-autoload

# 또는 전체 캐시 정리
php artisan optimize:clear

Route Not Found (404)​

증상:

404 | NOT FOUND

확인 사항:

  1. 라우트 목록 확인

    php artisan route:list | grep "경로명"

  2. 라우트 캐시 정리

    php artisan route:clear

  3. 미들웨어 확인

    // routes/web.php 또는 api.php에서 미들웨어 확인
    Route::middleware(['tenant'])->group(...)

환경 설정 문제​

APP_KEY 미설정​

증상:

No application encryption key has been specified.

해결 방법:

php artisan key:generate

.env 파일 누락​

증상:

  • 환경변수가 null로 나옴
  • 설정값이 적용되지 않음

해결 방법:

# .env 파일 생성
cp .env.example .env

# 설정 수정
vi .env

# 캐시 정리 (설정 캐시된 경우)
php artisan config:clear

환경변수가 적용되지 않음​

증상:

  • .env 수정 후에도 이전 값 사용

해결 방법:

# 설정 캐시 정리
php artisan config:clear

# Docker 환경이면 컨테이너 재시작
docker restart myapp-web
팁

php artisan config:cache를 사용하면 .env 변경 후 반드시 config:clear가 필요합니다.

성능 문제​

페이지 로딩이 느림​

원인 파악:

  1. Laravel Debugbar 설치 (개발 환경)

    composer require barryvdh/laravel-debugbar --dev

  2. 쿼리 확인

    • Debugbar에서 Queries 탭 확인
    • N+1 문제 확인

일반적인 해결 방법:

// 1. Eager Loading 사용
$users = User::with('tenant', 'roles')->get();

// 2. 캐싱 활용
Cache::remember('key', 3600, function () {
    return DB::table('expensive_query')->get();
});

// 3. 인덱스 추가
Schema::table('users', function (Blueprint $table) {
    $table->index(['tenant_id', 'email']);
});

메모리 부족​

증상:

Allowed memory size of XXX bytes exhausted

해결 방법:

  1. PHP 메모리 증가

    # php.ini 또는 Docker 환경변수
    memory_limit = 512M

  2. 대량 데이터 처리 시 chunk 사용

    User::chunk(1000, function ($users) {
        foreach ($users as $user) {
            // 처리
        }
    });

인증 문제​

로그인이 안 됨​

확인 사항:

  1. 세션 드라이버 확인

    # .env
    SESSION_DRIVER=redis  # 또는 database

  2. Redis/Database 연결 확인

    php artisan tinker
    >>> Redis::ping()
    >>> DB::connection()->getPdo()

  3. CSRF 토큰 확인

    <form method="POST">
        @csrf  <!-- 반드시 포함 -->
    </form>

세션이 유지되지 않음​

원인:

  • 쿠키 도메인 설정 문제
  • SESSION_DOMAIN 불일치

해결 방법:

# .env
SESSION_DOMAIN=.example.com  # 서브도메인 공유 시
SESSION_SECURE_COOKIE=false  # HTTPS가 아닌 경우

빠른 진단 명령어​

전체 캐시 정리​

php artisan optimize:clear

시스템 상태 확인​

# 라우트 확인
php artisan route:list

# 설정 확인
php artisan config:show app

# 환경 확인
php artisan about

Docker 환경 진단​

# 컨테이너 상태
docker ps -a

# 로그 확인
docker logs myapp-web

# 컨테이너 접속
docker exec -it myapp-web bash

긴급 복구 절차​

1. 기본 캐시 정리​

php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

2. 권한 재설정​

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

3. 의존성 재설치​

composer install --no-dev --optimize-autoloader
npm ci && npm run build

4. 마이그레이션 확인​

php artisan migrate:status
php artisan migrate

도움 요청​

위 방법으로 해결되지 않으면:

  1. 로그 수집: storage/logs/laravel.log
  2. 환경 정보: php artisan about 결과
  3. 재현 단계: 문제 발생 과정 정리
  4. GitHub Issues: 이슈 등록

관련 문서​