企业级 AI Agent 源码交付离线可重现编译构建架构实战：破解物理隔离内网依赖地狱、异构工具链冲突与确定性镜像打包难题

import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
import { resolve, join } from 'node:path';
import { createHash } from 'node:crypto';

/**
 * 依赖包审计项定义
 */
export interface PackageAuditItem {
  name: string;
  version: string;
  ecosystem: 'python' | 'npm';
  expectedHash: string;
  actualHash?: string;
  archivePath?: string;
  passed: boolean;
  failureReason?: string;
}

/**
 * 离线构建完整性审计报告
 */
export interface IntegrityAuditReport {
  timestamp: string;
  targetArchitecture: string;
  totalDependenciesChecked: number;
  passedCount: number;
  failedCount: number;
  isCompliant: boolean;
  suspiciousNetworkUrls: string[];
  auditedPackages: PackageAuditItem[];
}

/**
 * 生产级离线构建依赖完整性与合规审计引擎
 */
export class OfflineBuildIntegrityAuditor {
  private readonly offlineRepoPath: string;
  private readonly targetArch: string;

  /**
   * 初始化审计引擎
   * @param offlineRepoPath 本地离线制品与预编译轮子挂载目录
   * @param targetArch 目标硬件架构（如 x86_64, aarch64）
   */
  constructor(offlineRepoPath: string, targetArch: string = 'x86_64') {
    this.offlineRepoPath = resolve(offlineRepoPath);
    this.targetArch = targetArch;
  }

  /**
   * 计算本地文件的散列值（SHA-256）
   * @param filePath 物理文件绝对路径
   */
  private calculateFileSha256(filePath: string): string {
    const buffer = readFileSync(filePath);
    return createHash('sha256').update(buffer).digest('hex');
  }

  /**
   * 递归检索本地仓库中的文件索引
   * @param directory 检索基准目录
   */
  private buildLocalFileIndex(directory: string): Map<string, string> {
    const fileIndex = new Map<string, string>();
    if (!existsSync(directory)) return fileIndex;

    const walk = (currentDir: string) => {
      const entries = readdirSync(currentDir);
      for (const entry of entries) {
        const fullPath = join(currentDir, entry);
        const stat = statSync(fullPath);
        if (stat.isDirectory()) {
          walk(fullPath);
        } else if (stat.isFile()) {
          fileIndex.set(entry.toLowerCase(), fullPath);
        }
      }
    };

    walk(directory);
    return fileIndex;
  }

  /**
   * 解析 Python 锁文件（支持标准 requirements.lock 格式）
   * @param lockFilePath requirements.lock 路径
   */
  public parsePythonLockfile(lockFilePath: string): PackageAuditItem[] {
    if (!existsSync(lockFilePath)) {
      throw new Error(`Python 锁文件不存在: ${lockFilePath}`);
    }

    const content = readFileSync(lockFilePath, 'utf8');
    const lines = content.split('\n');
    const items: PackageAuditItem[] = [];

    let currentItem: Partial<PackageAuditItem> | null = null;

    for (const rawLine of lines) {
      const line = rawLine.trim();
      if (!line || line.startsWith('#')) continue;

      const pkgMatch = line.match(/^([a-zA-Z0-9_\-\.]+)\s*==\s*([a-zA-Z0-9_\-\.]+)/);
      if (pkgMatch) {
        if (currentItem && currentItem.name && currentItem.expectedHash) {
          items.push(currentItem as PackageAuditItem);
        }
        currentItem = {
          name: pkgMatch[1],
          version: pkgMatch[2],
          ecosystem: 'python',
          passed: false
        };
      }

      const hashMatch = line.match(/--hash=sha256:([a-fA-F0-9]{64})/);
      if (hashMatch && currentItem) {
        currentItem.expectedHash = hashMatch[1].toLowerCase();
      }
    }

    if (currentItem && currentItem.name && currentItem.expectedHash) {
      items.push(currentItem as PackageAuditItem);
    }

    return items;
  }

  /**
   * 执行全链路离线完整性审计
   * @param pythonLockPath Python requirements.lock 路径
   */
  public async executeAudit(pythonLockPath: string): Promise<IntegrityAuditReport> {
    const startTime = new Date().toISOString();
    const localIndex = this.buildLocalFileIndex(this.offlineRepoPath);
    const pythonItems = this.parsePythonLockfile(pythonLockPath);

    const auditedItems: PackageAuditItem[] = [];
    const suspiciousUrls: string[] = [];

    for (const item of pythonItems) {
      const expectedNormalizedName = item.name.replace(/[-_.]+/g, '_').toLowerCase();
      let matchedFile: string | undefined;

      for (const [fileName, fullPath] of localIndex.entries()) {
        if (fileName.startsWith(`${expectedNormalizedName}-${item.version}`) && fileName.endsWith('.whl')) {
          matchedFile = fullPath;
          break;
        }
      }

      if (!matchedFile) {
        item.passed = false;
        item.failureReason = `离线制品库中缺失匹配的 Wheel 包: ${item.name}==${item.version}`;
        auditedItems.push(item);
        continue;
      }

      item.archivePath = matchedFile;
      const actualSha256 = this.calculateFileSha256(matchedFile);
      item.actualHash = actualSha256;

      if (actualSha256 !== item.expectedHash) {
        item.passed = false;
        item.failureReason = `SHA-256 校验失败! 预期: ${item.expectedHash}, 实际: ${actualSha256}`;
      } else {
        item.passed = true;
      }

      auditedItems.push(item);
    }

    const passedCount = auditedItems.filter(i => i.passed).length;
    const failedCount = auditedItems.length - passedCount;

    return {
      timestamp: startTime,
      targetArchitecture: this.targetArch,
      totalDependenciesChecked: auditedItems.length,
      passedCount,
      failedCount,
      isCompliant: failedCount === 0,
      suspiciousNetworkUrls: suspiciousUrls,
      auditedPackages: auditedItems
    };
  }
}

# ==========================================
# 阶段一：密封编译构建沙箱（Builder）
# ==========================================
FROM harbor.corp.internal/base/manylinux2014_x86_64:2026.11 AS builder

# 固化构建时间戳，防止元数据随机漂移
ARG BUILD_DATE_EPOCH=1731369600
ENV SOURCE_DATE_EPOCH=${BUILD_DATE_EPOCH} \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1

WORKDIR /build

# 1. 复制本地锁文件与预编译轮子索引（完全不访问外网）
COPY constraints.txt requirements.lock /build/
COPY offline-wheels/ /build/offline-wheels/

# 2. 建立纯隔离虚拟运行环境并离线安装依赖
RUN python3.11 -m venv /opt/venv && \
    /opt/venv/bin/pip install --upgrade pip --no-index --find-links=/build/offline-wheels/ && \
    /opt/venv/bin/pip install \
      --no-index \
      --find-links=/build/offline-wheels/ \
      --no-build-isolation \
      --constraint=/build/constraints.txt \
      -r /build/requirements.lock

# 3. 复制核心智能体编排引擎源码并执行离线 C++ 算子编译
COPY engine-src/ /build/engine-src/
RUN cd /build/engine-src && \
    /opt/venv/bin/python setup.py build_ext --inplace

# ==========================================
# 阶段二：生产级轻量安全运行镜像（Runtime）
# ==========================================
FROM harbor.corp.internal/base/debian-slim:12-202611 AS runtime

# 仅安装必要运行时动态链接库（完全无编译器、无 gcc、无 git）
RUN apt-get update && apt-get install -y --no-install-recommends \
    libgomp1 \
    libnuma1 \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# 从 Builder 阶段仅复制预编译好的独立虚拟环境与工程产物
COPY --from=builder /opt/venv /opt/venv
COPY --from=builder /build/engine-src/dist /app/engine

# 设定专用非 root 安全运行账号
RUN useradd -u 10001 -m -s /bin/bash bxagent && \
    chown -R bxagent:bxagent /app
USER bxagent

WORKDIR /app
ENV PATH="/opt/venv/bin:$PATH" \
    PYTHONPATH="/app/engine"

EXPOSE 8080
ENTRYPOINT ["python", "-m", "bxagent.runtime.main"]