mt5-manager/docs/configuration.md

# Настройки и конфигурация

[Документация](README.md) · [Установка](installation.md) · [Эксплуатация](maintenance.md)

## Выбор файла

`python run.py --config-file config.local.json` выбирает файл настроек менеджера.
Без аргумента используется `config.json` из рабочего каталога. Параметры запуска
сети: `--host` (по умолчанию `0.0.0.0`) и `--port` (8000).

Менеджер читает JSON при запуске. Изменения через веб-интерфейс сохраняются
атомарной заменой файла и сразу применяются к конфигурации в памяти. Изменения
JSON вручную требуют перезапуска менеджера. Не редактируйте файл одновременно
с сохранением через интерфейс.

Начальный документ без счетов находится в [config.example.json](../config.example.json).
При подготовке личного файла замените `USERNAME` в `database` на путь текущего
пользователя, как показано в [быстром старте](../README.md).

## Общие параметры JSON

| Поле | Обязательность / значение по умолчанию | Назначение |
|---|---|---|
| `terminals` | Обязательное; для начала `{}` | Словарь управляемых экземпляров |
| `mt5_folder` | Обязательное | Базовая папка всех существующих и новых экземпляров |
| `mt5_exe` | Обязательное; указывайте `terminal64.exe` | Имя исполняемого файла; создание поддерживает именно это имя |
| `database` | Обязательное | Полный путь к общей SQLite в `Common/Files` пользователя Windows |
| `terminal_template` | `terminal-template` | Папка-образец для загружаемых файлов |
| `mt5_installation` | Пустая строка | Установка MT5, из которой берутся недостающие файлы и MetaEditor |
| `service_ex5` | Пустая строка | Явный путь к готовому сервису, если нужен |
| `startup_timeout_sec` | 180 | Ожидание состояния на каждом этапе запуска, от 10 до 900 секунд |
| `disk_warning_mb` | 1024 | Минимальный желаемый запас после копирования, в МиБ; допускается 0 |

Относительные пути разрешаются от папки выбранного JSON, а не от папки скрипта.
При сохранении менеджер записывает разрешённые пути. Переменные окружения внутри
строк JSON, например `%APPDATA%`, не раскрываются: подставляйте готовый путь.

На странице «Настройки» меняются папки, `service_ex5`, время ожидания и порог
свободного места. `database` и `mt5_exe` задаются в JSON. Веб-интерфейс не переносит
базу или папки терминалов. После изменения `mt5_folder` все экземпляры ищутся
относительно нового значения.

## Порядок выбора файлов

Для каждого из `terminal64.exe`, `MetaEditor64.exe` и `config/servers.dat` сначала
проверяется соответствующий файл в `terminal_template`. Если его нет, используется
файл из `mt5_installation`. Если установка явно не задана, она определяется
автоматически только при расположении проекта в `MQL5/Shared Projects`.
Для отдельно клонированного проекта укажите `mt5_installation` либо загрузите
нужные файлы через интерфейс. Произвольные родительские папки не просматриваются.
Таким образом, загрузка одного файла не требует загружать остальные заново.

Сервис выбирается в таком порядке:

1. Непустой `service_ex5`: используем этот путь. Ошибка пути не переключает поиск
   на другой EX5.
2. `ServiceStateWriter.ex5` в `terminal_template`, если он существует.
3. Сборка из исходника текущего проекта через MetaEditor: сначала из
   `terminal_template`, затем из выбранной или автоматически определённой установки. Уже
   существующий EX5 не компилируется повторно, если его время изменения не меньше
   времени изменения `ServiceStateWriter.mq5`.

Проверка свежести сравнивает MQ5 и EX5; это не полная проверка зависимостей сборки.
Готовый загруженный сервис и явно заданный EX5 не перекомпилируются.
При отдельном размещении проекта результат сборки находится рядом с исходником:
`ServiceStateWriter.ex5` исключён из Git. Для проекта в `MQL5/Shared Projects`
MetaEditor переносит результат в соответствующую подпапку `MQL5/Services`.
В обоих случаях при развёртывании сервис копируется в экземпляры по прежнему пути
`MQL5/Services/Shared Projects/mt5-manager/ServiceStateWriter.ex5`.
На странице настроек показываются сведения о найденных файлах, в том числе
из установки MT5; наличие файла в списке не обязательно означает его загрузку.

Загрузка заменяет файл-образец для будущих экземпляров. Работающие терминалы
при этом не получают новый EXE, `servers.dat` или сервис. Импорт `servers.dat`
не объединяет каталоги брокеров: загружается целый файл.

## Запись экземпляра

Ключ `terminals` — имя папки, по которому сервис регистрируется в SQLite:

```json
{
  "MetaTrader5.5": {
    "name": "Демо-терминал",
    "login": "",
    "server": "",
    "password": ""
  }
}
```

Это фрагмент содержимого `terminals`, а не полная конфигурация. При создании
имя предлагается автоматически, но его можно изменить. Для новых имён
проверяется допустимость одного компонента пути Windows и отсутствие занятого
имени без учёта регистра. Имена папок разных экземпляров должны быть уникальны,
поскольку база использует имя папки как ключ. Имя экземпляра — один компонент
пути Windows, без вложенных каталогов.

`name` — отображаемое название; оно не переименовывает папку. Расположение всегда
вычисляется как `mt5_folder / имя экземпляра`. Поле `path` из старых конфигураций
игнорируется и удаляется при следующем сохранении. Само чтение конфигурации
не переписывает файл.

После изменения базовой папки поиск процессов, запуск и распространение сервиса
сразу используют новые пути. Менеджер не переносит файлы и не останавливает процессы
в прежнем каталоге. Если новой папки ещё нет или она указана неверно, экземпляр
не будет найден, пока вы не исправите базу или не разместите терминал по нужному пути.
Несколько терминалов могут использовать один торговый счёт.

## Реквизиты счёта

Пустые `login`, `server` и `password` означают использование сохранённых настроек
самого терминала. Если их у терминала нет, он запускается без подключения.
Для нового экземпляра с заданным счётом нужен полный набор из трёх значений.
Номер счёта должен быть положительным целым; его можно передать числом или строкой.

В интерфейсе пустое поле пароля сохраняет прежний пароль менеджера. Флажок
«Убрать реквизиты из менеджера» очищает три поля менеджера, но не сохранённый
счёт внутри терминала. После применения терминал использует собственные настройки.
Старые записи с логином и сервером без пароля допустимы, если терминал уже умеет
подключаться к этому счёту; при необходимости перенастройки потребуется пароль.

Пароль хранится в JSON открытым текстом. API не выдаёт его обратно: возвращается
`password_set`. Параметры первого входа передаются временным INI в UTF-16,
который удаляется после настройки. В `config/common.ini` менеджер сохраняет
`Login`, `Server` и `KeepPrivate=1` для последующего обычного запуска.

## База и параметры MQL5-сервиса

Python читает `database`, а сервис открывает `InpDatabase` с флагом
`DATABASE_OPEN_COMMON`. Они должны указывать на один файл в
`%APPDATA%/MetaQuotes/Terminal/Common/Files` одного пользователя Windows.
Менеджер открывает базу только для чтения и не создаёт файл при ошибке пути.
Сервис при открытии создаёт отсутствующий файл и таблицы `terminals` и `states`,
в том числе когда файл SQLite уже существует, но пуст. Ошибки создания таблиц
попадают в журнал сервиса, после чего открытие повторяется на следующей итерации.
Полный путь базы выводится при запуске сервиса и в сообщениях об ошибках чтения Python.
При создании экземпляра менеджер берёт только имя файла из `database` и подставляет
его в `services.ini`. Размещение Python-базы в другой папке приведёт к расхождению.

| Параметр сервиса | Значение в образце | Назначение |
|---|---|---|
| `InpDatabase` | `mt5-manager.sqlite` | Имя базы внутри `Common/Files` |
| `InpIntervalSec` | 2 | Основной интервал записи в секундах |
| `InpJitterMs` | 1000 | Случайная добавка к паузе в миллисекундах |
| `InpBusyTimeout` | 3000 | Ожидание блокировки SQLite в миллисекундах |

Последнее состояние хранится с Unix-временем в секундах. Миллисекунды в параметрах
паузы и ожидания SQLite остаются единицами этих параметров. Для уже установленных
копий команда «Собрать и разложить сервис» проверяет запись ServiceStateWriter
в `config/services.ini` и восстанавливает её автозапуск. При необходимости изменения
конфигурации сначала остановите терминал. Остальные сервисы и заданные интервалы
сохраняются.