Обновление кластера
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. Если узел FE всего 1, проверка совместимости метаданных перед обновлением обязательна. Совместимость метаданных критически важна: сбой обновления из-за несовместимых метаданных может привести к потере данных.
Также учитывайте следующее:
- Рекомендуется проверять совместимость метаданных на машине для разработки или узле 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 также обратите внимание на следующие изменения:
| Изменение | Что затронуто | Что сделать |
|---|---|---|
Compaction больше не приостанавливается при высоком потреблении памяти (значение по умолчанию настройки 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 | Изменение затрагивает только вновь создаваемые партиции. См. Распределение данных по бакетам |
Значение по умолчанию настройки 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. См. Continuous Load |
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 скрываются маской ****** в результатах запросов | Скрипты, считывающие учётные данные из этих результатов | Получайте исходные значения из системы управления конфигурацией |
Изменения развёртывания и файлов конфигурации
| Изменение | Что затронуто | Что сделать |
|---|---|---|
В JAVA_OPTS для JDK 17 необходимо заменить --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, могут не запускаться или не работать |
Конечная точка 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 не может преобразовать её формат хранения |
Пользовательские функции больше не принимают сигнатуры с переменным числом аргументов ... | Java / Python UDF, UDAF, UDTF и ALIAS FUNCTION | Используйте фиксированное число параметров или один параметр ARRAY для передачи нескольких значений. См. CREATE FUNCTION |
Формат файлов native удалён | Чтение или экспорт файлов в этом формате | Используйте поддерживаемый формат, например Parquet или ORC. Перед обновлением преобразуйте старые файлы с помощью предыдущей версии Doris |
Изменения значений по умолчанию и поведения
| Изменение | Что затронуто | Что сделать |
|---|---|---|
Двоичные типы в Catalog всегда сопоставляются с VARBINARY; типы временных меток с часовым поясом всегда сопоставляются с TIMESTAMPTZ | Hive, Iceberg, Paimon и связанные сопоставления типов JDBC | enable.mapping.varbinary и enable.mapping.timestamp_tz остаются маркерами совместимости; установка значения false не восстанавливает прежние сопоставления. Для старых Catalog узел Master FE сохраняет эти маркеры со значением true. Проверьте типы полей в клиентах, часовые пояса и явные приведения типов |
| TVF S3 / HDFS / LOCAL всегда сохраняют семантику часового пояса временных меток | Чтение Parquet UTC Timestamp или ORC TIMESTAMP_INSTANT через TVF | В 4.1.5 параметр enable_mapping_timestamp_tz принимается для совместимости и игнорируется даже при значении false; enable_mapping_varbinary остаётся настраиваемым, его значение по умолчанию равно false. Текущая ветка dev игнорирует оба устаревших флага и всегда сопоставляет двоичные типы с VARBINARY, а временные метки с часовым поясом с TIMESTAMPTZ. См. S3 TVF, HDFS TVF и LOCAL TVF |
Значение по умолчанию настройки BE и переменной сеанса enable_file_cache меняется с false на true | Чтение удалённых файлов в режиме с совмещёнными вычислениями и хранением; в режиме с разделением вычислений и хранения на BE этот параметр уже принудительно включён | Проверьте пути кеша, ёмкость дисков, существующие явные настройки BE и сохранённые глобальные переменные. См. Файловый кеш |
Настройка FE meta_service_rpc_rate_limit_enabled включена по умолчанию; новый режим dry-run также включён по умолчанию | RPC от FE к Meta Service в режиме с разделением вычислений и хранения | По умолчанию ограничение частоты запросов только оценивается и регистрируется. Задайте meta_service_rpc_rate_limit_dry_run=false, чтобы применять его. Два новых переключателя dry-run на 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 | Проверьте происхождение файлов и выполните миграцию, как описано ниже. Одно лишь обновление средства чтения не восстановит исходные даты |
| В 4.1.5 встроенный Thrift обновлён с 0.16.0 до 0.24.0, а Iceberg SDK с 1.10.1 до 1.11.0 (текущая ветка dev использует Iceberg SDK 1.12.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 по-прежнему находится за пределами поддерживаемого диапазона DATE в Doris.
Старые значения невозможно автоматически отличить от корректных значений в новом кодировании. Проверяйте файлы по системе, которая их записала. Для файлов, в которых все поля 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.