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` | Единственная папка исходной установки с terminal64.exe и MetaEditor64.exe |
| `startup_timeout_sec` | 180 | Ожидание состояния на каждом этапе запуска, от 10 до 900 секунд |
| `disk_warning_mb` | 1024 | Минимальный желаемый запас после копирования, в МиБ; допускается 0 |

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

На странице «Настройки» меняются базовая папка терминалов и папка исходной
установки MT5. В сворачиваемом разделе «Дополнительные параметры» доступны
максимальное время ожидания запуска и порог предупреждения о свободном месте.
Они сохраняются вместе с папками кнопкой «Сохранить настройки». После изменения `mt5_folder`
менеджер предложит перенести папки существующих экземпляров и при необходимости
штатно остановить терминалы. При отмене настройки не сохраняются. После переноса
терминалы остаются остановленными. Одноимённые папки назначения не объединяются.
Если проект менеджера находится внутри базовой папки, её поле заблокировано:
сначала перенесите проект за её пределы. Ручное редактирование JSON файлы не переносит.

## Исходная установка и файлы экземпляров

Оба EXE берутся только из `terminal_template`. Эта папка может находиться вне
`mt5_folder` и не обязана содержать сам проект менеджера. После сохранения настроек
под полем этой папки показывается результат проверки обоих EXE. Для отсутствующих
файлов доступен сворачиваемый блок загрузки внутри «Размещения терминалов»;
существующие файлы не заменяются. При несохранённом пути результат прежней проверки
не показывается и загрузка недоступна.
Общего `servers.dat` больше нет: пользователь при необходимости выбирает его
в форме создания экземпляра. Выбранный файл целиком копируется в
`config/servers.dat` только новой копии. Без загрузки менеджер не копирует этот файл.

Сервис собирается из `ServiceStateWriter.mq5` текущего проекта через
`terminal_template/MetaEditor64.exe`. Если EX5 не старее исходника, при создании
можно использовать уже собранный файл. Кнопка раскладывания принудительно пересобирает
сервис. Готовый EX5 из исходной установки не используется.
При отдельном размещении проекта результат сборки находится рядом с исходником;
в `MQL5/Shared Projects` MetaEditor переносит его в каталог сервисов терминала.
В экземпляры сервис по-прежнему копируется в
`MQL5/Services/Shared Projects/mt5-manager/ServiceStateWriter.ex5`.

При чтении старой конфигурации непустой `mt5_installation` становится значением
`terminal_template`. Устаревшие `mt5_installation` и `service_ex5` удаляются из
конфигурации в памяти и исчезают из JSON при следующем сохранении.

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

Ключ `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` и восстанавливает её автозапуск. При необходимости изменения
конфигурации сначала остановите терминал. Остальные сервисы и заданные интервалы
сохраняются.