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

288 lines
13 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 MainService = require('../main');
/**
* 系统方法层:frontConfig(前端独立部署配置接口包装层)。
*
* 业务实现全部委托 ctx.service.systems.frontConfig:本层只做参数白名单过滤、
* 鉴权出口与统一成功/失败包装。
*/
class FrontConfigMethodsService extends MainService {
constructor(ctx) {
super(ctx);
// 公共按域名拉取:免登录、免权限、免鉴权(保留系统日志,与 workbench 公共接口口径一致)
// 注意:getByDomain 是唯一免登录接口;域名验证接口(setDomain/getDomain/checkDomain)一律需登录
const _noNeedLogin = 'getByDomain';
// settings 页配置接口:需登录、免权限、免鉴权(权限由业务层 isWarehouse 判定),不记系统日志
const _noNeedRight = 'getByDomain,getInfo,getCert,saveInfo,saveCert,setDomain,getDomain,checkDomain';
const _noNeedLog = 'getInfo,getCert,saveInfo,saveCert,setDomain,getDomain,checkDomain';
const _noNeedAuth = 'getByDomain,getInfo,getCert,saveInfo,saveCert,setDomain,getDomain,checkDomain';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 获取前端独立部署业务服务(systems/frontConfig)。
*
* @return {Object|null} 业务服务实例;不可用时返回 null。
*/
getFrontConfigService() {
return (this.service && this.service.systems && this.service.systems.frontConfig) || null;
}
/**
* 按域名拉取仓库前端公开配置(公共无鉴权接口)。
*
* 安全红线:响应仅含公开字段(domain/title/logo_url/login_bg_url/favicon_url/theme),
* 不含 cert_pem/key_pem/cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段。
*
* @param {Object} [data={}] 请求参数。
* @param {string} data.domain 待查询域名(必填,非空)。
* @return {Promise<Object>} 统一响应结构;命中返回公开字段配置(code=200),
* 未登记域名返回 code=404「域名未配置」。
*/
async getByDomain(data = {}) {
const { domain } = data || {};
const targetService = this.getFrontConfigService();
if (!targetService || typeof targetService.getByDomain !== 'function') {
return this.fail('获取前端配置失败', { code: 500 });
}
try {
const result = await targetService.getByDomain(domain);
return this.success('获取成功', { ...result, code: 200 });
} catch (error) {
return this.fail(error.message || '获取前端配置失败', {
code: Number(error.code) || 500,
});
}
}
/**
* 查询当前仓库前端独立部署品牌配置(settings 页回显,需登录)。
*
* 仅返回品牌与基础字段(warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/updated_at),
* 不含证书/私钥原文与同步状态等内部字段(证书回显走 frontConfig.getCert)。
*
* @return {Promise<Object>} 统一响应结果。
*/
async getInfo() {
const targetService = this.getFrontConfigService();
if (!targetService || typeof targetService.getInfo !== 'function') {
return this.fail('获取前端配置失败', { code: 500 });
}
try {
const result = await targetService.getInfo();
return this.success('ok', result);
} catch (error) {
return this.fail(error.message || '获取前端配置失败', {
code: Number(error.code) || 500,
});
}
}
/**
* 查询当前仓库前端独立部署证书配置(settings 页回显,需登录)。
*
* 响应含证书原文(cert_pem)与私钥原文(key_pem,取自 cert_key 列),
* 仅供仓库主体登录后的 settings 页回显,公共无鉴权接口 frontConfig.getByDomain
* 仍只返回公开字段白名单。
*
* @return {Promise<Object>} 统一响应结果。
*/
async getCert() {
const targetService = this.getFrontConfigService();
if (!targetService || typeof targetService.getCert !== 'function') {
return this.fail('获取前端证书配置失败', { code: 500 });
}
try {
const result = await targetService.getCert();
return this.success('ok', result);
} catch (error) {
return this.fail(error.message || '获取前端证书配置失败', {
code: Number(error.code) || 500,
});
}
}
/**
* 保存当前仓库前端独立部署品牌配置(upsert,一仓一行,仅品牌字段部分更新,需登录)。
*
* domain 与证书字段不再受理:domain 变更必须走 frontConfig.setDomain(域名验证通过后方可上传证书);
* cert_pem/key_pem/cert_path/key_path/cert_expire_at 一律被白名单过滤忽略。
*
* @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>} 统一响应结果。
*/
async saveInfo(data = {}) {
const targetService = this.getFrontConfigService();
if (!targetService || typeof targetService.saveInfo !== 'function') {
return this.fail('保存前端配置失败', { code: 500 });
}
try {
const source = data || {};
const params = {};
// domain/cert_path/key_path/cert_pem/key_pem/cert_expire_at 均不受理:
// domain 变更走 setDomain,证书与有效期字段由后端权威维护,前端传值直接忽略
for (const key of [ 'title', 'logo_url', 'favicon_url', 'login_bg_url', 'theme' ]) {
if (Object.prototype.hasOwnProperty.call(source, key)) {
params[key] = source[key];
}
}
const result = await targetService.saveInfo(params);
return this.success('ok', result);
} catch (error) {
return this.fail(error.message || '保存前端配置失败', {
code: Number(error.code) || 500,
});
}
}
/**
* 上传当前仓库前端独立部署证书(需登录、仅仓库主体)。
*
* domain 不再受理:域名一律取库内已设置且验证通过的值(前端若仍传 data.domain 一律忽略),
* 未设置域名或域名未通过 TXT 验证时由业务层返回 400。
* 后端自动写入 cert_expire_at(证书 validTo 权威值),证书/私钥内容直接入库(不落盘),
* 保存后清理该域名的公共拉取缓存并返回证书配置输出
* (响应含证书/私钥原文回显,13 字段,口径与 frontConfig.getCert 一致)。
*
* 域名切换提示:待验证域名提升为生效域名时会清空证书 5 列并重置同步状态(域名已变,证书必须
* 重新上传);前置闸门与 SAN/CN 覆盖校验始终以生效域名为准。
*
* @param {Object} data 请求参数。
* @param {string} data.pem 证书 PEM 文本(必填)。
* @param {string} data.key 私钥 PEM 文本(必填,与证书成对)。
* @return {Promise<Object>} 统一响应结果。
*/
async saveCert(data = {}) {
const targetService = this.getFrontConfigService();
if (!targetService || typeof targetService.saveCert !== 'function') {
return this.fail('上传前端证书失败', { code: 500 });
}
try {
const source = data || {};
const { pem, key } = source;
// data.domain 不再受理:域名只认库内已设置并验证通过的值,前端若仍传 domain 一律忽略
const result = await targetService.saveCert({
pem,
key,
});
return this.success('ok', result);
} catch (error) {
return this.fail(error.message || '上传前端证书失败', {
code: Number(error.code) || 500,
});
}
}
/**
* 设置当前仓库前端独立部署域名(需登录、仅仓库主体)。
*
* 设置成功只登记待验证域名并下发一次性 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<Object>} 统一响应结果(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();
if (!targetService || typeof targetService.setDomain !== 'function') {
return this.fail('设置域名失败', { code: 500 });
}
try {
const result = await targetService.setDomain(data || {});
return this.success('ok', result);
} catch (error) {
return this.fail(error.message || '设置域名失败', {
code: Number(error.code) || 500,
});
}
}
/**
* 查询当前仓库前端独立部署域名与验证状态(需登录、仅仓库主体)。
*
* 返回待校验的 verify_host/verify_value 与 cname;domain_status=1(已验证)时
* verify_host/verify_value 返回空串(校验令牌已无用途);无记录时返回空值默认。
*
* 两阶段切换后响应在既有 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<Object>} 统一响应结果(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();
if (!targetService || typeof targetService.getDomain !== 'function') {
return this.fail('获取域名配置失败', { code: 500 });
}
try {
const result = await targetService.getDomain();
return this.success('ok', result);
} catch (error) {
return this.fail(error.message || '获取域名配置失败', {
code: Number(error.code) || 500,
});
}
}
/**
* 主动校验当前仓库前端独立部署域名的 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<Object>} 统一响应结果(code=1);未设置域名时 code=400。
*/
async checkDomain() {
const targetService = this.getFrontConfigService();
if (!targetService || typeof targetService.checkDomain !== 'function') {
return this.fail('校验域名失败', { code: 500 });
}
try {
const result = await targetService.checkDomain();
return this.success('ok', result);
} catch (error) {
return this.fail(error.message || '校验域名失败', {
code: Number(error.code) || 500,
});
}
}
}
module.exports = FrontConfigMethodsService;