База данных и мост

Поддерживаемые запросы чтения#

Подключение включено по умолчанию для каждого сервера и не требует строки в server.cfg. Чтобы отключить его для одного сервера, откройте сервер в разделе серверов и нажмите «Disable connection» на карточке Tosun Connect; там же его можно включить снова. С set tosun_db_bridge_manual "1" в server.cfg значения tosun_db_bridge_enabled и tosun_db_bridge_money_write читаются из server.cfg, как раньше, и каждое выключено, пока не задано "1". Если старое полное зеркало включено намеренно (ts.panelMirror.enabled = true в configs/anticheat_config.lua), мост автоматически остаётся выключенным, чтобы зеркало продолжало работать. Поддерживаемые схемы QBCore/ESX предоставляют выбранные данные игроков, инвентаря, транспорта и журналов. Это не полный обозреватель базы.

Ограниченные запросы и изменение баланса#

В простое HTTPS-опрос панели выполняется примерно раз в 10 секунд без запросов к игровой базе. До 25 результатов на страницу, одна задача одновременно. Изменение баланса онлайн (установка из панели суммы наличных или банка у персонажа в сети) включено по умолчанию. Им могут пользоваться пользователи панели с ролью admin или owner (право на экономику). Персонаж должен быть в сети, а ожидаемый текущий баланс должен совпадать; иначе возвращается stale_balance и ничего не меняется. Перед отправкой панель показывает сводку для подтверждения, каждый запрос записывается в журнал аудита. Операция устанавливает итоговую сумму, а не прибавляет к ней. Неясный результат никогда не повторяется автоматически; сначала проверьте баланс в игре. Чтобы остановить чтение и изменение баланса для сервера, нажмите «Disable connection» на карточке Tosun Connect. Чтобы оставить чтение без изменения баланса, используйте ручной режим: set tosun_db_bridge_manual "1" и set tosun_db_bridge_enabled "1", без set tosun_db_bridge_money_write "1".

Подключение через игровой сервер#

Мост использует существующий oxmysql. Панель передаёт поддерживаемые задания через HTTPS-очередь; игровой сервер выполняет их локально и возвращает выбранные данные. Не нужно копировать пароль MySQL на сайт или открывать порт базы в интернет.

1. Подключение по умолчанию включено для каждого сервера; начиная с tosun-ac 9.6.14 включать его не нужно. Чтобы отключить его на одном сервере: Серверы → сервер → карточка Tosun Connect → «Disable connection». Если старое полное зеркалирование намеренно включено через ts.panelMirror.enabled = true в configs/anticheat_config.lua, мост автоматически остаётся выключенным, чтобы старое зеркалирование продолжало работать.
2. Начиная с tosun-ac 9.6.14 для подключения строки в server.cfg не нужны; остаётся только set tosun_ac_license с правильной лицензией. Старые строки tosun_db_bridge_enabled и tosun_db_bridge_money_write тогда игнорируются, их можно удалить; серверу со старым пакетом они нужны до установки нового пакета. Изменение баланса онлайн-персонажей тоже включено по умолчанию и доступно только пользователям панели с ролью admin или owner.
3. Разрешите исходящий HTTPS к admin.tosundev.com, проверьте консоль и запросите небольшой список игроков.

# Выполните в серверной консоли:
tosunac_db_status

Сайт сообщества только с лицензией#

Сайт вашего сообщества читает игровые данные через то же подключение Tosun Connect. Если для сервера в панели не указаны настройки игровой базы данных, сайту не нужны пользователь MySQL, GRANT и открытый порт 3306: страницы «Игроки», «Баны», «Срабатывания античита» и «Логи» загружают данные с игрового сервера при открытии.

В этом режиме сайт не может искать, фильтровать, снимать и добавлять баны или изменять деньги и инвентарь. Чтобы снять бан, используйте /ts unban <banID> в игре или ts unban <banID> в консоли сервера. Каждая страница — новый запрос, ответ приходит примерно за 10 секунд; если игровой сервер не в сети или подключение выключено на карточке Tosun Connect, страница сообщит об этом вместо пустого списка.

Для имён, работ, балансов, инвентаря и моделей транспорта на игровом сервере нужен tosun-ac 9.6.17 или новее. Со старыми пакетами некоторые серверы MySQL/MariaDB возвращают только ID персонажа.

Прямое подключение к игровой базе данных необязательно. Добавляйте его, только если на сайте нужны поиск и редактирование: создайте пользователя базы данных, который может подключаться только с IP-адреса сервера панели Tosun (поддержка его подтвердит), выдайте ему SELECT, INSERT, UPDATE и DELETE на игровую базу, откройте порт 3306 только для этого адреса и укажите данные в настройках базы данных сервера в разделе «Серверы» (Direct MySQL · Advanced). Панель сохраняет их только после успешной проверки подключения. Без этих данных используется настройка только с лицензией.

• Игроки: 25 персонажей на странице с ID персонажа, именем и работой. Команда также видит наличные и банк.
• Команда (модератор и выше) может нажать на персонажа, чтобы увидеть статус в сети, балансы и инвентарь, и загрузить транспорт этого персонажа.
• Баны и срабатывания античита: 25 записей на странице, только чтение. Срабатывания идут от старых к новым, баны — в порядке ID бана.
• Итоги на главной панели для игроков, банов и срабатываний показывают «—»: у подключения нет операции подсчёта, поэтому число не угадывается.

Доступные данные и ограничения#

Доступны список игроков, данные персонажа, его транспорт, баны и логи обнаружений. Обычно QBCore/Qbox используют players и player_vehicles, ESX — users и owned_vehicles. Нужны поддерживаемые столбцы и индексы. ready не подтверждает доступность произвольной таблицы.

Инвентарь возвращает выбранные поля, ограниченный объём сохранённых данных и максимум 100 просмотренных элементов. Произвольные метаданные, stash и все пользовательские таблицы не зеркалируются. Усечённый результат неполон: отсутствие предмета в нём не доказывает отсутствие владения. Для полной проверки используйте игровые инструменты инвентаря.

Состояние и нагрузка#

В простое мост опрашивает панель примерно раз в десять секунд и не читает игровую базу. Выполняется одно задание. Страница содержит до 25 результатов с курсором; переходите дальше, а не обновляйте первую страницу. Метаданные по запросу кешируются пять минут.

• oxmysql_unavailable: проверьте порядок запуска и подключение.
• unsupported_framework / schema_unavailable: проверьте фреймворк, таблицы и столбцы.
• unsupported_index: поручите проверку нужного ключа администратору БД; не добавляйте индекс без оценки нагрузки.
• request_expired / устаревшее состояние: проверьте сеть и возраст запроса перед повторным чтением.

• Фреймворки
• Измерение нагрузки

Осознанное изменение денег#

Изменение баланса онлайн-персонажей включено по умолчанию. Пользователи панели с ролью admin или owner (право на экономику) могут установить наличные или банк поддерживаемого онлайн-персонажа после проверки сводки подтверждения. Операция устанавливает абсолютный баланс, а не добавляет сумму при каждом повторе. Проверяется ожидаемый прежний баланс; если он не совпадает, возвращается stale_balance и ничего не меняется. Каждый запрос записывается в журнал аудита.

Прямой offline SQL не используется как запасной путь. Неясная операция сохраняется для защиты от повторения. Не выдавайте роль admin или owner сотрудникам, которые только проверяют данные. Чтобы остановить изменение денег на одном сервере, нажмите «Disable connection» в его карточке Tosun Connect (чтение тоже остановится) или включите ручной режим строкой set tosun_db_bridge_manual "1": тогда tosun_db_bridge_enabled и tosun_db_bridge_money_write берутся из server.cfg, и каждая из них выключена, пока не задано "1".

1. Прочитайте персонажа и баланс, подтвердите конечную сумму, выполните один раз.
2. При stale_balance перечитайте: игрок мог потратить или заработать деньги.
3. При unknown_outcome остановитесь, сравните живой баланс и записи. Не повторяйте запись до выяснения первого результата.

• API и учётные данные

Отличайте сохранённый список от текущих данных персонажа#

Список игроков читает сохранённые строки персонажей, а не непрерывный поток текущих данных. Детали могут заменить сохранённые балансы онлайн-значениями поддерживаемого framework и прочитать текущие предметы ox_inventory этого игрока, если они доступны. Выбирайте постоянный character_id, а не запомненный номер сессии. В панели учитывайте недоступные балансы и предупреждение о неполном инвентаре, прежде чем трактовать нули или считать список полным. Разработчики могут проверить соответствующие флаги balance_available и inventory_truncated. Недоступное поле или частичный список не доказывает потерю имущества. Данные автомобилей отражают выбранные сохранённые поля, но не подтверждают, что автомобиль сейчас создан в мире или относится к активной гаражной сессии.

1. Сравните известного персонажа с игрой в зафиксированное время, учитывая онлайн-статус и выбранный счёт.
2. При расхождении проверьте идентификатор, вид запроса и признаки доступности до каких-либо действий.
3. После переподключения или смены персонажа запросите новые детали, не используйте результат предыдущего персонажа.

Используйте страницы вместо выгрузки всей базы#

Очередь панели допускает три ожидающих или принятых запроса на сервер и двенадцать новых запросов в минуту. Задание действует 120 секунд; результаты временные и могут очищаться через пять минут после истечения задания, без гарантированного времени удаления. Ограничения предназначены для адресного управления, а не автоматического сбора всей базы. Используйте переход по страницам панели; разработчики следуют has_more и next_cursor только в одной операции и контексте персонажа. Пустая следующая страница отличается от ошибки запроса. Проверяются уникальные ключи и индексы владельцев автомобилей, поэтому неподдерживаемую структуру можно безопасно отклонить. Не переименовывайте рабочие столбцы и не добавляйте индекс только для подавления ошибки без оценки приложения и плана запроса.

1. Читайте по одной странице панели. В своей интеграции сохраняйте курсор с операцией и продолжайте только при has_more.
2. При queue_full или rate_limited дождитесь завершения открытых заданий вместо повторного открытия экранов.
3. Попросите администратора сначала изучить unsupported_index на копии; метаданные могут кэшироваться пять минут.

Останавливайте доступ, не стирая неопределённые операции#

Для просмотра выдайте только необходимые права чтения; менять баланс могут только роли admin и owner. Чтобы остановить подключение одного сервера, откройте Серверы → сервер → карточку Tosun Connect и нажмите «Disable connection»: все чтения и изменения баланса для этого сервера прекратятся, а включить подключение снова можно в той же карточке. Если нужно чтение без изменения баланса, используйте ручной режим: добавьте в server.cfg set tosun_db_bridge_manual "1" и set tosun_db_bridge_enabled "1", а tosun_db_bridge_money_write не задавайте или оставьте "0". В ручном режиме оба значения берутся из server.cfg, и каждое выключено, пока не задано "1"; поэтому ручной режим без set tosun_db_bridge_enabled "1" останавливает и чтение. Панель помечает ожидающие и принятые задания ошибкой; принятая денежная запись получает unknown_outcome, поскольку действие могло уже произойти. Поэтому игровой журнал операций нельзя считать удаляемым кэшем. Стирание KVP ради новой попытки может убрать доказательство, предотвращающее повтор. Проверяйте также доступ к полученным данным: мост не делает частными публично опубликованные снимки или логи поддержки.

1. Перед плановым отключением завершите чтения и разберите денежные неопределённости по текущему балансу и аудиту.
2. После отключения проверьте панель и tosunac_db_status; не считайте новую задачу просмотра успешной.
3. После повторного включения в карточке начните с чтения; не меняйте баланс до проверки прав, возможностей и прежних неопределённых операций.

# Server console / Sunucu konsolu:
tosunac_db_status

Проверьте схему, не изменяя данные игроков#

При schema_unavailable или unsupported_index сначала убедитесь, что выбрана база, которую действительно использует игра. Пример ниже читает только названия и типы столбцов; балансы, инвентарь и автомобили не изменяются. Это не обязательный этап установки. Уполномоченный администратор базы может выполнить запрос в своём обычном закрытом инструменте при поиске ошибки схемы. Не отправляйте SQL в мост панели: он принимает только заданные операции.

Чтение игроков QBCore/Qbox требует citizenid, money, job и charinfo в players; ESX требует identifier, accounts и job в users. Наличия таблицы недостаточно. Ключ персонажа должен иметь поддерживаемый тип и уникальный индекс по одному столбцу полной длины.

Чтение автомобилей также проверяет индексы для владельца и ключа автомобиля. Это позволяет не принуждать базу к дорогим запросам. Не переименовывайте таблицу отдельного гаража ради исчезновения ошибки; сначала получите оценку совместимости от разработчиков фреймворка и гаража.

• Запишите код ошибки, версию фреймворка и затронутую операцию чтения.
• Сравните столбцы и индексы; не прикладывайте строки игроков к обращению в поддержку.
• Оцените изменения сначала на тестовой копии. Кэш схемы моста может не увидеть новую структуру сразу.

SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
  AND TABLE_NAME IN ('players', 'users', 'player_vehicles', 'owned_vehicles')
ORDER BY TABLE_NAME, ORDINAL_POSITION
LIMIT 128;

Персонаж отображается, но список автомобилей пуст#

Допустим, персонаж из списка игроков открывается, но список автомобилей пуст. Сначала отличите успешно завершённый результат от неудачного задания. Успешный пустой список означает, что этот запрос не вернул подходящих записей; он не доказывает отсутствие автомобилей у игрока во всех системах. query_failed, schema_unavailable и unsupported_index нельзя считать пустым списком.

Убедитесь, что выбран тот же постоянный character_id. Номер сессии, меняющийся после переподключения, не заменяет ключ персонажа. QBCore/Qbox сопоставляет владельца через player_vehicles.citizenid, ESX — через owned_vehicles.owner. Если отдельный гараж использует другую таблицу или формат владельца, стандартный мост не находит эти записи автоматически.

Выбор другого персонажа в многоперсонажном аккаунте может дать похожий результат. Попросите уполномоченного администратора гаража проверить игровую запись одного известного автомобиля. Изменять баланс через мост, создавать автомобиль заново или очищать исходную таблицу для диагностики не требуется.

• Запишите ID сервера, скрытую часть ссылки на персонажа, время и статус задания.
• Следующие страницы запрашивайте для того же персонажа; не переносите cursor к другому.
• Сообщите поддержке, был ли список успешно пустым или вернулся точный код ошибки; уберите персональные данные.

Различайте числа, текст и недоступные поля#

Мост не показывает неизменённую строку БД: поддерживаемые поля нормализуются по типам и длине. Деньги персонажа читаются из чисел JSON. Например, 1200 и "1200" имеют разные типы хранения; собственный скрипт, преобразовавший деньги в текст, может сделать баланс недоступным. Недоступный баланс отображается в панели как —; это не означает нулевой баланс. Выбранные поля инвентаря — имя, подпись, количество, слот и качество; произвольные metadata, содержимое stash и счета предприятий в этот результат не входят.

Значения автомобиля, например топливо, двигатель и состояние, могут возвращаться текстом; формат сам по себе не основание для числового сравнения. Длина схемы поддерживаемых ключей char/varchar не превышает 96; передаваемый текстовый ключ дополнительно ограничен 96 байтами, что отличается для многобайтовых символов; также подходят int, bigint и mediumint. Не считайте собственный бинарный ключ стандартным. Длинный текст и инвентарь могут сокращаться: отсутствие в результате не означает удаления. Уточните исходный формат у разработчика. Нужное преобразование оцените по контракту данных игры в тестовой среде, не меняя рабочие данные ради заполненного экрана.

Принимайте запись баланса на конкретном примере#

Для разрешённой и подтверждённой коррекции представьте изменение наличных онлайн-персонажа с 1200 до 1250. Конечная сумма — 1250; значение 50 установит пятьдесят вместо прибавления пятидесяти. Проверьте выбор наличных или банка и сопоставьте постоянный идентификатор со свежими онлайн-данными. Подтверждение показывает персонажа, счёт и переход от текущей суммы к новому итогу. Сумма — неотрицательное целое конечное значение; собственные валюты и счета предприятий не заменяют эту операцию.

Постановка в очередь не завершает приёмку. Проверьте завершённый результат того же персонажа и счёта: before=1200 и after=1250; затем обычным чтением проверьте текущее состояние. Последующие расходы могут его изменить, не оправдывая автоматическую повторную отправку. Для stale_balance исследуйте устаревшее предположение, для unknown_outcome — неподтверждённое действие. Сохраните ссылку на запрос, время и очищенный результат. При неопределённости не отправляйте новую запись до пересмотра реального баланса и цели коррекции.

Срок ответа не отменяет SQL-запрос#

По умолчанию ответ SQL ожидается 5000 мс. query_timeout завершает ожидание панели; сам запрос может продолжать выполняться. Ресурс SQL остаётся занятым до первого настоящего callback, и следующее чтение возвращает query_busy. Поздний ответ не меняет уже показанный результат. Если callback не приходит, срок не освобождает ресурс автоматически. Администратор сервера должен проверить подключение и базу данных; перезапуск ресурса не доказывает отмену SQL-запроса.

Только владелец сервера при желании может добавить в server.cfg следующую строку set. Значение ограничивается диапазоном 1000–10 000 мс; недопустимое или бесконечное число даёт 5000 мс. Эта настройка не ускоряет SQL и не повторяет запросы автоматически.

Редактирование баланса в сети по умолчанию включено для пользователей панели с ролью admin или owner (право на экономику); в ручном режиме (set tosun_db_bridge_manual "1") оно выключено, пока tosun_db_bridge_money_write не равно "1". Нужны поддерживаемый персонаж в сети и подтверждение в панели. Операция заменяет только сумму наличных или банка после проверки ожидаемого текущего баланса; она никогда не переходит на запись SQL в офлайне. unknown_outcome или неясность подключения никогда не повторяются автоматически. Перед новой записью проверьте текущий баланс и журнал аудита; не удаляйте KVP-записи неопределённых операций, чтобы принудительно повторить запись.

set tosun_db_bridge_query_timeout_ms "5000"

Один SQL-файл в правильную базу#

Единственный SQL для импорта в новом ZIP — tosun-ac/INSTALL.sql. Не импортируйте вторую старую копию схемы. Нужна игровая база FiveM/oxmysql, а не база учётных записей и темы арендованного сайта. Недостающие старые столбцы исправляются до добавления стандартных значений; баны и пользовательские настройки сохраняются.

1. Сделайте резервную копию игровой базы и проверьте её имя.
2. Импортируйте только INSTALL.sql в HeidiSQL/phpMyAdmin либо явно укажите базу в mysql.
3. tosunac_db_check проверяет запрос, tosunac_db_status — мост. Мост включён по умолчанию и не требует строки в server.cfg. enabled=false ожидается в ручном режиме (set tosun_db_bridge_manual "1") без tosun_db_bridge_enabled "1" или если старое полное зеркало (ts.panelMirror.enabled = true в configs/anticheat_config.lua) включено намеренно; лицензия не создаёт MySQL-подключение.
4. Подключение панели (Tosun Connect) и изменение баланса онлайн-персонажей включены по умолчанию. Не добавляйте tosun_db_bridge_enabled и tosun_db_bridge_money_write в server.cfg; начиная с пакета 9.6.14 старые строки игнорируются, их можно удалить (более старым пакетам они нужны, пока не установлен актуальный пакет). Баланс задают только пользователи панели с ролью admin или owner: персонаж должен быть онлайн, ожидаемый баланс должен совпасть (иначе stale_balance и ничего не меняется), перед отправкой панель показывает сводку для подтверждения, каждый запрос пишется в журнал аудита, неясный результат не повторяется автоматически; сначала проверьте баланс в игре. Задаётся итоговая сумма, а не прибавка. Отключить всё подключение для одного сервера (останавливаются все запросы панели на чтение и все изменения баланса): Панель → Серверы → сервер → карточка Tosun Connect → Disable connection; снова включить его можно на той же карточке. Пароль базы храните на игровом сервере.

mysql -u YOUR_DB_USER -p YOUR_GAME_DATABASE < tosun-ac/INSTALL.sql

# txAdmin console:
tosunac_db_check
tosunac_db_status