문제 해결

대부분의 문제는 몇 가지 원인으로 귀결됩니다: PHP 버전, 파일 권한, 데이터베이스 자격 증명, 웹 서버 리라이팅 또는 누락된 워커. 이 페이지에서는 운영자가 가장 자주 겪는 증상과 각각의 해결 방법을 설명합니다. 확신이 없을 때는 PHP 에러 로그가 가장 빠른 해결책입니다.

설치 문제

"PHP 버전이 지원되지 않습니다"

TubePress는 PHP 8.2 이상이 필요하며, 다른 모든 것보다 먼저 실행되는 파싱 안전 버전 가드로 적용됩니다. 호스팅 패널에서 PHP 버전을 전환하거나 (또는 vhost를 최신 PHP-FPM 소켓으로 지정하고) 다시 로드하세요. 요구 사항을 참조하세요.

"데이터베이스에 연결할 수 없습니다"

설치 프로그램의 데이터베이스 단계에서 호스트(일반적으로 localhost 또는 127.0.0.1), 데이터베이스 이름, 사용자 및 비밀번호, 그리고 해당 사용자가 해당 데이터베이스에 대한 권한을 가지고 있는지 다시 확인하세요. 데이터베이스는 이미 존재해야 합니다 — 설치 프로그램은 스키마 자체가 아닌 테이블을 생성합니다.

설치 프로그램이 구성을 쓸 수 없습니다 / "쓰기 불가" 오류

웹 서버는 설치 중에 config/와 storage/에 쓰기 권한이 필요합니다. 해당 디렉토리를 PHP 사용자가 쓸 수 있도록 설정한 다음 다시 시도하세요. 설치 페이지의 권한 안내를 참조하세요.

설치를 완료했지만 /install이 계속 로드됩니다

설치 시 config/installed.php 파일이 기록됩니다. 파일이 없으면 앱은 설치되지 않은 것으로 판단하며, 설치가 완료된 경우 해당 파일이 존재하고 설치 프로그램이 잠겨야 합니다. config/가 쓰기 가능했는지 다시 확인하세요.

사이트는 로드되지만 페이지가 404를 반환합니다

홈 페이지는 작동하지만 다른 모든 URL이 404를 반환한다면, URL 리라이팅이 프론트 컨트롤러에 도달하지 못하는 것입니다.

• Apache — mod_rewrite가 활성화되어 있고 AllowOverride All이 설정되어 있는지 확인하여 번들된 .htaccess가 적용되도록 하세요.
• Nginx — location /이 프론트 컨트롤러로 폴스루되어야 합니다. 예: try_files $uri $uri/ /index.php?$query_string;. 웹 서버 노트는 아키텍처를 참조하세요.

로그인 & 관리자 접근

관리자 로그인을 찾을 수 없습니다

보안을 위해 사용자 정의 관리자 URL을 설정한 경우, 패널은 더 이상 /admin에 없으며 비밀 경로에서만 응답합니다. 데이터베이스 접근 권한이 있다면 settings 테이블에서 복구하세요. 보안을 참조하세요.

이중 인증으로 잠겨 있습니다

인증 앱을 분실한 경우, 데이터베이스에서 사용자의 TOTP를 비활성화하여 (users 테이블의 관련 열) 접근 권한을 복구한 다음 다시 등록하세요. 자세한 내용은 보안을 참조하세요.

업로드 & 미디어

대용량 업로드가 실패하거나 시간 초과됩니다

PHP 제한값 upload_max_filesize와 post_max_size를 높이고, nginx에서 client_max_body_size를 늘리세요. 데모는 높은 client_max_body_size를 통해 수 기가바이트 업로드를 허용합니다. 대용량 파일의 경우 서버에서도 동일하게 설정하세요.

동영상이 재생되지 않습니다

새로 업로드된 동영상은 트랜스코딩이 완료될 때까지 처리 중 상태일 수 있습니다. 포맷이 웹에서 제공 가능한지, 렌디션 파일이 스토리지에 존재하는지, 서버가 .mp4/.webm에 대한 올바른 MIME 타입을 전송하는지 확인하세요. 플레이어를 참조하세요.

썸네일 또는 미리보기가 누락되어 있습니다

썸네일 및 미리보기 생성에는 GD 또는 Imagick 확장이 필요합니다 (비디오 프레임의 경우 FFmpeg도 필요). 설치되어 있는지, 그리고 uploads/가 쓰기 가능한지 확인하세요.

트랜스코딩이 멈춰 있습니다

작업이 대기열에 있고 완료되지 않는 경우:

• 트랜스코딩이 실행되는 곳 (로컬 서버 또는 원격 워커)에 FFmpeg가 설치되어 있는지 확인하세요.
• 원격 트랜스코드 서버를 사용하는 경우, 워커가 실행 중이고 API 키가 관리자에서 구성된 것과 일치하는지 확인하세요.
• 스케줄러가 작동 중인지 확인하세요 (아래 참조) — 작업 디스패치 및 재시도는 pseudo-cron에서 실행됩니다.

예약된 작업이 실행되지 않습니다

pseudo-cron은 페이지 렌더링 시에만 실행됩니다. 조용한 사이트에서는 하트비트가 살아있게 유지합니다 — heartbeat_enabled가 1인지 확인하세요. 비활성화했다면, 다시 활성화하거나 주기적으로 사이트를 방문하는 시스템 cron 항목을 추가하세요.

이메일이 전송되지 않습니다

이메일 & 알림에서 SMTP를 구성하고 내장된 테스트 이메일 보내기 버튼을 사용하여 확인하세요. 테스트가 실패하면 SMTP 호스트/포트/자격 증명을 확인하고 호스트가 아웃바운드 메일을 허용하는지 확인하세요. 전달 가능성을 위해 도메인에 SPF/DKIM을 설정하세요.

성능

대규모 환경에서 빠른 사이트를 위해: OPcache를 활성화하고, PHP에 충분한 메모리를 할당하고, MySQL을 PHP와 같은 네트워크에 유지하고, CTR 재계산 및 기타 예약된 작업을 실행 상태로 유지하세요. TubePress는 대형 라이브러리에 필요한 인덱스와 청크 작업을 함께 제공합니다 — 유지 관리를 참조하세요.

업데이트가 실패합니다

업데이트가 적용되지 않으면 코어 파일이 PHP 사용자에 의해 쓰기 가능한지, PHP 8.2+ 버전을 사용하고 있는지 확인하세요. 업데이트 전에 항상 백업하여 롤백할 수 있도록 하세요. 업데이트를 참조하세요.

여전히 해결되지 않나요?

정확한 오류 메시지와 관련 로그 줄을 수집한 다음, 대시보드 또는 관리자 내 지원 위젯에서 티켓을 열어 주세요. PHP 버전, 웹 서버, 수행한 작업 등 더 많은 정보를 포함할수록 더 빠르게 해결됩니다. 공지 & 지원을 참조하세요.