@undefineds.co/xpod 0.1.0-local.202602081751

package/dist/edge/EdgeNodeDnsCoordinator.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeNodeDnsCoordinator = void 0;
+const global_logger_factory_1 = require("global-logger-factory");
+class EdgeNodeDnsCoordinator {
+    constructor(options) {
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.provider = options.provider;
+        this.rootDomain = this.normalizeRootDomain(options.rootDomain);
+        this.defaultRecordType = options.defaultRecordType ?? 'A';
+        this.ttl = this.normalizeTtl(options.ttl);
+        this.clusterIp = this.extractString(options.clusterIp);
+        this.enabled = Boolean(this.rootDomain);
+    }
+    async synchronize(nodeId, metadata) {
+        if (!this.enabled) {
+            return;
+        }
+        const hints = this.extractDnsHints(metadata);
+        // Extract subdomain and access mode
+        const subdomain = this.extractString(metadata.subdomain) ?? hints?.subdomain;
+        if (!subdomain) {
+            this.logger.debug(`Node ${nodeId} 未提供 subdomain，跳过 DNS 同步。`);
+            return;
+        }
+        const accessMode = this.extractString(metadata.accessMode);
+        const normalizedAccessMode = accessMode?.trim().toLowerCase();
+        // Determine DNS target based on access mode
+        let target;
+        let recordType;
+        if (normalizedAccessMode === 'direct') {
+            // Direct mode: DNS 指向节点公网 IP
+            // 优先使用 IPv6（如果有），因为可以避免 NAT 问题
+            const ipv6 = this.extractString(metadata.ipv6);
+            const ipv4 = this.extractString(metadata.ipv4);
+            const publicIp = this.extractString(metadata.publicIp);
+            const publicAddress = this.extractString(metadata.publicAddress);
+            // IPv6 优先策略：如果有公网 IPv6，优先使用
+            if (ipv6 && this.isIpv6(ipv6)) {
+                target = ipv6;
+                recordType = 'AAAA';
+                this.logger.debug(`Node ${nodeId} 使用 IPv6 地址: ${ipv6}`);
+            }
+            else {
+                target = publicIp ?? ipv4 ?? publicAddress;
+            }
+            if (!target && hints?.target) {
+                target = hints.target;
+            }
+            if (!target) {
+                this.logger.warn(`Node ${nodeId} (direct mode) 未提供公网 IP，跳过 DNS 同步。`);
+                return;
+            }
+        }
+        else if (normalizedAccessMode === 'proxy') {
+            // Proxy mode: DNS 指向 Cluster IP
+            if (!this.clusterIp) {
+                this.logger.debug(`Cluster IP 未配置，跳过 proxy 模式节点 ${nodeId} 的 DNS 同步。`);
+                return;
+            }
+            target = this.clusterIp;
+        }
+        else if (hints?.target) {
+            // Fallback: 使用旧的逻辑从 metadata 提取
+            target = hints.target;
+        }
+        else {
+            this.logger.debug(`Node ${nodeId} 未提供 accessMode/dns hints，跳过同步。`);
+            return;
+        }
+        const type = recordType ?? this.detectRecordType(target) ?? this.defaultRecordType;
+        const value = this.normalizeRecordValue(target, type);
+        if (!value) {
+            this.logger.warn(`Edge node ${nodeId} DNS 目标解析失败，跳过同步。`);
+            return;
+        }
+        try {
+            await this.provider.upsertRecord({
+                domain: this.rootDomain,
+                subdomain,
+                type,
+                value,
+                ttl: this.ttl,
+            });
+            const loggedMode = normalizedAccessMode ?? 'unknown';
+            this.logger.info(`已同步节点 ${nodeId} (${loggedMode}) 的 DNS: ${subdomain}.${this.rootDomain} -> ${value}`);
+        }
+        catch (error) {
+            this.logger.error(`同步节点 ${nodeId} DNS 记录失败: ${error.message}`);
+            throw error;
+        }
+    }
+    extractDnsHints(metadata) {
+        const dns = metadata?.dns;
+        if (!dns || typeof dns !== 'object') {
+            return undefined;
+        }
+        const subdomain = this.extractString(dns.subdomain);
+        if (!subdomain) {
+            return undefined;
+        }
+        const target = this.extractString(dns.target)
+            ?? this.extractString(metadata.publicAddress)
+            ?? this.extractString(metadata.baseUrl);
+        if (!target) {
+            return undefined;
+        }
+        return { subdomain, target };
+    }
+    extractString(value) {
+        if (typeof value !== 'string') {
+            return undefined;
+        }
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    detectRecordType(target) {
+        const host = this.extractHost(target) ?? target;
+        if (this.isIpv4(host)) {
+            return 'A';
+        }
+        if (this.isIpv6(host)) {
+            return 'AAAA';
+        }
+        if (host.includes('.')) {
+            return 'CNAME';
+        }
+        return undefined;
+    }
+    normalizeRecordValue(target, type) {
+        const host = this.extractHost(target) ?? target;
+        if (type === 'A' && this.isIpv4(host)) {
+            return host;
+        }
+        if (type === 'AAAA' && this.isIpv6(host)) {
+            return host;
+        }
+        if (type === 'CNAME') {
+            return host.endsWith('.') ? host : `${host}.`;
+        }
+        if (type === 'TXT') {
+            return host;
+        }
+        return undefined;
+    }
+    extractHost(input) {
+        try {
+            const url = new URL(input);
+            return url.hostname;
+        }
+        catch {
+            return input;
+        }
+    }
+    isIpv4(value) {
+        const parts = value.split('.');
+        if (parts.length !== 4) {
+            return false;
+        }
+        return parts.every((part) => {
+            if (!/^[0-9]{1,3}$/.test(part)) {
+                return false;
+            }
+            const num = Number(part);
+            return num >= 0 && num <= 255;
+        });
+    }
+    isIpv6(value) {
+        return /^[0-9a-fA-F:]+$/.test(value) && value.includes(':');
+    }
+    normalizeRootDomain(value) {
+        if (typeof value !== 'string') {
+            return undefined;
+        }
+        let trimmed = value.trim();
+        if (trimmed.includes('://')) {
+            try {
+                trimmed = new URL(trimmed).hostname;
+            }
+            catch {
+                // ignore
+            }
+        }
+        trimmed = trimmed.replace(/\.$/, '');
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    normalizeTtl(value) {
+        if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+            return Math.trunc(value);
+        }
+        if (typeof value === 'string') {
+            const parsed = Number(value.trim());
+            if (Number.isFinite(parsed) && parsed > 0) {
+                return Math.trunc(parsed);
+            }
+        }
+        return undefined;
+    }
+}
+exports.EdgeNodeDnsCoordinator = EdgeNodeDnsCoordinator;
+//# sourceMappingURL=EdgeNodeDnsCoordinator.js.map

package/dist/edge/EdgeNodeDnsCoordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeNodeDnsCoordinator.js","sourceRoot":"","sources":["../../src/edge/EdgeNodeDnsCoordinator.ts"],"names":[],"mappings":";;;AAAA,iEAAqD;AAqBrD,MAAa,sBAAsB;IASjC,YAAmB,OAAsC;QARxC,WAAM,GAAG,IAAA,oCAAY,EAAC,IAAI,CAAC,CAAC;QAS3C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC/D,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,GAAG,CAAC;QAC1D,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC;IAEM,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,QAAiC;QACxE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;QAE7C,oCAAoC;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,EAAE,SAAS,CAAC;QAC7E,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,MAAM,2BAA2B,CAAC,CAAC;YAC7D,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAC3D,MAAM,oBAAoB,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE9D,4CAA4C;QAC5C,IAAI,MAA0B,CAAC;QAC/B,IAAI,UAA0C,CAAC;QAE/C,IAAI,oBAAoB,KAAK,QAAQ,EAAE,CAAC;YACtC,6BAA6B;YAC7B,+BAA+B;YAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACvD,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;YAEjE,4BAA4B;YAC5B,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,MAAM,GAAG,IAAI,CAAC;gBACd,UAAU,GAAG,MAAM,CAAC;gBACpB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,MAAM,gBAAgB,IAAI,EAAE,CAAC,CAAC;YAC1D,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,QAAQ,IAAI,IAAI,IAAI,aAAa,CAAC;YAC7C,CAAC;YAED,IAAI,CAAC,MAAM,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;gBAC7B,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACxB,CAAC;YAED,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,MAAM,oCAAoC,CAAC,CAAC;gBACrE,OAAO;YACT,CAAC;QACH,CAAC;aAAM,IAAI,oBAAoB,KAAK,OAAO,EAAE,CAAC;YAC5C,gCAAgC;YAChC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;gBACpB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,MAAM,YAAY,CAAC,CAAC;gBACtE,OAAO;YACT,CAAC;YACD,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,CAAC;aAAM,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;YACzB,gCAAgC;YAChC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,MAAM,iCAAiC,CAAC,CAAC;YACnE,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,UAAU,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,iBAAiB,CAAC;QACnF,MAAM,KAAK,GAAG,IAAI,CAAC,oBAAoB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAEtD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,MAAM,mBAAmB,CAAC,CAAC;YACzD,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;gBAC/B,MAAM,EAAE,IAAI,CAAC,UAAW;gBACxB,SAAS;gBACT,IAAI;gBACJ,KAAK;gBACL,GAAG,EAAE,IAAI,CAAC,GAAG;aACd,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,oBAAoB,IAAI,SAAS,CAAC;YACrD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,KAAK,UAAU,YAAY,SAAS,IAAI,IAAI,CAAC,UAAU,OAAO,KAAK,EAAE,CAAC,CAAC;QACzG,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,MAAM,cAAe,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,QAAiC;QACvD,MAAM,GAAG,GAAG,QAAQ,EAAE,GAAG,CAAC;QAC1B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAE,GAA+B,CAAC,SAAS,CAAC,CAAC;QACjF,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAE,GAA+B,CAAC,MAAM,CAAC;eACrE,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC;eAC1C,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAE1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAC/B,CAAC;IAEO,aAAa,CAAC,KAAc;QAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IAEO,gBAAgB,CAAC,MAAc;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC;QAChD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,OAAO,GAAG,CAAC;QACb,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,oBAAoB,CAAC,MAAc,EAAE,IAAwB;QACnE,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC;QAChD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC;QAChD,CAAC;QACD,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,WAAW,CAAC,KAAa;QAC/B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;YAC3B,OAAO,GAAG,CAAC,QAAQ,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,KAAa;QAC1B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE;YAC1B,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YACzB,OAAO,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,GAAG,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAa;QAC1B,OAAO,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IAEO,mBAAmB,CAAC,KAAqB;QAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;QACH,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACrC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IAEO,YAAY,CAAC,KAA8B;QACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACrE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACpC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAzND,wDAyNC","sourcesContent":["import { getLoggerFor } from 'global-logger-factory';\nimport type { DnsProvider, DnsRecordTypeValue } from '../dns/DnsProvider';\n\nexport interface EdgeNodeDnsCoordinatorOptions {\n  provider: DnsProvider;\n  /** 顶级域名，例如 `xpod.example`。 */\n  rootDomain?: string | null;\n  /**\n   * 默认记录类型，当目标地址无法识别时回退使用。\n   * 一般为 `A`（IPv4）或 `AAAA`（IPv6）。\n   */\n  defaultRecordType?: DnsRecordTypeValue;\n  /** TTL 秒数，缺省按供应商默认。 */\n  ttl?: number | string | null;\n  /**\n   * Cluster 的公网 IP 地址，用于 proxy 模式的 DNS 指向。\n   * 如果未设置，proxy 模式节点将跳过 DNS 同步。\n   */\n  clusterIp?: string | null;\n}\n\nexport class EdgeNodeDnsCoordinator {\n  private readonly logger = getLoggerFor(this);\n  private readonly provider: DnsProvider;\n  private readonly rootDomain?: string;\n  private readonly defaultRecordType: DnsRecordTypeValue;\n  private readonly ttl?: number;\n  private readonly clusterIp?: string;\n  private readonly enabled: boolean;\n\n  public constructor(options: EdgeNodeDnsCoordinatorOptions) {\n    this.provider = options.provider;\n    this.rootDomain = this.normalizeRootDomain(options.rootDomain);\n    this.defaultRecordType = options.defaultRecordType ?? 'A';\n    this.ttl = this.normalizeTtl(options.ttl);\n    this.clusterIp = this.extractString(options.clusterIp);\n    this.enabled = Boolean(this.rootDomain);\n  }\n\n  public async synchronize(nodeId: string, metadata: Record<string, unknown>): Promise<void> {\n    if (!this.enabled) {\n      return;\n    }\n    \n    const hints = this.extractDnsHints(metadata);\n\n    // Extract subdomain and access mode\n    const subdomain = this.extractString(metadata.subdomain) ?? hints?.subdomain;\n    if (!subdomain) {\n      this.logger.debug(`Node ${nodeId} 未提供 subdomain，跳过 DNS 同步。`);\n      return;\n    }\n    \n    const accessMode = this.extractString(metadata.accessMode);\n    const normalizedAccessMode = accessMode?.trim().toLowerCase();\n    \n    // Determine DNS target based on access mode\n    let target: string | undefined;\n    let recordType: DnsRecordTypeValue | undefined;\n    \n    if (normalizedAccessMode === 'direct') {\n      // Direct mode: DNS 指向节点公网 IP\n      // 优先使用 IPv6（如果有），因为可以避免 NAT 问题\n      const ipv6 = this.extractString(metadata.ipv6);\n      const ipv4 = this.extractString(metadata.ipv4);\n      const publicIp = this.extractString(metadata.publicIp);\n      const publicAddress = this.extractString(metadata.publicAddress);\n      \n      // IPv6 优先策略：如果有公网 IPv6，优先使用\n      if (ipv6 && this.isIpv6(ipv6)) {\n        target = ipv6;\n        recordType = 'AAAA';\n        this.logger.debug(`Node ${nodeId} 使用 IPv6 地址: ${ipv6}`);\n      } else {\n        target = publicIp ?? ipv4 ?? publicAddress;\n      }\n      \n      if (!target && hints?.target) {\n        target = hints.target;\n      }\n\n      if (!target) {\n        this.logger.warn(`Node ${nodeId} (direct mode) 未提供公网 IP，跳过 DNS 同步。`);\n        return;\n      }\n    } else if (normalizedAccessMode === 'proxy') {\n      // Proxy mode: DNS 指向 Cluster IP\n      if (!this.clusterIp) {\n        this.logger.debug(`Cluster IP 未配置，跳过 proxy 模式节点 ${nodeId} 的 DNS 同步。`);\n        return;\n      }\n      target = this.clusterIp;\n    } else if (hints?.target) {\n      // Fallback: 使用旧的逻辑从 metadata 提取\n      target = hints.target;\n    } else {\n      this.logger.debug(`Node ${nodeId} 未提供 accessMode/dns hints，跳过同步。`);\n      return;\n    }\n    \n    const type = recordType ?? this.detectRecordType(target) ?? this.defaultRecordType;\n    const value = this.normalizeRecordValue(target, type);\n\n    if (!value) {\n      this.logger.warn(`Edge node ${nodeId} DNS 目标解析失败，跳过同步。`);\n      return;\n    }\n\n    try {\n      await this.provider.upsertRecord({\n        domain: this.rootDomain!,\n        subdomain,\n        type,\n        value,\n        ttl: this.ttl,\n      });\n      const loggedMode = normalizedAccessMode ?? 'unknown';\n      this.logger.info(`已同步节点 ${nodeId} (${loggedMode}) 的 DNS: ${subdomain}.${this.rootDomain} -> ${value}`);\n    } catch (error: unknown) {\n      this.logger.error(`同步节点 ${nodeId} DNS 记录失败: ${(error as Error).message}`);\n      throw error;\n    }\n  }\n\n  private extractDnsHints(metadata: Record<string, unknown>): { subdomain: string; target: string } | undefined {\n    const dns = metadata?.dns;\n    if (!dns || typeof dns !== 'object') {\n      return undefined;\n    }\n    const subdomain = this.extractString((dns as Record<string, unknown>).subdomain);\n    if (!subdomain) {\n      return undefined;\n    }\n\n    const target = this.extractString((dns as Record<string, unknown>).target)\n      ?? this.extractString(metadata.publicAddress)\n      ?? this.extractString(metadata.baseUrl);\n\n    if (!target) {\n      return undefined;\n    }\n    return { subdomain, target };\n  }\n\n  private extractString(value: unknown): string | undefined {\n    if (typeof value !== 'string') {\n      return undefined;\n    }\n    const trimmed = value.trim();\n    return trimmed.length > 0 ? trimmed : undefined;\n  }\n\n  private detectRecordType(target: string): DnsRecordTypeValue | undefined {\n    const host = this.extractHost(target) ?? target;\n    if (this.isIpv4(host)) {\n      return 'A';\n    }\n    if (this.isIpv6(host)) {\n      return 'AAAA';\n    }\n    if (host.includes('.')) {\n      return 'CNAME';\n    }\n    return undefined;\n  }\n\n  private normalizeRecordValue(target: string, type: DnsRecordTypeValue): string | undefined {\n    const host = this.extractHost(target) ?? target;\n    if (type === 'A' && this.isIpv4(host)) {\n      return host;\n    }\n    if (type === 'AAAA' && this.isIpv6(host)) {\n      return host;\n    }\n    if (type === 'CNAME') {\n      return host.endsWith('.') ? host : `${host}.`;\n    }\n    if (type === 'TXT') {\n      return host;\n    }\n    return undefined;\n  }\n\n  private extractHost(input: string): string | undefined {\n    try {\n      const url = new URL(input);\n      return url.hostname;\n    } catch {\n      return input;\n    }\n  }\n\n  private isIpv4(value: string): boolean {\n    const parts = value.split('.');\n    if (parts.length !== 4) {\n      return false;\n    }\n    return parts.every((part) => {\n      if (!/^[0-9]{1,3}$/.test(part)) {\n        return false;\n      }\n      const num = Number(part);\n      return num >= 0 && num <= 255;\n    });\n  }\n\n  private isIpv6(value: string): boolean {\n    return /^[0-9a-fA-F:]+$/.test(value) && value.includes(':');\n  }\n\n  private normalizeRootDomain(value?: string | null): string | undefined {\n    if (typeof value !== 'string') {\n      return undefined;\n    }\n    let trimmed = value.trim();\n    if (trimmed.includes('://')) {\n      try {\n        trimmed = new URL(trimmed).hostname;\n      } catch {\n        // ignore\n      }\n    }\n    trimmed = trimmed.replace(/\\.$/, '');\n    return trimmed.length > 0 ? trimmed : undefined;\n  }\n\n  private normalizeTtl(value?: number | string | null): number | undefined {\n    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {\n      return Math.trunc(value);\n    }\n    if (typeof value === 'string') {\n      const parsed = Number(value.trim());\n      if (Number.isFinite(parsed) && parsed > 0) {\n        return Math.trunc(parsed);\n      }\n    }\n    return undefined;\n  }\n}\n"]}

package/dist/edge/EdgeNodeDnsCoordinator.jsonld

@@ -0,0 +1,212 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator",
+      "@type": "Class",
+      "requireElement": "EdgeNodeDnsCoordinator",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_provider",
+          "range": "undefineds:dist/dns/DnsProvider.jsonld#DnsProvider"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_rootDomain",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeWildcard"
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "顶级域名，例如 `xpod.example`。"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_defaultRecordType",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              {
+                "@type": "ParameterRangeUnion",
+                "parameterRangeElements": [
+                  {
+                    "@type": "ParameterRangeLiteral",
+                    "parameterRangeValueLiteral": "A"
+                  },
+                  {
+                    "@type": "ParameterRangeLiteral",
+                    "parameterRangeValueLiteral": "AAAA"
+                  },
+                  {
+                    "@type": "ParameterRangeLiteral",
+                    "parameterRangeValueLiteral": "CNAME"
+                  },
+                  {
+                    "@type": "ParameterRangeLiteral",
+                    "parameterRangeValueLiteral": "TXT"
+                  }
+                ]
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "默认记录类型，当目标地址无法识别时回退使用。 一般为 `A`（IPv4）或 `AAAA`（IPv6）。"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_ttl",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              "xsd:string",
+              {
+                "@type": "ParameterRangeWildcard"
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "TTL 秒数，缺省按供应商默认。"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_clusterIp",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeWildcard"
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "Cluster 的公网 IP 地址，用于 proxy 模式的 DNS 指向。 如果未设置，proxy 模式节点将跳过 DNS 同步。"
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_logger",
+          "memberFieldName": "logger"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_provider",
+          "memberFieldName": "provider"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_rootDomain",
+          "memberFieldName": "rootDomain"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_defaultRecordType",
+          "memberFieldName": "defaultRecordType"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_ttl",
+          "memberFieldName": "ttl"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_clusterIp",
+          "memberFieldName": "clusterIp"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_enabled",
+          "memberFieldName": "enabled"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_synchronize",
+          "memberFieldName": "synchronize"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_extractDnsHints",
+          "memberFieldName": "extractDnsHints"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_extractString",
+          "memberFieldName": "extractString"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_detectRecordType",
+          "memberFieldName": "detectRecordType"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_normalizeRecordValue",
+          "memberFieldName": "normalizeRecordValue"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_extractHost",
+          "memberFieldName": "extractHost"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_isIpv4",
+          "memberFieldName": "isIpv4"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_isIpv6",
+          "memberFieldName": "isIpv6"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_normalizeRootDomain",
+          "memberFieldName": "normalizeRootDomain"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator__member_normalizeTtl",
+          "memberFieldName": "normalizeTtl"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options__constructorArgument",
+          "fields": [
+            {
+              "keyRaw": "provider",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_provider"
+              }
+            },
+            {
+              "keyRaw": "rootDomain",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_rootDomain"
+              }
+            },
+            {
+              "keyRaw": "defaultRecordType",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_defaultRecordType"
+              }
+            },
+            {
+              "keyRaw": "ttl",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_ttl"
+              }
+            },
+            {
+              "keyRaw": "clusterIp",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeDnsCoordinator.jsonld#EdgeNodeDnsCoordinator_options_clusterIp"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/edge/EdgeNodeHealthProbeService.d.ts

@@ -0,0 +1,25 @@
+import { EdgeNodeRepository } from '../identity/drizzle/EdgeNodeRepository';
+interface EdgeNodeHealthProbeServiceOptions {
+    repository?: EdgeNodeRepository;
+    identityDbUrl?: string;
+    enabled?: boolean | string;
+    timeoutMs?: number | string;
+    locations?: string | string[];
+}
+export declare class EdgeNodeHealthProbeService {
+    private readonly logger;
+    private readonly repository?;
+    private readonly enabled;
+    private readonly timeoutMs;
+    private readonly locations;
+    constructor(options: EdgeNodeHealthProbeServiceOptions);
+    probeNode(nodeId: string): Promise<void>;
+    private collectCandidates;
+    private ping;
+    private toUrl;
+    private createRepository;
+    private normalizeBoolean;
+    private normalizeTimeout;
+    private normalizeLocations;
+}
+export {};

package/dist/edge/EdgeNodeHealthProbeService.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeNodeHealthProbeService = void 0;
+const global_logger_factory_1 = require("global-logger-factory");
+const db_1 = require("../identity/drizzle/db");
+const EdgeNodeRepository_1 = require("../identity/drizzle/EdgeNodeRepository");
+class EdgeNodeHealthProbeService {
+    constructor(options) {
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.repository = options.repository ?? this.createRepository(options.identityDbUrl);
+        this.enabled = this.normalizeBoolean(options.enabled) && Boolean(this.repository);
+        this.timeoutMs = this.normalizeTimeout(options.timeoutMs) ?? 3_000;
+        this.locations = this.normalizeLocations(options.locations);
+    }
+    async probeNode(nodeId) {
+        if (!this.enabled) {
+            return;
+        }
+        const node = await this.repository.getNodeMetadata(nodeId);
+        if (!node?.metadata) {
+            this.logger.debug(`节点 ${nodeId} 无 metadata，跳过探测。`);
+            return;
+        }
+        const metadata = node.metadata;
+        const candidates = this.collectCandidates(metadata);
+        if (candidates.length === 0) {
+            this.logger.debug(`节点 ${nodeId} 没有可探测的候选地址。`);
+            return;
+        }
+        const results = [];
+        for (const candidate of candidates) {
+            for (const location of this.locations) {
+                const result = await this.ping(candidate, location);
+                results.push(result);
+            }
+        }
+        const successful = results.find((item) => item.success);
+        const clusterSuccess = results.some((item) => item.location === 'cluster' && item.success);
+        const status = clusterSuccess ? 'direct' : successful ? 'degraded' : 'unreachable';
+        const now = new Date();
+        const reachability = {
+            status,
+            lastProbeAt: now.toISOString(),
+            lastSuccessAt: successful ? successful.checkedAt : undefined,
+            samples: results,
+        };
+        await this.repository.mergeNodeMetadata(nodeId, { reachability });
+    }
+    collectCandidates(metadata) {
+        const candidates = new Set();
+        const direct = metadata.directCandidates ?? [];
+        for (const candidate of direct) {
+            if (typeof candidate === 'string' && candidate.trim().length > 0) {
+                candidates.add(candidate.trim());
+            }
+        }
+        if (typeof metadata.publicAddress === 'string') {
+            candidates.add(metadata.publicAddress.trim());
+        }
+        if (typeof metadata.baseUrl === 'string') {
+            candidates.add(metadata.baseUrl.trim());
+        }
+        return Array.from(candidates);
+    }
+    async ping(candidate, location) {
+        const url = this.toUrl(candidate);
+        if (!url) {
+            return { candidate, success: false, error: 'invalid-url', location: location.name, checkedAt: new Date().toISOString() };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const started = Date.now();
+        try {
+            if (location.endpoint) {
+                const probeUrl = new URL(location.endpoint);
+                probeUrl.searchParams.set('target', url.toString());
+                const response = await fetch(probeUrl.toString(), {
+                    method: 'GET',
+                    signal: controller.signal,
+                    headers: { 'accept': 'application/json' },
+                });
+                clearTimeout(timer);
+                const latencyMs = Date.now() - started;
+                if (!response.ok) {
+                    return {
+                        candidate,
+                        location: location.name,
+                        success: false,
+                        latencyMs,
+                        error: `status:${response.status}`,
+                        checkedAt: new Date().toISOString(),
+                    };
+                }
+                try {
+                    const data = await response.json();
+                    return {
+                        candidate,
+                        location: location.name,
+                        success: Boolean(data.success),
+                        latencyMs: typeof data.latencyMs === 'number' ? data.latencyMs : latencyMs,
+                        error: data.error,
+                        checkedAt: data.checkedAt ?? new Date().toISOString(),
+                    };
+                }
+                catch (error) {
+                    return {
+                        candidate,
+                        location: location.name,
+                        success: false,
+                        latencyMs,
+                        error: `invalid-json:${error.message}`,
+                        checkedAt: new Date().toISOString(),
+                    };
+                }
+            }
+            const response = await fetch(url.toString(), {
+                method: 'HEAD',
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            const latencyMs = Date.now() - started;
+            return {
+                candidate,
+                location: location.name,
+                success: response.ok,
+                latencyMs,
+                error: response.ok ? undefined : `status:${response.status}`,
+                checkedAt: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            clearTimeout(timer);
+            return {
+                candidate,
+                location: location.name,
+                success: false,
+                error: error.message,
+                checkedAt: new Date().toISOString(),
+            };
+        }
+    }
+    toUrl(value) {
+        try {
+            return new URL(value);
+        }
+        catch {
+            try {
+                return new URL(`https://${value}`);
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    createRepository(identityDbUrl) {
+        if (!identityDbUrl) {
+            return undefined;
+        }
+        const db = (0, db_1.getIdentityDatabase)(identityDbUrl);
+        return new EdgeNodeRepository_1.EdgeNodeRepository(db);
+    }
+    normalizeBoolean(value) {
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        if (typeof value === 'string') {
+            const normalized = value.trim().toLowerCase();
+            return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
+        }
+        return false;
+    }
+    normalizeTimeout(value) {
+        if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+            return Math.trunc(value);
+        }
+        if (typeof value === 'string') {
+            const parsed = Number(value.trim());
+            if (Number.isFinite(parsed) && parsed > 0) {
+                return Math.trunc(parsed);
+            }
+        }
+        return undefined;
+    }
+    normalizeLocations(value) {
+        const defaultLocation = { name: 'cluster' };
+        if (value === undefined) {
+            return [defaultLocation];
+        }
+        const input = Array.isArray(value) ? value : value.split(/[,;\n]+/u);
+        const result = [];
+        for (const entry of input) {
+            const trimmed = entry.trim();
+            if (trimmed.length === 0) {
+                continue;
+            }
+            const [namePart, endpointPart] = trimmed.split('@', 2);
+            const name = namePart.trim() || 'cluster';
+            const endpoint = endpointPart?.trim();
+            result.push({
+                name,
+                endpoint: endpoint?.length ? endpoint : undefined,
+            });
+        }
+        return result.length > 0 ? result : [defaultLocation];
+    }
+}
+exports.EdgeNodeHealthProbeService = EdgeNodeHealthProbeService;
+//# sourceMappingURL=EdgeNodeHealthProbeService.js.map