Apache Geaflow推理框架Geaflow-infer 解析系列（三）环境初始化流程

第3章：环境初始化流程

章节导读

"工欲善其事，必先利其器"。在 Java 进程可以调用 Python 推理之前，必须先准备好 Python 的运行环境。本章将深入讲解 geaflow-infer 如何初始化虚拟环境 、如何通过文件锁确保并发安全 、以及如何管理环境的生命周期。

通过本章，你将理解：

• 为什么 需要虚拟环境（依赖隔离、版本控制）
• 如何 实现单例模式和文件锁机制
• 如何 处理初始化失败和状态恢复

---

3.1 InferEnvironmentManager 单例模式设计

设计目标

InferEnvironmentManager 采用单例模式的原因：

问题场景:
  应用启动 10 个线程，都要初始化推理环境
  
没有单例的后果:
  ├─ 线程1: 创建虚拟环境 /env1 (耗时 5 秒)
  ├─ 线程2: 创建虚拟环境 /env2 (重复创建! 浪费时间)
  ├─ 线程3: 创建虚拟环境 /env3 (重复创建! 浪费时间)
  └─ ...
  总耗时: 50 秒，浪费了 45 秒

使用单例的效果:
  ├─ 线程1: 创建虚拟环境 /env (耗时 5 秒)
  ├─ 线程2: 等待线程1完成，复用 /env (0 秒)
  ├─ 线程3: 等待线程1完成，复用 /env (0 秒)
  └─ ...
  总耗时: 5 秒，所有线程共享一个环境

实现细节

双重检查锁定（Double-Checked Locking）

public class InferEnvironmentManager {
    private static InferEnvironmentManager INSTANCE = null;
    private static final Object LOCK = new Object();
    
    // 静态标志：初始化是否完成
    private static final AtomicBoolean INITIALIZED = new AtomicBoolean(false);
    private static final AtomicBoolean SUCCESS_FLAG = new AtomicBoolean(false);
    private static final AtomicReference<Throwable> ERROR_CASE = 
        new AtomicReference<>();
    
    // 初始化过程中的虚拟环境上下文
    private static InferEnvironmentContext environmentContext = null;
    
    /**
     * 构建并返回单例
     */
    public static synchronized InferEnvironmentManager 
        buildInferEnvironmentManager(Configuration config) {
        if (INSTANCE == null) {
            // 关键: 只有首次调用时才创建实例
            // synchronized 关键字保证线程安全
            INSTANCE = new InferEnvironmentManager(config);
        }
        return INSTANCE;
    }
    
    /**
     * 私有构造函数，防止外部直接 new
     */
    private InferEnvironmentManager(Configuration config) {
        this.configuration = config;
        this.executorService = Executors.newSingleThreadExecutor();
        // 触发异步初始化
        createEnvironment();
    }
    
    /**
     * 创建虚拟环境（异步执行）
     */
    public void createEnvironment() {
        // 使用 compareAndSet 确保只初始化一次
        if (INITIALIZED.compareAndSet(false, true)) {
            // 后台线程执行初始化
            executorService.execute(() -> {
                try {
                    environmentContext = constructInferEnvironment(configuration);
                    if (environmentContext.enableFinished()) {
                        SUCCESS_FLAG.set(true);
                        LOGGER.info("✓ 虚拟环境初始化成功");
                    }
                } catch (Throwable e) {
                    SUCCESS_FLAG.set(false);
                    ERROR_CASE.set(e);
                    LOGGER.error("✗ 虚拟环境初始化失败", e);
                }
            });
        }
    }
}

关键特性分析

1. 原子性（Atomicity）

//  错误做法：
private static boolean INITIALIZED = false;
if (!INITIALIZED) {  // Check
    INITIALIZED = true;  // Set
    initialize();  // 两个操作之间可能被中断
}

// ✓ 正确做法：
if (INITIALIZED.compareAndSet(false, true)) {  // 原子操作
    initialize();
}

优势:
  compareAndSet 是单条 CPU 指令，不可中断
  保证即使两个线程同时调用，也只有一个会成功

2. 可见性（Visibility）

// AtomicBoolean 的写操作包含内存屏障
SUCCESS_FLAG.set(true);  // 写操作，带屏障
// ↓ (内存屏障)
// 所有线程都能立即看到 true

// ✓ 任何线程的读操作都能看到最新值
if (SUCCESS_FLAG.get()) {  // 读操作，带屏障
    ...
}

---

3.2 虚拟环境创建流程

总流程概览

用户代码调用
    ↓
InferContext.build(config)
    ↓
InferEnvironmentManager.buildInferEnvironmentManager(config)
    ├─→ [同步返回单例] (不阻塞用户)
    │
    └─→ [后台线程] (异步初始化)
        ↓
        constructInferEnvironment(config)
        ├─→ Step1: 初始化 InferEnvironmentContext
        │   - 获取虚拟环境目录
        │   - 获取 Python 文件目录
        │   - 生成角色标识 (hostname:pid)
        │   - 初始化各种路径
        │   ↓
        ├─→ Step2: 创建 InferDependencyManager
        │   - 从 JAR 提取依赖文件
        │   - 生成 requirements.txt
        │   - 准备初始化脚本路径
        │   ↓
        ├─→ Step3: 使用文件锁，避免重复初始化
        │   - 创建锁文件
        │   - 获取文件锁（阻塞直到获得）
        │   - 检查 _finish 或 _failed 标记文件
        │   ↓
        ├─→ Step4: 执行 Shell 脚本创建虚拟环境
        │   - 调用 install-infer-env.sh
        │   - 创建 Conda 虚拟环境
        │   - 安装 Python 依赖包
        │   ↓
        ├─→ Step5: 标记初始化完成
        │   - 创建 _finish 或 _failed 标记文件
        │   - 释放文件锁
        │   ↓
        └─→ 设置 SUCCESS_FLAG 或 ERROR_CASE

分步详解

Step1: InferEnvironmentContext 初始化

private InferEnvironmentContext constructInferEnvironment(
    Configuration configuration) throws Exception {
    
    // 获取配置
    String inferEnvDirectory = configuration
        .getString(GeaFlowConfigKey.GEAFLOW_INFER_ENV_DIR);
    String inferFilesDirectory = configuration
        .getString(GeaFlowConfigKey.GEAFLOW_INFER_FILES_DIR);
    
    // 创建上下文
    InferEnvironmentContext context = 
        new InferEnvironmentContext(
            inferEnvDirectory,
            inferFilesDirectory,
            configuration
        );
    
    // InferEnvironmentContext 中的关键初始化
    // - virtualEnvDirectory: 虚拟环境目录
    // - inferFilesDirectory: Python 脚本目录
    // - pythonExec: Python 可执行文件路径
    // - inferScript: infer_server.py 路径
    // - roleNameIndex: "hostname:pid" 形式的唯一标识
    
    return context;
}

关键数据：

配置示例:
  GEAFLOW_INFER_ENV_DIR = "/tmp/geaflow_infer_env"
  GEAFLOW_INFER_FILES_DIR = "/tmp/geaflow_infer_files"

初始化后:
  virtualEnvDirectory = "/tmp/geaflow_infer_env"
  pythonExec = "/tmp/geaflow_infer_env/conda/bin/python3"
  inferScript = "/tmp/geaflow_infer_files/infer_server.py"
  roleNameIndex = "hostname:12345" (主机名:进程ID)

Step2: InferDependencyManager 初始化

// 在 Step1 之后
InferDependencyManager dependencyManager = 
    new InferDependencyManager(environmentContext);

// 内部做了什么？
public class InferDependencyManager {
    public InferDependencyManager(InferEnvironmentContext context) {
        this.environmentContext = context;
        
        // 1. 从 JAR 中提取运行时文件
        List<String> runtimeFiles = buildInferRuntimeFiles();
        // 返回: ["infer/infer_server.py", "infer/requirements.txt", ...]
        
        // 2. 将文件复制到目标目录
        for (String file : runtimeFiles) {
            copyFileFromJar(file, 
                environmentContext.getInferFilesDirectory());
        }
        
        // 3. 准备初始化脚本路径
        this.buildInferEnvShellPath = 
            environmentContext.getInferFilesDirectory() 
            + "/install-infer-env.sh";
        
        // 4. 准备 requirements.txt 路径
        this.inferEnvRequirementsPath = 
            environmentContext.getInferFilesDirectory() 
            + "/requirements.txt";
    }
}

从 JAR 提取文件的原理：

JAR 结构:
  geaflow-infer.jar
  ├─ META-INF/
  ├─ org/apache/geaflow/...  (编译的 class 文件)
  └─ infer/  (资源文件)
     ├─ infer_server.py       (Python 服务脚本)
     ├─ requirements.txt       (Python 依赖)
     ├─ install-infer-env.sh   (初始化脚本)
     ├─ env/
     │  └─ install-infer-env.sh
     └─ inferRuntime/
        ├─ some_lib.so
        └─ config.json

提取流程:
  1. 使用 ClassLoader.getResource("infer/inferRuntime")
  2. 列出所有文件
  3. 使用 InputStream 逐个读取
  4. 写入到目标目录

Step3: 文件锁机制（详细见后续小节）

// 关键代码
File lockFile = new File(inferEnvDirectory + "/" + LOCK_FILE);
FileLock lock = InferFileUtils.addLock(lockFile);  // 获取锁

try {
    // 检查是否已初始化
    File finishFile = new File(inferEnvDirectory + "/._finish");
    File failedFile = new File(inferEnvDirectory + "/._failed");
    
    if (failedFile.exists()) {
        // 之前初始化失败，这次也会失败
        environmentContext.setFinished(false);
        return environmentContext;
    }
    
    if (finishFile.exists()) {
        // 已初始化成功，直接返回
        environmentContext.setFinished(true);
        return environmentContext;
    }
    
    // Step4: 执行初始化脚本
    executeInstallScript(...);
    
    // Step5: 创建 _finish 标记
    finishFile.createNewFile();
    
} finally {
    lock.release();  // 释放锁
}

Step4 & Step5: 执行 Shell 脚本

#!/bin/bash
# install-infer-env.sh

ENV_DIR=$1
REQUIREMENTS_FILE=$2

# Step 1: 创建 Conda 虚拟环境
conda create -p ${ENV_DIR}/conda python=3.8 -y

# Step 2: 激活虚拟环境
source ${ENV_DIR}/conda/bin/activate

# Step 3: 安装 Python 依赖
pip install -r ${REQUIREMENTS_FILE}

# Step 4: 验证安装
python -c "import sys; print('OK')"

echo "虚拟环境初始化成功"

requirements.txt 示例：

# 基础依赖
numpy==1.21.0
scipy==1.7.0

# ML 库
tensorflow==2.6.0
torch==1.9.0
scikit-learn==0.24.2

# 工具
pydantic==1.8.2

---

3.3 文件锁机制实现

设计问题

场景: 多个 GeaFlow 应用实例运行在同一台机器，
     共享同一个虚拟环境目录

问题:
  实例A                    实例B
    │                        │
    └─→ 进程启动             └─→ 进程启动
        ├─→ 检查 _finish  ✗    ├─→ 检查 _finish  ✗
        ├─→ 开始初始化         ├─→ 开始初始化
        │   conda create...    │   conda create...
        │   安装依赖(耗时5s)    │   (重复安装! 可能冲突)
        │   ...                │   ...
        ├─→ 创建 _finish ✓     └─→ 创建 _finish ✓
        │                       
        └─→ 初始化完成          └─→ 初始化完成

问题: 两个进程都认为虚拟环境还未初始化，
     都开始初始化，导致重复和冲突！

文件锁解决方案

Java 中的 FileLock

public static FileLock addLock(File lockFile) throws IOException {
    // Step 1: 创建锁文件
    if (!lockFile.exists()) {
        lockFile.createNewFile();
    }
    
    // Step 2: 打开文件通道
    RandomAccessFile raf = new RandomAccessFile(lockFile, "rw");
    FileChannel channel = raf.getChannel();
    
    // Step 3: 请求文件锁
    // 如果锁已被其他进程持有，这里会阻塞
    FileLock lock = channel.lock();  // 阻塞直到获得锁
    
    // 返回后，说明已获得独占锁
    return lock;
}

流程图

实例A                        文件系统             实例B
  │                             │                  │
  ├─→ 打开 lock 文件             │                  │
  ├─→ 请求锁 lock.lock()        │                  │
  │   [获得锁 ✓] ←──────────────┤                  │
  │                             │ ←─────────────────┤
  │                             │                  ├─→ 打开 lock 文件
  │                             │                  ├─→ 请求锁 lock.lock()
  │   [持有锁中...]              │                  │   [阻塞，等待锁] 
  │   ├─→ 检查 _finish  ✗        │                  │
  │   ├─→ 初始化虚拟环境         │                  │   [等待...]
  │   │   conda create...        │                  │   [等待...]
  │   │   pip install...         │                  │
  │   │   [耗时 5 秒]             │                  │
  │   ├─→ 创建 _finish ✓         │                  │
  │   └─→ 释放锁                 │                  │
  │       lock.release()         │ ────────────────→│
  │                             │                  ├─→ [获得锁 ✓]
  │                             │                  ├─→ 检查 _finish ✓
  │                             │                  ├─→ [已初始化，跳过]
  │                             │                  └─→ 释放锁

完整的初始化流程（带文件锁）

public InferEnvironmentContext constructInferEnvironment(
    Configuration configuration) throws Exception {
    
    // Step 1: 创建环境上下文
    InferEnvironmentContext context = 
        new InferEnvironmentContext(inferEnvDirectory, ...);
    
    // Step 2: 创建依赖管理器
    InferDependencyManager depManager = 
        new InferDependencyManager(context);
    
    // Step 3: 获取文件锁（关键！）
    File lockFile = new File(inferEnvDirectory + "/.lock");
    FileLock lock = InferFileUtils.addLock(lockFile);
    
    try {
        // Step 4: 检查初始化状态
        File finishFile = new File(inferEnvDirectory + "/._finish");
        File failedFile = new File(inferEnvDirectory + "/._failed");
        
        if (failedFile.exists()) {
            LOGGER.warn("虚拟环境之前初始化失败，本次也可能失败");
            context.setFinished(false);
            return context;
        }
        
        if (finishFile.exists()) {
            LOGGER.info("虚拟环境已初始化，直接使用");
            context.setFinished(true);
            return context;
        }
        
        // Step 5: 执行初始化脚本
        LOGGER.info("开始初始化虚拟环境...");
        String shellPath = depManager.getInferEnvShellPath();
        String requirementsPath = depManager.getInferEnvRequirementsPath();
        
        ProcessBuilder pb = new ProcessBuilder(
            "bash", shellPath, inferEnvDirectory, requirementsPath
        );
        pb.redirectErrorStream(true);
        Process process = pb.start();
        
        int exitCode = process.waitFor();
        if (exitCode != 0) {
            failedFile.createNewFile();  // 标记失败
            context.setFinished(false);
            throw new RuntimeException("虚拟环境初始化失败");
        }
        
        // Step 6: 标记成功
        finishFile.createNewFile();
        context.setFinished(true);
        LOGGER.info("虚拟环境初始化成功");
        
    } finally {
        // 一定要释放锁！
        lock.release();
    }
    
    return context;
}

文件锁的细节

锁的作用范围

// 同一 JVM 内的不同线程:
  线程A: fileLock1 = channel.lock()
  线程B: fileLock2 = channel.lock()  // 会阻塞！

// 不同 JVM 进程:
  Java进程A: fileLock1 = channel.lock()
  Java进程B: fileLock2 = channel.lock()  // 会阻塞！
  
  C进程: flock() 或 fcntl()  // 也会被阻塞

结论: FileLock 是进程级别的，不仅仅是线程级别

锁的自动释放

// 自动释放情况:
1. 显式调用 lock.release()
2. 持有 Lock 的 FileChannel 关闭
3. 持有 Lock 的 JVM 进程终止

// ❌ 危险做法:
RandomAccessFile raf = new RandomAccessFile(file, "rw");
FileChannel channel = raf.getChannel();
FileLock lock = channel.lock();
// ... 忘记释放 ...
// 锁会在进程终止时自动释放，但期间会阻塞其他进程

// ✓ 正确做法:
try {
    lock = channel.lock();
    // ... 关键操作 ...
} finally {
    if (lock != null) lock.release();
    if (channel != null) channel.close();
    if (raf != null) raf.close();
}

---

3.4 环境状态管理与错误处理

状态机设计

┌─────────────┐
│   INITIAL   │  应用刚启动
│  (初始状态)  │
└──────┬──────┘
       │
       │ buildInferEnvironmentManager()
       ▼
┌─────────────┐
│ INITIALIZING│  虚拟环境初始化中
│  (初始化中)  │
└──────┬──────┘
       │
   ┌───┴───┐
   │       │
   ▼       ▼
┌──────┐ ┌──────┐
│SUCCESS │FAILED│  初始化结果
└──────┘ └──────┘
 │        │
 │        │ 后续 infer() 调用
 │        ▼
 │     ┌────────────────┐
 │     │ 抛出异常        │
 │     │(初始化失败)      │
 │     └────────────────┘
 │
 │ 后续 infer() 调用
 ▼
┌────────────────┐
│ RUNNING        │
│ (推理中)        │
└────────────────┘

关键状态检查

public class InferEnvironmentManager {
    
    // 1. 检查初始化是否完成
    public static Boolean checkInferEnvironmentStatus() {
        return SUCCESS_FLAG.get();
    }
    
    // 2. 获取环境上下文
    public static InferEnvironmentContext getEnvironmentContext() {
        return environmentContext;
    }
    
    // 3. 检查并抛出错误
    public static void checkError() {
        final Throwable exception = ERROR_CASE.get();
        if (exception != null) {
            String message = "虚拟环境初始化失败: " 
                + exception.getMessage();
            LOGGER.error(message);
            throw new GeaflowRuntimeException(message, exception);
        }
    }
}

在 InferContext 中的使用

public class InferContext {
    
    public <OUT> OUT infer(Object... inputs) throws IOException {
        // 1. 检查虚拟环境是否初始化成功
        InferEnvironmentManager.checkError();
        
        // 2. 等待虚拟环境就绪（如果还在初始化）
        while (!InferEnvironmentManager.checkInferEnvironmentStatus()) {
            Thread.sleep(100);  // 等待 100ms
            InferEnvironmentManager.checkError();  // 检查是否失败
            
            if (System.currentTimeMillis() - startTime > TIMEOUT) {
                throw new TimeoutException("虚拟环境初始化超时");
            }
        }
        
        // 3. 虚拟环境就绪，开始推理
        return dataBridge.read();  // 这里已安全
    }
}

错误恢复机制

场景 1: 初始化脚本失败

infer() 调用
  ↓
检查虚拟环境状态
  ├─→ SUCCESS_FLAG = false ✗
  ├─→ ERROR_CASE = RuntimeException("conda create failed")
  │
  └─→ 抛出异常给用户
      用户应处理这个异常：
      - 检查网络连接（pip 下载）
      - 检查磁盘空间
      - 检查 requirements.txt 是否有冲突
      - 手动删除虚拟环境目录，重新初始化

场景 2: 进程中途崩溃

虚拟环境初始化中...
  → conda create... ✓
  → pip install... ✓
  → 写入 _finish ✓
  → 释放锁
  
此时 process 异常退出

下次启动:
  检查 _finish ✓ 存在
  → 直接使用已初始化的环境
  → 不重复初始化

---

最佳实践

// ✓ 正确用法
try {
    InferContext context = InferContext.build(config);
    
    // 虚拟环境初始化在后台进行
    // 这里立即返回，不会阻塞
    
    Object result = context.infer(features);
    // 首次 infer() 会等待虚拟环境就绪
    
} catch (GeaflowRuntimeException e) {
    // 虚拟环境初始化失败
    // 检查日志，修正问题后重新启动应用
    e.printStackTrace();
}

---

参考资源

• Java FileLock 文档
• AtomicBoolean vs synchronized
• Conda 虚拟环境
• 单例模式最佳实践