FiveM 整合指南

本指南將教你如何在 FiveM 伺服器上整合 ScriptVerify 授權驗證系統。

📋 前置準備

在開始之前，請確保你已經：

1. 擁有 ScriptVerify 系統的授權金鑰 (License Key)
2. 知道你的 FiveM 伺服器 IP 位址
3. 已在管理後台為授權金鑰綁定正確的 IP 和腳本授權
4. 擁有 FiveM 伺服器的檔案存取權限

🚀 快速開始

步驟 1: 下載 FiveM Resource

1. 從管理員檔案中心下載 fivem_resource 資料夾
2. 或從 Protected Scripts 頁面下載特定腳本的 Resource

下載的資料夾結構應該如下：

fivem_resource/
├── fxmanifest.lua      # Resource 配置檔
├── sv_config.lua       # 授權配置檔（需要修改）
├── server.lua          # 驗證邏輯（自動生成）
└── script/
    └── main.lua        # 受保護的腳本內容

步驟 2: 配置授權資訊

開啟 sv_config.lua 檔案，填入你的授權資訊：

sv_config = {
    -- 你的授權金鑰（必填）
    licenseKey = "YOUR_LICENSE_KEY_HERE",

    -- 腳本名稱（必填，需與後台一致）
    SCRIPT_NAME = "your_script_name",

    -- 選擇 server.lua 版本（選填）
    serverLuaVersion = "latest",  -- 可選: "latest", "v1.0.0", "v2.0.0" 等
}

配置說明：

licenseKey

• 從管理後台的「授權管理」頁面取得
• 格式範例："ISRUP2D@gFNZ4rIa"
• 請確保授權金鑰已在後台綁定此伺服器的 IP

SCRIPT_NAME

• 必須與後台「Protected Scripts」中上傳的腳本名稱完全一致
• 區分大小寫
• 範例："sun_carry", "advanced_hud", "police_system"

serverLuaVersion (可選)

• 控制使用哪個版本的驗證邏輯
• "latest": 使用最新版本（預設）
• "v1.0.0": 使用指定版本（適合需要穩定環境的伺服器）
• 詳見 版本管理指南

步驟 3: 部署到 FiveM 伺服器

1. 上傳 Resource

   # 將整個資料夾複製到 FiveM 伺服器的 resources 目錄
   # 路徑範例：
   server-data/resources/[your_category]/your_script_name/

2. 修改 server.cfg

   # 在 server.cfg 中啟動 resource
   ensure your_script_name
   
   # 或使用 start 命令
   start your_script_name

3. 重啟伺服器

   # 重新啟動 FiveM 伺服器
   # 或使用控制台命令
   refresh
   restart your_script_name

驗證流程解析

自動驗證機制

當 FiveM 伺服器啟動時，驗證流程如下：

graph TD
    A[FiveM 伺服器啟動] --> B[讀取 sv_config.lua]
    B --> C[發送驗證請求到 API]
    C --> D{驗證成功?}
    D -->|是| E[下載並執行 server.lua]
    E --> F[腳本正常運行]
    D -->|否| G[顯示錯誤訊息]
    G --> H[腳本無法啟動]

    F --> I[定期重新驗證]
    I --> D

驗證請求內容

-- server.lua 會自動發送以下資訊進行驗證
{
    "linesceKey": "YOUR_LICENSE_KEY",
    "serverIP": "123.456.789.012",
    "scriptName": "your_script_name",
    "serverLuaVersion": "latest"
}

API 驗證回應

成功回應：

{
    "status": "success",
    "message": "License verified successfully",
    "script_content": "-- 動態生成的腳本內容..."
}

失敗回應範例：

{
    "detail": "License key not found"
}

{
    "detail": "Server IP mismatch. Expected: 123.456.789.012, Got: 111.222.333.444"
}

{
    "detail": "Script not authorized for this license"
}

安全機制

IP 綁定驗證

• 每個授權金鑰綁定特定的伺服器 IP
• 驗證時會比對請求來源 IP 與授權 IP
• IP 不符則驗證失敗

如何更新 IP：

1. 登入管理後台
2. 進入「授權管理」
3. 點擊「編輯」按鈕
4. 更新 IP 位址
5. 新 IP 可能需要 3-5 分鐘才能生效（快取更新時間）

腳本授權控制

• 授權金鑰必須擁有該腳本的使用權限
• 管理員可在後台新增或移除腳本授權
• 未授權的腳本無法通過驗證

如何新增腳本授權：

1. 進入「授權管理」
2. 選擇目標授權
3. 點擊「新增腳本」
4. 選擇要授權的腳本

動態腳本載入

• 實際腳本內容不存在於客戶端
• 驗證成功後才從伺服器動態取得
• 使用 Lua 的 load() 函數執行
• 驗證失敗則腳本無法執行

進階配置

自訂 API 端點

如果你使用自架的驗證伺服器，需要修改 server.lua：

-- 在 server.lua 頂部找到並修改 API_URL
local API_URL = "https://your-domain.com/verify"

多腳本配置

如果一個 Resource 包含多個受保護的腳本：

-- sv_config.lua
sv_config = {
    scripts = {
        {
            licenseKey = "LICENSE_KEY_1",
            SCRIPT_NAME = "script_one",
            serverLuaVersion = "latest"
        },
        {
            licenseKey = "LICENSE_KEY_2",
            SCRIPT_NAME = "script_two",
            serverLuaVersion = "v1.0.0"
        }
    }
}

注意：需要自行修改 server.lua 以支援多腳本配置

離線模式（開發用）

僅用於開發測試，生產環境絕不可使用！

-- 在 server.lua 中添加離線模式標記
local OFFLINE_MODE = false  -- 設為 true 啟用離線模式

if OFFLINE_MODE then
    print("^3[WARNING] Running in OFFLINE MODE - For development only!^0")
    -- 跳過驗證，直接載入本地腳本
end

控制台輸出說明

成功啟動

[ScriptVerify] License verification successful
[ScriptVerify] Script: sun_carry
[ScriptVerify] Version: latest
[ScriptVerify] Server protected by ScriptVerify

驗證失敗

[ScriptVerify]  License verification failed
[ScriptVerify] Error: Server IP mismatch
[ScriptVerify] Expected: 123.456.789.012
[ScriptVerify] Got: 111.222.333.444

網路錯誤

[ScriptVerify]  Failed to connect to verification server
[ScriptVerify] Error: timeout
[ScriptVerify] Please check your network connection

常見問題排解

問題 1: 驗證失敗 - IP 不符

症狀：

Error: Server IP mismatch

原因：

• 伺服器 IP 已變更
• 使用 Proxy/CDN 導致 IP 被轉換
• 授權金鑰綁定錯誤的 IP

解決方法：

1. 確認伺服器當前真實 IP（可使用 curl ifconfig.me）
2. 在管理後台更新授權金鑰的綁定 IP
3. 等待 3-5 分鐘讓快取更新
4. 重啟 FiveM Resource

問題 2: 授權金鑰不存在

症狀：

Error: License key not found

原因：

• 授權金鑰輸入錯誤
• 授權已被刪除或過期

解決方法：

1. 檢查 sv_config.lua 中的授權金鑰是否正確
2. 確認授權金鑰在後台仍然存在
3. 注意大小寫和特殊字元

問題 3: 腳本未授權

症狀：

Error: Script not authorized for this license

原因：

• 該授權金鑰沒有此腳本的使用權限
• 腳本名稱拼寫錯誤

解決方法：

1. 確認 SCRIPT_NAME 與後台完全一致
2. 在後台為授權金鑰新增該腳本的授權
3. 檢查是否有大小寫差異

問題 4: 無法連接到驗證伺服器

症狀：

Failed to connect to verification server

原因：

• 網路連線問題
• 防火牆封鎖
• API 伺服器離線

解決方法：

1. 檢查伺服器網路連線
2. 確認防火牆規則允許對外連線
3. 測試 API 端點是否可訪問：

   curl -X POST https://your-api-url.com/verify

問題 5: 版本不存在

症狀：

Warning: Requested version v2.0.0 not found, falling back to Firebase Storage

原因：

• 指定的版本不存在
• 版本號輸入錯誤

解決方法：

1. 檢查可用版本列表（在管理後台的版本管理中）
2. 修改 sv_config.lua 使用正確的版本號
3. 或使用 "latest" 自動使用最新版本

📈 監控與維護

檢查驗證日誌

在管理後台的「驗證日誌」頁面可以查看：

• 每次驗證請求的時間
• 驗證成功/失敗狀態
• 失敗原因詳細資訊
• IP 位址比對結果

定期檢查項目

1. 每週：

   • 檢查驗證日誌是否有異常失敗
   • 確認伺服器 IP 沒有變更

2. 每月：

   • 查看授權金鑰使用狀況
   • 清理不再使用的授權

3. 更新時：

   • 查看 版本管理 了解新版本變更
   • 決定是否更新 serverLuaVersion

實戰案例

案例 1: 單一腳本部署

場景： 你購買了一個攜帶系統腳本 sun_carry

步驟：

1. 管理員上傳腳本到 Protected Scripts
2. 創建授權金鑰並綁定你的伺服器 IP
3. 為授權金鑰新增 sun_carry 腳本授權
4. 你下載 fivem_resource 資料夾
5. 修改 sv_config.lua:

   sv_config = {
       licenseKey = "ISRUP2D@gFNZ4rIa",
       SCRIPT_NAME = "sun_carry",
       serverLuaVersion = "latest"
   }

6. 上傳到 FiveM 伺服器並啟動
7. 驗證成功，腳本開始運行

案例 2: 版本回退

場景： 更新到 v2.0.0 後發現不穩定，需要回退到 v1.0.0

步驟：

1. 停止 FiveM Resource
2. 修改 sv_config.lua:

   sv_config = {
       licenseKey = "ISRUP2D@gFNZ4rIa",
       SCRIPT_NAME = "sun_carry",
       serverLuaVersion = "v1.0.0"  -- 從 latest 改為 v1.0.0
   }

3. 重啟 Resource
4. 系統自動載入 v1.0.0 版本

案例 3: IP 更換

場景： 伺服器搬遷，IP 從 123.456.789.012 變更為 111.222.333.444

步驟：

1. 登入管理後台
2. 進入「授權管理」
3. 找到對應授權，點擊「編輯」
4. 更新 IP 為 111.222.333.444
5. 等待 3-5 分鐘（快取更新時間）
6. 重啟 FiveM Resource
7. 驗證成功

🔗 相關文件

• 授權管理 - 了解如何管理授權金鑰
• 版本管理 - 學習版本控制系統
• Protected Scripts - 腳本保護機制說明
• 客戶檔案中心 - 下載授權的檔案

最佳實踐

建議做法

1. 使用版本鎖定： 生產環境建議使用固定版本號而非 latest
2. 備份配置： 保存一份 sv_config.lua 的備份
3. 測試環境： 在測試伺服器先測試新版本再部署到正式環境
4. 監控日誌： 定期查看驗證日誌確保系統正常運作
5. 文件紀錄： 記錄每次版本更新和配置變更

避免做法 d

1. 不要分享授權金鑰： 每個授權金鑰綁定特定 IP，分享無效
2. 不要修改 server.lua： 除非你完全理解驗證機制
3. 不要繞過驗證： 這會違反授權條款且可能導致法律問題
4. 不要忽略錯誤： 驗證失敗必定有原因，應該排查而非忽略

📞 需要協助？

如果遇到本文件未涵蓋的問題：

1. 查看 常見問題
2. 檢查 [驗證日誌] 了解詳細錯誤資訊
3. 聯繫系統管理員或技術支援

** 恭喜！你已經完成 FiveM 整合設定。**

記得定期檢查更新和維護授權狀態，確保腳本穩定運行。