本指南涵盖了在 Legion Hosting 上运行 alt:V 服务器的资源开发、数据库设置、管理工具、玩家管理、载具和武器管理以及故障排除。有关初始服务器设置、server.toml 配置和连接说明，请参阅 alt:V 服务器设置指南。

---

管理员设置

alt:V 没有内置的管理员系统。管理员功能通过您创建或安装的资源（脚本）来实现。大多数游戏模式会实现自己的管理员系统，包含权限等级、角色和管理员命令。

常见管理员方案

• 数据库角色： 大多数角色扮演和游戏模式框架将管理员角色存储在数据库中。管理员被分配角色（例如 moderator、admin、superadmin），授予不同的权限等级。
• 配置文件管理员： 更简单的设置可以使用配置文件列出管理员的 Steam ID 或 alt:V ID 及其权限等级。
• 控制台命令： GPanel 服务器控制台始终拥有完全访问权限。您可以编写服务器端脚本来接受控制台输入以执行管理操作。

设置管理员资源

1. 选择或开发适合您游戏模式的管理员资源。
2. 通过 Files 选项卡或 SFTP 将资源上传到 resources/ 目录。
3. 将资源名称添加到 server.toml 中的 resources 数组。
4. 配置管理员资源（设置您的管理员 Steam/alt:V ID、权限等级等）。
5. 重启服务器。

---

资源系统

资源是 alt:V 服务器的核心构建模块。每个资源都是一个独立的模块，可以包含服务器端代码、客户端代码或两者兼有。资源使用 JavaScript、TypeScript 或 C# 编写。

资源结构

resources/
  my-resource/
    resource.toml         <-- Resource configuration (required)
    server/
      index.js            <-- Server-side entry point
      utils.js            <-- Additional server-side files
    client/
      index.js            <-- Client-side entry point (runs in player's GTA V)
    shared/
      config.js           <-- Shared code accessible by both server and client

resource.toml 配置

type = "js"
main = "server/index.js"
client-main = "client/index.js"
client-files = ["client/*"]
deps = ["chat"]

字段说明：type（js 或 csharp），main（服务器端入口点），client-main（客户端入口点，在玩家的 GTA V 中运行），client-files（发送给客户端的文件，支持通配符），deps（需要先加载的其他资源）。

---

安装资源

要在服务器上安装预构建的资源：

1. 下载资源文件（通常是一个包含 resource.toml 和脚本文件的文件夹）。
2. 在 GPanel 中停止服务器。
3. 通过 Files 选项卡或 SFTP 将资源文件夹上传到 resources/。
4. 将资源文件夹名称添加到 server.toml 中的 resources 数组：

resources = ["existing-resource", "new-resource"]

5. 如果资源有依赖项，请确保这些依赖项也已安装并列出。
6. 根据资源文档进行配置（配置文件、数据库设置等）。
7. 启动服务器。检查控制台中的资源加载消息和任何错误。

移除资源

1. 停止服务器。
2. 从 server.toml 中的 resources 数组中移除资源名称。
3. 可选择从 resources/ 中删除资源文件夹。
4. 启动服务器。

---

数据库设置

大多数 alt:V 游戏模式需要数据库来存储玩家数据、载具、物品栏和其他持久化信息。alt:V 最常用的两种数据库系统是 MongoDB 和 MySQL/MariaDB。

MongoDB

MongoDB 是一种 NoSQL 文档数据库，常与 JavaScript/TypeScript 资源配合使用。您可以使用 MongoDB Atlas（提供免费套餐）等托管服务或自托管实例。获取您的连接字符串（例如 mongodb+srv://user:[email protected]/mydb）并在资源的配置文件中进行设置。Node.js 资源使用 mongodb npm 包。

MySQL / MariaDB

MySQL 常与 C# 资源和一些 JavaScript 框架配合使用。从托管服务或自托管实例获取数据库，使用连接详细信息（主机、端口、用户名、密码、数据库名称）配置您的资源，并运行所需的 SQL 迁移脚本。

---

玩家管理

alt:V 中的玩家管理通过您的资源来处理。常见操作包括：

识别玩家

alt:V 为每个连接的玩家提供多个标识符：

踢出和封禁

在您的资源中实现踢出和封禁功能：

import alt from "alt-server";

// Kick a player
player.kick("Reason for kick");

// Ban check on connect (store bans in database)
alt.on("playerConnect", (player) => {
    if (isPlayerBanned(player.socialID)) {
        player.kick("You are banned from this server.");
    }
});

---

载具和武器管理

载具和武器通过服务器端脚本进行管理。alt:V 让您完全控制载具和武器的生成、修改和移除。

生成载具

import alt from "alt-server";

// Spawn a vehicle at a position
const vehicle = new alt.Vehicle(
    "sultan",            // Vehicle model name
    0, 0, 72,           // Position (x, y, z)
    0, 0, 0             // Rotation (rx, ry, rz)
);
vehicle.numberPlateText = "LEGION";

给予武器

// Give a weapon to a player
player.giveWeapon(alt.hash("weapon_pistol"), 100, true);

// Remove all weapons
player.removeAllWeapons();

载具持久化

默认情况下，载具仅存在于服务器内存中，重启后会丢失。要在重启后保留载具，请将其数据（型号、位置、改装、所有者）存储在数据库中，并在服务器启动时重新创建。

---

故障排除

资源未加载

• 检查 server.toml 中的资源名称是否与 resources/ 中的文件夹名称完全匹配。
• 验证资源是否有有效的 resource.toml 文件，且 type 和 main 字段正确。
• 检查控制台中资源加载期间的错误消息。脚本中的语法错误会阻止资源启动。
• 确保 deps 中列出的所有依赖项都已安装并加载。
• 验证 server.toml 中加载了正确的模块（JavaScript 使用 js-module，C# 使用 csharp-module）。

玩家无法连接

• 验证服务器正在运行且在 GPanel 中显示为在线。
• 检查玩家是否使用 alt:V 启动器，而非常规 GTA V 启动器。
• 确保 alt:V 服务器分支与玩家使用的分支匹配（release、rc 或 dev）。分支不匹配会阻止连接。
• 如果设置了密码保护，请验证玩家输入的密码是否正确。
• 让玩家尝试使用 IP 和端口直接连接。请参阅 如何查找服务器 IP 和端口。

服务器崩溃

• 检查崩溃前控制台中的错误消息。
• 有问题的资源是导致崩溃的最常见原因。禁用最近添加的资源以隔离问题。
• 确保您的服务器文件是最新的。如需要，可从 Startup 选项卡触发重新安装。
• 资源中的内存泄漏可能导致服务器随时间耗尽 RAM。监控 GPanel 资源图表，查看是否有内存使用量持续增长的情况。

数据库和语音问题

• 验证数据库凭据和连接字符串。对于 MongoDB Atlas，请在网络访问设置中将服务器 IP 加入白名单。
• 检查控制台中的数据库连接错误消息。
• 语音聊天需要在 server.toml 中配置 [voice] 部分，并需要实现语音频道逻辑的资源。仅配置文件只是设置了基础架构。

性能问题

• 分析您的资源中的高开销操作（大量循环、同步数据库调用、过多实体创建）。
• 谨慎使用 alt.setInterval 和 alt.setTimeout。每帧大量计算操作是最常见的性能杀手。
• 监控 GPanel 资源图表的 CPU 和 RAM 使用情况。
• 对于高玩家数量的服务器，考虑升级您的服务器方案。提交支持工单以讨论选项。

---

相关文章

• alt:V 服务器设置指南 — 初始设置、server.toml 配置、语音聊天和连接说明
• 如何查找服务器 IP 和端口
• 如何通过 SFTP 上传文件
• 服务器启动指南 — 在 Legion Hosting 上启动任何游戏服务器的通用指南

---

需要更多帮助？

如果您遇到本指南未涵盖的问题，我们的支持团队随时为您提供帮助。请在 legionhosting.net/submitticket.php 提交工单，并附上您的服务器详细信息、问题描述以及 GPanel 控制台中的相关错误消息。