Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

feat: Implement local MMDB GeoIP lookup with UI for source switching, enhance mobile detail drawers for IP tables, and improve settings interaction for GeoIP provider selection.

luolei3adbcd924bfc
diff --git a/CHANGELOG.en.md b/CHANGELOG.en.md
index 89de0cb..7286c93 100644
--- a/CHANGELOG.en.md
+++ b/CHANGELOG.en.md
@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [1.2.9] - 2026-02-16
+
+### Added
+
+- **Offline GeoIP lookup via local MMDB** 🌐
+ - Added IP lookup source switching in Settings (`online` / `local`)
+ - Added support for local MMDB files: `GeoLite2-City.mmdb`, `GeoLite2-ASN.mmdb` (required), `GeoLite2-Country.mmdb` (optional)
+- **MMDB preflight checks and safeguards**
+ - Required MMDB files are validated before enabling local mode
+ - Local option is disabled when required files are missing, with missing-file hints in UI
+- **MMDB availability fallback safeguards**
+ - If MMDB files are removed, runtime lookup now falls back to online API automatically
+ - If config is still `local` while MMDB is unavailable, backend auto-reverts persisted provider to `online` to keep UI and runtime behavior consistent
+- **Improved local development MMDB directory detection**
+ - Improved MMDB directory resolution with multiple candidates and env override support
+ - Fixed the case where Local could not be enabled even though MMDB files existed in local development
+- **Unified mobile details interaction**
+ - Rules page (Domains / IPs) now uses Drawer for mobile details
+ - Mobile details behavior is aligned with devices and stats pages
+- **Improved settings interaction consistency**
+ - `IP Lookup Source` selected-state visuals are now consistent with the Favicon selector
+ - Options are now fully row-clickable instead of requiring direct radio-button clicks
+
+### Changed
+
+- Documentation updates (`README.md` / `README.en.md` / `.env.example`):
+ - Added clearer local MMDB deployment and mount instructions
+ - Clarified that `GEOIP_ONLINE_API_URL` is intended for endpoints compatible with the `ipinfo.my` response schema
+ - Consolidated duplicate English README entry points
+
## [1.2.8] - 2026-02-15
### Performance
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a1b232f..f20fe77 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,36 @@
## [未发布]
+## [1.2.9] - 2026-02-16
+
+### 新增
+
+- **离线 GeoIP(本地 MMDB)能力** 🌐
+ - 设置页新增 IP 查询来源切换(`online` / `local`)
+ - 支持本地 MMDB 数据源:`GeoLite2-City.mmdb`、`GeoLite2-ASN.mmdb`(必需),`GeoLite2-Country.mmdb`(可选)
+- **MMDB 预检测与保护**
+ - 切换到本地模式前先检查必需 MMDB 文件
+ - 缺失文件时本地选项自动禁用,并显示缺失文件列表
+- **MMDB 可用性兜底机制**
+ - 当用户删除历史 MMDB 文件后,运行时查询会自动回退到在线接口
+ - 若配置仍是 `local` 且 MMDB 不可用,服务端会自动回写为 `online`,避免 UI 与实际行为不一致
+- **本地开发目录识别增强**
+ - 增强 MMDB 目录探测逻辑(支持多候选目录与环境变量覆盖)
+ - 修复本地开发场景下 `geoip` 目录已存在但仍无法启用 Local 的问题
+- **移动端详情交互统一**
+ - 规则页(Domains / IPs)移动端详情统一改为 Drawer 交互
+ - 与设备页、统计页保持一致的移动端信息展示方式
+- **设置页交互一致性增强**
+ - `IP Lookup Source` 选中态视觉与 Favicon 选项统一
+ - 选项改为整行可点击,不再只能点击前置单选按钮
+
+### 变更
+
+- 文档更新(中英文 README / `.env.example`):
+ - 增补本地 MMDB 部署与挂载说明
+ - 明确 `GEOIP_ONLINE_API_URL` 仅适用于兼容 `ipinfo.my` 响应结构的在线接口
+ - 收敛重复英文 README,保留统一入口
+
## [1.2.8] - 2026-02-15
### 性能优化
diff --git a/apps/web/components/features/backend/backend-config-dialog.tsx b/apps/web/components/features/backend/backend-config-dialog.tsx
index ceb311d..3e84859 100644
--- a/apps/web/components/features/backend/backend-config-dialog.tsx
+++ b/apps/web/components/features/backend/backend-config-dialog.tsx
@@ -1451,18 +1451,39 @@ export function BackendConfigDialog({
onValueChange={handleGeoLookupProviderChange}
className="space-y-2"
disabled={updatingGeoLookup || isShowcase}>
- <div className="flex items-center gap-2 rounded-md border p-3">
+ <div
+ className={cn(
+ "flex items-center gap-2 rounded-md border p-3 transition-all",
+ geoLookupConfig.provider === "online"
+ ? "border-primary bg-primary/5"
+ : "border-border hover:bg-muted/50",
+ !(updatingGeoLookup || isShowcase) && "cursor-pointer",
+ )}
+ onClick={() => {
+ if (updatingGeoLookup || isShowcase) return;
+ handleGeoLookupProviderChange("online");
+ }}>
<RadioGroupItem value="online" id="geo-provider-online" />
- <Label htmlFor="geo-provider-online" className="cursor-pointer">
+ <Label htmlFor="geo-provider-online" className="cursor-pointer font-medium">
{t("geoLookupOnline")}
</Label>
</div>
<div
className={cn(
- "flex items-center gap-2 rounded-md border p-3",
+ "flex items-center gap-2 rounded-md border p-3 transition-all",
+ geoLookupConfig.provider === "local"
+ ? "border-primary bg-primary/5"
+ : "border-border hover:bg-muted/50",
!geoLookupConfig.localMmdbReady &&
- "opacity-60 cursor-not-allowed",
- )}>
+ "opacity-60 cursor-not-allowed hover:bg-transparent",
+ geoLookupConfig.localMmdbReady &&
+ !(updatingGeoLookup || isShowcase) &&
+ "cursor-pointer",
+ )}
+ onClick={() => {
+ if (updatingGeoLookup || isShowcase || !geoLookupConfig.localMmdbReady) return;
+ handleGeoLookupProviderChange("local");
+ }}>
<RadioGroupItem
value="local"
id="geo-provider-local"
@@ -1471,7 +1492,7 @@ export function BackendConfigDialog({
<Label
htmlFor="geo-provider-local"
className={cn(
- "cursor-pointer",
+ "cursor-pointer font-medium",
!geoLookupConfig.localMmdbReady && "cursor-not-allowed",
)}>
{t("geoLookupLocal")}
diff --git a/apps/web/components/features/stats/table/ip-stats-table.tsx b/apps/web/components/features/stats/table/ip-stats-table.tsx
index 66eec95..7136ab2 100644
--- a/apps/web/components/features/stats/table/ip-stats-table.tsx
+++ b/apps/web/components/features/stats/table/ip-stats-table.tsx
@@ -95,6 +95,7 @@ export function IPStatsTable({
const [mobileDetailsOpen, setMobileDetailsOpen] = useState(false);
const [mobileDetailIP, setMobileDetailIP] = useState<IPStats | null>(null);
const detailIPKey = mobileDetailsOpen ? (mobileDetailIP?.ip ?? null) : expandedIP;
+ const mobileDetailIPGradient = getIPGradient(mobileDetailIP?.ip ?? "0.0.0.0");
useEffect(() => {
// Context switch (backend/device/proxy/rule binding change): collapse.
@@ -519,7 +520,10 @@ export function IPStatsTable({
<Drawer open={mobileDetailsOpen} onOpenChange={handleMobileDetailsOpenChange}>
<DrawerContent className="sm:hidden">
<DrawerHeader className="border-b border-border/60 bg-background/95 px-5 pt-2 pb-2.5">
- <div className="min-w-0 rounded-md border border-border/60 bg-muted/25 px-2.5 py-2">
+ <div className="flex items-center gap-2.5 min-w-0 rounded-md border border-border/60 bg-muted/25 px-2.5 py-2">
+ <div className={`w-5 h-5 rounded-md bg-gradient-to-br ${mobileDetailIPGradient} flex items-center justify-center shrink-0`}>
+ <Server className="w-3 h-3 text-white" />
+ </div>
<DrawerTitle className="truncate text-left font-mono text-[15px] font-semibold leading-6">
{mobileDetailIP?.ip || t("unknownIP")}
</DrawerTitle>
diff --git a/apps/web/components/features/stats/table/ip-table.tsx b/apps/web/components/features/stats/table/ip-table.tsx
index da30e36..3ad0b64 100644
--- a/apps/web/components/features/stats/table/ip-table.tsx
+++ b/apps/web/components/features/stats/table/ip-table.tsx
@@ -216,6 +216,7 @@ export function IPsTable({
const total = hasWsIPsPage ? wsIPsPage!.total : ipsQuery.data?.total ?? 0;
const loading = !hasWsIPsPage && ipsQuery.isLoading && !ipsQuery.data;
const detailIPKey = mobileDetailsOpen ? (mobileDetailIP?.ip ?? null) : expandedIP;
+ const mobileIPColor = getIPColor(mobileDetailIP?.ip ?? "0.0.0.0");
useEffect(() => {
// Backend switch means a different data universe, collapse safely.
@@ -643,10 +644,17 @@ export function IPsTable({
<Drawer open={mobileDetailsOpen} onOpenChange={handleMobileDetailsOpenChange}>
<DrawerContent className="sm:hidden">
- <DrawerHeader className="border-b border-border/60 px-4 py-2">
- <DrawerTitle className="truncate text-left text-sm font-semibold">
- {mobileDetailIP?.ip || t("unknownIP")}
- </DrawerTitle>
+ <DrawerHeader className="border-b border-border/60 bg-background/95 px-5 pt-2 pb-2.5">
+ <div className="flex items-center gap-2.5 min-w-0 rounded-md border border-border/60 bg-muted/25 px-2.5 py-2">
+ <div
+ className={`w-5 h-5 rounded-md ${mobileIPColor.bg} ${mobileIPColor.text} flex items-center justify-center shrink-0`}
+ >
+ <Server className="w-3 h-3" />
+ </div>
+ <DrawerTitle className="truncate text-left font-mono text-[15px] font-semibold leading-6">
+ {mobileDetailIP?.ip || t("unknownIP")}
+ </DrawerTitle>
+ </div>
</DrawerHeader>
<div className="max-h-[76vh] overflow-y-auto pb-[max(env(safe-area-inset-bottom),0px)]">
{mobileDetailIP ? (
diff --git a/apps/web/messages/en.json b/apps/web/messages/en.json
index d20a890..29be02e 100644
--- a/apps/web/messages/en.json
+++ b/apps/web/messages/en.json
@@ -415,7 +415,7 @@
"faviconIm": "favicon.im (Recommended for China)",
"faviconOff": "Off (Use default icons)",
"geoLookupProvider": "IP Lookup Source",
- "geoLookupProviderDescription": "Switch between online API and local MMDB lookup. Local mode avoids external network dependency and improves privacy.",
+ "geoLookupProviderDescription": "Switch between online API and local MMDB lookup. Online mode works out of the box, while local mode is suitable for offline or restricted-network environments.",
"geoLookupOnline": "Online API (Default)",
"geoLookupLocal": "Local MMDB",
"geoLookupFixedPathHint": "Local mode automatically reads MMDB files (requires GeoLite2-City.mmdb and GeoLite2-ASN.mmdb, Country optional).",
diff --git a/apps/web/messages/zh.json b/apps/web/messages/zh.json
index 50fb222..c9194bc 100644
--- a/apps/web/messages/zh.json
+++ b/apps/web/messages/zh.json
@@ -414,7 +414,7 @@
"faviconIm": "favicon.im (国内推荐)",
"faviconOff": "关闭(使用默认图标)",
"geoLookupProvider": "IP 查询来源",
- "geoLookupProviderDescription": "可在在线接口与本地 MMDB 查询间切换。本地模式不依赖外部网络并且更有利于隐私保护。",
+ "geoLookupProviderDescription": "可在在线接口与本地 MMDB 查询间切换。在线模式开箱即用,本地模式适用于离线或受限网络环境。",
"geoLookupOnline": "在线接口(默认)",
"geoLookupLocal": "本地 MMDB",
"geoLookupFixedPathHint": "本地模式会自动读取 MMDB 文件(需包含 GeoLite2-City.mmdb 和 GeoLite2-ASN.mmdb,Country 可选)。",