From 09e8463c742b625722ee6ff2a697507775287aa0 Mon Sep 17 00:00:00 2001 From: Meow <197331664+Meo597@users.noreply.github.com> Date: Sun, 26 Apr 2026 15:24:35 +0800 Subject: [PATCH] Geodata: Support automatically updating .dat files and hot reloading --- .vitepress/menus/sidebar.en.mts | 3 +- .vitepress/menus/sidebar.mts | 3 +- .vitepress/menus/sidebar.ru.mts | 4 +++ docs/config/geodata.md | 56 +++++++++++++++++++++++++++++++++ docs/config/index.md | 7 ++++- docs/en/config/geodata.md | 56 +++++++++++++++++++++++++++++++++ docs/en/config/index.md | 7 ++++- docs/ru/config/geodata.md | 56 +++++++++++++++++++++++++++++++++ docs/ru/config/index.md | 7 ++++- 9 files changed, 194 insertions(+), 5 deletions(-) create mode 100644 docs/config/geodata.md create mode 100644 docs/en/config/geodata.md create mode 100644 docs/ru/config/geodata.md diff --git a/.vitepress/menus/sidebar.en.mts b/.vitepress/menus/sidebar.en.mts index 25375c4f..92dbef24 100644 --- a/.vitepress/menus/sidebar.en.mts +++ b/.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" } ] }, { diff --git a/.vitepress/menus/sidebar.mts b/.vitepress/menus/sidebar.mts index 728c72e5..c7af5b6d 100644 --- a/.vitepress/menus/sidebar.mts +++ b/.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" } ] }, { diff --git a/.vitepress/menus/sidebar.ru.mts b/.vitepress/menus/sidebar.ru.mts index e28f42b0..e68b9b39 100644 --- a/.vitepress/menus/sidebar.ru.mts +++ b/.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" } ] }, diff --git a/docs/config/geodata.md b/docs/config/geodata.md new file mode 100644 index 00000000..ae6f6312 --- /dev/null +++ b/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#资源文件路径) 解析，并且必须是资源目录内已经存在的普通文件；不支持绝对路径或跳出资源目录的路径。 diff --git a/docs/config/index.md b/docs/config/index.md index 1b56daf7..7d2d3cf2 100644 --- a/docs/config/index.md +++ b/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) + +地理数据文件自动更新与热重载。 diff --git a/docs/en/config/geodata.md b/docs/en/config/geodata.md new file mode 100644 index 00000000..8312e076 --- /dev/null +++ b/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. diff --git a/docs/en/config/index.md b/docs/en/config/index.md index 8a95ab40..f85a59cd 100644 --- a/docs/en/config/index.md +++ b/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. diff --git a/docs/ru/config/geodata.md b/docs/ru/config/geodata.md new file mode 100644 index 00000000..bd91335b --- /dev/null +++ b/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#путь-к-файлам-ресурсов). Это должен быть уже существующий обычный файл внутри каталога ресурсов; абсолютные пути и пути с выходом за пределы каталога ресурсов не поддерживаются. diff --git a/docs/ru/config/index.md b/docs/ru/config/index.md index 43e7ba05..1a37d5fc 100644 --- a/docs/ru/config/index.md +++ b/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) + +Автоматическое обновление и горячая перезагрузка файлов геоданных.