@infly/libs 2.0.45 → 2.0.47

package/build/docker/docker-build-push.js

@@ -1,240 +1,373 @@
-/**
- * Docker 镜像构建与推送（infly-libs 公共模块）
- *
- * 支持两种运行模式（自动检测）：
- *
- * 1. Monorepo 模式 — 检测到 git submodule (--show-superproject-working-tree 有值)
- *    构建上下文 = superproject 根，Dockerfile 使用 Dockerfile.monorepo
- *    @infly/* 包从 workspace 源码解析
- *
- * 2. 独立模式 — 非 submodule 且 cwd = git 根
- *    构建上下文 = 当前目录，Dockerfile 使用 Dockerfile
- *    @infly/* 包从 npm registry 安装
- *
- * 用法：
- *   infly-libs build:docker [--local] [--env prod|dev] [--dry-run] [--cicd-url URL]
- */
-
-const { execSync } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-
-// ---------- 默认配置 ----------
-const DEFAULT_REGISTRY = "ccr.ccs.tencentyun.com";
-const DEFAULT_NAMESPACE = "points";
-
-function formatCicdLink(value) {
-  if (value === undefined) {
-    return "";
-  }
-  if (typeof value !== "string" || !value.trim()) {
-    throw new Error("--cicd-url 缺少参数值");
-  }
-
-  const rawUrl = value.trim();
-  if (/[\u0000-\u001f\u007f]/.test(rawUrl)) {
-    throw new Error("--cicd-url 不能包含控制字符");
-  }
-
-  let parsedUrl;
-  try {
-    parsedUrl = new URL(rawUrl);
-  } catch {
-    throw new Error("--cicd-url 必须是合法的 HTTP/HTTPS URL");
-  }
-
-  if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
-    throw new Error("--cicd-url 只支持 HTTP/HTTPS URL");
-  }
-  if (parsedUrl.username || parsedUrl.password) {
-    throw new Error("--cicd-url 不能包含用户名或密码凭据");
-  }
-
-  return `发布系统：\x1b[34m${decodeURI(parsedUrl.href)}\x1b[0m`;
-}
-
-function detectMode() {
-  const cwd = path.resolve(process.cwd());
-
-  // git submodule → monorepo 模式，contextRoot = superproject 根
-  try {
-    const superproject = execSync("git rev-parse --show-superproject-working-tree", {
-      encoding: "utf-8", stdio: "pipe",
-    }).trim();
-    if (superproject) {
-      return { isStandalone: false, contextRoot: superproject };
-    }
-  } catch {}
-
-  // 非 submodule：cwd = git 根 → 独立模式，否则 monorepo 模式
-  const gitRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim();
-  const isStandalone = path.resolve(cwd) === path.resolve(gitRoot);
-
-  return {
-    isStandalone,
-    contextRoot: isStandalone ? cwd : gitRoot,
-  };
-}
-
-function run(cmd, { silent = false, dryRun = false, cwd } = {}) {
-  if (dryRun) {
-    console.log(`  [DRY RUN] ${cmd}`);
-    return "";
-  }
-  return execSync(cmd, {
-    stdio: silent ? "pipe" : "inherit",
-    cwd: cwd || process.cwd(),
-    encoding: "utf-8",
-  });
-}
-
-function startDockerDesktop() {
-  console.log("\x1b[1;33mDocker Desktop 未运行，正在启动...\x1b[0m");
-  try {
-    try {
-      execSync(
-        `powershell.exe -Command "Start-Process 'C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe'"`,
-        { stdio: "ignore" }
-      );
-    } catch {
-      execSync(
-        `cmd.exe /c start "" "C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe"`,
-        { stdio: "ignore" }
-      );
-    }
-
-    process.stdout.write("等待 Docker 引擎就绪");
-    for (let i = 0; i < 30; i++) {
-      try {
-        execSync("docker info", { stdio: "ignore" });
-        console.log("\n\x1b[0;32m✓ Docker 已就绪\x1b[0m");
-        return true;
-      } catch {}
-      process.stdout.write(".");
-      execSync("sleep 2", { stdio: "ignore" });
-    }
-    console.log("");
-    return false;
-  } catch {
-    return false;
-  }
-}
-
-async function dockerBuildPush(options = {}) {
-  const {
-    env = "prod",
-    registry = DEFAULT_REGISTRY,
-    namespace = DEFAULT_NAMESPACE,
-    local = false,
-    dryRun = false,
-    cicdUrl,
-  } = options;
-  const cicdLink = formatCicdLink(cicdUrl);
-
-  // 1. 检测运行模式并定位关键路径
-  const cwd = path.resolve(process.cwd());
-  const { isStandalone, contextRoot } = detectMode();
-
-  const appPkgPath = path.join(cwd, "package.json");
-  if (!fs.existsSync(appPkgPath)) {
-    console.error("错误: 当前目录下缺少 package.json，请在 app 目录内执行");
-    process.exit(1);
-  }
-
-  let buildContext, dockerfileArg, modeLabel;
-  if (isStandalone) {
-    if (!fs.existsSync(path.join(cwd, "Dockerfile"))) {
-      console.error("错误: 当前目录下缺少 Dockerfile");
-      process.exit(1);
-    }
-    buildContext = cwd;
-    dockerfileArg = "Dockerfile";
-    modeLabel = "独立模式";
-  } else {
-    const appDir = path.relative(contextRoot, cwd).replace(/\\/g, "/");
-    if (!fs.existsSync(path.join(contextRoot, appDir, "Dockerfile.monorepo"))) {
-      console.error("错误: 缺少 Dockerfile.monorepo");
-      process.exit(1);
-    }
-    buildContext = contextRoot;
-    dockerfileArg = `${appDir}/Dockerfile.monorepo`;
-    modeLabel = `monorepo 模式 (${appDir})`;
-  }
-
-  // 2. 从 package.json 推导镜像名
-  const pkg = JSON.parse(fs.readFileSync(appPkgPath, "utf-8"));
-  const imageName = pkg.name.replace(/^@[^/]+\//, "");
-
-  // 3. 获取版本号（monorepo 模式取 superproject 的 commit）
-  const commitHash = execSync("git rev-parse --short HEAD", {
-    cwd: contextRoot, encoding: "utf-8",
-  }).trim();
-  const fullCommit = execSync("git rev-parse HEAD", {
-    cwd: contextRoot, encoding: "utf-8",
-  }).trim();
-
-  // 4. 镜像标签
-  const imageBase = `${registry}/${namespace}/${imageName}`;
-  const tags = [`${imageBase}:${commitHash}`, `${imageBase}:${env}`];
-  if (env === "prod") tags.push(`${imageBase}:latest`);
-
-  // 5. Docker Desktop 自动启动（仅本地模式）
-  if (local) {
-    console.log("\x1b[0;32m>>> 检查 Docker 运行状态\x1b[0m");
-    try {
-      execSync("docker info", { stdio: "ignore" });
-      console.log("\x1b[0;32m✓ Docker 已运行\x1b[0m");
-    } catch {
-      const ok = startDockerDesktop();
-      if (!ok) {
-        console.error("\x1b[0;31m错误: Docker Desktop 启动超时，请手动启动后重试\x1b[0m");
-        process.exit(1);
-      }
-    }
-  }
-
-  // 6. 打印信息
-  console.log("\x1b[0;34m==========================================");
-  console.log("构建并推送 Docker 镜像");
-  console.log("==========================================\x1b[0m");
-  console.log(`运行模式:   ${modeLabel}`);
-  console.log(`镜像名称:   ${imageName}`);
-  console.log(`环境:        ${env}`);
-  console.log(`版本号:      ${commitHash}`);
-  console.log("标签:");
-  tags.forEach((t) => console.log(`  ${t}`));
-  console.log("");
-
-  // 7. 构建
-  console.log("\x1b[0;32m>>> 开始构建 Docker 镜像\x1b[0m");
-  const tagArgs = tags.map((t) => `-t ${t}`).join(" ");
-  const buildCmd = `docker build -f ${dockerfileArg} ${tagArgs} --build-arg GIT_COMMIT=${fullCommit} .`;
-  run(buildCmd, { cwd: buildContext, dryRun });
-  console.log("\x1b[0;32m✓ 镜像构建完成\x1b[0m");
-
-  // 8. 推送
-  console.log("");
-  console.log(`\x1b[0;32m>>> 推送镜像到 ${registry}\x1b[0m`);
-  for (const tag of tags) {
-    run(`docker push ${tag}`, { dryRun });
-  }
-
-  // 9. 结果摘要
-  console.log("");
-  console.log("\x1b[0;34m==========================================");
-  console.log("✅ 完成");
-  console.log("==========================================\x1b[0m");
-  console.log("可用标签:");
-  console.log(`  ${tags[0]}  (commit 精确版本)`);
-  console.log(`  ${tags[1]}       (${env} 环境)`);
-  if (env === "prod") console.log(`  ${tags[2]}    (最新)`);
-  if (cicdLink) {
-    console.log("");
-    console.log(cicdLink);
-  }
-  console.log("");
-
-  return { mode: isStandalone ? "standalone" : "monorepo", buildContext, imageName, commitHash, tags };
-}
-
-module.exports = { dockerBuildPush, detectMode, formatCicdLink };
+/**
+ * Docker 镜像构建与推送（infly-libs 公共模块）
+ *
+ * 支持两种运行模式（自动检测）：
+ *
+ * 1. Monorepo 模式 — 检测到 git submodule (--show-superproject-working-tree 有值)
+ *    构建上下文 = superproject 根，Dockerfile 使用 Dockerfile.monorepo
+ *    @infly/* 包从 workspace 源码解析
+ *
+ * 2. 独立模式 — 非 submodule 且 cwd = git 根
+ *    构建上下文 = 当前目录，Dockerfile 使用 Dockerfile
+ *    @infly/* 包从 npm registry 安装
+ *
+ * 用法：
+ *   infly-libs build:docker [--local] [--standalone] [--commit-only]
+ *     [--env prod|dev] [--dry-run] [--cicd-url URL]
+ *     [--health-check] [--health-timeout SECONDS] [--health-add-host HOST:IP]
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+// ---------- 默认配置 ----------
+const DEFAULT_REGISTRY = "ccr.ccs.tencentyun.com";
+const DEFAULT_NAMESPACE = "points";
+
+function formatCicdLink(value) {
+  if (value === undefined) {
+    return "";
+  }
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("--cicd-url 缺少参数值");
+  }
+
+  const rawUrl = value.trim();
+  if (/[\u0000-\u001f\u007f]/.test(rawUrl)) {
+    throw new Error("--cicd-url 不能包含控制字符");
+  }
+
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(rawUrl);
+  } catch {
+    throw new Error("--cicd-url 必须是合法的 HTTP/HTTPS URL");
+  }
+
+  if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
+    throw new Error("--cicd-url 只支持 HTTP/HTTPS URL");
+  }
+  if (parsedUrl.username || parsedUrl.password) {
+    throw new Error("--cicd-url 不能包含用户名或密码凭据");
+  }
+
+  return `发布系统：\x1b[34m${decodeURI(parsedUrl.href)}\x1b[0m`;
+}
+
+function detectMode({ standalone = false } = {}) {
+  const cwd = path.resolve(process.cwd());
+
+  if (standalone) {
+    const gitRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim();
+    if (path.resolve(cwd) !== path.resolve(gitRoot)) {
+      throw new Error("--standalone 必须在当前 Git 仓库根目录执行");
+    }
+    return { isStandalone: true, contextRoot: cwd };
+  }
+
+  // git submodule → monorepo 模式，contextRoot = superproject 根
+  try {
+    const superproject = execSync("git rev-parse --show-superproject-working-tree", {
+      encoding: "utf-8", stdio: "pipe",
+    }).trim();
+    if (superproject) {
+      return { isStandalone: false, contextRoot: superproject };
+    }
+  } catch {}
+
+  // 非 submodule：cwd = git 根 → 独立模式，否则 monorepo 模式
+  const gitRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim();
+  const isStandalone = path.resolve(cwd) === path.resolve(gitRoot);
+
+  return {
+    isStandalone,
+    contextRoot: isStandalone ? cwd : gitRoot,
+  };
+}
+
+function run(cmd, { silent = false, dryRun = false, cwd } = {}) {
+  if (dryRun) {
+    console.log(`  [DRY RUN] ${cmd}`);
+    return "";
+  }
+  return execSync(cmd, {
+    stdio: silent ? "pipe" : "inherit",
+    cwd: cwd || process.cwd(),
+    encoding: "utf-8",
+  });
+}
+
+function normalizeHealthOptions({ healthTimeout = "60", healthAddHost } = {}) {
+  const timeoutSeconds = Number(healthTimeout);
+  if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 600) {
+    throw new Error("--health-timeout 必须是 1 到 600 之间的整数秒");
+  }
+
+  if (
+    healthAddHost !== undefined &&
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*:(?:[A-Fa-f0-9:.]+|host-gateway)$/.test(healthAddHost)
+  ) {
+    throw new Error("--health-add-host 必须使用安全的 HOST:IP 或 HOST:host-gateway 格式");
+  }
+
+  return { timeoutSeconds, healthAddHost };
+}
+
+function normalizeTagPrefix(value) {
+  if (value === undefined || value === null) return "";
+  const prefix = String(value).trim();
+  if (!prefix) return "";
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/.test(prefix)) {
+    throw new Error(
+      "--tag-prefix 必须以字母或数字开头，最多 40 字符，且只包含字母、数字、点、下划线和连字符"
+    );
+  }
+  return prefix;
+}
+
+function resolveImageTags(imageBase, commitHash, env, commitOnly = false, tagPrefix = "") {
+  const tags = [`${imageBase}:${tagPrefix}${commitHash}`];
+  if (commitOnly) return tags;
+  tags.push(`${imageBase}:${tagPrefix}${env}`);
+  if (env === "prod") tags.push(`${imageBase}:${tagPrefix}latest`);
+  return tags;
+}
+
+function wait(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function healthCheckImage(imageTag, options = {}) {
+  const { dryRun = false, imageName = "image" } = options;
+  const { timeoutSeconds, healthAddHost } = normalizeHealthOptions(options);
+  const safeImageName = imageName.replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 40);
+  const containerName = `infly-health-${safeImageName}-${process.pid}-${Date.now()}`;
+  const addHostArg = healthAddHost ? ` --add-host ${healthAddHost}` : "";
+
+  console.log("");
+  console.log("\x1b[0;32m>>> 启动临时容器并等待镜像 HEALTHCHECK\x1b[0m");
+  run(`docker run --detach --name ${containerName}${addHostArg} ${imageTag}`, { dryRun });
+
+  if (dryRun) {
+    run(`docker inspect --format health-status ${containerName}`, { dryRun });
+    run(`docker rm --force ${containerName}`, { dryRun });
+    console.log("\x1b[0;32m✓ [DRY RUN] 镜像健康检查计划完成\x1b[0m");
+    return;
+  }
+
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let lastStatus = "starting";
+  try {
+    while (Date.now() < deadline) {
+      lastStatus = run(
+        `docker inspect --format "{{if .State.Health}}{{.State.Health.Status}}{{else}}missing{{end}}" ${containerName}`,
+        { silent: true }
+      ).trim();
+
+      if (lastStatus === "healthy") {
+        console.log("\x1b[0;32m✓ 镜像健康检查通过\x1b[0m");
+        return;
+      }
+      if (lastStatus === "unhealthy" || lastStatus === "missing") {
+        break;
+      }
+      wait(1000);
+    }
+
+    console.error(`\x1b[0;31m镜像健康检查失败，最终状态: ${lastStatus}\x1b[0m`);
+    run(`docker logs ${containerName}`);
+    throw new Error(`镜像 ${imageTag} 未通过健康检查，已阻止推送`);
+  } finally {
+    try {
+      run(`docker rm --force ${containerName}`, { silent: true });
+    } catch (cleanupError) {
+      console.warn(`警告: 临时容器 ${containerName} 清理失败: ${cleanupError.message}`);
+    }
+  }
+}
+
+function startDockerDesktop() {
+  console.log("\x1b[1;33mDocker Desktop 未运行，正在启动...\x1b[0m");
+  try {
+    try {
+      execSync(
+        `powershell.exe -Command "Start-Process 'C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe'"`,
+        { stdio: "ignore" }
+      );
+    } catch {
+      execSync(
+        `cmd.exe /c start "" "C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe"`,
+        { stdio: "ignore" }
+      );
+    }
+
+    process.stdout.write("等待 Docker 引擎就绪");
+    for (let i = 0; i < 30; i++) {
+      try {
+        execSync("docker info", { stdio: "ignore" });
+        console.log("\n\x1b[0;32m✓ Docker 已就绪\x1b[0m");
+        return true;
+      } catch {}
+      process.stdout.write(".");
+      execSync("sleep 2", { stdio: "ignore" });
+    }
+    console.log("");
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+async function dockerBuildPush(options = {}) {
+  const {
+    env = "prod",
+    registry = DEFAULT_REGISTRY,
+    namespace = DEFAULT_NAMESPACE,
+    local = false,
+    dryRun = false,
+    cicdUrl,
+    healthCheck = false,
+    healthTimeout,
+    healthAddHost,
+    version,
+    revision,
+    standalone = false,
+    commitOnly = false,
+    tagPrefix,
+  } = options;
+  const cicdLink = formatCicdLink(cicdUrl);
+
+  // 1. 检测运行模式并定位关键路径
+  const cwd = path.resolve(process.cwd());
+  const { isStandalone, contextRoot } = detectMode({ standalone });
+
+  const appPkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(appPkgPath)) {
+    console.error("错误: 当前目录下缺少 package.json，请在 app 目录内执行");
+    process.exit(1);
+  }
+
+  let buildContext, dockerfileArg, modeLabel;
+  if (isStandalone) {
+    if (!fs.existsSync(path.join(cwd, "Dockerfile"))) {
+      console.error("错误: 当前目录下缺少 Dockerfile");
+      process.exit(1);
+    }
+    buildContext = cwd;
+    dockerfileArg = "Dockerfile";
+    modeLabel = "独立模式";
+  } else {
+    const appDir = path.relative(contextRoot, cwd).replace(/\\/g, "/");
+    if (!fs.existsSync(path.join(contextRoot, appDir, "Dockerfile.monorepo"))) {
+      console.error("错误: 缺少 Dockerfile.monorepo");
+      process.exit(1);
+    }
+    buildContext = contextRoot;
+    dockerfileArg = `${appDir}/Dockerfile.monorepo`;
+    modeLabel = `monorepo 模式 (${appDir})`;
+  }
+
+  // 2. 从 package.json 推导镜像名
+  const pkg = JSON.parse(fs.readFileSync(appPkgPath, "utf-8"));
+  const imageName = pkg.name.replace(/^@[^/]+\//, "");
+
+  // 3. 获取版本号（monorepo 模式取 superproject 的 commit）
+  const commitHash = version || execSync("git rev-parse --short HEAD", {
+    cwd: contextRoot, encoding: "utf-8",
+  }).trim();
+  const fullCommit = revision || execSync("git rev-parse HEAD", {
+    cwd: contextRoot, encoding: "utf-8",
+  }).trim();
+  if (!/^[0-9a-f]{7,40}$/i.test(commitHash) || !/^[0-9a-f]{7,40}$/i.test(fullCommit)) {
+    throw new Error("Docker 镜像版本和 revision 必须是合法的 Git commit hash");
+  }
+
+  // 4. 镜像标签
+  const imageBase = `${registry}/${namespace}/${imageName}`;
+  const normalizedPrefix = normalizeTagPrefix(tagPrefix);
+  const tags = resolveImageTags(imageBase, commitHash, env, commitOnly, normalizedPrefix);
+
+  // 5. Docker Desktop 自动启动（仅本地模式）
+  if (local) {
+    console.log("\x1b[0;32m>>> 检查 Docker 运行状态\x1b[0m");
+    try {
+      execSync("docker info", { stdio: "ignore" });
+      console.log("\x1b[0;32m✓ Docker 已运行\x1b[0m");
+    } catch {
+      const ok = startDockerDesktop();
+      if (!ok) {
+        console.error("\x1b[0;31m错误: Docker Desktop 启动超时，请手动启动后重试\x1b[0m");
+        process.exit(1);
+      }
+    }
+  }
+
+  // 6. 打印信息
+  console.log("\x1b[0;34m==========================================");
+  console.log("构建并推送 Docker 镜像");
+  console.log("==========================================\x1b[0m");
+  console.log(`运行模式:   ${modeLabel}`);
+  console.log(`镜像名称:   ${imageName}`);
+  console.log(`环境:        ${env}`);
+  console.log(`版本号:      ${commitHash}`);
+  if (normalizedPrefix) {
+    console.log(`标签前缀:   ${normalizedPrefix}（全部标签带此前缀，发布标签由 CI 晋升）`);
+  }
+  console.log("标签:");
+  tags.forEach((t) => console.log(`  ${t}`));
+  console.log("");
+
+  // 7. 构建
+  console.log("\x1b[0;32m>>> 开始构建 Docker 镜像\x1b[0m");
+  const tagArgs = tags.map((t) => `-t ${t}`).join(" ");
+  const buildCmd = `docker build -f ${dockerfileArg} ${tagArgs} --build-arg GIT_COMMIT=${fullCommit} --label org.opencontainers.image.revision=${fullCommit} --label org.opencontainers.image.version=${commitHash} .`;
+  run(buildCmd, { cwd: buildContext, dryRun });
+  console.log("\x1b[0;32m✓ 镜像构建完成\x1b[0m");
+
+  // 8. 可选镜像健康门禁（失败会抛错，任何标签都不会推送）
+  if (healthCheck) {
+    healthCheckImage(tags[0], {
+      dryRun,
+      imageName,
+      healthTimeout,
+      healthAddHost,
+    });
+  }
+
+  // 9. 推送
+  console.log("");
+  console.log(`\x1b[0;32m>>> 推送镜像到 ${registry}\x1b[0m`);
+  for (const tag of tags) {
+    run(`docker push ${tag}`, { dryRun });
+  }
+
+  // 10. 结果摘要
+  console.log("");
+  console.log("\x1b[0;34m==========================================");
+  console.log("✅ 完成");
+  console.log("==========================================\x1b[0m");
+  console.log("可用标签:");
+  console.log(`  ${tags[0]}  (commit 精确版本)`);
+  if (!commitOnly) {
+    console.log(`  ${tags[1]}       (${env} 环境)`);
+    if (env === "prod") console.log(`  ${tags[2]}    (最新)`);
+  }
+  if (cicdLink) {
+    console.log("");
+    console.log(cicdLink);
+  }
+  console.log("");
+
+  return { mode: isStandalone ? "standalone" : "monorepo", buildContext, imageName, commitHash, tags };
+}
+
+module.exports = {
+  dockerBuildPush,
+  detectMode,
+  formatCicdLink,
+  healthCheckImage,
+  normalizeHealthOptions,
+  normalizeTagPrefix,
+  resolveImageTags,
+};