WMS_MAIN/script/warehouse-cert-sync.cjs
liufumingren 3c252a65d3 feat(deploy): 证书同步脚本支持站点个性化配置外置(customDir 契约)
生成的 server 块不再内联 location /,改为只含证书骨架(listen / server_name /
ssl_certificate*),尾部以 include <customDir>/<domain>/*.conf 收口;站点级
location / root / 伪静态等个性化配置由运维放进该目录,脚本绝不内联、绝不覆盖。
默认目录 <confDir>/custom(生产 /www/wwwroot/nginx_config/custom、开发
D:/wms/nginx_config/custom),位于部署根上一级之外,发布回退不会触碰。

配置入口:新增 `--custom-dir` 参数、`CERT_SYNC_CUSTOM_DIR` 环境变量与配置键 customDir,
缺省即 <confDir>/custom;--help、参数解析默认值与启动日志同步补充。

目录维护(ensureCustomConf,幂等且绝不覆盖用户文件):
- 递归创建 <customDir>/<domain>/(0755),保证 server 块 include 的通配符始终合法
  (目录不存在 / 目录为空 / 目录有文件 三种情况 nginx -t 均通过,已在生产 nginx 1.28.0 实测);
- 目录内已有其它 *.conf → 视为用户自定义配置:不写默认文件,并删除脚本自产的
  00-default.conf(避免两个 location / 触发 nginx duplicate location);
- 目录内无其它 *.conf → 首次原子写默认文件 00-default.conf(0644,首行带脚本标记),
  已存在(无论是否被运维改过)一律不覆盖;
- 只有带脚本标记的文件才可能被删除,无标记文件一律不动;dry-run 只打印计划、不落盘。

其它:
- server 块内容校验放宽为「upstreamInclude 或 customGlobPath 命中即可」(upstream
  include 现在位于外置文件内,不再直接出现在 server 块里);
- 旧域名下线仍只删 confDir 根层的 server 块,custom/<domain>/ 目录保留不删
  (旧块删除后其 include 已失效,残留目录无副作用,可被运维移作他用)。
2026-09-27 03:13:21 +08:00

1938 lines
89 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';
/**
* 仓库前端证书同步脚本(nginx 部署器)。
*
* 职责:扫描 wms_warehouse_front_config 中 sync_status=0(待同步)的记录,
* 将 cert_pem / cert_key 内容写为证书文件,生成对应域名 server 块,
* 逐条 nginx -t 校验后统一 reload,并回写部署状态。
* 生成的 server 块只含证书骨架(listen / server_name / ssl_certificate*),
* 站点级个性化配置(location / root / 伪静态等)全部外置到 customDir 契约目录,
* 本脚本不在生成的 server 块内内联任何 location 指令。
* 另外承担「旧域名下线」(两阶段域名切换的应用侧配套,应用不碰 nginx 文件):
* - 消费 retired_domain:删除旧域名残留的 server 块与证书文件,删干净后才清空该槽位;
* - 孤儿兜底清理:以目录实际文件为准做差集,回收因 retired_domain 单槽位丢失而残留的旧产物;
* - 统计口径:汇总的「待删 / 已删文件数」按绝对路径去重后输出;通道命中数(retired_domain / orphan)
* 单独列示,两者之和大于去重数属预期(dry-run 不落盘,两条通道都会看到同一文件);
* - 只要本轮删过文件,就先 nginx -t 再 reload;-t 失败回滚本轮删除并保留 retired_domain 待下轮重试。
*
* 设计要点:
* - 每分钟被服务器侧 root crontab 调用(薄 shell 包装由部署 agent 适配),
* 必须幂等、可重入:重复执行会覆盖同名文件与 conf,无副作用。
* - 逐条失败隔离:单条写文件失败 / nginx -t 失败只回写该条
* sync_status=2 + last_sync_error + sync_attempts+1,不影响其他条目;
* nginx -t 失败时撤销本条 server 块,保证不拖垮整体 nginx。
* - reload 策略:本批有成功条目时执行一次 nginx -s reload;
* reload 失败时本批成功条目回退 sync_status=0(下分钟自动重试,
* sync_attempts 达到 RELOAD_FAILURE_MAX_RETRY 后转 sync_status=2 终止重试)。
* - 站点个性化配置外置:server 块尾部以 include <customDir>/<domain>/*.conf 收口,
* 脚本只负责该目录存在与默认反代文件(00-default.conf)的首次生成,
* 用户自定义 *.conf 一律保留、永不覆盖,详见「部署约定」customDir 契约。
* - 敏感红线:任何日志/错误输出不得打印 cert_pem / cert_key 内容,
* last_sync_error 统一做 PEM 片段脱敏 + 500 字符截断。
* - 文件权限:私钥 0600、证书/conf 0644;写文件采用「临时文件 + rename」原子写。
* - DB 读写全部参数化(sequelize replacements),禁止字符串拼接 SQL。
* - 数据库目标显式处理:--env 决定 WMS_DB_TARGET,先于 require 设置,
* 覆盖终端残留的 NODE_ENV,避免误连生产库。
*
* 部署约定(供部署 agent):
* - 脚本以部署根目录为 cwd 运行(薄 shell 包装中先 cd 到部署根目录)。
* - 双环境外部配置文件(随代码 git 提交,发布时严禁覆盖/删除/改写):
* script/warehouse-cert-sync.config.dev.json 开发环境(本机宝塔 Windows nginx)
* script/warehouse-cert-sync.config.prod.json 生产环境(服务器宝塔构建 nginx,systemd)
* 按 --env 自动选择;所选配置缺失或 JSON 非法一律致命退出(exit 1),
* 生产环境宁可不跑也不猜,开发环境同样显式报错而非静默回退。
* - 参数优先级:CLI 参数 > 环境变量 > 外部配置文件 > 内置默认。
* - 证书目录 / nginx server 块目录 / upstream include / nginx 二进制 /
* reload 与 -t 命令默认全部来自配置文件;生产配置中 certDir/confDir 相对
* cwd(部署根 /www/wwwroot/qimen)解析为 ../.ssl 与 ../nginx_config,
* 目录不存在时自动递归创建;nginx 主配置由运维自行 include ../nginx_config/*.conf,
* 本脚本不管理主配置。
* - customDir 契约(站点个性化配置外置,运维改站点只需动这里):
* - 一域名一目录:<customDir>/<domain>/(目录名沿用文件名清洗推导,
* 清洗后与原域名不一致时带 _短哈希8 防碰撞);
* - 生成块尾部 include <customDir>/<domain>/*.conf(通配符:目录不存在 /
* 目录为空 / 目录有文件三种情况 nginx -t 均通过,已在生产 nginx 1.28.0 实测);
* - 默认文件 <customDir>/<domain>/00-default.conf(0644 原子写):仅当目录内
* 没有其它 *.conf 时由脚本写入一次,之后永不覆盖;内容为默认反代
* (include upstream + Host / X-Warehouse-Domain 头),首行带脚本标记;
* - 放自定义文件(实现 root + 伪静态等):把任意命名的 *.conf 放进该域名目录;
* 一旦存在自定义 *.conf,脚本不再写默认文件,并自动删除脚本自产的
* 00-default.conf(避免两个 location / 触发 nginx duplicate location);
* 只有带脚本标记的 00-default.conf 才会被删除,无标记文件一律不动;
* - customDir 默认 <confDir>/custom(生产 /www/wwwroot/nginx_config/custom、
* 开发 D:/wms/nginx_config/custom),位于部署根上一级之外,发布回退不会触碰;
* - 旧域名下线只删 confDir 根层的 server 块,custom/<domain>/ 目录保留不删
* (旧 server 块删除后其 include 已失效,残留目录无副作用,可能被运维移作他用)。
* - 自定义命令占位符:{nginxBin} 与 {nginxPrefix}(-p 前缀目录,win32 宝塔 nginx
* 防 cwd 劫持),替换时自动按平台加引号;覆盖命令经 shell 执行。
* - 建议 crontab 每分钟调用一次薄 shell 包装(crontab 安装由部署 agent 负责)。
*
* 用法:
* node script/warehouse-cert-sync.cjs --env development --skip-nginx --dry-run
* node script/warehouse-cert-sync.cjs --env development \
* --cert-dir <临时目录> --conf-dir <临时目录> --skip-nginx \
* --nginx-bin <fake-nginx> --reload-cmd <覆盖命令>
* node script/warehouse-cert-sync.cjs --env production
* node script/warehouse-cert-sync.cjs --env production --dry-run
* node script/warehouse-cert-sync.cjs --env production --cleanup-only
* node script/warehouse-cert-sync.cjs --env production --cleanup-only --dry-run
*
* 退出码约定(供 crontab 告警):
* 0 正常:无待处理行、本批全部成功、dry-run 完成;
* 1 致命:参数非法 / DB 连接失败 / 目录不可建 / 生产环境 nginx 缺失;
* 2 业务级失败:本批存在条目处理失败或 nginx reload 失败(详情已回写 DB)。
*/
const fs = require('node:fs');
const path = require('node:path');
const crypto = require('node:crypto');
const { spawnSync } = require('node:child_process');
const Sequelize = require('sequelize');
const PROJECT_ROOT = path.resolve(__dirname, '..');
const DB_CONFIG_PATH = path.join(PROJECT_ROOT, 'database', 'config.js');
// 部署约定默认目录:相对脚本运行时 cwd(部署根目录)的上一级,
// path.resolve(process.cwd(), ...) 在运行时解析为绝对路径;
// nginx 主配置由运维自行 include 该 conf 目录,本脚本不管理主配置。
const DEFAULT_CERT_DIR = path.resolve(process.cwd(), '..', '.ssl');
const DEFAULT_CONF_DIR = path.resolve(process.cwd(), '..', 'nginx_config');
const DEFAULT_UPSTREAM_INCLUDE = 'nginx-upstream.conf';
const DEFAULT_NGINX_BIN = 'nginx';
const DEFAULT_LIMIT = 50;
// 双环境外部配置文件:按 --env 选择(文件随代码 git 提交,发布时不得覆盖删除)。
// development → 本机宝塔 Windows nginx(nginx.exe + -p 前缀);production → 服务器宝塔构建 nginx(systemd)。
const ENV_CONFIG_FILE = {
development: path.join(__dirname, 'warehouse-cert-sync.config.dev.json'),
production: path.join(__dirname, 'warehouse-cert-sync.config.prod.json'),
};
const NGINX_CMD_TIMEOUT_MS = 30 * 1000;
const LAST_SYNC_ERROR_MAX_LENGTH = 500;
const RELOAD_FAILURE_MAX_RETRY = 5;
const DOMAIN_MAX_LENGTH = 253;
const DOMAIN_PATTERN = /^[A-Za-z0-9*._-]+$/;
const PEM_CERT_MARK = 'BEGIN CERTIFICATE';
const PEM_KEY_MARK = 'PRIVATE KEY';
const EXIT_OK = 0;
const EXIT_FATAL = 1;
const EXIT_BUSINESS_FAILURE = 2;
const CERT_FILE_MODE = 0o644;
const KEY_FILE_MODE = 0o600;
const CUSTOM_DIR_MODE = 0o755;
const CUSTOM_CONF_FILE_MODE = 0o644;
const DEFAULT_CUSTOM_CONF_NAME = '00-default.conf';
const DEFAULT_CUSTOM_CONF_MARKER = '由 warehouse-cert-sync 生成的默认站点配置';
const TABLE_NAME = 'wms_warehouse_front_config';
// ---- 旧域名下线 / 孤儿兜底清理相关常量 ----
// conf 文件名形态:{domainSafe}{[_短哈希8]}.conf(与 buildConfFileName 产物一致,仅作第一道形态闸门)
const CONF_FILE_NAME_PATTERN = /^[A-Za-z0-9._-]+?(?:_[0-9a-f]{8})?\.conf$/;
// 证书 / 私钥文件名形态:{store_id}_{domainSafe}{[_短哈希8]}.pem|.key
const CERT_FILE_NAME_PATTERN = /^[A-Za-z0-9]+_[A-Za-z0-9._-]+?(?:_[0-9a-f]{8})?\.(?:pem|key)$/;
// server_name 指令解析(取第一条 server_name 的域名)
const SERVER_NAME_PATTERN = /^[ \t]*server_name[ \t]+([^;]+);/m;
/**
* 单条处理结果统计。
* @typedef {Object} SyncStats
* @property {number} total 本批扫描到的待同步条数。
* @property {number} success 成功条数。
* @property {number} failed 失败条数。
*/
/**
* 命令行参数集合。
* @typedef {Object} SyncArgs
* @property {string} env 数据库环境标记:development | production。
* @property {string} configPath 生效的外部配置文件绝对路径。
* @property {boolean} dryRun 仅扫描与输出计划,不写文件、不改库。
* @property {boolean} cleanupOnly 只做旧域名下线与孤儿兜底清理,不做证书同步(--cleanup-only)。
* @property {boolean} skipNginx 跳过 nginx -t / reload。
* @property {string} certDir 证书输出目录(绝对路径)。
* @property {string} confDir nginx server 块目录(绝对路径)。
* @property {string} customDir 站点个性化配置外置目录(绝对路径,默认 <confDir>/custom)。
* @property {string} upstreamInclude upstream 配置文件 include 名。
* @property {number} limit 单次处理条数上限。
* @property {string} nginxBin nginx 可执行文件路径。
* @property {string} nginxPrefix nginx -p 前缀目录(空串表示不启用)。
* @property {string} reloadCmd nginx reload 命令覆盖(空串按系统类型推导)。
* @property {string} testCmd nginx -t 校验命令覆盖(空串按系统类型推导)。
* @property {boolean} help 是否打印帮助。
*/
/**
* nginx 命令执行描述(由 buildNginxCommand 统一产出)。
* @typedef {Object} NginxCommandDesc
* @property {string} command 命令字符串(shell 模式)或可执行文件路径(直连模式)。
* @property {string[]} args 直连模式的参数数组(shell 模式为空数组)。
* @property {boolean} shell 是否经 shell 执行(true 时 command 为完整命令字符串)。
*/
/**
* 脚本运行上下文(参数、DB 连接、nginx 可用性等)。
* @typedef {Object} SyncContext
* @property {SyncArgs} args 解析后的命令行参数。
* @property {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @property {boolean} nginxMissing nginx 二进制缺失(开发环境自动降级)。
* @property {NginxCommandDesc} testCommand nginx -t 校验命令执行描述。
* @property {NginxCommandDesc} reloadCommand nginx reload 命令执行描述。
*/
/**
* 打印帮助信息(stdout)。
* @return {void}
*/
function printUsage() {
const text = [
'仓库前端证书同步脚本(nginx 部署器)',
'',
'用法: node script/warehouse-cert-sync.cjs --env <development|production> [选项]',
'',
'环境配置文件(按 --env 自动加载,随代码提交,发布时不得覆盖删除):',
' script/warehouse-cert-sync.config.dev.json 开发环境(本机宝塔 Windows nginx)',
' script/warehouse-cert-sync.config.prod.json 生产环境(服务器宝塔构建 nginx,systemd)',
' 所选配置缺失或 JSON 非法将致命退出(exit 1),生产环境宁可不跑也不猜。',
' 支持键: nginxBin / nginxPrefix / certDir / confDir / customDir / upstreamInclude / testCmd / reloadCmd',
' (customDir 可缺省,缺省即 <confDir>/custom)',
'',
'参数优先级: CLI 参数 > 环境变量 > 外部配置文件 > 内置默认',
'',
'选项:',
' --env <env> 运行环境(必填,显式指定,不受终端 NODE_ENV 残留影响,同时决定数据库与配置文件)',
' --dry-run 仅扫描并输出计划,不写文件、不改库(含旧域名下线/孤儿清理的待删清单)',
' --cleanup-only 只做旧域名下线与孤儿兜底清理,不做证书同步(供运维单独执行)',
' --cert-dir <path> 证书输出目录(默认取配置文件或 ../.ssl,相对路径按 cwd 解析)',
' --conf-dir <path> nginx server 块目录(默认取配置文件或 ../nginx_config,同样按 cwd 解析)',
' --custom-dir <path> 站点个性化配置外置目录(默认取配置文件或 <confDir>/custom,按 cwd 解析)',
' --upstream-include <v> 默认站点配置(custom/<域名>/00-default.conf)include 的 upstream 配置名',
' (默认取配置文件或 nginx-upstream.conf)',
' --skip-nginx 跳过 nginx -t 校验与 nginx reload(开发/测试用)',
' --nginx-bin <path> nginx 可执行文件路径(默认取配置文件或 PATH 中的 nginx)',
' --nginx-prefix <path> nginx -p 前缀目录(win32 宝塔 nginx 防 cwd 劫持,默认取配置文件)',
' --reload-cmd <cmd> reload 命令覆盖(默认按系统类型推导 "{nginxBin} -s reload";',
' 支持 {nginxBin} / {nginxPrefix} 占位符且自动按平台加引号;',
' linux 可传 "systemctl reload nginx")',
' --test-cmd <cmd> nginx -t 校验命令覆盖(默认按系统类型推导 "{nginxBin} -t",语义同上)',
' --limit <n> 单次处理条数上限(默认 50)',
' --help, -h 打印本帮助',
'',
'环境变量(优先级高于配置文件、低于命令行参数):',
' CERT_SYNC_ENV / CERT_SYNC_CERT_DIR / CERT_SYNC_CONF_DIR / CERT_SYNC_CUSTOM_DIR',
' CERT_SYNC_UPSTREAM_INCLUDE / CERT_SYNC_LIMIT / CERT_SYNC_NGINX_BIN / CERT_SYNC_NGINX_PREFIX',
' CERT_SYNC_RELOAD_CMD / CERT_SYNC_TEST_CMD',
' WMS_DB_TARGET / DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME(透传 database/config.js)',
'',
'退出码: 0 正常;1 致命错误;2 业务级失败(条目失败或 reload 失败,供 cron 告警)',
].join('\n');
console.log(text);
}
/**
* 加载 --env 对应的外部配置文件(双环境外部配置文件机制)。
* 文件随代码 git 提交;所选配置缺失或 JSON 非法一律视为致命错误,
* 生产环境宁可不跑也不猜,开发环境同样显式报错而非静默回退内置默认。
* @param {string} env 数据库环境标记:development | production。
* @return {{configPath: string, config: Object}} 配置文件绝对路径与解析后的配置对象。
* @throws {Error} 配置文件缺失、JSON 非法或顶层结构非对象时抛出异常(触发退出码 1)。
*/
function loadEnvConfig(env) {
const configPath = ENV_CONFIG_FILE[env];
let rawText = '';
try {
rawText = fs.readFileSync(configPath, 'utf8');
} catch (error) {
throw new Error(`环境配置文件缺失: ${configPath}(--env=${env} 必须搭配对应配置文件;生产环境宁可不跑也不猜,请恢复该文件或改用显式 CLI 参数覆盖)`);
}
let config = null;
try {
config = JSON.parse(rawText);
} catch (error) {
throw new Error(`环境配置文件 JSON 非法: ${configPath} - ${error.message}`);
}
if (!config || typeof config !== 'object' || Array.isArray(config)) {
throw new Error(`环境配置文件结构非法: ${configPath}(顶层必须是 JSON 对象)`);
}
return { configPath, config };
}
/**
* 解析命令行参数:CLI 参数 > 环境变量 > 外部配置文件 > 内置默认(优先级从高到低)。
* 先解析 CLI 原始值,再按 --env 加载外部配置文件作为默认值来源,
* 最后统一应用优先级回填缺省字段(目录类值经 path.resolve 解析为绝对路径)。
* @param {string[]} argv process.argv.slice(2) 结果。
* @return {SyncArgs} 解析后的参数集合。
* @throws {Error} 参数非法或配置文件缺失/非法时抛出异常(触发退出码 1)。
*/
function parseArgs(argv) {
const cli = {
env: '',
certDir: '',
confDir: '',
customDir: '',
upstreamInclude: '',
nginxBin: '',
nginxPrefix: '',
reloadCmd: '',
testCmd: '',
limit: null,
dryRun: false,
cleanupOnly: false,
skipNginx: false,
help: false,
};
for (let index = 0; index < argv.length; index++) {
const item = argv[index];
const eqIndex = item.indexOf('=');
const key = eqIndex >= 0 ? item.slice(0, eqIndex) : item;
const inlineValue = eqIndex >= 0 ? item.slice(eqIndex + 1) : null;
const readValue = () => {
if (inlineValue !== null) {
return inlineValue;
}
if (index + 1 >= argv.length) {
throw new Error(`参数 ${key} 缺少值`);
}
index++;
return argv[index];
};
if (key === '--help' || key === '-h') {
cli.help = true;
} else if (key === '--dry-run') {
cli.dryRun = true;
} else if (key === '--cleanup-only') {
cli.cleanupOnly = true;
} else if (key === '--skip-nginx') {
cli.skipNginx = true;
} else if (key === '--env') {
cli.env = String(readValue() || '').trim();
} else if (key === '--cert-dir') {
cli.certDir = String(readValue() || '').trim();
} else if (key === '--conf-dir') {
cli.confDir = String(readValue() || '').trim();
} else if (key === '--custom-dir') {
cli.customDir = String(readValue() || '').trim();
} else if (key === '--upstream-include') {
cli.upstreamInclude = String(readValue() || '').trim();
} else if (key === '--nginx-bin') {
cli.nginxBin = String(readValue() || '').trim();
} else if (key === '--nginx-prefix') {
cli.nginxPrefix = String(readValue() || '').trim();
} else if (key === '--reload-cmd') {
cli.reloadCmd = String(readValue() || '').trim();
} else if (key === '--test-cmd') {
cli.testCmd = String(readValue() || '').trim();
} else if (key === '--limit') {
cli.limit = Number(readValue());
} else {
throw new Error(`未知参数: ${item}`);
}
}
if (cli.help) {
return {
env: cli.env || String(process.env.CERT_SYNC_ENV || '').trim(),
configPath: '',
certDir: '',
confDir: '',
customDir: '',
upstreamInclude: '',
nginxBin: '',
nginxPrefix: '',
reloadCmd: '',
testCmd: '',
limit: DEFAULT_LIMIT,
dryRun: cli.dryRun,
cleanupOnly: cli.cleanupOnly,
skipNginx: cli.skipNginx,
help: true,
};
}
const env = cli.env || String(process.env.CERT_SYNC_ENV || '').trim();
if (env !== 'development' && env !== 'production') {
throw new Error('必须通过 --env 显式指定运行环境:development | production');
}
// 外部配置文件作为默认值来源(优先级低于 CLI 参数与环境变量)
const { configPath, config } = loadEnvConfig(env);
// 优先级:CLI 参数 > 环境变量 > 外部配置文件 > 内置默认
const pickString = (cliValue, envName, configValue, fallback) => {
const envValue = String(process.env[envName] || '').trim();
const configString = configValue === undefined || configValue === null ? '' : String(configValue).trim();
const value = cliValue || envValue || configString || fallback;
return String(value).trim();
};
// customDir 缺省值依赖 confDir(<confDir>/custom),故先解析 confDir 再回填
const confDir = path.resolve(pickString(cli.confDir, 'CERT_SYNC_CONF_DIR', config.confDir, DEFAULT_CONF_DIR));
const customDirRaw = pickString(cli.customDir, 'CERT_SYNC_CUSTOM_DIR', config.customDir, '');
const customDir = customDirRaw ? path.resolve(customDirRaw) : path.join(confDir, 'custom');
const args = {
env,
configPath,
dryRun: cli.dryRun,
cleanupOnly: cli.cleanupOnly,
skipNginx: cli.skipNginx,
help: false,
certDir: path.resolve(pickString(cli.certDir, 'CERT_SYNC_CERT_DIR', config.certDir, DEFAULT_CERT_DIR)),
confDir,
customDir,
upstreamInclude: pickString(cli.upstreamInclude, 'CERT_SYNC_UPSTREAM_INCLUDE', config.upstreamInclude, DEFAULT_UPSTREAM_INCLUDE),
nginxBin: pickString(cli.nginxBin, 'CERT_SYNC_NGINX_BIN', config.nginxBin, DEFAULT_NGINX_BIN),
nginxPrefix: pickString(cli.nginxPrefix, 'CERT_SYNC_NGINX_PREFIX', config.nginxPrefix, ''),
reloadCmd: pickString(cli.reloadCmd, 'CERT_SYNC_RELOAD_CMD', config.reloadCmd, ''),
testCmd: pickString(cli.testCmd, 'CERT_SYNC_TEST_CMD', config.testCmd, ''),
limit: cli.limit !== null ? cli.limit : (Number(process.env.CERT_SYNC_LIMIT) || DEFAULT_LIMIT),
};
if (!Number.isInteger(args.limit) || args.limit <= 0) {
throw new Error(`--limit 必须是正整数,当前值: ${args.limit}`);
}
if (!args.upstreamInclude) {
throw new Error('--upstream-include 不能为空');
}
if (!args.nginxBin) {
throw new Error('--nginx-bin 不能为空');
}
return args;
}
/**
* 按 --env 显式设置数据库连接目标,覆盖终端残留的 NODE_ENV。
* WMS_DB_TARGET 优先级高于 NODE_ENV(database/config.js 约定),
* 在 require database/config.js 之前调用本函数即可消除残留风险。
* @param {SyncArgs} args 解析后的参数集合。
* @return {void}
*/
function applyDbTarget(args) {
const target = args.env === 'production' ? 'production' : 'development';
process.env.WMS_DB_TARGET = target;
const residue = process.env.NODE_ENV;
if (residue && String(residue).trim().toLowerCase() !== String(target).toLowerCase()) {
console.warn(`[CERT-SYNC] 检测到终端残留 NODE_ENV=${residue},已由 --env=${args.env} 显式覆盖(WMS_DB_TARGET=${target})`);
}
}
/**
* 加载 database/config.js 并创建 Sequelize 实例。
* @param {SyncArgs} args 解析后的参数集合。
* @return {import('sequelize').Sequelize} Sequelize 实例。
* @throws {Error} 配置加载失败时抛出异常。
*/
function connectDb(args) {
const dbConfigAll = require(DB_CONFIG_PATH);
const cfg = dbConfigAll[args.env] || dbConfigAll.production;
if (!cfg || !cfg.host) {
throw new Error('数据库配置解析失败,请检查 --env 与 config 文件');
}
const sequelize = new Sequelize(cfg.database, cfg.username, cfg.password, {
host: cfg.host,
port: cfg.port,
dialect: cfg.dialect || 'mysql',
logging: false,
define: cfg.define,
pool: cfg.pool,
});
console.log(`[CERT-SYNC] 数据库目标: ${args.env} -> ${cfg.host}:${cfg.port}/${cfg.database}`);
return sequelize;
}
/**
* 统一构造 nginx 命令执行描述(系统类型分支集中在唯一入口)。
*
* 分支策略:
* - 自定义命令(reloadCmd / testCmd 覆盖)非空:优先采用覆盖命令字符串,
* 经 shell 执行(win32 由 cmd.exe 包装、POSIX 由 /bin/sh 包装),
* 覆盖 systemctl 等非标准 reload 场景;{nginxBin} / {nginxPrefix} 占位符
* 替换时自动按平台加引号(win32 双引号、POSIX 单引号),
* 避免路径被 shell 按空白/斜杠二次切分。
* - win32:nginx 二进制为 .cmd/.bat 批处理时不能被 spawnSync 直接执行,
* 保持经 shell 包装整条命令(参数做引号转义)的执行方式。
* - linux / darwin / 其他 POSIX:spawnSync(nginxBin, args, shell=false)
* 原样执行,避免 shell 注入与引号歧义。
* @param {string} nginxBin nginx 可执行文件路径。
* @param {string} nginxPrefix nginx -p 前缀目录(空串表示不启用,供 {nginxPrefix} 占位符使用)。
* @param {string[]} args nginx 参数数组(默认推导场景)。
* @param {string} customCommand 自定义覆盖命令(空串表示使用默认推导)。
* @return {NginxCommandDesc} 命令执行描述。
* @throws {Error} 自定义命令含 {nginxPrefix} 占位符但未提供 nginxPrefix 时抛出异常。
*/
function buildNginxCommand(nginxBin, nginxPrefix, args, customCommand) {
if (customCommand) {
if (String(customCommand).includes('{nginxPrefix}') && !nginxPrefix) {
throw new Error('自定义命令包含 {nginxPrefix} 占位符,但未配置 nginx prefix(--nginx-prefix / CERT_SYNC_NGINX_PREFIX / 配置文件 nginxPrefix)');
}
// 占位符替换时自动按平台加引号,防止路径被 shell 按空白/斜杠二次切分
const quoteShellValue = value => (process.platform === 'win32'
? `"${String(value).replace(/"/g, '')}"`
: `'${String(value).replace(/'/g, '')}'`);
return {
command: String(customCommand)
.split('{nginxBin}')
.join(quoteShellValue(nginxBin))
.split('{nginxPrefix}')
.join(quoteShellValue(nginxPrefix)),
args: [],
shell: true,
};
}
const isWindowsBatch = process.platform === 'win32' && /\.(cmd|bat)$/i.test(nginxBin);
if (isWindowsBatch) {
const quote = value => `"${String(value).replace(/"/g, '')}"`;
return {
command: `${quote(nginxBin)} ${args.map(quote).join(' ')}`,
args: [],
shell: true,
};
}
return {
command: nginxBin,
args,
shell: false,
};
}
/**
* 执行 nginx 命令的底层 spawnSync 封装。
* 仅消费 buildNginxCommand 产出的执行描述,不做任何平台判断。
* @param {NginxCommandDesc} commandDesc nginx 命令执行描述。
* @return {import('node:child_process').SpawnSyncReturns<string>} spawnSync 原始结果。
*/
function spawnNginxRaw(commandDesc) {
if (commandDesc.shell) {
return spawnSync(commandDesc.command, {
encoding: 'utf8',
timeout: NGINX_CMD_TIMEOUT_MS,
shell: true,
});
}
return spawnSync(commandDesc.command, commandDesc.args, {
encoding: 'utf8',
timeout: NGINX_CMD_TIMEOUT_MS,
});
}
/**
* 探测 nginx 二进制是否可用(ENOENT 判定缺失)。
* @param {string} nginxBin nginx 可执行文件路径。
* @param {string} nginxPrefix nginx -p 前缀目录(空串表示不启用)。
* @return {boolean} 可用返回 true,缺失返回 false。
*/
function nginxBinExists(nginxBin, nginxPrefix) {
const result = spawnNginxRaw(buildNginxCommand(nginxBin, nginxPrefix, [ '-v' ], ''));
return !(result.error && result.error.code === 'ENOENT');
}
/**
* 探测 wms_warehouse_front_config 是否已有 domain_status 列。
*
* 域名验证闸门依赖该列;脚本部署早于迁移时该列不存在,需降级为不按验证状态过滤,
* 保证脚本可在迁移前先行部署(与 app/service/systems/frontConfig.js 的降级策略一致)。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @return {Promise<boolean>} 存在返回 true;探测失败返回 false。
*/
async function hasDomainStatusColumn(sequelize) {
try {
const rows = await sequelize.query(
`SELECT COUNT(*) AS c FROM information_schema.columns
WHERE table_schema = DATABASE() AND table_name = ? AND column_name = 'domain_status'`,
{ replacements: [ TABLE_NAME ], type: Sequelize.QueryTypes.SELECT }
);
return Number(rows && rows[0] && rows[0].c) > 0;
} catch (error) {
console.warn(`[CERT-SYNC] domain_status 列探测失败(按无该列降级): ${sanitizeErrorText(error.message)}`);
return false;
}
}
/**
* 扫描待同步记录(sync_status=0、且域名已验证 domain_status=1,按 id 升序,limit 条)。
*
* 域名验证闸门:未通过验证(domain_status 为 0/2)的域名不生成 nginx server 块;
* filterVerifiedDomain 为 false 时(迁移尚未执行、无 domain_status 列)降级为不过滤。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @param {number} limit 单次处理条数上限。
* @param {boolean} [filterVerifiedDomain] 是否只取已验证域名,默认 true。
* @return {Promise<Object[]>} 待同步记录数组。
*/
async function scanPendingRows(sequelize, limit, filterVerifiedDomain = true) {
const verifiedFilter = filterVerifiedDomain ? ' AND domain_status = 1' : '';
return sequelize.query(
`SELECT id, store_id, domain, cert_pem, cert_key, cert_expire_at, sync_attempts
FROM ${TABLE_NAME}
WHERE sync_status = 0${verifiedFilter}
ORDER BY id ASC
LIMIT ?`,
{ replacements: [ limit ], type: Sequelize.QueryTypes.SELECT }
);
}
/**
* 将域名清洗为安全的文件名片段(非法字符替换为下划线)。
* @param {string} input 原始域名。
* @return {string} 清洗后的片段,空结果返回 'unknown'。
*/
function sanitizeFileNameSegment(input) {
const cleaned = String(input || '').replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
return cleaned || 'unknown';
}
/**
* 计算域名的 8 位短哈希(仅当域名被清洗后与原名不一致时用于防碰撞)。
* @param {string} domain 原始域名。
* @return {string} 8 位十六进制哈希。
*/
function shortHash(domain) {
return crypto.createHash('md5')
.update(String(domain))
.digest('hex')
.slice(0, 8);
}
/**
* 域名命名推导(写盘与下线清理共用的唯一入口)。
* 命名规则:domain 做非法字符清洗得到 domainSafe;清洗后与原名不一致时
* 追加 _短哈希8 防不同域名清洗后碰撞(如 *.a.com 会被清洗为 .a.com)。
* @param {string} domainRaw 原始域名(已 trim)。
* @return {{domainSafe: string, suffix: string}} 命名片段(suffix 为空串或 _短哈希8)。
*/
function computeDomainNameParts(domainRaw) {
const domainSafe = sanitizeFileNameSegment(domainRaw);
const changed = domainSafe !== domainRaw;
return {
domainSafe,
suffix: changed ? `_${shortHash(domainRaw)}` : '',
};
}
/**
* 推导域名对应的 server 块文件名({domainSafe}{suffix}.conf)。
* 写入(buildFileNames)与删除(旧域名下线 / 孤儿兜底清理)共用本推导,
* 保证「按名删除」与「按名写入」严格一致。
* @param {string} domainRaw 原始域名(已 trim)。
* @return {string} conf 文件名(不含目录)。
*/
function buildConfFileName(domainRaw) {
const parts = computeDomainNameParts(domainRaw);
return `${parts.domainSafe}${parts.suffix}.conf`;
}
/**
* 推导证书 / 私钥文件名前缀({store_id}_{domainSafe}{suffix})。
* @param {number|string} storeId 仓库 ID。
* @param {string} domainRaw 原始域名(已 trim)。
* @return {string} baseName(不含扩展名与目录)。
*/
function buildCertBaseName(storeId, domainRaw) {
const parts = computeDomainNameParts(domainRaw);
return `${storeId}_${parts.domainSafe}${parts.suffix}`;
}
/**
* 推导域名的站点个性化配置外置路径(customDir 契约,一域名一目录)。
* 目录名与 server 块 / 证书文件共用同一套命名推导(computeDomainNameParts),
* 保证「生成块 include 的目录」与「脚本维护的目录」严格一致。
* @param {SyncArgs} args 解析后的参数集合。
* @param {string} domainRaw 原始域名(已 trim)。
* @return {{customDirPath: string, customGlobPath: string, defaultPath: string}} 外置配置路径集合。
*/
function buildCustomPaths(args, domainRaw) {
const parts = computeDomainNameParts(domainRaw);
const customDirPath = path.join(args.customDir, `${parts.domainSafe}${parts.suffix}`);
return {
customDirPath,
customGlobPath: path.join(customDirPath, '*.conf'),
defaultPath: path.join(customDirPath, DEFAULT_CUSTOM_CONF_NAME),
};
}
/**
* 生成一条记录的文件名与落盘路径(命名推导见 computeDomainNameParts)。
* @param {SyncArgs} args 解析后的参数集合。
* @param {number} storeId 仓库 ID。
* @param {string} domainRaw 原始域名(已 trim)。
* @return {{baseName: string, certPath: string, keyPath: string, confPath: string,
* customDirPath: string, customGlobPath: string}} 文件路径集合。
*/
function buildFileNames(args, storeId, domainRaw) {
const baseName = buildCertBaseName(storeId, domainRaw);
const customPaths = buildCustomPaths(args, domainRaw);
return {
baseName,
certPath: path.join(args.certDir, `${baseName}.pem`),
keyPath: path.join(args.certDir, `${baseName}.key`),
confPath: path.join(args.confDir, buildConfFileName(domainRaw)),
customDirPath: customPaths.customDirPath,
customGlobPath: customPaths.customGlobPath,
};
}
/**
* 校验单条记录的 domain 与证书/私钥内容(不做加密学解析,仅做安全与形态校验)。
* @param {string} domainRaw 原始域名。
* @param {*} certPem 证书 PEM 内容。
* @param {*} keyPem 私钥 PEM 内容。
* @return {string|null} 校验失败返回错误描述,通过返回 null。
*/
function validateRowContent(domainRaw, certPem, keyPem) {
if (!domainRaw) {
return 'domain 为空,无法生成文件名与 server 块';
}
if (domainRaw.length > DOMAIN_MAX_LENGTH || !DOMAIN_PATTERN.test(domainRaw)) {
return `domain 含非法字符或超长(${domainRaw.length} 字符)`;
}
const cert = String(certPem || '').trim();
const key = String(keyPem || '').trim();
if (!cert) {
return 'cert_pem 内容为空';
}
if (!key) {
return 'cert_key 内容为空';
}
if (!cert.includes(PEM_CERT_MARK)) {
return `cert_pem 缺少 ${PEM_CERT_MARK} 标记,不是合法证书 PEM`;
}
if (!key.includes(PEM_KEY_MARK)) {
return `cert_key 缺少 ${PEM_KEY_MARK} 标记,不是合法私钥 PEM`;
}
return null;
}
/**
* 生成 server 块内容(仅证书骨架 + 外置站点配置 include,不含任何 location)。
* 站点级 location / root / 伪静态等个性化配置由运维放入 <customDir>/<domain>/ 下的
* *.conf,本脚本绝不内联也不覆盖。
* @param {string} domain 域名(已通过白名单校验)。
* @param {string} certPath 证书文件绝对路径。
* @param {string} keyPath 私钥文件绝对路径。
* @param {string} customGlobPath 站点个性化配置外置目录通配路径(<customDir>/<domain>/*.conf)。
* @return {string} server 块文本。
*/
function buildServerConf(domain, certPath, keyPath, customGlobPath) {
return `server {
listen 443 ssl;
server_name ${domain};
ssl_certificate ${certPath};
ssl_certificate_key ${keyPath};
include ${customGlobPath};
}
`;
}
/**
* 生成默认站点配置内容(customDir 契约的 00-default.conf)。
* 仅在目录内没有其它 *.conf 时由脚本写入一次,之后不再覆盖;
* 首行标记同时用作「脚本自产」判定,确保清理时不会误删用户文件。
* @param {string} upstreamInclude upstream 配置文件 include 名。
* @return {string} 默认站点配置文本。
*/
function buildDefaultCustomConf(upstreamInclude) {
return `# ${DEFAULT_CUSTOM_CONF_MARKER}:仅在目录内无其它 *.conf 时写入,之后不再覆盖。
location / {
include ${upstreamInclude};
proxy_set_header Host $host;
proxy_set_header X-Warehouse-Domain $host;
}
`;
}
/**
* 确保域名的站点个性化配置外置目录与默认文件就绪(customDir 契约)。
*
* 规则(幂等、绝不覆盖用户配置):
* 1. 递归创建 <customDir>/<domain>/ 目录(0755),保证生成块的 include 通配符合法;
* dry-run 不建目录,只打印计划;
* 2. 目录内已有其它 *.conf(默认文件除外)→ 视为用户自定义配置,一律保留:
* - 不写入默认文件;
* - 若存在「脚本自产」的 00-default.conf(内容含脚本标记),删除之,
* 避免两个 location / 触发 nginx duplicate location;无标记的 00-default.conf
* 视为用户文件,不删不动(只有脚本自产默认文件允许被本函数删除);
* 3. 目录内无其它 *.conf → 确保默认文件存在:不存在则原子写 00-default.conf(0644),
* 已存在(无论是否被修改过)一律不覆盖。
* @param {SyncArgs} args 解析后的参数集合。
* @param {string} domainRaw 原始域名(已 trim)。
* @return {{dirPath: string, defaultPath: string, hasCustom: boolean}} 目录 / 默认文件 / 是否已存在用户自定义配置。
*/
function ensureCustomConf(args, domainRaw) {
const paths = buildCustomPaths(args, domainRaw);
if (args.dryRun) {
console.log(`[CERT-SYNC][CUSTOM] 计划: 确保目录存在(mkdir -p 0755)-> ${paths.customDirPath}`);
} else {
try {
fs.mkdirSync(paths.customDirPath, { recursive: true, mode: CUSTOM_DIR_MODE });
} catch (error) {
throw new Error(`创建站点个性化配置目录失败: ${paths.customDirPath} - ${error.message}`);
}
}
// 扫描目录内现有 *.conf;dry-run 未建目录(ENOENT)按空目录处理
let confNames = [];
try {
confNames = fs.readdirSync(paths.customDirPath, { withFileTypes: true })
.filter(entry => entry.isFile() && /\.conf$/i.test(entry.name))
.map(entry => entry.name);
} catch (error) {
if (!args.dryRun || !error || error.code !== 'ENOENT') {
throw error;
}
}
const otherNames = confNames.filter(name => name !== DEFAULT_CUSTOM_CONF_NAME);
const hasDefaultFile = confNames.includes(DEFAULT_CUSTOM_CONF_NAME);
// 已有用户自定义 *.conf:保留;顺带清掉脚本自产的默认文件(避免 duplicate location)
if (otherNames.length > 0) {
console.log(`[CERT-SYNC][CUSTOM] 已存在用户自定义配置 ${otherNames.length} 个(${otherNames.slice(0, 3).join(', ')}${otherNames.length > 3 ? ' …' : ''}),保留,不写入默认文件: ${paths.customDirPath}`);
if (hasDefaultFile) {
const defaultContent = readTextFileOrNull(paths.defaultPath);
if (defaultContent !== null && defaultContent.includes(DEFAULT_CUSTOM_CONF_MARKER)) {
if (args.dryRun) {
console.log(`[CERT-SYNC][CUSTOM] 计划: 删除脚本自产的默认文件(已有用户自定义配置,避免 duplicate location)-> ${paths.defaultPath}`);
} else {
removeFileQuiet(paths.defaultPath);
console.log(`[CERT-SYNC][CUSTOM] 已删除脚本自产的默认文件(已有用户自定义配置,避免 nginx duplicate location): ${paths.defaultPath}`);
}
} else {
console.warn(`[CERT-SYNC][CUSTOM][WARN] 默认文件存在但无脚本标记(非脚本自产),不删不动,请自行确认是否与用户配置冲突: ${paths.defaultPath}`);
}
}
return { dirPath: paths.customDirPath, defaultPath: paths.defaultPath, hasCustom: true };
}
// 目录内没有用户自定义:确保默认文件存在(已存在一律不覆盖)
if (hasDefaultFile) {
const defaultContent = readTextFileOrNull(paths.defaultPath);
if (defaultContent !== null && defaultContent.includes(DEFAULT_CUSTOM_CONF_MARKER)) {
console.log(`[CERT-SYNC][CUSTOM] 默认站点配置已存在(脚本自产),保持不变: ${paths.defaultPath}`);
} else {
console.warn(`[CERT-SYNC][CUSTOM][WARN] 默认文件已存在但无脚本标记(可能被运维修改),不覆盖不删除: ${paths.defaultPath}`);
}
return { dirPath: paths.customDirPath, defaultPath: paths.defaultPath, hasCustom: false };
}
if (args.dryRun) {
console.log(`[CERT-SYNC][CUSTOM] 计划: 目录内无自定义配置,将写入默认文件(仅首次)-> ${paths.defaultPath}`);
} else {
writeFileAtomic(paths.defaultPath, buildDefaultCustomConf(args.upstreamInclude), CUSTOM_CONF_FILE_MODE);
console.log(`[CERT-SYNC][CUSTOM] 已写入默认站点配置(仅首次生成,之后不再覆盖): ${paths.defaultPath}`);
}
return { dirPath: paths.customDirPath, defaultPath: paths.defaultPath, hasCustom: false };
}
/**
* 原子写文件:先写同目录临时文件(指定权限),rename 覆盖目标;
* 失败时清理临时文件后抛出异常。
* @param {string} filePath 目标文件绝对路径。
* @param {string} content 文件内容。
* @param {number} mode 文件权限(八进制)。
* @return {void}
* @throws {Error} 写文件失败时抛出异常。
*/
function writeFileAtomic(filePath, content, mode) {
const dir = path.dirname(filePath);
const tmpPath = path.join(dir, `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}`);
try {
fs.writeFileSync(tmpPath, content, { encoding: 'utf8', mode });
fs.chmodSync(tmpPath, mode);
fs.renameSync(tmpPath, filePath);
} catch (error) {
try {
fs.unlinkSync(tmpPath);
} catch (cleanupError) {
// 清理临时文件失败可忽略,不影响主错误
}
throw error;
}
}
/**
* 静默删除文件(不存在时忽略)。
* @param {string} filePath 文件绝对路径。
* @return {void}
*/
function removeFileQuiet(filePath) {
try {
fs.unlinkSync(filePath);
} catch (error) {
if (error && error.code !== 'ENOENT') {
console.warn(`[CERT-SYNC] 删除文件失败: ${filePath} - ${error.message}`);
}
}
}
/**
* 执行 nginx 命令(同步,带超时),返回状态与输出。
* @param {NginxCommandDesc} commandDesc nginx 命令执行描述。
* @return {{ok: boolean, stdout: string, stderr: string}} 执行结果。
*/
function runNginxCommand(commandDesc) {
const result = spawnNginxRaw(commandDesc);
const label = commandDesc.shell
? commandDesc.command
: `${commandDesc.command} ${commandDesc.args.join(' ')}`;
if (result.error) {
return {
ok: false,
stdout: '',
stderr: `${label} 执行失败: ${result.error.message}`,
};
}
return {
ok: result.status === 0,
stdout: String(result.stdout || ''),
stderr: String(result.stderr || ''),
};
}
/**
* 脱敏并截断错误文本:去掉 PEM 块内容、压缩空白、截断到列上限。
* @param {string} text 原始错误文本。
* @return {string} 脱敏截断后的文本(≤500 字符)。
*/
function sanitizeErrorText(text) {
return String(text || '')
.replace(/-----BEGIN [^-]*-----[\s\S]*?-----END [^-]*-----/g, '[PEM 内容已省略]')
.replace(/\s+/g, ' ')
.trim()
.slice(0, LAST_SYNC_ERROR_MAX_LENGTH);
}
/**
* 回写单条失败状态:sync_status=2、last_sync_error、sync_attempts+1、
* cert_path/key_path 置空(内容已换路径未知)。
* WHERE 带 sync_status=0 与 domain 守卫,避免覆盖并发重新保存的结果。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @param {Object} row 记录对象(含 id、domain)。
* @param {string} message 失败原因(原样日志,回写前会脱敏截断)。
* @return {Promise<void>} 无返回值。
*/
async function markRowFailed(sequelize, row, message) {
await sequelize.query(
`UPDATE ${TABLE_NAME}
SET sync_status = 2,
last_sync_error = :error,
sync_attempts = sync_attempts + 1,
cert_path = NULL,
key_path = NULL,
updated_at = NOW()
WHERE id = :id AND sync_status = 0 AND domain = :domain`,
{
replacements: {
error: sanitizeErrorText(message),
id: row.id,
domain: row.domain,
},
}
);
}
/**
* 回写单条成功状态:sync_status=1、回填 cert_path/key_path 实际全路径、
* last_synced_at=NOW()、last_sync_error 清空。
* WHERE 带 sync_status=0 与 domain 守卫,避免覆盖并发重新保存的结果。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @param {Object} row 记录对象(含 id、domain)。
* @param {string} certPath 证书文件绝对路径。
* @param {string} keyPath 私钥文件绝对路径。
* @return {Promise<void>} 无返回值。
*/
async function markRowSuccess(sequelize, row, certPath, keyPath) {
await sequelize.query(
`UPDATE ${TABLE_NAME}
SET sync_status = 1,
cert_path = :certPath,
key_path = :keyPath,
last_synced_at = NOW(),
last_sync_error = NULL,
updated_at = NOW()
WHERE id = :id AND sync_status = 0 AND domain = :domain`,
{
replacements: {
certPath,
keyPath,
id: row.id,
domain: row.domain,
},
}
);
}
/**
* reload 失败后的重试回写:sync_attempts+1;未达重试上限时回退
* sync_status=0(下分钟自动重试),达到上限转 sync_status=2 终止重试。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @param {Object} row 记录对象(含 id、domain、sync_attempts)。
* @param {string} message 失败原因。
* @return {Promise<number>} 回写后的同步状态(0 重试 / 2 终止)。
*/
async function markRowReloadRetry(sequelize, row, message) {
const attempts = Number(row.sync_attempts || 0) + 1;
const nextStatus = attempts >= RELOAD_FAILURE_MAX_RETRY ? 2 : 0;
await sequelize.query(
`UPDATE ${TABLE_NAME}
SET sync_status = :status,
last_sync_error = :error,
sync_attempts = sync_attempts + 1,
updated_at = NOW()
WHERE id = :id AND sync_status = 0 AND domain = :domain`,
{
replacements: {
status: nextStatus,
error: sanitizeErrorText(message),
id: row.id,
domain: row.domain,
},
}
);
return nextStatus;
}
/**
* 逐条处理待同步记录:确保站点个性化配置目录(customDir 契约)→ 写证书/私钥文件 →
* 写 server 块 → 单条 nginx -t;nginx -t 失败撤销本条 server 块并重新校验,保证不拖垮整体 nginx。
* 返回成功条目列表(不立即回写 DB,等 reload 后再统一回写)。
* @param {SyncContext} ctx 运行上下文。
* @param {Object[]} rows 待同步记录数组。
* @param {SyncStats} stats 统计对象(就地更新)。
* @return {Promise<Array<{row: Object, names: Object}>>} 成功条目数组。
*/
async function processRows(ctx, rows, stats) {
const successRows = [];
const { args } = ctx;
for (const row of rows) {
const domainRaw = String(row.domain || '').trim();
const rowLabel = `#${row.id} store=${row.store_id} domain=${domainRaw || '(空)'}`;
const validateError = validateRowContent(domainRaw, row.cert_pem, row.cert_key);
const names = buildFileNames(args, row.store_id, domainRaw);
if (args.dryRun) {
console.log(`[CERT-SYNC][PLAN] ${rowLabel}`);
const custom = ensureCustomConf(args, domainRaw);
console.log(`[CERT-SYNC][PLAN] cert_pem ${String(row.cert_pem || '').length} 字节 -> ${names.certPath}`);
console.log(`[CERT-SYNC][PLAN] cert_key ${String(row.cert_key || '').length} 字节 -> ${names.keyPath}`);
console.log(`[CERT-SYNC][PLAN] server 块 -> ${names.confPath}`);
console.log(`[CERT-SYNC][PLAN] custom 目录 -> ${custom.dirPath}${custom.hasCustom ? '(已有自定义配置,保留)' : ''}`);
console.log(`[CERT-SYNC][PLAN] custom include -> ${names.customGlobPath}`);
console.log(`[CERT-SYNC][PLAN] 默认文件 -> ${custom.defaultPath}(${custom.hasCustom ? '不写入' : '将写入'})`);
console.log(`[CERT-SYNC][PLAN] nginx -t=${!args.skipNginx && !ctx.nginxMissing} reload=${!args.skipNginx && !ctx.nginxMissing}`);
console.log(`[CERT-SYNC][PLAN] 预校验: ${validateError ? `将失败(${validateError})` : '通过'}`);
if (!validateError) {
stats.success++;
} else {
stats.failed++;
}
continue;
}
if (validateError) {
console.error(`[CERT-SYNC][FAIL] ${rowLabel} - ${validateError}`);
await markRowFailed(ctx.sequelize, row, validateError);
stats.failed++;
continue;
}
try {
ensureCustomConf(args, domainRaw);
writeFileAtomic(names.certPath, String(row.cert_pem), CERT_FILE_MODE);
writeFileAtomic(names.keyPath, String(row.cert_key), KEY_FILE_MODE);
writeFileAtomic(names.confPath, buildServerConf(domainRaw, names.certPath, names.keyPath, names.customGlobPath), CERT_FILE_MODE);
if (!args.skipNginx && !ctx.nginxMissing) {
const testResult = runNginxCommand(ctx.testCommand);
if (!testResult.ok) {
// 撤销本条 server 块,避免拖垮整体 nginx,并复验恢复
removeFileQuiet(names.confPath);
const restoreResult = runNginxCommand(ctx.testCommand);
const restoreTip = restoreResult.ok
? ''
: `(撤销本条后 nginx -t 仍失败,请检查其他配置: ${sanitizeErrorText(restoreResult.stderr || restoreResult.stdout)})`;
const errorText = `nginx -t 校验失败: ${sanitizeErrorText(testResult.stderr || testResult.stdout)}${restoreTip}`;
throw new Error(errorText);
}
}
console.log(`[CERT-SYNC][OK] ${rowLabel} 文件与 server 块已写入`);
successRows.push({ row, names });
stats.success++;
} catch (error) {
// 清理本条已落盘的文件(幂等:下次重试重新写入)
removeFileQuiet(names.certPath);
removeFileQuiet(names.keyPath);
removeFileQuiet(names.confPath);
const message = error && error.message ? error.message : String(error);
console.error(`[CERT-SYNC][FAIL] ${rowLabel} - ${message}`);
await markRowFailed(ctx.sequelize, row, message);
stats.failed++;
}
}
return successRows;
}
/**
* 回写本批成功条目(在 reload 成功或 skip-nginx 之后调用)。
* @param {SyncContext} ctx 运行上下文。
* @param {Array<{row: Object, names: Object}>} successRows 成功条目数组。
* @return {Promise<void>} 无返回值。
*/
async function writeBackSuccessRows(ctx, successRows) {
for (const { row, names } of successRows) {
await markRowSuccess(ctx.sequelize, row, names.certPath, names.keyPath);
}
}
/**
* reload 失败处理:本批成功条目按重试策略回写(回退待同步或转失败)。
* @param {SyncContext} ctx 运行上下文。
* @param {Array<{row: Object, names: Object}>} successRows 本批成功条目数组。
* @param {string} reloadError reload 失败原因(脱敏后)。
* @return {Promise<void>} 无返回值。
*/
async function handleReloadFailure(ctx, successRows, reloadError) {
console.error(`[CERT-SYNC][RELOAD-FAIL] nginx -s reload 失败: ${reloadError}`);
for (const { row } of successRows) {
const retriedStatus = await markRowReloadRetry(ctx.sequelize, row, `nginx reload 失败: ${reloadError}`);
console.error(`[CERT-SYNC][RELOAD-RETRY] #${row.id} 回写 sync_status=${retriedStatus}(${retriedStatus === 0 ? '下分钟自动重试' : '已达重试上限,需人工介入'})`);
}
}
// =====================================================================
// 旧域名下线(retired_domain 消费)与孤儿兜底清理
//
// 背景:前端独立部署改为两阶段域名切换后,应用侧只登记 pending,并在 TXT 校验
// 通过后「提升」为新域名(domain 换成新域名、清空证书并重置同步状态),同时把
// 旧域名写入 retired_domain(仅保留最近一个)。应用不碰 nginx 文件,因此旧域名的
// server 块与证书文件必须由本脚本下线。
//
// 红线:
// 1. 只允许删除 confDir / certDir 内的文件,删除前统一做目录前缀校验;
// 2. 只允许删除「本系统按命名规则生成」的文件(白名单识别,见 cleanupOrphans);
// 3. --dry-run 只打印待删清单,绝不删除文件、不写库、不 reload;
// 4. 删除失败(权限等)不中断整轮,只计入统计并 WARN。
// =====================================================================
/**
* 探测 wms_warehouse_front_config 是否已有 retired_domain 列(两阶段域名切换新增)。
*
* 脚本可能先于迁移部署:该列不存在时整段跳过下线 / 清理流程并 WARN,
* 与 domain_status 的降级策略同源(宁可不做,也不猜)。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @return {Promise<boolean>} 存在返回 true;探测失败返回 false。
*/
async function hasRetiredDomainColumn(sequelize) {
try {
const rows = await sequelize.query(
`SELECT COUNT(*) AS c FROM information_schema.columns
WHERE table_schema = DATABASE() AND table_name = ? AND column_name = 'retired_domain'`,
{ replacements: [ TABLE_NAME ], type: Sequelize.QueryTypes.SELECT }
);
return Number(rows && rows[0] && rows[0].c) > 0;
} catch (error) {
console.warn(`[CERT-SYNC] retired_domain 列探测失败(按无该列降级,跳过下线与孤儿清理): ${sanitizeErrorText(error.message)}`);
return false;
}
}
/**
* 扫描待下线的旧域名记录(retired_domain 非空,按 id 升序,limit 条)。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @param {number} limit 单轮处理条数上限。
* @return {Promise<Object[]>} 待下线记录数组(id / store_id / domain / retired_domain / retired_at)。
*/
async function scanRetiredRows(sequelize, limit) {
return sequelize.query(
`SELECT id, store_id, domain, retired_domain, retired_at
FROM ${TABLE_NAME}
WHERE retired_domain IS NOT NULL AND retired_domain <> ''
ORDER BY id ASC
LIMIT ?`,
{ replacements: [ limit ], type: Sequelize.QueryTypes.SELECT }
);
}
/**
* 读取「生效域名集合」= 允许存在 nginx server 块的域名。
* domain_status 列缺失(迁移未执行)时降级为不按验证状态过滤。
* 集合统一小写化:DNS 与 nginx server_name 匹配均不区分大小写,
* 避免 A.com / a.com 的大小写差异被误判为孤儿。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @param {boolean} domainStatusReady 是否存在 domain_status 列。
* @return {Promise<Set<string>>} 小写化生效域名集合。
*/
async function loadEffectiveDomains(sequelize, domainStatusReady) {
const verifiedFilter = domainStatusReady ? ' AND domain_status = 1' : '';
const rows = await sequelize.query(
`SELECT DISTINCT domain FROM ${TABLE_NAME}
WHERE domain IS NOT NULL AND domain <> ''${verifiedFilter}`,
{ type: Sequelize.QueryTypes.SELECT }
);
const domains = new Set();
for (const row of rows || []) {
const domain = String(row.domain || '').trim().toLowerCase();
if (domain) {
domains.add(domain);
}
}
return domains;
}
/**
* 读取「库内仍存在的证书文件名前缀集合」(不限域名验证状态)。
* 孤儿证书兜底的安全闸门:只要某证书文件仍能对应表内任意一行的
* (store_id, domain) 命名推导结果,就一律不删(可能只是 conf 尚未写出)。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @return {Promise<Set<string>>} baseName 集合({store_id}_{domainSafe}{suffix})。
*/
async function loadKnownCertBaseNames(sequelize) {
const rows = await sequelize.query(
`SELECT DISTINCT store_id, domain FROM ${TABLE_NAME}
WHERE domain IS NOT NULL AND domain <> ''`,
{ type: Sequelize.QueryTypes.SELECT }
);
const baseNames = new Set();
for (const row of rows || []) {
const domain = String(row.domain || '').trim();
if (!domain) {
continue;
}
baseNames.add(buildCertBaseName(row.store_id, domain));
}
return baseNames;
}
/**
* 生成去重台账的路径键:win32 下路径大小写不敏感(D:/ 与 d:/ 指向同一文件),统一小写,
* 避免同一文件在去重台账里被算成两个文件。
* @param {string} filePath 文件绝对路径。
* @return {string} 去重键。
*/
function cleanupPathKey(filePath) {
const resolved = path.resolve(filePath);
return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
}
/**
* 创建下线 / 清理统计对象(就地累加,供汇总打印与退出码判定使用)。
*
* 两套口径不可混用:
* - 通道命中数(retiredConfs/retiredCerts/orphanConfs/orphanCerts):按「谁动的手」累加,
* 同一文件被两条通道各处理一次就计两次(dry-run 不落盘 → 会真实出现;真实运行不会);
* - 去重后文件数(cleanedPaths.size):按绝对路径去重,是「本轮待删 / 已删文件数」的唯一权威口径。
* @return {Object} 统计对象。
*/
function createCleanupStats() {
return {
scannedRetired: 0, // 扫描到的待下线行数
clearedRows: 0, // 已清空 retired_domain 的行数
retiredConfs: 0, // 下线通道命中的 conf 个数(不去重)
retiredCerts: 0, // 下线通道命中的证书文件个数(不去重)
orphanConfs: 0, // 孤儿通道命中的 conf 个数(不去重)
orphanCerts: 0, // 孤儿通道命中的证书文件个数(不去重)
planned: 0, // dry-run 计划行数(含通道重复列出;去重后文件数见 cleanedPaths.size)
cleanedPaths: new Map(), // 去重台账:路径键 → 首次列出/删除该路径的通道名(dry-run 与真实运行共用)
duplicateListings: 0, // dry-run 下被第二条通道重复列表的次数(解释「通道命中数之和 > 去重数」)
skippedRetired: 0, // 跳过的待下线条数(形态非法 / 数据冲突)
skippedOrphan: 0, // 孤儿清理跳过的文件数(白名单未命中 / 超单轮上限 / 不可判定)
deleteFailed: 0, // 删除失败文件数(权限等,非致命)
refusedPaths: 0, // 路径前缀校验拒绝数(红线护栏命中)
clearedDeferred: 0, // 因 nginx -t / reload 失败而延后清空的行数
cleanupFailed: 0, // 清理阶段失败计数(nginx -t 或 reload 失败,用于退出码)
};
}
/**
* 格式化「去重后」口径摘要:`N 个文件(去重后;通道命中 retired_domain=X, orphan=Y)`。
*
* 去重后文件数取 cleanedPaths 规模;通道命中数之和大于 N 属于预期:
* dry-run 不落盘,先列出的通道不会真的删掉文件,后一条通道仍会看到同一文件。
* @param {Object} stats 统计对象。
* @return {string} 摘要文本。
*/
function formatCleanupDedupDetail(stats) {
const retiredHits = stats.retiredConfs + stats.retiredCerts;
const orphanHits = stats.orphanConfs + stats.orphanCerts;
return `${stats.cleanedPaths.size} 个文件(去重后;通道命中 retired_domain=${retiredHits}, orphan=${orphanHits})`;
}
/**
* 路径前缀校验:解析后必须严格位于允许目录内(红线:禁止删除配置目录之外的路径)。
* win32 下 path.relative 不区分大小写,POSIX 下区分。
* @param {string} allowedDir 允许删除的目录(绝对路径)。
* @param {string} filePath 待删除文件路径。
* @return {boolean} 位于目录内返回 true。
*/
function isPathInsideDir(allowedDir, filePath) {
const rel = path.relative(path.resolve(allowedDir), path.resolve(filePath));
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
return false;
}
return true;
}
/**
* 读取文本文件;不存在或不可读返回 null(调用方按「不可判定」处理,不删除)。
* @param {string} filePath 文件绝对路径。
* @return {string|null} 文件内容或 null。
*/
function readTextFileOrNull(filePath) {
try {
return fs.readFileSync(filePath, 'utf8');
} catch (error) {
if (error && error.code !== 'ENOENT') {
console.warn(`[CERT-SYNC][WARN] 读取文件失败(按不可判定处理,不删除): ${filePath} - ${sanitizeErrorText(error.message)}`);
}
return null;
}
}
/**
* 读取目录下的普通文件列表(目录不存在 / 不可读返回空数组并 WARN)。
* @param {string} dirPath 目录绝对路径。
* @return {Array<{name: string, fullPath: string}>} 文件列表。
*/
function readDirSafe(dirPath) {
let entries = [];
try {
entries = fs.readdirSync(dirPath, { withFileTypes: true });
} catch (error) {
console.warn(`[CERT-SYNC][WARN] 目录不可读(本轮跳过该目录扫描): ${dirPath} - ${sanitizeErrorText(error.message)}`);
return [];
}
const files = [];
for (const entry of entries) {
if (!entry.isFile()) {
continue;
}
files.push({ name: entry.name, fullPath: path.join(dirPath, entry.name) });
}
return files;
}
/**
* 从 conf 内容解析首个 server_name 的域名。
* @param {string} content conf 文件内容。
* @return {string|null} 域名(去引号与空白),解析不到返回 null。
*/
function parseServerName(content) {
const matched = SERVER_NAME_PATTERN.exec(String(content || ''));
if (!matched) {
return null;
}
const firstToken = String(matched[1] || '').trim().split(/\s+/)[0] || '';
const domain = firstToken.replace(/^["']|["']$/g, '').trim();
return domain || null;
}
/**
* 采集 conf 内容中引用的证书 / 私钥文件名前缀({store_id}_{domainSafe}{suffix})。
* 用于在「删除后的 conf 集合」上判定证书文件是否仍被引用。
* @param {string} content conf 文件内容。
* @param {Set<string>} target 采集结果集合(就地累加)。
* @return {void}
*/
function collectCertBaseNames(content, target) {
const pattern = /([A-Za-z0-9]+_[A-Za-z0-9._-]+?)\.(?:pem|key)/g;
const text = String(content || '');
let matched = pattern.exec(text);
while (matched) {
target.add(matched[1]);
matched = pattern.exec(text);
}
}
/**
* 受控删除(下线与孤儿清理的唯一删除入口)。
*
* 行为约定:
* 1. 目标必须位于 allowedDir 内(前缀校验),否则拒绝并 WARN(红线);
* 2. dry-run 只打印 [PLAN] DELETE,绝不落盘;
* 3. 文件不存在不算失败,只记 [SKIP] 日志;
* 4. 删除前缓存文件内容,供本轮 nginx -t 失败时回滚(尽量恢复磁盘原状);
* 5. 删除失败不抛异常,计入统计并 WARN,不中断整轮;
* 6. 计划 / 删除成功的路径登记入去重台账(cleanedPaths),供汇总输出去重口径。
* @param {SyncContext} ctx 运行上下文。
* @param {string} allowedDir 允许删除的目录(confDir 或 certDir)。
* @param {string} filePath 目标文件绝对路径。
* @param {'retired_domain'|'orphan'} reason 删除原因(审计日志用)。
* @param {Object} stats 统计对象(就地累加)。
* @param {Array<{path: string, content: Buffer, mode: number}>} rollbackEntries 回滚素材集合(就地累加)。
* @return {'deleted'|'planned'|'missing'|'refused'|'failed'} 处理结果。
*/
function deleteFileGuarded(ctx, allowedDir, filePath, reason, stats, rollbackEntries) {
if (!isPathInsideDir(allowedDir, filePath)) {
console.warn(`[CERT-SYNC][WARN] 拒绝删除配置目录之外的路径: ${filePath}(原因=${reason},允许目录=${allowedDir})`);
stats.refusedPaths++;
return 'refused';
}
let stat = null;
try {
stat = fs.statSync(filePath);
} catch (error) {
if (error && error.code === 'ENOENT') {
console.log(`[CERT-SYNC][SKIP] 待删文件不存在: ${filePath} 原因=${reason}`);
return 'missing';
}
console.warn(`[CERT-SYNC][WARN] 读取待删文件属性失败: ${filePath} - ${sanitizeErrorText(error.message)}`);
stats.deleteFailed++;
return 'failed';
}
if (!stat.isFile()) {
console.warn(`[CERT-SYNC][WARN] 待删目标不是普通文件,已跳过: ${filePath}`);
return 'missing';
}
const dedupKey = cleanupPathKey(filePath);
if (ctx.args.dryRun) {
// dry-run 绝不落盘 → 同一路径可能被后一条通道再次列出:
// 第二次列出时追加去重标注,避免运维按日志行数误判待删文件规模
const listedBy = stats.cleanedPaths.get(dedupKey);
if (listedBy) {
stats.duplicateListings++;
console.log(`[CERT-SYNC][PLAN] DELETE ${filePath} 原因=${reason} [已由 ${listedBy} 通道列出,去重]`);
} else {
stats.cleanedPaths.set(dedupKey, reason);
console.log(`[CERT-SYNC][PLAN] DELETE ${filePath} 原因=${reason}`);
}
stats.planned++;
return 'planned';
}
try {
// 回滚素材:删除前缓存内容与权限(私钥内容只在内存中流转,绝不打印)
const content = fs.readFileSync(filePath);
// mode 只取低 9 位权限位(0o777),避免把文件类型位带进回滚写入
// eslint-disable-next-line no-bitwise
rollbackEntries.push({ path: filePath, content, mode: stat.mode & 0o777 });
fs.unlinkSync(filePath);
} catch (error) {
console.warn(`[CERT-SYNC][WARN] 删除失败(不中断本轮): ${filePath} - ${sanitizeErrorText(error.message)}`);
stats.deleteFailed++;
return 'failed';
}
// 去重台账只登记首次成功的删除(真实运行下第二条通道只会命中 [SKIP] 待删文件不存在)
if (!stats.cleanedPaths.has(dedupKey)) {
stats.cleanedPaths.set(dedupKey, reason);
}
console.log(`[CERT-SYNC] DELETE ${filePath} 原因=${reason}`);
return 'deleted';
}
/**
* 回滚本轮已删除的文件(nginx -t 失败时把磁盘尽量恢复成本轮开始前的状态)。
* @param {Array<{path: string, content: Buffer, mode: number}>} rollbackEntries 回滚素材集合。
* @return {number} 成功恢复的文件数。
*/
function rollbackDeletedFiles(rollbackEntries) {
let restored = 0;
for (const entry of rollbackEntries) {
try {
writeFileAtomic(entry.path, entry.content, entry.mode);
restored++;
} catch (error) {
console.error(`[CERT-SYNC][WARN] 回滚失败,需人工恢复: ${entry.path} - ${sanitizeErrorText(error.message)}`);
}
}
return restored;
}
/**
* 消费 retired_domain(下线主线):删除旧域名残留的 server 块与证书文件。
*
* 产物路径完全按写入时的命名推导推算(与 buildFileNames 同源):
* - server 块:{confDir}/{domainSafe}{suffix}.conf
* - 证书文件:{certDir}/{store_id}_{domainSafe}{suffix}.pem 与 .key
* suffix 仅在「域名被清洗后与原名不一致」时出现(下划线 + 域名 md5 前 8 位),
* 例如 *.a.com 会被清洗为 .a.com,必须带 _短哈希8 才不会与 .a.com 的产物冲突。
*
* 安全闸门(任一命中即整条跳过:不删文件、不清空槽位):
* 1. retired_domain 形态非法(空 / 超长 / 含非法字符);
* 2. retired_domain 与当前 domain 相同(数据异常,槽位指向生效域名);
* 3. retired_domain 仍在生效域名集合内(可能被其它仓库使用)。
* 文件不存在不算失败(只记 [SKIP] 日志);权限等硬失败保留槽位待下一轮重试。
* 外置个性化配置目录 <customDir>/<domain>/ 不做下线删除:旧 server 块删除后其
* include 已失效,残留目录无副作用且可能被运维移作他用,一律保留。
* @param {SyncContext} ctx 运行上下文。
* @param {Object} cleanupCtx 清理上下文(stats / effectiveDomains / handledConfPaths / rollbackEntries)。
* @return {Promise<Array<{row: Object, retiredDomain: string}>>} 可清空槽位的行(reload 成功后统一清空)。
*/
async function consumeRetiredDomains(ctx, cleanupCtx) {
const { args } = ctx;
const { stats, effectiveDomains, handledConfPaths, removedConfPaths, rollbackEntries } = cleanupCtx;
const rows = await scanRetiredRows(ctx.sequelize, args.limit);
stats.scannedRetired = rows.length;
const clearableRows = [];
for (const row of rows) {
const currentDomain = String(row.domain || '').trim();
const retiredRaw = String(row.retired_domain || '').trim();
const rowLabel = `#${row.id} store=${row.store_id} retired=${retiredRaw || '(空)'}`;
if (!retiredRaw || retiredRaw.length > DOMAIN_MAX_LENGTH || !DOMAIN_PATTERN.test(retiredRaw)) {
console.warn(`[CERT-SYNC][WARN] ${rowLabel} retired_domain 形态非法,跳过(不删文件、不清空槽位)`);
stats.skippedRetired++;
continue;
}
if (retiredRaw.toLowerCase() === currentDomain.toLowerCase()) {
console.warn(`[CERT-SYNC][WARN] ${rowLabel} retired_domain 与当前 domain 相同(数据异常),跳过以免误删生效产物`);
stats.skippedRetired++;
continue;
}
if (effectiveDomains.has(retiredRaw.toLowerCase())) {
console.warn(`[CERT-SYNC][WARN] ${rowLabel} retired_domain 仍在生效域名集合内(可能被其它仓库使用),跳过以免误删`);
stats.skippedRetired++;
continue;
}
const confPath = path.join(args.confDir, buildConfFileName(retiredRaw));
const certBaseName = buildCertBaseName(row.store_id, retiredRaw);
// 无论删除结果如何都登记为「本轮已处理」,避免孤儿清理对同一文件重复动作与重复日志
handledConfPaths.add(confPath);
const targets = [
{ dir: args.confDir, filePath: confPath, kind: 'conf' },
{ dir: args.certDir, filePath: path.join(args.certDir, `${certBaseName}.pem`), kind: 'cert' },
{ dir: args.certDir, filePath: path.join(args.certDir, `${certBaseName}.key`), kind: 'cert' },
];
let hardFailed = false;
for (const target of targets) {
const result = deleteFileGuarded(ctx, target.dir, target.filePath, 'retired_domain', stats, rollbackEntries);
if (result === 'failed') {
hardFailed = true;
continue;
}
if (result === 'deleted' || result === 'planned') {
if (target.kind === 'conf') {
stats.retiredConfs++;
removedConfPaths.add(target.filePath);
} else {
stats.retiredCerts++;
}
}
}
if (hardFailed) {
console.warn(`[CERT-SYNC][WARN] ${rowLabel} 存在删除失败,保留 retired_domain 待下一轮重试`);
continue;
}
clearableRows.push({ row, retiredDomain: retiredRaw });
}
return clearableRows;
}
/**
* 清空 retired_domain 槽位(retired_at 保留作审计)。
* 防并发守卫:WHERE 带 id + retired_domain 双条件(与 markRowSuccess 同风格),
* 避免覆盖并发写入的新值(应用可能刚好又发生一次域名切换)。
* @param {import('sequelize').Sequelize} sequelize Sequelize 实例。
* @param {Object} row 记录对象(含 id)。
* @param {string} retiredDomain 本轮消费的旧域名原值(并发守卫条件)。
* @return {Promise<number>} 受影响行数(0 表示已被并发修改,未清空)。
*/
async function clearRetiredDomainSlot(sequelize, row, retiredDomain) {
const queryResult = await sequelize.query(
`UPDATE ${TABLE_NAME}
SET retired_domain = NULL,
updated_at = NOW()
WHERE id = :id AND retired_domain = :retiredDomain`,
{ replacements: { id: row.id, retiredDomain } }
);
const metadata = Array.isArray(queryResult) ? queryResult[1] : null;
const affected = metadata && typeof metadata.affectedRows === 'number' ? Number(metadata.affectedRows) : null;
return affected === null ? 1 : affected;
}
/**
* 执行旧域名下线 + 孤儿兜底清理。
*
* 执行顺序(关键:避免 reload 失败时误清空 retired_domain):
* 1. 删除旧域名 conf / 证书 + 孤儿差集删除(只删白名单命中的文件);
* 2. 只要本轮删过任何文件,就在删除后的配置树上执行 nginx -t,通过后再 reload;
* 3. nginx -t 失败 → 回滚本轮删除的文件并告警;reload 失败 → 直接告警;
* -t / reload 任一失败都不清空 retired_domain(槽位保留即待办标记,下一分钟自动重试,
* 等价于证书同步的 markRowReloadRetry「回退待处理 + 下一轮重试」策略);
* 4. 只有「本轮无文件变更」或「-t 通过且 reload 成功」才清空槽位。
* @param {SyncContext} ctx 运行上下文。
* @param {boolean} domainStatusReady 是否存在 domain_status 列。
* @param {Object} stats 统计对象(就地累加)。
* @return {Promise<void>} 无返回值。
*/
async function runCleanup(ctx, domainStatusReady, stats) {
const { args } = ctx;
const rollbackEntries = [];
const handledConfPaths = new Set();
const removedConfPaths = new Set();
const effectiveDomains = await loadEffectiveDomains(ctx.sequelize, domainStatusReady);
const knownBaseNames = await loadKnownCertBaseNames(ctx.sequelize);
const cleanupCtx = { stats, effectiveDomains, knownBaseNames, handledConfPaths, removedConfPaths, rollbackEntries };
console.log(`[CERT-SYNC] 下线清理开始: 生效域名 ${effectiveDomains.size} 个, 库内证书命名 ${knownBaseNames.size} 个, dry-run=${args.dryRun}`);
const clearableRows = await consumeRetiredDomains(ctx, cleanupCtx);
await cleanupOrphans(ctx, cleanupCtx);
// 汇总统一改为「去重后」口径:dry-run 下同一文件可能被下线通道与孤儿通道各列一次,
// 直接相加各通道计数会虚增待删规模(发布前核对待删清单的关键输出)
const dedupedFiles = stats.cleanedPaths.size;
if (dedupedFiles === 0) {
console.log('[CERT-SYNC] 下线清理: 本轮无文件变更,跳过 nginx -t / reload');
} else if (args.dryRun) {
console.log(`[CERT-SYNC][PLAN] 下线清理: 待删 ${formatCleanupDedupDetail(stats)}、不执行 nginx -t / reload、不写库`);
return;
} else if (args.skipNginx || ctx.nginxMissing) {
console.warn(`[CERT-SYNC] 下线清理: 已跳过 nginx -t / reload(${args.skipNginx ? '--skip-nginx' : '本机未检测到 nginx'}),文件删除已生效,清库继续`);
console.log(`[CERT-SYNC] 下线清理: 删除 ${formatCleanupDedupDetail(stats)}`);
} else {
const testResult = runNginxCommand(ctx.testCommand);
if (!testResult.ok) {
console.error(`[CERT-SYNC][RELOAD-FAIL] 下线清理后 nginx -t 失败: ${sanitizeErrorText(testResult.stderr || testResult.stdout)}`);
const restored = rollbackDeletedFiles(rollbackEntries);
if (rollbackEntries.length > 0) {
const retest = runNginxCommand(ctx.testCommand);
const retestTip = retest.ok
? '(回滚后 nginx -t 已恢复)'
: `(回滚后 nginx -t 仍失败,请检查其它配置: ${sanitizeErrorText(retest.stderr || retest.stdout)})`;
console.error(`[CERT-SYNC][RELOAD-FAIL] 已回滚 ${restored}/${rollbackEntries.length} 个文件${retestTip}`);
}
stats.cleanupFailed++;
stats.clearedDeferred += clearableRows.length;
console.warn(`[CERT-SYNC][WARN] 本轮不清空 retired_domain(${clearableRows.length} 条保留,下一轮自动重试)`);
return;
}
const reloadResult = runNginxCommand(ctx.reloadCommand);
if (!reloadResult.ok) {
console.error(`[CERT-SYNC][RELOAD-FAIL] nginx -s reload 失败: ${sanitizeErrorText(reloadResult.stderr || reloadResult.stdout)}`);
stats.cleanupFailed++;
stats.clearedDeferred += clearableRows.length;
console.warn(`[CERT-SYNC][WARN] 本轮不清空 retired_domain(${clearableRows.length} 条保留,下一轮自动重试;文件已删除,重试幂等)`);
return;
}
console.log(`[CERT-SYNC] 下线清理: 删除 ${formatCleanupDedupDetail(stats)}`);
console.log('[CERT-SYNC] 下线清理: nginx -t 通过 + nginx -s reload 成功');
}
for (const item of clearableRows) {
const affected = await clearRetiredDomainSlot(ctx.sequelize, item.row, item.retiredDomain);
if (affected === 0) {
console.warn(`[CERT-SYNC][WARN] #${item.row.id} retired_domain 已被并发修改,本轮跳过清空(下一轮按新值处理)`);
stats.skippedRetired++;
continue;
}
stats.clearedRows++;
}
}
/**
* 打印下线 / 清理统计(dry-run 时以待删口径输出)。
* @param {Object} stats 统计对象。
* @param {SyncArgs} args 参数集合。
* @return {void}
*/
function printCleanupSummary(stats, args) {
const prefix = args.dryRun ? '[CERT-SYNC][PLAN] ' : '[CERT-SYNC] ';
const verb = args.dryRun ? '待删除' : '删除';
console.log(`${prefix}旧域名下线: 处理 ${stats.scannedRetired} 条, ${verb} conf ${stats.retiredConfs} 个, 证书文件 ${stats.retiredCerts} 个, 跳过 ${stats.skippedRetired} 条`);
console.log(`${prefix}孤儿兜底清理: ${verb} conf ${stats.orphanConfs} 个, 证书文件 ${stats.orphanCerts} 个, 白名单未命中/超上限跳过 ${stats.skippedOrphan} 个`);
console.log(`${prefix}下线清理汇总: ${verb} ${formatCleanupDedupDetail(stats)}(其中通道重复列出 ${stats.duplicateListings} 行), 清空 retired_domain ${stats.clearedRows} 条(延后 ${stats.clearedDeferred} 条), 删除失败 ${stats.deleteFailed} 个, 路径越界拒绝 ${stats.refusedPaths} 个, 清理阶段失败 ${stats.cleanupFailed}`);
}
/**
* 判定清理阶段是否存在需要告警的失败(统一退出码口径:删除失败 / 路径越界 / -t 或 reload 失败)。
* @param {Object} stats 清理统计对象。
* @return {boolean} 存在失败返回 true。
*/
function hasCleanupFailure(stats) {
return stats.deleteFailed > 0 || stats.refusedPaths > 0 || stats.cleanupFailed > 0;
}
/**
* 孤儿兜底清理:以目录实际文件为准做差集,回收 retired_domain 单槽位(只记最近一个)
* 丢失中间域名后残留的产物。
*
* conf 白名单识别(三条全部命中才认为是本系统生成、才允许删除):
* 1. 文件名形态命中 CONF_FILE_NAME_PATTERN({domainSafe}{[_短哈希8]}.conf);
* 2. 文件内容包含本系统固有标记之一(模板两代兼容):
* - 旧模板(location 硬编码时代):包含 upstreamInclude 路径字符串;
* - 新模板(仅证书骨架 + 外置 include):包含本脚本按该域名推导的
* custom 通配路径(<customDir>/<domain>/*.conf);
* 3. 文件内容可解析出 server_name <domain>,domain 通过域名白名单校验,
* 且用该 domain 反推的 conf 文件名与实际文件名完全一致(命名可回推一致)。
* 未命中的文件一律不动(他人手工 conf、宝塔自身文件等),只计入跳过统计;
* 扫描范围仅 confDir 根层普通文件(readDirSafe 按 entry.isFile() 过滤),
* custom/ 等子目录不会进入待删集合,外置站点配置目录绝不递归清理。
* 命中白名单且 domain 不在生效集合内(按小写比较)→ 列入待删。
*
* 证书 / 私钥文件:仅处理文件名严格命中 CERT_FILE_NAME_PATTERN 的,且需同时满足
* - 在「删除后的 conf 集合」上不被任何存活 conf 引用(引用判定覆盖全部 conf,
* 含未通过白名单的文件,避免删掉他人 conf 仍在使用的证书);
* - 不是库内任意一行 (store_id, domain) 的命名推导产物(可能只是 conf 尚未写出)。
* 存在不可读 conf 时本轮整体跳过证书清理(无法证明「未被引用」,宁可不删)。
*
* 单轮删除数量上限为 --limit,超出部分下一轮继续(cron 每分钟一次,可自然收敛)。
* @param {SyncContext} ctx 运行上下文。
* @param {Object} cleanupCtx 清理上下文(stats / effectiveDomains / knownBaseNames / handledConfPaths / rollbackEntries)。
* @return {Promise<void>} 无返回值。
*/
async function cleanupOrphans(ctx, cleanupCtx) {
const { args } = ctx;
const { stats, effectiveDomains, knownBaseNames, handledConfPaths, removedConfPaths, rollbackEntries } = cleanupCtx;
// ---------- 第一遍:conf 目录扫描 + 白名单判定 ----------
// 只扫根层:readDirSafe 以 withFileTypes + entry.isFile() 过滤,
// custom/ 等子目录(外置站点个性化配置)不会进入待删集合,孤儿清理绝不递归到子目录。
const confEntries = readDirSafe(args.confDir);
const confContents = new Map();
const orphanConfs = [];
let unreadableConf = false;
for (const entry of confEntries) {
if (!/\.conf$/i.test(entry.name)) {
continue;
}
if (handledConfPaths.has(entry.fullPath)) {
continue;
}
const content = readTextFileOrNull(entry.fullPath);
if (content === null) {
unreadableConf = true;
continue;
}
confContents.set(entry.fullPath, content);
if (!CONF_FILE_NAME_PATTERN.test(entry.name)) {
stats.skippedOrphan++;
continue;
}
const domain = parseServerName(content);
if (!domain || domain.length > DOMAIN_MAX_LENGTH || !DOMAIN_PATTERN.test(domain)) {
stats.skippedOrphan++;
continue;
}
if (buildConfFileName(domain) !== entry.name) {
stats.skippedOrphan++;
continue;
}
// 固有标记判定(模板两代兼容):旧模板含 upstreamInclude;新模板含本脚本为该域名推导的外置通配路径
const customGlobPath = buildCustomPaths(args, domain).customGlobPath;
if (!content.includes(args.upstreamInclude) && !content.includes(customGlobPath)) {
stats.skippedOrphan++;
continue;
}
if (effectiveDomains.has(domain.toLowerCase())) {
continue;
}
if (orphanConfs.length >= args.limit) {
stats.skippedOrphan++;
continue;
}
orphanConfs.push({ fullPath: entry.fullPath, domain });
}
// ---------- 第二遍:删除孤儿 conf ----------
for (const item of orphanConfs) {
const result = deleteFileGuarded(ctx, args.confDir, item.fullPath, 'orphan', stats, rollbackEntries);
handledConfPaths.add(item.fullPath);
if (result === 'deleted' || result === 'planned') {
stats.orphanConfs++;
removedConfPaths.add(item.fullPath);
}
}
// ---------- 第三遍:证书引用判定(在删除后的 conf 集合上判断) ----------
if (unreadableConf) {
console.warn('[CERT-SYNC][WARN] conf 目录存在不可读文件,无法证明证书未被引用,本轮跳过证书孤儿清理');
stats.skippedOrphan++;
return;
}
const referencedBaseNames = new Set();
for (const entry of confEntries) {
if (!/\.conf$/i.test(entry.name)) {
continue;
}
if (removedConfPaths.has(entry.fullPath) || !fs.existsSync(entry.fullPath)) {
continue;
}
const content = confContents.has(entry.fullPath) ? confContents.get(entry.fullPath) : readTextFileOrNull(entry.fullPath);
if (content === null) {
continue;
}
collectCertBaseNames(content, referencedBaseNames);
}
// ---------- 第四遍:证书 / 私钥文件差集删除 ----------
let orphanCertCount = 0;
for (const entry of readDirSafe(args.certDir)) {
if (!CERT_FILE_NAME_PATTERN.test(entry.name)) {
continue;
}
const baseName = entry.name.replace(/\.(pem|key)$/i, '');
if (referencedBaseNames.has(baseName)) {
continue;
}
if (knownBaseNames.has(baseName)) {
continue;
}
if (orphanCertCount >= args.limit) {
stats.skippedOrphan++;
continue;
}
const result = deleteFileGuarded(ctx, args.certDir, entry.fullPath, 'orphan', stats, rollbackEntries);
if (result === 'deleted' || result === 'planned') {
stats.orphanCerts++;
orphanCertCount++;
}
}
}
/**
* 主流程:解析参数 → 连接数据库 → 扫描 → 逐条处理 → reload → 回写状态。
* @return {Promise<void>} 无返回值,通过 process.exitCode 表达执行结果。
*/
async function main() {
const args = parseArgs(process.argv.slice(2));
if (args.help) {
printUsage();
return;
}
console.log(`[CERT-SYNC] 开始: env=${args.env} dry-run=${args.dryRun} cleanup-only=${args.cleanupOnly} skip-nginx=${args.skipNginx} limit=${args.limit}`);
console.log(`[CERT-SYNC] 外部配置文件: ${args.configPath}`);
console.log(`[CERT-SYNC] 证书目录: ${args.certDir}`);
console.log(`[CERT-SYNC] server 块目录: ${args.confDir}`);
console.log(`[CERT-SYNC] 站点个性化配置目录(custom): ${args.customDir}(server 块 include <customDir>/<domain>/*.conf)`);
console.log(`[CERT-SYNC] upstream include: ${args.upstreamInclude}`);
console.log(`[CERT-SYNC] nginx 二进制: ${args.nginxBin}`);
if (args.nginxPrefix) {
console.log(`[CERT-SYNC] nginx -p 前缀: ${args.nginxPrefix}`);
}
applyDbTarget(args);
const testCommand = buildNginxCommand(args.nginxBin, args.nginxPrefix, [ '-t' ], args.testCmd);
const reloadCommand = buildNginxCommand(args.nginxBin, args.nginxPrefix, [ '-s', 'reload' ], args.reloadCmd);
const commandLabel = desc => (desc.shell ? desc.command : `${desc.command} ${desc.args.join(' ')}`);
console.log(`[CERT-SYNC] nginx -t 命令: ${commandLabel(testCommand)}(${args.testCmd ? '自定义命令' : '按系统类型推导'})`);
console.log(`[CERT-SYNC] nginx reload 命令: ${commandLabel(reloadCommand)}(${args.reloadCmd ? '自定义命令' : '按系统类型推导'})`);
const sequelize = connectDb(args);
const ctx = { args, sequelize, nginxMissing: false, testCommand, reloadCommand };
try {
try {
await sequelize.authenticate();
} catch (error) {
throw new Error(`数据库连接失败: ${error.message}`);
}
// 目录准备:不存在则递归创建(创建失败视为致命错误,避免逐条全部失败)
try {
fs.mkdirSync(args.certDir, { recursive: true });
fs.mkdirSync(args.confDir, { recursive: true });
} catch (error) {
throw new Error(`目录创建失败: ${error.message}`);
}
// nginx 可用性探测:生产环境缺失视为致命;开发环境缺失自动降级为跳过
if (!args.skipNginx && !nginxBinExists(args.nginxBin, args.nginxPrefix)) {
if (args.env === 'development') {
console.warn(`[CERT-SYNC] 开发环境未检测到 nginx(${args.nginxBin}),自动跳过 nginx -t / reload`);
ctx.nginxMissing = true;
} else {
throw new Error(`nginx 二进制不可用: ${args.nginxBin}(生产环境必须可用,或显式 --skip-nginx)`);
}
}
// 域名验证闸门:迁移尚未执行(无 domain_status 列)时降级为不按验证状态过滤,
// 保证脚本可先行部署;迁移执行后自动生效
const domainStatusReady = await hasDomainStatusColumn(sequelize);
if (!domainStatusReady) {
console.warn('[CERT-SYNC] 未检测到 wms_warehouse_front_config.domain_status 列(迁移尚未执行),本轮降级为不按域名验证状态过滤');
}
// 旧域名下线 + 孤儿兜底清理(两阶段域名切换的 nginx 侧配套):
// 放在证书同步之前执行,避免同一轮内「写新 conf」与「删旧 conf」互相干扰;
// 本流程自带一次 nginx -t / reload(仅在本轮确实删过文件时),与下面的同步流程互不耦合。
const cleanupStats = createCleanupStats();
const retiredDomainReady = await hasRetiredDomainColumn(sequelize);
if (!retiredDomainReady) {
console.warn('[CERT-SYNC] 未检测到 wms_warehouse_front_config.retired_domain 列(迁移尚未执行),本轮跳过旧域名下线与孤儿兜底清理');
} else {
await runCleanup(ctx, domainStatusReady, cleanupStats);
printCleanupSummary(cleanupStats, args);
}
// --cleanup-only:只做下线 / 清理,不做证书同步(供运维单独执行)
if (args.cleanupOnly) {
console.log(`[CERT-SYNC][SUMMARY] --cleanup-only 完成: 清空 retired_domain ${cleanupStats.clearedRows} 条, ${args.dryRun ? '待删' : '删除'} ${formatCleanupDedupDetail(cleanupStats)}, 通道命中明细(不去重)conf ${cleanupStats.retiredConfs + cleanupStats.orphanConfs} 个 / 证书文件 ${cleanupStats.retiredCerts + cleanupStats.orphanCerts} 个, 删除失败 ${cleanupStats.deleteFailed} 个`);
process.exitCode = hasCleanupFailure(cleanupStats) ? EXIT_BUSINESS_FAILURE : EXIT_OK;
return;
}
const rows = await scanPendingRows(sequelize, args.limit, domainStatusReady);
if (!rows || rows.length === 0) {
console.log('[CERT-SYNC] 无待同步记录,静默退出');
if (hasCleanupFailure(cleanupStats)) {
process.exitCode = EXIT_BUSINESS_FAILURE;
}
return;
}
const stats = { total: rows.length, success: 0, failed: 0 };
const successRows = await processRows(ctx, rows, stats);
if (args.dryRun) {
console.log(`[CERT-SYNC][SUMMARY] dry-run 完成: total=${stats.total} 可成功=${stats.success} 将失败=${stats.failed}`);
return;
}
if (successRows.length > 0 && !args.skipNginx && !ctx.nginxMissing) {
const reloadResult = runNginxCommand(ctx.reloadCommand);
if (reloadResult.ok) {
console.log('[CERT-SYNC] nginx -s reload 成功');
await writeBackSuccessRows(ctx, successRows);
} else {
await handleReloadFailure(ctx, successRows, sanitizeErrorText(reloadResult.stderr || reloadResult.stdout));
stats.failed += successRows.length;
stats.success -= successRows.length;
}
} else if (successRows.length > 0) {
await writeBackSuccessRows(ctx, successRows);
}
console.log(`[CERT-SYNC][SUMMARY] total=${stats.total} success=${stats.success} failed=${stats.failed}`);
if (stats.failed > 0 || hasCleanupFailure(cleanupStats)) {
process.exitCode = EXIT_BUSINESS_FAILURE;
} else {
process.exitCode = EXIT_OK;
}
} finally {
await sequelize.close();
}
}
// 顶层错误兜底:致命错误退出码 1(cron 可据 1/2 区分告警级别)
main().catch(error => {
console.error(`[CERT-SYNC][FATAL] ${error && error.message ? error.message : String(error)}`);
process.exitCode = EXIT_FATAL;
});