常见 RedM 服务器问题的故障排除指南，包括许可证密钥错误、服务器浏览器可见性、资源加载失败、客户端连接、数据库问题和性能优化。有关初始设置说明，请参阅我们的 RedM 服务器设置指南。

许可证密钥错误

许可证密钥问题是启动新 RedM 服务器时最常见的问题。以下是典型错误及其解决方案：

"Invalid license key" 或 "Could not authenticate"

原因	解决方案
许可证密钥输入错误或包含多余空格	直接从 Keymaster 复制密钥。删除 GPanel 中 CFX_LICENSE 启动变量或 server.cfg 中 sv_licenseKey 行的任何前导/尾随空白。
IP 地址不匹配	密钥注册的 IP 与服务器实际 IP 不同。前往 Keymaster，检查注册的 IP，并将其更新为 GPanel 中显示的服务器 IP。
在 GPanel 和 server.cfg 中设置了不同的密钥值	确保密钥一致。最好在 GPanel 启动变量中设置，让 egg 处理将其传递给服务器。如果由 GPanel 处理，请删除或注释掉 server.cfg 中的 sv_licenseKey。
Cfx.re 账户问题或密钥被吊销	登录 Keymaster 并验证密钥是否仍然有效。如果旧密钥已被删除或过期，请生成新密钥。
Keymaster 服务暂时不可用	检查 Cfx.re 状态页面 了解服务中断情况。等待后重试。

服务器未出现在浏览器中

如果您的服务器正在运行但玩家在 RedM 服务器浏览器中找不到它：

检查清单

1. 等待至少 5 分钟。 启动后，服务器需要时间向 Cfx.re 主服务器列表注册。新服务器可能需要几分钟才能显示。
2. 验证许可证密钥是否有效。 没有有效的许可证密钥，服务器将不会被列出。检查服务器控制台是否有许可证相关的错误。
3. 检查端点配置。 确保 server.cfg 中的 endpoint_add_tcp 和 endpoint_add_udp 使用正确的端口：

   endpoint_add_tcp "0.0.0.0:30120"
   endpoint_add_udp "0.0.0.0:30120"

   端口必须与 GPanel 中分配的端口匹配。
4. 检查 "sv_master1" 或列表设置。 确保您没有意外将服务器设置为不在列表中显示。配置中不应有 sv_master1 ""（这会禁用主列表注册）。
5. 确认服务器确实在运行。 检查 GPanel 控制台。如果服务器崩溃或停止，它将不会出现在浏览器中。
6. 尝试直接连接。 即使服务器不在浏览器中，直接连接也应该可以工作。让玩家在 RedM 中按 F8 并输入：

   connect YOUR_SERVER_IP:PORT

资源加载失败

在向服务器添加新脚本或框架时，资源错误很常见。以下是最常见的问题：

"Could not find resource [resource_name]"

• 资源文件夹不存在于 resources/ 目录中，或位于错误的位置。
• 文件夹名称与 ensure 中使用的名称不匹配。资源名称区分大小写。
• 修复： 验证资源文件夹是否存在，以及 server.cfg 中的名称是否完全匹配。使用 GPanel 文件管理器或 SFTP 进行检查。

"Failed to load resource [resource_name]: manifest error"

• 资源的 fxmanifest.lua 或 __resource.lua 存在语法错误。
• 清单引用了资源文件夹中不存在的文件。
• 修复： 打开清单文件并检查拼写错误、缺少的逗号或对不存在文件的引用。检查服务器控制台以获取错误的具体行号。

"Error loading script [filename]: [error details]"

• 资源中的 Lua、C# 或 JavaScript 文件存在语法或运行时错误。
• 修复： 阅读控制台中的完整错误消息。它将包含文件名和行号。常见原因包括：
  • 缺少依赖项（必须先加载的另一个资源）
  • 过时的资源与当前 RedM 服务器版本不兼容
  • 资源配置文件中的配置值不正确

资源加载顺序问题

server.cfg 中的资源按其出现顺序加载。如果某个资源依赖于另一个资源（例如 vorp_inventory 依赖于 vorp_core），则依赖项必须先列出：

# Correct order - dependencies first
ensure oxmysql
ensure vorp_core
ensure vorp_inventory
ensure vorp_stores

# Wrong order - will cause errors
# ensure vorp_inventory   <-- depends on vorp_core
# ensure vorp_core        <-- loaded too late

客户端连接问题

当玩家无法连接到您的服务器时：

"Connection timed out" / "Failed to connect"

原因	解决方案
服务器未运行	检查 GPanel 控制台以确认服务器在线且未崩溃。
IP 或端口错误	验证玩家是否使用了 GPanel 中正确的 IP 和端口。参阅 如何查找服务器 IP 和端口。
端点配置错误	确保 server.cfg 中的 endpoint_add_tcp 和 endpoint_add_udp 使用 0.0.0.0:PORT，其中 PORT 与 GPanel 匹配。
服务器已满	检查 sv_maxclients 是否已达上限。如果您的托管计划允许，请增加该值。

"Connection rejected by server"

• 服务器密码： 如果设置了 sv_password，玩家必须输入正确的密码。
• 白名单资源： 如果您启用了白名单资源，玩家必须获得批准后才能连接。
• 封禁： 玩家可能已被封禁。检查您的封禁列表或数据库中的玩家标识符。

客户端连接时崩溃

• 服务器上的某个资源发送了错误数据或存在导致客户端崩溃的客户端脚本错误。
• 修复： 逐个禁用最近添加的资源以找出问题资源。检查客户端连接期间服务器控制台的错误。
• 确保玩家的 RedM 客户端是最新版本。

"Could not download file" 错误

• 服务器正在尝试发送超出传输限制的大文件（例如流式资产），或连接不稳定。
• 修复： 减小流式资产的大小，如果支持的话使用 CDN/外部托管来存放大文件，或让玩家重试连接。

数据库问题（MySQL / oxmysql）

大多数 RedM 角色扮演框架使用 MySQL 进行持久化数据存储。最常用的数据库连接器是 oxmysql。

连接失败错误

如果 oxmysql（或其他 MySQL 连接器）无法连接，请检查以下内容：

# Typical oxmysql connection string in server.cfg
set mysql_connection_string "mysql://user:password@host:3306/database_name?charset=utf8mb4"

错误	解决方案
ECONNREFUSED 或 "Connection refused"	MySQL 服务器未运行、主机/端口错误，或 MySQL 服务器不接受外部连接。验证主机、端口，并确保数据库服务器在线。
ER_ACCESS_DENIED_ERROR	连接字符串中的用户名或密码错误。在数据库托管面板中仔细检查凭据。
ER_BAD_DB_ERROR	数据库名称不存在。首先通过数据库管理面板（phpMyAdmin 等）创建数据库。
ETIMEDOUT	数据库服务器无法访问。检查是否有防火墙规则阻止连接，或数据库主机是否正确。
"Too many connections"	数据库已达到最大连接数限制。这可能是因为资源没有正确关闭连接，或限制设置过低。重启服务器并检查 MySQL 的 max_connections 设置。

缺少表或架构错误

角色扮演框架通常需要在运行之前设置好数据库表：

1. 查看框架的文档或 GitHub 仓库中的 SQL 导入文件（通常命名为 database.sql、schema.sql 或类似名称）。
2. 使用 phpMyAdmin 或 MySQL 客户端将 SQL 文件导入数据库。
3. 某些框架会在首次启动时自动创建表。确保数据库用户具有 CREATE TABLE 权限。

性能问题

如果您的 RedM 服务器出现延迟、低 tick rate 或整体性能不佳：

识别性能问题

检查服务器控制台中的性能警告。RedM 服务器的目标 tick rate 约为每秒 30-64 tick。您可以通过以下方式监控：

• txAdmin 仪表板： 如果 txAdmin 可用，它会显示实时服务器性能指标。
• 服务器控制台： 注意 "slow tick" 或 "resource hitch" 警告。
• resmon 命令： 在服务器控制台（或 F8 控制台）中输入 resmon 1 以启用资源监控器，它显示每个资源的 CPU 时间。

常见性能解决方案

问题	解决方案
特定资源导致 CPU 使用率过高	使用 resmon 1 找出该资源。考虑用更优化的替代方案替换它，或联系资源开发者。
加载的资源过多	每个资源都会消耗服务器资源。审核您的资源列表并移除未使用或冗余的资源。
数据库查询瓶颈	缓慢或未建立索引的数据库查询可能导致服务器卡顿。检查控制台中 oxmysql 的慢查询警告。为频繁查询的列添加索引。
高玩家数导致延迟	将 sv_maxclients 降低到服务器硬件能够承受的水平。考虑升级托管计划以获取更多资源。
OneSync 实体限制	生成过多的实体（NPC、载具、物体）会降低性能。使用能清理未使用实体的资源。
内存泄漏	某些编码不佳的资源会随时间泄漏内存。在 GPanel 中监控服务器 RAM 使用情况。定期重启服务器（每 6-12 小时）可以缓解此问题。

建议做法

• 安排自动重启，每 6-12 小时使用 GPanel 的计划功能或 txAdmin 清除累积的内存和实体问题。
• 保持资源更新以受益于性能修复和优化。
• 避免功能重复 — 不要运行两个执行相同功能的资源（例如两个天气系统）。
• 在测试服务器上测试新资源（或在低玩家数量时），然后再部署到主服务器。
• 定期监控服务器指标，通过 GPanel 或 txAdmin 及早发现问题。

一般故障排除技巧

1. 始终阅读服务器控制台输出。 几乎每个错误都会在控制台中包含一条消息，告诉您出了什么问题以及在哪里。
2. 更改配置后重启服务器。 大多数对 server.cfg 的更改需要完全重启服务器才能生效。
3. 逐个禁用资源以隔离问题。在 server.cfg 中使用 # 注释掉 ensure 行。
4. 在更改前保留备份。在进行重大更新前下载您的 server.cfg 和数据库。
5. 查看 Cfx.re 论坛和文档，访问 docs.fivem.net 获取适用于 FiveM 和 RedM 的官方文档。
6. 验证资源兼容性。为旧版本构建的资源可能无法在当前 RedM 版本上运行。

相关文章

• RedM 服务器设置指南 — 许可证密钥、server.cfg 配置、资源管理和连接。
• 如何查找服务器 IP 和端口
• 如何通过 SFTP 上传文件
• 新服务器入门指南

需要帮助？

仍然遇到 RedM 服务器问题？提交工单，并附上服务器控制台中的任何错误消息。我们的团队将帮助您诊断和解决问题。