ariankeshavarz/3x-ui repository overview

⁠3x-ui Debug

An extended Docker image for 3x-ui⁠ with a comprehensive network, system, and Python debugging toolkit.

The goal is simple: keep the original 3x-ui application intact while making the same container much more useful for troubleshooting DNS, routing, connectivity, packet loss, TLS, HTTP, throughput, and system-level issues.

⁠Official 3x-ui Project

This image is based on the official 3x-ui project:

• GitHub: https://github.com/MHSanaei/3x-ui⁠
• Documentation: https://docs.sanaei.dev/⁠

The upstream 3x-ui application is not modified, patched, recompiled, or replaced by this image.

The original 3x-ui entrypoint and startup model are preserved.

The image simply adds debugging and troubleshooting tools on top of the official 3x-ui container.

⁠What This Image Changes

The base 3x-ui application remains the responsibility of the upstream project.

This image adds:

• Network troubleshooting tools
• Packet capture tools
• Throughput testing
• System and process monitoring
• Python 3
• Python networking libraries
• General shell and filesystem utilities
• JSON tooling

No standalone Xray Core is added separately by this image.

The Xray/runtime components already provided by the upstream 3x-ui image remain untouched.

⁠Base Image

FROM ghcr.io/mhsanaei/3x-ui:latest

The upstream 3x-ui image already provides its normal application stack and runtime dependencies.

The debug image extends that environment with additional packages.

⁠Included Network Tools

⁠Connectivity & DNS

• curl
• wget
• dig
• nslookup
• ping
• traceroute
• mtr

⁠Network Inspection

• ip
• ss
• nc
• tcpdump
• iftop
• iperf3
• openssl

⁠JSON

• jq

These tools allow troubleshooting directly from the same container where 3x-ui is running.

⁠Included System & Process Tools

• procps
• ps
• top
• free
• vmstat
• btop
• htop

⁠Shell & File Utilities

• Bash
• Coreutils
• Findutils
• grep
• sed
• awk
• tar
• unzip
• gzip
• tree
• less
• vim
• nano

⁠Python

Python 3 is included for custom diagnostics, automation, API testing, and troubleshooting.

Installed Python packages:

• requests
• urllib3
• httpx
• aiohttp
• psutil
• rich
• click
• pyyaml
• python-dateutil
• dnspython
• netaddr

Example:

import requests
import urllib3
import httpx
import aiohttp
import psutil
import dns
import netaddr

⁠Fail2ban

The upstream 3x-ui Docker image already includes and manages Fail2ban.

This image does not replace or redesign the upstream Fail2ban setup.

The original 3x-ui entrypoint is preserved so that the upstream Fail2ban initialization and 3x-ipl jail behavior continue to be handled by 3x-ui itself.

For the upstream implementation, see:

https://github.com/MHSanaei/3x-ui/blob/main/DockerEntrypoint.sh⁠

⁠Network Debugging

⁠DNS

dig google.com

nslookup google.com

⁠ICMP

ping 1.1.1.1

⁠Route Analysis

ip route

mtr -r -c 10 1.1.1.1

traceroute 1.1.1.1

⁠TCP

nc -zv example.com 443

ss -lntup

⁠TLS

openssl s_client \
  -connect example.com:443 \
  -servername example.com

⁠HTTP / HTTPS

curl -Iv https://example.com

⁠Packet Capture

tcpdump -ni eth0

⁠Interface Monitoring

iftop -i eth0

⁠Throughput Testing

iperf3 -c <server>

Reverse throughput test:

iperf3 -c <server> -R

⁠Packet Capture Capabilities

tcpdump and iftop are configured with:

cap_net_raw
cap_net_admin

These file capabilities allow the tools to request the capabilities required for packet and interface-level diagnostics.

The entire container does not need to be converted into a dedicated privileged debug process just to run these tools.

For Docker, the runtime should still provide:

cap_add:
  - NET_ADMIN
  - NET_RAW

Example:

docker run --rm -it \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  ariankeshavarz/3x-ui:latest

⁠Docker Compose

Example:

services:
  3xui:
    image: ariankeshavarz/3x-ui:latest

    container_name: 3xui_app

    cap_add:
      - NET_ADMIN
      - NET_RAW

    volumes:
      - $PWD/db/:/etc/x-ui/
      - $PWD/cert/:/root/cert/

    environment:
      XRAY_VMESS_AEAD_FORCED: "false"
      XUI_ENABLE_FAIL2BAN: "true"

    tty: true

    ports:
      - "2053:2053"

    restart: unless-stopped

For PostgreSQL, use the same upstream 3x-ui database configuration documented by the official project.

⁠Kubernetes / KaaS

The primary benefit of this image is troubleshooting directly from the same Pod and network namespace where 3x-ui is running.

Example:

kubectl exec -it <pod-name> -- /bin/bash

Then:

dig example.com

mtr -r -c 10 example.com

ss -lntup

tcpdump -ni eth0

iftop -i eth0

iperf3 -c <server>

This makes it possible to investigate problems without deploying a separate troubleshooting container.

Typical use cases include:

• DNS failures
• Routing problems
• Packet loss
• TCP connection failures
• TLS handshake issues
• HTTP/HTTPS connectivity
• Bandwidth and throughput testing
• Unexpected network behavior between replicas
• Container-level network troubleshooting

⁠System Troubleshooting

The same container can also be used to investigate resource-related problems.

Examples:

ps aux

top

htop

btop

free -h

vmstat 1

ip addr

ip route

ss -s

⁠Verified Debug Toolkit

The following tools were verified in the built image:

⁠Real Network Tests

The built image was exercised with:

• DNS resolution
• HTTP/HTTPS requests
• TLS/OpenSSL
• MTR route analysis
• TCP packet capture
• Interface traffic monitoring
• iperf3 throughput testing

Example observed throughput:

iperf3 reverse test
~1.52 Gbit/s

⁠Upstream 3x-ui Runtime

The image preserves the upstream 3x-ui startup behavior rather than replacing it.

The official project uses:

ENTRYPOINT ["/app/DockerEntrypoint.sh"]
CMD ["./x-ui"]

and the debug image keeps this behavior intact.

The upstream Dockerfile can be found here:

https://github.com/MHSanaei/3x-ui/blob/main/Dockerfile⁠

The upstream entrypoint can be found here:

https://github.com/MHSanaei/3x-ui/blob/main/DockerEntrypoint.sh⁠

⁠Security Notes

• The 3x-ui application itself is not modified.
• The upstream 3x-ui entrypoint is preserved.
• No separate Xray Core binary is added by this debug image.
• tcpdump and iftop receive only the required file capabilities.
• Packet capture capabilities are still subject to Docker/Kubernetes runtime policy.
• Debug tools are not executed automatically during container startup.

⁠Why This Image?

The standard 3x-ui container is designed to run the panel and its normal runtime components.

When a network problem occurs, however, you often need to answer questions such as:

Is DNS working?

Is the route changing?

Is there packet loss?

Can I reach the destination on TCP?

Is TLS working?

What is actually happening on the interface?

How much throughput can this container achieve?

Without troubleshooting utilities inside the container, you may need to deploy another debugging container or move the investigation to the host.

This image puts the required tools next to the 3x-ui workload itself.

That makes it useful for:

• Docker
• Kubernetes
• KaaS
• HA deployments
• NOC operations
• Network troubleshooting
• Connectivity investigations
• Performance testing

⁠Changelog

⁠Initial Debug Image

⁠Based On

• Official 3x-ui⁠ Docker image
• Original 3x-ui startup flow preserved

⁠Added Network Tools

• curl
• wget
• bind-tools (dig, nslookup)
• ping
• traceroute
• mtr
• iproute2 (ip, ss)
• netcat
• OpenSSL
• tcpdump
• iftop
• iperf3

⁠Added System Tools

• procps
• btop
• htop
• coreutils
• findutils
• grep
• sed
• gawk
• tar
• unzip
• gzip
• tree
• vim
• nano
• less
• jq

⁠Added Python

• Python 3
• requests
• urllib3
• httpx
• aiohttp
• psutil
• rich
• click
• pyyaml
• python-dateutil
• dnspython
• netaddr

⁠Runtime

• Preserved the official 3x-ui entrypoint.
• Preserved the official 3x-ui command model.
• Preserved the upstream Fail2ban integration.
• Added packet-capture capabilities for tcpdump and iftop.