Agency Phone 安装指南：完整 FiveM 安装与配置

本指南引导您完成在FiveM服务器上安装和配置Agency Phone的完整过程。无论您运行QBCore、ESX还是完全自定义框架，这里都有您需要的一切，从前提条件到首次启动再到配置微调。完整技术参考请参见官方文档： docs.agencyg.de/phone.

先决条件

安装Agency Phone之前，请确保您的服务器环境满足以下要求：

• FiveM 服务器制品： 版本 6633 或更新版本（推荐：始终保持 artifacts 最新）
• 数据库: MySQL 5.7+ 或 MariaDB 10.3+，配合 oxmysql (推荐)或 mysql-async 已安装并配置
• CFX Keymaster: 你的服务器许可证密钥必须在 keymaster.fivem.net
• 框架（可选）： 如果您想要更深层的框架集成，选择 QBCore 或 ESX。独立运行不需要。
• 当前激活的Agency Phone购买： 资源通过 CFX 资产门户在购买后交付

步骤 1：购买并下载

完成购买后，请在 Agency Scripts shop，你的许可证会自动注册到你的CFX账户。下载方法：

1. 登录到 keymaster.fivem.net 带有与你购买关联的CFX账户。
2. 前往 已授权资产 并定位 agency-phone.
3. 点击 下载 获取最新发布的压缩包。
4. 如果您购买了 QBCore 或 ESX 桥接，也请下载 agency-phone-bridge-qb 或 agency-phone-bridge-esx 来自同一列表。

步骤 2：文件夹结构

解压 zip 文件。您的 resources 提取后目录应如下所示：

resources/
  [agency]/
    agency-phone/
      client/
      server/
      html/
      config.lua
      fxmanifest.lua
    agency-phone-bridge-qb/   (QBCore only)
      client/
      server/
      fxmanifest.lua

该 [agency] 文件夹是一个类别文件夹（方括号告诉 FiveM 它是资源组）。这不是严格要求，您可以将 agency-phone 直接在 resources/，但使用类别文件夹可保持整洁。

步骤 3：数据库设置

Agency Phone creates its own database tables on first launch using the auto-migration system built into oxmysql. You do not need to manually import any SQL files. Simply ensure your database connection is configured in server.cfg:

# server.cfg, database connection string (oxmysql example)
set mysql_connection_string "mysql://user:password@localhost/fivem_db?charset=utf8mb4"

首次服务器启动时，Agency Phone将创建以下表： phone_contacts, phone_messages, phone_calls, phone_gallery, phone_social_posts，和 phone_settings. 如果你使用的是全新数据库，表会自动创建。如果从另一个电话脚本迁移，确保现有架构中没有名称冲突。

步骤 4：server.cfg 条目

为您的...添加以下确保行 server.cfg. 加载顺序重要，oxmysql 必须先于 Agency Phone 加载：

# Dependencies
ensure oxmysql

# Agency Phone (standalone or with framework bridge)
ensure agency-phone

# Only add if using QBCore bridge:
# ensure qb-core
# ensure agency-phone-bridge-qb

# Only add if using ESX bridge:
# ensure es_extended
# ensure agency-phone-bridge-esx

如果您运行QBCore或ESX，确保框架本身已加载 之前 桥接资源，如上面注释所示。独立核心（agency-phone)应始终在任何桥接资源之前确保。

步骤 5：配置（config.lua）

打开 agency-phone/config.lua 在文本编辑器中。这是主要配置文件，控制手机行为的几乎所有方面。以下是最重要设置的详细讲解：

Config = {}

-- ============================================================
-- FRAMEWORK
-- "standalone" | "qbcore" | "esx"
-- ============================================================
Config.Framework = "standalone"

-- ============================================================
-- PHONE NUMBERS
-- ============================================================
-- Format string for auto-generated numbers. X = random digit.
Config.PhoneNumberFormat = "555-XXXX"

-- Allow players to pay in-game currency to change their number
Config.AllowNumberChange = true
Config.NumberChangeCost   = 500  -- default currency (adjust per framework)

-- ============================================================
-- APPS: enable/disable individual apps
-- ============================================================
Config.EnableBankingApp   = true
Config.EnableSocialApp    = true
Config.EnableGPSApp       = true
Config.EnableCameraApp    = true
Config.EnableMDT          = false   -- set true only for LEO servers
Config.EnableNotesApp     = true

-- ============================================================
-- MDT (only relevant when Config.EnableMDT = true)
-- ============================================================
-- Jobs that can access the MDT app
Config.MDTJobs = { "police", "sheriff", "highway_patrol" }

-- ============================================================
-- SOCIAL MEDIA
-- ============================================================
-- Rename the social app to match your server's lore
Config.SocialAppName = "Chirper"
-- Max post length in characters
Config.SocialPostMaxLength = 280

-- ============================================================
-- ENCRYPTED MESSAGING
-- Requires players to hold a specific inventory item
-- ============================================================
Config.EncryptedChat     = false
Config.EncryptedChatItem = "burner_phone"

-- ============================================================
-- UI
-- ============================================================
-- Default theme: "dark" or "light"
Config.DefaultTheme = "dark"
-- Notification display duration in milliseconds
Config.NotificationDuration = 5000
-- Phone open keybind (FiveM key name)
Config.PhoneKey = "F1"

QBCore 专用说明

使用 QBCore 桥接时（Config.Framework = "qbcore"），银行应用自动从 QBCore 经济系统拉取余额和交易数据。基于职业的应用权限（如 MDT 访问）使用 QBCore 原生职业系统，除添加职业名称外无需额外配置 Config.MDTJobs. 电话号码按角色存储，并绑定到 QBCore 角色标识符。

ESX特定说明

使用 ESX 桥接 (Config.Framework = "esx"），银行应用连接到 ESX 账户（默认： bank）。如果您的 ESX 设置使用自定义账户名称，请在桥接自身配置中进行设置。 config.lua. ESX工作等级被尊重以访问MDT，只需列出工作名称；该工作内所有等级自动获得访问权限，除非你在桥接配置中设置了等级限制。

步骤 6：首次启动验证

启动你的服务器并观察控制台输出。成功加载 Agency Phone 如下所示：

[agency-phone] Database tables verified/created, OK
[agency-phone] Framework: standalone
[agency-phone] Loaded 0 contacts, 0 messages (fresh install)
[agency-phone] Resource started successfully, v2.x.x

如果您在此阶段看到错误，请检查下面的故障排除部分。服务器运行后，连接客户端并按下 F1 (或您配置的手机键)打开手机。首次使用时，如果玩家尚未分配号码，手机将提示玩家设置号码。

常见错误及修复

错误：“oxmysql未启动”

这意味着oxmysql未在你的 server.cfg. 移动 ensure oxmysql 上面一行 ensure agency-phone 并重启服务器。

错误：“创建表phone_contacts失败：表已存在”

这是一个警告，不是致命错误，意味着您正在覆盖现有数据库。现有数据会被保留。您可以安全忽略此警告。如果想要干净安装，请手动删除 phone_* 请先查看数据库中的表。

按键时电话界面未打开

首先检查资源是否在服务器控制台启动无误。其次确认无其他资源使用相同快捷键（默认：F1）。您可在 config.lua 在 Config.PhoneKey第三，检查NUI焦点冲突，如果另一个资源同时捕获了NUI焦点，电话可能无法正确接收按键。

银行应用显示$0 / 余额为空

如果您运行独立模式，银行应用默认使用内部钱包。要连接QBCore或ESX经济系统，必须使用相应桥接资源并设置 Config.Framework 正确。如果桥接已确保但余额仍显示为零，请验证玩家的角色在电话初始化前已完全加载到框架中（server.cfg 中的框架加载顺序）。

警察无法看到 MDT 应用

确认 Config.EnableMDT = true 在config.lua中，并且玩家当前的职业名称必须与其中一条条目完全匹配 Config.MDTJobs. 职业名称匹配区分大小写。请使用框架职业配置中定义的精确职业名称字符串。

额外配置选项

Agency Phone has many more configuration options beyond what is covered in this guide. Some of the most useful advanced settings include:

• Config.MaxContactsPerPlayer，限制玩家可存储的联系人数量（默认：无限制）
• Config.GPSUpdateInterval，玩家位置标记在共享GPS上的更新频率（毫秒）。
• Config.SocialPostCooldown，防止垃圾信息的社交媒体发帖最短间隔时间（秒）
• Config.AllowAnonCalls，玩家是否可以拨打隐藏号码的电话。
• Config.CameraPhotoQuality，NUI 截图质量等级（1-10，影响游戏内图库图片大小）

带有所有选项的完整注释配置文件可在官方文档中获得， docs.agencyg.de/phone. 文档随每次发布更新，包含设置变更时的版本特定迁移说明。

保持 Agency Phone 更新

当发布新版本时，您将在 CFX keymaster 账户收到通知。更新时，从 Granted Assets 页面下载新压缩包，解压并替换现有文件。 agency-phone 服务器上的文件夹。更新实时服务器前务必阅读更新日志，它列出了需要注意的 config.lua 键更改。更新不会删除您的数据库和现有玩家数据。