WMS_MAIN/app/service/systems/frontConfig.js
liufumingren 3f5eb49081 feat(frontConfig): 前端独立部署域名两阶段切换(pending 登记 + TXT 校验通过后提升)
- 迁移 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 补齐入库)。
2026-09-25 23:40:56 +08:00

2240 lines
98 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
const crypto = require('node:crypto');
// 域名验证 TXT 记录的兜底解析使用 Node 内置 DNS(本文件为全仓首次引入 node:dns):
// DoH(ctx.curl)多端点全部「未取到值」时降级为系统解析,且显式限时(见 resolveTxtBySystem);
// 仅服务域名验证链路,不参与业务主链路。
const dns = require('node:dns');
const { Service } = require('egg');
// 仓库前端配置品牌文本字段元信息(对应 wms_warehouse_front_config,一仓一行)。
// 域名与证书字段不在此列:domain 只能通过 frontConfig.setDomain 设置(并先通过域名验证),
// cert_pem/cert_key/cert_path/key_path 只能通过证书上传接口(saveCert)变更。
const TEXT_FIELDS = Object.freeze([
Object.freeze({ key: 'title', name: 'title', maxLength: 100 }),
Object.freeze({ key: 'logo_url', name: 'logo_url', maxLength: 255 }),
Object.freeze({ key: 'favicon_url', name: 'favicon_url', maxLength: 255 }),
Object.freeze({ key: 'login_bg_url', name: 'login_bg_url', maxLength: 255 }),
]);
// 公共按域名拉取接口对外输出的字段白名单(安全红线:严禁输出证书/私钥内容与证书路径、同步状态等内部字段)
const PUBLIC_FIELDS = Object.freeze([
'domain',
'title',
'logo_url',
'login_bg_url',
'favicon_url',
'theme',
]);
// 公共按域名拉取接口缓存 TTL(秒)
const PUBLIC_CACHE_TTL_SECONDS = 600;
// 未登记域名空缓存 TTL(秒):短缓存兜底防穿透,域名登记后由保存流程主动失效
const PUBLIC_MISS_CACHE_TTL_SECONDS = 60;
// 证书/私钥 PEM 文本最大长度(正常 RSA/ECC 证书远小于该值,防止异常大报文)
const PEM_MAX_LENGTH = 64 * 1024;
// 域名验证状态(与 wms_warehouse_front_config.domain_status 列及模型 validate 保持一致)
const DOMAIN_STATUS_UNVERIFIED = 0;
const DOMAIN_STATUS_VERIFIED = 1;
const DOMAIN_STATUS_FAILED = 2;
// 域名形态:至少两段标签,每段 1~63 位、仅字母数字与连字符、首尾不得为连字符;
// 天然排除通配符 *、下划线、首尾点与单段主机名(长度上限由 normalizeText 的 ≤100 兜住)
const DOMAIN_PATTERN = /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.(?!-)[A-Za-z0-9-]{1,63}(?<!-))+$/;
// 域名验证 TXT 记录主机名前缀与随机码字节数(5 字节 → 10 位 hex)
const DOMAIN_VERIFY_HOST_PREFIX = 'wmsv-';
const DOMAIN_VERIFY_HOST_RANDOM_BYTES = 5;
// 域名验证 TXT 记录值随机字节数(16 字节 → 32 位 hex)
const DOMAIN_VERIFY_TOKEN_BYTES = 16;
// 域名验证失败原因落库长度上限(与 domain_last_error STRING(500) 列宽一致)
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;
/**
* 前端独立部署配置服务:仓库前端品牌配置、证书上传与按域名公共拉取。
*
* 数据表:wms_warehouse_front_config(一仓一行,domain 全局唯一)。
* 公共拉取缓存键:front:config:domain:{domain}。
*/
class FrontConfigService extends Service {
createError(message, code = 500) {
const error = new Error(message);
error.code = code;
return error;
}
/**
* 从 ctx.user.store_id 获取当前仓库 ID。
*
* @return {number} 仓库 ID。
* @throws {Error} 未识别到仓库时抛出,状态码 400。
*/
getCurrentWarehouseId() {
const warehouseId = Number(this.ctx.user && this.ctx.user.store_id);
if (!Number.isFinite(warehouseId) || warehouseId <= 0) {
throw this.createError('未识别到当前仓库,无法操作仓库设置', 400);
}
return warehouseId;
}
/**
* 删除指定缓存键。
*
* @param {string} cacheKey 缓存键。
* @return {Promise<void>} 无返回值。
*/
async deleteCacheByKey(cacheKey) {
if (!cacheKey) {
return;
}
if (this.app && typeof this.app.delCacheAsync === 'function') {
await this.app.delCacheAsync(cacheKey);
return;
}
if (this.app && typeof this.app.setCacheAsync === 'function') {
await this.app.setCacheAsync(cacheKey, null, 0);
}
}
/**
* 校验并规范化仓库前端配置的字符串字段。
*
* @param {*} value 原始值。
* @param {string} fieldName 字段名。
* @param {number} maxLength 字段最大长度。
* @return {string|null} 规范化后的字符串;空值返回 null(表示清空)。
* @throws {Error} 超长时抛出,状态码 400。
*/
normalizeText(value, fieldName, maxLength) {
if (value === undefined || value === null) {
return null;
}
const normalized = String(value).trim();
if (!normalized) {
return null;
}
if (normalized.length > maxLength) {
throw this.createError(`${fieldName} 长度不能超过 ${maxLength} 字符`, 400);
}
return normalized;
}
/**
* 校验并规范化仓库前端配置的 theme 字段。
*
* @param {*} value 原始值(对象或 JSON 字符串)。
* @return {Object|null} 规范化后的主题对象;空值返回 null(表示清空)。
* @throws {Error} 非合法 JSON 对象时抛出,状态码 400。
*/
normalizeTheme(value) {
if (value === undefined || value === null || value === '') {
return null;
}
let parsed = value;
if (typeof value === 'string') {
try {
parsed = JSON.parse(value.trim());
} catch (error) {
throw this.createError('theme 必须是合法的 JSON 对象', 400);
}
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw this.createError('theme 必须是合法的 JSON 对象', 400);
}
return parsed;
}
/**
* 校验非空 domain 的全局唯一性(可空列唯一索引允许多 NULL,数据库不兜底)。
*
* 两阶段切换后「占用」的定义包含待验证域名:其他仓库的 domain 或 pending_domain
* 命中任一即视为已占用(否则两个仓库可同时把同一域名登记为待验证,直到「提升」时才在
* domain 唯一索引上撞车)。注意 pending_domain 只有普通索引(非唯一),
* 并发提交仍可能绕过本校验,最终由 domain 唯一索引在提升时兜底。
*
* @param {string} domain 待校验域名(非空,已小写化)。
* @param {number} excludeWarehouseId 排除的仓库 ID(当前仓库自身)。
* @return {Promise<void>} 无返回值。
* @throws {Error} domain 已被其他仓库使用时抛出,状态码 409。
*/
async assertDomainUnique(domain, excludeWarehouseId) {
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
const { Op } = this.app.Sequelize;
const existing = await configModel.findOne({
where: {
store_id: { [Op.ne]: excludeWarehouseId },
[Op.or]: [
{ domain },
{ pending_domain: domain },
],
},
attributes: [ 'store_id', 'domain', 'pending_domain' ],
});
if (existing) {
throw this.createError(`域名 ${domain} 已被其他仓库使用`, 409);
}
}
/**
* 从记录(Sequelize 实例或普通对象)读取字段值。
*
* @param {Object} record 记录实例或普通对象。
* @param {string} key 字段名。
* @return {*} 字段值;不可读时返回 null。
*/
getRecordField(record, key) {
if (!record) {
return null;
}
if (typeof record.get === 'function') {
return record.get(key);
}
return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : null;
}
/**
* 脱敏并截断错误文本:去掉 PEM 块内容、压缩空白、按列宽截断。
*
* 安全红线:域名验证失败原因会写入 domain_last_error 并回显前端,
* 严禁把原始网络错误/堆栈原样落库(脱敏思路参考 script/warehouse-cert-sync.cjs 的 sanitizeErrorText)。
*
* @param {*} text 原始错误文本。
* @return {string} 脱敏截断后的文本(≤500 字符)。
*/
sanitizeErrorText(text) {
return String(text === undefined || text === null ? '' : text)
.replace(/-----BEGIN [^-]*-----[\s\S]*?-----END [^-]*-----/g, '[PEM 内容已省略]')
.replace(/\s+/g, ' ')
.trim()
.slice(0, DOMAIN_LAST_ERROR_MAX_LENGTH);
}
/**
* 读取域名验证配置(config.frontConfig.domainVerify),缺失或非法项回退默认值。
*
* 公共方法:app/schedule 下的域名验证定时任务会直接调用,签名与返回值需保持稳定。
*
* @return {Object} 域名验证配置,字段如下:
* - enable {boolean}:是否启用域名验证定时任务;
* - interval {string}:扫描间隔(Egg schedule 语法);
* - lockTtlSeconds {number}:Redis 跨进程锁 TTL(秒);
* - batchSize {number}:单轮最多处理行数;
* - dohUrls {string[]}:DoH 端点数组(顺序即尝试顺序,多端点顺序尝试、命中即返回);
* - dohUrl {string}:恒等于 dohUrls[0],兼容仍在读单端点键的旧调用方(历史单字符串配置仍生效);
* - timeoutMs {number}:单个 DoH 端点、以及系统 DNS 兜底单次查询的超时(毫秒);
* - maxAttempts {number}:自动重试次数上限。
*/
getDomainVerifyConfig() {
const frontConfig = (this.app && this.app.config && this.app.config.frontConfig) || {};
const raw = frontConfig.domainVerify || {};
const toPositiveNumber = (value, fallback) => {
const parsed = Number(value);
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),
// 单轮行数上限:最坏耗时核算见 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)。
*
* 域名未通过验证时随 getDomain 返回给前端,提示用户把域名 CNAME 指向该目标。
*
* @return {string} CNAME 目标;未配置返回空串。
*/
getCnameTarget() {
const frontConfig = (this.app && this.app.config && this.app.config.frontConfig) || {};
return String(frontConfig.cname || '').trim();
}
/**
* 生成域名验证所需的随机码(一次性校验子域 + TXT 记录值)。
*
* 校验目标用一次性随机子域(wmsv-<10 位 hex>.<域名>)而非裸域名,
* 避免与用户主域上已有的其它 TXT 记录(SPF/DKIM/站点校验等)互相干扰。
*
* @param {string} domain 已规范化的域名。
* @return {Object} { host: 待校验 TXT 主机名, token: 待校验 TXT 记录值(32 位 hex) }。
*/
buildDomainVerifyCode(domain) {
const randomTag = crypto.randomBytes(DOMAIN_VERIFY_HOST_RANDOM_BYTES).toString('hex');
return {
host: `${DOMAIN_VERIFY_HOST_PREFIX}${randomTag}.${domain}`,
token: crypto.randomBytes(DOMAIN_VERIFY_TOKEN_BYTES).toString('hex'),
};
}
/**
* 解析 DoH 应答中单条 TXT 记录的 data 文本(去外层引号、多段拼接、截断保护)。
*
* DoH JSON 的 Answer[].data 形如 "abc" 或 "abc" "def"(TXT 单条记录可按 255 字节分段)。
*
* @param {*} data DoH 应答中的 data 字段。
* @return {string} 解析后的 TXT 文本;无内容返回空串。
*/
parseTxtAnswerData(data) {
const text = String(data === undefined || data === null ? '' : data).trim();
if (!text) {
return '';
}
const segments = text.match(/"([^"]*)"/g);
const value = segments && segments.length > 0
? segments.map(segment => segment.slice(1, -1)).join('')
: text.replace(/"/g, '');
return value.trim().slice(0, TXT_VALUE_MAX_LENGTH);
}
/**
* 从 DoH 应答的 Answer 数组中提取 TXT 记录(type=16)。
*
* @param {Array} answers DoH 应答的 Answer 数组。
* @return {string[]} TXT 记录文本列表(已去空、截断)。
*/
extractTxtValuesFromAnswers(answers) {
const values = [];
for (const answer of Array.isArray(answers) ? answers : []) {
if (!answer || Number(answer.type) !== 16) {
continue;
}
const value = this.parseTxtAnswerData(answer.data);
if (value) {
values.push(value);
}
}
return values;
}
/**
* 请求单个 DoH 端点解析 TXT 记录,并把结果三分类(本方法自身不抛异常)。
*
* 分类口径:
* - values:拿到至少一条 TXT 值 → 调用方应立即返回,不再尝试后续端点;
* - empty :Status === 0 且有 Question 但无 Answer(NODATA),或 Status === 3(NXDOMAIN)
* → 「本端点未解析到记录」。注意这不等于「记录一定不存在」:可能是该端点的负缓存滞后
* (见 resolveTxtByDoh 中的实测案例),故调用方必须继续尝试下一个端点,不能就此定论;
* - error :请求异常/超时、HTTP 非 200、响应体非对象等 → 「本端点解析失败」,同样继续下一个端点。
*
* @param {string} host 待解析主机名。
* @param {string} endpoint DoH 端点地址(不含查询串)。
* @param {number} timeoutMs 单端点请求超时(毫秒)。
* @return {Promise<Object>} { kind: values|empty|error, endpoint: string, values?: string[], reason?: string }。
* reason 已脱敏截断,仅用于日志与最终错误文案。
*/
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) {
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 请求异常',
};
}
}
/**
* 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<Object>} { 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<string[]>} TXT 记录文本列表(多段已拼接、去空、截断)。
* @throws {Error} 解析失败(含 NXDOMAIN/超时)时抛出。
*/
async resolveTxtBySystem(host, timeoutMs) {
const limitMs = Number(timeoutMs) > 0 ? Number(timeoutMs) : 0;
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;
}
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)。
*
* 决策流程:
* 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<Object>} { values: string[], source: 'doh'|'system', endpoint: string|null }。
* @throws {Error} 所有 DoH 端点均失败且系统 DNS 也失败时抛出,状态码 500,文案已脱敏截断。
*/
async resolveTxtValues(host) {
const normalizedHost = String(host || '').trim().toLowerCase();
if (!normalizedHost) {
throw this.createError('域名解析主机名不能为空', 400);
}
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 {
systemValues = await this.resolveTxtBySystem(normalizedHost, verifyConfig.timeoutMs);
} catch (error) {
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 };
}
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 归属记录(定时任务逐行调用,必须失败隔离、不得抛异常)。
*
* 签名说明(两阶段切换改造):新增可选第二参数 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<Object>} 校验结果,字段如下:
* - verified {boolean}:是否校验通过(解析到的 TXT 记录中包含校验值);
* - values {string[]}:实际解析到的 TXT 值;
* - source {string}:解析来源 doh/system,未解析为空串(resolveTxtValues 另返回 endpoint,本方法不透出);
* - 注意:解析路径「明确无记录」时本方法返回 verified=false + values=[](不抛异常),
* 仅当所有 DoH 端点与系统 DNS 都解析失败时,resolveTxtValues 才抛 500 并在此转为 error 文案。
* - error {string|null}:失败原因(已脱敏截断),成功为 null。
*/
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 主机名,请重新设置域名' };
}
if (!verifyToken) {
return { verified: false, values: [], source: '', error: '未生成待校验的 TXT 记录值,请重新设置域名' };
}
try {
const { values, source } = await this.resolveTxtValues(verifyHost);
const normalizedValues = values.map(value => String(value).trim());
// 校验值为后端生成的 hex,比对时忽略大小写(DNS 记录本身大小写不敏感)
const expected = verifyToken.toLowerCase();
if (normalizedValues.some(value => value.toLowerCase() === expected)) {
return { verified: true, values: normalizedValues, source, error: null };
}
return {
verified: false,
values: normalizedValues,
source,
error: normalizedValues.length > 0 ? 'TXT 记录未包含校验值' : '未解析到 TXT 记录',
};
} catch (error) {
return {
verified: false,
values: [],
source: '',
error: this.sanitizeErrorText(error.message) || '域名解析失败',
};
}
}
/**
* 判定错误是否为「数据库列不存在」(迁移尚未执行的典型表现)。
*
* 迁移尚未执行时查询 domain_status 等新列会报 ER_BAD_FIELD_ERROR / Unknown column,
* 这类错误必须走降级路径(而非中断定时任务、也不应让公共拉取接口直接 500)。
*
* @param {*} error 错误对象。
* @return {boolean} 是未知列错误返回 true。
*/
isUnknownColumnError(error) {
if (!error) {
return false;
}
const code = String((error.parent && error.parent.code) || error.code || '');
if (code === 'ER_BAD_FIELD_ERROR') {
return true;
}
const message = String(error.message || '');
return /unknown column/i.test(message) || message.includes('ER_BAD_FIELD_ERROR');
}
/**
* 查询「已验证」的域名配置记录(公共拉取闸门的查库入口)。
*
* 迁移容错:迁移尚未执行(domain_status 列不存在)时降级为仅按 domain 查询,
* 保持迁移前的行为,并用进程内一次性标记避免刷日志;
* 迁移完成后需重启实例,闸门才会真正生效(进程内标记与 model 定义均在重启后刷新)。
*
* @param {Object} configModel WarehouseFrontConfig model。
* @param {string} normalizedDomain 已 trim 的域名。
* @return {Promise<Object|null>} 命中返回记录实例,未命中返回 null。
* @throws {Error} 非「未知列」的数据库异常原样抛出(由调用方转 500)。
*/
async findVerifiedDomainRecord(configModel, normalizedDomain) {
try {
return await configModel.findOne({
where: {
domain: normalizedDomain,
domain_status: DOMAIN_STATUS_VERIFIED,
},
});
} catch (error) {
if (!this.isUnknownColumnError(error)) {
throw error;
}
// 一次性 WARN:迁移完成并重启实例后自动恢复闸门,避免每个请求都刷日志
if (this.app && !this.app._frontConfigDomainStatusFallbackWarned) {
this.app._frontConfigDomainStatusFallbackWarned = true;
this.ctx.logger.warn(
'[FrontConfigService.findVerifiedDomainRecord] wms_warehouse_front_config.domain_status 列不存在'
+ '(迁移尚未执行),本次降级为仅按 domain 查询;迁移完成后需重启实例才能恢复域名验证闸门'
);
}
return configModel.findOne({
where: {
domain: normalizedDomain,
},
});
}
}
/**
* 扫描并校验「待验证域名」(供定时任务与手动触发复用)。
*
* 两阶段切换后本方法只处理 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 不可用、或迁移尚未执行(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, 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:校验失败且 pending 状态回写成功的行数;skipped:因达到 maxAttempts 上限而未自动重试的行数;
* errors:脱敏后的错误原因列表(含提升失败,这类行不计入 verified / failed)。
*/
async verifyPendingDomains(options = {}) {
const verifyConfig = this.getDomainVerifyConfig();
const batchSize = Number(options.batchSize) > 0
? Math.floor(Number(options.batchSize))
: verifyConfig.batchSize;
const maxAttempts = Number(options.maxAttempts) > 0
? Math.floor(Number(options.maxAttempts))
: verifyConfig.maxAttempts;
const onRow = typeof options.onRow === 'function' ? options.onRow : null;
const summary = { scanned: 0, verified: 0, failed: 0, skipped: 0, errors: [] };
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findAll !== 'function') {
summary.errors.push('WarehouseFrontConfig model 不可用');
return summary;
}
const { Op } = this.app.Sequelize;
const pendingWhere = {
pending_domain: { [Op.ne]: null },
pending_verify_host: { [Op.ne]: null },
pending_verify_token: { [Op.ne]: null },
};
let rows = [];
try {
rows = await configModel.findAll({
where: {
...pendingWhere,
pending_verify_attempts: { [Op.lt]: maxAttempts },
},
attributes: [
'id',
'store_id',
'domain',
'pending_domain',
'pending_verify_host',
'pending_verify_token',
'pending_verify_attempts',
'pending_last_error',
],
order: [[ 'id', 'ASC' ]],
limit: batchSize,
raw: true,
});
} 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 + hint);
return summary;
}
// 已达上限的行不再自动重试,单独计数便于观察「自动重试已耗尽」的域名规模;
// 计数失败不影响主流程(计入 errors 即可)
try {
summary.skipped = await configModel.count({
where: {
...pendingWhere,
pending_verify_attempts: { [Op.gte]: maxAttempts },
},
});
} catch (error) {
const reason = this.sanitizeErrorText(error.message) || '未知错误';
this.ctx.logger.warn('[FrontConfigService.verifyPendingDomains] 统计已达重试上限行数失败: %s', reason);
summary.errors.push('统计已达重试上限行数失败:' + reason);
}
summary.scanned = rows.length;
for (const row of rows) {
const rowId = Number(row.id);
const rowDomain = String(row.domain || '').trim();
const pendingDomain = String(row.pending_domain || '').trim();
let result = { verified: false, error: '未解析到 TXT 记录' };
try {
// verifyDomainRecord 契约上不抛异常,此处为最后一道兜底,保证单行失败不中断整轮
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) || '域名校验异常' };
}
if (result.verified) {
// 校验通过 → 提升为生效域名:清空证书、重置同步状态、旧域名写入 retired_domain 下线队列
try {
await this.promotePendingDomain(row);
summary.verified += 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
);
}
}
if (onRow) {
try {
await onRow({
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 || ''),
});
} catch (error) {
// 回调异常只 WARN,绝不影响主流程
this.ctx.logger.warn(
'[FrontConfigService.verifyPendingDomains] onRow 回调执行失败 id=%s: %s',
rowId,
this.sanitizeErrorText(error.message)
);
}
}
}
return summary;
}
/**
* 构建前端配置品牌信息输出对象(settings 页回显,无记录时返回默认空值)。
*
* 安全红线:仅输出品牌与基础字段,严禁输出 cert_pem/key_pem/cert_expire_at/
* sync_status/sync_attempts/last_sync_error/last_synced_at 等证书与同步内部字段。
*
* @param {Object|null} record 配置记录实例(可为 null)。
* @param {number} warehouseId 当前仓库 ID。
* @return {Object} 品牌信息输出对象(warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/updated_at)。
*/
buildInfoOutput(record, warehouseId) {
const hasRecord = !!(record && typeof record.get === 'function');
const getValue = key => (hasRecord ? record.get(key) : null);
return {
warehouse_id: Number(warehouseId || 0),
domain: hasRecord ? (getValue('domain') || '') : '',
title: hasRecord ? (getValue('title') || '') : '',
logo_url: hasRecord ? (getValue('logo_url') || '') : '',
favicon_url: hasRecord ? (getValue('favicon_url') || '') : '',
login_bg_url: hasRecord ? (getValue('login_bg_url') || '') : '',
theme: hasRecord ? (getValue('theme') || null) : null,
updated_at: hasRecord ? (getValue('updated_at') || null) : null,
};
}
/**
* 构建前端配置证书输出对象(证书/私钥原文回显,无记录时返回默认空值)。
*
* 证书回显:输出证书原文(cert_pem)与私钥原文(key_pem,取自 cert_key 列),
* 不再输出 cert_path/key_path 路径字段(保存时已置空,尚无真实路径)。
* 安全说明:私钥原文回显仅限仓库主体登录后的 settings 页(getCert/saveCert
* 复用本输出);公共无鉴权接口 getByDomain 走 buildPublicOutput 白名单,不经过本方法。
*
* ⚠ 响应契约:本方法输出 13 个字段(原有 10 个 + 本次新增 3 个),文档与测试需同步。
* 原有 10 字段:warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/
* sync_attempts/last_sync_error/last_synced_at/updated_at。
* 新增 3 字段(追加在末尾):
* - domain_status:域名验证状态 0-未验证/1-已验证/2-验证失败;
* - can_set_cert:域名非空且已验证(domain_status=1)才允许上传证书;
* - can_set_cert_reason:不可上传时的原因,可上传为空串。
*
* @param {Object|null} record 配置记录实例(可为 null)。
* @param {number} warehouseId 当前仓库 ID。
* @return {Object} 证书输出对象(13 字段)。
*/
buildCertOutput(record, warehouseId) {
const hasRecord = !!(record && typeof record.get === 'function');
const getValue = key => (hasRecord ? record.get(key) : null);
const domain = hasRecord ? (getValue('domain') || '') : '';
const domainStatus = hasRecord ? Number(getValue('domain_status') || 0) : DOMAIN_STATUS_UNVERIFIED;
// 上传证书的前置闸门:必须先设置域名并通过 DNS TXT 验证
const canSetCert = !!domain && domainStatus === DOMAIN_STATUS_VERIFIED;
let canSetCertReason = '';
if (!domain) {
canSetCertReason = '请先设置域名';
} else if (!canSetCert) {
canSetCertReason = this.describeDomainStatus(domainStatus);
}
return {
warehouse_id: Number(warehouseId || 0),
domain: hasRecord ? (getValue('domain') || '') : '',
cert_pem: hasRecord ? (getValue('cert_pem') || '') : '',
key_pem: hasRecord ? (getValue('cert_key') || '') : '',
cert_expire_at: hasRecord ? (getValue('cert_expire_at') || null) : null,
sync_status: hasRecord ? Number(getValue('sync_status') || 0) : 0,
sync_attempts: hasRecord ? Number(getValue('sync_attempts') || 0) : 0,
last_sync_error: hasRecord ? (getValue('last_sync_error') || '') : '',
last_synced_at: hasRecord ? (getValue('last_synced_at') || null) : null,
updated_at: hasRecord ? (getValue('updated_at') || null) : null,
can_set_cert: canSetCert,
can_set_cert_reason: canSetCertReason,
domain_status: domainStatus,
};
}
/**
* 查询当前仓库前端独立部署品牌配置(settings 页回显)。
*
* 需登录(token 绑定仓库上下文,只能查到自己仓库的配置),仅返回品牌与基础字段,
* 不含证书/私钥原文与同步状态等内部字段(证书回显走 getCert)。
*
* @return {Promise<Object>} 品牌信息输出对象;无记录时返回默认空值。
* @throws {Error} 未识别到当前仓库时抛出 400;非仓库主体时抛出 403。
*/
async getInfo() {
const warehouseId = this.getCurrentWarehouseId();
// 仅仓库主体管理员可查看前端独立部署配置(isWarehouse 判定)
await this.assertWarehouseSubject();
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
const record = await configModel.findOne({
where: {
store_id: warehouseId,
},
});
return this.buildInfoOutput(record, warehouseId);
}
/**
* 查询当前仓库前端独立部署证书配置(settings 页回显)。
*
* 需登录(token 绑定仓库上下文,只能查到自己仓库的配置),
* 响应含证书原文(cert_pem)与私钥原文(key_pem),仅供仓库主体 settings 页回显;
* 公共无鉴权接口 getByDomain 仍只返回公开字段白名单。
*
* @return {Promise<Object>} 证书输出对象;无记录时返回默认空值。
* @throws {Error} 未识别到当前仓库时抛出 400;非仓库主体时抛出 403。
*/
async getCert() {
const warehouseId = this.getCurrentWarehouseId();
// 仅仓库主体管理员可查看前端独立部署证书(isWarehouse 判定)
await this.assertWarehouseSubject();
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
const record = await configModel.findOne({
where: {
store_id: warehouseId,
},
});
return this.buildCertOutput(record, warehouseId);
}
/**
* 查询当前仓库域名验证状态(settings 页回显,需登录、仅仓库主体)。
*
* 需登录(token 绑定仓库上下文,只能查到自己仓库的配置);无记录时返回空值默认。
*
* 两阶段切换后输出在既有 9 个字段之后追加待验证域名组(pending_domain / pending_verify_host /
* pending_verify_value / pending_attempts / pending_last_error / pending_created_at /
* pending_active),既有字段一律不改名、不删除;字段口径详见 buildDomainOutput。
*
* @return {Promise<Object>} 域名输出对象,既有 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() {
const warehouseId = this.getCurrentWarehouseId();
// 仅仓库主体管理员可查看前端独立部署域名配置(isWarehouse 判定)
await this.assertWarehouseSubject();
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
const record = await configModel.findOne({
where: {
store_id: warehouseId,
},
});
return this.buildDomainOutput(record, warehouseId);
}
/**
* 设置当前仓库自持域名(需登录、仅仓库主体)。
*
* 两阶段切换(本次改造核心):本接口只登记「待验证域名」,不直接改动生效域名。
* 第一阶段(本接口):把入参写入 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<Object>} 域名输出对象(生效域名组 + 待验证域名组 + cname)。
* @throws {Error} 未识别到当前仓库时抛出 400;非仓库主体时抛出 403;
* 参数非法时抛出 400;域名被其他仓库占用时抛出 409。
*/
async setDomain(data = {}) {
const warehouseId = this.getCurrentWarehouseId();
// 仅仓库主体管理员可配置前端独立部署域名(isWarehouse 判定)
await this.assertWarehouseSubject();
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
const domain = this.normalizeText(data.domain, 'domain', 100);
if (!domain) {
throw this.createError('domain 不能为空', 400);
}
// 统一转小写存储:DNS 大小写不敏感,避免同一域名靠大小写差异绕过去重校验
const normalizedDomain = domain.toLowerCase();
if (!DOMAIN_PATTERN.test(normalizedDomain)) {
throw this.createError('domain 格式不正确', 400);
}
const record = await configModel.findOne({
where: {
store_id: warehouseId,
},
});
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;
// ===== 分支 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);
}
// ===== 分支 B:入参 == 生效域名 且有待验证域名 → 取消待切换 =====
if (record && matchesCurrentDomain && currentPendingDomain) {
// 只清 pending 6 列:生效域名、证书 5 列、同步 4 列一律不动;
// 待验证域名从未生效(不参与 getByDomain),因此无需清理公共缓存
await record.update(this.buildPendingClearPatch());
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(pendingPatch);
} else {
// 首次设置:新行只带 store_id 与 pending 组;domain 保持 NULL(尚未生效),
// domain_status 默认 0,证书脚本只处理 domain_status = 1 的行,不会误处理本行
savedRecord = await configModel.create({
store_id: warehouseId,
...pendingPatch,
});
}
} catch (error) {
// 并发写入兜底:唯一索引冲突统一转为业务错误
if (error && error.name === 'SequelizeUniqueConstraintError') {
const conflictFields = error.fields || {};
if (Object.prototype.hasOwnProperty.call(conflictFields, 'domain')) {
throw this.createError(`域名 ${normalizedDomain} 已被其他仓库使用`, 409);
}
throw this.createError('仓库前端配置保存冲突,请稍后重试', 409);
}
throw error;
}
// 回查一次再输出,避免实例上残留 CURRENT_TIMESTAMP 等字面量
const refreshedRecord = await configModel.findByPk(savedRecord.id);
// 不清任何公共缓存:新域名尚未生效(生效域名 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<Object|null>} 提升后的最新记录实例(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<Object>} 域名输出对象 + 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 校验并回写结果(需登录、仅仓库主体)。
*
* 两阶段切换后本接口同时承担两条路径:
* 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<Object>} 域名输出对象 + verified(本次是否通过)
* + resolved_values(本次解析到的 TXT 值,最多 5 条)。
* @throws {Error} 未识别到当前仓库时抛出 400;未设置域名时抛出 400;非仓库主体时抛出 403;
* 待验证域名已被其他仓库用为生效域名时抛出 409。
*/
async checkDomain() {
const warehouseId = this.getCurrentWarehouseId();
// 仅仓库主体管理员可触发域名校验(isWarehouse 判定)
await this.assertWarehouseSubject();
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
const record = await configModel.findOne({
where: {
store_id: warehouseId,
},
});
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);
// 已验证域名一律短路(不论库内有无校验码):
// 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,
resolved_values: [],
};
}
const patch = {};
let verifyHost = String(record.get('domain_verify_host') || '').trim();
let verifyToken = String(record.get('domain_verify_token') || '').trim();
// 未验证/验证失败(domain_status ∈ {0, 2},已验证行已在上方短路)且库内缺少校验码:
// 补发一份,用户配置 DNS 解析后再次校验即可通过(本次校验仍会因记录未生效而失败)
if (!verifyHost || !verifyToken) {
const verifyCode = this.buildDomainVerifyCode(domain);
verifyHost = verifyCode.host;
verifyToken = verifyCode.token;
patch.domain_verify_host = verifyHost;
patch.domain_verify_token = verifyToken;
}
const verifyResult = await this.verifyDomainRecord(record, {
host: verifyHost,
token: verifyToken,
});
if (verifyResult.verified) {
patch.domain_status = DOMAIN_STATUS_VERIFIED;
patch.domain_verified_at = new Date();
patch.domain_last_error = null;
} else {
patch.domain_status = DOMAIN_STATUS_FAILED;
patch.domain_verify_attempts = Number(record.get('domain_verify_attempts') || 0) + 1;
patch.domain_last_error = this.sanitizeErrorText(verifyResult.error) || '域名验证失败';
}
await record.update(patch);
// 回查一次再输出,避免实例上残留 CURRENT_TIMESTAMP 等字面量
const savedRecord = await configModel.findByPk(record.id);
return {
...this.buildDomainOutput(savedRecord, warehouseId),
verified: !!verifyResult.verified,
resolved_values: this.buildResolvedValues(verifyResult.values),
};
}
/**
* 构建域名验证输出对象(getDomain/setDomain/checkDomain 共用)。
*
* 返回结构(两阶段切换后扩展,既有字段一律不改名、不删除):
* · 生效域名组: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} 域名输出对象(生效组 + 待验证组 + cname)。
*/
buildDomainOutput(record, warehouseId) {
const hasRecord = !!(record && typeof record.get === 'function');
const getValue = key => (hasRecord ? record.get(key) : null);
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),
domain,
domain_status: domainStatus,
verify_host: exposeVerifyInfo ? String(getValue('domain_verify_host') || '') : '',
verify_value: exposeVerifyInfo ? String(getValue('domain_verify_token') || '') : '',
cname: this.getCnameTarget(),
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,已验证返回空串)。
*
* @param {number} domainStatus 域名验证状态。
* @return {string} 状态文案。
*/
describeDomainStatus(domainStatus) {
if (Number(domainStatus) === DOMAIN_STATUS_VERIFIED) {
return '';
}
if (Number(domainStatus) === DOMAIN_STATUS_FAILED) {
return '域名验证失败';
}
return '域名待验证';
}
/**
* 构建前端配置公共拉取接口的缓存键(按域名)。
*
* @param {string} domain 域名(内部会 trim 规范化)。
* @return {string} Redis 缓存键。
*/
getDomainCacheKey(domain) {
return `front:config:domain:${String(domain || '').trim()}`;
}
/**
* 构建前端配置公共拉取接口的输出对象(仅公开字段白名单)。
*
* 安全红线:只输出 PUBLIC_FIELDS 白名单字段,
* 严禁输出 cert_pem/cert_key 证书与私钥内容,以及 cert_path、key_path、
* sync_status、sync_attempts、last_sync_error 等内部字段。
*
* @param {Object} record 配置记录实例。
* @return {Object} 仅含公开字段的输出对象。
*/
buildPublicOutput(record) {
const hasRecord = !!(record && typeof record.get === 'function');
const getValue = key => (hasRecord ? record.get(key) : null);
const output = {};
for (const key of PUBLIC_FIELDS) {
const value = hasRecord ? getValue(key) : null;
output[key] = key === 'theme' ? (value || null) : (value || '');
}
return output;
}
/**
* 清理指定域名的前端配置公共拉取缓存(空域名跳过)。
*
* @param {string} domain 待清理的域名。
* @return {Promise<void>} 无返回值。
*/
async clearDomainCache(domain) {
const normalizedDomain = String(domain || '').trim();
if (!normalizedDomain) {
return;
}
await this.deleteCacheByKey(this.getDomainCacheKey(normalizedDomain));
}
/**
* 批量清理多个域名的公共拉取缓存(去重、忽略空值,单个失败仅记 WARN 不抛出)。
*
* 顺序说明(重要):域名提升/切换必须先写库、后清缓存,且旧域名与新域名两个 key 都要清——
* 公共拉取缓存 key 按域名精确匹配(front:config:domain:{domain}),漏清旧域名会让已下线的
* 旧域名继续对外返回配置,漏清新域名则让新域名继续返回旧配置。
*
* @param {string[]} domains 待清理域名列表(可含空值/重复项)。
* @param {string} [logTag] 日志前缀(定位调用方)。
* @return {Promise<void>} 无返回值(绝不抛出)。
*/
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 缓存 + 查库兜底)。
*
* 安全红线:只返回公开字段(domain/title/logo_url/login_bg_url/favicon_url/theme),
* 严禁返回 cert_pem/cert_key 证书与私钥内容,以及 cert_path/key_path/
* sync_status/sync_attempts/last_sync_error 等内部字段。
*
* @param {string} domain 待查询域名。
* @return {Promise<Object>} 仅含公开字段的配置对象。
* @throws {Error} domain 为空时抛出 400;未登记域名抛出 404;数据库异常抛出 500。
*/
async getByDomain(domain) {
const normalizedDomain = String(domain || '').trim();
if (!normalizedDomain) {
throw this.createError('domain 不能为空', 400);
}
if (normalizedDomain.length > 100) {
throw this.createError('domain 长度不能超过 100 字符', 400);
}
const cacheKey = this.getDomainCacheKey(normalizedDomain);
// 缓存取舍:命中缓存后 TTL(PUBLIC_CACHE_TTL_SECONDS = 600s)内直接返回,
// 若该行随后被置为「未验证」,理论上最长仍有 600s 会被放行;
// 但 setDomain / saveCert / 域名验证扫描成功均已调用 clearDomainCache 主动失效,
// 实际可通过缓存被放行的窗口很短,接受该取舍。
// 优先读缓存;Redis 异常时降级查库(getCacheAsync 内部已做 Redis 降级处理)
if (this.app && typeof this.app.getCacheAsync === 'function') {
try {
const cached = await this.app.getCacheAsync(cacheKey);
// 未登记域名空缓存标记:直接按未配置返回,防穿透
if (cached && typeof cached === 'object' && cached.configured === false) {
throw this.createError('域名未配置', 404);
}
if (cached && typeof cached === 'object' && typeof cached.domain === 'string' && cached.domain) {
return cached;
}
} catch (error) {
if (Number(error.code) === 404) {
throw error;
}
this.ctx.logger.warn('[FrontConfigService.getByDomain] 读取缓存失败,降级查库: %s', error.message);
}
}
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
// 应用层闸门:只放行 domain_status = 1(已验证)的域名;
// 迁移尚未执行时 findVerifiedDomainRecord 内部降级为仅按 domain 查询(保持迁移前行为)
const record = await this.findVerifiedDomainRecord(configModel, normalizedDomain);
if (!record) {
// 缓存穿透兜底:未登记域名写短 TTL 空缓存,防止高频探测打穿数据库
if (this.app && typeof this.app.setCacheAsync === 'function') {
try {
await this.app.setCacheAsync(cacheKey, { configured: false }, PUBLIC_MISS_CACHE_TTL_SECONDS);
} catch (error) {
this.ctx.logger.warn('[FrontConfigService.getByDomain] 写入未命中空缓存失败: %s', error.message);
}
}
throw this.createError('域名未配置', 404);
}
const output = this.buildPublicOutput(record);
if (this.app && typeof this.app.setCacheAsync === 'function') {
try {
await this.app.setCacheAsync(cacheKey, output, PUBLIC_CACHE_TTL_SECONDS);
} catch (error) {
this.ctx.logger.warn('[FrontConfigService.getByDomain] 写入缓存失败: %s', error.message);
}
}
return output;
}
/**
* 规范化证书/私钥 PEM 文本:去首尾空白,空值返回 null(表示未提供)。
*
* @param {*} value 原始值(PEM 文本)。
* @param {string} fieldName 字段名(用于错误提示)。
* @return {string|null} 规范化后的 PEM 文本;空值返回 null。
* @throws {Error} 内容超过长度上限时抛出,状态码 400。
*/
normalizePem(value, fieldName) {
if (value === undefined || value === null) {
return null;
}
const normalized = String(value).trim();
if (!normalized) {
return null;
}
if (normalized.length > PEM_MAX_LENGTH) {
throw this.createError(`${fieldName} 内容长度不能超过 ${PEM_MAX_LENGTH} 字符`, 400);
}
return normalized;
}
/**
* 用 Node 内置 crypto.X509Certificate 解析证书 PEM 文本。
*
* @param {string} certPem 证书 PEM 文本。
* @return {Object} 解析成功后的 X509Certificate 实例。
* @throws {Error} 证书无法解析时抛出,状态码 400,统一文案“证书不合法”。
*/
parseCertPem(certPem) {
try {
return new crypto.X509Certificate(certPem);
} catch (error) {
throw this.createError('证书不合法', 400);
}
}
/**
* 校验证书有效期:未生效或已过期的证书禁止提交。
*
* @param {Object} cert 已解析的 X509Certificate 实例。
* @return {void} 无返回值。
* @throws {Error} 证书未生效或已过期时抛出,状态码 400,统一文案“证书不合法”。
*/
assertCertValid(cert) {
const now = Date.now();
const validFrom = new Date(cert.validFrom);
const validTo = new Date(cert.validTo);
if (Number.isNaN(validFrom.getTime())) {
throw this.createError('证书不合法', 400);
}
if (validFrom.getTime() > now) {
throw this.createError('证书不合法', 400);
}
if (Number.isNaN(validTo.getTime())) {
throw this.createError('证书不合法', 400);
}
if (validTo.getTime() <= now) {
throw this.createError('证书不合法', 400);
}
}
/**
* 收集证书可覆盖的域名列表:SAN 中的 DNS 项与 CN,统一转小写。
*
* @param {Object} cert 已解析的 X509Certificate 实例。
* @return {string[]} 小写域名列表。
*/
collectCertNames(cert) {
const names = [];
const sanText = cert.subjectAltName || '';
for (const part of String(sanText).split(',')) {
const entry = String(part).trim();
if (entry.startsWith('DNS:')) {
const dnsName = entry.slice(4).trim();
if (dnsName) {
names.push(dnsName.toLowerCase());
}
}
}
const subjectText = cert.subject || '';
const cnMatch = /CN\s*=\s*([^,\n]+)/i.exec(String(subjectText));
if (cnMatch && cnMatch[1]) {
names.push(cnMatch[1].trim().toLowerCase());
}
return names;
}
/**
* 判断证书域名列表是否覆盖目标域名(支持精确匹配与通配符 *.example.com)。
*
* @param {string[]} names 证书 SAN/CN 域名列表(小写)。
* @param {string} domain 待校验域名。
* @return {boolean} 是否覆盖。
*/
certCoversDomain(names, domain) {
const target = String(domain).toLowerCase();
if (!target) {
return true;
}
return names.some(name => {
const normalized = String(name).toLowerCase();
if (normalized === target) {
return true;
}
if (normalized.startsWith('*.')) {
const suffix = normalized.slice(1);
if (!target.endsWith(suffix)) {
return false;
}
const prefix = target.slice(0, target.length - suffix.length);
return prefix.length > 0 && !prefix.includes('.');
}
return false;
});
}
/**
* 校验私钥与证书是否成对:对比两者的 SPKI DER 公钥指纹。
*
* @param {string} keyPem 私钥 PEM 文本。
* @param {Object} cert 已解析的 X509Certificate 实例。
* @return {void} 无返回值。
* @throws {Error} 私钥无法解析或与证书不匹配时抛出,状态码 400,统一文案“证书不合法”。
*/
validateKeyPem(keyPem, cert) {
let publicKey;
try {
publicKey = crypto.createPublicKey(keyPem);
} catch (error) {
throw this.createError('证书不合法', 400);
}
const keySpki = publicKey.export({ type: 'spki', format: 'der' });
const certSpki = cert.publicKey.export({ type: 'spki', format: 'der' });
if (Buffer.compare(keySpki, certSpki) !== 0) {
throw this.createError('证书不合法', 400);
}
}
/**
* 校验当前主体为仓库主体(前端独立部署配置仅仓库主体可操作)。
*
* @return {Promise<Object>} 当前主体对象(含 id/company_name/project/isWarehouse/status)。
* @throws {Error} 签约关系服务不可用时抛出 500;非仓库主体时抛出 403。
*/
async assertWarehouseSubject() {
const storeWarehouseService = this.ctx.service && this.ctx.service.systems && this.ctx.service.systems.storeWarehouse;
if (!storeWarehouseService || typeof storeWarehouseService.getCurrentSubject !== 'function') {
throw this.createError('签约关系服务不可用', 500);
}
const currentSubject = await storeWarehouseService.getCurrentSubject();
if (!currentSubject || !currentSubject.isWarehouse) {
throw this.createError('仅仓库主体可配置前端独立部署', 403);
}
return currentSubject;
}
/**
* 保存当前仓库前端独立部署品牌配置(upsert,一仓一行,仅品牌字段部分更新)。
*
* 域名与证书不在本接口受理范围:domain 变更必须走 setDomain(并重新通过域名验证);
* cert_pem/key_pem/cert_path/key_path/cert_expire_at 一律不受理(方法层白名单过滤)。
* 保存仍视为一次配置变更:同步状态重置为待同步,写库成功后清理当前 domain 的公共拉取缓存。
*
* @param {Object} [data={}] 请求参数。
* @param {string} [data.title] 站点标题(≤100 字符,空值清空)。
* @param {string} [data.logo_url] Logo 地址(≤255 字符,空值清空)。
* @param {string} [data.favicon_url] 站点 favicon 图标地址(≤255 字符,空值清空)。
* @param {string} [data.login_bg_url] 登录页背景图地址(≤255 字符,空值清空)。
* @param {Object|string} [data.theme] 主题配置(合法 JSON 对象或 JSON 字符串,空值清空)。
* @return {Promise<Object>} 保存后的品牌信息输出对象(同步状态已重置为待同步;不含证书/私钥字段)。
* @throws {Error} 非仓库主体时抛出 403;参数非法时抛出 400。
*/
async saveInfo(data = {}) {
const warehouseId = this.getCurrentWarehouseId();
// 仅仓库主体管理员可配置前端独立部署(isWarehouse 判定)
await this.assertWarehouseSubject();
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
const patch = {};
for (const field of TEXT_FIELDS) {
if (Object.prototype.hasOwnProperty.call(data, field.key)) {
patch[field.key] = this.normalizeText(data[field.key], field.name, field.maxLength);
}
}
if (Object.prototype.hasOwnProperty.call(data, 'theme')) {
patch.theme = this.normalizeTheme(data.theme);
}
// 保存即重置同步状态:本次保存待同步
patch.sync_status = 0;
patch.sync_attempts = 0;
patch.last_sync_error = null;
patch.last_synced_at = null;
let record = await configModel.findOne({
where: {
store_id: warehouseId,
},
});
// 品牌字段不改变 domain:写库成功后清理当前 domain 的公共拉取缓存即可
const previousDomain = record ? String(record.get('domain') || '').trim() : '';
try {
if (record) {
await record.update(patch);
} else {
record = await configModel.create({
store_id: warehouseId,
...patch,
});
}
} catch (error) {
// 并发写入兜底:唯一索引冲突统一转为业务错误
if (error && error.name === 'SequelizeUniqueConstraintError') {
throw this.createError('仓库前端配置保存冲突,请稍后重试', 409);
}
throw error;
}
// 回查一次再输出,避免实例上残留 CURRENT_TIMESTAMP 等字面量
const savedRecord = await configModel.findByPk(record.id);
// 写库成功后清理公共拉取缓存(先写库后清缓存);清缓存失败仅记日志,不影响保存结果
if (previousDomain) {
await this.clearDomainCache(previousDomain)
.catch(error => {
this.ctx.logger.warn('[FrontConfigService.saveInfo] 清理前端配置缓存失败: %s', error.message);
});
}
return this.buildInfoOutput(savedRecord, warehouseId);
}
/**
* 上传当前仓库前端独立部署证书(证书/私钥成对,需登录、仅仓库主体)。
*
* domain 不再作为入参受理:域名一律取库内已设置的值(前端若仍传 domain 会被忽略),
* 且必须先通过 DNS TXT 验证(domain_status=1)才允许上传。
* 校验链:库内域名非空且已验证 → 证书可解析 → 未生效拒绝 → 已过期拒绝 →
* 私钥与证书成对 → 证书 SAN/CN 覆盖库内 domain(支持 *.example.com 通配,不覆盖返回 400)。
* 证书校验链任一失败均返回统一文案“证书不合法”(400),不返回细节。
* 通过后自动写入 cert_expire_at(证书 validTo 权威值,不接受前端传值),
* 证书/私钥 PEM 内容直接写入 cert_pem/cert_key 列(内容仅定时任务读取,不写暂存文件);
* 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 文本(必填,与证书成对)。
* @return {Promise<Object>} 保存后的证书输出对象(13 字段,含证书/私钥原文回显)。
* @throws {Error} 非仓库主体时抛出 403;未设置/未验证域名、参数非法或证书不合法时抛出 400。
*/
async saveCert(data = {}) {
const warehouseId = this.getCurrentWarehouseId();
// 仅仓库主体管理员可上传前端独立部署证书(isWarehouse 判定)
await this.assertWarehouseSubject();
const configModel = this.ctx.model && this.ctx.model.WarehouseFrontConfig;
if (!configModel || typeof configModel.findOne !== 'function') {
throw this.createError('WarehouseFrontConfig model 不可用', 500);
}
// 入参必填校验:pem/key 必填(nginx 起 HTTPS 需要成对);data.domain 一律忽略不受理
const certPem = this.normalizePem(data.pem, 'pem');
if (!certPem) {
throw this.createError('pem 不能为空', 400);
}
const keyPem = this.normalizePem(data.key, 'key');
if (!keyPem) {
throw this.createError('key 不能为空', 400);
}
const record = await configModel.findOne({
where: {
store_id: warehouseId,
},
});
// 前置闸门:证书必须挂在当前仓库已设置并验证通过的域名上
const domain = record ? String(record.get('domain') || '').trim() : '';
if (!domain) {
throw this.createError('请先设置并验证域名', 400);
}
if (Number(record.get('domain_status') || 0) !== DOMAIN_STATUS_VERIFIED) {
throw this.createError('域名未通过验证,暂时无法上传证书', 400);
}
// 校验链:证书可解析 → 未生效/已过期拒绝 → 私钥匹配 → SAN/CN 覆盖库内域名
const cert = this.parseCertPem(certPem);
this.assertCertValid(cert);
this.validateKeyPem(keyPem, cert);
const certNames = this.collectCertNames(cert);
if (!this.certCoversDomain(certNames, domain)) {
throw this.createError('证书不合法', 400);
}
// 证书/私钥内容直接入库(不再写暂存文件),有效期以证书 validTo 权威写入。
// cert_path/key_path 保存时置空:内容已换而路径陈旧,避免 nginx 误读;
// 等待定时任务(Egg schedule/外部 crontab)部署后回填真实路径。
// patch 内不再含 domain:本接口已不受理域名变更,域名唯一性由 setDomain 保证,无需重复校验。
const patch = {
cert_pem: certPem,
cert_key: keyPem,
cert_path: null,
key_path: null,
cert_expire_at: new Date(cert.validTo),
// 保存即重置同步状态:本次上传待同步
sync_status: 0,
sync_attempts: 0,
last_sync_error: null,
last_synced_at: null,
};
try {
await record.update(patch);
} catch (error) {
// 并发写入兜底:唯一索引冲突统一转为业务错误
if (error && error.name === 'SequelizeUniqueConstraintError') {
throw this.createError('仓库前端配置保存冲突,请稍后重试', 409);
}
throw error;
}
// 回查一次再输出,避免实例上残留 CURRENT_TIMESTAMP 等字面量
const savedRecord = await configModel.findByPk(record.id);
// 写库成功后清理公共拉取缓存(先写库后清缓存:避免先清后写时并发读把旧值重新写回缓存)。
// 域名已不能在本接口变更,「旧域名/新域名」必然相同,因此只需清当前域名一个 key;
// 清缓存失败仅记日志,不影响保存结果。
await this.clearDomainCache(domain)
.catch(error => {
this.ctx.logger.warn('[FrontConfigService.saveCert] 清理前端配置缓存失败: %s', error.message);
});
return this.buildCertOutput(savedRecord, warehouseId);
}
}
module.exports = FrontConfigService;