이 가이드는 가장 일반적인 FiveM 서버 문제 — TXAdmin 접근 문제, CFX 라이선스 키 오류, 데이터베이스 연결 실패, 서버 크래시, 플레이어 연결 문제, 리소스 로딩 실패 — 에 대한 해결책을 다룹니다. 초기 서버 설정은 FiveM 서버 설정 가이드를 참조하세요.
일반 문제 해결 팁: 항상 GPanel 콘솔 출력과 TXAdmin 로그를 먼저 확인하세요. 대부분의 오류는 원인을 가리키는 명확한 메시지를 출력합니다.
TXAdmin이 로드되지 않거나 접근할 수 없음
- GPanel에서 서버가 실행 중인지 확인하세요 — TXAdmin은 FiveM 서버 프로세스가 활성화되어 있을 때만 시작됩니다.
- GPanel 콘솔에서 TXAdmin URL과 포트를 확인하세요. TXAdmin 포트는 게임 포트와 다릅니다.
https://가 아닌http://를 사용하고 있는지 확인하세요 — TXAdmin은 기본적으로 SSL을 사용하지 않습니다.- TXAdmin이 이전에는 작동했지만 로드되지 않는다면, GPanel에서 서버를 재시작해 보세요.
- 브라우저 캐시를 지우거나 시크릿/비공개 창을 사용해 보세요.
TXAdmin 비밀번호를 잊으셨나요? 로그인할 수 없는 경우, TXAdmin 프로필 데이터를 삭제하고 설정 마법사를 다시 실행해야 할 수 있습니다. GPanel Files 탭에서 TXAdmin의 데이터 디렉터리를 확인하고 프로필 파일을 제거한 다음, 서버를 재시작하세요.
CFX 라이선스 키 오류
| 오류 메시지 | 원인 | 해결책 |
|---|---|---|
Invalid license key |
키가 잘못 복사되었거나 추가 공백이 있음 | Keymaster로 이동하여 키가 활성 상태인지 확인하고, 주의 깊게 다시 복사하세요. GPanel Startup 변수와 server.cfg의 sv_licenseKey 양쪽 모두에 붙여넣으세요. |
License key already in use |
키가 다른 서버 IP에 등록되어 있음 | 각 키는 한 번에 하나의 서버에서만 사용할 수 있습니다. Keymaster에서 기존 키를 취소하고 현재 서버 IP로 새 키를 생성하세요. |
Unable to verify license key |
Cfx.re 인증 서버가 일시적으로 사용 불가능함 | 몇 분 기다린 후 서버를 재시작하세요. 장애 발생 여부는 status.cfx.re에서 확인하세요. |
팁: 키가 GPanel Startup 변수와
server.cfg(sv_licenseKey) 양쪽 모두에 설정되어 있는지 확인하세요. 구성에 따라 서버가 둘 중 하나에서 키를 읽을 수 있습니다.
데이터베이스 연결 오류
| 오류 메시지 | 원인 | 해결책 |
|---|---|---|
Connection refused 또는 ETIMEDOUT |
잘못된 데이터베이스 호스트 또는 포트 | GPanel Databases 탭에서 데이터베이스 호스트 주소와 포트를 다시 확인하세요. localhost나 127.0.0.1을 사용하지 마세요. |
Access denied |
잘못된 사용자 이름 또는 비밀번호 | 오타를 방지하기 위해 GPanel에서 자격 증명을 직접 복사하세요. 비밀번호는 대소문자를 구분합니다. |
Unknown database |
데이터베이스 이름이 일치하지 않음 | 연결 문자열의 데이터베이스 이름이 GPanel에 표시된 것과 정확히 일치하는지 확인하세요. |
추가 데이터베이스 문제 해결 단계:
- oxmysql을 사용하는 경우,
resources/폴더에oxmysql리소스가 있는지, 그리고 데이터베이스를 필요로 하는 모든 리소스 앞에 server.cfg에ensure oxmysql이 나타나는지 확인하세요. - 비밀번호에
@,#,%와 같은 특수 문자가 포함된 경우, 연결 문자열에서 URL 인코딩하세요(예:@는%40이 됩니다). - 연결 문자열에 누락되거나 추가된 문자가 있는지 테스트하세요 — 잘못 배치된 문자 하나라도 실패를 유발합니다.
localhost를 사용하지 마세요. 데이터베이스 서버는 게임 서버와 별개입니다. 항상 GPanel Databases 탭에 표시된 전체 호스트 주소를 사용하세요.
시작 시 서버 크래시
- GPanel 콘솔에서 오류 메시지를 확인하세요. 일반적인 원인으로는 누락되거나 잘못 구성된
server.cfg, 잘못된 CFX 라이선스 키, 또는 손상된 리소스가 있습니다. - server.cfg에서 커스텀 리소스를 주석 처리하여(각
ensure줄 앞에#추가) 비활성화한 후 재시작해 보세요. 문제가 되는 리소스를 식별하기 위해 하나씩 다시 추가하세요. endpoint_add_tcp와endpoint_add_udp의 포트가 GPanel에서 할당된 포트와 일치하는지 확인하세요.
# Comment out resources to isolate the problem
#ensure suspicious-resource
#ensure another-resource
# Keep core resources enabled
ensure mapmanager
ensure spawnmanager
ensure sessionmanager
ensure hardcap
ensure chat
문제가 되는 리소스를 찾기 위한 이진 탐색: 리소스가 많은 경우, 하나씩 하는 대신 한 번에 절반씩 주석 처리하세요. 이렇게 하면 문제를 훨씬 빠르게 좁힐 수 있습니다.
플레이어가 연결할 수 없음
- GPanel에서 서버가 Running으로 표시되는지 확인하세요.
- IP와 포트를 확인하세요 — 플레이어는 TXAdmin 포트가 아닌 게임 포트를 사용해야 합니다.
sv_maxclients가 0이나 비정상적으로 낮은 숫자로 설정되어 있지 않은지 확인하세요.- 서버 비밀번호(server.cfg의
sv_password)를 사용하는 경우, 플레이어가 이를 알고 있는지 확인하세요. - 플레이어는 FiveM 클라이언트가 설치되어 있어야 합니다 — 일반 GTA V 런처로는 연결할 수 없습니다.
- GPanel Network 탭을 확인하고
endpoint_add_tcp와endpoint_add_udp의 포트가 일치하는지 확인하세요. 불일치 시 연결이 차단됩니다.
서버가 브라우저에 나타나지 않나요? 새 서버는 FiveM 서버 목록에 나타나기까지 5~15분이 걸릴 수 있습니다. 그동안에는 직접 연결(
IP:PORT)을 사용하세요. 또한 sv_licenseKey가 유효한지 확인하세요.
리소스가 로드되지 않음
- 리소스 폴더가
resources/디렉터리(또는 적절한 하위 폴더) 안에 있는지 확인하세요. - 폴더 이름이 server.cfg의
ensure줄과 정확히 일치하는지 확인하세요(대소문자 구분). - 각 리소스는 유효한
fxmanifest.lua(또는 이전 버전의__resource.lua)를 포함해야 합니다. 이 파일이 없으면 리소스가 로드되지 않습니다. - TXAdmin 또는 GPanel 콘솔에서 해당 리소스와 관련된 오류 메시지를 확인하세요. 일반적인 오류로는 누락된 종속성이나 Lua 구문 오류가 있습니다.
- 리소스가 프레임워크(ESX, QBCore)를 필요로 하는 경우, server.cfg에서 해당 리소스보다 먼저 프레임워크가 로드되는지 확인하세요.
- 리소스가 데이터베이스를 필요로 하는 경우, MySQL 리소스(oxmysql, mysql-async)가 로드되어 있고 데이터베이스 연결이 작동하는지 확인하세요.
폴더 구조를 확인하세요. 흔한 실수 중 하나는 리소스를 업로드한 후
resources/my-resource/my-resource/fxmanifest.lua처럼 이중으로 중첩된 폴더가 되는 것입니다. 매니페스트는 리소스 폴더 바로 안에 있어야 합니다: resources/my-resource/fxmanifest.lua.
서버 성능 문제
- TXAdmin을 열고 Dashboard에서 성능 지표(틱 시간, 플레이어 수, 메모리 사용량)를 확인하세요.
- 정상적인 FiveM 서버는 서버 틱 시간("hitch"라고도 함)을 20ms 미만으로 유지해야 합니다. 이를 초과하는 지속적인 스파이크는 리소스가 너무 많은 처리 시간을 사용하고 있음을 나타냅니다.
- TXAdmin Resources 페이지를 사용하여 어떤 리소스가 가장 많은 서버 시간을 소비하는지 식별하세요.
- 최적화가 잘 되지 않은 리소스를 제거하거나 교체하세요. 출처가 불분명한 무료 리소스가 성능 문제의 원인인 경우가 많습니다.
- 서버 요금제의 메모리 또는 CPU 한도에 도달하고 있다면 로드된 리소스의 수를 줄이세요.
도움 받기
위의 해결책을 시도했지만 여전히 문제가 발생하는 경우:
- GPanel 콘솔 또는 TXAdmin 로그에서 전체 오류 메시지를 복사하세요.
- 이미 시도한 문제 해결 단계를 기록하세요.
- 이 정보와 함께 https://legionhosting.net/submitticket.php에서 지원 티켓을 여세요. 저희 팀이 최대한 빠르게 도와드리겠습니다.
