本指南涵盖最常见的 FiveM 服务器问题的解决方案 — TXAdmin 访问问题、CFX 许可证密钥错误、数据库连接失败、服务器崩溃、玩家连接问题和资源无法加载。有关初始服务器设置，请参阅 FiveM 服务器设置指南。
通用故障排除提示： 请始终先检查 GPanel 控制台输出和 TXAdmin 日志。大多数错误会产生明确的信息指向原因。
TXAdmin 无法加载或无法访问
- 在 GPanel 中确认服务器正在运行 — TXAdmin 仅在 FiveM 服务器进程活跃时启动。
- 在 GPanel 控制台中查看 TXAdmin URL 和端口。TXAdmin 端口与游戏端口不同。
- 确保您使用的是
http://而不是https://— 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资源，并且ensure oxmysql在 server.cfg 中出现在任何需要数据库的资源 之前。 - 如果您的密码包含
@、#或%等特殊字符，请在连接字符串中进行 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中的端口匹配。端口不匹配将导致无法连接。
服务器未在浏览器中显示？ 新服务器可能需要 5-15 分钟才能出现在 FiveM 服务器列表中。在此期间请使用直接连接（
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 中的性能指标（tick 时间、玩家数量、内存使用量）。
- 健康的 FiveM 服务器应将服务器 tick 时间（也称为 "hitch"）保持在 20ms 以下。持续超过此值的峰值表示某个资源使用了过多的处理时间。
- 使用 TXAdmin 的 Resources 页面来识别哪些资源消耗了最多的服务器时间。
- 移除或替换优化不佳的资源。来自未知来源的免费资源通常是性能问题的原因。
- 如果达到服务器计划的内存或 CPU 限制，请减少已加载资源的数量。
获取帮助
如果您已尝试上述解决方案但仍然遇到问题：
- 从 GPanel 控制台或 TXAdmin 日志中复制 完整的错误信息。
- 记录您已经尝试过的故障排除步骤。
- 在 https://legionhosting.net/submitticket.php 提交工单并附上这些信息。我们的团队将尽快为您提供帮助。
