Обновление кластера
Apache Doris поддерживает поэтапное обновление путём последовательной замены бинарных файлов на узлах FE и BE. Это сводит к минимуму время простоя и сохраняет доступность кластера во время обновления. Этот документ предназначен для администраторов кластеров и описывает правила совместимости версий, процедуру проверки совместимости метаданных и подробные шаги обновления.
Сценарии применения
| Сценарий | Применимость | Примечания |
|---|---|---|
| Обновление версии исправлений в пределах одной минорной версии (например, с 2.1.3 до 2.1.7) | Да | Поэтапное обновление можно выполнить напрямую |
| Обновление между минорными версиями (например, с 3.0 до 3.3) | Да, последовательно | Обновляйте по порядку: с 3.0 до 3.1, с 3.1 до 3.2, с 3.2 до 3.3 |
| Обновление мажорной версии (например, с 2.x до 3.x) | Да, последовательно | Прямое обновление между мажорными версиями не рекомендуется; обновляйте последовательно, переходя от одной минорной версии к следующей |
| Обновление кластера с одним узлом FE | Да, после проверки совместимости | Сначала расширьте кластер до отказоустойчивой конфигурации с 3 узлами FE либо выполните проверку совместимости метаданных перед обновлением |
| Обновление между версиями с потенциально несовместимыми метаданными | Да, после проверки совместимости | Перед обновлением необходимо проверить совместимость метаданных |
Предварительные требования
Перед обновлением убедитесь в следующем:
- Вы прочитали примечания к выпуску целевой версии и понимаете изменения в поведении и совместимость между версиями.
- Данные хранятся с 3 репликами, чтобы сбой обновления не привёл к потере данных.
- В клиентских задачах предусмотрены повторные попытки (см. раздел «Что следует учитывать при обновлении» ниже).
- Для проверки совместимости метаданных доступна машина для разработки или узел BE.
- Установочный пакет целевой версии скачан и распакован (в приведённых ниже шагах
${DORIS_NEW_HOME}обозначает корневой каталог новой версии, а${DORIS_OLD_HOME}обозначает корневой каталог старой версии, работающей в промышленной среде).
Совместимость версий
Номер версии Doris состоит из трёх чисел. Первое число обозначает основной этап развития, второе указывает версию с новыми функциями, а третье указывает версию с исправлениями ошибок. В выпусках, меняющих только третье число, новые функции не появляются. Рассмотрим Doris 2.1.3:
| Позиция | Пример значения | Значение |
|---|---|---|
| Первое число | 2 | 2-й основной этап развития |
| Второе число | 1 | Версия с новыми функциями в рамках этого этапа |
| Третье число | 3 | 3-й выпуск исправлений для этой функциональной версии |
При обновлении соблюдайте следующие правила:
| Тип обновления | Поддерживается ли пропуск версий | Рекомендуемый путь |
|---|---|---|
| Изменение третьего числа (при неизменном втором числе) | Поддерживается | Обновляйте напрямую, например с 2.1.3 до 2.1.7 |
| Изменение второго числа | Пропуск версий не рекомендуется | Обновляйте последовательно, переходя от одной версии по второму числу к следующей, например с 3.0 до 3.1, затем до 3.2 и до 3.3 |
| Изменение первого числа | Пропуск версий не рекомендуется | Сначала обновитесь до последней версии по второму числу в пределах текущего первого числа, затем переходите на следующую мажорную версию |
Подробную информацию о версиях см. в разделе Правила нумерации версий.
Что следует учитывать при обновлении
Перед обновлением обратите внимание на следующие три момента:
| Особенность | Что делать |
|---|---|
| Изменения в поведении между версиями | Перед обновлением прочитайте примечания к выпуску целевой версии и проверьте, есть ли несовместимые изменения в поведении |
| Повторные попытки клиентских задач | Во время обновления узлы перезапускаются по очереди, поэтому для задач Stream Load и выполнения запросов необходимо добавить повторные попытки. В Routine Load, Flink Doris Connector и Spark Doris Connector повторные попытки уже предусмотрены, поэтому дополнительных действий не требуется |
| Восстановление и балансировка реплик | Перед обновлением необходимо отключить восстановление и балансировку реплик. После завершения обновления их необходимо включить снова независимо от того, завершилось ли обновление успешно |
Для обновления Doris достаточно заменить каталоги /bin и /lib в каталоге FE, а также каталоги /bin и /lib в каталоге BE.
В версиях 2.0.2 и новее в каталогах развёртывания FE и BE появился каталог custom_lib/ (создайте его вручную, если он отсутствует). Он предназначен для хранения пользовательских сторонних jar-файлов, например hadoop-lzo-*.jar и orai18n.jar. При обновлении заменять этот каталог не требуется.
Проверка совместимости метаданных
Проверка совместимости метаданных позволяет до обновления убедиться, что новая версия корректно загружает существующие метаданные, и тем самым предотвратить потерю данных при сбое обновления. Рекомендуется выполнять эту проверку перед каждым обновлением.
В промышленной среде рекомендуется использовать отказоустойчивую конфигурацию с 3 или более узлами FE. Если имеется только 1 узел FE, перед обновлением обязательно выполните проверку совместимости метаданных. Совместимость метаданных критически важна: если обновление завершится неудачей из-за несовместимости метаданных, возможна потеря данных.
Также учитывайте следующее:
- Рекомендуется выполнять проверку совместимости метаданных на машине для разработки или узле BE и избегать её выполнения на узле FE.
- Если проверку можно выполнить только на узле FE, выберите узел, не являющийся Master, и сначала остановите на нём исходный процесс FE.
1. Создайте резервную копию метаданных
Перед началом обновления создайте резервную копию метаданных узла Master FE.
Узел Master FE можно определить по столбцу IsMaster в выводе show frontends. Резервную копию метаданных FE можно создать без остановки процесса FE. По умолчанию метаданные FE хранятся в каталоге fe/doris-meta; путь к каталогу метаданных также можно уточнить по параметру meta_dir в fe.conf.
2. Измените файл конфигурации FE для проверки
Отредактируйте fe.conf в тестовой среде:
vi ${DORIS_NEW_HOME}/conf/fe.conf
Установите для всех портов значения, отличающиеся от значений в промышленной среде, и измените параметр clusterId:
...
## modify port
http_port = 18030
rpc_port = 19020
query_port = 19030
arrow_flight_sql_port = 19040
edit_log_port = 19010
## modify clusterIP
clusterId=<a_new_clusterID, such as 123456>
...
Примеры портов для тестовой среды:
| Параметр | Пример значения | Описание |
|---|---|---|
http_port | 18030 | Порт HTTP-службы FE |
rpc_port | 19020 | Порт Thrift Server FE |
query_port | 19030 | Порт запросов FE по протоколу MySQL |
arrow_flight_sql_port | 19040 | Порт Arrow Flight SQL |
edit_log_port | 19010 | Порт взаимодействия FE BDBJE |
clusterId | 123456 | Идентификатор тестового кластера; должен отличаться от идентификатора промышленного кластера |
3. Скопируйте метаданные Master FE
Скопируйте резервную копию метаданных Master FE в новую среду для проверки совместимости:
cp ${DORIS_OLD_HOME}/fe/doris-meta/* ${DORIS_NEW_HOME}/fe/doris-meta
4. Измените cluster_id в файле метаданных VERSION
Измените cluster_id в файле VERSION в скопированном каталоге метаданных на новый идентификатор кластера, например 123456, как в примере выше:
vi ${DORIS_NEW_HOME}/fe/doris-meta/image/VERSION
clusterId=123456
5. Запустите процесс FE в тестовой среде
sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon --metadata_failure_recovery
В версиях до 2.0.2 сначала добавьте metadata_failure_recovery=true в fe.conf, затем запустите процесс FE:
echo "metadata_failure_recovery=true" >> ${DORIS_NEW_HOME}/conf/fe.conf
sh ${DORIS_NEW_HOME}/bin/start_fe.sh --daemon
6. Убедитесь, что FE успешно запущен
Подключитесь к тестовому FE через клиент MySQL, используя query_port 19030 из примера выше:
mysql -uroot -P19030 -h127.0.0.1
Если подключение успешно, новая версия корректно загружает текущие метаданные и проверка совместимости метаданных пройдена.
Общий порядок обновления
Полный процесс обновления состоит из следующих шагов, которые необходимо выполнять строго по порядку:
- Отключите восстановление и балансировку реплик.
- Обновите узлы BE (в кластере с несколькими репликами можно выполнить канареечное обновление).
- Обновите узлы FE (сначала узлы Observer/Follower, затем Master).
- Снова включите восстановление и балансировку реплик.
Общий принцип: сначала обновляйте BE, затем FE. При обновлении FE сначала обновляйте узлы Observer FE и Follower FE, а узел Master FE обновляйте последним.
Шаги обновления
Шаг 1: отключите восстановление и балансировку реплик
Во время обновления узлы перезапускаются, что может вызвать ненужную балансировку кластера и восстановление реплик. Сначала отключите эти механизмы с помощью следующих трёх параметров:
admin set frontend config("disable_balance" = "true");
admin set frontend config("disable_colocate_balance" = "true");
admin set frontend config("disable_tablet_scheduler" = "true");
Используются следующие параметры:
| Параметр | Значение перед обновлением | Действие |
|---|---|---|
disable_balance | true | Отключает балансировку реплик, предотвращая их перемещение из-за перезапуска узлов |
disable_colocate_balance | true | Отключает балансировку реплик для таблиц Colocate Join |
disable_tablet_scheduler | true | Отключает планирование tablet, предотвращая восстановление реплик |
Шаг 2: обновите узлы BE
Для сохранности данных храните их с 3 репликами, чтобы избежать потери данных из-за ошибочных действий или сбоев при обновлении.
В кластере с несколькими репликами можно выбрать один узел BE для канареечного обновления. После проверки обновите остальные узлы по одному.
2.1 Остановите обновляемый узел BE
sh ${DORIS_OLD_HOME}/be/bin/stop_be.sh
2.2 Создайте резервные копии существующих каталогов /bin и /lib
mv ${DORIS_OLD_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin_back
mv ${DORIS_OLD_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib_back
2.3 Скопируйте каталоги /bin и /lib новой версии
cp -r ${DORIS_NEW_HOME}/be/bin ${DORIS_OLD_HOME}/be/bin
cp -r ${DORIS_NEW_HOME}/be/lib ${DORIS_OLD_HOME}/be/lib
2.4 Запустите узел BE
sh ${DORIS_OLD_HOME}/be/bin/start_be.sh --daemon
2.5 Проверьте обновление
Подключитесь к кластеру и проверьте информацию об узлах:
show backends\G
Если статус Alive узла BE равен true, а значение Version соответствует новой версии, узел успешно обновлён. Убедившись в этом, таким же образом обновите остальные узлы BE по одному.
Шаг 3: обновите узлы FE
Если узлов FE несколько, сначала обновите узлы, не являющиеся Master (Observer или Follower), а узел Master обновите последним, когда все остальные уже обновлены.
3.1 Остановите обновляемый узел FE
sh ${DORIS_OLD_HOME}/fe/bin/stop_fe.sh
3.2 Создайте резервные копии существующих каталогов
Создайте резервные копии трёх каталогов: /bin, /lib и /mysql_ssl_default_certificate:
mv ${DORIS_OLD_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin_back
mv ${DORIS_OLD_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib_back
mv ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate_back
3.3 Скопируйте каталоги новой версии
cp -r ${DORIS_NEW_HOME}/fe/bin ${DORIS_OLD_HOME}/fe/bin
cp -r ${DORIS_NEW_HOME}/fe/lib ${DORIS_OLD_HOME}/fe/lib
cp -r ${DORIS_NEW_HOME}/fe/mysql_ssl_default_certificate ${DORIS_OLD_HOME}/fe/mysql_ssl_default_certificate
3.4 Запустите узел FE
sh ${DORIS_OLD_HOME}/fe/bin/start_fe.sh --daemon
3.5 Проверьте обновление
Подключитесь к кластеру и проверьте информацию об узлах:
show frontends\G
Если статус Alive узла FE равен true, а значение Version соответствует новой версии, узел успешно обновлён.
3.6 Обновите остальные узлы FE по одному
Таким же образом обновите остальные узлы FE, не являющиеся Master, по одному и обновите узел Master FE последним.
Шаг 4: снова включите восстановление и балансировку реплик
После завершения обновления, когда статус Alive всех узлов BE снова станет true, включите восстановление и балансировку реплик кластера:
admin set frontend config("disable_balance" = "false");
admin set frontend config("disable_colocate_balance" = "false");
admin set frontend config("disable_tablet_scheduler" = "false");
Примечания по обновлению до отдельных версий
В этом разделе перечислены изменения в поведении, требующие особого внимания при обновлении до конкретной версии. Помимо этого раздела, всегда читайте примечания к выпуску целевой версии, чтобы ознакомиться с полным списком изменений.
Миграция переменных сеанса при обновлении с 3.x до 4.0
FE отслеживает ход миграции значений по умолчанию переменных сеанса с помощью внутренней переменной variable_version. При обновлении с 3.x до 4.0 (variable_version меньше 400) FE автоматически изменяет глобальные значения по умолчанию следующих переменных:
| Переменная | Значение по умолчанию после миграции | Описание |
|---|---|---|
enable_ansi_query_organization_behavior | false | Сохраняет поведение организации запросов из 3.x, чтобы семантика не изменилась после обновления |
enable_new_type_coercion_behavior | false | Сохраняет поведение приведения типов из 3.x |
enable_sql_cache | true | Включает SQL Cache |
enable_nereids_distribute_planner | true | Этот пункт миграции добавлен в версии 4.0.8, см. ниже |
Миграция выполняется только один раз, когда variable_version повышается со значения ниже 400 до 400. Она никогда не перезаписывает значение, которое пользователь явно установил после этого.
Обновление до 4.0.8
Начиная с версии 4.0.8 при обновлении с 3.x до 4.0 включается планировщик распределения Nereids (enable_nereids_distribute_planner).
До 4.0.8, если в образе метаданных кластера было сохранено enable_nereids_distribute_planner=false, после обновления это значение восстанавливалось без изменений, и кластер продолжал использовать прежний планировщик распределения. В версии 4.0.8 переменная добавлена в миграцию variable_version=400, поэтому после обновления новый планировщик распределения включается во всех таких случаях.
Если распределение плана запроса отличается от того, что было до обновления, можно вернуть прежнее поведение командой SET GLOBAL enable_nereids_distribute_planner = false; и сообщить о затронутых запросах.
При обновлении до 4.0.8 также обратите внимание на следующие изменения:
| Изменение | Область влияния | Что делать |
|---|---|---|
Компактация больше не приостанавливается при высоком потреблении памяти (значение по умолчанию параметра BE enable_compaction_pause_on_high_memory меняется с true на false) | Все режимы развёртывания | Верните значение true, чтобы сохранить прежнее поведение. См. Конфигурация BE |
Минимальное количество автоматически создаваемых бакетов увеличено с 1 до 3 (параметр FE autobucket_min_buckets) | Таблицы, создаваемые с BUCKETS AUTO | Изменение затрагивает только вновь создаваемые разделы. См. Распределение данных по бакетам |
Конечная точка BE _stream_load_forward требует включения соответствующего параметра и аутентификации запросов | Развёртывания, использующие переадресацию Group Commit через BE в режиме разделения вычислений и хранения | Установите enable_group_commit_streamload_be_forward=true в каждом be.conf и убедитесь, что учётная запись загрузки данных имеет глобальную привилегию LOAD. См. Group Commit |
API управления узлами требуют глобальной привилегии ADMIN | Автоматизация, вызывающая /rest/v2/manager/node/{action}/{be|fe|broker} | Добавьте аутентификацию с учётной записью ADMIN в вызывающий код. См. Действия с узлами |
| Stream Load проверяет доступ учётной записи к вычислительной группе, которая фактически обслуживает запрос | Stream Load в режиме разделения вычислений и хранения | Предоставьте учётной записи загрузки данных доступ к соответствующей вычислительной группе. См. Stream Load |
| В режиме разделения вычислений и хранения размер данных всегда указывается как объём удалённых данных | Скрипты, вычисляющие ёмкость по SHOW TABLETS или information_schema.partitions | Используйте REMOTE_DATA_SIZE. См. partitions |
Конфиденциальные свойства Kafka в заданиях Routine Load маскируются как ****** в результатах запросов | Скрипты, считывающие учётные данные из SHOW ROUTINE LOAD | Получайте исходные значения из своей системы управления конфигурацией. См. SHOW ROUTINE LOAD |
Формат временных меток прогрева меняется с HH:mm:ss на yyyy-MM-dd HH:mm:ss | Скрипты, разбирающие статус заданий прогрева | Измените формат разбора времени. См. Разделение чтения и записи |
Ошибки сканирования больше не содержат префикс failed to initialize storage reader | Правила мониторинга, сопоставляющие ошибки по этому префиксу | Используйте код ошибки и информацию tablet= / backend= |
Обновление до 4.1.4
Начиная с версии 4.1.4 при обновлении с 3.x до 4.1.4 глобальное значение по умолчанию переменной сеанса enable_nereids_distribute_planner устанавливается в true. В серии 4.0 такое поведение действует с 4.0.8.
Это изменение происходит только тогда, когда значение variable_version кластера ниже 400, поэтому кластер, уже работающий на 4.0.x или 4.1.x, сохраняет ранее записанное значение этой переменной.
Если распределение плана запроса отличается от того, что было до обновления, можно вернуть прежнее поведение командой SET GLOBAL enable_nereids_distribute_planner = false; и сообщить о затронутых запросах.
Начиная с версии 4.1.4 при преобразовании значения FLOAT / DOUBLE в строку формируется самая короткая строка, которая при обратном преобразовании даёт то же значение, вместо строки с фиксированным количеством значащих цифр. Сохранённое значение не меняется, но его текстовое представление может отличаться от 4.1.3 (например, 246.9120025634766 превращается в 246.91200256347656, а 0.0000123456 превращается в 1.23456e-05).
Это затрагивает результаты запросов по протоколу MySQL, CAST(... AS STRING), отображение сложных типов / JSON / VARIANT, SELECT INTO OUTFILE, EXPORT и столбцы с плавающей точкой во внешних таблицах. Если последующая система обработки сравнивает строковые представления значений с плавающей точкой на точное совпадение, скорректируйте её после обновления. См. Типы с плавающей точкой.
При обновлении до 4.1.4 также обратите внимание на следующие изменения:
Удалённые интерфейсы и синтаксис
| Изменение | Область влияния | Что делать |
|---|---|---|
Табличная функция iceberg_meta() удалена | SQL, считывающий метаданные Iceberg через эту табличную функцию | Используйте системные таблицы Iceberg <table>$<system_table_name>. См. ICEBERG_META |
Конечные точки FE /api/<ns>/<db>/<tbl>/upload удалены вместе с параметром FE http_load_submitter_max_worker_threads | Скрипты, отправляющие небольшие файлы для загрузки данных через эти конечные точки | Используйте Stream Load или TVF S3 / HDFS / LOCAL. См. Отправка файлов |
Оператор PLAN REPLAYER PLAY '<file>' удалён | Процессы отладки, воспроизводящие minidump | Остался только PLAN REPLAYER DUMP |
Действие set_session_variable удалено из политик рабочих нагрузок | Политики рабочих нагрузок, использующие это действие | Используйте cancel_query / move_query_to_group |
Параметр BE get_stack_trace_tool удалён, а поля HTTP-вывода стеков потоков BE изменены | Скрипты, собирающие стеки потоков BE | Разбирайте новые поля вывода |
Параметр BE s3_client_retry_slow_down удалён в режиме разделения вычислений и хранения | Развёртывания, использующие его для управления повторными попытками при ограничении запросов S3 | Настройка не требуется: BE теперь всегда повторяет запросы при ответах S3 429 / 503, а Recycler никогда не выполняет повторные попытки |
Таймер HdfsIO и его семь счётчиков удалены из профиля запроса | Автоматизация, разбирающая профиль | Используйте другие счётчики, связанные с вводом-выводом |
Изменения значений по умолчанию и поведения
| Изменение | Область влияния | Что делать |
|---|---|---|
Минимальное количество автоматически создаваемых бакетов увеличено с 1 до 3 (параметр FE autobucket_min_buckets) | Таблицы, создаваемые с BUCKETS AUTO | Изменение затрагивает только вновь создаваемые разделы. См. Распределение данных по бакетам |
Значение по умолчанию переменной сеанса max_scanners_concurrency меняется с 4 на 8 | Все запросы | Верните значение 4, чтобы сохранить прежнее поведение |
Значение по умолчанию параметра FE default_get_version_from_ms_timeout_second меняется с 3 на 30 | Режим разделения вычислений и хранения | Ничего делать не нужно; это уменьшает число сбоев запросов из-за колебаний времени отклика Meta Service |
Значение по умолчанию параметра BE enable_cache_read_from_peer меняется с true на false, а параметр cache_read_from_peer_expired_seconds удалён | Развёртывания, использующие чтение из кеша других узлов между вычислительными группами | Явно установите enable_cache_read_from_peer=true в be.conf, чтобы сохранить прежнее поведение |
Переменная сеанса eager_aggregation_on_join удалена; добавлены eager_aggregation_on_broadcast_join (по умолчанию true) и eager_agg_broadcast_row_count (по умолчанию 250000) | Сеансы / скрипты, устанавливающие eager_aggregation_on_join | Удалите присваивания этой переменной |
В табличной функции jobs() столбец потокового задания Lag переименован в LagBytes, а его единица измерения изменена с секунд на байты; добавлен столбец LastSourceEventTimestamp | Скрипты, разбирающие вывод jobs(), и мониторинг на основе метрики streaming_job_per_job_lag | Используйте столбец LagBytes и метрику streaming_job_per_job_lag_bytes. См. Непрерывная загрузка |
Arrow Flight SQL возвращает DATETIME / DATETIMEV2 как Arrow Timestamp без часового пояса (TIMESTAMPTZ по-прежнему учитывает часовой пояс) | Клиенты, считывающие столбцы времени через Arrow Flight SQL | Интерпретируйте значения без часового пояса |
Агрегатная функция, содержащая другую агрегатную функцию в любом из своих аргументов, теперь возвращает ошибку aggregate function cannot contain aggregate parameters | Существующий SQL, например group_concat(x ORDER BY sum(k)) | Перепишите SQL так, чтобы сначала выполнялась агрегация, а затем использовался её результат |
Изменение default.replication_num или default.replication_allocation теперь удаляет конфликтующее устаревшее свойство | Старые таблицы, в метаданных которых всё ещё присутствуют оба свойства | Никаких действий не требуется. SHOW CREATE TABLE и фактическое распределение реплик теперь согласованы. Во время поэтапного обновления изменяйте эти два свойства только после обновления всех FE, иначе старые и новые FE могут применить разные настройки реплик |
Свойства Catalog Paimon paimon.table-option.* ограничены списком из семи разрешённых ключей | Catalog, использующие другие ключи paimon.table-option.* | Удалите ключи, не входящие в список разрешённых. См. Paimon Catalog |
В свойства хранения добавлен зарезервированный ключ doris.fs.cache.key, а неявное значение по умолчанию fs.<schema>.impl.disable.cache=true больше не применяется | Catalog / TVF, использующие внешнее хранилище | Обновляйте узлы BE раньше узлов FE |
В режиме разделения вычислений и хранения ADMIN SET FRONTEND CONFIG доступен только пользователю root | Скрипты, меняющие параметры FE во время работы с учётной записью, отличной от root | Используйте учётную запись root либо задавайте параметры в fe.conf |
Параметры FE s3_load_endpoint_white_list, jdbc_driver_url_white_list и force_sqlserver_jdbc_encrypt_false больше нельзя изменять во время работы | Скрипты, меняющие эти параметры через ADMIN SET FRONTEND CONFIG | Задайте их в fe.conf и перезапустите FE |
Конфиденциальные свойства Kafka в Routine Load, а также столбцы IV / CIPHER ключей шифрования в information_schema маскируются как ****** в результатах запросов | Скрипты, считывающие учётные данные из этих результатов | Получайте исходные значения из своей системы управления конфигурацией |
Изменения развёртывания и файлов конфигурации
| Изменение | Область влияния | Что делать |
|---|---|---|
Для JDK 17 в JAVA_OPTS необходимо заменить --add-opens=java.base/java.nio=ALL-UNNAMED на --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED | Развёртывания с пользовательским значением JAVA_OPTS_FOR_JDK_17 в fe.conf / be.conf | Перенесите эту опцию из fe.conf / be.conf, поставляемых в пакете нового выпуска. Иначе функции на основе Arrow, например Arrow Flight SQL, могут не запуститься или работать со сбоями |
Модуль paimon-scanner в be-java-extensions переименован в paimon-connector | Пользовательские скрипты развёртывания, ссылающиеся на be/lib/java_extensions/paimon-scanner | Измените путь на paimon-connector |
Конечная точка BE _stream_load_forward требует включения соответствующего параметра и аутентификации запросов | Развёртывания, использующие переадресацию Group Commit через BE в режиме разделения вычислений и хранения | Установите enable_group_commit_streamload_be_forward=true в каждом be.conf и убедитесь, что учётная запись загрузки данных имеет глобальную привилегию LOAD. См. Group Commit |
Обновление до 4.1.5
Следующие изменения приведены относительно 4.1.4.1. Перед обновлением проверьте настройки инвертированных индексов V1, сопоставления типов внешних таблиц и файлы с историческими датами.
Удалённые интерфейсы и синтаксис
| Изменение | Область влияния | Что делать |
|---|---|---|
| Создание инвертированных индексов V1 запрещено; в существующие таблицы V1 нельзя добавлять новые инвертированные индексы | CREATE TABLE, CREATE INDEX и ALTER TABLE ADD INDEX | Для новых таблиц используйте V2 или V3. Существующие таблицы остаются доступными для чтения. Если нужны новые индексы, пересоздайте таблицу; ALTER TABLE не может преобразовать её формат хранения |
Пользовательские функции больше не принимают сигнатуры с переменным числом аргументов ... | UDF, UDAF и UDTF на Java / Python, а также ALIAS FUNCTION | Используйте фиксированное число параметров или один параметр ARRAY для передачи нескольких значений. См. CREATE FUNCTION |
Формат файлов native удалён | Чтение или экспорт файлов в этом формате | Используйте поддерживаемый формат, например Parquet или ORC. Перед обновлением преобразуйте старые файлы с помощью предыдущей версии Doris |
Изменения значений по умолчанию и поведения
| Изменение | Область влияния | Что делать |
|---|---|---|
Двоичные типы Catalog всегда сопоставляются с VARBINARY; типы временных меток с часовым поясом всегда сопоставляются с TIMESTAMPTZ | Сопоставления типов Hive, Iceberg, Paimon и связанных JDBC | enable.mapping.varbinary и enable.mapping.timestamp_tz остаются маркерами совместимости; установка значения false не восстанавливает старые сопоставления. Master FE сохраняет маркеры со значением true для старых Catalog. Проверьте типы полей на стороне клиента, часовые пояса и явные преобразования типов |
| TVF S3 / HDFS / LOCAL всегда сохраняют семантику часового пояса временных меток | Чтение Parquet UTC Timestamp или ORC TIMESTAMP_INSTANT через TVF | enable_mapping_timestamp_tz принимается для совместимости и игнорируется даже при значении false. Параметр TVF enable_mapping_varbinary остаётся настраиваемым и по умолчанию равен false |
Значение по умолчанию параметра BE и переменной сеанса enable_file_cache меняется с false на true | Чтение удалённых файлов в режиме совместного размещения вычислений и хранения; узлы BE в режиме разделения вычислений и хранения уже принудительно включают этот механизм | Проверьте пути кеша, ёмкость дисков, существующие явные настройки BE и сохранённые глобальные переменные. См. Файловый кеш |
Параметр FE meta_service_rpc_rate_limit_enabled включён по умолчанию; новый пробный режим также включён по умолчанию | RPC от FE к Meta Service в режиме разделения вычислений и хранения | По умолчанию ограничение частоты запросов только оценивается и фиксируется в журнале. Установите meta_service_rpc_rate_limit_dry_run=false, чтобы применять ограничение. Два новых переключателя пробного режима BE также необходимо отключить, чтобы включить фактическое ожидание. См. Конфигурация FE и Конфигурация BE |
Значение по умолчанию cloud_version_syncer_interval_second меняется с 20 на 60 секунд, cloud_get_version_task_batch_size с 2000 на 200, а новое максимальное число попыток равно 3 | Кластеры с разделением вычислений и хранения, использующие фоновую синхронизацию версий | Задайте явные значения, если нужна прежняя частота или размер пакета. Изменение интервала требует перезапуска FE |
Значение по умолчанию FE streaming_cdc_fetch_splits_batch_size меняется со 100 на 16; BE request_cdc_client_timeout_ms с 60000 на 120000 | Потоковая загрузка данных CDC | Миграция не требуется. Проверьте явные настройки, если вы настраивали пропускную способность или время ожидания |
| Прежний механизм аутентификации LDAP по умолчанию отклоняет пустые пароли | Вход с использованием LDAP Bind без аутентификации | Используйте действительный пароль. Переключатель совместимости ldap_allow_empty_pass по умолчанию равен false и требует перезапуска FE. Плагин аутентификации LDAP всегда отклоняет пустые пароли. См. LDAP |
| Отсутствие файлов данных или файлов удалений в зафиксированных снимках Iceberg всегда вызывает ошибку | Запросы Iceberg с ignore_not_found_file_in_external_table=true | Восстановите отсутствующие файлы или используйте корректный снимок. Этот переключатель больше не позволяет пропускать файлы зафиксированных снимков Iceberg |
Некорректные значения Iceberg schema.name-mapping.default теперь вызывают ошибку вместо чтения с допуском ошибок | Таблицы с некорректными свойствами сопоставления имён | Исправьте или удалите свойство через средство записи, затем обновите метаданные Doris. См. Iceberg Catalog |
| Для команд работы со словарями, прогревом, ограничениями и других команд добавлены проверки привилегий; GRANT / REVOKE на уровне столбцов проверяет собственные привилегии выполняющего команду пользователя | Учётные записи для соответствующих операций и скрипты автоматизации | Предоставьте необходимые привилегии на целевые и связанные объекты. См. документацию соответствующей команды |
| Новые AI Resources, созданные пользователем root, может изменять или удалять только root | AI Resources, созданные с маркером root начиная с 4.1.5 | Выполняйте эти операции от имени root. Ресурсы без маркера, созданные до обновления, не затрагиваются. См. AI Resources |
Изменения развёртывания и файлов конфигурации
| Изменение | Область влияния | Что делать |
|---|---|---|
Действующее значение параметра FE inverted_index_storage_format=V1 препятствует запуску | Кластеры, в которых V1 настроен в fe.conf или fe_custom.conf | Перед обновлением измените его на V2 или V3 и проверьте, не переопределяет ли fe_custom.conf настройки fe.conf |
При экспорте Parquet параметр enable_int96_timestamps теперь по умолчанию равен false, поэтому используются временные метки INT64 с логическими типами | Потребители Outfile / Export, зависящие от старого формата INT96 | Убедитесь в поддержке логических временных меток INT64. Если требуется старый формат, явно установите enable_int96_timestamps=true. Допускаются только true и false |
| Файлы со старой кодировкой DATE в Doris могут содержать смещение дат нулевого года | Файлы ORC / Parquet, экспортированные из Doris и содержащие даты от 0000-01-01 до 0000-02-28 | Проверьте происхождение файлов и выполните миграцию, как описано ниже. Одного обновления средства чтения недостаточно для восстановления исходных дат |
| Поставляемая версия Thrift обновлена с 0.16.0 до 0.24.0; Iceberg SDK с 1.10.1 до 1.11.0 | Развёртывания, в которых Doris собирается из исходного кода или повторно используются артефакты сторонних зависимостей | Подготовьте зависимости из исходного кода этого выпуска. Не используйте старый генератор Thrift и не смешивайте версии JAR |
Проверки привилегий команд
Версия 4.1.5 добавляет проверки привилегий для перечисленных ниже операций. Для эксплуатационных скриптов и учётных записей с делегированными правами проверьте привилегии как на целевые объекты, так и на все объекты, изменяемые каскадными операциями:
| Операция | Необходимые привилегии |
|---|---|
ADD CONSTRAINT / DROP CONSTRAINT | ALTER на целевую таблицу; добавление внешнего ключа также требует ALTER на таблицу, на которую он ссылается; удаление первичного ключа с каскадным изменением внешних ключей также требует ALTER на каждую таблицу, затронутую каскадной операцией |
CREATE DICTIONARY / DROP DICTIONARY | Создание требует CREATE на словарь и SELECT на его исходную таблицу; удаление требует DROP на словарь |
WARM UP COMPUTE GROUP | USAGE на целевую группу и любую указанную исходную группу, а также SELECT на явно указанные таблицы; правила ON TABLES также требуют глобальной привилегии ADMIN |
| Отмена прогрева, очистка корзины Catalog, удаление stage и управление корневыми ключами TDE | Глобальная привилегия ADMIN |
Конечные точки /rest/v1, требующие административных привилегий | При аутентификации как через Basic, так и через Cookie требуется глобальная привилегия ADMIN или NODE. Успешный вызов /login аутентифицирует пользователя, но не предоставляет доступ к административным конечным точкам |
Запросы метаданных также становятся более устойчивыми к ошибкам: information_schema.view_dependency пропускает представления, определения которых невозможно разобрать или которые ссылаются на недопустимые объекты, вместо того чтобы завершать весь запрос с ошибкой. Если представление отсутствует в результате, проверьте его определение и журналы предупреждений FE. Отсутствие строки не означает, что у представления нет зависимостей.
Миграция файлов DATE с датами нулевого года
Версия 4.1.5 исправляет преобразование значений DATE в число дней с начала эпохи по пролептическому григорианскому календарю в Arrow, Parquet и ORC V2. Старая кодировка Doris записывала число дней с начала эпохи на один больше ожидаемого для дат от 0000-01-01 до 0000-02-28. Даты начиная с 0000-03-01 не затрагиваются, а 0000-02-29 по-прежнему находится за пределами поддерживаемого диапазона Doris DATE.
Старые значения невозможно автоматически отличить от корректных значений в новой кодировке. Проверяйте файлы по средству, которым они были записаны. Для файлов, в которых все поля DATE, как достоверно установлено, используют старую кодировку Doris, примените инструмент офлайн-миграции из исходного кода этого выпуска:
python tools/legacy_date_migration/migrate_legacy_dates.py \
--input legacy.parquet --output migrated.parquet --format parquet \
--confirm-legacy-doris-date-encoding
Для файлов ORC измените --format на orc. Инструмент требует Python 3.8+ и PyArrow с поддержкой выбранного формата. Он записывает новый файл и не перезаписывает исходный. Не запускайте его для файлов, созданных другими средствами записи, файлов смешанного происхождения или уже перенесённых файлов. После миграции используйте enable_file_scanner_v2=true и проверьте граничные даты, количество строк и значения NULL по доверенному источнику, прежде чем переключать потребителей. Для табличных форматов, таких как Iceberg, не заменяйте файлы данных на месте. Пересоздайте таблицу через средство записи соответствующего табличного формата или выполните поддерживаемую транзакционную перезапись, чтобы разделы, статистика и метаданные снимков были пересчитаны согласованно.
Часто задаваемые вопросы
Вопрос: после обновления у узла BE / FE значение Alive равно false, а Version по-прежнему указывает старую версию. Что делать?
Процесс не запустился либо новая версия не смогла запуститься. Проверьте журналы ошибок be.log / fe.log и убедитесь, что каталоги /bin и /lib заменены правильно.
Вопрос: после обновления FE не запускается из-за ошибки несовместимости метаданных. Что делать?
Скачок между версиями был слишком большим либо проверка совместимости метаданных не выполнялась. Откатитесь на старую версию, выполните проверку по процедуре из раздела «Проверка совместимости метаданных» этого документа и при необходимости обновляйте версии последовательно.
Вопрос: после обновления пропали jar-файлы в custom_lib/. Что произошло?
Каталог custom_lib/ был перезаписан по ошибке. Заменять нужно только /bin и /lib; каталог custom_lib/ заменять нельзя.
Вопрос: почему задачи Stream Load завершаются с ошибкой во время обновления?
Перезапуск узлов прерывает клиентские соединения. Добавьте повторные попытки на стороне клиента. В Routine Load и Flink/Spark Doris Connectors повторные попытки уже предусмотрены.
Вопрос: после обновления количество реплик не соответствует ожидаемому или реплики часто перемещаются. В чём причина?
Механизмы, управляемые disable_balance / disable_tablet_scheduler, не были отключены либо не были включены снова после обновления. Проверьте порядок отключения и включения этих механизмов: отключайте их перед обновлением и включайте снова после него.
Вопрос: почему обновление с пропуском минорных версий завершилось неудачей?
Версии обновлялись непоследовательно. Выполните откат и обновляйтесь поэтапно, например по пути 3.0 to 3.1 to 3.2 to 3.3.
Вопрос: обновление кластера с одним узлом FE завершилось неудачей, и метаданные были потеряны. Что делать?
Проверка совместимости метаданных не выполнялась. Перед обновлением расширьте кластер до отказоустойчивой конфигурации с 3 узлами FE либо выполните проверку совместимости метаданных на машине для разработки или узле BE.