From 5fd3707ffb50d294ca81f3110bdf2391336f25f7 Mon Sep 17 00:00:00 2001
From: Shinsuke Sugaya <shinsuke@apache.org>
Date: Fri, 21 Aug 2026 12:20:48 +0900
Subject: [PATCH] docs(upgrade): say that four api.v2.* keys were renamed in
 15.8

Four /api/v2 configuration keys lost their api.v2. prefix in 15.8 and no
backward-compatible alias was kept, so a setting left under its old name is
ignored without a warning and the shipped default takes effect instead. That
reaches an existing deployment on upgrade and was not written down.

  api.v2.chat.stream.keepalive.interval.ms -> api.chat.stream.keepalive.interval.ms
  api.v2.param.max.length                  -> api.param.max.length
  api.v2.param.max.array.size              -> api.param.max.array.size
  api.v2.click.max.rt                      -> api.click.max.timestamp

The first is the one most likely to have been tuned: it sets how often a
keep-alive frame is sent while POST /api/v2/chat/stream waits for the model, so
a lost setting shows up in AI search mode. The last also changed name for
accuracy - it bounds a click log's rt value, which is a timestamp rather than a
response time. Values, defaults and behaviour are otherwise unchanged, and only
an explicit setting is affected.

Added to the 15.8 migration section in all seven languages.
---
 de/15.8/install/upgrade.rst    | 37 +++++++++++++++++++++++++++++++++
 en/15.8/install/upgrade.rst    | 36 ++++++++++++++++++++++++++++++++
 es/15.8/install/upgrade.rst    | 38 ++++++++++++++++++++++++++++++++++
 fr/15.8/install/upgrade.rst    | 38 ++++++++++++++++++++++++++++++++++
 ja/15.8/install/upgrade.rst    | 36 ++++++++++++++++++++++++++++++++
 ko/15.8/install/upgrade.rst    | 36 ++++++++++++++++++++++++++++++++
 zh-cn/15.8/install/upgrade.rst | 33 +++++++++++++++++++++++++++++
 7 files changed, 254 insertions(+)

diff --git a/de/15.8/install/upgrade.rst b/de/15.8/install/upgrade.rst
index 20ffc994..c560c51f 100644
--- a/de/15.8/install/upgrade.rst
+++ b/de/15.8/install/upgrade.rst
@@ -648,6 +648,43 @@ ihnen benannte Berechtigung. Dokumente, die einzelnen Benutzern zugewiesen sind,
 Benutzer dann nicht mehr gefunden. Um das bisherige Verhalten beizubehalten, stellen Sie den
 mitgelieferten Standardwert ``true`` wieder her.
 
+Falls Sie die /api/v2-Konfigurationsschlüssel geändert haben
+------------------------------------------------------------
+
+In 15.8 haben vier Konfigurationsschlüssel ihr Präfix ``api.v2.`` verloren. Werte, Standardwerte
+und Verhalten bleiben unverändert, **es gibt jedoch keinen abwärtskompatiblen Aliasnamen**: Eine
+unter dem alten Namen belassene Einstellung wird ohne Warnung ignoriert, und stattdessen greift
+der mitgelieferte Standardwert.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Bis 15.7
+     - 15.8
+     - Standardwert
+   * - ``api.v2.chat.stream.keepalive.interval.ms``
+     - ``api.chat.stream.keepalive.interval.ms``
+     - ``15000``
+   * - ``api.v2.param.max.length``
+     - ``api.param.max.length``
+     - ``1000``
+   * - ``api.v2.param.max.array.size``
+     - ``api.param.max.array.size``
+     - ``100``
+   * - ``api.v2.click.max.rt``
+     - ``api.click.max.timestamp``
+     - ``9999999999999``
+
+Wenn Sie einen dieser Schlüssel in ``fess_config.properties`` oder als JVM-Argument
+``-Dfess.config.<Schlüssel>`` gesetzt haben, benennen Sie ihn um. Betroffen sind nur explizit
+gesetzte Werte; eine Installation, die sie nie geändert hat, erfordert keine Maßnahme.
+
+Der erste Schlüssel bestimmt, wie oft ein Keep-alive-Frame gesendet wird, während
+``POST /api/v2/chat/stream`` auf das Modell wartet - eine verlorene Einstellung fällt daher im
+KI-Suchmodus auf. Der letzte Schlüssel wurde auch aus Gründen der Genauigkeit umbenannt: Er
+begrenzt den Wert ``rt`` eines Klickprotokolls, der ein Zeitstempel und keine Antwortzeit ist.
+
+
 Aktualisierung der Plugin-Versionen
 -----------------------------------
 
diff --git a/en/15.8/install/upgrade.rst b/en/15.8/install/upgrade.rst
index 78f3afa8..7cb47ff3 100644
--- a/en/15.8/install/upgrade.rst
+++ b/en/15.8/install/upgrade.rst
@@ -622,6 +622,42 @@ In a deployment that sets it to ``false``, users lose the permission named after
 the upgrade, so documents permissioned to an individual user stop matching for that user. To keep
 the previous behaviour, restore the shipped default of ``true``.
 
+If You Changed the /api/v2 Configuration Keys
+------------------------------------------------
+
+In 15.8, four configuration keys lost their ``api.v2.`` prefix. Their values, defaults and
+behaviour are unchanged, but **no backward-compatible alias is kept**: a setting left under its
+old name is ignored without any warning, and the shipped default takes effect instead.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Up to 15.7
+     - 15.8
+     - Default
+   * - ``api.v2.chat.stream.keepalive.interval.ms``
+     - ``api.chat.stream.keepalive.interval.ms``
+     - ``15000``
+   * - ``api.v2.param.max.length``
+     - ``api.param.max.length``
+     - ``1000``
+   * - ``api.v2.param.max.array.size``
+     - ``api.param.max.array.size``
+     - ``100``
+   * - ``api.v2.click.max.rt``
+     - ``api.click.max.timestamp``
+     - ``9999999999999``
+
+If you set any of these in ``fess_config.properties`` or as a ``-Dfess.config.<key>`` JVM
+argument, rename them. Only an explicit setting is affected; an installation that never changed
+them needs no action.
+
+The first key controls how often a keep-alive frame is sent while ``POST /api/v2/chat/stream``
+is waiting for the model, so AI search mode is where a lost setting becomes visible. The last
+key was renamed for accuracy as well: it bounds the ``rt`` value a click log may carry, which is
+a timestamp rather than a response time.
+
+
 Updating Plugin Versions
 ------------------------
 
diff --git a/es/15.8/install/upgrade.rst b/es/15.8/install/upgrade.rst
index a9a902e8..f5b11db0 100644
--- a/es/15.8/install/upgrade.rst
+++ b/es/15.8/install/upgrade.rst
@@ -648,6 +648,44 @@ que lleva su propio nombre, por lo que los documentos asignados a un usuario con
 aparecer para ese usuario. Para mantener el comportamiento anterior, restaure el valor
 predeterminado ``true``.
 
+Si Había Modificado las Claves de Configuración de /api/v2
+----------------------------------------------------------
+
+En 15.8, cuatro claves de configuración perdieron su prefijo ``api.v2.``. Sus valores, valores
+predeterminados y comportamiento no cambian, pero **no se conserva ningún alias retrocompatible**:
+una configuración que permanezca con su nombre antiguo se ignora sin ninguna advertencia y se
+aplica el valor predeterminado incluido.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Hasta 15.7
+     - 15.8
+     - Valor predeterminado
+   * - ``api.v2.chat.stream.keepalive.interval.ms``
+     - ``api.chat.stream.keepalive.interval.ms``
+     - ``15000``
+   * - ``api.v2.param.max.length``
+     - ``api.param.max.length``
+     - ``1000``
+   * - ``api.v2.param.max.array.size``
+     - ``api.param.max.array.size``
+     - ``100``
+   * - ``api.v2.click.max.rt``
+     - ``api.click.max.timestamp``
+     - ``9999999999999``
+
+Si estableció alguna de ellas en ``fess_config.properties`` o como argumento de JVM
+``-Dfess.config.<clave>``, cámbieles el nombre. Solo se ven afectadas las configuraciones
+explícitas; una instalación que nunca las modificó no requiere ninguna acción.
+
+La primera clave controla con qué frecuencia se envía una trama de keep-alive mientras
+``POST /api/v2/chat/stream`` espera al modelo, por lo que el modo de búsqueda con IA es donde se
+nota una configuración perdida. La última clave también se renombró por precisión: limita el
+valor ``rt`` que puede llevar un registro de clic, que es una marca de tiempo y no un tiempo de
+respuesta.
+
+
 Actualización de la Versión de los Plugins
 ---------------------------------------------
 
diff --git a/fr/15.8/install/upgrade.rst b/fr/15.8/install/upgrade.rst
index 22de827c..4d7d5442 100644
--- a/fr/15.8/install/upgrade.rst
+++ b/fr/15.8/install/upgrade.rst
@@ -652,6 +652,44 @@ permission portant leur propre nom : les documents attribués à un utilisateur
 plus pour cet utilisateur. Pour conserver le comportement précédent, rétablissez la valeur par
 défaut ``true``.
 
+Si vous aviez modifié les clés de configuration /api/v2
+-------------------------------------------------------
+
+En 15.8, quatre clés de configuration ont perdu leur préfixe ``api.v2.``. Leurs valeurs, leurs
+valeurs par défaut et leur comportement sont inchangés, mais **aucun alias rétrocompatible n'est
+conservé** : un paramètre laissé sous son ancien nom est ignoré sans avertissement et la valeur
+par défaut fournie s'applique.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Jusqu'à 15.7
+     - 15.8
+     - Valeur par défaut
+   * - ``api.v2.chat.stream.keepalive.interval.ms``
+     - ``api.chat.stream.keepalive.interval.ms``
+     - ``15000``
+   * - ``api.v2.param.max.length``
+     - ``api.param.max.length``
+     - ``1000``
+   * - ``api.v2.param.max.array.size``
+     - ``api.param.max.array.size``
+     - ``100``
+   * - ``api.v2.click.max.rt``
+     - ``api.click.max.timestamp``
+     - ``9999999999999``
+
+Si vous avez défini l'une de ces clés dans ``fess_config.properties`` ou via l'argument JVM
+``-Dfess.config.<clé>``, renommez-la. Seuls les paramètres explicites sont concernés ; une
+installation qui ne les a jamais modifiés n'a rien à faire.
+
+La première clé détermine la fréquence d'envoi d'une trame keep-alive pendant que
+``POST /api/v2/chat/stream`` attend le modèle : c'est donc dans le mode de recherche IA qu'un
+paramètre perdu se remarque. La dernière clé a également été renommée par souci d'exactitude :
+elle borne la valeur ``rt`` que peut porter un journal de clic, qui est un horodatage et non un
+temps de réponse.
+
+
 Mise à jour de la version des plugins
 -------------------------------------
 
diff --git a/ja/15.8/install/upgrade.rst b/ja/15.8/install/upgrade.rst
index 8b8e60e4..ce7b3af8 100644
--- a/ja/15.8/install/upgrade.rst
+++ b/ja/15.8/install/upgrade.rst
@@ -621,6 +621,42 @@ RDN として解析した値になりました。DN の中でエスケープさ
 個々のユーザーに対して設定した権限を持つ文書が検索できなくなります。従来の挙動を維持する場合は、
 同梱の既定値である ``true`` に戻してください。
 
+/api/v2 の設定キーを変更していた場合
+------------------------------------------------
+
+15.8 から、4 つの設定キーが ``api.v2.`` の接頭辞を失いました。値・既定値・挙動は変わりませんが、\
+**後方互換のための別名は用意されていません**\ 。古い名前のまま残した設定は警告もなく無視され、\
+同梱の既定値が使われます。
+
+.. list-table::
+   :header-rows: 1
+
+   * - 15.7 まで
+     - 15.8
+     - 既定値
+   * - ``api.v2.chat.stream.keepalive.interval.ms``
+     - ``api.chat.stream.keepalive.interval.ms``
+     - ``15000``
+   * - ``api.v2.param.max.length``
+     - ``api.param.max.length``
+     - ``1000``
+   * - ``api.v2.param.max.array.size``
+     - ``api.param.max.array.size``
+     - ``100``
+   * - ``api.v2.click.max.rt``
+     - ``api.click.max.timestamp``
+     - ``9999999999999``
+
+``fess_config.properties`` または ``-Dfess.config.<キー>`` の JVM 引数でこれらを設定していた場合は、\
+新しい名前に変更してください。影響を受けるのは明示的に設定していた場合だけで、\
+変更していなかった環境で対応は不要です。
+
+1 つ目のキーは ``POST /api/v2/chat/stream`` がモデルの応答を待つあいだに送出する keep-alive の\
+間隔を決めるため、設定が失われたことに気づくのは AI 検索モードの利用時になります。\
+最後のキーは名前の正確さのためにも変更されました。これはクリックログが持てる ``rt`` の値の上限で、\
+応答時間ではなくタイムスタンプを指します。
+
+
 プラグインのバージョン更新
 --------------------------
 
diff --git a/ko/15.8/install/upgrade.rst b/ko/15.8/install/upgrade.rst
index 46660ed0..0c14691e 100644
--- a/ko/15.8/install/upgrade.rst
+++ b/ko/15.8/install/upgrade.rst
@@ -615,6 +615,42 @@ LDAP / Active Directory 연동을 사용하던 경우
 설정한 권한을 가진 문서를 검색할 수 없게 됩니다. 기존 동작을 유지하려면 기본값인 ``true`` 로
 되돌리십시오.
 
+/api/v2 설정 키를 변경했던 경우
+------------------------------------------------
+
+15.8부터 네 개의 설정 키에서 ``api.v2.`` 접두사가 없어졌습니다. 값과 기본값, 동작은 그대로이지만
+**하위 호환을 위한 별칭은 제공되지 않습니다**. 예전 이름 그대로 남겨 둔 설정은 경고 없이 무시되며,
+기본으로 포함된 값이 사용됩니다.
+
+.. list-table::
+   :header-rows: 1
+
+   * - 15.7까지
+     - 15.8
+     - 기본값
+   * - ``api.v2.chat.stream.keepalive.interval.ms``
+     - ``api.chat.stream.keepalive.interval.ms``
+     - ``15000``
+   * - ``api.v2.param.max.length``
+     - ``api.param.max.length``
+     - ``1000``
+   * - ``api.v2.param.max.array.size``
+     - ``api.param.max.array.size``
+     - ``100``
+   * - ``api.v2.click.max.rt``
+     - ``api.click.max.timestamp``
+     - ``9999999999999``
+
+``fess_config.properties`` 또는 ``-Dfess.config.<키>`` JVM 인수로 이 키들을 설정했다면 새 이름으로
+변경하십시오. 영향을 받는 것은 명시적으로 설정한 경우뿐이며, 변경한 적이 없는 환경에서는 대응이
+필요하지 않습니다.
+
+첫 번째 키는 ``POST /api/v2/chat/stream`` 이 모델의 응답을 기다리는 동안 keep-alive 프레임을 보내는
+간격을 정하므로, 설정이 사라진 것은 AI 검색 모드에서 드러납니다. 마지막 키는 정확성을 위해서도
+이름이 바뀌었습니다. 클릭 로그가 가질 수 있는 ``rt`` 값의 상한이며, 응답 시간이 아니라
+타임스탬프를 가리킵니다.
+
+
 플러그인 버전 갱신
 ------------------------
 
diff --git a/zh-cn/15.8/install/upgrade.rst b/zh-cn/15.8/install/upgrade.rst
index 2944aa7e..cf210cde 100644
--- a/zh-cn/15.8/install/upgrade.rst
+++ b/zh-cn/15.8/install/upgrade.rst
@@ -596,6 +596,39 @@ Graph。在解析完成之前——或解析未能完全成功时——用户拥
 在设置为 ``false`` 的环境中，升级后用户会失去以自身命名的权限，因此针对单个用户设置了权限的文档
 将无法被该用户检索到。若要保持原有行为，请恢复为随附的默认值 ``true``\ 。
 
+若此前修改过 /api/v2 配置键
+------------------------------------------------
+
+从 15.8 起，有四个配置键去掉了 ``api.v2.`` 前缀。其取值、默认值和行为均未改变，但\
+**没有保留向后兼容的别名**\ ：仍使用旧名称的设置会被静默忽略，实际生效的是随附的默认值。
+
+.. list-table::
+   :header-rows: 1
+
+   * - 15.7 及以前
+     - 15.8
+     - 默认值
+   * - ``api.v2.chat.stream.keepalive.interval.ms``
+     - ``api.chat.stream.keepalive.interval.ms``
+     - ``15000``
+   * - ``api.v2.param.max.length``
+     - ``api.param.max.length``
+     - ``1000``
+   * - ``api.v2.param.max.array.size``
+     - ``api.param.max.array.size``
+     - ``100``
+   * - ``api.v2.click.max.rt``
+     - ``api.click.max.timestamp``
+     - ``9999999999999``
+
+如果曾在 ``fess_config.properties`` 中或通过 ``-Dfess.config.<键>`` JVM 参数设置过这些键，\
+请改用新名称。只有显式设置过的情况才会受影响；从未修改过的环境无需处理。
+
+第一个键决定 ``POST /api/v2/chat/stream`` 等待模型响应期间发送 keep-alive 帧的间隔，\
+因此设置失效会在 AI 搜索模式中显现。最后一个键的改名也是为了更准确：它限制的是点击日志中\
+``rt`` 的取值上限，而该值是时间戳而非响应时间。
+
+
 插件版本更新
 ------------------------