Geodata: Support automatically updating .dat files and hot reloading

.vitepress/menus/sidebar.en.mts

@@ -43,7 +43,8 @@ export const sidebar: DefaultTheme.Config["sidebar"] = {
           link: "/en/config/transport.md"
         },
         { text: "Metrics", link: "/en/config/metrics.md" },
-        { text: "Observatory", link: "/en/config/observatory.md" }
+        { text: "Observatory", link: "/en/config/observatory.md" },
+        { text: "Geodata Files", link: "/en/config/geodata.md" }
       ]
     },
     {

.vitepress/menus/sidebar.mts

@@ -37,7 +37,8 @@ export const sidebar: DefaultTheme.Config["sidebar"] = {
           link: "/config/transport.md"
         },
         { text: "Metrics", link: "/config/metrics.md" },
-        { text: "连接观测", link: "/config/observatory.md" }
+        { text: "连接观测", link: "/config/observatory.md" },
+        { text: "地理数据文件", link: "/config/geodata.md" }
       ]
     },
     {

.vitepress/menus/sidebar.ru.mts

@@ -55,6 +55,10 @@ export const sidebar: DefaultTheme.Config["sidebar"] = {
         {
           text: "Мониторинг подключений",
           link: "/ru/config/observatory.md"
+        },
+        {
+          text: "Файлы геоданных",
+          link: "/ru/config/geodata.md"
         }
       ]
     },

docs/config/geodata.md

@@ -0,0 +1,56 @@
+# 地理数据文件
+
+用于按计划热重载地理数据文件，也可以在重载前下载新的 `.dat` 文件。适合不方便重启 Xray、又需要定期更新地理数据文件的场景。
+
+低内存设备慎用。
+
+## GeodataObject
+
+```json
+{
+  "cron": "0 4 * * *",
+  "outbound": "proxy",
+  "assets": [
+    { "url": "https://example.com/geoip.dat", "file": "geoip.dat" },
+    { "url": "https://example.com/geosite.dat", "file": "geosite.dat" }
+  ]
+}
+```
+
+> `cron`: string
+
+标准 5 段 cron 表达式，按 Xray 运行环境的本地时区执行。例如：
+
+- `"0 4 * * *"`：每天 04:00 执行。
+- `"30 3 * * 1"`：每周一 03:30 执行。
+
+未设置时不会启用定时任务。如果上一次任务还没有结束，下一次触发会被跳过。
+
+> `outbound`: string
+
+下载 geodata 文件时使用的出站代理 `tag`。不指定的话走路由模块。
+
+> `assets`: \[ [AssetObject](#assetobject) \]
+
+需要下载并替换的 geodata 文件列表。
+
+如果下载后的重载失败，本次下载替换的文件会整体回滚。
+
+### AssetObject
+
+```json
+{
+  "url": "https://example.com/geoip.dat",
+  "file": "geoip.dat"
+}
+```
+
+> `url`: string
+
+资源文件的下载地址，必须是 HTTPS URL。
+
+> `file`: string
+
+写入的资源文件名，例如 `geoip.dat`、`geosite.dat`。
+
+该文件会按 [资源文件路径](./features/env.md#资源文件路径) 解析，并且必须是资源目录内已经存在的普通文件；不支持绝对路径或跳出资源目录的路径。

docs/config/index.md

@@ -23,7 +23,8 @@ Xray 的配置文件为 json 格式, 客户端和服务端的配置格式没有
   "fakedns": {},
   "metrics": {},
   "observatory": {},
-  "burstObservatory": {}
+  "burstObservatory": {},
+  "geodata": {}
 }
 ```
 
@@ -122,3 +123,7 @@ metrics 配置。更直接（希望更好）的统计导出方式。
 > burstObservatory: [BurstObservatoryObject](./observatory.md#burstobservatoryobject)
 
 突发连接观测。探测出站代理的连接状态。
+
+> geodata: [GeodataObject](./geodata.md)
+
+地理数据文件自动更新与热重载。

docs/en/config/geodata.md

@@ -0,0 +1,56 @@
+# Geodata Files
+
+Reloads geodata files on a schedule, and can download new `.dat` files before reloading. It is intended for cases where restarting Xray is inconvenient but geodata still needs periodic updates.
+
+Use with caution on low-memory devices.
+
+## GeodataObject
+
+```json
+{
+  "cron": "0 4 * * *",
+  "outbound": "proxy",
+  "assets": [
+    { "url": "https://example.com/geoip.dat", "file": "geoip.dat" },
+    { "url": "https://example.com/geosite.dat", "file": "geosite.dat" }
+  ]
+}
+```
+
+> `cron`: string
+
+A standard 5-field cron expression, evaluated in the local time zone of the Xray runtime environment. For example:
+
+- `"0 4 * * *"`: run every day at 04:00.
+- `"30 3 * * 1"`: run every Monday at 03:30.
+
+If omitted, the scheduled task is not enabled. If the previous task is still running, the next trigger is skipped.
+
+> `outbound`: string
+
+The outbound proxy `tag` used when downloading geodata files. If omitted, downloads go through the routing module.
+
+> `assets`: \[ [AssetObject](#assetobject) \]
+
+The list of geodata files to download and replace.
+
+If reloading fails after the download, all files replaced by this update are rolled back together.
+
+### AssetObject
+
+```json
+{
+  "url": "https://example.com/geoip.dat",
+  "file": "geoip.dat"
+}
+```
+
+> `url`: string
+
+The resource download URL. It must be an HTTPS URL.
+
+> `file`: string
+
+The resource filename to write, such as `geoip.dat` or `geosite.dat`.
+
+The file is resolved using the [Resource File Path](./features/env.md#resource-file-path). It must be an existing regular file inside the resource directory; absolute paths and paths escaping the resource directory are not supported.

docs/en/config/index.md

@@ -23,7 +23,8 @@ The format is as follows:
   "fakedns": {},
   "metrics": {},
   "observatory": {},
-  "burstObservatory": {}
+  "burstObservatory": {},
+  "geodata": {}
 }
 ```
 
@@ -121,3 +122,7 @@ Background connection observatory. Detects the connection status of outbound pro
 > burstObservatory: [BurstObservatoryObject](./observatory.md#burstobservatoryobject)
 
 Burst connection observatory. Detects the connection status of outbound proxies.
+
+> geodata: [GeodataObject](./geodata.md)
+
+Automatic update and hot reload for geodata files.

docs/ru/config/geodata.md

@@ -0,0 +1,56 @@
+# Файлы геоданных
+
+Перезагружает файлы геоданных по расписанию, а также может перед перезагрузкой скачать новые `.dat` файлы. Это подходит для случаев, когда перезапуск Xray нежелателен, но geodata нужно периодически обновлять.
+
+На устройствах с малым объемом памяти используйте с осторожностью.
+
+## GeodataObject
+
+```json
+{
+  "cron": "0 4 * * *",
+  "outbound": "proxy",
+  "assets": [
+    { "url": "https://example.com/geoip.dat", "file": "geoip.dat" },
+    { "url": "https://example.com/geosite.dat", "file": "geosite.dat" }
+  ]
+}
+```
+
+> `cron`: string
+
+Стандартное cron-выражение из 5 полей, выполняется в локальном часовом поясе среды, где запущен Xray. Например:
+
+- `"0 4 * * *"`: выполнять каждый день в 04:00.
+- `"30 3 * * 1"`: выполнять каждый понедельник в 03:30.
+
+Если поле не задано, задача по расписанию не включается. Если предыдущая задача еще выполняется, следующий запуск будет пропущен.
+
+> `outbound`: string
+
+`tag` исходящего прокси, используемого при загрузке файлов geodata. Если не указано, загрузка идет через модуль маршрутизации.
+
+> `assets`: \[ [AssetObject](#assetobject) \]
+
+Список файлов geodata, которые нужно скачать и заменить.
+
+Если после загрузки перезагрузка завершится ошибкой, все файлы, замененные в рамках этого обновления, будут откатаны вместе.
+
+### AssetObject
+
+```json
+{
+  "url": "https://example.com/geoip.dat",
+  "file": "geoip.dat"
+}
+```
+
+> `url`: string
+
+URL для загрузки ресурса. Должен быть HTTPS URL.
+
+> `file`: string
+
+Имя файла ресурса для записи, например `geoip.dat` или `geosite.dat`.
+
+Файл разрешается через [путь к файлам ресурсов](./features/env.md#путь-к-файлам-ресурсов). Это должен быть уже существующий обычный файл внутри каталога ресурсов; абсолютные пути и пути с выходом за пределы каталога ресурсов не поддерживаются.

docs/ru/config/index.md

@@ -23,7 +23,8 @@
   "fakedns": {},
   "metrics": {},
   "observatory": {},
-  "burstObservatory": {}
+  "burstObservatory": {},
+  "geodata": {}
 }
 ```
 
@@ -124,3 +125,7 @@
 > burstObservatory: [BurstObservatoryObject](./observatory.md#burstobservatoryobject)
 
 Мониторинг параллельных подключений. Обнаружение состояния подключения исходящего прокси.
+
+> geodata: [GeodataObject](./geodata.md)
+
+Автоматическое обновление и горячая перезагрузка файлов геоданных.