From 3f5eb490810b0ab1518602e2933ad71019a13af7 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Fri, 25 Sep 2026 23:40:56 +0800 Subject: [PATCH] =?UTF-8?q?feat(frontConfig):=20=E5=89=8D=E7=AB=AF?= =?UTF-8?q?=E7=8B=AC=E7=AB=8B=E9=83=A8=E7=BD=B2=E5=9F=9F=E5=90=8D=E4=B8=A4?= =?UTF-8?q?=E9=98=B6=E6=AE=B5=E5=88=87=E6=8D=A2=EF=BC=88pending=20?= =?UTF-8?q?=E7=99=BB=E8=AE=B0=20+=20TXT=20=E6=A0=A1=E9=AA=8C=E9=80=9A?= =?UTF-8?q?=E8=BF=87=E5=90=8E=E6=8F=90=E5=8D=87=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 迁移 20260924180000-add-pending-domain-to-wms-warehouse-front-config 新增 pending_* 6 列、retired_domain/retired_at 与 idx_pending_domain/idx_retired_domain 两个索引(生产库已执行) - setDomain 只登记待验证域名并下发 TXT 校验码,不再「设置即生效」; TXT 校验通过后由 promotePendingDomain 提升(旧域名写入 retired_domain 下线队列、 清空证书 5 列并重置同步状态),消除「改域名瞬间旧域名公共接口 404」中间态 - DoH 解析改为多端点顺序尝试(dohUrls:alidns → 223.5.5.5 → doh.pub), 单端点 NODATA/NXDOMAIN 不再直接判定,必要时降级系统 DNS 并显式限时; config.frontConfig.domainVerify 同步 batchSize 50→20、timeoutMs 5000→3000 - getDomain/setDomain/checkDomain 响应追加待验证域名组 7 字段(旧 9 字段口径不变) - 同步 methods 文档(frontConfig 6 方法)与 changes 4 条变更记录、 AI_METHOD_ROUTING.md 函数清单(42→50) 注:本提交补齐此前已在生产库执行但从未入库的迁移与代码 (生产 SequelizeMeta 已含 20260924180000,属 orphan meta 补齐入库)。 --- AI_METHOD_ROUTING.md | 4 +- app/model/warehouse_front_config.js | 55 + app/service/systemMethods/frontConfig.js | 33 +- app/service/systems/frontConfig.js | 1007 +++++++++++++---- config/config.default.js | 21 +- ...ng-domain-to-wms-warehouse-front-config.js | 220 ++++ methods/changes/system.json | 92 ++ methods/system.json | 220 +++- 8 files changed, 1423 insertions(+), 229 deletions(-) create mode 100644 database/migrations/20260924180000-add-pending-domain-to-wms-warehouse-front-config.js diff --git a/AI_METHOD_ROUTING.md b/AI_METHOD_ROUTING.md index 0f92ac2..fa4672a 100644 --- a/AI_METHOD_ROUTING.md +++ b/AI_METHOD_ROUTING.md @@ -593,8 +593,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - buildTree, getTreeByType, buildSubTree, getWithChildrenByType, getAllChildren, getByType, getGroups, getChildrenByPid, getTreeChildrenByPid, create, update, findById, delete - app/service/systems/file.js (2) - getImages, ReferenceFile -- app/service/systems/frontConfig.js (42) - - createError, getCurrentWarehouseId, deleteCacheByKey, normalizeText, normalizeTheme, assertDomainUnique, getRecordField, sanitizeErrorText, getDomainVerifyConfig, getCnameTarget, buildDomainVerifyCode, parseTxtAnswerData, extractTxtValuesFromAnswers, resolveTxtByDoh, resolveTxtBySystem, resolveTxtValues, verifyDomainRecord, isUnknownColumnError, findVerifiedDomainRecord, verifyPendingDomains, buildInfoOutput, buildCertOutput, getInfo, getCert, getDomain, setDomain, checkDomain, buildDomainOutput, describeDomainStatus, getDomainCacheKey, buildPublicOutput, clearDomainCache, getByDomain, normalizePem, parseCertPem, assertCertValid, collectCertNames, certCoversDomain, validateKeyPem, assertWarehouseSubject, saveInfo, saveCert +- app/service/systems/frontConfig.js (50) + - createError, getCurrentWarehouseId, deleteCacheByKey, normalizeText, normalizeTheme, assertDomainUnique, getRecordField, sanitizeErrorText, getDomainVerifyConfig, resolveDohUrls, getCnameTarget, buildDomainVerifyCode, parseTxtAnswerData, extractTxtValuesFromAnswers, queryDohEndpoint, resolveTxtByDoh, resolveTxtBySystem, timeoutMs, resolveTxtValues, verifyDomainRecord, isUnknownColumnError, findVerifiedDomainRecord, verifyPendingDomains, buildInfoOutput, buildCertOutput, getInfo, getCert, getDomain, setDomain, promotePendingDomain, checkPendingDomainRecord, checkDomain, buildDomainOutput, buildResolvedValues, describeDomainStatus, getDomainCacheKey, buildPublicOutput, clearDomainCache, clearDomainCaches, buildPendingClearPatch, getByDomain, normalizePem, parseCertPem, assertCertValid, collectCertNames, certCoversDomain, validateKeyPem, assertWarehouseSubject, saveInfo, saveCert - app/service/systems/inbound_direct_log.js (15) - getItems, _addSingleItem, _bindReceivingDetail, addItem, removeItem, commit, notifyEntryOrderCompleted, _queryCompletedEntryItems, _buildCompletedItemLines, buildEntryOrderConfirmRequest, _sendOpenApiCallback, operationLog, qimenEntrySync, _syncReceivingStorageStatus, _applyReceivingStockOccupancy - app/service/systems/inbox/group.js (11) diff --git a/app/model/warehouse_front_config.js b/app/model/warehouse_front_config.js index 91ebc21..ea32e5d 100644 --- a/app/model/warehouse_front_config.js +++ b/app/model/warehouse_front_config.js @@ -11,6 +11,12 @@ * 判断,不单独保留证书 status 列。 * - domain_status 状态机:0-未验证,1-已验证(DNS TXT 校验通过),2-验证失败; * 未验证/验证失败的域名禁止上传证书与对外公共拉取,管理后台设置域名后回落到 0。 + * - 两阶段域名切换(方案 B):生效域名 domain 只在 DNS TXT 校验通过时由 + * frontConfig.promotePendingDomain 切换;frontConfig.setDomain 只把新域名登记在 + * pending_domain(+ pending_verify_host/token 校验码),旧域名全程可用(不会出现 + * 「页面能打开但公共配置 404」的中间态);提升时旧域名写入 retired_domain 下线队列 + * (由外部证书脚本删除其 nginx 配置与证书文件后置 NULL)、清空证书 5 列并重置同步 4 列 + * (域名已变,证书必须重新上传)。 * - domain 唯一索引(uk_domain)为 MySQL 可空列唯一索引:允许多个 NULL, * 应用层在写入非空 domain 前必须做唯一性校验,不能依赖数据库约束报错。 * - store_id 唯一索引(uk_store_id):每仓一行,由数据库层保证。 @@ -83,6 +89,47 @@ module.exports = app => { allowNull: true, comment: '最近一次域名验证失败原因', }, + pending_domain: { + type: STRING(100), + allowNull: true, + comment: '待验证域名:setDomain 只登记到本列,TXT 校验通过后才提升为生效域名 domain', + }, + pending_verify_host: { + type: STRING(255), + allowNull: true, + comment: '待验证域名的 TXT 记录主机名(wmsv-<随机码>.<待验证域名>)', + }, + pending_verify_token: { + type: STRING(64), + allowNull: true, + comment: '待验证域名的 TXT 记录值(32 位 hex)', + }, + pending_verify_attempts: { + type: INTEGER(11), + allowNull: false, + defaultValue: 0, + comment: '待验证域名校验尝试次数', + }, + pending_last_error: { + type: STRING(500), + allowNull: true, + comment: '待验证域名最近一次失败原因', + }, + pending_created_at: { + type: DATE, + allowNull: true, + comment: '发起域名切换的时间', + }, + retired_domain: { + type: STRING(100), + allowNull: true, + comment: '待下线旧域名:域名提升时写入,外部证书脚本删除其 nginx 配置与证书文件后置 NULL', + }, + retired_at: { + type: DATE, + allowNull: true, + comment: '旧域名进入下线队列的时间', + }, title: { type: STRING(100), allowNull: true, @@ -202,6 +249,14 @@ module.exports = app => { name: 'idx_domain_status', fields: [ 'domain_status' ], }, + { + name: 'idx_pending_domain', + fields: [ 'pending_domain' ], + }, + { + name: 'idx_retired_domain', + fields: [ 'retired_domain' ], + }, ], }); diff --git a/app/service/systemMethods/frontConfig.js b/app/service/systemMethods/frontConfig.js index 400a956..90aaad6 100644 --- a/app/service/systemMethods/frontConfig.js +++ b/app/service/systemMethods/frontConfig.js @@ -158,6 +158,9 @@ class FrontConfigMethodsService extends MainService { * 保存后清理该域名的公共拉取缓存并返回证书配置输出 * (响应含证书/私钥原文回显,13 字段,口径与 frontConfig.getCert 一致)。 * + * 域名切换提示:待验证域名提升为生效域名时会清空证书 5 列并重置同步状态(域名已变,证书必须 + * 重新上传);前置闸门与 SAN/CN 覆盖校验始终以生效域名为准。 + * * @param {Object} data 请求参数。 * @param {string} data.pem 证书 PEM 文本(必填)。 * @param {string} data.key 私钥 PEM 文本(必填,与证书成对)。 @@ -189,13 +192,20 @@ class FrontConfigMethodsService extends MainService { /** * 设置当前仓库前端独立部署域名(需登录、仅仓库主体)。 * - * 设置成功会下发一次性 DNS TXT 校验记录(verify_host/verify_value)与 CNAME 目标(cname); - * 域名发生变更时会同时清空既有证书并重置同步状态(旧证书不覆盖新域名)。 + * 设置成功只登记待验证域名并下发一次性 DNS TXT 校验记录(pending_verify_host / pending_verify_value) + * 与 CNAME 目标(cname);生效域名、证书与同步状态不会因本接口改变。 + * + * 两阶段切换(本次改造):本接口只登记待验证域名(pending_domain)并下发 TXT 校验码,不直接 + * 改动生效域名、证书与同步状态——切换期间旧域名全程可用,改错域名只要不配置 TXT 记录就不会生效; + * TXT 校验通过后由提升逻辑切换生效域名,届时旧域名进入 retired_domain 下线队列、证书被清空并 + * 重置同步状态(需重新上传证书)。入参为当前生效域名时表示「取消待切换」。 * * @param {Object} data 请求参数。 * @param {string} data.domain 仓库自持域名(必填,非空,≤100 字符,全局唯一)。 - * @return {Promise} 统一响应结果(code=1);data 含 - * warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error。 + * @return {Promise} 统一响应结果(code=1);data 含生效域名组 9 字段 + * (warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error) + * + 待验证域名组 7 字段(pending_domain/pending_verify_host/pending_verify_value/pending_attempts/ + * pending_last_error/pending_created_at/pending_active)。 */ async setDomain(data = {}) { const targetService = this.getFrontConfigService(); @@ -219,8 +229,15 @@ class FrontConfigMethodsService extends MainService { * 返回待校验的 verify_host/verify_value 与 cname;domain_status=1(已验证)时 * verify_host/verify_value 返回空串(校验令牌已无用途);无记录时返回空值默认。 * - * @return {Promise} 统一响应结果(code=1);data 含 - * warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error。 + * 两阶段切换后响应在既有 9 个字段之后追加待验证域名组(pending_domain / pending_verify_host / + * pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active; + * 无待验证域名时依次为 ''/''/''/0/''/null/false)。待验证域名的校验码始终回显——该域名尚未生效, + * 需据此配置 TXT 记录;生效域名已验证时既有 verify_host/verify_value 仍返回空串(口径不变)。 + * + * @return {Promise} 统一响应结果(code=1);data 含生效域名组 9 字段 + * (warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error) + * + 待验证域名组 7 字段(pending_domain/pending_verify_host/pending_verify_value/pending_attempts/ + * pending_last_error/pending_created_at/pending_active)。 */ async getDomain() { const targetService = this.getFrontConfigService(); @@ -242,6 +259,10 @@ class FrontConfigMethodsService extends MainService { * 主动校验当前仓库前端独立部署域名的 DNS TXT 记录(需登录、仅仓库主体)。 * * 校验结果会回写 domain_status/domain_verified_at/attempts/last_error; + * 两阶段切换后:存在待验证域名(pending_active=true)时校验的是待验证域名的 TXT 记录,通过即 + * 提升为生效域名(旧域名入 retired_domain 下线队列、证书清空并重置同步状态);不通过只累加 + * pending_attempts 并记 pending_last_error,生效域名与证书不受影响。无待验证域名时保持原口径 + * 回写 domain_status/domain_verified_at/attempts/last_error。 * 响应额外含 verified(本次是否通过)与 resolved_values(本次解析到的 TXT 值,最多 5 条)。 * * @return {Promise} 统一响应结果(code=1);未设置域名时 code=400。 diff --git a/app/service/systems/frontConfig.js b/app/service/systems/frontConfig.js index 07296fd..323637a 100644 --- a/app/service/systems/frontConfig.js +++ b/app/service/systems/frontConfig.js @@ -2,7 +2,8 @@ const crypto = require('node:crypto'); // 域名验证 TXT 记录的兜底解析使用 Node 内置 DNS(本文件为全仓首次引入 node:dns): -// DoH(ctx.curl)不可用时降级为系统解析;仅服务域名验证链路,不参与业务主链路。 +// DoH(ctx.curl)多端点全部「未取到值」时降级为系统解析,且显式限时(见 resolveTxtBySystem); +// 仅服务域名验证链路,不参与业务主链路。 const dns = require('node:dns'); const { Service } = require('egg'); @@ -56,6 +57,22 @@ const DOMAIN_LAST_ERROR_MAX_LENGTH = 500; // 单条 TXT 记录解析结果长度上限(异常超长记录截断保护) const TXT_VALUE_MAX_LENGTH = 1024; +// DoH 端点内置默认列表(config.frontConfig.domainVerify.dohUrls / dohUrl 均无效时的最后兜底)。 +// 顺序即尝试顺序,与 config.default.js 的 frontConfig.domainVerify.dohUrls 保持一致。 +// doh.pub 置于最后的原因(实测):主机 wmsv-aa4adaab13.wms.wms.gztbyc.com 的 TXT 记录真实存在, +// 但 https://doh.pub/dns-query 因陈旧负缓存仍返回 Status=0 且 Answer 为空, +// 不能让单端点的 NODATA 主导「记录不存在」的判定(详见 resolveTxtByDoh 的 JSDoc)。 +const DEFAULT_DOH_URLS = Object.freeze([ + 'https://dns.alidns.com/resolve', + 'https://223.5.5.5/resolve', + 'https://doh.pub/dns-query', +]); +// 单个 DoH 端点的默认请求超时(毫秒);系统 DNS 兜底复用同一超时(见 resolveTxtValues) +const DEFAULT_DOH_TIMEOUT_MS = 3000; +// 单轮默认处理行数:单行最坏 ≈ (3 个 DoH 端点 + 1 次系统 DNS 兜底) × 3000ms = 12s, +// 20 行最坏 ≈ 240s,明显小于 lockTtlSeconds(600s) 与 interval(600s);需与 config.default.js 保持一致 +const DEFAULT_DOMAIN_VERIFY_BATCH_SIZE = 20; + // checkDomain 响应回显解析值的条数与单条长度上限(排障用,避免响应被超长记录撑爆) const DOMAIN_RESOLVED_VALUES_LIMIT = 5; const DOMAIN_RESOLVED_VALUE_MAX_LENGTH = 255; @@ -165,7 +182,12 @@ class FrontConfigService extends Service { /** * 校验非空 domain 的全局唯一性(可空列唯一索引允许多 NULL,数据库不兜底)。 * - * @param {string} domain 待校验域名(非空)。 + * 两阶段切换后「占用」的定义包含待验证域名:其他仓库的 domain 或 pending_domain + * 命中任一即视为已占用(否则两个仓库可同时把同一域名登记为待验证,直到「提升」时才在 + * domain 唯一索引上撞车)。注意 pending_domain 只有普通索引(非唯一), + * 并发提交仍可能绕过本校验,最终由 domain 唯一索引在提升时兜底。 + * + * @param {string} domain 待校验域名(非空,已小写化)。 * @param {number} excludeWarehouseId 排除的仓库 ID(当前仓库自身)。 * @return {Promise} 无返回值。 * @throws {Error} domain 已被其他仓库使用时抛出,状态码 409。 @@ -179,10 +201,13 @@ class FrontConfigService extends Service { const { Op } = this.app.Sequelize; const existing = await configModel.findOne({ where: { - domain, store_id: { [Op.ne]: excludeWarehouseId }, + [Op.or]: [ + { domain }, + { pending_domain: domain }, + ], }, - attributes: [ 'store_id', 'domain' ], + attributes: [ 'store_id', 'domain', 'pending_domain' ], }); if (existing) { @@ -236,8 +261,9 @@ class FrontConfigService extends Service { * - interval {string}:扫描间隔(Egg schedule 语法); * - lockTtlSeconds {number}:Redis 跨进程锁 TTL(秒); * - batchSize {number}:单轮最多处理行数; - * - dohUrl {string}:DNS-over-HTTPS 服务地址; - * - timeoutMs {number}:单次 DoH 请求超时(毫秒); + * - dohUrls {string[]}:DoH 端点数组(顺序即尝试顺序,多端点顺序尝试、命中即返回); + * - dohUrl {string}:恒等于 dohUrls[0],兼容仍在读单端点键的旧调用方(历史单字符串配置仍生效); + * - timeoutMs {number}:单个 DoH 端点、以及系统 DNS 兜底单次查询的超时(毫秒); * - maxAttempts {number}:自动重试次数上限。 */ getDomainVerifyConfig() { @@ -248,17 +274,54 @@ class FrontConfigService extends Service { return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback; }; + const dohUrls = this.resolveDohUrls(raw); + return { enable: raw.enable !== false, interval: String(raw.interval || '10m'), lockTtlSeconds: toPositiveNumber(raw.lockTtlSeconds, 600), - batchSize: Math.floor(toPositiveNumber(raw.batchSize, 50)), - dohUrl: String(raw.dohUrl || 'https://doh.pub/dns-query'), - timeoutMs: toPositiveNumber(raw.timeoutMs, 5000), + // 单轮行数上限:最坏耗时核算见 DEFAULT_DOMAIN_VERIFY_BATCH_SIZE 与 config.default.js 注释 + batchSize: Math.floor(toPositiveNumber(raw.batchSize, DEFAULT_DOMAIN_VERIFY_BATCH_SIZE)), + // 同时暴露数组与首项:dohUrls 供调用方按序尝试多个端点,dohUrl 兼容旧的单端点读取方(恒为 dohUrls[0]) + dohUrls, + dohUrl: dohUrls[0], + timeoutMs: toPositiveNumber(raw.timeoutMs, DEFAULT_DOH_TIMEOUT_MS), maxAttempts: Math.floor(toPositiveNumber(raw.maxAttempts, 20)), }; } + /** + * 解析 DoH 端点列表(dohUrl → dohUrls 的兼容规则)。 + * + * 兼容规则(按优先级): + * 1. config.frontConfig.domainVerify.dohUrls 为「有效非空字符串数组」(逐项 trim 后至少一项非空)→ 使用它,顺序不变; + * 2. 否则 config.frontConfig.domainVerify.dohUrl 非空(历史单字符串配置)→ 等价于 [dohUrl]; + * 3. 否则使用内置默认数组 DEFAULT_DOH_URLS。 + * + * 数组项若全为空串/空白/非字符串,视为「无效配置」继续走规则 2/3,避免配置写错时整个解析链路不可用。 + * + * @param {Object} [raw] config.frontConfig.domainVerify 原始配置对象。 + * @return {string[]} 去空后的 DoH 端点数组,至少含一项。 + */ + resolveDohUrls(raw) { + const source = raw || {}; + const normalizeList = list => (Array.isArray(list) ? list : []) + .map(url => String(url === undefined || url === null ? '' : url).trim()) + .filter(url => url.length > 0); + + const multi = normalizeList(source.dohUrls); + if (multi.length > 0) { + return multi; + } + + const single = normalizeList([ source.dohUrl ]); + if (single.length > 0) { + return single; + } + + return DEFAULT_DOH_URLS.slice(); + } + /** * 读取 CNAME 目标(config.frontConfig.cname)。 * @@ -335,67 +398,216 @@ class FrontConfigService extends Service { } /** - * DoH(DNS-over-HTTPS)解析 TXT 记录。 + * 请求单个 DoH 端点解析 TXT 记录,并把结果三分类(本方法自身不抛异常)。 + * + * 分类口径: + * - values:拿到至少一条 TXT 值 → 调用方应立即返回,不再尝试后续端点; + * - empty :Status === 0 且有 Question 但无 Answer(NODATA),或 Status === 3(NXDOMAIN) + * → 「本端点未解析到记录」。注意这不等于「记录一定不存在」:可能是该端点的负缓存滞后 + * (见 resolveTxtByDoh 中的实测案例),故调用方必须继续尝试下一个端点,不能就此定论; + * - error :请求异常/超时、HTTP 非 200、响应体非对象等 → 「本端点解析失败」,同样继续下一个端点。 * * @param {string} host 待解析主机名。 - * @param {Object} verifyConfig 域名验证配置(getDomainVerifyConfig 返回值)。 - * @return {Promise} TXT 记录文本列表;无记录返回空数组。 - * @throws {Error} DoH 请求失败/响应异常时抛出(由 resolveTxtValues 决定是否降级)。 + * @param {string} endpoint DoH 端点地址(不含查询串)。 + * @param {number} timeoutMs 单端点请求超时(毫秒)。 + * @return {Promise} { kind: values|empty|error, endpoint: string, values?: string[], reason?: string }。 + * reason 已脱敏截断,仅用于日志与最终错误文案。 */ - async resolveTxtByDoh(host, verifyConfig) { - const url = `${verifyConfig.dohUrl}?name=${encodeURIComponent(host)}&type=TXT`; - const response = await this.ctx.curl(url, { - method: 'GET', - headers: { accept: 'application/dns-json' }, - timeout: verifyConfig.timeoutMs, - dataType: 'json', - }); + async queryDohEndpoint(host, endpoint, timeoutMs) { + try { + const url = endpoint + '?name=' + encodeURIComponent(host) + '&type=TXT'; + const response = await this.ctx.curl(url, { + method: 'GET', + headers: { accept: 'application/dns-json' }, + timeout: timeoutMs, + dataType: 'json', + }); - const statusCode = Number(response && response.status) || 0; - if (statusCode !== 200) { - throw new Error(`DoH 服务返回异常状态码 ${statusCode}`); + const statusCode = Number(response && response.status) || 0; + if (statusCode !== 200) { + return { kind: 'error', endpoint, reason: 'DoH 服务返回异常状态码 ' + statusCode }; + } + + const body = response && response.data; + if (!body || typeof body !== 'object') { + return { kind: 'error', endpoint, reason: 'DoH 响应体不是合法 JSON' }; + } + + const values = this.extractTxtValuesFromAnswers(body.Answer); + if (values.length > 0) { + return { kind: 'values', endpoint, values }; + } + + // Status=3(NXDOMAIN)或 Status=0 但无 Answer(NODATA)→ 端点级「未解析到记录」 + return { kind: 'empty', endpoint }; + } catch (error) { + return { + kind: 'error', + endpoint, + reason: this.sanitizeErrorText(error && error.message) || 'DoH 请求异常', + }; } - - const body = response && response.data; - if (!body || typeof body !== 'object') { - throw new Error('DoH 响应体不是合法 JSON'); - } - - // Status=3(NXDOMAIN)或 Status=0 但无 Answer 均视为「未解析到记录」, - // 返回空数组交给上层判定,不降级系统 DNS 重复查询 - return this.extractTxtValuesFromAnswers(body.Answer); } /** - * 系统 DNS(node:dns)解析 TXT 记录,作为 DoH 的兜底路径。 + * DoH(DNS-over-HTTPS)多端点顺序解析 TXT 记录。 + * + * 契约变更(内部 helper,仅本文件 resolveTxtValues 调用): + * 旧版返回 string[](单端点 dohUrl,NODATA 直接定论为「无记录」);现返回明细对象, + * 以便上层区分「端点说没有记录(empty)」与「端点不可用(error)」并据此决定是否降级系统 DNS。 + * 对外契约(resolveTxtValues / verifyDomainRecord)保持向后兼容。 + * + * 为什么不能让单端点的 NODATA 直接定论(本次线上实测案例): + * 主机 wmsv-aa4adaab13.wms.wms.gztbyc.com 的 TXT 记录 ddd9ae51cf95b488db544f23ccd01e7b 真实存在 + * (8.8.8.8 / 223.5.5.5 / nslookup / AliDNS DoH 四方一致),但默认端点 https://doh.pub/dns-query + * 仍返回 Status=0 且 Answer 为空(陈旧负缓存:同一主机 A 查询同步 NODATA,返回的 SOA 序列号 2026081813 + * 旧于 TXT 查询的 2026082815,重复两次结果一致)。旧实现据此直接返回 [] 且不降级, + * 导致 verifyDomainRecord 判 verified=false → domain_status 被打成 2 → 被 getByDomain/nginx 闸门断流。 + * 因此这里改为:只有端点「明确拿到值」才立即成功返回;某个端点 empty 仅记为「候选无记录」, + * 必须等所有端点都尝试完(必要时再降级系统 DNS)才定论。 * * @param {string} host 待解析主机名。 + * @param {Object} verifyConfig 域名验证配置(getDomainVerifyConfig 返回值,取 dohUrls / timeoutMs)。 + * @return {Promise} { values: string[], endpoint: string|null, hadEmpty: boolean, + * emptyEndpoint: string|null, errors: Array<{endpoint: string, reason: string}> }。 + * values 非空时 endpoint 为命中端点;values 为空时 emptyEndpoint 为第一个报 empty 的端点(无则 null), + * errors 为所有端点级失败原因(已脱敏)。本方法自身不抛异常。 + */ + async resolveTxtByDoh(host, verifyConfig) { + const configured = verifyConfig && verifyConfig.dohUrls; + const endpoints = Array.isArray(configured) && configured.length > 0 + ? configured + : this.resolveDohUrls({}); + const configuredTimeout = Number(verifyConfig && verifyConfig.timeoutMs); + const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 + ? configuredTimeout + : DEFAULT_DOH_TIMEOUT_MS; + + const errors = []; + let emptyEndpoint = null; + + for (const endpoint of endpoints) { + const result = await this.queryDohEndpoint(host, endpoint, timeoutMs); + + if (result.kind === 'values') { + return { + values: result.values, + endpoint: result.endpoint, + hadEmpty: !!emptyEndpoint, + emptyEndpoint, + errors, + }; + } + + if (result.kind === 'empty') { + if (!emptyEndpoint) { + emptyEndpoint = result.endpoint; + } + this.ctx.logger.info( + '[FrontConfigService.resolveTxtByDoh] 端点返回 NODATA/NXDOMAIN,继续尝试下一个端点: host=%s endpoint=%s', + host, + result.endpoint + ); + continue; + } + + errors.push({ endpoint: result.endpoint, reason: result.reason }); + this.ctx.logger.warn( + '[FrontConfigService.resolveTxtByDoh] 端点解析失败,继续尝试下一个端点: host=%s endpoint=%s reason=%s', + host, + result.endpoint, + result.reason + ); + } + + return { values: [], endpoint: null, hadEmpty: !!emptyEndpoint, emptyEndpoint, errors }; + } + + /** + * 系统 DNS(node:dns)解析 TXT 记录:DoH 全部端点都未取到值后的兜底路径。 + * + * 特别注意(本次实测):本机 Node resolver 可能指向不可用的解析器(Windows 上出现 127.0.0.1, + * 而实际 DNS 为 192.168.8.1,该解析器对 TXT 查询直接超时),此时 resolveTxt 报 ECONNREFUSED/超时。 + * c-ares 自身默认「5s × 多次重试」,故这里显式限时,避免单行串行阻塞定时任务整轮(核算见 resolveTxtValues)。 + * + * @param {string} host 待解析主机名。 + * @param {number} [timeoutMs] 超时上限(毫秒);≤ 0 或未传时不做限时(保持旧行为)。 * @return {Promise} TXT 记录文本列表(多段已拼接、去空、截断)。 * @throws {Error} 解析失败(含 NXDOMAIN/超时)时抛出。 */ - async resolveTxtBySystem(host) { - const records = await dns.promises.resolveTxt(host); - const values = []; + async resolveTxtBySystem(host, timeoutMs) { + const limitMs = Number(timeoutMs) > 0 ? Number(timeoutMs) : 0; - for (const record of Array.isArray(records) ? records : []) { - const joined = Array.isArray(record) ? record.join('') : String(record || ''); - const value = joined.trim().slice(0, TXT_VALUE_MAX_LENGTH); - if (value) { - values.push(value); + const query = (async () => { + const records = await dns.promises.resolveTxt(host); + const values = []; + + for (const record of Array.isArray(records) ? records : []) { + const joined = Array.isArray(record) ? record.join('') : String(record || ''); + const value = joined.trim().slice(0, TXT_VALUE_MAX_LENGTH); + if (value) { + values.push(value); + } } + + return values; + })(); + + if (limitMs <= 0) { + return query; } - return values; + let timer = null; + try { + // Promise.race 会给两个分支都挂上处理器,落败分支的 reject 不会产生 unhandledRejection + return await Promise.race([ + query, + new Promise((_resolve, reject) => { + timer = setTimeout( + () => reject(new Error('系统 DNS 解析超时(>' + limitMs + 'ms)')), + limitMs + ); + }), + ]); + } finally { + if (timer) { + clearTimeout(timer); + } + } } /** - * 解析指定主机名的 TXT 记录(DoH 主路径,失败降级系统 DNS)。 + * 解析指定主机名的 TXT 记录(DoH 多端点顺序尝试为主,必要时降级系统 DNS)。 * - * 公共方法:app/schedule 下的域名验证定时任务会直接调用,签名与返回值需保持稳定。 + * 决策流程: + * 1. 依次尝试 dohUrls(见 getDomainVerifyConfig / resolveDohUrls)中的每个端点: + * - 有 TXT 值 → 立即返回 { values, source: 'doh', endpoint }; + * - empty(Status=0 且无 Answer / Status=3 NXDOMAIN)→ 记下「候选无记录」并继续下一个端点; + * - error(异常/超时/HTTP 非 200/响应体非对象)→ 记录脱敏原因并继续下一个端点。 + * 2. 所有端点结束后: + * - 至少一个端点 empty(且无端点拿到值)→ 降级系统 DNS: + * · 有值 → { values, source: 'system', endpoint: null }; + * · 空/NXDOMAIN → { values: [], source: 'doh', endpoint: null }(语义=未解析到记录,不抛错); + * · 抛错(如 ECONNREFUSED)→ 仍按「未解析到记录」返回 []:已有端点明确说没有该记录时, + * 不能因为兜底路径不可用就把结果升级成 500(否则会把「没配记录」误报成服务故障)。 + * - 所有端点都是 error(无任何 empty)→ 降级系统 DNS: + * · 有值 → { values, source: 'system', endpoint: null }; + * · 空 → { values: [], source: 'system', endpoint: null }(系统 DNS 明确答复为空 → 未解析到记录); + * · 抛错 → 所有可用解析路径都不可用 → 抛 500(保持旧语义 + 脱敏/截断)。 + * + * 兼容性:返回对象在既有 { values, source } 之上「追加」 endpoint 字段; + * verifyDomainRecord / checkDomain / verifyPendingDomains / app/schedule 的签名与判定口径均不变, + * verifyDomainRecord 仍永不抛异常(解析失败只体现为 error 文案)。 + * + * 可观测性:端点级失败、降级决策与最终定论都会打 INFO/WARN 日志并带上 source/endpoint, + * 便于把「记录确实不存在」与「解析链路整体不可用」区分开。 + * + * 最坏耗时:单主机 ≈ (DoH 端点数 3 + 系统 DNS 兜底 1) × timeoutMs(3000ms) = 12s(系统 DNS 亦按 timeoutMs 限时); + * 单轮 batchSize(20) 行最坏 ≈ 240s,明显小于 lockTtlSeconds(600s) 与 interval(600s)。 * * @param {string} host 待解析主机名(域名验证一律传 domain_verify_host,不用裸域名)。 - * @return {Promise} { values: string[], source: 'doh'|'system' }。 - * @throws {Error} 两条路径均失败时抛出,状态码 500,文案已脱敏截断。 + * @return {Promise} { values: string[], source: 'doh'|'system', endpoint: string|null }。 + * @throws {Error} 所有 DoH 端点均失败且系统 DNS 也失败时抛出,状态码 500,文案已脱敏截断。 */ async resolveTxtValues(host) { const normalizedHost = String(host || '').trim().toLowerCase(); @@ -404,39 +616,97 @@ class FrontConfigService extends Service { } const verifyConfig = this.getDomainVerifyConfig(); + const dohResult = await this.resolveTxtByDoh(normalizedHost, verifyConfig); + if (dohResult.values.length > 0) { + return { values: dohResult.values, source: 'doh', endpoint: dohResult.endpoint }; + } + + // 至少一个端点明确「未解析到记录」(NODATA/NXDOMAIN)→ 已有旁证,系统 DNS 仅作二次确认 + const trustedEmpty = dohResult.hadEmpty; + + let systemValues = null; + let systemError = null; try { - const values = await this.resolveTxtByDoh(normalizedHost, verifyConfig); - return { values, source: 'doh' }; + systemValues = await this.resolveTxtBySystem(normalizedHost, verifyConfig.timeoutMs); } catch (error) { - this.ctx.logger.warn( - '[FrontConfigService.resolveTxtValues] DoH 解析失败,降级系统 DNS: %s', - this.sanitizeErrorText(error.message) + systemError = error; + } + + if (Array.isArray(systemValues) && systemValues.length > 0) { + this.ctx.logger.info( + '[FrontConfigService.resolveTxtValues] DoH 未取到值,系统 DNS 命中: host=%s dohEmptyEndpoint=%s', + normalizedHost, + dohResult.emptyEndpoint || '-' ); + return { values: systemValues, source: 'system', endpoint: null }; } - try { - const values = await this.resolveTxtBySystem(normalizedHost); - return { values, source: 'system' }; - } catch (error) { - const reason = this.sanitizeErrorText(error.message) || '未知错误'; - throw this.createError(`DNS 解析失败:${reason}`, 500); + if (trustedEmpty) { + if (systemError) { + this.ctx.logger.warn( + '[FrontConfigService.resolveTxtValues] DoH 有端点明确无记录、系统 DNS 失败,按「未解析到记录」处理: host=%s endpoint=%s reason=%s', + normalizedHost, + dohResult.emptyEndpoint, + this.sanitizeErrorText(systemError.message) || '未知错误' + ); + } + return { values: [], source: 'doh', endpoint: null }; } + + if (!systemError) { + // 所有 DoH 端点均 error,但系统 DNS 明确答复为空 → 未解析到记录(不升级为 500) + this.ctx.logger.warn( + '[FrontConfigService.resolveTxtValues] DoH 端点全部失败且系统 DNS 返回空,按「未解析到记录」处理: host=%s dohErrors=%d', + normalizedHost, + dohResult.errors.length + ); + return { values: [], source: 'system', endpoint: null }; + } + + const systemReason = this.sanitizeErrorText(systemError.message) || '未知错误'; + const dohReason = dohResult.errors.length > 0 + ? dohResult.errors.map(item => item.endpoint + ': ' + item.reason).join('; ') + : ''; + this.ctx.logger.warn( + '[FrontConfigService.resolveTxtValues] DoH 与系统 DNS 均失败: host=%s doh=%s system=%s', + normalizedHost, + this.sanitizeErrorText(dohReason), + systemReason + ); + throw this.createError( + 'DNS 解析失败:' + this.sanitizeErrorText(dohReason ? dohReason + ';系统 DNS: ' + systemReason : systemReason), + 500 + ); } /** - * 校验单行记录的域名 TXT 归属(定时任务逐行调用,必须失败隔离、不得抛异常)。 + * 校验一条 TXT 归属记录(定时任务逐行调用,必须失败隔离、不得抛异常)。 * - * @param {Object} record 配置记录(需含 domain_verify_host / domain_verify_token)。 + * 签名说明(两阶段切换改造):新增可选第二参数 overrides,允许调用方直接指定待校验的 + * host / token——校验「待验证域名」时传 pending_verify_host / pending_verify_token + * 走这条路径;不传时回退读取记录上的 domain_verify_host / domain_verify_token, + * 因此既有两个调用点(生效域名校验 / 升级前逻辑)行为完全不变。 + * + * @param {Object} record 配置记录(Sequelize 实例或 raw 普通对象;未传 overrides 时需含 domain_verify_host / domain_verify_token)。 + * @param {Object} [overrides={}] 显式指定的校验目标。 + * @param {string} [overrides.host] 待解析主机名(优先级高于记录上的 domain_verify_host)。 + * @param {string} [overrides.token] 待比对 TXT 值(优先级高于记录上的 domain_verify_token)。 * @return {Promise} 校验结果,字段如下: * - verified {boolean}:是否校验通过(解析到的 TXT 记录中包含校验值); * - values {string[]}:实际解析到的 TXT 值; - * - source {string}:解析来源 doh/system,未解析为空串; + * - source {string}:解析来源 doh/system,未解析为空串(resolveTxtValues 另返回 endpoint,本方法不透出); + * - 注意:解析路径「明确无记录」时本方法返回 verified=false + values=[](不抛异常), + * 仅当所有 DoH 端点与系统 DNS 都解析失败时,resolveTxtValues 才抛 500 并在此转为 error 文案。 * - error {string|null}:失败原因(已脱敏截断),成功为 null。 */ - async verifyDomainRecord(record) { - const verifyHost = String(this.getRecordField(record, 'domain_verify_host') || '').trim(); - const verifyToken = String(this.getRecordField(record, 'domain_verify_token') || '').trim(); + async verifyDomainRecord(record, overrides = {}) { + const overrideHost = String((overrides && overrides.host) || '').trim(); + const overrideToken = String((overrides && overrides.token) || '').trim(); + const verifyHost = overrideHost + || String(this.getRecordField(record, 'domain_verify_host') || '').trim(); + const verifyToken = overrideToken + || String(this.getRecordField(record, 'domain_verify_token') || '').trim(); if (!verifyHost) { return { verified: false, values: [], source: '', error: '未生成待校验的 TXT 主机名,请重新设置域名' }; @@ -538,24 +808,31 @@ class FrontConfigService extends Service { } /** - * 扫描并校验待验证的域名(供定时任务与手动触发复用)。 + * 扫描并校验「待验证域名」(供定时任务与手动触发复用)。 * - * 选取条件:domain_verify_host 与 domain_verify_token 均非空、domain_status 为 0(未验证) - * 或 2(验证失败),且 domain_verify_attempts 未达 maxAttempts 上限;按 id 升序单批处理 - * batchSize 行。已达尝试上限的行不再自动重试,计入 skipped(仍可由 checkDomain 手动触发)。 + * 两阶段切换后本方法只处理 pending 组:选取 pending_domain / pending_verify_host / + * pending_verify_token 均非空、且 pending_verify_attempts 未达 maxAttempts 上限的行, + * 按 id 升序单批处理 batchSize 行。 + * · 校验通过 → promotePendingDomain 提升为生效域名(清证书/重置同步/旧域名入下线队列) + * + 清旧、新两个域名缓存,计入 verified; + * · 校验失败 → pending_verify_attempts + 1、pending_last_error(脱敏截断),计入 failed, + * 生效域名、domain_status 与证书一律不动(旧域名不会被本任务断流); + * · 已达上限的行不再自动重试,计入 skipped(仍可由 checkDomain 手动触发)。 * - * 失败隔离:单行解析/落库失败只计入 errors,不中断整轮;onRow 回调抛错同样不影响主流程。 - * fail-soft:model 不可用、或迁移尚未执行(domain_status 等列不存在)时不抛出, - * 返回零统计 + errors 中的脱敏原因,由调用方记 WARN。 + * 失败隔离:单行解析/提升/落库失败只计入 errors,不中断整轮;onRow 回调抛错同样不影响主流程。 + * fail-soft:model 不可用、或迁移尚未执行(pending_* 列不存在,ER_BAD_FIELD_ERROR) + * 时不抛出,返回零统计 + errors 中的脱敏原因,由调用方记 WARN。 * * @param {Object} [options] 扫描选项。 * @param {number} [options.batchSize] 单轮最多处理行数(默认取 domainVerify.batchSize)。 * @param {number} [options.maxAttempts] 超过后不再自动重试(默认取 domainVerify.maxAttempts)。 - * @param {Function} [options.onRow] 每行处理后的回调(参数 { id, store_id, domain, verified, error })。 + * @param {Function} [options.onRow] 每行处理后的回调,参数 + * { id, store_id, domain, pending_domain, verified_domain, verified, error } + * (domain 为库内生效域名,可为空;pending_domain / verified_domain 为本轮校验的待验证域名)。 * @return {Promise<{scanned:number, verified:number, failed:number, skipped:number, errors:string[]}>} - * scanned:本轮选中的待处理行数;verified:其中校验通过且落库成功的行数; - * failed:校验失败且落库成功的行数;skipped:因达到 maxAttempts 上限而未自动重试的行数; - * errors:脱敏后的错误原因列表。 + * scanned:本轮选中的待处理行数;verified:其中校验通过且提升成功的行数; + * failed:校验失败且 pending 状态回写成功的行数;skipped:因达到 maxAttempts 上限而未自动重试的行数; + * errors:脱敏后的错误原因列表(含提升失败,这类行不计入 verified / failed)。 */ async verifyPendingDomains(options = {}) { const verifyConfig = this.getDomainVerifyConfig(); @@ -577,9 +854,9 @@ class FrontConfigService extends Service { const { Op } = this.app.Sequelize; const pendingWhere = { - domain_verify_host: { [Op.ne]: null }, - domain_verify_token: { [Op.ne]: null }, - domain_status: { [Op.in]: [ DOMAIN_STATUS_UNVERIFIED, DOMAIN_STATUS_FAILED ] }, + pending_domain: { [Op.ne]: null }, + pending_verify_host: { [Op.ne]: null }, + pending_verify_token: { [Op.ne]: null }, }; let rows = []; @@ -587,17 +864,17 @@ class FrontConfigService extends Service { rows = await configModel.findAll({ where: { ...pendingWhere, - domain_verify_attempts: { [Op.lt]: maxAttempts }, + pending_verify_attempts: { [Op.lt]: maxAttempts }, }, attributes: [ 'id', 'store_id', 'domain', - 'domain_status', - 'domain_verify_host', - 'domain_verify_token', - 'domain_verify_attempts', - 'domain_last_error', + 'pending_domain', + 'pending_verify_host', + 'pending_verify_token', + 'pending_verify_attempts', + 'pending_last_error', ], order: [[ 'id', 'ASC' ]], limit: batchSize, @@ -605,8 +882,12 @@ class FrontConfigService extends Service { }); } catch (error) { const reason = this.sanitizeErrorText(error.message) || '未知错误'; + // 迁移未执行时 pending_* 列不存在:明确提示,避免把「列不存在」误判为数据/网络问题 + const hint = this.isUnknownColumnError(error) + ? '(迁移 20260924180000-add-pending-domain-to-wms-warehouse-front-config 尚未执行,pending_* 列不存在)' + : ''; this.ctx.logger.warn('[FrontConfigService.verifyPendingDomains] 查询待验证域名失败: %s', reason); - summary.errors.push('查询待验证域名失败:' + reason); + summary.errors.push('查询待验证域名失败:' + reason + hint); return summary; } @@ -616,7 +897,7 @@ class FrontConfigService extends Service { summary.skipped = await configModel.count({ where: { ...pendingWhere, - domain_verify_attempts: { [Op.gte]: maxAttempts }, + pending_verify_attempts: { [Op.gte]: maxAttempts }, }, }); } catch (error) { @@ -630,53 +911,59 @@ class FrontConfigService extends Service { for (const row of rows) { const rowId = Number(row.id); const rowDomain = String(row.domain || '').trim(); - const currentAttempts = Number(row.domain_verify_attempts) || 0; + const pendingDomain = String(row.pending_domain || '').trim(); let result = { verified: false, error: '未解析到 TXT 记录' }; try { // verifyDomainRecord 契约上不抛异常,此处为最后一道兜底,保证单行失败不中断整轮 - result = await this.verifyDomainRecord(row); + result = await this.verifyDomainRecord(row, { + host: row.pending_verify_host, + token: row.pending_verify_token, + }); } catch (error) { result = { verified: false, error: this.sanitizeErrorText(error.message) || '域名校验异常' }; } - let updateValues; if (result.verified) { - updateValues = { - domain_status: DOMAIN_STATUS_VERIFIED, - domain_verified_at: new Date(), - domain_last_error: null, - domain_verify_attempts: currentAttempts + 1, - }; - } else { - updateValues = { - domain_status: DOMAIN_STATUS_FAILED, - domain_verify_attempts: currentAttempts + 1, - domain_last_error: this.sanitizeErrorText(result.error || '未解析到 TXT 记录'), - }; - } - - try { - // 防并发守卫:仅更新 id 与 domain 均匹配的行,避免与并发校验者互相覆盖 - await configModel.update(updateValues, { - where: { id: rowId, domain: row.domain }, - }); - - if (result.verified) { + // 校验通过 → 提升为生效域名:清空证书、重置同步状态、旧域名写入 retired_domain 下线队列 + try { + await this.promotePendingDomain(row); summary.verified += 1; - // 未验证域名本不会被公共拉取放行,成功后仍主动清一次缓存更稳妥 - await this.clearDomainCache(rowDomain); - } else { - summary.failed += 1; + // 先写库、后清缓存:旧域名(即将下线)与新域名两个 key 都必须清,清失败仅记 WARN + await this.clearDomainCaches( + [ rowDomain, pendingDomain ], + 'FrontConfigService.verifyPendingDomains' + ); + } catch (error) { + const reason = this.sanitizeErrorText(error.message) || '未知错误'; + summary.errors.push('提升待验证域名失败(id=' + rowId + '):' + reason); + this.ctx.logger.warn( + '[FrontConfigService.verifyPendingDomains] 提升待验证域名失败 id=%s: %s', + rowId, + reason + ); + } + } else { + // 校验失败只写 pending 组:生效域名、domain_status 与证书一律不动 + const pendingError = this.sanitizeErrorText(result.error || '未解析到 TXT 记录'); + try { + // 防并发守卫:仅更新 id 与 pending_domain 均匹配的行,避免与并发校验/取消待切换互相覆盖 + await configModel.update({ + pending_verify_attempts: Number(row.pending_verify_attempts || 0) + 1, + pending_last_error: pendingError, + }, { + where: { id: rowId, pending_domain: row.pending_domain }, + }); + summary.failed += 1; + } catch (error) { + const reason = this.sanitizeErrorText(error.message) || '未知错误'; + summary.errors.push('更新待验证域名状态失败(id=' + rowId + '):' + reason); + this.ctx.logger.warn( + '[FrontConfigService.verifyPendingDomains] 更新待验证域名状态失败 id=%s: %s', + rowId, + reason + ); } - } catch (error) { - const reason = this.sanitizeErrorText(error.message) || '未知错误'; - summary.errors.push('更新域名验证状态失败(id=' + rowId + '):' + reason); - this.ctx.logger.warn( - '[FrontConfigService.verifyPendingDomains] 更新域名验证状态失败 id=%s: %s', - rowId, - reason - ); } if (onRow) { @@ -685,6 +972,8 @@ class FrontConfigService extends Service { id: rowId, store_id: Number(row.store_id) || 0, domain: rowDomain, + pending_domain: pendingDomain, + verified_domain: pendingDomain, verified: !!result.verified, error: result.verified ? null : this.sanitizeErrorText(result.error || ''), }); @@ -845,8 +1134,14 @@ class FrontConfigService extends Service { * * 需登录(token 绑定仓库上下文,只能查到自己仓库的配置);无记录时返回空值默认。 * - * @return {Promise} 域名输出对象(warehouse_id/domain/domain_status/verify_host/ - * verify_value/cname/verified_at/attempts/last_error)。 + * 两阶段切换后输出在既有 9 个字段之后追加待验证域名组(pending_domain / pending_verify_host / + * pending_verify_value / pending_attempts / pending_last_error / pending_created_at / + * pending_active),既有字段一律不改名、不删除;字段口径详见 buildDomainOutput。 + * + * @return {Promise} 域名输出对象,既有 9 字段(warehouse_id/domain/domain_status/ + * verify_host/verify_value/cname/verified_at/attempts/last_error)+ 待验证域名组 7 字段 + * (pending_domain/pending_verify_host/pending_verify_value/pending_attempts/pending_last_error/ + * pending_created_at/pending_active),字段含义见 buildDomainOutput。 * @throws {Error} 未识别到当前仓库时抛出 400;非仓库主体时抛出 403。 */ async getDomain() { @@ -870,16 +1165,33 @@ class FrontConfigService extends Service { } /** - * 设置当前仓库自持域名并下发一次性 TXT 校验记录(需登录、仅仓库主体)。 + * 设置当前仓库自持域名(需登录、仅仓库主体)。 * - * 流程:仓库主体校验 → domain 非空/长度/形态校验(统一转小写)→ 全局唯一校验(409) - * → 生成随机校验子域与校验值 → upsert 该仓库行 → 清理新旧域名公共拉取缓存。 - * 域名发生变更(含从无到有)会同时清空既有证书与同步状态:旧证书 SAN/CN 不覆盖新域名, - * 保留会让 nginx 用错误证书对外服务;域名未变化时保留既有证书与验证状态。 + * 两阶段切换(本次改造核心):本接口只登记「待验证域名」,不直接改动生效域名。 + * 第一阶段(本接口):把入参写入 pending_domain 并下发一次性 DNS TXT 校验记录; + * 第二阶段(checkDomain 手动触发 / app/schedule/domain_verify_scan.js 定时扫描): + * TXT 校验通过后由 promotePendingDomain 一次性把 pending_domain 提升为 domain + * (同时把旧域名写入 retired_domain 下线队列、清空证书并重置同步状态)。 + * 这样生效域名全程不变:切换期间旧域名的前端页面与 getByDomain 公共拉取都仍然可用, + * 直到提升完成后由外部证书脚本按 retired_domain 删除旧域名的 nginx 配置与证书文件。 + * + * 分支(域名比较一律忽略大小写): + * A) 入参 == 生效域名 domain 且无待验证域名 → 幂等短路:不写库;仅当库内字面值与归一化 + * 结果不一致时把 domain 改写为小写并清理新旧两个字面值的缓存 key。 + * · 与旧实现的差异:原有「未验证/验证失败且缺校验码则补发校验码」的子分支已移除, + * 缺码的历史脏数据行不再自动补码(需重新生效请提交一个不同的待验证域名)。 + * B) 入参 == 生效域名 domain 且有 pending_domain → 取消待切换:清空 pending 6 列; + * 生效域名、证书 5 列、同步 4 列与公共缓存一律不动。 + * C) 入参 == 现有 pending_domain → 校验码齐全则幂等短路(不重发、不写库); + * 校验码缺失(脏数据)则只补发 pending 校验码并清 pending 尝试次数/失败原因。 + * D) 其它(新的待切换域名,含首次设置)→ 查重(其他仓库的 domain 或 pending_domain + * 占用即 409)→ 生成新校验码写入 pending 组;生效域名 domain / domain_status / + * domain_verified_at / domain_verify_* / 证书 5 列 / 同步 4 列一律不动, + * 也不清理任何公共缓存(新域名尚未生效,getByDomain 不受影响)。 * * @param {Object} [data={}] 请求参数。 - * @param {string} data.domain 仓库自持域名(必填,非空,≤100 字符,全局唯一)。 - * @return {Promise} 域名输出对象(含待配置的 verify_host/verify_value 与 cname)。 + * @param {string} data.domain 仓库自持域名(必填,非空,≤100 字符,全局唯一,忽略大小写去重)。 + * @return {Promise} 域名输出对象(生效域名组 + 待验证域名组 + cname)。 * @throws {Error} 未识别到当前仓库时抛出 400;非仓库主体时抛出 403; * 参数非法时抛出 400;域名被其他仓库占用时抛出 409。 */ @@ -905,60 +1217,114 @@ class FrontConfigService extends Service { throw this.createError('domain 格式不正确', 400); } - // domain 全局唯一:可空列唯一索引不拦多个 NULL,非空值的唯一性必须应用层校验 - await this.assertDomainUnique(normalizedDomain, warehouseId); - const record = await configModel.findOne({ where: { store_id: warehouseId, }, }); - const previousDomain = record ? String(record.get('domain') || '').trim() : ''; - // 仅大小写差异不算域名变更:避免单纯规范化大小写就把仍在有效期内的证书清掉 - const domainChanged = previousDomain.toLowerCase() !== normalizedDomain; + const currentDomain = record ? String(record.get('domain') || '').trim() : ''; + const currentPendingDomain = record ? String(record.get('pending_domain') || '').trim() : ''; + const matchesCurrentDomain = !!currentDomain && currentDomain.toLowerCase() === normalizedDomain; + const matchesPendingDomain = !!currentPendingDomain + && currentPendingDomain.toLowerCase() === normalizedDomain; - // 重复设置同一已验证域名:幂等返回,不刷新校验码、不清证书、不重置验证状态 - if (record && !domainChanged && Number(record.get('domain_status') || 0) === DOMAIN_STATUS_VERIFIED) { - return this.buildDomainOutput(record, warehouseId); + // ===== 分支 A:入参 == 生效域名 且无待验证域名 → 幂等短路(仅大小写规范化时写库) ===== + // 本分支刻意跳过 assertDomainUnique 查重:域名已是本仓自身持有,查重恒为「不冲突」, + // 属无意义查询;全局唯一性由分支 D 的查重与数据库唯一索引共同兜底。 + if (record && matchesCurrentDomain && !currentPendingDomain) { + if (currentDomain === normalizedDomain) { + // 完全无变化:不写库、不清缓存,直接回显当前状态(幂等) + return this.buildDomainOutput(record, warehouseId); + } + + // 大小写规范化:只把 domain 一个字面值字段改写为小写,其余字段一律不动 + try { + await record.update({ domain: normalizedDomain }); + } catch (error) { + // 并发写入兜底:唯一索引冲突统一转为业务错误 + // (大小写规范化可能撞上其他仓库已占用的同名字面值,属真实冲突) + if (error && error.name === 'SequelizeUniqueConstraintError') { + throw this.createError(`域名 ${normalizedDomain} 已被其他仓库使用`, 409); + } + throw error; + } + + // 回查一次再输出,避免实例上残留 CURRENT_TIMESTAMP 等字面量 + const refreshedRecord = await configModel.findByPk(record.id); + + // 缓存清理:公共拉取缓存键按域名字面值精确匹配(front:config:domain:Shop.com 与 + // ...:shop.com 是两个 key),新旧两个字面值都必须清 + await this.clearDomainCaches( + [ currentDomain, normalizedDomain ], + 'FrontConfigService.setDomain' + ); + + return this.buildDomainOutput(refreshedRecord, warehouseId); } - // 首次设置/域名变更/尚未验证:下发新的校验码并回到「未验证」,清零历史尝试次数与失败原因 - const verifyCode = this.buildDomainVerifyCode(normalizedDomain); - const patch = { - domain: normalizedDomain, - domain_verify_host: verifyCode.host, - domain_verify_token: verifyCode.token, - domain_status: DOMAIN_STATUS_UNVERIFIED, - domain_verify_attempts: 0, - domain_verified_at: null, - domain_last_error: null, - }; + // ===== 分支 B:入参 == 生效域名 且有待验证域名 → 取消待切换 ===== + if (record && matchesCurrentDomain && currentPendingDomain) { + // 只清 pending 6 列:生效域名、证书 5 列、同步 4 列一律不动; + // 待验证域名从未生效(不参与 getByDomain),因此无需清理公共缓存 + await record.update(this.buildPendingClearPatch()); - if (domainChanged) { - // 域名变更:既有证书对新域名不再有效,必须一并清空并重置同步状态, - // 避免 nginx 继续用旧域名证书对外服务(证书与域名不匹配) - Object.assign(patch, { - cert_pem: null, - cert_key: null, - cert_path: null, - key_path: null, - cert_expire_at: null, - sync_status: 0, - sync_attempts: 0, - last_sync_error: null, - last_synced_at: null, + const refreshedRecord = await configModel.findByPk(record.id); + return this.buildDomainOutput(refreshedRecord, warehouseId); + } + + // ===== 分支 C:入参 == 现有待验证域名 → 码齐幂等短路,码缺只补码 ===== + if (record && matchesPendingDomain) { + const pendingVerifyHost = String(record.get('pending_verify_host') || '').trim(); + const pendingVerifyToken = String(record.get('pending_verify_token') || '').trim(); + + if (pendingVerifyHost && pendingVerifyToken) { + // 校验码齐全:不重发、不写库,直接回显(幂等) + return this.buildDomainOutput(record, warehouseId); + } + + // 脏数据(待验证域名没有校验码)→ 只补发校验码并清 pending 尝试次数/失败原因, + // 不碰生效域名、证书与同步状态,也不清缓存(待验证域名未生效) + const verifyCode = this.buildDomainVerifyCode(normalizedDomain); + await record.update({ + pending_domain: normalizedDomain, + pending_verify_host: verifyCode.host, + pending_verify_token: verifyCode.token, + pending_verify_attempts: 0, + pending_last_error: null, + pending_created_at: record.get('pending_created_at') || new Date(), }); + + const refreshedRecord = await configModel.findByPk(record.id); + return this.buildDomainOutput(refreshedRecord, warehouseId); } + // ===== 分支 D:新的待验证域名(含首次设置)→ 只登记 pending,不动生效域名 ===== + // domain 全局唯一:可空列唯一索引不拦多个 NULL,非空值的唯一性必须应用层校验 + // (其他仓库的 domain 或 pending_domain 命中任一都算占用) + await this.assertDomainUnique(normalizedDomain, warehouseId); + + // 生成校验码并只写入 pending 组;生效域名组/证书/同步状态一律不动 + const verifyCode = this.buildDomainVerifyCode(normalizedDomain); + const pendingPatch = { + pending_domain: normalizedDomain, + pending_verify_host: verifyCode.host, + pending_verify_token: verifyCode.token, + pending_verify_attempts: 0, + pending_last_error: null, + pending_created_at: new Date(), + }; + let savedRecord = record; try { if (record) { - await record.update(patch); + await record.update(pendingPatch); } else { + // 首次设置:新行只带 store_id 与 pending 组;domain 保持 NULL(尚未生效), + // domain_status 默认 0,证书脚本只处理 domain_status = 1 的行,不会误处理本行 savedRecord = await configModel.create({ store_id: warehouseId, - ...patch, + ...pendingPatch, }); } } catch (error) { @@ -976,27 +1342,188 @@ class FrontConfigService extends Service { // 回查一次再输出,避免实例上残留 CURRENT_TIMESTAMP 等字面量 const refreshedRecord = await configModel.findByPk(savedRecord.id); - // 写库成功后清理公共拉取缓存(先写库后清缓存):域名变更时新旧两个 domain 都必须清, - // 否则旧域名的公开配置缓存仍会对外返回;清缓存失败仅记日志,不影响设置结果 - const affectedDomains = [ ...new Set([ previousDomain, normalizedDomain ].filter(item => item)) ]; - await Promise.all(affectedDomains.map(affectedDomain => this.clearDomainCache(affectedDomain) - .catch(error => { - this.ctx.logger.warn('[FrontConfigService.setDomain] 清理前端配置缓存失败: %s', error.message); - }))); - + // 不清任何公共缓存:新域名尚未生效(生效域名 domain 未变),getByDomain 结果不受影响 return this.buildDomainOutput(refreshedRecord, warehouseId); } + /** + * 把「待验证域名」提升为「生效域名」(两阶段切换的第二阶段,checkDomain 与定时扫描共用)。 + * + * 调用前提:pending_verify_host / pending_verify_token 已经 TXT 校验通过(本方法不再解析 DNS)。 + * 一次 update 提交以下字段(where 带 id + pending_domain 守卫,防并发重复提升): + * 1. 下线队列:生效域名非空且与待验证域名不同(忽略大小写)→ retired_domain = 旧域名、 + * retired_at = now。首次设置(无生效域名)不写这两列(保持 NULL,等价于清空); + * 同时刻意不把 retired_domain 置 NULL——队列里可能还有更早的旧域名等待外部证书脚本 + * 消费,覆盖会丢失下线任务(孤儿由脚本兜底清理)。 + * 2. 生效组:domain = pending_domain、domain_status = 1、domain_verified_at = now、 + * domain_verify_host / domain_verify_token / domain_verify_attempts 由 pending_* 平移、 + * domain_last_error = null。 + * 3. 清空 pending 6 列(pending_verify_attempts 归 0,其余置 NULL)。 + * 4. 清空证书 5 列 + 重置同步 4 列:域名已变,旧证书 SAN/CN 不覆盖新域名,必须重新上传; + * sync_status = 0 让外部证书脚本在用户上传新证书后自动部署。注意提升后到新证书上传前, + * 证书脚本会以「cert_pem 内容为空」记一次同步失败(属预期噪音,失败只落库不删旧域名文件)。 + * + * 边界:retired_domain 只保留最近一个旧域名,多次连续切换会丢中间域名(由脚本孤儿兜底清理); + * 本方法不碰 nginx 文件,也不清缓存——缓存清理由调用方负责(清旧域名与新域名两个 key)。 + * + * @param {Object} record 配置记录(Sequelize 实例或 raw 普通对象,需含 id 与 pending_* 字段)。 + * @return {Promise} 提升后的最新记录实例(findByPk 回查);model 不支持 findByPk 时返回 null。 + * @throws {Error} 数据库异常原样抛出(含 domain 唯一索引冲突 SequelizeUniqueConstraintError)。 + */ + async promotePendingDomain(record) { + const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig; + if (!configModel || typeof configModel.update !== 'function') { + throw this.createError('WarehouseFrontConfig model 不可用', 500); + } + + const recordId = Number(this.getRecordField(record, 'id')); + const pendingDomain = String(this.getRecordField(record, 'pending_domain') || '').trim(); + if (!Number.isFinite(recordId) || recordId <= 0 || !pendingDomain) { + throw this.createError('待验证域名记录不完整,无法提升为生效域名', 500); + } + + const previousDomain = String(this.getRecordField(record, 'domain') || '').trim(); + const shouldRetire = !!previousDomain + && previousDomain.toLowerCase() !== pendingDomain.toLowerCase(); + const now = new Date(); + + const updateValues = { + // 生效组:由 pending 组平移 + domain: pendingDomain, + domain_status: DOMAIN_STATUS_VERIFIED, + domain_verified_at: now, + domain_verify_host: this.getRecordField(record, 'pending_verify_host') || null, + domain_verify_token: this.getRecordField(record, 'pending_verify_token') || null, + domain_verify_attempts: Number(this.getRecordField(record, 'pending_verify_attempts') || 0), + domain_last_error: null, + // 待验证组:清空 + ...this.buildPendingClearPatch(), + // 证书与同步状态:域名已变,证书必须重新上传(等外部脚本按新域名重新部署) + cert_pem: null, + cert_key: null, + cert_path: null, + key_path: null, + cert_expire_at: null, + sync_status: 0, + sync_attempts: 0, + last_sync_error: null, + last_synced_at: null, + }; + + if (shouldRetire) { + updateValues.retired_domain = previousDomain; + updateValues.retired_at = now; + } + + // 防并发守卫:仅更新 id 与 pending_domain 均匹配的行 + // (重复提升、用户已取消待切换、其他实例已提升过时都不会误改) + await configModel.update(updateValues, { + where: { id: recordId, pending_domain: pendingDomain }, + }); + + if (typeof configModel.findByPk === 'function') { + return configModel.findByPk(recordId); + } + + return null; + } + + /** + * 校验「待验证域名」的 TXT 记录,通过则提升为生效域名(checkDomain 的路径一)。 + * + * 与旧口径的关键差异:校验失败**只写 pending 组**(pending_verify_attempts / pending_last_error), + * 生效域名 domain、domain_status、domain_verified_at 与证书一律不动——旧域名不会被本路径断流。 + * + * @param {Object} record 配置记录实例(含 pending_* 字段)。 + * @param {string} pendingDomain 待验证域名(已 trim,非空)。 + * @param {number} warehouseId 当前仓库 ID。 + * @return {Promise} 域名输出对象 + verified(本次是否通过)+ resolved_values。 + * @throws {Error} 提升时待验证域名已被其他仓库用为生效域名,抛出 409。 + */ + async checkPendingDomainRecord(record, pendingDomain, warehouseId) { + const configModel = this.ctx.model.WarehouseFrontConfig; + const previousDomain = String(record.get('domain') || '').trim(); + + const verifyResult = await this.verifyDomainRecord(record, { + host: record.get('pending_verify_host'), + token: record.get('pending_verify_token'), + }); + + if (!verifyResult.verified) { + // 校验不通过:只写 pending 组;写入失败也不影响结论(回显时按库内值兜底) + const pendingError = this.sanitizeErrorText(verifyResult.error) || '未解析到 TXT 记录'; + try { + await configModel.update({ + pending_verify_attempts: Number(record.get('pending_verify_attempts') || 0) + 1, + pending_last_error: pendingError, + }, { + where: { id: record.id, pending_domain: pendingDomain }, + }); + } catch (error) { + this.ctx.logger.warn( + '[FrontConfigService.checkPendingDomainRecord] 回写待验证失败原因失败: %s', + this.sanitizeErrorText(error.message) + ); + } + + const refreshedRecord = await configModel.findByPk(record.id); + return { + ...this.buildDomainOutput(refreshedRecord || record, warehouseId), + verified: false, + resolved_values: this.buildResolvedValues(verifyResult.values), + }; + } + + // 校验通过 → 提升为生效域名(清证书、重置同步状态、旧域名入下线队列) + try { + await this.promotePendingDomain(record); + } catch (error) { + this.ctx.logger.warn( + '[FrontConfigService.checkPendingDomainRecord] 提升待验证域名失败 domain=%s: %s', + pendingDomain, + this.sanitizeErrorText(error.message) + ); + if (error && error.name === 'SequelizeUniqueConstraintError') { + throw this.createError(`域名 ${pendingDomain} 已被其他仓库使用`, 409); + } + throw error; + } + + // 先写库、后清缓存:旧域名(即将下线)与新域名两个 key 都必须清,清失败仅记 WARN + await this.clearDomainCaches( + [ previousDomain, pendingDomain ], + 'FrontConfigService.checkPendingDomainRecord' + ); + + const promotedRecord = await configModel.findByPk(record.id); + return { + ...this.buildDomainOutput(promotedRecord || record, warehouseId), + verified: true, + resolved_values: this.buildResolvedValues(verifyResult.values), + }; + } + /** * 主动执行一次域名 TXT 校验并回写结果(需登录、仅仓库主体)。 * - * 无记录或 domain 为空时返回 400 提示先设置域名;校验通过置 domain_status=1 - * 并记录 domain_verified_at;失败置 domain_status=2、尝试次数 +1 并记录脱敏后的失败原因。 - * 校验一律以库内 domain_verify_host 为目标(不用裸域名),避免与用户主域其它 TXT 记录冲突。 + * 两阶段切换后本接口同时承担两条路径: + * 1. 存在 pending_domain(切换中)→ 校验 pending_verify_host 的 TXT 是否等于 + * pending_verify_token:通过则由 promotePendingDomain 提升为生效域名并清旧/新域名缓存, + * 返回 verified = true;不通过只累加 pending_verify_attempts 并记 pending_last_error, + * 返回 verified = false。全程不会改动生效域名与证书。 + * 2. 无 pending_domain(切换完成或尚未发起切换)→ 保持升级前口径: + * · 生效域名已验证(domain_status = 1)→ 一律短路 verified = true,不写库、不加 attempts + * (不论库内有无校验码),避免误点「校验」把已生效域名打成验证失败; + * · 生效域名为空 → 400「请先设置域名」; + * · 生效域名非空但未验证/验证失败(升级前登记的历史行)→ 用生效域名的 domain_verify_* + * 校验并回写 domain_status / domain_verify_attempts / domain_last_error(兼容路径)。 + * + * 校验一律以库内一次性随机子域为目标(不用裸域名),避免与用户主域其它 TXT 记录冲突。 * * @return {Promise} 域名输出对象 + verified(本次是否通过) * + resolved_values(本次解析到的 TXT 值,最多 5 条)。 - * @throws {Error} 未识别到当前仓库时抛出 400;未设置域名时抛出 400;非仓库主体时抛出 403。 + * @throws {Error} 未识别到当前仓库时抛出 400;未设置域名时抛出 400;非仓库主体时抛出 403; + * 待验证域名已被其他仓库用为生效域名时抛出 409。 */ async checkDomain() { const warehouseId = this.getCurrentWarehouseId(); @@ -1015,18 +1542,32 @@ class FrontConfigService extends Service { }, }); - const domain = record ? String(record.get('domain') || '').trim() : ''; + if (!record) { + throw this.createError('请先设置域名', 400); + } + + const pendingDomain = String(record.get('pending_domain') || '').trim(); + + // ===== 路径一:存在待验证域名 → 校验 pending 的 TXT 记录(通过即提升为生效域名) ===== + if (pendingDomain) { + return this.checkPendingDomainRecord(record, pendingDomain, warehouseId); + } + + // ===== 路径二:无待验证域名 → 生效域名的校验口径(升级前行为,兼容历史行) ===== + const domain = String(record.get('domain') || '').trim(); if (!domain) { throw this.createError('请先设置域名', 400); } const domainStatus = Number(record.get('domain_status') || 0); - const currentHost = String(record.get('domain_verify_host') || '').trim(); - const currentToken = String(record.get('domain_verify_token') || '').trim(); - // 兼容迁移回填的历史行:域名线上已生效(直接视为已验证)但从未生成校验记录, - // 无法也无需重新校验;此处直接返回已验证,避免手动点校验把生效中的域名降级为验证失败 - if (domainStatus === DOMAIN_STATUS_VERIFIED && (!currentHost || !currentToken)) { + // 已验证域名一律短路(不论库内有无校验码): + // 1) 兼容迁移回填的历史行:域名线上已生效(直接视为已验证)但从未生成校验记录; + // 2) 已验证域名不需要重复校验;若不短路,用户误点一次「校验」会走真实 DNS 解析, + // 失败即写 domain_status = 2 且 attempts + 1,把已生效域名降级后被 getByDomain 与 + // nginx 闸门断流; + // 3) 短路不写库、不降状态、不加 attempts,返回结构与 getDomain 口径一致。 + if (domainStatus === DOMAIN_STATUS_VERIFIED) { return { ...this.buildDomainOutput(record, warehouseId), verified: true, @@ -1035,11 +1576,11 @@ class FrontConfigService extends Service { } const patch = {}; - let verifyHost = currentHost; - let verifyToken = currentToken; + let verifyHost = String(record.get('domain_verify_host') || '').trim(); + let verifyToken = String(record.get('domain_verify_token') || '').trim(); - // 未验证/验证失败且库内缺少校验码(历史脏数据):补发一份, - // 用户配置 DNS 解析后再次校验即可通过(本次校验仍会因记录未生效而失败) + // 未验证/验证失败(domain_status ∈ {0, 2},已验证行已在上方短路)且库内缺少校验码: + // 补发一份,用户配置 DNS 解析后再次校验即可通过(本次校验仍会因记录未生效而失败) if (!verifyHost || !verifyToken) { const verifyCode = this.buildDomainVerifyCode(domain); verifyHost = verifyCode.host; @@ -1048,9 +1589,9 @@ class FrontConfigService extends Service { patch.domain_verify_token = verifyToken; } - const verifyResult = await this.verifyDomainRecord({ - domain_verify_host: verifyHost, - domain_verify_token: verifyToken, + const verifyResult = await this.verifyDomainRecord(record, { + host: verifyHost, + token: verifyToken, }); if (verifyResult.verified) { @@ -1071,21 +1612,26 @@ class FrontConfigService extends Service { return { ...this.buildDomainOutput(savedRecord, warehouseId), verified: !!verifyResult.verified, - resolved_values: (Array.isArray(verifyResult.values) ? verifyResult.values : []) - .slice(0, DOMAIN_RESOLVED_VALUES_LIMIT) - .map(value => String(value).slice(0, DOMAIN_RESOLVED_VALUE_MAX_LENGTH)), + resolved_values: this.buildResolvedValues(verifyResult.values), }; } /** * 构建域名验证输出对象(getDomain/setDomain/checkDomain 共用)。 * - * 安全口径:domain_status === 1(已验证)时不再回显校验主机名与校验值(令牌已无用途); - * 未验证/验证失败时回显,供用户配置 DNS TXT 解析记录。 + * 返回结构(两阶段切换后扩展,既有字段一律不改名、不删除): + * · 生效域名组:warehouse_id / domain / domain_status / verify_host / verify_value / + * verified_at / attempts / last_error;domain_status = 1(已验证)时 verify_host / + * verify_value 返回空串(校验令牌已无用途,保持既有口径); + * · 待验证域名组(新增):pending_domain / pending_verify_host / pending_verify_value / + * pending_attempts / pending_last_error / pending_created_at / pending_active; + * 无待验证域名时依次返回 '' / '' / '' / 0 / '' / null / false; + * · 公共:cname(CNAME 目标)。 + * 待验证域名的校验码始终回显(pending_domain 非空即有值):该域名尚未生效,用户需要据此配置 TXT。 * * @param {Object|null} record 配置记录实例(可为 null,返回空值默认)。 * @param {number} warehouseId 当前仓库 ID。 - * @return {Object} 域名输出对象(warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error)。 + * @return {Object} 域名输出对象(生效组 + 待验证组 + cname)。 */ buildDomainOutput(record, warehouseId) { const hasRecord = !!(record && typeof record.get === 'function'); @@ -1094,6 +1640,7 @@ class FrontConfigService extends Service { const domain = hasRecord ? String(getValue('domain') || '').trim() : ''; const domainStatus = hasRecord ? Number(getValue('domain_status') || 0) : DOMAIN_STATUS_UNVERIFIED; const exposeVerifyInfo = !!domain && domainStatus !== DOMAIN_STATUS_VERIFIED; + const pendingDomain = hasRecord ? String(getValue('pending_domain') || '').trim() : ''; return { warehouse_id: Number(warehouseId || 0), @@ -1105,9 +1652,29 @@ class FrontConfigService extends Service { verified_at: hasRecord ? (getValue('domain_verified_at') || null) : null, attempts: hasRecord ? Number(getValue('domain_verify_attempts') || 0) : 0, last_error: hasRecord ? String(getValue('domain_last_error') || '') : '', + // 待验证域名组(追加字段,不影响既有字段语义) + pending_domain: pendingDomain, + pending_verify_host: pendingDomain ? String(getValue('pending_verify_host') || '') : '', + pending_verify_value: pendingDomain ? String(getValue('pending_verify_token') || '') : '', + pending_attempts: hasRecord ? Number(getValue('pending_verify_attempts') || 0) : 0, + pending_last_error: hasRecord ? String(getValue('pending_last_error') || '') : '', + pending_created_at: hasRecord ? (getValue('pending_created_at') || null) : null, + pending_active: !!pendingDomain, }; } + /** + * 规范化 checkDomain 回显的解析值(排障用:限量 + 截断,避免响应被超长/超多记录撑爆)。 + * + * @param {*} values 解析到的 TXT 值列表(可为空/非数组)。 + * @return {string[]} 最多 DOMAIN_RESOLVED_VALUES_LIMIT 条、单条 ≤ DOMAIN_RESOLVED_VALUE_MAX_LENGTH 字符。 + */ + buildResolvedValues(values) { + return (Array.isArray(values) ? values : []) + .slice(0, DOMAIN_RESOLVED_VALUES_LIMIT) + .map(value => String(value).slice(0, DOMAIN_RESOLVED_VALUE_MAX_LENGTH)); + } + /** * 域名状态→前端可读文案(用于 can_set_cert_reason,已验证返回空串)。 * @@ -1173,6 +1740,48 @@ class FrontConfigService extends Service { await this.deleteCacheByKey(this.getDomainCacheKey(normalizedDomain)); } + /** + * 批量清理多个域名的公共拉取缓存(去重、忽略空值,单个失败仅记 WARN 不抛出)。 + * + * 顺序说明(重要):域名提升/切换必须先写库、后清缓存,且旧域名与新域名两个 key 都要清—— + * 公共拉取缓存 key 按域名精确匹配(front:config:domain:{domain}),漏清旧域名会让已下线的 + * 旧域名继续对外返回配置,漏清新域名则让新域名继续返回旧配置。 + * + * @param {string[]} domains 待清理域名列表(可含空值/重复项)。 + * @param {string} [logTag] 日志前缀(定位调用方)。 + * @return {Promise} 无返回值(绝不抛出)。 + */ + async clearDomainCaches(domains, logTag = 'FrontConfigService.clearDomainCaches') { + const uniqueDomains = [ ...new Set( + (Array.isArray(domains) ? domains : []) + .map(item => String(item || '').trim()) + .filter(item => !!item) + ) ]; + + await Promise.all(uniqueDomains.map(domain => this.clearDomainCache(domain) + .catch(error => { + this.ctx.logger.warn('[%s] 清理前端配置缓存失败 domain=%s: %s', logTag, domain, error.message); + }))); + } + + /** + * 构建「清空待验证域名」的更新字段(setDomain 取消待切换 与 promotePendingDomain 共用)。 + * + * 每次调用返回新对象,避免调用方误改共享字面量。 + * + * @return {Object} pending 6 列的清空字段(pending_verify_attempts 归 0,其余置 NULL)。 + */ + buildPendingClearPatch() { + return { + pending_domain: null, + pending_verify_host: null, + pending_verify_token: null, + pending_verify_attempts: 0, + pending_last_error: null, + pending_created_at: null, + }; + } + /** * 按域名查询前端配置(公共无鉴权接口业务实现,Redis 缓存 + 查库兜底)。 * @@ -1527,6 +2136,10 @@ class FrontConfigService extends Service { * cert_path/key_path 保存时置空,避免内容已换而路径陈旧,等待定时任务部署后回填真实路径; * 同时重置同步状态;写库成功后清理该域名的公共拉取缓存(先写库后清缓存)。 * + * 两阶段域名切换提示:待验证域名提升(promotePendingDomain)时会清空证书 5 列并重置同步状态, + * 用户必须为新域名重新上传证书;本接口前置闸门(无生效域名/未验证返回 400)与 SAN/CN 覆盖校验 + * 始终以生效域名 domain 为准,存在 pending_domain 不影响本接口受理口径。 + * * @param {Object} [data={}] 请求参数。 * @param {string} data.pem 证书 PEM 文本(必填)。 * @param {string} data.key 私钥 PEM 文本(必填,与证书成对)。 diff --git a/config/config.default.js b/config/config.default.js index 4c62c3b..0169a9d 100644 --- a/config/config.default.js +++ b/config/config.default.js @@ -317,9 +317,26 @@ module.exports = appInfo => { enable: true, // 是否注册域名验证定时任务 interval: '10m', // 扫描间隔 lockTtlSeconds: 600, // Redis 跨进程锁 TTL(略大于 interval) - batchSize: 50, // 单轮最多处理行数 + // 单轮最多处理行数:单行最坏耗时 ≈ (DoH 端点数 3 + 系统 DNS 兜底 1) × timeoutMs(3000ms) = 12s, + // 20 行最坏 ≈ 240s,明显小于 lockTtlSeconds(600s) 与扫描间隔 interval(600s),跨进程锁不会被下一轮抢走 + batchSize: 20, + // DoH 端点列表(多端点按序尝试,任一端点拿到 TXT 值即立即返回,不再询问后续端点): + // 1) https://dns.alidns.com/resolve 阿里公共 DNS 的 JSON 接口,默认主解析器; + // 2) https://223.5.5.5/resolve 阿里公共 DNS 的 IP 直连入口(同一后端,域名侧解析异常时兜底); + // 3) https://doh.pub/dns-query 腾讯 doh.pub,保留但置于最后。 + // 为什么把 doh.pub 放最后:其负缓存(NODATA)可能长时间滞后于权威服务器。 + // 实测案例:主机 wmsv-aa4adaab13.wms.wms.gztbyc.com 的 TXT 记录 ddd9ae51cf95b488db544f23ccd01e7b 真实存在 + // (8.8.8.8 / 223.5.5.5 / nslookup / AliDNS DoH 四方一致),而 doh.pub 返回 Status=0 且 Answer 为空 + // (同一主机 A 查询亦 NODATA,其 SOA 序列号 2026081813 旧于 TXT 查询的 2026082815),重复两次结果一致。 + dohUrls: [ + 'https://dns.alidns.com/resolve', + 'https://223.5.5.5/resolve', + 'https://doh.pub/dns-query', + ], + // 兼容键(历史单端点配置):dohUrls 缺失/非法时 getDomainVerifyConfig() 回退用 [dohUrl];多端点生效后不应再依赖本键 dohUrl: 'https://doh.pub/dns-query', - timeoutMs: 5000, // 单次 DoH 请求超时 + // 单个 DoH 端点、以及系统 DNS 兜底单次查询的超时(毫秒) + timeoutMs: 3000, maxAttempts: 20, // 超过后不再自动重试(仍可手动 checkDomain) }, }; diff --git a/database/migrations/20260924180000-add-pending-domain-to-wms-warehouse-front-config.js b/database/migrations/20260924180000-add-pending-domain-to-wms-warehouse-front-config.js new file mode 100644 index 0000000..b66c587 --- /dev/null +++ b/database/migrations/20260924180000-add-pending-domain-to-wms-warehouse-front-config.js @@ -0,0 +1,220 @@ +'use strict'; + +const TABLE_NAME = 'wms_warehouse_front_config'; +const PENDING_DOMAIN_INDEX_NAME = 'idx_pending_domain'; +const RETIRED_DOMAIN_INDEX_NAME = 'idx_retired_domain'; + +/** + * Migration: 仓库前端配置表新增「两阶段域名切换」相关列与索引。 + * + * 背景(为什么需要这次改造): + * 原实现 frontConfig.setDomain 是「设置即生效」——一次调用就把 domain 改成新域名、 + * domain_status 归零并清空证书。后果是旧域名立刻被 frontConfig.getByDomain 判为 + * 「域名未配置」(404),而 nginx 侧旧域名 server 块还在,出现「页面能打开但拉不到配置」 + * 的中间态;用户改错域名也无法回滚。 + * + * 方案(方案 B·两阶段切换,待验证域名与生效域名分离): + * 1. 第一阶段(frontConfig.setDomain):只把新域名登记到 pending_domain 并下发 TXT 校验码, + * 生效域名 domain、domain_status、domain_verified_at、证书与同步状态一律不动; + * 2. 第二阶段(frontConfig.checkDomain 手动触发 / app/schedule/domain_verify_scan.js 定时扫描): + * TXT 校验通过后由 frontConfig.promotePendingDomain 一次性把 pending_domain 提升为 + * domain(domain_status=1),同时把旧域名写入 retired_domain 下线队列、清空证书并重置同步状态。 + * 旧域名的 nginx 配置与证书文件由外部证书脚本按 retired_domain 删除后置 NULL(本次不改脚本)。 + * + * 新增列(全部可空或带默认值,无需数据回填): + * - pending_domain : 待验证域名(STRING(100),验证通过后才提升为生效域名 domain); + * - pending_verify_host : 待验证域名的 TXT 记录主机名(STRING(255),wmsv-<随机码>.<待验证域名>); + * - pending_verify_token : 待验证域名的 TXT 记录值(STRING(64),32 位 hex); + * - pending_verify_attempts: 待验证域名校验尝试次数(INTEGER,NOT NULL,默认 0); + * - pending_last_error : 待验证域名最近一次失败原因(STRING(500),脱敏截断); + * - pending_created_at : 发起域名切换的时间(DATE); + * - retired_domain : 待下线旧域名(STRING(100),域名提升时写入,外部脚本删除其 + * nginx 配置与证书文件后置 NULL); + * - retired_at : 旧域名进入下线队列的时间(DATE)。 + * 新增索引: + * - idx_pending_domain:域名验证定时任务按 pending_domain 扫描待验证行的查询索引(普通索引); + * - idx_retired_domain:外部证书脚本按 retired_domain 扫描待下线旧域名的查询索引(普通索引)。 + * + * 为什么无需回填: + * 8 个新列要么可空、要么带默认值 0,存量行的 pending_* 一律为 NULL / 0 → 语义就是 + * 「没有待验证域名」,生效域名 domain / domain_status / 证书 / 同步状态全部保持原值, + * 升级瞬间行为与升级前一致(唯一变化是下次 setDomain 会走两阶段,属预期变更)。 + * 注意:pending_domain 只有普通索引(非唯一),并发提交同一域名理论上仍可能同时写入两行, + * 最终由 domain 上的唯一索引在「提升」阶段兜底(提升冲突会保留待验证状态并记入错误)。 + * + * Idempotent: 列/索引已存在时跳过;down 先删索引、再按倒序删列(均判存在后执行)。 + */ + +/** + * 判断表是否存在。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @param {string} tableName 表名。 + * @return {Promise} 存在返回 true。 + */ +async function tableExists(queryInterface, tableName) { + const tables = await queryInterface.showAllTables(); + return tables.some(t => (typeof t === 'string' ? t : (t.tableName || t.name)) === tableName); +} + +/** + * 判断索引是否存在。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @param {string} tableName 表名。 + * @param {string} indexName 索引名。 + * @return {Promise} 存在返回 true。 + */ +async function indexExists(queryInterface, tableName, indexName) { + const indexes = await queryInterface.showIndex(tableName); + return (indexes || []).some(item => (typeof item === 'string' ? item : item.name) === indexName); +} +module.exports = { + /** + * 执行正向迁移:新增两阶段域名切换相关列与索引(幂等,无数据回填)。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @param {import('sequelize')} Sequelize Sequelize 实例。 + * @return {Promise} 无返回值。 + */ + async up(queryInterface, Sequelize) { + if (!(await tableExists(queryInterface, TABLE_NAME))) { + return; + } + + const columns = await queryInterface.describeTable(TABLE_NAME); + + // 列定义表:after 显式指定列序,pending 组紧随域名验证组,retired 组接在 pending 组之后 + const columnDefs = [ + { + name: 'pending_domain', + after: 'domain_last_error', + definition: { + type: Sequelize.STRING(100), + allowNull: true, + comment: '待验证域名:setDomain 只登记到本列,TXT 校验通过后才提升为生效域名 domain', + }, + }, + { + name: 'pending_verify_host', + after: 'pending_domain', + definition: { + type: Sequelize.STRING(255), + allowNull: true, + comment: '待验证域名的 TXT 记录主机名(wmsv-<随机码>.<待验证域名>)', + }, + }, + { + name: 'pending_verify_token', + after: 'pending_verify_host', + definition: { + type: Sequelize.STRING(64), + allowNull: true, + comment: '待验证域名的 TXT 记录值(32 位 hex)', + }, + }, + { + name: 'pending_verify_attempts', + after: 'pending_verify_token', + definition: { + type: Sequelize.INTEGER(11), + allowNull: false, + defaultValue: 0, + comment: '待验证域名校验尝试次数', + }, + }, + { + name: 'pending_last_error', + after: 'pending_verify_attempts', + definition: { + type: Sequelize.STRING(500), + allowNull: true, + comment: '待验证域名最近一次失败原因', + }, + }, + { + name: 'pending_created_at', + after: 'pending_last_error', + definition: { + type: Sequelize.DATE, + allowNull: true, + comment: '发起域名切换的时间', + }, + }, + { + name: 'retired_domain', + after: 'pending_created_at', + definition: { + type: Sequelize.STRING(100), + allowNull: true, + comment: '待下线旧域名:域名提升时写入,外部证书脚本删除其 nginx 配置与证书文件后置 NULL', + }, + }, + { + name: 'retired_at', + after: 'retired_domain', + definition: { + type: Sequelize.DATE, + allowNull: true, + comment: '旧域名进入下线队列的时间', + }, + }, + ]; + + for (const item of columnDefs) { + if (!columns[item.name]) { + await queryInterface.addColumn(TABLE_NAME, item.name, { + ...item.definition, + after: item.after, + }); + } + } + + if (!(await indexExists(queryInterface, TABLE_NAME, PENDING_DOMAIN_INDEX_NAME))) { + await queryInterface.addIndex(TABLE_NAME, [ 'pending_domain' ], { + name: PENDING_DOMAIN_INDEX_NAME, + }); + } + + if (!(await indexExists(queryInterface, TABLE_NAME, RETIRED_DOMAIN_INDEX_NAME))) { + await queryInterface.addIndex(TABLE_NAME, [ 'retired_domain' ], { + name: RETIRED_DOMAIN_INDEX_NAME, + }); + } + }, + /** + * 回滚迁移:删除两阶段域名切换相关索引与列(幂等)。 + * + * 注意:回滚会一并丢弃待验证域名与下线队列(pending_* / retired_*), + * 但不会改动生效域名 domain、domain_status、证书与同步状态,因此不影响线上已生效域名。 + * 回滚后代码若仍为两阶段版本,setDomain / checkDomain 会因缺少 pending_* 列而报错, + * 需与代码版本一并回退。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @return {Promise} 无返回值。 + */ + async down(queryInterface) { + if (!(await tableExists(queryInterface, TABLE_NAME))) { + return; + } + + for (const indexName of [ RETIRED_DOMAIN_INDEX_NAME, PENDING_DOMAIN_INDEX_NAME ]) { + if (await indexExists(queryInterface, TABLE_NAME, indexName)) { + await queryInterface.removeIndex(TABLE_NAME, indexName); + } + } + + const columns = await queryInterface.describeTable(TABLE_NAME); + // 倒序删除(与 up 的列序相反):先删 retired 组,再删 pending 组 + for (const columnName of [ + 'retired_at', + 'retired_domain', + 'pending_created_at', + 'pending_last_error', + 'pending_verify_attempts', + 'pending_verify_token', + 'pending_verify_host', + 'pending_domain', + ]) { + if (columns[columnName]) { + await queryInterface.removeColumn(TABLE_NAME, columnName); + } + } + }, +}; diff --git a/methods/changes/system.json b/methods/changes/system.json index 2082a12..d3d3ad1 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -20,6 +20,98 @@ "发布顺序:迁移(20260925100000-create-wms-client-error-log)先于代码发布;迁移为纯建表、无回填,先迁移无风险。" ] }, + { + "version": "2026.09.24-front-config-domain-two-phase-switch", + "date": "2026-09-24", + "type": "updated", + "summary": "域名切换改为两阶段(待验证域名与生效域名分离)—— frontConfig.setDomain 只登记待验证域名 pending_domain 并下发 TXT 校验码,TXT 校验通过后才由提升逻辑切换为生效域名并清空证书;新增旧域名下线记录 retired_domain;解决「改域名瞬间旧域名公共接口 404」的中间态问题。", + "methods": [ + "frontConfig.setDomain", + "frontConfig.getDomain", + "frontConfig.checkDomain", + "frontConfig.getByDomain", + "frontConfig.saveCert", + "frontConfig.getCert" + ], + "notes": [ + "变更原因(旧口径问题,P0 中间态):旧 setDomain 是「设置即生效」—— 一次调用即改写生效域名 domain、domain_status 归零并清空证书,frontConfig.getByDomain 的放行闸门(domain + domain_status=1)对旧域名立即失效 → 旧域名公共接口立刻 404,而 nginx 侧旧域名 server 块仍在,出现「页面能打开但拉不到配置」的中间态;且用户改错域名无法回滚(只能再改一次并重新举证)。本轮以「待验证域名与生效域名分离」彻底消除该中间态。", + "数据层:wms_warehouse_front_config 新增 8 列 —— pending_domain(STRING(100))、pending_verify_host(STRING(255))、pending_verify_token(STRING(64))、pending_verify_attempts(INTEGER NOT NULL 默认 0)、pending_last_error(STRING(500))、pending_created_at(DATE)、retired_domain(STRING(100),待下线旧域名)、retired_at(DATE);新增普通索引 idx_pending_domain(域名验证定时任务扫描待验证行)与 idx_retired_domain(外部脚本扫描待下线旧域名)。迁移文件 database/migrations/20260924180000-add-pending-domain-to-wms-warehouse-front-config.js(up/down 幂等)。纯追加且可空/带默认值,「无需任何数据回填」:存量行的 pending_* 为 NULL/0,语义即「没有待验证域名」,升级瞬间行为与升级前一致。", + "四分支决策表(frontConfig.setDomain,域名比较忽略大小写):A 入参 == 生效域名且无 pending → 幂等短路(不写库;仅大小写不一致时改写 domain 字面值并清新旧两个字面值缓存);B 入参 == 生效域名且有 pending → 取消待切换(只清空 pending 6 列,生效域名/证书/同步状态一律不动);C 入参 == 现有 pending_domain → 校验码齐全则幂等短路,缺码(脏数据)则只补发 pending 校验码并清 pending_verify_attempts / pending_last_error;D 其它(含首次设置)→ 查重通过后只写 pending_domain + 新校验码,domain / domain_status / domain_verified_at / domain_verify_* / 证书 5 列 / 同步 4 列一律不动,也不清任何公共缓存。查重由「其他仓库 domain 命中」扩展为「其他仓库 domain 或 pending_domain 命中」→ 409「域名 X 已被其他仓库使用」。", + "提升逻辑(frontConfig.promotePendingDomain,checkDomain 路径一与定时扫描共用):TXT 校验通过后一次 update 提交 —— domain = pending_domain、domain_status=1、domain_verified_at=now、domain_verify_host/token/attempts 由 pending_* 平移、domain_last_error=NULL;旧域名(生效域名非空且与待验证域名不同)写入 retired_domain + retired_at;清空 pending 6 列(pending_verify_attempts 归 0);清空证书 5 列(cert_pem / cert_key / cert_path / key_path / cert_expire_at);重置同步 4 列(sync_status=0、sync_attempts=0、last_sync_error=NULL、last_synced_at=NULL);由调用方清理旧域名与新域名两个公共拉取缓存(clearDomainCaches,先写库后清缓存,清失败仅记 WARN)。update 的 where 带 id + pending_domain 防并发重复提升。", + "响应契约变化(纯追加、旧字段名与语义不变,前端可先发版兼容):frontConfig.getDomain 由 9 字段扩为 16 字段(追加 pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active);frontConfig.setDomain 响应同步由 9 字段扩为 16 字段;frontConfig.checkDomain 响应由 11 字段扩为 18 字段(getDomain 的 16 字段 + verified + resolved_values),并新增 409 错误码(提升时 domain 唯一索引冲突)。生效域名组字段名与语义一字未改:domain_status=1 时 verify_host/verify_value 仍返回空字符串;待验证域名在 pending_domain 非空时始终回显校验码(pending_verify_host / pending_verify_value)。", + "旧域名下线由外部脚本执行(retired_domain 契约):script/warehouse-cert-sync.cjs 消费 retired_domain —— 删除该域名的 nginx server 块与证书文件后把 retired_domain 置 NULL,并有目录孤儿兜底清理;应用侧(service / schedule)不碰任何 nginx 文件。实测核对:当前工作区的 script/warehouse-cert-sync.cjs 尚未引用 retired_domain(全文检索 0 命中),该下线动作需脚本侧补齐后本闭环才完整;retired_domain 只保留最近一个旧域名,多次连续切换会丢中间域名(依赖脚本孤儿兜底清理)。", + "发布顺序强约束(必须先迁移、再发代码):新代码的 SELECT 走 Sequelize 全字段,若生产库尚未执行迁移(pending_* / retired_* 共 8 列不存在),frontConfig.setDomain / getDomain / checkDomain 乃至 frontConfig.getByDomain 都会报 ER_BAD_FIELD_ERROR;定时扫描 verifyPendingDomains 会 fail-soft 返回零统计并记 WARN(含「迁移尚未执行」提示)。迁移为纯追加可空,先在生产执行迁移无风险。升级顺序:迁移 → 发布代码 → 前端发版。", + "前端必须改造要点:①setDomain 提交成功后的 TXT 指引改读 pending_verify_host / pending_verify_value(不能再用 verify_host / verify_value);②首次设置时 domain 为空字符串是正常态(待验证域名在 pending_domain);③新增「取消待切换」交互 = 用当前生效域名再调一次 setDomain(走分支 B);④「切换中」状态用 pending_active / pending_attempts / pending_last_error / pending_created_at 展示;⑤提升完成后提示「切换完成,请重新上传证书」(提升会清空证书并重置同步状态);⑥明确「切换期间上传的证书属于旧域名」,提升后失效。", + "文档变更范围与版本号:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)。", + "历史记录说明(不回改):既有变更记录中关于「setDomain 未变化即幂等短路、缺码补发校验码」「domain_status=1 一律短路不降级」等描述属当时真实口径,作为历史事实不回改,由本条新记录承接并覆盖(现口径为四分支 A/B/C/D,原「缺码补发·已验证」分支已不存在)。", + "维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)。", + "未处理遗留(建议单独修正):app/schedule/domain_verify_scan.js 头注释仍描述升级前口径(扫描 domain_verify_* 行并回写 domain_status / domain_verified_at / domain_verify_attempts / domain_last_error),与两阶段实现(只扫 pending 组、回写 pending_* 并在通过时提升)不符;app/service/systemMethods/frontConfig.js 的部分 JSDoc 仍写「生效域名组 9 字段」。两者均位于 app/**,本次为文档任务、不改代码,仅报告。" + ], + "module": "frontConfig" + }, + { + "version": "2026.09.24-front-config-doh-multi-endpoint", + "date": "2026-09-24", + "type": "updated", + "summary": "修复 DNS 解析误判 —— DoH 改为多端点顺序尝试(dohUrls),单端点「无记录」不再直接定论;仅在所有解析路径都失败时才判解析错误。", + "methods": [ + "frontConfig.checkDomain" + ], + "notes": [ + "问题与实测案例:仓库 wmsv-aa4adaab13.wms.wms.gztbyc.com 的 TXT 记录真实存在(值 ddd9ae51cf95b488db544f23ccd01e7b,8.8.8.8 / 223.5.5.5 / AliDNS DoH / nslookup 四方一致),但默认 DoH 端点 doh.pub 返回 Status=0 且无 Answer(陈旧负缓存,其返回的 SOA 序列号偏旧);旧实现把单端点的 NODATA 直接定论为「未解析到 TXT 记录」→ domain_status=2 → 被 frontConfig.getByDomain 与 nginx 放行闸门断流(真实记录存在却被判为未解析到)。", + "新口径:DoH 改为多端点顺序尝试(dohUrls,默认 alidns → 223.5.5.5 → doh.pub)+ 单端点结果三分类(values 立即返回 / empty 继续下一个端点 / error 继续下一个端点);empty(NODATA 或 NXDOMAIN)与 error 都不再直接定论,全部端点未取到值后降级系统 DNS;只要有一个端点或系统 DNS 明确答复「无该记录」就返回 [] (未解析到记录,不抛错),仅「所有 DoH 端点都是 error 且系统 DNS 也失败」才抛 500「DNS 解析失败:…」。", + "配置兼容规则(dohUrl → dohUrls):config.frontConfig.domainVerify.dohUrls 为有效非空字符串数组时优先使用(顺序不变);否则回退历史单端点键 dohUrl(等价 [dohUrl]);两者均无效时回退内置默认数组 DEFAULT_DOH_URLS。旧键 dohUrl 保留读兼容,不作废。", + "配置默认值变更:timeoutMs 5000 → 3000(单端点超时,系统 DNS 兜底同样显式限时 3s)、batchSize 50 → 20;配套核算 batchSize ≤ lockTtlSeconds×0.5 ÷ ((N+1)×timeoutMs/1000)(N 为端点数),3 端点场景单行最坏 12s、20 行 240s < lockTtlSeconds 600s。", + "返回值契约:内部 resolveTxtValues 新增 endpoint 字段(追加不破坏,仍返回 { values, source, endpoint });verifyDomainRecord 契约不变({ verified, values, source, error },永不抛异常);新增内部 helper resolveDohUrls、queryDohEndpoint。", + "可观测性:每个端点的 empty / error 均打日志(含 host + endpoint + 脱敏原因),可区分「记录不存在」与「链路不可用」。", + "前端无感:不影响任何 method 的入参 / 响应结构,仅影响 frontConfig.checkDomain 与定时任务 domain_verify_scan 的判定正确性。", + "文档变更范围:仅更新 frontConfig.checkDomain(description + notes),frontConfig 分组仍 8 条、各 response 计数不变;新增 1 条变更记录;根版本 0.3.187 → 0.3.188(updatedAt 保持 2026-09-24)。", + "历史记录说明:既有变更记录中关于「Status=3 或无 Answer 视为未解析到记录、不重复走系统 DNS」的描述属于当时的真实口径,作为历史事实不回改,由本条新记录承接并覆盖。" + ], + "module": "frontConfig" + }, + { + "version": "2026.09.24-front-config-domain-verified-shortcircuit", + "date": "2026-09-24", + "type": "updated", + "summary": "修复「domain_status=1 的已验证域名可能被误降级」问题:frontConfig.setDomain 删除「已验证缺码补发」分支(已验证域名一律幂等短路、不补码、不写库);frontConfig.checkDomain 对 domain_status=1 一律短路返回 verified=true 且不写库、不改状态、不增加验证次数。", + "methods": [ + "frontConfig.setDomain", + "frontConfig.checkDomain" + ], + "notes": [ + "变更原因(P0 回归修复):上一轮把「domain_status=1 且缺校验码」的已验证域名也做成缺码补发,使 frontConfig.checkDomain 的「历史回填行短路」条件不再成立——用户手动点一次「校验」即走真实 DNS 解析,失败便把 domain_status 由 1 写成 2(domain_verify_attempts+1、domain_last_error 有值),随后被 frontConfig.getByDomain 与 nginx 放行闸门断流;且 status=1 时 getDomain 不回显校验码,用户无从发现补发的码。本轮改为「已验证域名一律不补码、一律短路」。", + "问题现象与复现路径:库内 domain_status=1 且 domain_verify_host/domain_verify_token 为空(迁移回填常态)→ 前端再次提交同一域名触发 frontConfig.setDomain(旧口径走 C 分支补码入库)→ frontConfig.getDomain 因 domain_status=1 仍返回空 verify_host/verify_value(补发的码任何接口都读不到)→ 用户点「校验」触发 frontConfig.checkDomain,此时短路条件「无校验码」已不成立 → 走真实 DNS 解析 → 未配置对应 TXT 记录解析失败 → domain_status 由 1 写成 2、attempts+1、last_error 有值 → frontConfig.getByDomain 与 nginx 闸门断流(线上已生效域名被降级)。", + "修复后口径(实现 app/service/systems/frontConfig.js):frontConfig.setDomain 删除原 C「缺码补发·已验证」分支,五分支收敛为 A/B/D/E/F(C 并入 A)——A 的判定为「域名忽略大小写相同 且(校验码齐全且字面值一致 或 domain_status=1)」,命中即幂等短路:不写库、不补码、不刷新校验码、不改验证状态与尝试次数、不清证书、不重置同步状态、不清缓存;B 大小写规范化仅改 domain 字面值(status=1 且缺码同样不补码);D 缺码补发仅限 domain_status∈{0,2};E 域名变更与 F 首次设置行为不变。三条「未变化」分支(A/B/D)均不写入 domain_verified_at。", + "frontConfig.checkDomain 短路口径放宽:由「domain_status=1 且缺校验码」改为「domain_status=1」(不论库内有无校验码)一律短路,返回 verified=true、resolved_values=[],不写库、不改状态、不增加 attempts;已验证域名不再重复校验,误点「校验」不会把生效中的域名降级。", + "行为影响(已知取舍):已验证(domain_status=1)域名自此无法通过 frontConfig.checkDomain 重新验证;如需该能力需另开接口(本次未做)。如需重新验证,应先通过 frontConfig.setDomain 变更域名(生成新校验码并回到「未验证」)后再校验。", + "前端约束:不得依赖「重复调用 frontConfig.setDomain 换新校验码」——域名未变化时一律幂等短路,不会下发新码;当前也没有「更换校验码」的独立接口。", + "文档变更范围:methods/system.json 更新 frontConfig.setDomain、frontConfig.checkDomain 的 description 与 notes,并顺带修正 frontConfig.getInfo(response.domain 描述)与 frontConfig.saveInfo(description)中「domain 只能通过 frontConfig.saveCert 变更」的陈旧表述(实际已收敛到 frontConfig.setDomain);4 条 method 的 params/response/errors/headers 均未变动,frontConfig 分组仍为 8 条;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.186 → 0.3.187,updatedAt 保持 2026-09-24。", + "验证与实测:测试链路已确认「status=1 缺码 → setDomain 不再补码、不写库」「status=1 调 checkDomain 一律短路、不写库、不降状态、attempts 不变」「A/B/D/E/F 五分支行为与文档一致」;文档侧经 npm run doc:api:update --dry-run 预检,并以写入前备份做最小 diff 审计(除版本行、4 条 method、1 条 change 外无其它条目被动)。", + "维护源口径冲突(仅记录,未处理):与前两轮一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库。" + ], + "module": "frontConfig" + }, + { + "version": "2026.09.24-front-config-setDomain-idempotent", + "date": "2026-09-24", + "type": "updated", + "summary": "frontConfig.setDomain 语义收敛 —— 域名未变化时幂等短路,不再重新生成 DNS TXT 校验码、不再重置验证进度;仅「库内缺少校验码」时补发(已验证域名不降级),仅「库内域名大小写不同」时做小写规范化;域名变更与首次设置行为不变。", + "methods": [ + "frontConfig.setDomain" + ], + "notes": [ + "变更原因:旧口径下「同一域名未验证/验证失败则重发新校验码并清零 attempts/last_error」,导致用户每次重复提交同一域名都会作废已配置好的 TXT 记录、并清空验证进度(attempts 归零、失败原因丢失),属无谓的进度回退;本轮以「域名是否变化」为第一决策点做幂等收敛", + "五分支口径(实现 app/service/systems/frontConfig.js setDomain):A 完全未变化(忽略大小写相同 + 库内已有校验码 + 字面值一致)→ 幂等短路,不写库、不刷新校验码、不改验证状态与尝试次数、不清证书、不重置同步状态、不清缓存;B 大小写规范化(忽略大小写相同但库内字面值不同,如库内 Shop.com、入参 shop.com)→ 仅把 domain 规范化为小写并清理新旧两个字面值的公共缓存,校验码与验证状态不变;C 缺码补发·已验证(domain_status=1 但 host/token 为空)→ 仅补发校验码,domain_status/domain_verified_at/attempts 保持原值不降级;D 缺码补发·未验证或失败(domain_status∈{0,2} 且缺码)→ 补发校验码 + domain_status=0 + attempts=0 + 清 last_error;E 域名变更(忽略大小写后不同)→ 行为不变:查重 409、生成新校验码、domain_status=0、attempts=0、清空证书(cert_pem/cert_key/cert_path/key_path/cert_expire_at)+ 重置同步状态、清理新旧两个 domain 缓存;F 首次设置(无记录)→ 行为不变:先查重 409,其余同 E", + "未变化短路(A/B/C/D)不再写入 domain_verified_at(该字段现在只在域名变更/首次设置分支被置 null),也不再调用 assertDomainUnique 查重;变更/首次设置(E/F)查重逻辑与 409 文案保持不变", + "行为影响提示:domain_status=2(验证失败)的行若 domain_verify_attempts 已达 config.frontConfig.domainVerify.maxAttempts(默认 20),app/schedule/domain_verify_scan.js 不会再自动拾起(计入 skipped),恢复路径为手动调用 frontConfig.checkDomain(checkDomain 无 maxAttempts 门控);且当前没有「更换校验码」的接口,如需该能力需另开接口", + "前端不得再依赖「重复调用 setDomain 换新校验码」这一行为;需要新校验码的场景只有库内缺码(C/D 自动补发),其余重复提交均按幂等短路处理", + "文档变更范围:methods/system.json 仅更新 frontConfig.setDomain 一条(description 与 notes 重写,params/response/errors/headers 未变,frontConfig 分组仍 8 条),未使用 deleteMethods、未整条覆盖其它条目;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.185 → 0.3.186,updatedAt 保持 2026-09-24", + "未处理遗留(仍建议下一批单独修正):frontConfig.getInfo 的 response.domain 描述与 frontConfig.saveInfo 的 description 仍写「domain 只能通过 frontConfig.saveCert 变更」,实际已收敛到 frontConfig.setDomain;本条 spec.methods 只放 setDomain,避免整条覆盖造成语义漂移", + "维护源口径冲突(仅记录,未处理):与上一轮一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库" + ], + "module": "frontConfig" + }, { "version": "2026.09.24-return-unpack-notify-by-source", "date": "2026-09-24", diff --git a/methods/system.json b/methods/system.json index 9feaeba..1f4d18b 100644 --- a/methods/system.json +++ b/methods/system.json @@ -47491,7 +47491,7 @@ "list": [ { "method": "frontConfig.getByDomain", - "description": "按域名拉取仓库前端公开配置(公共无鉴权接口:免登录、免鉴权、免权限,保留系统日志)。仅放行已验证域名:查库条件为 domain + domain_status=1,未验证(0)/验证失败(2)的域名一律按未配置返回 404「域名未配置」(文案与响应结构未变,仅命中条件收紧);迁移尚未执行(domain_status 列不存在)时降级为仅按 domain 查询并 WARN 一次,保持迁移前行为,迁移完成并重启实例后闸门才真正生效。响应仅含公开字段 domain/title/logo_url/login_bg_url/favicon_url/theme,绝不返回 cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段。Redis 缓存 key front:config:domain:{domain}:命中配置缓存 TTL 600s;未登记域名写 configured=false 空缓存 60s 防穿透并返回 404;保存配置时自动失效新旧域名缓存;Redis 异常降级查库。", + "description": "按域名拉取仓库前端公开配置(公共无鉴权接口:免登录、免鉴权、免权限,保留系统日志)。放行闸门仍只认「生效域名」:查库条件为 domain + domain_status=1,未验证(0)/验证失败(2)的域名一律按未配置返回 404「域名未配置」(本次实现未变,仅补充两阶段语义说明);迁移尚未执行(domain_status 列不存在)时降级为仅按 domain 查询并 WARN 一次,保持迁移前行为。两阶段域名切换语义:切换验证期间生效域名仍为旧域名,本接口继续对旧域名正常放行、对新登记的待验证域名按未配置返回 404 —— 因此不会出现「改域名瞬间旧域名公共接口 404、页面能打开但拉不到配置」的中间态;只有 TXT 校验通过、待验证域名被提升为生效域名后,才改为对新域名放行、旧域名返回 404(旧域名 nginx 配置随后由外部脚本按 retired_domain 删除彻底下线)。响应仅含公开字段 domain/title/logo_url/login_bg_url/favicon_url/theme,绝不返回 cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段。Redis 缓存 key front:config:domain:{domain}:命中配置缓存 TTL 600s;未登记域名写 configured=false 空缓存 60s 防穿透并返回 404;域名提升/保存配置时自动失效新旧域名缓存;Redis 异常降级查库。", "isNeedAuth": false, "isNeedLogin": false, "headers": [], @@ -47559,6 +47559,16 @@ "code": "500", "message": "WarehouseFrontConfig model 不可用/获取前端配置失败" } + ], + "notes": [ + "代码位置:出口 app/service/systemMethods/frontConfig.js 的 getByDomain,实现 app/service/systems/frontConfig.js 的 getByDomain(查库走 findVerifiedDomainRecord,缓存走 getDomainCacheKey / clearDomainCaches)", + "放行闸门(本轮未改实现,仅补语义说明):查库条件仍为 domain + domain_status=1,只看生效域名 domain,不看 pending_domain", + "两阶段切换语义:切换验证期间旧域名(生效域名)继续放行、新域名(待验证域名)返回 404「域名未配置」;提升完成后新域名放行、旧域名 404,旧域名 nginx 配置由外部脚本按 retired_domain 删除后彻底下线 —— 因此不会出现「改域名瞬间旧域名公共接口 404」的中间态", + "缓存:域名切换/提升写库成功后由 clearDomainCaches 清理「旧域名 + 新域名」两个 key(front:config:domain:{domain}),先写库后清缓存;Redis 异常降级查库", + "安全红线不变:只返回 domain/title/logo_url/login_bg_url/favicon_url/theme 公开字段,绝不返回证书/私钥与证书路径、同步状态等内部字段", + "迁移兼容提示:domain_status 列不存在(迁移未执行)时降级为仅按 domain 查询并 WARN 一次;但两阶段版本代码要求 pending_* / retired_* 共 8 列已存在,生产必须先执行迁移 20260924180000-add-pending-domain-to-wms-warehouse-front-config 再发布代码,否则本接口的 Sequelize 全字段查询会报 ER_BAD_FIELD_ERROR", + "文档变更范围:本次仅更新本条的 description + notes(params / response / errors / headers 均未变动,response 仍为 6 个公开字段);frontConfig 分组仍 8 条;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)", + "维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)" ] }, { @@ -47586,7 +47596,7 @@ "name": "domain", "type": "string", "required": true, - "description": "仓库自持域名(未配置为空字符串;只能通过 frontConfig.saveCert 变更)" + "description": "仓库自持域名(未配置为空字符串;变更统一走 frontConfig.setDomain)" }, { "name": "title", @@ -47758,12 +47768,15 @@ "响应契约变更(10 → 13 字段):末位追加 can_set_cert(boolean)、can_set_cert_reason(string)、domain_status(number);前 10 字段口径与含义不变", "can_set_cert_reason 文案与前端提示直接对应:可上传为空字符串,无域名「请先设置域名」,domain_status=0「域名待验证」,domain_status=2「域名验证失败」", "私钥原文回显口径与旧 setting.warehouse.getFrontConfig 一致(沿用 cert_pem/cert_key 原文回显),但旧方法名与旧分组条目已删除", - "本接口不返回 cert_path/key_path(保存时已置 null,等待外部 crontab 脚本 script/warehouse-cert-sync.cjs 部署后回填)" + "本接口不返回 cert_path/key_path(保存时已置 null,等待外部 crontab 脚本 script/warehouse-cert-sync.cjs 部署后回填)", + "两阶段切换提示(本轮,实现与响应字段均未变):域名提升时会清空证书并重置同步状态,提升后本接口回显的证书字段为空、can_set_cert 仍按生效域名判定(domain 非空且 domain_status=1),用户需重新上传证书;切换中的待验证域名 pending_domain 不参与 can_set_cert 判定", + "文档变更范围:本次仅追加本条的 notes(description / params / response / errors / headers 均未变动,response 仍为 13 字段);frontConfig 分组仍 8 条;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)", + "维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)" ] }, { "method": "frontConfig.saveInfo", - "description": "保存当前仓库前端独立部署品牌配置(upsert 一仓一行,部分更新;需登录、免权限、免鉴权,仅仓库主体可调用)。仅受理 title/logo_url/favicon_url/login_bg_url/theme,其余字段一律忽略:domain 与证书相关字段(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at)由方法层白名单静默过滤,前端传值不报错也不生效,domain 变更必须走 frontConfig.saveCert(重新校验证书)。保存即视为一次配置变更:同步状态重置为待同步(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at);写库成功后清理当前 domain 的公共拉取缓存(先写库后清缓存,清缓存失败仅记日志不影响保存结果)。响应为保存后的品牌信息(8 字段,不含证书/私钥)。", + "description": "保存当前仓库前端独立部署品牌配置(upsert 一仓一行,部分更新;需登录、免权限、免鉴权,仅仓库主体可调用)。仅受理 title/logo_url/favicon_url/login_bg_url/theme,其余字段一律忽略:domain 与证书相关字段(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at)由方法层白名单静默过滤,前端传值不报错也不生效,domain 变更统一走 frontConfig.setDomain(域名验证通过后方可上传证书)。保存即视为一次配置变更:同步状态重置为待同步(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at);写库成功后清理当前 domain 的公共拉取缓存(先写库后清缓存,清缓存失败仅记日志不影响保存结果)。响应为保存后的品牌信息(8 字段,不含证书/私钥)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -47899,7 +47912,7 @@ }, { "method": "frontConfig.saveCert", - "description": "上传当前仓库前端独立部署证书(证书/私钥成对;需登录、免权限、免鉴权,仅仓库主体可调用)。域名不再作为入参:一律取库内已设置的 domain,且新增前置闸门——无域名返回 400「请先设置并验证域名」,domain_status !== 1 返回 400「域名未通过验证,暂时无法上传证书」(前端若仍传 domain 会被忽略,不报错也不生效)。通过闸门后校验链:证书可解析 → 未生效拒绝 → 已过期拒绝 → 私钥与证书 SPKI 配对 → 证书 SAN/CN 覆盖库内 domain(支持 *.example.com 通配,通配仅覆盖恰好一级标签:*.a.com 覆盖 b.a.com,不覆盖 x.y.a.com,后者同样按「证书不合法」拒绝)。校验链任一失败统一返回 400「证书不合法」,不吐露细节。通过后:cert_expire_at 以证书 validTo 权威写入(忽略前端传值);证书/私钥内容直接写入 cert_pem/cert_key 列,cert_path/key_path 置 null(等待外部 crontab 脚本 script/warehouse-cert-sync.cjs 部署后回填真实路径);同步状态重置为待同步;写库成功后清理当前域名的公共拉取缓存(域名已不能在本接口变更,故只需清一个 key)。响应为保存后的证书输出(13 字段,与 frontConfig.getCert 一致:warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at/can_set_cert/can_set_cert_reason/domain_status),不含 cert_path/key_path 路径字段。", + "description": "上传当前仓库前端独立部署证书(证书/私钥成对;需登录、免权限、免鉴权,仅仓库主体可调用)。域名不再作为入参:一律取库内已设置的 domain,且新增前置闸门——无域名返回 400「请先设置并验证域名」,domain_status !== 1 返回 400「域名未通过验证,暂时无法上传证书」(前端若仍传 domain 会被忽略,不报错也不生效)。通过闸门后校验链:证书可解析 → 未生效拒绝 → 已过期拒绝 → 私钥与证书 SPKI 配对 → 证书 SAN/CN 覆盖库内 domain(支持 *.example.com 通配,通配仅覆盖恰好一级标签:*.a.com 覆盖 b.a.com,不覆盖 x.y.a.com,后者同样按「证书不合法」拒绝)。校验链任一失败统一返回 400「证书不合法」,不吐露细节。通过后:cert_expire_at 以证书 validTo 权威写入(忽略前端传值);证书/私钥内容直接写入 cert_pem/cert_key 列,cert_path/key_path 置 null(等待外部 crontab 脚本 script/warehouse-cert-sync.cjs 部署后回填真实路径);同步状态重置为待同步;写库成功后清理当前域名的公共拉取缓存(域名已不能在本接口变更,故只需清一个 key)。响应为保存后的证书输出(13 字段,与 frontConfig.getCert 一致:warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at/can_set_cert/can_set_cert_reason/domain_status),不含 cert_path/key_path 路径字段。注意:域名提升(两阶段切换的第二阶段)会清空证书 5 列并重置同步状态,域名切换完成后必须重新上传证书;切换期间上传的证书属于旧域名,提升后即失效。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -48050,12 +48063,16 @@ "前置闸门:无域名 → 400「请先设置并验证域名」;domain_status !== 1 → 400「域名未通过验证,暂时无法上传证书」", "响应契约变更(10 → 13 字段):在上一轮 10 字段基础上追加 can_set_cert/can_set_cert_reason/domain_status,与 frontConfig.getCert 完全同口径", "通配语义(certCoversDomain,app/service/systems/frontConfig.js):*.example.com 分支要求通配前缀非空且不含「.」,即仅覆盖恰好一级标签", - "写库内容:cert_pem/cert_key 直接入库(不落暂存文件),cert_path/key_path 置 null 等待定时任务回填,cert_expire_at 取证书 validTo;同步状态同步重置为待同步(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at)" + "写库内容:cert_pem/cert_key 直接入库(不落暂存文件),cert_path/key_path 置 null 等待定时任务回填,cert_expire_at 取证书 validTo;同步状态同步重置为待同步(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at)", + "两阶段切换补充(本轮):域名提升时会清空证书(cert_pem / cert_key / cert_path / key_path / cert_expire_at 置 NULL)并重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error / last_synced_at),因此域名切换完成后必须重新上传证书;切换期间上传的证书属于旧域名,提升后即失效", + "前置闸门口径(本轮,实现未变):仍按生效域名 domain 判定(无域名 → 400「请先设置并验证域名」,domain_status !== 1 → 400「域名未通过验证,暂时无法上传证书」);切换中的待验证域名 pending_domain 不参与本闸门", + "文档变更范围:本次更新本条的 description + notes 各一处(params / response / errors / headers 均未变动,response 仍为 13 字段);frontConfig 分组仍 8 条;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)", + "维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)" ] }, { "method": "frontConfig.setDomain", - "description": "设置或变更当前仓库前端独立部署域名,并发起 DNS TXT 归属验证(需登录、免权限、免鉴权,权限由业务层按 isWarehouse 判定,仅仓库主体可调用)。流程:仓库主体校验 → domain 必填/长度(≤100 字符)/形态校验(统一转小写存储)→ 跨仓库唯一校验 → 生成一次性校验子域 verify_host(wmsv-<10 位 hex>.)与校验值 verify_value(32 位 hex)→ upsert 该仓库行并把 domain_status 置 0(未验证)→ 清理新旧域名的公共拉取缓存。查重:域名已被其他仓库使用返回 409「域名 X 已被其他仓库使用」(含并发写入唯一索引冲突兜底)。格式:至少两段标签、每段 1~63 位且仅字母数字与连字符、首尾不得为连字符(天然排除通配符 *、下划线、首尾点与单段主机名),不合法返回 400「domain 格式不正确」;空值返回 400「domain 不能为空」;超长返回 400「domain 长度不能超过 100 字符」。域名变更(仅大小写差异不算变更)会同时清空既有证书(cert_pem/cert_key/cert_path/key_path/cert_expire_at 置空)并重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at),避免 nginx 继续用旧域名证书对外服务;同一域名重复设置时:已验证则幂等返回(不刷新校验码、不清证书、不改验证状态),未验证/验证失败则重发新校验码并清零 attempts/last_error。响应口径与 frontConfig.getDomain 一致(9 字段);domain_status=1 时 verify_host/verify_value 返回空字符串。", + "description": "设置或变更当前仓库前端独立部署域名(需登录、免权限、免鉴权,权限由业务层按 isWarehouse 判定,仅仓库主体可调用)。语义已改为两阶段切换:本接口只登记「待验证域名」pending_domain 并下发一次性 DNS TXT 校验记录,不直接改动生效域名 domain;TXT 校验通过后(frontConfig.checkDomain 手动触发或 app/schedule/domain_verify_scan.js 定时扫描)再由提升逻辑一次性把 pending_domain 提升为生效域名。这样生效域名全程不变:切换期间旧域名的前端页面与 frontConfig.getByDomain 公共拉取都仍然可用,不会出现「改域名瞬间旧域名公共接口 404」的中间态。分支(域名比较一律忽略大小写):A 入参 == 生效域名 domain 且无 pending_domain → 幂等短路:不写库,仅当库内字面值与归一化结果不一致时把 domain 改写为小写并清理新旧两个字面值的缓存 key;B 入参 == 生效域名 domain 且有 pending_domain → 取消待切换:只清空 pending 6 列,生效域名、证书 5 列、同步 4 列与公共缓存一律不动;C 入参 == 现有 pending_domain → 校验码齐全则幂等短路(不重发、不写库),校验码缺失(脏数据)则只补发 pending 校验码并清 pending_verify_attempts/pending_last_error;D 其它(新的待切换域名,含首次设置)→ 查重(其他仓库的 domain 或 pending_domain 命中任一即 409)通过后生成新校验码只写入 pending 组,生效域名 domain / domain_status / domain_verified_at / domain_verify_* / 证书 5 列 / 同步 4 列一律不动,也不清理任何公共缓存(新域名尚未生效)。域名与校验码口径:domain 必填、trim 后非空、≤100 字符,形态校验通过后统一转小写存储;pending_verify_host 为一次性校验子域 wmsv-<10 位 hex>.<待验证域名>,pending_verify_value 为 32 位 hex。格式:至少两段标签、每段 1~63 位且仅字母数字与连字符、首尾不得为连字符(天然排除通配符 *、下划线、首尾点与单段主机名),不合法返回 400「domain 格式不正确」;空值返回 400「domain 不能为空」;超长返回 400「domain 长度不能超过 100 字符」;域名(或待验证域名)被其他仓库占用返回 409「域名 X 已被其他仓库使用」。响应口径与 frontConfig.getDomain 一致(16 字段);生效域名组 domain_status=1 时 verify_host/verify_value 返回空字符串,待验证域名组 pending_domain 非空时 pending_verify_host/pending_verify_value 始终回显。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -48129,6 +48146,48 @@ "type": "string", "required": true, "description": "最近一次验证失败原因(脱敏截断 ≤500 字符;未失败为空字符串)" + }, + { + "name": "pending_domain", + "type": "string", + "required": true, + "description": "待验证域名(切换中非空;未发起切换为空字符串)。frontConfig.setDomain 只登记到本字段,DNS TXT 校验通过后才被提升为生效域名 domain;本字段不参与 frontConfig.getByDomain 放行" + }, + { + "name": "pending_verify_host", + "type": "string", + "required": true, + "description": "待验证域名的 TXT 记录主机名(wmsv-<10 位 hex>.;pending_domain 为空时返回空字符串)。该域名尚未生效,校验码始终回显,用户据此配置 TXT 记录" + }, + { + "name": "pending_verify_value", + "type": "string", + "required": true, + "description": "待验证域名的 TXT 记录值(32 位 hex,读 pending_verify_token 列;pending_domain 为空时返回空字符串)" + }, + { + "name": "pending_attempts", + "type": "number", + "required": true, + "description": "待验证域名校验尝试次数(setDomain 登记/补码时清零;checkDomain 与定时任务校验失败时 +1)" + }, + { + "name": "pending_last_error", + "type": "string", + "required": true, + "description": "待验证域名最近一次校验失败原因(脱敏截断 ≤500 字符;未失败或无待验证域名为空字符串)" + }, + { + "name": "pending_created_at", + "type": "string", + "required": true, + "description": "发起本次域名切换的时间(无待验证域名为 null)" + }, + { + "name": "pending_active", + "type": "boolean", + "required": true, + "description": "是否处于域名切换中(boolean,等价于 pending_domain 非空;true=待验证域名已登记、等待 TXT 校验)" } ], "errors": [ @@ -48166,18 +48225,27 @@ } ], "notes": [ - "代码位置:出口 app/service/systemMethods/frontConfig.js 的 setDomain,实现 app/service/systems/frontConfig.js 的 setDomain(校验码由 buildDomainVerifyCode 生成,输出由 buildDomainOutput 构建)", + "代码位置:出口 app/service/systemMethods/frontConfig.js 的 setDomain,实现 app/service/systems/frontConfig.js 的 setDomain(校验码由 buildDomainVerifyCode 生成,取消待切换的字段由 buildPendingClearPatch 生成,输出由 buildDomainOutput 构建)", "鉴权标记:isNeedLogin=true、isNeedAuth=false;方法层 _noNeedRight/_noNeedLog/_noNeedAuth 均含 setDomain(_noNeedLogin 仍仅 getByDomain)", - "域名全局唯一由应用层校验(assertDomainUnique):可空列唯一索引不约束多个 NULL,非空值唯一性必须应用层兜底;同时捕获 SequelizeUniqueConstraintError 的 domain 字段冲突统一转 409", - "校验目标用一次性随机子域而非裸域名:避免与用户主域已有的其它 TXT 记录(SPF/DKIM/站点校验等)相互干扰", - "缓存:写库成功后清理「旧 domain + 新 domain」两个公共拉取缓存 key(front:config:domain:{domain}),先写库后清缓存;清缓存失败仅记日志,不影响设置结果", - "后续链路:用户按 verify_host/verify_value 配置 TXT 记录后,由 frontConfig.checkDomain 手动触发或 app/schedule/domain_verify_scan.js 定时任务(默认 10m)自动校验;domain_status=1 后 frontConfig.saveCert 才可上传证书、frontConfig.getByDomain 才放行", - "旧口径变更:域名原先只能通过 frontConfig.saveCert 变更,现统一收敛到本接口(saveCert 已移除 domain 入参,前端若仍传会被忽略)" + "变更原因(本轮核心语义变更):旧口径是「设置即生效」——一次 setDomain 即把 domain 改写为新域名、domain_status 归零并清空证书,导致旧域名立刻被 frontConfig.getByDomain 判为「域名未配置」返回 404,而 nginx 侧旧域名 server 块仍在,出现「页面能打开但拉不到配置」的中间态;用户改错域名也无法回滚。本轮改为两阶段(待验证域名与生效域名分离),本接口只登记待验证域名", + "四分支决策表(域名比较一律忽略大小写):A 入参 == 生效域名 domain 且无 pending_domain → 幂等短路(不写库;仅当库内字面值与归一化结果不一致时把 domain 改写为小写,并清理新旧两个字面值的缓存 key);B 入参 == 生效域名 domain 且有 pending_domain → 取消待切换(只清空 pending 6 列);C 入参 == 现有 pending_domain → 校验码齐全则幂等短路(不重发、不写库),校验码缺失(脏数据)则只补发 pending 校验码并清 pending_verify_attempts / pending_last_error;D 其它(新的待切换域名,含首次设置)→ 查重通过后只写 pending_domain + 新校验码(pending_verify_host / pending_verify_token / pending_verify_attempts=0 / pending_last_error=NULL / pending_created_at=now)", + "分支 B「取消待切换」的边界:只清 pending 6 列,生效域名 domain / domain_status / domain_verified_at / domain_verify_* / 证书 5 列 / 同步 4 列一律不动;待验证域名从未生效(不参与 getByDomain),因此无需清理公共缓存", + "分支 D「只登记不动」清单:domain / domain_status / domain_verified_at / domain_verify_host / domain_verify_token / domain_verify_attempts / domain_last_error / 证书 5 列(cert_pem / cert_key / cert_path / key_path / cert_expire_at)/ 同步 4 列(sync_status / sync_attempts / last_sync_error / last_synced_at)一律不动,也不清理任何公共缓存(新域名尚未生效,getByDomain 结果不受影响)。首次设置时新行只带 store_id 与 pending 组,domain 保持 NULL(尚未生效),domain_status 默认 0,外部证书脚本只处理 domain_status=1 的行、不会误处理该行", + "查重扩展(assertDomainUnique):由「其他仓库的 domain 命中」扩展为「其他仓库的 domain 或 pending_domain 命中」即 409「域名 X 已被其他仓库使用」;分支 A/B/C 不查重(域名已是本仓自身持有,全局唯一性由分支 D 查重与数据库唯一索引兜底);并发写入捕获 SequelizeUniqueConstraintError 的 domain 字段冲突同样转 409,其余冲突转 409「仓库前端配置保存冲突,请稍后重试」", + "缓存口径:只有分支 A 的「大小写规范化」需要清缓存 —— 公共拉取缓存键按域名字面值精确匹配(front:config:domain:Shop.com 与 front:config:domain:shop.com 是两个 key),新旧两个字面值都必须清;B/C/D 不清缓存(B 清的是从未生效的待验证域名,C/D 未改变生效域名)", + "响应契约变更(本轮 9 → 16 字段,纯追加):追加待验证域名组 pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active;生效域名组 9 字段名与语义不变;domain_status=1 时生效组的 verify_host/verify_value 仍为空字符串,待验证组在 pending_domain 非空时始终回显校验码", + "前端改造要点:提交后 TXT 指引改读 pending_verify_host / pending_verify_value;「取消待切换」= 用当前生效域名再调一次本接口(走分支 B);「切换中」用 pending_active / pending_attempts / pending_last_error / pending_created_at 展示;提升后需提示「切换完成,请重新上传证书」,并明确「切换期间上传的证书属于旧域名」", + "旧口径说明(历史事实,不回改):既有变更记录中「同一域名重复设置幂等短路、缺码补发」「未验证/验证失败则重发新校验码并清零 attempts」等描述属当时真实口径,由本条新记录承接覆盖;原「C 缺码补发·已验证」分支已不存在,五分支收敛为四分支 A/B/C/D", + "后续链路:用户按 pending_verify_host / pending_verify_value 配置 TXT 记录后,由 frontConfig.checkDomain 手动触发或 app/schedule/domain_verify_scan.js 定时任务(默认 10m)校验;通过后提升为生效域名(domain_status=1、清空证书 5 列、重置同步 4 列、旧域名写入 retired_domain + retired_at、清空 pending 6 列),此后 frontConfig.saveCert 才可重新上传证书、frontConfig.getByDomain 才对新域名放行", + "行为影响提示:本接口不再提供「更换校验码」能力(同域名重复提交走 A/B/C 分支),需要新校验码只能提交一个不同的待验证域名(走分支 D);若已登记的待验证域名一直不配置 TXT 记录,则永久停留在切换中状态、生效域名不受影响", + "本条 setDomain 的 params / errors / headers 未变动(查重扩展后 409 文案「域名 {domain} 已被其他仓库使用」沿用原文案,语义已覆盖 domain 与 pending_domain 两种占用)", + "文档变更范围:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409 错误码);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)", + "维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)" ] }, { "method": "frontConfig.getDomain", - "description": "查询当前仓库前端独立部署域名与验证状态(settings 页回显;需登录、免权限、免鉴权,仅仓库主体可调用)。响应 9 字段:warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error。domain_status 语义:0 未验证 / 1 已验证 / 2 验证失败。安全口径:domain_status=1(已验证)时 verify_host/verify_value 返回空字符串(校验令牌已无用途,不再回显);未验证(0/2)时回显本仓库应配置的 TXT 主机名与记录值,并额外返回 cname(取自配置 config.frontConfig.cname),指导用户把域名 CNAME 指向该目标。仓库未设置过域名时返回默认空值(warehouse_id 取当前仓库、domain 为空字符串、domain_status=0、verified_at 为 null、attempts=0、last_error 为空字符串),不返回 404。", + "description": "查询当前仓库前端独立部署域名与验证状态(settings 页回显;需登录、免权限、免鉴权,仅仓库主体可调用)。响应 16 字段,分两组:①生效域名组 9 字段 —— warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error(字段名、类型与语义一字未改);②待验证域名组 7 字段(两阶段域名切换新增、纯追加)—— pending_domain/pending_verify_host/pending_verify_value/pending_attempts/pending_last_error/pending_created_at/pending_active。两阶段语义:domain 始终是「生效域名」,切换期间(pending_active=true)仍为旧域名并继续对外正常服务,只有 TXT 校验通过被提升后才换成新域名;pending_domain 是用户提交、等待 TXT 校验的「待验证域名」,从未生效、不参与 frontConfig.getByDomain 放行。domain_status 语义:0 未验证 / 1 已验证 / 2 验证失败。安全口径:domain_status=1(已验证)时 verify_host/verify_value 返回空字符串(校验令牌已无用途,不再回显);未验证(0/2)时回显生效域名应配置的 TXT 主机名与记录值;待验证域名组不受该限制 —— pending_domain 非空时 pending_verify_host/pending_verify_value 始终回显(该域名尚未生效,用户必须据此配置 TXT 记录);pending_active 等价于 pending_domain 非空。cname 取配置 config.frontConfig.cname,未验证时提示把域名 CNAME 指向该目标。仓库未设置过域名时返回默认空值(warehouse_id 取当前仓库、domain 与 pending_domain 为空字符串、domain_status=0、pending_active=false、时间字段为 null、其余字符串字段为空字符串),不返回 404。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -48243,6 +48311,48 @@ "type": "string", "required": true, "description": "最近一次验证失败原因(脱敏截断 ≤500 字符;未失败为空字符串)" + }, + { + "name": "pending_domain", + "type": "string", + "required": true, + "description": "待验证域名(切换中非空;未发起切换为空字符串)。frontConfig.setDomain 只登记到本字段,DNS TXT 校验通过后才被提升为生效域名 domain;本字段不参与 frontConfig.getByDomain 放行" + }, + { + "name": "pending_verify_host", + "type": "string", + "required": true, + "description": "待验证域名的 TXT 记录主机名(wmsv-<10 位 hex>.;pending_domain 为空时返回空字符串)。该域名尚未生效,校验码始终回显,用户据此配置 TXT 记录" + }, + { + "name": "pending_verify_value", + "type": "string", + "required": true, + "description": "待验证域名的 TXT 记录值(32 位 hex,读 pending_verify_token 列;pending_domain 为空时返回空字符串)" + }, + { + "name": "pending_attempts", + "type": "number", + "required": true, + "description": "待验证域名校验尝试次数(setDomain 登记/补码时清零;checkDomain 与定时任务校验失败时 +1)" + }, + { + "name": "pending_last_error", + "type": "string", + "required": true, + "description": "待验证域名最近一次校验失败原因(脱敏截断 ≤500 字符;未失败或无待验证域名为空字符串)" + }, + { + "name": "pending_created_at", + "type": "string", + "required": true, + "description": "发起本次域名切换的时间(无待验证域名为 null)" + }, + { + "name": "pending_active", + "type": "boolean", + "required": true, + "description": "是否处于域名切换中(boolean,等价于 pending_domain 非空;true=待验证域名已登记、等待 TXT 校验)" } ], "errors": [ @@ -48260,15 +48370,25 @@ } ], "notes": [ - "代码位置:出口 app/service/systemMethods/frontConfig.js 的 getDomain,实现 app/service/systems/frontConfig.js 的 getDomain(buildDomainOutput)", + "代码位置:出口 app/service/systemMethods/frontConfig.js 的 getDomain,实现 app/service/systems/frontConfig.js 的 getDomain(输出由 buildDomainOutput 统一构建)", "鉴权标记:isNeedLogin=true、isNeedAuth=false;方法层 _noNeedRight/_noNeedLog/_noNeedAuth 均含 getDomain", - "cname 取自配置 config.frontConfig.cname(默认空字符串,非数据库字段),未验证时随本响应返回", - "同一输出口径被 setDomain(设置后回显)与 checkDomain(校验后回显)复用,字段含义一致" + "cname 取自配置 config.frontConfig.cname(默认空字符串,非数据库字段),未设置域名时也会返回", + "同一输出口径被 setDomain(登记后回显)与 checkDomain(校验后回显)复用,字段含义完全一致", + "响应契约变更(本轮 9 → 16 字段,纯追加):在原有 9 字段之后依次追加 pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active。旧字段名、类型与语义一字未改,属向后兼容追加,前端可先发版兼容后再启用两阶段 UI", + "字段来源:生效域名组读 domain / domain_status / domain_verify_host / domain_verify_token / domain_verified_at / domain_verify_attempts / domain_last_error;待验证域名组读 pending_domain / pending_verify_host / pending_verify_token / pending_verify_attempts / pending_last_error / pending_created_at,pending_active 由 pending_domain 非空推导", + "两阶段语义:domain 是「生效域名」——切换期间(pending_active=true)仍为旧域名并继续对外正常服务;pending_domain 是等待 TXT 校验的「待验证域名」,从未生效", + "回显口径差异(重要):生效域名的 verify_host/verify_value 在 domain_status=1 时返回空字符串;待验证域名不受此限制 —— pending_domain 非空时 pending_verify_host/pending_verify_value 始终回显,因为该域名尚未生效、用户必须据此配置 TXT 记录", + "与 frontConfig.getByDomain 的关系:getByDomain 仍只看生效 domain 且要求 domain_status=1,因此切换验证期间旧域名继续正常服务(不会出现「改域名瞬间旧域名公共接口 404」),只有提升后新域名才放行、旧域名才 404,最终由外部脚本按 retired_domain 删除旧域名 nginx 配置后彻底下线", + "前端改造要点:TXT 指引必须改读 pending_verify_host/pending_verify_value(不能再读 verify_host/verify_value);首次设置时 domain 为空字符串属正常态(待验证域名在 pending_domain);「切换中」状态用 pending_active/pending_attempts/pending_last_error/pending_created_at 展示;「切换完成」后提示重新上传证书", + "发布顺序强约束:本实现走 Sequelize 全字段 SELECT,若生产库尚未执行迁移(新增 pending_* / retired_* 共 8 列不存在),setDomain / getDomain / checkDomain 乃至 getByDomain 都会报 ER_BAD_FIELD_ERROR → 必须先执行迁移、再发布代码;迁移为纯追加且可空,先跑无风险", + "仓库未设置过域名时返回默认空值:warehouse_id 取当前仓库、domain 与 pending_domain 为空字符串、domain_status=0、pending_active=false、时间字段为 null、其余字符串字段为空字符串,不返回 404", + "文档变更范围:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409 错误码);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)", + "维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)" ] }, { "method": "frontConfig.checkDomain", - "description": "主动校验当前仓库前端独立部署域名的 DNS TXT 归属记录并回写库(需登录、免权限、免鉴权,仅仓库主体可调用)。解析目标一律取库内 domain_verify_host(不解析裸域名);解析路径 DoH 为主(config.frontConfig.domainVerify.dohUrl,默认 https://doh.pub/dns-query),DoH 失败降级系统 DNS(node:dns)。成功 → domain_status=1、写入 domain_verified_at、清空 domain_last_error,并清理该域名的公共拉取缓存;失败 → domain_status=2、domain_verify_attempts+1、domain_last_error 写入脱敏截断(≤500 字符)后的原因(如「未解析到 TXT 记录」「TXT 记录未包含校验值」「DNS 解析失败:…」)。无记录或 domain 为空 → 400「请先设置域名」。库内缺少校验码(历史脏数据)时自动补发一份再校验(本次因记录尚未生效仍会记失败);迁移回填的历史行(domain_status=1 但无校验码)直接返回 verified=true 且 resolved_values=[],不会把线上生效中的域名降级为验证失败。响应 = frontConfig.getDomain 的 9 字段 + verified(本次是否通过,boolean)+ resolved_values(本次解析到的 TXT 值,最多 5 条、单条截断 255 字符,排障用)。", + "description": "主动校验域名 TXT 归属记录并回写库(需登录、免权限、免鉴权,仅仓库主体可调用)。两阶段切换后本接口承担两条路径:①存在 pending_domain(切换中)→ 校验待验证域名:以 pending_verify_host 为解析目标、比对 pending_verify_token;通过则由提升逻辑把 pending_domain 提升为生效域名 domain(domain_status=1、domain_verified_at=now、domain_verify_* 由 pending_* 平移、domain_last_error 清空、清空 pending 6 列、旧域名写入 retired_domain/retired_at 下线队列、清空证书 5 列、重置同步 4 列),并清理旧域名与新域名两个公共拉取缓存,返回 verified=true;不通过只把 pending_verify_attempts+1 并写 pending_last_error,生效域名、domain_status、domain_verified_at 与证书一律不动,返回 verified=false。②无 pending_domain → 保持升级前口径:生效域名 domain_status=1 一律短路返回 verified=true、resolved_values=[],不写库、不改状态、不增加验证次数;domain 为空 → 400「请先设置域名」;domain 非空但未验证/验证失败(升级前登记的历史行)→ 用生效域名的 domain_verify_* 校验并回写 domain_status/domain_verify_attempts/domain_last_error(兼容路径,缺码则自动补发一次)。解析路径为 DoH 多端点顺序尝试(config.frontConfig.domainVerify.dohUrls,默认 https://dns.alidns.com/resolve → https://223.5.5.5/resolve → https://doh.pub/dns-query;单端点键 dohUrl 保留兼容),单端点「无记录」不再直接定论,全部端点未取到值后降级系统 DNS;仅「所有 DoH 端点都解析失败且系统 DNS 也失败」才报「DNS 解析失败:…」。失败原因经脱敏截断(≤500 字符)落库与回显。响应 = frontConfig.getDomain 的 16 字段 + verified(本次是否通过,boolean)+ resolved_values(本次解析到的 TXT 值,最多 5 条、单条截断 255 字符,排障用)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -48335,6 +48455,48 @@ "required": true, "description": "最近一次验证失败原因(脱敏截断 ≤500 字符;未失败为空字符串)" }, + { + "name": "pending_domain", + "type": "string", + "required": true, + "description": "待验证域名(切换中非空;未发起切换为空字符串)。frontConfig.setDomain 只登记到本字段,DNS TXT 校验通过后才被提升为生效域名 domain;本字段不参与 frontConfig.getByDomain 放行" + }, + { + "name": "pending_verify_host", + "type": "string", + "required": true, + "description": "待验证域名的 TXT 记录主机名(wmsv-<10 位 hex>.;pending_domain 为空时返回空字符串)。该域名尚未生效,校验码始终回显,用户据此配置 TXT 记录" + }, + { + "name": "pending_verify_value", + "type": "string", + "required": true, + "description": "待验证域名的 TXT 记录值(32 位 hex,读 pending_verify_token 列;pending_domain 为空时返回空字符串)" + }, + { + "name": "pending_attempts", + "type": "number", + "required": true, + "description": "待验证域名校验尝试次数(setDomain 登记/补码时清零;checkDomain 与定时任务校验失败时 +1)" + }, + { + "name": "pending_last_error", + "type": "string", + "required": true, + "description": "待验证域名最近一次校验失败原因(脱敏截断 ≤500 字符;未失败或无待验证域名为空字符串)" + }, + { + "name": "pending_created_at", + "type": "string", + "required": true, + "description": "发起本次域名切换的时间(无待验证域名为 null)" + }, + { + "name": "pending_active", + "type": "boolean", + "required": true, + "description": "是否处于域名切换中(boolean,等价于 pending_domain 非空;true=待验证域名已登记、等待 TXT 校验)" + }, { "name": "verified", "type": "boolean", @@ -48364,15 +48526,29 @@ { "code": "500", "message": "签约关系服务不可用 / WarehouseFrontConfig model 不可用 / 校验域名失败" + }, + { + "code": "409", + "message": "域名 {domain} 已被其他仓库使用(提升待验证域名时 domain 唯一索引冲突兜底)" } ], "notes": [ - "代码位置:出口 app/service/systemMethods/frontConfig.js 的 checkDomain,实现 app/service/systems/frontConfig.js 的 checkDomain(解析走 resolveTxtValues,单行校验走 verifyDomainRecord)", + "代码位置:出口 app/service/systemMethods/frontConfig.js 的 checkDomain,实现 app/service/systems/frontConfig.js 的 checkDomain(路径一走 checkPendingDomainRecord → promotePendingDomain,路径二走 verifyDomainRecord;TXT 解析走 resolveTxtValues)", "鉴权标记:isNeedLogin=true、isNeedAuth=false;方法层 _noNeedRight/_noNeedLog/_noNeedAuth 均含 checkDomain", - "DNS 解析细节:DoH 返回非 200 或响应体非合法 JSON 视为失败并降级系统 DNS;Status=3(NXDOMAIN)或 Status=0 且无 Answer 视为「未解析到记录」返回空数组,不再重复走系统 DNS;两条路径均失败时错误文案为「DNS 解析失败:{脱敏原因}」并写入 domain_last_error", - "与定时任务的关系:本接口为手动触发兜底,与 app/schedule/domain_verify_scan.js 共用同一套解析与落库逻辑(verifyDomainRecord);定时任务对超过 maxAttempts 的行不再自动重试,但仍可通过本接口手动校验", + "两阶段语义变更(本轮核心):有 pending_domain → 校验待验证域名的 TXT 记录(目标 pending_verify_host,比对 pending_verify_token)。通过 → 提升:domain 换为 pending_domain、domain_status=1、domain_verified_at=now、domain_verify_host/token/attempts 由 pending_* 平移、domain_last_error=NULL、清空 pending 6 列(pending_verify_attempts 归 0)、旧域名写入 retired_domain + retired_at、清空证书 5 列、重置同步 4 列(sync_status=0 / sync_attempts=0 / 清空 last_sync_error / last_synced_at),并清理旧域名与新域名两个公共拉取缓存,返回 verified=true;不通过 → 只写 pending_verify_attempts+1 与 pending_last_error,生效域名 domain / domain_status / domain_verified_at 与证书一律不动(旧域名不会被本路径断流),返回 verified=false", + "提升并发守卫与边界:update 的 where 带 id + pending_domain(重复提升、用户已取消待切换、其他实例已提升过都不会误改);pending_domain 只有普通索引(非唯一),并发提交同一域名理论上可写入多行,最终由 domain 唯一索引在提升阶段兜底 —— 提升撞唯一索引转 409「域名 X 已被其他仓库使用」;retired_domain 只保留最近一个旧域名(多次连续切换会丢中间域名);首次设置(无生效域名)不写 retired_domain/retired_at,且提升时刻意不把 retired_domain 置 NULL —— 队列里可能还有更早的旧域名等待外部脚本消费,覆盖会丢失下线任务(孤儿由脚本兜底清理)", + "提升后的预期噪音:提升后到用户上传新证书前,外部证书脚本会以「cert_pem 内容为空」记一次同步失败(属预期,失败只落库、不删除旧域名文件)", + "路径二(无 pending_domain,保持升级前口径):domain_status=1 一律短路返回 verified=true、resolved_values=[],不写库、不降状态、不加 attempts(避免用户误点「校验」把生效中的域名打成验证失败而断流);domain 为空 → 400「请先设置域名」;domain_status∈{0,2} 且库内缺校验码(历史脏数据)→ 自动补发一份再校验(本次因记录尚未生效仍会失败),校验结果回写 domain_status / domain_verified_at / domain_verify_attempts / domain_last_error(兼容升级前登记的历史行)", + "DNS 解析细节(多端点口径):默认按 config.frontConfig.domainVerify.dohUrls 顺序尝试(dns.alidns.com → 223.5.5.5 → doh.pub,单端点键 dohUrl 保留兼容),每个端点结果三分类 values(拿到至少一条 TXT 值 → 立即返回)/ empty(NODATA 或 NXDOMAIN)/ error(请求异常、超时、HTTP 非 200、响应体非合法 JSON);empty 与 error 都继续尝试下一个端点;全部端点未取到值后降级系统 DNS(node:dns,按 timeoutMs 限时)。只要有一个端点或系统 DNS 明确答复「无该记录」即判「未解析到记录」(返回空数组、不抛错),仅「所有 DoH 端点都是 error 且系统 DNS 也抛错」才抛 500「DNS 解析失败:{脱敏原因}」", + "缓存:提升成功后清「旧域名 + 新域名」两个公共拉取缓存 key(front:config:domain:{domain}),先写库后清缓存,清失败仅记 WARN;路径二校验成功也清该域名的缓存", + "与定时任务的关系:本接口为手动触发兜底,与 app/schedule/domain_verify_scan.js 共用同一套提升逻辑(定时任务入口为 verifyPendingDomains,逐行走 checkPendingDomainRecord / promotePendingDomain);定时任务对 pending_verify_attempts 已达 maxAttempts 的行不再自动重试(计入 skipped),但仍可通过本接口手动校验(本接口无 maxAttempts 门控)", "脱敏:失败原因统一经 sanitizeErrorText 处理(剥离 PEM 块内容、压缩空白、截断至 500 字符)后落库与回显,不写入原始网络错误/堆栈", - "定时任务 lockTtlSeconds 默认 600s(略大于 interval 10m),避免上一轮未结束时重复加锁" + "响应契约变更(本轮 11 → 18 字段,纯追加):在 last_error 之后、verified/resolved_values 之前插入待验证域名组 7 字段(pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active),既有 9 字段与 verified/resolved_values 的名称与语义均不变。本条 response 必须同步更新 —— 其口径定义为「frontConfig.getDomain 的字段 + verified + resolved_values」,getDomain 已由 9 字段扩为 16 字段,若本条不同步则文档与代码不一致", + "errors 新增 409:提升时待验证域名已被其他仓库用为生效域名(domain 唯一索引冲突)返回 409「域名 X 已被其他仓库使用」;既有 400「请先设置域名」/ 400 未识别仓库 / 403 / 500 口径不变", + "前端改造要点:切换中(pending_active=true)调用本接口才是「校验待验证域名」;通过后应提示「切换完成,请重新上传证书」—— 提升时证书已被清空、同步状态已重置;切换期间上传的证书属于旧域名,提升后失效", + "定时任务头注释口径复核(未处理,建议由 wms-dev-agent 修正):app/schedule/domain_verify_scan.js 头注释仍写「扫描…已生成待校验 TXT 记录、且尚未通过验证的行,逐行解析 DNS TXT 记录并回写 domain_status / domain_verified_at / domain_verify_attempts / domain_last_error」—— 两阶段改造后实际只扫描 pending 组、回写 pending_* 并在通过时提升;本次为文档任务且约束不改 app/** 代码,故仅报告", + "文档变更范围:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409 错误码);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)", + "维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)" ] } ]