@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/dns/cloudflare/CloudflareDnsProvider.js

@@ -27,32 +27,34 @@ class CloudflareDnsProvider {
         const zoneId = await this.getZoneId(options.domain);
         const fullName = this.buildFullName(options.subdomain, options.domain);
         const ttl = options.ttl ?? 1; // Cloudflare: 1 = auto
-        // 查找所有同名记录（不限类型），以处理 CNAME 与 A/AAAA 冲突
-        const existing = await this.findRecord(zoneId, fullName);
+        // 一次拉回该名字下的全部记录，再按类型判断（审计 N14）。
+        // 旧实现只取第一条、类型不同就删除——于是 `_acme-challenge` 的 TXT 或同一名字下的 MX
+        // 会被“为写 A 记录”误删。
+        const records = await this.findRecords(zoneId, fullName);
+        const existing = records.find((record) => record.type === options.type);
         if (existing) {
-            // 如果现有记录类型不同（如 CNAME vs AAAA），必须先删除旧记录
-            if (existing.type !== options.type) {
-                this.logger.info(`发现 DNS 类型冲突 (现有: ${existing.type}, 目标: ${options.type})，正在删除旧记录 ${fullName}...`);
-                await this.callApi(`zones/${zoneId}/dns_records/${existing.id}`, 'DELETE');
-                // 删除后继续执行创建逻辑
-            }
-            else {
-                // 类型相同，检查内容是否需要更新
-                if (existing.content === options.value && (existing.ttl === ttl || ttl === 1)) {
-                    this.logger.debug(`DNS 记录已存在且一致，跳过更新 ${fullName} ${options.type}`);
-                    return;
-                }
-                // 更新现有记录
-                await this.callApi(`zones/${zoneId}/dns_records/${existing.id}`, 'PATCH', {
-                    type: options.type,
-                    name: fullName,
-                    content: options.value,
-                    ttl,
-                    proxied: false, // DNS-01 验证需要关闭代理
-                });
-                this.logger.info(`已更新 DNS 记录 ${fullName} ${options.type}`);
+            // 类型相同，检查内容是否需要更新
+            if (existing.content === options.value && (existing.ttl === ttl || ttl === 1)) {
+                this.logger.debug(`DNS 记录已存在且一致，跳过更新 ${fullName} ${options.type}`);
                 return;
             }
+            // 更新现有记录
+            await this.callApi(`zones/${zoneId}/dns_records/${existing.id}`, 'PATCH', {
+                type: options.type,
+                name: fullName,
+                content: options.value,
+                ttl,
+                proxied: false, // DNS-01 验证需要关闭代理
+            });
+            this.logger.info(`已更新 DNS 记录 ${fullName} ${options.type}`);
+            return;
+        }
+        // 只有 CNAME 与其他记录类型互斥（RFC 1034）：写 A/AAAA 前要清掉同名 CNAME，写 CNAME 前
+        // 要清掉同名 A/AAAA。MX/TXT 等类型可以与 A/AAAA 共存，必须原样保留。
+        const conflicting = records.find((record) => CloudflareDnsProvider.isMutuallyExclusive(options.type, record.type));
+        if (conflicting) {
+            this.logger.info(`发现互斥 DNS 记录 (现有: ${conflicting.type}, 目标: ${options.type})，删除该记录 ${conflicting.id} (${fullName})...`);
+            await this.callApi(`zones/${zoneId}/dns_records/${conflicting.id}`, 'DELETE');
         }
         // 创建新记录
         await this.callApi(`zones/${zoneId}/dns_records`, 'POST', {
@@ -71,12 +73,19 @@ class CloudflareDnsProvider {
         }
         const zoneId = await this.getZoneId(options.domain);
         const fullName = this.buildFullName(options.subdomain, options.domain);
-        // 删除时也要支持泛查找，以防类型传错，但通常 deleteRecord 会传 type
-        const existing = await this.findRecord(zoneId, fullName, options.type, options.value);
+        // 删除必须带类型（接口里 type 是必填）：按“同名 + 同类型（+ 同内容）”精确匹配，
+        // 绝不退化成“删这个名字下的第一条记录”。
+        const matches = await this.findRecords(zoneId, fullName, options.type, options.value);
+        const existing = matches[0];
         if (!existing) {
             this.logger.debug(`DNS 记录不存在，跳过删除 ${fullName} ${options.type}`);
             return;
         }
+        if (existing.type !== options.type) {
+            // API 不该返回别的类型；真返回了就宁可不删，也不动别人的记录。
+            this.logger.warn(`拒绝删除类型不匹配的记录 ${fullName}：请求 ${options.type}，返回 ${existing.type}`);
+            return;
+        }
         await this.callApi(`zones/${zoneId}/dns_records/${existing.id}`, 'DELETE');
         this.logger.info(`已删除 DNS 记录 ${fullName} ${options.type}`);
     }
@@ -130,9 +139,12 @@ class CloudflareDnsProvider {
         throw new Error(`找不到域名 ${domain} 的任何所属 Zone，请检查域名是否正确或手动提供 zoneId`);
     }
     /**
-     * 查找现有 DNS 记录
+     * 查找现有 DNS 记录。
+     *
+     * `type` 与 `value` 都会下推到 API 查询里，返回**全部**匹配项而不是 `response[0]`：
+     * 调用方要按类型判断能不能动这条记录，靠“第一条”猜类型正是 N14 的成因。
      */
-    async findRecord(zoneId, fullName, type, value) {
+    async findRecords(zoneId, fullName, type, value) {
         const params = new URLSearchParams({
             name: fullName,
         });
@@ -143,7 +155,26 @@ class CloudflareDnsProvider {
             params.set('content', value);
         }
         const response = await this.callApi(`zones/${zoneId}/dns_records?${params.toString()}`, 'GET');
-        return response[0];
+        return Array.isArray(response) ? response : [];
+    }
+    async findRecord(zoneId, fullName, type, value) {
+        return (await this.findRecords(zoneId, fullName, type, value)).find((record) => type === undefined || record.type === type);
+    }
+    /**
+     * 是否与目标类型互斥：CNAME 不能与任何其他记录共存（RFC 1034），其余组合（含 TXT 与
+     * A/AAAA、MX 与 A/AAAA）都可以并存。
+     */
+    static isMutuallyExclusive(target, existing) {
+        if (existing === target) {
+            return false;
+        }
+        if (target === 'TXT') {
+            return false;
+        }
+        if (existing === 'CNAME') {
+            return true;
+        }
+        return target === 'CNAME' && (existing === 'A' || existing === 'AAAA');
     }
     /**
      * 调用 Cloudflare API

package/dist/edge/EdgeNodeAgent.d.ts

@@ -34,6 +34,11 @@ export interface EdgeNodeAgentOptions {
         certificatePath: string;
         fullChainPath?: string;
         renewBeforeDays?: number;
+        /** 后台续期检查间隔（默认 6 小时）；仅在本地 ACME 模式使用。 */
+        renewalCheckIntervalMs?: number;
+        /** 续期失败后的首次重试延迟（默认 60 秒，指数增长到上限）。 */
+        renewalRetryBaseDelayMs?: number;
+        renewalRetryMaxDelayMs?: number;
         propagationDelayMs?: number;
         postDeployCommand?: string[];
     };

package/dist/edge/EdgeNodeAgent.js

@@ -106,6 +106,8 @@ class EdgeNodeAgent {
         this.p2pAcceptRunning = false;
         void this.frpManager?.stop();
         this.clusterCertificate?.stop();
+        // 停止后不该再有后台续期：一个已停的 agent 不该继续向 CA 发请求。
+        this.localCertificate?.stopAutoRenewal();
         this.localCertificate = undefined;
         this.clusterCertificate = undefined;
     }
@@ -487,6 +489,12 @@ class EdgeNodeAgent {
             if (issued && acmeOptions.postDeployCommand && acmeOptions.postDeployCommand.length > 0) {
                 await this.runPostDeploy(acmeOptions.postDeployCommand);
             }
+            // 启动即检查只解决"开机时过期"，节点长期运行要靠后台续期（审计 N15）。
+            manager.startAutoRenewal({
+                intervalMs: acmeOptions.renewalCheckIntervalMs,
+                retryBaseDelayMs: acmeOptions.renewalRetryBaseDelayMs,
+                retryMaxDelayMs: acmeOptions.renewalRetryMaxDelayMs,
+            });
         }
         catch (error) {
             this.logger.error(`自动签发证书失败：${error.message}`);

package/dist/edge/acme/AcmeCertificateManager.d.ts

@@ -1,3 +1,4 @@
+import { type CertificateRenewalSchedulerStatus } from './CertificateRenewalScheduler';
 import type { DnsProvider } from '../../dns/DnsProvider';
 /**
  * DNS 验证处理器接口
@@ -60,9 +61,29 @@ export declare class AcmeCertificateManager {
     private readonly renewBeforeDays;
     private readonly propagationDelayMs;
     private issuing;
+    private renewalScheduler?;
     constructor(options: AcmeCertificateManagerOptions);
     ensureCertificate(): Promise<boolean>;
     readCertificateStatus(): Promise<RuntimeCertificateStatus>;
+    /**
+     * Starts the background renewal loop (audit N15).
+     *
+     * `ensureCertificate()` only looks at startup: a long-running node needed someone to call
+     * `renewCertificate()` by hand before the certificate expired. The scheduler checks on an
+     * interval, renews when the status is due, and backs off when the CA is unreachable.
+     */
+    startAutoRenewal(options?: {
+        intervalMs?: number;
+        retryBaseDelayMs?: number;
+        retryMaxDelayMs?: number;
+    }): void;
+    /**
+     * Stops the loop but keeps its final status readable: "why did it stop renewing" is exactly
+     * the question an operator asks after a failed renewal, and a discarded scheduler cannot
+     * answer it.
+     */
+    stopAutoRenewal(): void;
+    getRenewalSchedulerStatus(): CertificateRenewalSchedulerStatus | undefined;
     isAvailable(): boolean;
     renewCertificate(): Promise<RuntimeCertificateRenewalResult>;
     private extractDomainsFromCertificate;
@@ -71,6 +92,9 @@ export declare class AcmeCertificateManager {
     private issueCertificateFromCA;
     private ensureAccount;
     private loadOrCreateAccountKey;
+    /** 写私钥：创建时就用 0600，并对已存在的文件再 chmod 一次。 */
+    private writePrivateFile;
+    private restrictFileMode;
     private readOptionalFile;
     private ensureDirectory;
     private delay;

package/dist/edge/acme/AcmeCertificateManager.js

@@ -10,6 +10,7 @@ const promises_1 = require("node:fs/promises");
 const node_crypto_1 = require("node:crypto");
 const acme_client_1 = __importDefault(require("acme-client"));
 const global_logger_factory_1 = require("global-logger-factory");
+const CertificateRenewalScheduler_1 = require("./CertificateRenewalScheduler");
 const DnsChallengeClient_1 = require("./DnsChallengeClient");
 const utils_1 = require("./utils");
 /**
@@ -52,10 +53,16 @@ class LocalDnsChallengeHandler {
 }
 exports.LocalDnsChallengeHandler = LocalDnsChallengeHandler;
 const DEFAULT_DIRECTORY_URL = acme_client_1.default.directory.letsencrypt.production;
+// Staging is deliberately NOT in the default failover list: a staging certificate is not trusted
+// by any browser, so a production deployment that "succeeded" through it would be serving a
+// broken endpoint while reporting success (audit N15). ZeroSSL is a real alternative CA.
 const DEFAULT_FALLBACK_URLS = [
-    acme_client_1.default.directory.letsencrypt.staging, // Staging as fallback for testing
-    'https://acme.zerossl.com/v2/DV90', // ZeroSSL as alternative CA
+    'https://acme.zerossl.com/v2/DV90',
 ];
+/** A staging/test directory: certificates from here are not trusted by clients. */
+function isStagingDirectory(directoryUrl) {
+    return /staging|acme-staging/iu.test(directoryUrl);
+}
 class AcmeCertificateManager {
     constructor(options) {
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
@@ -83,6 +90,8 @@ class AcmeCertificateManager {
         this.email = options.email;
         this.domains = options.domains;
         this.directoryUrl = options.directoryUrl ?? DEFAULT_DIRECTORY_URL;
+        // A staging CA only ever appears here because the operator listed it explicitly; the
+        // defaults never add one (audit N15).
         this.fallbackDirectoryUrls = options.fallbackDirectoryUrls ?? DEFAULT_FALLBACK_URLS;
         this.accountKeyPath = options.accountKeyPath;
         this.certificateKeyPath = options.certificateKeyPath;
@@ -126,6 +135,39 @@ class AcmeCertificateManager {
             return { status: 'missing' };
         }
     }
+    /**
+     * Starts the background renewal loop (audit N15).
+     *
+     * `ensureCertificate()` only looks at startup: a long-running node needed someone to call
+     * `renewCertificate()` by hand before the certificate expired. The scheduler checks on an
+     * interval, renews when the status is due, and backs off when the CA is unreachable.
+     */
+    startAutoRenewal(options = {}) {
+        if (this.renewalScheduler) {
+            // Already created: start() is a no-op while running, and restarts it after a stop.
+            this.renewalScheduler.start();
+            return;
+        }
+        this.renewalScheduler = new CertificateRenewalScheduler_1.CertificateRenewalScheduler({
+            readStatus: async () => await this.readCertificateStatus(),
+            renew: async () => {
+                await this.renewCertificate();
+            },
+            ...options,
+        });
+        this.renewalScheduler.start();
+    }
+    /**
+     * Stops the loop but keeps its final status readable: "why did it stop renewing" is exactly
+     * the question an operator asks after a failed renewal, and a discarded scheduler cannot
+     * answer it.
+     */
+    stopAutoRenewal() {
+        this.renewalScheduler?.stop();
+    }
+    getRenewalSchedulerStatus() {
+        return this.renewalScheduler?.getStatus();
+    }
     isAvailable() {
         return this.domains.some((domain) => domain.trim().length > 0)
             && this.email.trim().length > 0
@@ -180,12 +222,21 @@ class AcmeCertificateManager {
         if (this.fullChainPath) {
             await this.ensureDirectory((0, node_path_1.dirname)(this.fullChainPath));
         }
-        // Try primary CA first, then fallback CAs
+        // Try the primary CA first, then the failover chain. The chain is exactly what the operator
+        // configured: the defaults contain no staging CA, so a production deployment cannot silently
+        // end up serving a certificate no client trusts (audit N15).
         const directoryUrls = [this.directoryUrl, ...this.fallbackDirectoryUrls];
+        const stagingInChain = directoryUrls.filter(isStagingDirectory);
+        if (stagingInChain.length > 0 && !isStagingDirectory(this.directoryUrl)) {
+            this.logger.warn(`ACME 失败切换链包含 staging CA（${stagingInChain.join(', ')}）：该 CA 签发的证书客户端不信任`);
+        }
         let lastError;
         for (const directoryUrl of directoryUrls) {
             try {
                 await this.issueCertificateFromCA(directoryUrl);
+                if (isStagingDirectory(directoryUrl)) {
+                    this.logger.warn(`证书由 staging CA 签发，客户端不会信任：${directoryUrl}`);
+                }
                 return; // Success!
             }
             catch (error) {
@@ -196,8 +247,9 @@ class AcmeCertificateManager {
                 }
             }
         }
-        // All CAs failed
-        throw new Error(`所有 ACME CA 都失败。最后错误: ${lastError?.message}`);
+        // All CAs failed: name every CA that was tried, so the operator does not have to guess.
+        throw new Error(`所有 ACME CA 都失败（已尝试 ${directoryUrls.length} 个：${directoryUrls.join(', ')}）。`
+            + `最后错误: ${lastError?.message}`);
     }
     async issueCertificateFromCA(directoryUrl) {
         this.logger.info(`使用 ACME CA: ${directoryUrl}`);
@@ -228,7 +280,8 @@ class AcmeCertificateManager {
                 await this.dnsHandler.removeChallenge(recordName);
             },
         });
-        await node_fs_1.promises.writeFile(this.certificateKeyPath, privateKey.toString());
+        // 私钥 0600（证书本身是公开材料，保持默认权限即可）：审计 N18。
+        await this.writePrivateFile(this.certificateKeyPath, privateKey.toString());
         await node_fs_1.promises.writeFile(this.certificatePath, certificate);
         if (this.fullChainPath) {
             await node_fs_1.promises.writeFile(this.fullChainPath, certificate);
@@ -255,13 +308,28 @@ class AcmeCertificateManager {
     async loadOrCreateAccountKey(path) {
         const existing = await this.readOptionalFile(path);
         if (existing) {
+            // 旧版本可能留下了 0644 的账户私钥，读到就顺手收紧。
+            await this.restrictFileMode(path);
             return existing.toString();
         }
         await this.ensureDirectory((0, node_path_1.dirname)(path));
         const key = await acme_client_1.default.crypto.createPrivateKey();
-        await node_fs_1.promises.writeFile(path, key);
+        await this.writePrivateFile(path, key.toString());
         return key.toString();
     }
+    /** 写私钥：创建时就用 0600，并对已存在的文件再 chmod 一次。 */
+    async writePrivateFile(path, contents) {
+        await node_fs_1.promises.writeFile(path, contents, { encoding: 'utf8', mode: 0o600 });
+        await this.restrictFileMode(path);
+    }
+    async restrictFileMode(path) {
+        try {
+            await node_fs_1.promises.chmod(path, 0o600);
+        }
+        catch (error) {
+            this.logger.warn(`无法收紧私钥文件权限 ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     async readOptionalFile(path) {
         try {
             return await node_fs_1.promises.readFile(path);

package/dist/edge/acme/AcmeCertificateManager.jsonld

@@ -224,6 +224,10 @@
           "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_issuing",
           "memberFieldName": "issuing"
         },
+        {
+          "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_renewalScheduler",
+          "memberFieldName": "renewalScheduler"
+        },
         {
           "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_constructor",
           "memberFieldName": "constructor"
@@ -236,6 +240,18 @@
           "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_readCertificateStatus",
           "memberFieldName": "readCertificateStatus"
         },
+        {
+          "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_startAutoRenewal",
+          "memberFieldName": "startAutoRenewal"
+        },
+        {
+          "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_stopAutoRenewal",
+          "memberFieldName": "stopAutoRenewal"
+        },
+        {
+          "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_getRenewalSchedulerStatus",
+          "memberFieldName": "getRenewalSchedulerStatus"
+        },
         {
           "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_isAvailable",
           "memberFieldName": "isAvailable"
@@ -268,6 +284,14 @@
           "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_loadOrCreateAccountKey",
           "memberFieldName": "loadOrCreateAccountKey"
         },
+        {
+          "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_writePrivateFile",
+          "memberFieldName": "writePrivateFile"
+        },
+        {
+          "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_restrictFileMode",
+          "memberFieldName": "restrictFileMode"
+        },
         {
           "@id": "undefineds:dist/edge/acme/AcmeCertificateManager.jsonld#AcmeCertificateManager__member_readOptionalFile",
           "memberFieldName": "readOptionalFile"

package/dist/edge/acme/CertificateRenewalScheduler.d.ts

@@ -0,0 +1,67 @@
+import { getLoggerFor } from 'global-logger-factory';
+/**
+ * Renews a certificate before it expires, without a human in the loop (audit N15).
+ *
+ * The runtime could already read a certificate's status and renew on demand, but nothing drove
+ * that: a node that stayed up long enough simply served an expired certificate until someone
+ * called the admin endpoint. This keeps a single timer that checks the status, renews when the
+ * status says it is due, and backs off when renewal fails instead of hammering the CA.
+ *
+ * It is deliberately provider-agnostic (status reader + renewer) so the ACME manager and the
+ * cluster-mode manager can share it, and so tests need no certificates at all.
+ */
+export type CertificateRenewalStatus = 'valid' | 'renewal_due' | 'missing' | 'invalid';
+export interface CertificateRenewalState {
+    status: CertificateRenewalStatus;
+    expiresAt?: string;
+}
+export interface CertificateRenewalSchedulerOptions {
+    readStatus: () => Promise<CertificateRenewalState>;
+    renew: () => Promise<void>;
+    /** How often to look when everything is fine. */
+    intervalMs?: number;
+    /** First retry delay after a failed renewal; doubles up to `retryMaxDelayMs`. */
+    retryBaseDelayMs?: number;
+    retryMaxDelayMs?: number;
+    now?: () => Date;
+    logger?: Pick<ReturnType<typeof getLoggerFor>, 'info' | 'warn' | 'error'>;
+}
+export interface CertificateRenewalSchedulerStatus {
+    running: boolean;
+    /** What the last check saw. */
+    lastStatus?: CertificateRenewalStatus;
+    lastCheckedAt?: string;
+    lastRenewedAt?: string;
+    lastError?: string;
+    consecutiveFailures: number;
+    /** Delay before the next check, so a crash loop is visible instead of implied. */
+    nextCheckInMs?: number;
+}
+export declare class CertificateRenewalScheduler {
+    private readonly options;
+    private readonly logger;
+    private readonly now;
+    private readonly intervalMs;
+    private readonly retryBaseDelayMs;
+    private readonly retryMaxDelayMs;
+    private timer?;
+    private running;
+    private inFlight;
+    private consecutiveFailures;
+    private status;
+    constructor(options: CertificateRenewalSchedulerOptions);
+    /** Starts the loop; repeated calls are a no-op, so a restart cannot double the timers. */
+    start(): void;
+    stop(): void;
+    getStatus(): CertificateRenewalSchedulerStatus;
+    /**
+     * One check-and-renew cycle.
+     *
+     * Exposed so an operator action or a test can drive it directly; concurrent calls share the
+     * in-flight run instead of renewing twice.
+     */
+    runOnce(): Promise<CertificateRenewalSchedulerStatus>;
+    /** Delay before the next check: the normal interval, or a growing retry after failures. */
+    nextDelayMs(): number;
+    private schedule;
+}

package/dist/edge/acme/CertificateRenewalScheduler.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CertificateRenewalScheduler = void 0;
+const global_logger_factory_1 = require("global-logger-factory");
+const DEFAULT_INTERVAL_MS = 6 * 60 * 60 * 1_000;
+const DEFAULT_RETRY_BASE_DELAY_MS = 60 * 1_000;
+const DEFAULT_RETRY_MAX_DELAY_MS = 60 * 60 * 1_000;
+class CertificateRenewalScheduler {
+    constructor(options) {
+        this.options = options;
+        this.running = false;
+        this.inFlight = false;
+        this.consecutiveFailures = 0;
+        this.status = { running: false, consecutiveFailures: 0 };
+        this.logger = options.logger ?? (0, global_logger_factory_1.getLoggerFor)('CertificateRenewalScheduler');
+        this.now = options.now ?? (() => new Date());
+        this.intervalMs = positive(options.intervalMs, DEFAULT_INTERVAL_MS);
+        this.retryBaseDelayMs = positive(options.retryBaseDelayMs, DEFAULT_RETRY_BASE_DELAY_MS);
+        this.retryMaxDelayMs = positive(options.retryMaxDelayMs, DEFAULT_RETRY_MAX_DELAY_MS);
+    }
+    /** Starts the loop; repeated calls are a no-op, so a restart cannot double the timers. */
+    start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.status = { ...this.status, running: true };
+        this.schedule(0);
+    }
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.status = { ...this.status, running: false, nextCheckInMs: undefined };
+    }
+    getStatus() {
+        return { ...this.status };
+    }
+    /**
+     * One check-and-renew cycle.
+     *
+     * Exposed so an operator action or a test can drive it directly; concurrent calls share the
+     * in-flight run instead of renewing twice.
+     */
+    async runOnce() {
+        if (this.inFlight) {
+            return this.getStatus();
+        }
+        this.inFlight = true;
+        try {
+            const current = await this.options.readStatus();
+            this.status = {
+                ...this.status,
+                lastStatus: current.status,
+                lastCheckedAt: this.now().toISOString(),
+            };
+            if (current.status === 'valid') {
+                this.consecutiveFailures = 0;
+                this.status = { ...this.status, consecutiveFailures: 0, lastError: undefined };
+                return this.getStatus();
+            }
+            this.logger.info(`certificate status is ${current.status}; renewing`);
+            await this.options.renew();
+            this.consecutiveFailures = 0;
+            this.status = {
+                ...this.status,
+                consecutiveFailures: 0,
+                lastError: undefined,
+                lastRenewedAt: this.now().toISOString(),
+            };
+            this.logger.info('certificate renewed');
+            return this.getStatus();
+        }
+        catch (error) {
+            this.consecutiveFailures += 1;
+            const message = error instanceof Error ? error.message : String(error);
+            this.status = {
+                ...this.status,
+                consecutiveFailures: this.consecutiveFailures,
+                lastError: message,
+            };
+            this.logger.error(`certificate renewal failed (attempt ${this.consecutiveFailures}): ${message}`);
+            return this.getStatus();
+        }
+        finally {
+            this.inFlight = false;
+        }
+    }
+    /** Delay before the next check: the normal interval, or a growing retry after failures. */
+    nextDelayMs() {
+        if (this.consecutiveFailures === 0) {
+            return this.intervalMs;
+        }
+        const exponent = Math.max(0, this.consecutiveFailures - 1);
+        return Math.min(this.retryBaseDelayMs * 2 ** exponent, this.retryMaxDelayMs);
+    }
+    schedule(delayMs) {
+        if (!this.running) {
+            return;
+        }
+        this.status = { ...this.status, nextCheckInMs: delayMs };
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.runOnce().then(() => this.schedule(this.nextDelayMs()));
+        }, delayMs);
+        // A renewal timer must not keep the process alive on its own.
+        this.timer.unref?.();
+    }
+}
+exports.CertificateRenewalScheduler = CertificateRenewalScheduler;
+function positive(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+//# sourceMappingURL=CertificateRenewalScheduler.js.map

package/dist/edge/frp/FrpcProcessManager.d.ts

@@ -25,6 +25,10 @@ export interface FrpcRuntimeStatus {
     error?: string;
     entrypoint?: string;
     pid?: number;
+    /** Restarts since the last healthy run, so a crash loop is visible instead of implied. */
+    restartCount?: number;
+    /** Delay before the next automatic restart, when one is scheduled. */
+    nextRestartInMs?: number;
 }
 export declare class FrpcProcessManager {
     private readonly logger;
@@ -39,10 +43,22 @@ export declare class FrpcProcessManager {
     private restarting;
     private status;
     private desiredRunning;
+    private restartTimer?;
+    private consecutiveFailures;
+    private startedAt;
     constructor(options: FrpcProcessManagerOptions);
     applyConfig(config?: FrpTunnelRuntimeConfig, status?: string, entrypoint?: string): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * 结束当前进程，但不碰重启计数与待重启定时器。
+     *
+     * 先把 `this.process` 置空：退出回调据此判断“这个进程已被替换”，不会为它再排一次重启，
+     * 也不会把它的退出写成当前状态。
+     */
+    private stopProcess;
     private restart;
+    private nextRestartDelayMs;
+    private cancelPendingRestart;
     private ensureDirectory;
     private writeConfigFile;
     getStatus(): FrpcRuntimeStatus;