Веб сервер

Запускает веб сервер для 'ioBroker драйверов'

Текущий релиз
9.1.4
Разработчик
bluefox
Лицензия
MIT

ioBroker.web

Веб-сервер на базе Node.js и Express для чтения файлов из базы данных ioBroker.

Этот адаптер использует библиотеки Sentry для автоматического сообщения разработчикам об исключениях и ошибках в коде. Более подробную информацию, а также инструкции по отключению отправки сообщений об ошибках см. в документации Sentry-Plugin ! Система отчетности Sentry используется начиная с js-controller 3.0.

Настройка веб-сокетов

У некоторых клиентов, использующих веб-сокеты, возникают проблемы с производительностью связи. Иногда эта проблема связана с переходом на механизм длительного опроса (long polling) при использовании механизма связи socket.io. Вы можете установить параметр «Принудительное использование веб-сокетов» (Force Web-Sockets) , чтобы принудительно использовать только транспорт веб-сокетов.

Сертификаты Let's Encrypt

Читайте здесь

Центр сертификации проверяет HTTP-запрос HTTP-01 на порту 80, поэтому на хосте с одним публичным IP-адресом этот запрос попадает на тот сетевой адаптер, который обслуживает этот порт. При включенных запросах HTTP-01 от Answer ACME (acmeChallenge (по умолчанию) этот экземпляр предоставляет токены.acme адаптер опубликован в/.well-known/acme-challenge/ иacme Адаптеру не нужно останавливать его, чтобы получить доступ к порту. Здесь обрабатывается только запрос на опубликованный токен, все остальное передается без изменений. Отключите эту опцию, чтобы сохранить этот путь исключительно к веб-приложению.

Расширения

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

Например, пользователь может активировать специальный прокси-адаптер и получить доступ к другим устройствам (например, веб-камерам) через тот же веб-сервер. Необходимо, чтобы все сервисы были доступны через один веб-сервер.

Веб-расширение могло бы и должно поддерживатьunload функция, которая может возвращатьpromise если разгрузка займет некоторое время.

Подробнее о веб-расширениях можно прочитать здесь .

Защита методом грубой силы

Если аутентификация включена и пользователь вводит неверный пароль 5 раз в течение одной минуты, он должен подождать не менее одной минуты до следующей попытки. После 15-й неверной попытки пользователь должен подождать 1 час.

Опция "Оставаться в системе"

Если этот параметр выбран, пользователь останется авторизованным в течение одного месяца. В противном случае пользователь останется авторизованным в течение заданного времени ожидания авторизации.

Получите доступ к значениям состояния.

Доступ к значениям нормального состояния можно получить с помощью HTTP-запроса GET.

http://IP:8082/state/system.adapter.web.0.alive =>
{"val":true,"ack":true,"ts":1606831924559,"q":0,"from":"system.adapter.web.0","lc":1606777539894}

или получить доступ к таким файлам, как:

http://IP:8082/vis-2.0/javascript.picture.png =>
[IMAGE]

Начиная с версии 8.0.0, вы также можете записывать значения через HTTP POST-запрос:

[POST] http://IP:8082/state/javascript.0.myVariable => true

Или в виде JSON-объекта с дополнительными параметрами:

[POST] http://IP:8082/state/javascript.0.myVariable =>
{"val": true, "ack": false}

Примечание: для использования этой функции необходимо отключить параметр "Отключить состояния и информацию о сокете" в настройках веб-адаптера.

Доступ к объектам

Вы можете считывать объекты (включая шаблоны с подстановочными знаками) с помощью HTTP GET-запроса. Ответ всегда представляет собой JSON-массив , поскольку шаблон может соответствовать нескольким объектам.

По умолчанию каждый возвращаемый объект содержит только_id ,type иcommon Используйтеextended и/илиnative Флаги запроса для запроса дополнительных данных.

Когдаdepth Если используется запрос и найден соответствующий объект, расположенный глубже запрошенного уровня, возвращается синтетический заполнитель точно на этой глубине:

{ "_id": "0_userdata.0", "type": "virtual" }

Это позволяет браузеру дерева видеть, что контент существует ниже промежуточного пути, даже если сам этот путь не содержит реального объекта ioBroker. Виртуальные объекты намеренно опускаютcommon чтобы полезная нагрузка была небольшой, отображаемое имя может быть получено из_id Реальный объект с тем же идентификатором всегда имеет приоритет над своим виртуальным заменителем.

http://IP:8082/object/0_userdata.0.branch.* =>
[ { "_id": "0_userdata.0.branch.a", "type": "state", "common": { ... } }, ... ]

Поддерживаемые параметры запроса:

ПараметрОписание
typeФильтрация по типу объекта (например)state ,channel ,device ,folder ,enum ,instance , ...). По умолчаниюstate если опущено. Пройтиall для запроса объектов любого типа.
commonTypeФильтр поcommon.type объекта (number ,string ,boolean ,mixed ,array ,object ).
depthМаксимальное количество частей, разделённых точками, в идентификаторе объекта. Например, чтобы получить только непосредственных потомков0_userdata.0.branch (состоящий из 3 частей), запрос/object/0_userdata.0.branch.*?depth=4 .depth=1 молча прижат кdepth=2 (Объекты ioBroker существуют на 1 уровне или на 3+ уровнях — записи «экземпляров» 2-го уровня, например)0_userdata.0 (это то, что на самом деле нужно корневому древовидному браузеру). Любые объекты, состоящие из одного сегмента, удаляются из ответа по той же причине.
extendedПроходить?extended или?extended=true дополнительно включить такие атрибуты системы, какacl ,from ,ts ,user ,enums ,_rev .
nativeПроходить?native или?native=true дополнительно включитьnative часть каждого объекта.
systemПо умолчанию объекты находятся вsystem.* иscript.* скрыты . Пропуск?system или?system=true включить их.

Примеры:

[GET] http://IP:8082/object/0_userdata.0.branch.*?depth=4&type=all
[GET] http://IP:8082/object/0_userdata.0.*?type=state
[GET] http://IP:8082/object/0_userdata.0.*?type=state&commonType=boolean
[GET] http://IP:8082/object/system.adapter.web.0?native=true
[GET] http://IP:8082/object/system.adapter.web.0?extended=true&native=true
[GET] http://IP:8082/object/system.adapter.web.0

Примечание: для использования этой функции необходимо отключить параметр "Отключить доставку объектов" в настройках веб-адаптера.

Опция "Базовая аутентификация"

Позволяет выполнить вход через базовую аутентификацию путем отправки401 Несанкционированное использованиеWWW-Authenticate Заголовок. Его можно использовать для таких приложений, как FullyBrowser . При вводе неверных учетных данных вы будете перенаправлены на страницу входа.

Список пользователей

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

Если пользователя нет в списке, он не сможет получить доступ к веб-серверу.

Проще установить для каждого объекта и каждого состояния права доступа для конкретного пользователя.

Расширенные параметры

Перенаправление по умолчанию

Если при открытии веб-порта в браузере не должно отображаться меню выбора приложения, а должно отображаться какое-либо конкретное приложение, путь к нему можно указать здесь (например,/vis/ Таким образом, этот путь откроется автоматически.

Аутентификация OAuth2

Веб-адаптер поддерживает аутентификацию OAuth2.

Для получения токенов пользователю необходимо перейти по следующему URL-адресу:

http://ip:8082//oauth/token?grant_type=password&username=<user>&password=<password>&client_id=ioBroker&stayloggedin=<false/true>

stayloggedin=true Это означает, что токен будет сохранен в браузере и будет использоваться для последующих запросов; его использование необязательно.

Ответ выглядит так:

{
    "access_token": "21f89e3eee32d3af08a71c1cc44ec72e0e3014a9",
    "expires_in": "2025-02-23T11:39:32.208Z",
    "refresh_token": "66d35faa5d53ca8242cfe57367210e76b7ffded7",
    "refresh_token_expires_in": "2025-03-25T10:39:32.208Z",
    "token_type": "Bearer"
}

Более подробную информацию можно найти здесь: https://github.com/ioBroker/webserver?tab=readme-ov-file#oauth2-support

Авторизация сторонних клиентов (OAuth)

Указанная выше конечная точка для ввода токена требует, чтобы клиент обрабатывал пароль пользователя ioBroker. Клиенты, работающие вне вашего контроля — клиенты MCP или веб-расширения, обслуживающие их, — не должны этого делать. Включение параметра «Разрешить сторонние клиенты» в настройках дополнительно обеспечивает поток авторизации OAuth2 на основе кода в браузере с использованием PKCE: клиент перенаправляется на страницу входа и согласия, пользователь подтверждает авторизацию, и клиент получает токен, привязанный к запрошенному ресурсу.

По умолчанию эта функция отключена. При включении:

  • Клиенты обнаруживают сервер через/.well-known/oauth-authorization-server и зарегистрироваться самостоятельно, если параметр "Разрешить саморегистрацию клиентов" не отключен.
  • Неаутентифицированные запросы, которые не содержат запросаtext/html на них отвечают следующим образом401 и аWWW-Authenticate Вместо перенаправления на страницу входа в систему используется запрос подтверждения — перенаправление бесполезно для клиента API. Браузеры не затрагиваются.
  • Веб-расширения публикуют собственные метаданные ресурсов в разделе/.well-known/oauth-protected-resource/<path> Эти документы остаются читаемыми и без ввода учетных данных.
  • Укажите публичный URL-адрес, если сервер работает за обратным прокси-сервером, и используйте HTTPS: удаленные клиенты отказываются от использования обычного протокола.http:// .

9.1.4 (2026-08-31)

  • (@GermanBluefox) Обновлены пакеты

9.1.3 (2026-08-28)

  • (@GermanBluefox) Обновлены пакеты

9.1.2 (2026-08-27)

  • (@GermanBluefox) Добавил настройкуacmeChallenge (включено по умолчанию): веб-сервер отвечает на HTTP-запросы ACME HTTP-01, публикуемые адаптером ACME, поэтому адаптеру ACME больше не нужно останавливать этот экземпляр для доступа к порту 80.

9.1.1 (2026-08-26)

  • (@GermanBluefox) Исправлены отсутствующие заголовки CORS на каждом маршруте, который отвечает, не передавая запрос дальше — в том числе и на всем сервере OAuth2. Получение токена из браузера с другого источника завершалось ошибкой.No Access-Control-Allow-Origin header is present Теперь промежуточное ПО CORS регистрируется перед всеми маршрутами, а не после них.
  • (@GermanBluefox) Теперь отраженный источник отправляется вместе сVary: Origin и незаданный источник, метод или список заголовков больше не отображаются в виде строкового значения.undefined в ответе

9.1.0 (2026-08-04)

  • (@GermanBluefox) Добавлен поток авторизации OAuth2 с PKCE, поэтому сторонние клиенты (например, клиенты MCP) могут быть авторизованы без просмотра пароля пользователя.
  • (@GermanBluefox) Неаутентифицированные запросы, не содержащие HTML, теперь получают401 Вместо запроса подтверждения авторизации используется перенаправление при включенной аутентификации OAuth.
  • (@GermanBluefox) Обновлено@iobroker/webserver до 2.0.1

License

The MIT License (MIT)

Copyright (c) 2014-2026 Bluefox dogafox@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.