deker1176/xray-mikrotik-custom repository overview

⁠xray-mikrotik-custom

ARG XRAY_VERSION=26.3.27 ARG HEV_VERSION=2.14.4 Custom Xray VLESS client container for MikroTik RouterOS with multi-architecture support.

⁠xray-mikrotik-custom

Custom Xray VLESS client container for MikroTik RouterOS with multi-architecture support.

⁠Features

• Multi-arch image:
  • linux/arm64
  • linux/arm/v7
• Xray + HEV Socks5 Tunnel inside one container
• TUN mode with automatic route setup
• VLESS URL parsing from VLESS_URL
• Automatic Xray config generation
• Automatic HEV config generation
• Reality and TLS support:
  • security=reality
  • security=tls
• Supported transports:
  • TCP+Vision
  • XHTTP
  • gRPC
  • WebSocket
  • H2
  • HTTPUpgrade
• Bypass logic:
  • static bypass IPs
  • bypass DNS servers
  • bypass domains resolved at startup
  • automatic bypass route for the server from VLESS_URL
• Memory-saving options for MikroTik devices with limited RAM:
  • Xray buffer size control
  • HEV stack size control
  • optional UDP disable
  • optional sniffing disable
  • reduced MTU option
• Separate logging logic:
  • LOG_LEVEL controls Xray logs
  • DEBUG_STARTUP controls wrapper startup/debug output only

⁠Image tags

deker1176/xray-mikrotik-custom:stable
deker1176/xray-mikrotik-custom:arm64
deker1176/xray-mikrotik-custom:armv7

Recommended tag:

deker1176/xray-mikrotik-custom:stable

The stable tag is multi-arch and contains:

• linux/arm64
• linux/arm/v7

⁠Why this image exists

When using TUN mode inside a MikroTik container, the default route may move to tun0.

Because of that, DNS requests and even the connection to the VLESS server itself may try to go through the same tunnel before it is fully established.

This image solves that by allowing you to define direct routes for:

• DNS servers
• static IPs
• domains
• the current server from VLESS_URL

The wrapper resolves the domain at startup and adds direct bypass routes through the normal container interface before traffic is moved to tun0.

⁠Quick Start

⁠1. Create bridge and veth interface

If you do not already have a dedicated bridge for containers, create it first:

/interface/bridge/add name=containers
/ip/address/add address=172.17.0.1/24 interface=containers

/interface/veth/add name=veth-vless address=172.17.0.2/24 gateway=172.17.0.1
/interface/bridge/port/add bridge=containers interface=veth-vless

⁠2. Add NAT for container internet access

Use your real WAN interface list or WAN interface.

/ip/firewall/nat/add chain=srcnat src-address=172.17.0.0/24 out-interface-list=WAN action=masquerade

If you do not use out-interface-list=WAN, specify your WAN interface manually, for example:

/ip/firewall/nat/add chain=srcnat src-address=172.17.0.0/24 out-interface=ether1 action=masquerade

⁠3. Set environment variables

Minimal recommended set for MikroTik:

/container/envs/add list=vless-env key=VLESS_URL value="vless://[email protected]:443?type=tcp&security=reality&flow=xtls-rprx-vision&pbk=PUBLIC_KEY&fp=randomized&sni=www.google.com&sid=SHORTID&spx=%2F"

/container/envs/add list=vless-env key=CONTAINER_GW value=172.17.0.1
/container/envs/add list=vless-env key=CONTAINER_IFACE value=veth-vless

/container/envs/add list=vless-env key=BYPASS_DNS value=1.1.1.1,8.8.8.8
/container/envs/add list=vless-env key=RESOLV_DNS value=1.1.1.1,8.8.8.8
/container/envs/add list=vless-env key=BYPASS_DOMAINS value=server.example.com

/container/envs/add list=vless-env key=LOG_LEVEL value=warning
/container/envs/add list=vless-env key=DEBUG_STARTUP value=0
/container/envs/add list=vless-env key=XRAY_BUFFER_SIZE value=0
/container/envs/add list=vless-env key=HEV_STACK_SIZE value=16384
/container/envs/add list=vless-env key=ENABLE_UDP value=false
/container/envs/add list=vless-env key=MTU value=1280

Only VLESS_URL is strictly required, but the values above are recommended for MikroTik devices with limited RAM.

⁠4. Create and start container

/container/add remote-image=deker1176/xray-mikrotik-custom:stable \
  interface=veth-vless root-dir=disk1/containers/vless \
  envlist=vless-env logging=yes start-on-boot=yes name=vless

/container/start vless

If you want to avoid cached old layers during testing, use a new root-dir, for example:

root-dir=disk1/containers/vless102

⁠5. Route traffic through container

Create routing table and default route through the container:

/routing/table/add fib name=to_vpn
/ip/route/add dst-address=0.0.0.0/0 gateway=172.17.0.2 routing-table=to_vpn

Example for one subnet:

/routing/rule/add src-address=192.168.88.0/24 action=lookup-only-in-table table=to_vpn

Example for one client only:

/routing/rule/add src-address=192.168.88.100/32 action=lookup-only-in-table table=to_vpn

For MikroTik routers with small RAM, start with one client or a small group of clients before routing a whole subnet.

⁠Environment Variables

⁠Recommended low-memory setup

For MikroTik routers with limited RAM:

LOG_LEVEL=warning
DEBUG_STARTUP=0
XRAY_BUFFER_SIZE=0
HEV_STACK_SIZE=16384
ENABLE_UDP=false
MTU=1280

If the router still kills the container under heavy load, try:

HEV_STACK_SIZE=8192
ENABLE_SNIFFING=false

Also reduce the number of clients routed through the container.

⁠VLESS Reality example

vless://[email protected]:443?type=tcp&security=reality&flow=xtls-rprx-vision&pbk=PUBLIC_KEY&fp=randomized&sni=www.google.com&sid=SHORTID&spx=%2F#Example

This generates Xray streamSettings with:

"security": "reality",
"realitySettings": {
  "fingerprint": "randomized",
  "serverName": "www.google.com",
  "publicKey": "PUBLIC_KEY",
  "spiderX": "/",
  "shortId": "SHORTID"
}

⁠TLS support

For links with:

security=tls

the wrapper generates tlsSettings.

ALLOW_INSECURE is used only for TLS mode:

ALLOW_INSECURE=false

For Reality mode, separate TLS settings are not required because Xray uses security=reality and realitySettings.

⁠How bypass works

At startup, the wrapper script:

1. writes /etc/resolv.conf from RESOLV_DNS
2. adds direct routes for BYPASS_IPS
3. adds direct routes for BYPASS_DNS
4. resolves BYPASS_DOMAINS
5. resolves the current server from VLESS_URL
6. adds direct routes for resolved IP addresses through CONTAINER_GW and CONTAINER_IFACE
7. generates Xray config
8. generates HEV config
9. starts Xray
10. starts HEV Socks5 Tunnel
11. configures default route through tun0
12. keeps bypass routes through the normal container interface

This avoids the common TUN loop problem where DNS or the VLESS server connection itself tries to go through tun0.

⁠Diagnostics

View container logs:

/log/print where message~"vless"

Enter container shell:

/container/shell vless

Useful checks inside the container:

ip a
ip route
cat /etc/resolv.conf
cat /etc/xray/config.json
cat /etc/hev-socks5/config.yaml
curl -v --socks5-hostname 127.0.0.1:1080 https://api.ipify.org

Check direct route to server:

nslookup server.example.com
ip route get SERVER_IP

The route to the VLESS server must go through the normal container interface, for example:

SERVER_IP via 172.17.0.1 dev veth-vless

⁠Notes

• BYPASS_DOMAINS is resolved only at container startup.
• If the domain IP changes later, restart the container to refresh routes.
• Keep BYPASS_DNS and RESOLV_DNS configured when using domain names.
• CONTAINER_IFACE is used for direct routes outside TUN.
• ENABLE_UDP=false is recommended on low-memory MikroTik routers.
• Browser HTTPS still works without UDP; browsers will fall back from QUIC to TCP.

⁠Requirements

• MikroTik RouterOS 7.x with container support
• Supported architectures:
  • ARM64
  • ARMv7
• USB/disk storage for container root-dir
• Working container bridge/veth setup
• NAT for container subnet

⁠License

MIT

⁠xray-mikrotik-custom

Кастомный контейнер-клиент Xray VLESS для MikroTik RouterOS с поддержкой нескольких архитектур.

⁠Возможности

• Multi-arch образ:
  • linux/arm64
  • linux/arm/v7
• Xray + HEV Socks5 Tunnel в одном контейнере
• TUN-режим с автоматической настройкой маршрутов
• Разбор VLESS-ссылки из VLESS_URL
• Автоматическая генерация Xray config
• Автоматическая генерация HEV config
• Поддержка Reality и TLS:
  • security=reality
  • security=tls
• Поддерживаемые транспорты:
  • TCP+Vision
  • XHTTP
  • gRPC
  • WebSocket
  • H2
  • HTTPUpgrade
• Логика bypass:
  • статические bypass IP
  • bypass DNS-серверов
  • bypass доменов с резолвом при старте
  • автоматический bypass-маршрут для сервера из VLESS_URL
• Опции экономии памяти для MikroTik с малым объемом RAM:
  • управление размером буфера Xray
  • управление размером стека HEV
  • возможность отключить UDP
  • возможность отключить sniffing
  • уменьшение MTU
• Раздельная логика логирования:
  • LOG_LEVEL управляет логами Xray
  • DEBUG_STARTUP управляет только startup/debug выводом wrapper-скрипта

⁠Теги образа

deker1176/xray-mikrotik-custom:stable
deker1176/xray-mikrotik-custom:arm64
deker1176/xray-mikrotik-custom:armv7

Рекомендуемый тег:

deker1176/xray-mikrotik-custom:stable

Тег stable является multi-arch и содержит:

• linux/arm64
• linux/arm/v7

⁠Зачем нужен этот образ

При использовании TUN-режима внутри контейнера MikroTik маршрут по умолчанию может переключаться на tun0.

Из-за этого DNS-запросы и даже соединение до самого VLESS-сервера могут пытаться идти через этот же туннель еще до того, как он полностью поднялся.

Этот образ решает проблему за счет возможности задавать прямые маршруты для:

• DNS-серверов
• статических IP
• доменов
• текущего сервера из VLESS_URL

Wrapper при старте резолвит домен и добавляет прямые bypass-маршруты через обычный интерфейс контейнера до переключения трафика в tun0.

⁠Быстрый старт

⁠1. Создать bridge и veth-интерфейс

Если отдельного bridge для контейнеров еще нет, сначала создайте его:

/interface/bridge/add name=containers
/ip/address/add address=172.17.0.1/24 interface=containers

/interface/veth/add name=veth-vless address=172.17.0.2/24 gateway=172.17.0.1
/interface/bridge/port/add bridge=containers interface=veth-vless

⁠2. Добавить NAT для доступа контейнера в интернет

Используйте ваш реальный WAN interface-list или WAN-интерфейс.

/ip/firewall/nat/add chain=srcnat src-address=172.17.0.0/24 out-interface-list=WAN action=masquerade

Если out-interface-list=WAN не используется, укажите WAN-интерфейс вручную, например:

/ip/firewall/nat/add chain=srcnat src-address=172.17.0.0/24 out-interface=ether1 action=masquerade

⁠3. Задать переменные окружения

Минимальный рекомендуемый набор для MikroTik:

/container/envs/add list=vless-env key=VLESS_URL value="vless://[email protected]:443?type=tcp&security=reality&flow=xtls-rprx-vision&pbk=PUBLIC_KEY&fp=randomized&sni=www.google.com&sid=SHORTID&spx=%2F"

/container/envs/add list=vless-env key=CONTAINER_GW value=172.17.0.1
/container/envs/add list=vless-env key=CONTAINER_IFACE value=veth-vless

/container/envs/add list=vless-env key=BYPASS_DNS value=1.1.1.1,8.8.8.8
/container/envs/add list=vless-env key=RESOLV_DNS value=1.1.1.1,8.8.8.8
/container/envs/add list=vless-env key=BYPASS_DOMAINS value=server.example.com

/container/envs/add list=vless-env key=LOG_LEVEL value=warning
/container/envs/add list=vless-env key=DEBUG_STARTUP value=0
/container/envs/add list=vless-env key=XRAY_BUFFER_SIZE value=0
/container/envs/add list=vless-env key=HEV_STACK_SIZE value=16384
/container/envs/add list=vless-env key=ENABLE_UDP value=false
/container/envs/add list=vless-env key=MTU value=1280

Строго обязательна только переменная VLESS_URL, но значения выше рекомендуются для MikroTik с ограниченной RAM.

⁠4. Создать и запустить контейнер

/container/add remote-image=deker1176/xray-mikrotik-custom:stable \
  interface=veth-vless root-dir=disk1/containers/vless \
  envlist=vless-env logging=yes start-on-boot=yes name=vless

/container/start vless

Если нужно исключить использование старых закешированных слоев при тестах, задайте новый root-dir, например:

root-dir=disk1/containers/vless102

⁠5. Направить трафик через контейнер

Создайте таблицу маршрутизации и default route через контейнер:

/routing/table/add fib name=to_vpn
/ip/route/add dst-address=0.0.0.0/0 gateway=172.17.0.2 routing-table=to_vpn

Пример для подсети:

/routing/rule/add src-address=192.168.88.0/24 action=lookup-only-in-table table=to_vpn

Пример только для одного клиента:

/routing/rule/add src-address=192.168.88.100/32 action=lookup-only-in-table table=to_vpn

Для MikroTik с малым объемом RAM сначала пускайте через контейнер одного клиента или небольшую группу клиентов, а не всю подсеть сразу.

⁠Переменные окружения

⁠Рекомендуемая настройка для экономии памяти

Для MikroTik с ограниченной RAM:

LOG_LEVEL=warning
DEBUG_STARTUP=0
XRAY_BUFFER_SIZE=0
HEV_STACK_SIZE=16384
ENABLE_UDP=false
MTU=1280

Если роутер всё равно убивает контейнер под большой нагрузкой, попробуйте:

HEV_STACK_SIZE=8192
ENABLE_SNIFFING=false

Также уменьшите количество клиентов, которые идут через контейнер.

⁠Пример VLESS Reality

vless://[email protected]:443?type=tcp&security=reality&flow=xtls-rprx-vision&pbk=PUBLIC_KEY&fp=randomized&sni=www.google.com&sid=SHORTID&spx=%2F#Example

Будет сгенерирован Xray streamSettings:

"security": "reality",
"realitySettings": {
  "fingerprint": "randomized",
  "serverName": "www.google.com",
  "publicKey": "PUBLIC_KEY",
  "spiderX": "/",
  "shortId": "SHORTID"
}

⁠Поддержка TLS

Для ссылок с:

security=tls

wrapper генерирует tlsSettings.

ALLOW_INSECURE используется только в TLS-режиме:

ALLOW_INSECURE=false

Для Reality-режима отдельные TLS-настройки не нужны, потому что Xray использует security=reality и realitySettings.

⁠Как работает bypass

При старте контейнера wrapper-скрипт:

1. записывает /etc/resolv.conf из RESOLV_DNS
2. добавляет прямые маршруты для BYPASS_IPS
3. добавляет прямые маршруты для BYPASS_DNS
4. резолвит домены из BYPASS_DOMAINS
5. резолвит текущий сервер из VLESS_URL
6. добавляет прямые маршруты для полученных IP-адресов через CONTAINER_GW и CONTAINER_IFACE
7. генерирует Xray config
8. генерирует HEV config
9. запускает Xray
10. запускает HEV Socks5 Tunnel
11. настраивает default route через tun0
12. сохраняет bypass-маршруты через обычный интерфейс контейнера

Это позволяет избежать типичной TUN-петли, когда DNS или соединение до самого VLESS-сервера пытается идти через tun0.

⁠Диагностика

Просмотр логов контейнера:

/log/print where message~"vless"

Вход в shell контейнера:

/container/shell vless

Полезные проверки внутри контейнера:

ip a
ip route
cat /etc/resolv.conf
cat /etc/xray/config.json
cat /etc/hev-socks5/config.yaml
curl -v --socks5-hostname 127.0.0.1:1080 https://api.ipify.org

Проверить прямой маршрут до сервера:

nslookup server.example.com
ip route get SERVER_IP

Маршрут до VLESS-сервера должен идти через обычный интерфейс контейнера, например:

SERVER_IP via 172.17.0.1 dev veth-vless

⁠Примечания

• BYPASS_DOMAINS резолвится только при старте контейнера.
• Если IP домена изменится позже, перезапустите контейнер для обновления маршрутов.
• При использовании доменов держите настроенными BYPASS_DNS и RESOLV_DNS.
• CONTAINER_IFACE используется для прямых маршрутов вне TUN.
• ENABLE_UDP=false рекомендуется для MikroTik с малым объемом RAM.
• HTTPS в браузере работает без UDP; браузеры перейдут с QUIC на TCP.

⁠Требования

• MikroTik RouterOS 7.x с поддержкой контейнеров
• Поддерживаемые архитектуры:
  • ARM64
  • ARMv7
• USB-накопитель или диск для root-dir контейнера
• Рабочая схема bridge/veth для контейнера
• NAT для подсети контейнера

⁠Лицензия

MIT