maven-proxy 1.3.0 → 1.3.2

package/README.md

@@ -2,6 +2,8 @@
 
 [English](README.md) | [中文](README-zh.md)
 
+[English ChangeLog](ChangeLog.md) | [中文更新日志](ChangeLog-zh.md)
+
 [![npm version](https://img.shields.io/npm/v/maven-proxy.svg)](https://www.npmjs.com/package/maven-proxy)
 
 ## 1. Project Positioning
@@ -275,6 +277,8 @@ Environment variables:
 - REPO_FALLBACK_REPOS: repository fallback list.
 - NPM_REGISTRY_DOMAINS: npm domains for ecosystem routing (wildcards supported).
 - MAVEN_REPO_DOMAINS: maven domains for ecosystem routing (wildcards supported).
+- MAVEN_CACHE_USE_DOMAIN_DIR: whether Maven cache uses hostname as the first-level directory. Default false.
+- MAVEN_CACHE_IGNORE_PATH_PREFIXES: Maven cache path-prefix ignore rules (comma-separated, supports host/path and host:port/path). Default: repo1.maven.org/maven2,repo.maven.apache.org/maven2,jitpack.io/,plugins.gradle.org/m2,dl.google.com/dl/android/maven2,dl.google.com/dl/google/maven.
 - HTTPS_MITM_DOMAINS: MITM domain list (includes registry.npmjs.org by default, wildcards supported).
 - DOWNLOAD_LOG_DIR: log directory.
 - LOG_RETENTION: log retention duration (supports s/m/h/d), for example 7d.
@@ -325,6 +329,8 @@ Priority:
 - `HTTPS_PASSTHROUGH_FOR_UNMATCHED`: Whether unmatched HTTPS domains are tunneled directly. Default `false`.
 - `NPM_REGISTRY_DOMAINS`: Domains treated as npm ecosystem for cache routing (wildcards supported).
 - `MAVEN_REPO_DOMAINS`: Domains treated as Maven ecosystem for cache routing (wildcards supported).
+- `MAVEN_CACHE_USE_DOMAIN_DIR`: Whether Maven cache uses hostname as the first-level directory. Default `false`.
+- `MAVEN_CACHE_IGNORE_PATH_PREFIXES`: Maven cache path-prefix ignore rules (comma-separated, supports `host/path` and `host:port/path`). Default `repo1.maven.org/maven2,repo.maven.apache.org/maven2,jitpack.io/,plugins.gradle.org/m2,dl.google.com/dl/android/maven2,dl.google.com/dl/google/maven`.
 - `MULTI_THREAD_DOMAINS`: Domains allowed to use multi-thread download (wildcards supported).
 - `MULTI_THREAD_COUNT`: Number of download threads for ranged downloads.
 - `MULTI_THREAD_MIN_SIZE_MB`: Minimum size threshold to trigger multi-thread download (MB).

package/bin/maven-proxy.js

@@ -140,63 +140,81 @@ function resolvePath(inputPath) {
 }
 
 function getDefaultConfigTemplate() {
-  return [
+  const lines = [
     "# Maven Proxy default user config",
+    "# Maven Proxy 用户模式默认配置",
     "# This file is loaded by default in user mode.",
     "",
-    "PROXY_PORT=8080",
-    "REPO_PORT=8081",
-    "CACHE_DIR=data/cache",
-    "CACHE_CLEANUP_ENABLED=true",
-    "CACHE_CLEANUP_DAILY_AT=03:00",
-    "CACHE_CLEANUP_CHECK_MIN_INTERVAL=10m",
-    "CACHE_TOUCH_ON_HIT=true",
-    "CACHE_TOUCH_MIN_INTERVAL=1d",
-    "CACHE_RETENTION_START=10d",
-    "CACHE_RETENTION_MIN=1d",
-    "CACHE_DISK_FREE_TRIGGER=20G",
-    "CACHE_DISK_FREE_TARGET=25G",
-    "CACHE_MAX_SIZE=",
-    "CACHE_TARGET_SIZE=",
-    "REPO_FALLBACK_REPOS=https://repo1.maven.org/maven2,https://jitpack.io,https://plugins.gradle.org/m2,https://maven.google.com",
-    "ENABLE_HTTPS_PROXY=true",
-    "HTTPS_MITM_DOMAINS=repo1.maven.org,repo.maven.apache.org,registry.npmjs.org",
-    "HTTPS_PASSTHROUGH_FOR_UNMATCHED=false",
-    "NPM_REGISTRY_DOMAINS=registry.npmjs.org,registry.npmmirror.com,npm.pkg.github.com",
-    "MAVEN_REPO_DOMAINS=repo1.maven.org,repo.maven.apache.org,jitpack.io,plugins.gradle.org,maven.google.com",
-    "MULTI_THREAD_DOMAINS=repo1.maven.org",
-    "MULTI_THREAD_COUNT=8",
-    "MULTI_THREAD_MIN_SIZE_MB=1",
-    "DOWNLOAD_TIMEOUT=60s",
-    "OUTBOUND_KEEP_ALIVE=true",
-    "OUTBOUND_KEEP_ALIVE_INTERVAL=1s",
-    "OUTBOUND_MAX_SOCKETS=64",
-    "OUTBOUND_MAX_FREE_SOCKETS=16",
-    "MAVEN_AFFINITY_ENABLED=true",
-    "MAVEN_AFFINITY_INDEX_DIR=data/index",
-    "MAVEN_NEGATIVE_CACHE_TTL=24h",
-    "MAVEN_AFFINITY_FLUSH_INTERVAL=5s",
-    "MAVEN_AFFINITY_EVENT_MAX_MB=8",
-    "DOWNLOAD_LOG_DIR=data/logs/downloads",
-    "LOG_RETENTION=7d",
-    "LOG_TO_STDOUT=false",
-    "UPSTREAM_PROXY_URL=",
-    "UPSTREAM_HTTP_PROXY_URL=",
-    "UPSTREAM_HTTPS_PROXY_URL=",
-    "UPSTREAM_NO_PROXY=127.0.0.1,localhost",
-    "UPSTREAM_IGNORE_DOMAINS=",
-    "CERT_DIR=data/certs",
-    "ROOT_CERT_PATH=data/certs/root-ca.crt",
-    "ROOT_KEY_PATH=data/certs/root-ca.key.pem",
-    "LEAF_CERT_DIR=data/certs/leaf",
-    "TRUST_STORE_PATH=data/certs/proxy-truststore.jks",
-    "TRUST_STORE_ALIAS=maven-proxy-root-ca",
-    "TRUST_STORE_PASSWORD=changeit",
-    "EXISTING_TRUST_STORE_PATH=",
-    "EXISTING_TRUST_STORE_PASSWORD=",
-    "JAVA_HOME=",
-    "",
-  ].join("\n");
+  ];
+
+  const appendEntry = (key, value, zhComment, enComment) => {
+    lines.push(`# 中文: ${zhComment}`);
+    lines.push(`# English: ${enComment}`);
+    lines.push(`${key}=${value}`);
+    lines.push("");
+  };
+
+  appendEntry("PROXY_PORT", "8080", "代理服务端口，默认 8080。", "Proxy service port. Default: 8080.");
+  appendEntry("REPO_PORT", "8081", "本地仓库服务端口，默认 8081。", "Local repository service port. Default: 8081.");
+  appendEntry("CACHE_DIR", "data/cache", "缓存根目录，默认 data/cache。", "Cache root directory. Default: data/cache.");
+  appendEntry("CACHE_CLEANUP_ENABLED", "true", "是否启用自动缓存清理，默认 true。", "Enable automatic cache cleanup. Default: true.");
+  appendEntry("CACHE_CLEANUP_DAILY_AT", "03:00", "每日固定检查时间（本地时区，HH:mm），默认 03:00。", "Fixed daily check time in local timezone (HH:mm). Default: 03:00.");
+  appendEntry("CACHE_CLEANUP_CHECK_MIN_INTERVAL", "10m", "压力检测最小间隔（支持 s/m/h/d），默认 10m。", "Minimum interval for pressure checks (supports s/m/h/d). Default: 10m.");
+  appendEntry("CACHE_TOUCH_ON_HIT", "true", "缓存命中返回时是否更新文件 mtime，默认 true。", "Update file mtime when serving cache hit. Default: true.");
+  appendEntry("CACHE_TOUCH_MIN_INTERVAL", "1d", "同一文件两次 touch 最小间隔（支持 s/m/h/d），默认 1d。", "Minimum interval between touches for the same file (supports s/m/h/d). Default: 1d.");
+  appendEntry("CACHE_RETENTION_START", "10d", "清理轮次初始保留窗口（支持 s/m/h/d），默认 10d。", "Initial retention window for cleanup cycle (supports s/m/h/d). Default: 10d.");
+  appendEntry("CACHE_RETENTION_MIN", "1d", "清理轮次最小保留窗口（支持 s/m/h/d），默认 1d。", "Minimum retention window for cleanup cycle (supports s/m/h/d). Default: 1d.");
+  appendEntry("CACHE_DISK_FREE_TRIGGER", "20G", "磁盘剩余空间低于该值触发清理（支持 K/M/G/T），默认 20G。", "Trigger cleanup when free disk space is below this value (supports K/M/G/T). Default: 20G.");
+  appendEntry("CACHE_DISK_FREE_TARGET", "25G", "磁盘剩余空间恢复到该值可停止清理（支持 K/M/G/T），默认 25G。", "Stop cleanup when free disk space recovers to this value (supports K/M/G/T). Default: 25G.");
+  appendEntry("CACHE_MAX_SIZE", "", "可选：缓存总大小触发阈值（支持 K/M/G/T），默认空（禁用）。", "Optional: cache total size trigger threshold (supports K/M/G/T). Default: empty (disabled).");
+  appendEntry("CACHE_TARGET_SIZE", "", "可选：缓存总大小回落目标（支持 K/M/G/T），默认空（禁用）。", "Optional: cache size recovery target (supports K/M/G/T). Default: empty (disabled).");
+  appendEntry(
+    "REPO_FALLBACK_REPOS",
+    "https://repo1.maven.org/maven2,https://jitpack.io,https://plugins.gradle.org/m2,https://dl.google.com",
+    "缓存未命中时回源仓库列表（逗号分隔）。",
+    "Fallback repository list when cache misses (comma-separated).",
+  );
+  appendEntry("ENABLE_HTTPS_PROXY", "true", "是否启用 HTTPS 代理处理（true/false），默认 true。", "Enable HTTPS proxy handling (true/false). Default: true.");
+  appendEntry("HTTPS_MITM_DOMAINS", "repo1.maven.org,repo.maven.apache.org,registry.npmjs.org", "执行 MITM 证书签发的域名列表（逗号分隔，支持通配符）。", "Domains for MITM certificate issuance (comma-separated, wildcard supported).");
+  appendEntry("HTTPS_PASSTHROUGH_FOR_UNMATCHED", "false", "未命中 MITM 域名时是否允许隧道透传，默认 false。", "Allow tunnel passthrough for unmatched MITM domains. Default: false.");
+  appendEntry("NPM_REGISTRY_DOMAINS", "registry.npmjs.org,registry.npmmirror.com,npm.pkg.github.com", "识别为 npm 生态并分流缓存的域名列表（支持通配符）。", "Domains recognized as npm ecosystem for cache routing (wildcard supported).");
+  appendEntry("MAVEN_REPO_DOMAINS", "repo1.maven.org,repo.maven.apache.org,jitpack.io,plugins.gradle.org,dl.google.com", "识别为 Maven 生态并分流缓存的域名列表（支持通配符）。", "Domains recognized as Maven ecosystem for cache routing (wildcard supported).");
+  appendEntry("MAVEN_CACHE_USE_DOMAIN_DIR", "false", "Maven 缓存是否按域名作为一级目录，默认 false。", "Whether Maven cache uses hostname as the first-level directory. Default: false.");
+  appendEntry("MAVEN_CACHE_IGNORE_PATH_PREFIXES", "repo1.maven.org/maven2,repo.maven.apache.org/maven2,jitpack.io/,plugins.gradle.org/m2,dl.google.com/dl/android/maven2,dl.google.com/dl/google/maven", "Maven 缓存应忽略的路径前缀规则（逗号分隔，支持 host/path 与 host:port/path）。", "Maven cache path-prefix ignore rules (comma-separated, supports host/path and host:port/path).");
+  appendEntry("MULTI_THREAD_DOMAINS", "repo1.maven.org", "启用多线程下载的域名列表（支持通配符）。", "Domains that enable multi-thread download (wildcard supported).");
+  appendEntry("MULTI_THREAD_COUNT", "8", "多线程下载线程数，默认 8。", "Thread count for multi-thread download. Default: 8.");
+  appendEntry("MULTI_THREAD_MIN_SIZE_MB", "1", "触发多线程下载的最小文件大小阈值（MB），默认 1。", "Minimum file size threshold in MB to trigger multi-thread download. Default: 1.");
+  appendEntry("DOWNLOAD_TIMEOUT", "60s", "上游请求超时时间（支持 s/m/h/d），默认 60s。", "Upstream request timeout (supports s/m/h/d). Default: 60s.");
+  appendEntry("DOWNLOAD_LOG_DIR", "data/logs/downloads", "统一主日志与错误日志目录。", "Unified main and error log directory.");
+  appendEntry("LOG_RETENTION", "7d", "日志保留时长（支持 s/m/h/d），默认 7d。", "Log retention duration (supports s/m/h/d). Default: 7d.");
+  appendEntry("LOG_TO_STDOUT", "false", "是否输出运行期日志到命令行，默认 false。", "Output runtime logs to stdout. Default: false.");
+  appendEntry("LOG_CONNECT_EVENTS", "false", "是否输出详细 CONNECT/MITM 握手日志，默认 false。", "Output detailed CONNECT/MITM handshake logs. Default: false.");
+  appendEntry("OUTBOUND_KEEP_ALIVE", "true", "是否启用出站 keep-alive 连接复用池，默认 true。", "Enable outbound keep-alive connection pool. Default: true.");
+  appendEntry("OUTBOUND_KEEP_ALIVE_INTERVAL", "1s", "keep-alive 间隔（支持 s/m/h/d），默认 1s。", "Keep-alive interval (supports s/m/h/d). Default: 1s.");
+  appendEntry("OUTBOUND_MAX_SOCKETS", "64", "每个源站最大出站连接数，默认 64。", "Maximum outbound sockets per upstream host. Default: 64.");
+  appendEntry("OUTBOUND_MAX_FREE_SOCKETS", "16", "每个源站可保留空闲连接上限，默认 16。", "Maximum free outbound sockets kept per upstream host. Default: 16.");
+  appendEntry("MAVEN_AFFINITY_ENABLED", "true", "是否启用 Maven affinity 缓存索引，默认 true。", "Enable Maven affinity index. Default: true.");
+  appendEntry("MAVEN_AFFINITY_INDEX_DIR", "data/index", "Maven affinity 索引目录，默认 data/index。", "Maven affinity index directory. Default: data/index.");
+  appendEntry("MAVEN_NEGATIVE_CACHE_TTL", "24h", "负缓存 TTL（支持 s/m/h/d），默认 24h。", "Negative cache TTL (supports s/m/h/d). Default: 24h.");
+  appendEntry("MAVEN_AFFINITY_FLUSH_INTERVAL", "5s", "affinity 事件日志 flush 周期（支持 s/m/h/d），默认 5s。", "Affinity event log flush interval (supports s/m/h/d). Default: 5s.");
+  appendEntry("MAVEN_AFFINITY_EVENT_MAX_MB", "8", "affinity 事件日志压缩阈值（MB），默认 8。", "Affinity event log compaction threshold in MB. Default: 8.");
+  appendEntry("UPSTREAM_PROXY_URL", "", "通用上级代理地址（HTTP/HTTPS 兜底）。", "Generic upstream proxy URL fallback for HTTP/HTTPS.");
+  appendEntry("UPSTREAM_HTTP_PROXY_URL", "", "HTTP 请求使用的上级代理地址。", "Upstream proxy URL for HTTP requests.");
+  appendEntry("UPSTREAM_HTTPS_PROXY_URL", "", "HTTPS 请求使用的上级代理地址。", "Upstream proxy URL for HTTPS requests.");
+  appendEntry("UPSTREAM_NO_PROXY", "127.0.0.1,localhost", "不走上级代理的域名列表（逗号分隔，支持通配符，* 表示全部直连）。", "Domains that bypass upstream proxy (comma-separated, wildcard supported, * means direct for all).");
+  appendEntry("UPSTREAM_IGNORE_DOMAINS", "", "额外忽略上级代理的域名列表（支持通配符）。", "Additional domains ignored by upstream proxy (wildcard supported).");
+  appendEntry("CERT_DIR", "data/certs", "证书根目录，默认 data/certs。", "Certificate root directory. Default: data/certs.");
+  appendEntry("ROOT_CERT_PATH", "data/certs/root-ca.crt", "Root CA 证书路径。", "Root CA certificate path.");
+  appendEntry("ROOT_KEY_PATH", "data/certs/root-ca.key.pem", "Root CA 私钥路径。", "Root CA private key path.");
+  appendEntry("LEAF_CERT_DIR", "data/certs/leaf", "站点叶子证书目录。", "Leaf certificate directory.");
+  appendEntry("TRUST_STORE_PATH", "data/certs/proxy-truststore.jks", "Java trust store 文件路径。", "Java trust store file path.");
+  appendEntry("TRUST_STORE_ALIAS", "maven-proxy-root-ca", "导入 Root CA 到 trust store 时使用的别名。", "Alias used to import Root CA into trust store.");
+  appendEntry("TRUST_STORE_PASSWORD", "changeit", "trust store 密码。", "Trust store password.");
+  appendEntry("EXISTING_TRUST_STORE_PATH", "", "已有 truststore 路径（可选），初始化时可作为源。", "Existing truststore path (optional), used as source during init.");
+  appendEntry("EXISTING_TRUST_STORE_PASSWORD", "", "已有 truststore 密码（可选），用于读取 EXISTING_TRUST_STORE_PATH。", "Existing truststore password (optional), used to read EXISTING_TRUST_STORE_PATH.");
+  appendEntry("JAVA_HOME", "", "Java 安装路径；为空或无效时会自动探测。", "Java installation path; auto-detected when empty or invalid.");
+
+  return `${lines.join("\n").trimEnd()}\n`;
 }
 
 async function initConfigFile(configFile, force = false) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maven-proxy",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Maven proxy with cache, HTTPS MITM for selected domains, and local repo publishing",
   "main": "src/index.js",
   "bin": {
@@ -19,6 +19,7 @@
     "cli:start": "node bin/maven-proxy.js start --mode development",
     "cli:stop": "node bin/maven-proxy.js stop",
     "cli:doctor": "node bin/maven-proxy.js doctor --mode development",
+    "cli:doctor:user": "node bin/maven-proxy.js doctor --mode user",
     "cli:truststore:print": "node bin/maven-proxy.js truststore print --mode development",
     "cli:truststore:init": "node bin/maven-proxy.js truststore init --mode development",
     "cli:truststore:merge": "node bin/maven-proxy.js truststore merge --mode development",

package/src/cache/cache-path.js

@@ -16,6 +16,162 @@ function looksLikeMavenVersionSegment(segment) {
   return /^\d[0-9A-Za-z._-]*$/.test(String(segment || ""));
 }
 
+function normalizeSlashPath(rawPath) {
+  const decoded = safeDecode(rawPath || "/").replace(/\\/g, "/").replace(/\/+/g, "/");
+  if (!decoded) {
+    return "/";
+  }
+  return decoded.startsWith("/") ? decoded : `/${decoded}`;
+}
+
+function trimTrailingSlash(normalizedPath) {
+  if (normalizedPath.length > 1 && normalizedPath.endsWith("/")) {
+    return normalizedPath.slice(0, -1);
+  }
+  return normalizedPath;
+}
+
+function normalizeRulePrefixPath(rawPrefix) {
+  return trimTrailingSlash(normalizeSlashPath(rawPrefix || "/"));
+}
+
+function getEffectivePort(urlObj) {
+  if (urlObj?.port) {
+    return String(urlObj.port);
+  }
+  return urlObj?.protocol === "https:" ? "443" : "80";
+}
+
+function parseMavenCacheIgnorePathRule(rawRule) {
+  const text = String(rawRule || "").trim();
+  if (!text) {
+    return null;
+  }
+
+  const firstSlash = text.indexOf("/");
+  if (firstSlash <= 0) {
+    return null;
+  }
+
+  const hostPortText = text.slice(0, firstSlash).trim().toLowerCase();
+  const prefixText = text.slice(firstSlash);
+  const hostMatch = hostPortText.match(/^([^:\/]+)(?::(\d+))?$/);
+  if (!hostMatch) {
+    return null;
+  }
+
+  const hostname = hostMatch[1];
+  const port = hostMatch[2] || "";
+  const pathPrefix = normalizeRulePrefixPath(prefixText);
+
+  return {
+    hostname,
+    port,
+    pathPrefix,
+    raw: text,
+  };
+}
+
+function ruleMatchesUrl(rule, urlObj) {
+  if (!rule || !urlObj) {
+    return false;
+  }
+
+  const hostname = String(urlObj.hostname || "").toLowerCase();
+  if (!hostname || hostname !== rule.hostname) {
+    return false;
+  }
+
+  if (!rule.port) {
+    return true;
+  }
+
+  return getEffectivePort(urlObj) === rule.port;
+}
+
+export function parseMavenCacheIgnorePathPrefixes(rawRules) {
+  const input = Array.isArray(rawRules) ? rawRules.join(",") : String(rawRules || "");
+  const tokens = input
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  const parsed = [];
+  const dedupe = new Set();
+
+  for (const token of tokens) {
+    const rule = parseMavenCacheIgnorePathRule(token);
+    if (!rule) {
+      continue;
+    }
+
+    const key = `${rule.hostname}:${rule.port}|${rule.pathPrefix}`;
+    if (dedupe.has(key)) {
+      continue;
+    }
+
+    dedupe.add(key);
+    parsed.push(rule);
+  }
+
+  return parsed;
+}
+
+export function stripMavenIgnoredPathPrefix(pathname, urlObj, rules = []) {
+  const normalizedPath = normalizeSlashPath(pathname || "/");
+  const validRules = Array.isArray(rules) ? rules : [];
+  if (validRules.length === 0 || !urlObj) {
+    return normalizedPath;
+  }
+
+  const matchedRules = validRules
+    .filter((rule) => ruleMatchesUrl(rule, urlObj))
+    .sort((a, b) => b.pathPrefix.length - a.pathPrefix.length);
+
+  for (const rule of matchedRules) {
+    const prefix = rule.pathPrefix;
+    if (prefix === "/") {
+      return normalizedPath;
+    }
+
+    if (normalizedPath === prefix) {
+      return "/";
+    }
+
+    if (normalizedPath.startsWith(`${prefix}/`)) {
+      const stripped = normalizedPath.slice(prefix.length);
+      return stripped || "/";
+    }
+  }
+
+  return normalizedPath;
+}
+
+export function buildMavenHostlessPathCandidates(pathname, rules = []) {
+  const normalizedPath = normalizeSlashPath(pathname || "/");
+  const candidates = new Set([normalizedPath]);
+  const validRules = Array.isArray(rules) ? rules : [];
+
+  for (const rule of validRules) {
+    const prefix = rule.pathPrefix;
+    if (!prefix || prefix === "/") {
+      continue;
+    }
+
+    if (normalizedPath === prefix) {
+      candidates.add("/");
+      continue;
+    }
+
+    if (normalizedPath.startsWith(`${prefix}/`)) {
+      const stripped = normalizedPath.slice(prefix.length);
+      candidates.add(stripped || "/");
+    }
+  }
+
+  return [...candidates];
+}
+
 function isLikelyMavenFilePath(parts, normalizedPath) {
   if (normalizedPath.endsWith("/") || parts.length === 0) {
     return false;
@@ -63,9 +219,14 @@ function isLikelyMavenFilePath(parts, normalizedPath) {
 export function getCacheFilePath(cacheDir, urlObj, options = {}) {
   const ecosystem = sanitizeSegment(String(options.ecosystem || "generic").toLowerCase());
   const includeHost = options.includeHost ?? ecosystem !== "maven";
+  const mavenIgnoreRules = options.mavenCacheIgnorePathPrefixRules || [];
 
   const rawPathname = safeDecode(urlObj.pathname || "/");
-  const normalized = rawPathname.replace(/\\/g, "/");
+  let normalized = rawPathname.replace(/\\/g, "/");
+  if (ecosystem === "maven") {
+    normalized = stripMavenIgnoredPathPrefix(normalized, urlObj, mavenIgnoreRules);
+  }
+
   const lowerNormalized = normalized.toLowerCase();
   const parts = normalized.split("/").filter(Boolean);
 

package/src/config/config.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import dotenv from "dotenv";
 import { detectJavaHome } from "../common/java-home.js";
+import { parseMavenCacheIgnorePathPrefixes } from "../cache/cache-path.js";
 
 const cwd = process.cwd();
 const userConfigDir = path.resolve(os.homedir(), "maven-proxy");
@@ -193,7 +194,16 @@ const defaultRepoFallbackRepos = [
   "https://repo1.maven.org/maven2",
   "https://jitpack.io",
   "https://plugins.gradle.org/m2",
-  "https://maven.google.com",
+  "https://dl.google.com",
+];
+
+const defaultMavenCacheIgnorePathPrefixes = [
+  "repo1.maven.org/maven2",
+  "repo.maven.apache.org/maven2",
+  "jitpack.io/",
+  "plugins.gradle.org/m2",
+  "dl.google.com/dl/android/maven2",
+  "dl.google.com/dl/google/maven",
 ];
 
 const repoFallbackRepos = normalizeRepoList(
@@ -201,12 +211,16 @@ const repoFallbackRepos = normalizeRepoList(
   defaultRepoFallbackRepos,
 );
 
+const mavenCacheIgnorePathPrefixes = String(process.env.MAVEN_CACHE_IGNORE_PATH_PREFIXES || "").trim()
+  || defaultMavenCacheIgnorePathPrefixes.join(",");
+const mavenCacheIgnorePathPrefixRules = parseMavenCacheIgnorePathPrefixes(mavenCacheIgnorePathPrefixes);
+
 const defaultMavenRepoDomains = [
   "repo1.maven.org",
   "repo.maven.apache.org",
   "jitpack.io",
   "plugins.gradle.org",
-  "maven.google.com",
+  "dl.google.com",
   ...extractHostsFromUrls(repoFallbackRepos),
 ];
 
@@ -241,6 +255,9 @@ export const config = {
   httpsMitmDomains: toList(process.env.HTTPS_MITM_DOMAINS, ["repo1.maven.org", "repo.maven.apache.org", "registry.npmjs.org"]),
   npmRegistryDomains: toList(process.env.NPM_REGISTRY_DOMAINS, ["registry.npmjs.org", "registry.npmmirror.com", "npm.pkg.github.com"]),
   mavenRepoDomains: toList(process.env.MAVEN_REPO_DOMAINS, [...new Set(defaultMavenRepoDomains)]),
+  mavenCacheUseDomainDir: toBool(process.env.MAVEN_CACHE_USE_DOMAIN_DIR, false),
+  mavenCacheIgnorePathPrefixes,
+  mavenCacheIgnorePathPrefixRules,
   multiThreadDomains: toList(process.env.MULTI_THREAD_DOMAINS, ["repo1.maven.org"]),
   multiThreadCount: Math.max(1, toInt(process.env.MULTI_THREAD_COUNT, 4)),
   multiThreadMinSizeBytes,

package/src/index.js

@@ -120,6 +120,8 @@ async function main() {
   startupInfo(`[maven-proxy] repo  port: ${config.repoPort}`);
   startupInfo(`[maven-proxy] cache dir : ${config.cacheDir}`);
   startupInfo(`[maven-proxy] cache maven: ${config.mavenCacheDir}`);
+  startupInfo(`[maven-proxy] maven cache use domain dir: ${config.mavenCacheUseDomainDir}`);
+  startupInfo(`[maven-proxy] maven cache ignore path prefixes: ${config.mavenCacheIgnorePathPrefixes || "(none)"}`);
   startupInfo(`[maven-proxy] cache npm  : ${config.npmCacheDir}`);
   startupInfo(`[maven-proxy] cache other: ${config.genericCacheDir}`);
   startupInfo(`[maven-proxy] log dir: ${config.downloadLogDir}`);

package/src/proxy/proxy-http-handler.js

@@ -200,7 +200,8 @@ export function createHttpRequestHandler({
       ecosystem = detectPackageEcosystem(urlObj, config, matchesDomain);
       cachePath = getCacheFilePath(config.cacheDir, urlObj, {
         ecosystem,
-        includeHost: ecosystem !== "maven",
+        includeHost: ecosystem !== "maven" || config.mavenCacheUseDomainDir,
+        mavenCacheIgnorePathPrefixRules: config.mavenCacheIgnorePathPrefixRules,
       });
 
       if (ecosystem === "maven" && mavenAffinityIndex?.enabled) {
@@ -220,7 +221,9 @@ export function createHttpRequestHandler({
     }
 
     if (canonical && mavenAffinityIndex) {
-      if (isPositiveAffinityEligible(canonical.fileName)) {
+      const canUsePositiveAffinity = !config.mavenCacheUseDomainDir && isPositiveAffinityEligible(canonical.fileName);
+
+      if (canUsePositiveAffinity) {
         const preferredPath = await mavenAffinityIndex.resolvePreferredCachePath(canonical.canonicalKey);
         if (preferredPath) {
           console.log(`[proxy] affinity hit canonical=${canonical.canonicalKey} host=${urlObj.hostname}`);
@@ -244,7 +247,12 @@ export function createHttpRequestHandler({
       await fs.promises.mkdir(path.dirname(cachePath), { recursive: true });
       await downloader.ensureCached(urlObj, cachePath, req.headers);
 
-      if (canonical && mavenAffinityIndex && isPositiveAffinityEligible(canonical.fileName)) {
+      if (
+        canonical &&
+        mavenAffinityIndex &&
+        !config.mavenCacheUseDomainDir &&
+        isPositiveAffinityEligible(canonical.fileName)
+      ) {
         mavenAffinityIndex.recordSuccess({
           canonicalKey: canonical.canonicalKey,
           host: urlObj.hostname,

package/src/repo/repo-server.js

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
+import {
+  buildMavenHostlessPathCandidates,
+  stripMavenIgnoredPathPrefix,
+} from "../cache/cache-path.js";
 
 function safeJoin(baseDir, requestPath) {
   const pathname = decodeURIComponent(requestPath || "/");
@@ -13,6 +17,58 @@ function safeJoin(baseDir, requestPath) {
   return path.join(baseDir, normalized);
 }
 
+function sanitizeHostSegment(hostname) {
+  return String(hostname || "unknown").toLowerCase().replace(/[<>:\\"|?*]/g, "_");
+}
+
+function collectRepoHosts(repoBases = []) {
+  const hosts = new Set();
+
+  for (const repoBase of repoBases) {
+    try {
+      const parsed = new URL(repoBase);
+      hosts.add(sanitizeHostSegment(parsed.hostname));
+    } catch {
+      // ignore invalid URL
+    }
+  }
+
+  return [...hosts];
+}
+
+function buildDomainScopedPath(mavenCacheDir, hostname, relativePath) {
+  const hostDir = sanitizeHostSegment(hostname);
+  return safeJoin(path.join(mavenCacheDir, hostDir), relativePath);
+}
+
+function normalizeRelativePathForHost(relativePath, hostname, rules = []) {
+  const inputPath = `/${String(relativePath || "").replace(/^\/+/, "")}`;
+  const normalized = stripMavenIgnoredPathPrefix(
+    inputPath,
+    { protocol: "https:", hostname, port: "" },
+    rules,
+  );
+  return normalized.replace(/^\/+/, "");
+}
+
+function normalizeRelativePathCandidates(relativePath, rules = []) {
+  const inputPath = `/${String(relativePath || "").replace(/^\/+/, "")}`;
+  const candidates = buildMavenHostlessPathCandidates(inputPath, rules);
+  return candidates.map((item) => item.replace(/^\/+/, ""));
+}
+
+function buildDefaultRepoFilePath(config, relativePath) {
+  if (!config.mavenCacheUseDomainDir) {
+    const candidates = normalizeRelativePathCandidates(relativePath, config.mavenCacheIgnorePathPrefixRules);
+    return safeJoin(config.mavenCacheDir, candidates[0] || relativePath);
+  }
+
+  const hosts = collectRepoHosts(config.repoFallbackRepos || []);
+  const host = hosts[0] || "unknown";
+  const normalized = normalizeRelativePathForHost(relativePath, host, config.mavenCacheIgnorePathPrefixRules);
+  return buildDomainScopedPath(config.mavenCacheDir, host, normalized || relativePath);
+}
+
 async function statIfExists(filePath) {
   try {
     return await fs.promises.stat(filePath);
@@ -24,6 +80,68 @@ async function statIfExists(filePath) {
   }
 }
 
+async function findCachedMavenFile(config, relativePath) {
+  const ignoreRules = config.mavenCacheIgnorePathPrefixRules || [];
+
+  if (!config.mavenCacheUseDomainDir) {
+    const candidates = normalizeRelativePathCandidates(relativePath, ignoreRules);
+    for (const candidate of candidates) {
+      const filePath = safeJoin(config.mavenCacheDir, candidate);
+      const stats = await statIfExists(filePath);
+      if (stats && stats.isFile()) {
+        return { filePath, stats };
+      }
+    }
+
+    const fallbackPath = safeJoin(config.mavenCacheDir, candidates[0] || relativePath);
+    return { filePath: fallbackPath, stats: null };
+  }
+
+  const checkedHosts = new Set();
+  const preferredHosts = collectRepoHosts(config.repoFallbackRepos || []);
+
+  for (const host of preferredHosts) {
+    checkedHosts.add(host);
+    const normalized = normalizeRelativePathForHost(relativePath, host, ignoreRules);
+    const filePath = buildDomainScopedPath(config.mavenCacheDir, host, normalized || relativePath);
+    const stats = await statIfExists(filePath);
+    if (stats && stats.isFile()) {
+      return { filePath, stats };
+    }
+  }
+
+  let entries = [];
+  try {
+    entries = await fs.promises.readdir(config.mavenCacheDir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    if (checkedHosts.has(entry.name)) {
+      continue;
+    }
+
+    const normalized = normalizeRelativePathForHost(relativePath, entry.name, ignoreRules);
+    const filePath = safeJoin(path.join(config.mavenCacheDir, entry.name), normalized || relativePath);
+    const stats = await statIfExists(filePath);
+    if (stats && stats.isFile()) {
+      return { filePath, stats };
+    }
+  }
+
+  return {
+    filePath: buildDefaultRepoFilePath(config, relativePath),
+    stats: null,
+  };
+}
+
 function buildRemoteUrl(repoBase, relativePath) {
   const base = repoBase.endsWith("/") ? repoBase : `${repoBase}/`;
   const relative = relativePath.replace(/^\/+/, "");
@@ -41,31 +159,45 @@ function buildCandidateRelativePaths(relativePath) {
   return [...new Set(candidates.filter(Boolean))];
 }
 
-async function ensureFromRemoteRepos(config, downloader, filePath, relativePath, cacheCleanupManager = null) {
+async function ensureFromRemoteRepos(config, downloader, relativePath, cacheCleanupManager = null) {
   if (!downloader) {
-    return null;
+    return { filePath: buildDefaultRepoFilePath(config, relativePath), stats: null };
   }
 
   const repos = config.repoFallbackRepos || [];
   if (repos.length === 0) {
-    return null;
+    return { filePath: buildDefaultRepoFilePath(config, relativePath), stats: null };
   }
 
   let hasNon404Error = false;
   let lastError = null;
   const candidatePaths = buildCandidateRelativePaths(relativePath);
+  const ignoreRules = config.mavenCacheIgnorePathPrefixRules || [];
 
   for (const repoBase of repos) {
     for (const candidatePath of candidatePaths) {
       const remoteUrl = buildRemoteUrl(repoBase, candidatePath);
 
       try {
+        const normalizedRelativePath = normalizeRelativePathForHost(
+          relativePath,
+          remoteUrl.hostname,
+          ignoreRules,
+        ) || relativePath;
+
+        const targetPath = config.mavenCacheUseDomainDir
+          ? buildDomainScopedPath(config.mavenCacheDir, remoteUrl.hostname, normalizedRelativePath)
+          : safeJoin(config.mavenCacheDir, normalizedRelativePath);
+
         if (cacheCleanupManager) {
           await cacheCleanupManager.checkAndCleanupIfNeeded("repo-cache-miss");
         }
         console.log(`[repo] cache miss, try remote ${remoteUrl.href}`);
-        await downloader.ensureCached(remoteUrl, filePath, {});
-        return await statIfExists(filePath);
+        await downloader.ensureCached(remoteUrl, targetPath, {});
+        return {
+          filePath: targetPath,
+          stats: await statIfExists(targetPath),
+        };
       } catch (error) {
         lastError = error;
         if (error.statusCode !== 404) {
@@ -79,7 +211,7 @@ async function ensureFromRemoteRepos(config, downloader, filePath, relativePath,
     throw lastError;
   }
 
-  return null;
+  return { filePath: buildDefaultRepoFilePath(config, relativePath), stats: null };
 }
 
 export function startRepoServer(config, downloader = null, cacheCleanupManager = null) {
@@ -87,11 +219,12 @@ export function startRepoServer(config, downloader = null, cacheCleanupManager =
     try {
       const urlObj = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
       const relativePath = path.posix.normalize(urlObj.pathname || "/").replace(/^\/+/, "");
-      const filePath = safeJoin(config.mavenCacheDir, relativePath);
-      let stats = await statIfExists(filePath);
+      let { filePath, stats } = await findCachedMavenFile(config, relativePath);
 
       if (!stats || !stats.isFile()) {
-        stats = await ensureFromRemoteRepos(config, downloader, filePath, relativePath, cacheCleanupManager);
+        const fetched = await ensureFromRemoteRepos(config, downloader, relativePath, cacheCleanupManager);
+        filePath = fetched.filePath;
+        stats = fetched.stats;
       }
 
       if (!stats || !stats.isFile()) {