Web Cluster Configuration for 1C-Bitrix

Web Cluster Configuration for 1C-Bitrix

The "Web Cluster" module in 1C-Bitrix is not a one-click horizontal auto-scaling solution. It is a set of synchronization mechanisms that allow multiple servers to operate as a single unit: shared cache, file replication, unified sessions. Without properly configuring each component, the cluster behaves unpredictably — one node invalidates the cache while another serves stale data.

What the Web Cluster Module Includes

The cluster module (BitrixVM Enterprise or a separate license) provides:

• Node management — server registration, availability monitoring
• Load balancing — request routing between nodes
• Cache synchronization — invalidation across all nodes via shared Memcached
• File replication — synchronization of upload/ between servers
• DB replication — read/write split configuration for MySQL

Activating and Configuring Nodes

The module is installed on each node but managed through a single admin panel.

Adding a node via API:

\Bitrix\Main\Loader::includeModule('cluster');

$result = \Bitrix\Cluster\Node::add([
    'NAME'      => 'web-02',
    'HOST'      => '10.0.0.12',
    'PORT'      => 443,
    'HTTPS'     => 'Y',
    'STATUS'    => 'ACTIVE',
    'SORT'      => 100,
]);

if ($result->isSuccess()) {
    echo 'Node added: ' . $result->getId();
}

Checking node connectivity:

# Each node must be able to reach the API of the other nodes
curl -k https://10.0.0.12/bitrix/admin/cluster_check.php

Read/Write Split for the Database

The most valuable part of the cluster for high load — routing SELECT queries to replicas while INSERT/UPDATE/DELETE go to the master. Reduces master load by 60–80% with a typical read/write ratio of 10:1.

In .settings.php:

'connections' => [
    'value' => [
        'default' => [
            'className' => '\Bitrix\Main\DB\MysqlConnection',
            'host'      => 'db-master:3306',
            'database'  => 'bitrix',
            'login'     => 'bitrix',
            'password'  => 'secret',
        ],
        'slave'  => [
            'className' => '\Bitrix\Main\DB\MysqlConnection',
            'host'      => 'db-replica:3306',
            'database'  => 'bitrix',
            'login'     => 'bitrix_ro',
            'password'  => 'secret_ro',
        ],
    ],
],

The cluster module configuration specifies which queries go to which connection. Transactional queries are forcefully routed to the master regardless of the operation type.

File Synchronization via the Module

The module can synchronize files between nodes via HTTP requests to agents on each server. When a file is uploaded through the admin interface on node-1, the module automatically copies it to node-2 and node-3.

Configuring the sync agent on each node:

# nginx: restrict the sync agent from public access
location /bitrix/admin/cluster_file_sync.php {
    allow 10.0.0.0/24;  # internal network only
    deny all;
    fastcgi_pass unix:/run/php/php8.1-fpm.sock;
}

An alternative to built-in synchronization — inotify + rsync via lsyncd. Operates independently of PHP and is more reliable for large file volumes:

-- /etc/lsyncd/lsyncd.conf.lua
sync {
    default.rsync,
    source = "/var/www/bitrix/upload",
    target = "web-02:/var/www/bitrix/upload",
    delay = 1,
    rsync = {
        compress = false,
        owner = true,
        perms = true,
    }
}

Session Management in a Cluster

File-based sessions are non-functional in a cluster — requests from the same user may hit different nodes. Move sessions to Memcached or Redis:

; php.ini on all nodes (identical)
session.save_handler = memcached
session.save_path = "10.0.0.30:11211,10.0.0.31:11211"

Sticky sessions on the load balancer are a temporary solution and not recommended: when a node fails, all its users lose their sessions.

Verifying Cluster Operation

# Status of all nodes
curl http://admin:[email protected]/bitrix/admin/cluster_nodes.php?ajax=Y

# Cache invalidation test via API
php -r "
\Bitrix\Main\Loader::includeModule('cluster');
\Bitrix\Cluster\Cache::clearAll();
echo 'Cache cleared on all nodes';
"