Требования к Redis для iQChannels

Разворачивание Redis с нуля при уже установленной платформе (подключение интеграции с S3)

ℹ️ Про связь с S3: требования к Redis не зависят от подключения S3-хранилища — S3 настраивается в секции files платформы (инструкция поставляется со сборкой). Настоящий документ определяет требования к Redis-контуру.

ℹ️ Про адреса в документе: подсеть 172.28.0.0/24 и адреса 172.28.0.11–23 — пример. Выберите свободную подсеть в своей инфраструктуре и замените адреса согласованно во всех конфигах: sentinel monitor, replicaof, replica-announce-ip, sentinel_addrs, статические IP в docker-compose.

⚠️ Про режим работы: описанная конфигурация рассчитана на кластерный режим платформы (cluster_mode: enabled, несколько нод iQChannels) и соответствует кластерным конфигурациям из требований вендора. Если ваша схема развёртывания иная — конфигурацию можно адаптировать под себя (см. §3.1); критичные требования (версия, pool_size, персистентность, noeviction) обязательны в любом варианте.

---

1. Требования вендора

Требование	Значение
Версия Redis	8.2 и выше — для всех конфигураций, включая Redis Sentinel. Сверьте с требованиями конкретной версии поставляемой сборки платформы
Режим	Кластерные конфигурации платформы — Redis Sentinel (master + реплики + sentinel-ноды)
Размещение	Отдельные ВМ (или изолированный docker-контур) — не совмещать с нодами приложения

Ресурсы по тирам нагрузки (из требований вендора)

Выберите конфигурацию по ожидаемому числу активных онлайн-операторов:

Конфигурация	ВМ Redis Sentinel	vCPU (на ВМ)	RAM	Диск
До 250 операторов (~2 500 клиентов)	3	2–4	8 ГБ	10 ГБ
До 500 операторов (~5 000 клиентов)	3	4–8	12 ГБ	16 ГБ
До 5 000 операторов (~50 000 клиентов)	3+	4–8	16 ГБ	32 ГБ

Каждая ВМ несёт одну роль: master, replica или sentinel. Диск — под данные+AOF с запасом.

---

2. Целевая архитектура (кластерный режим)

                        iQChannels (несколько нод)
                              │  sentinel-протокол
              ┌───────────────┼───────────────┐
        sentinel-1       sentinel-2       sentinel-3     ← кворум 2 из 3
              └───────────────┼───────────────┘            следят за master
                       ┌──────┴──────┐
                 redis-master    (write + read)
                  ┌─────┴─────┐
           redis-replica-1  redis-replica-2        ← горячий резерв

Решение	Почему
1 master + 2 replica	Реплика переживает отказ master; sentinel поднимает её автоматическим failover
3 sentinel (кворум 2)	Сам кластер sentinel отказоустойчив; большинство нужно для решения о failover
Статические IP	Sentinel адресует ноды по неизменным IP; без этого failover ломается
Режим sentinel в платформе	Приложение само находит актуальный master после failover
RDB + AOF одновременно	Redis хранит очереди сообщений платформы — потеря данных недопустима

2.1 Варианты для иных схем развёртывания

Режим платформы	Redis-контур
Кластерный (несколько нод iQChannels)	Описанный вариант: 1 master + 2 replica + 3 sentinel
Базовый (до ~50 операторов, 1–2 ноды приложения)	Допустим один инстанс Redis; sentinel — по желанию, для отказоустойчивости

При уменьшении топологии: уберите ненужные реплики/сентинелы, в config.yaml платформы поставьте mode: single и укажите адрес инстанса. Остальные требования (версия, персистентность, пароли, maxmemory-policy noeviction, pool_size: 64) обязательны в любом варианте.

---

3. Структура файлов

/opt/new_redis/
├── docker-compose.yml
└── conf/
    ├── redis-master.conf
    ├── redis-replica-1.conf
    ├── redis-replica-2.conf
    └── sentinel.conf          # общий шаблон для всех трёх sentinel

/opt/iqchannels/
└── config.yaml                # конфиг платформы (секция redis)

---

4. Конфиги Redis

4.1 conf/redis-master.conf

port 6379
bind 0.0.0.0
protected-mode no            # допустимо при изолированной сети и отсутствии публикации портов

daemonize no                 # в контейнере демонизация не нужна
supervised no
logfile ""                   # логи в stdout → видны в docker logs
loglevel notice

dir /data                    # именованный том / раздел на диске

# Персистентность: RDB + AOF
save 900 1
save 300 10
save 60 10000
appendonly yes
appendfilename "appendonly.aof"
appendfsync everysec

# Лимит памяти — ОБЯЗАТЕЛЬНО
# maxmemory 4gb              # подбирается по RAM сервера
# maxmemory-policy noeviction  # только noeviction! Redis хранит очереди сообщений

# Пароли — ОБЯЗАТЕЛЬНО для продакшена
# requirepass <СИЛЬНЫЙ_ПАРОЛЬ>
# masterauth  <ТЕ_ЖЕ_ПАРОЛЬ>   # нужен, чтобы бывший master подключился репликой после failover

4.2 conf/redis-replica-1.conf (replica-2 — аналогично, свой announce-ip)

port 6379
bind 0.0.0.0
protected-mode no

daemonize no
supervised no
logfile ""
loglevel notice

dir /data

save 900 1
save 300 10
save 60 10000
appendonly yes
appendfilename "appendonly.aof"
appendfsync everysec

replica-read-only yes

replicaof 172.28.0.11 6379        # адрес master-ноды

# КРИТИЧНО в docker: анонсировать контейнерный IP,
# иначе sentinel увидит NAT-адрес и разорвёт репликацию
replica-announce-ip 172.28.0.12
replica-announce-port 6379

# requirepass / masterauth — те же значения, что на мастере

4.3 conf/sentinel.conf (единый шаблон для всех трёх)

port 26379
bind 0.0.0.0
protected-mode no

dir /tmp
logfile ""
loglevel notice

# имя мастер-группы должно совпадать с master_name в config.yaml платформы!
# quorum 2 = минимум 2 sentinel из 3 должны согласиться, что master упал
sentinel monitor mymaster 172.28.0.11 6379 2

sentinel down-after-milliseconds mymaster 5000   # мастер молчит 5 сек → кандидат на failover
sentinel failover-timeout mymaster 15000         # окно повтора failover
sentinel parallel-syncs mymaster 1               # сколько реплик переконфигурировать сразу

# при включённых паролях на нодах данных:
# sentinel auth-pass mymaster <ТЕ_ЖЕ_ПАРОЛЬ>

Почему sentinel запускается через копирование конфига: sentinel в рантайме перезаписывает свой конфиг (фиксирует топологию после failover). Шаблон подключён read-only, поэтому стартуют от копии: sh -c "cp /etc/redis/sentinel.conf /tmp/sentinel.conf && redis-sentinel /tmp/sentinel.conf"

Тюнинг: при ложных срабатываниях в медленных сетях увеличить down-after-milliseconds до 10000–15000.

4.4 docker-compose.yml — фрагмент Redis-части

services:
  redis-master:
    image: redis:8-alpine          # версия 8.2+; при развёртывании на ВМ — пакет redis >= 8.2
    container_name: redis-master
    command: redis-server /usr/local/etc/redis/redis.conf
    volumes:
      - /opt/new_redis/conf/redis-master.conf:/usr/local/etc/redis/redis.conf:ro
      - data-master:/data
    networks:
      redis-net:
        ipv4_address: 172.28.0.11
    restart: unless-stopped

  redis-replica-1:                   # replica-2 аналогично
    image: redis:8-alpine
    container_name: redis-replica-1
    command: redis-server /usr/local/etc/redis/redis.conf
    volumes:
      - /opt/new_redis/conf/redis-replica-1.conf:/usr/local/etc/redis/redis.conf:ro
      - data-replica-1:/data
    depends_on:
      - redis-master
    networks:
      redis-net:
        ipv4_address: 172.28.0.12
    restart: unless-stopped

  sentinel-1:                        # sentinel-2/3 аналогично
    image: redis:8-alpine
    container_name: redis-sentinel-1
    command: sh -c "cp /etc/redis/sentinel.conf /tmp/sentinel.conf && redis-sentinel /tmp/sentinel.conf"
    volumes:
      - /opt/new_redis/conf/sentinel.conf:/etc/redis/sentinel.conf:ro
    depends_on:
      - redis-master
      - redis-replica-1
      - redis-replica-2
    networks:
      redis-net:
        ipv4_address: 172.28.0.21
    restart: unless-stopped

volumes:
  data-master:
  data-replica-1:
  data-replica-2:

networks:
  redis-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/24     # ЗАМЕНИТЕ на свою свободную подсеть

Важно:

• Порты Redis наружу не публикуются — доступ только из внутренней сети платформы.
• При развёртывании на отдельных ВМ (по требованиям вендора) конфиги те же, минус docker-специфика (replica-announce-ip оставьте с реальным IP ноды); порты между ВМ закрыть firewall-правилами по адресам нод платформы.

---

5. Подключение существующей платформы к новому Redis

5.1 Секция redis в /opt/iqchannels/config.yaml

redis:
 mode: sentinel              # для одиночного инстанса — single и адрес в single_addr
 master_name: mymaster       # ДОЛЖЕН совпадать с именем в sentinel monitor!
 sentinel_addrs:             # все три адреса — не один!
   - 172.28.0.21:26379
   - 172.28.0.22:26379
   - 172.28.0.23:26379
 route_randomly: false       # всегда false: чтения только из master — консистентность
 route_by_latency: false     # всегда false: в sentinel-режиме работа через master
 pool_size: 64               # КРИТИЧНО — см. §6, п.1
 l1cache:
  enabled: true
  tables:
   sys_queue_messages:
    enabled: false
   notification_inboxes:
    enabled: false
   chat_sse_connections:
    enabled: false
 l0cache:
  enabled: true
  tables:
   sys_queue_consumers:
    enabled: false

5.2 Процедура переключения (окно обслуживания)

1. Убедиться, что новый Redis развёрнут и пуст: на master-ноде redis-cli DBSIZE → 0
2. Остановить ноды iQChannels (docker stop iqc1 iqc2 ... или сервис)
3. Внести изменения в config.yaml (секция redis из §5.1)
4. Запустить ноды платформы
5. Проверить логи: docker logs iqc1 --since 5m | grep -iE 'redis|sentinel' — без ошибок
6. Индексы и кэши платформа построит на пустом Redis автоматически при старте

Если ранее использовался другой Redis и в нём могли остаться незавершённые сообщения очередей — до переключения убедиться, что очереди выработаны (дождаться обработки или перенести), иначе незавершённые задания будут потеряны.

---

6. Обязательные шаги при передаче/обновлении сборки платформы

1. pool_size: 64 в config.yaml (секция redis) — безусловно, для любой топологии. Без него система долго запускается и не срабатывает close_ticket.

2. Очистка индексов Redis перед запуском — только при обновлении существующей установки или если Redis уже содержит данные:

• кластер/sentinel: подключиться redis-cli к мастер-ноде и выполнить:

  SELECT 0
  FLUSHDB ASYNC
  (мастер найти: redis-cli -h <sentinel> -p 26379 sentinel get-master-addr-by-name mymaster)
• если Redis выделен только под iQChannels — достаточно FLUSHALL ASYNC
• при установке Redis с нуля (пустой инстанс) очистка не требуется — достаточно убедиться, что DBSIZE = 0 (см. §5.2 п.1)

3. На случай ухудшения работы системы после обновления: отключить доработки по autocommit — в config.yaml, раздел db, поставить read_autocommit: false. При штатной работе оставить true. Перед откатом на предыдущую версию платформы — выполнить очистку Redis из п. 2.

---

7. Проверка после развёртывания

# 1. Репликация: ожидаем role:master, connected_slaves:2, обе online
docker exec redis-master redis-cli info replication | grep -E 'role|connected_slaves|slave[0-9]'
# (на ВМ: redis-cli -h <master> info replication | ...)

# 2. Sentinel видит мастера: ожидаем flags:master
docker exec redis-sentinel-1 redis-cli -p 26379 sentinel masters | head -20

# 3. Запись появляется на реплике
docker exec redis-master redis-cli set testkey ok
docker exec redis-replica-1 redis-cli --no-raw get testkey

# 4. Платформа подключилась: в логах нет ошибок redis
docker logs iqc1 --since 5m 2>&1 | grep -iE 'redis|sentinel' | tail

8. Тестовый failover (обязателен перед приёмкой)

docker exec redis-sentinel-1 redis-cli -p 26379 sentinel failover mymaster

# Через ~15 секунд одна из реплик стала master:
docker exec redis-replica-1 redis-cli info replication | grep role
docker exec redis-replica-2 redis-cli info replication | grep role

# Платформа продолжает работать без перезапуска (sentinel-клиент переключился сам):
docker logs iqc1 --since 2m 2>&1 | grep -iE 'failover|switch|master' | tail

Мониторинг (алерты по метрикам redis-exporter):

• смена роли мастера (redis_master != 1 у ожидаемой ноды);
• redis_connected_slaves < 2 — потеря реплики;
• redis_memory_used_bytes > 80% maxmemory;
• статус RDB/AOF (redis_rdb_last_bgsave_status, AOF last write) != ok.