📚 课程目录第2章运行环境配置与常见问题

2、运行环境配置与常见问题归纳总结

说起环境配置，很多人觉得不就是装个软件嘛？其实这里头坑不少。我接触AutoDock以来，至少有一半的批次质控失败，根源都在环境上。不是Python版本不对，就是路径写死了，要不就是某个动态库没找到。

说白了，环境配置好比盖楼打地基。地基歪了，楼上装修得再漂亮也得塌。咱们今天就把这些坑一个个填平。

2.1 运行环境全景图

先看看整个环境长什么样。AutoDock批次质控不是单个程序在跑，而是一整套工具链在协作。我习惯把环境拆成三层：

个人小技巧：我在搭建环境时，习惯先跑一遍 python --version 和 pip list，把当前状态截图保存。出了问题至少知道「原来是什么版本」。

2.2 Python 环境——最容易翻车的地方

你想想看，一个批次质控流程里，Python 脚本要调 AutoDock 工具、解析输出文件、还要跟数据库交互。哪个环节的版本对不上，都会炸。

为什么会这样？因为 AutoDock 相关的 Python 绑定库，对版本非常敏感。

最常遇到的几个问题：

Python 3.12 以上版本：很多旧版 numpy 和 scipy 还没适配，直接报 ImportError。
pip 安装时权限不足：非 root 用户跑 pip install 到系统目录，装了一半报错。
虚拟环境交叉污染：不同项目的依赖全装在一个环境里，版本冲突时根本查不出来。

警告：我强烈建议使用虚拟环境。你可以在项目目录下这样操作：

python -m venv autodock_env
source autodock_env/bin/activate  # Linux/macOS
# 或
autodock_env\Scripts\activate     # Windows

pip install numpy==1.23.5 scipy==1.9.3 pandas matplotlib

这样做的好处是，哪天环境搞烂了，删掉重来就行，不影响系统Python。

2.3 路径配置——别让程序找不到家

我记得有一次，同事的脚本跑了一整天质控，最后一刻报错说找不到输出文件。排查下来，原来是脚本里写死了 /home/user/2023/project，换了服务器就歇菜。

路径问题的常见表现：

问题描述	典型错误日志	根本原因
找不到分子文件	`FileNotFoundError: ./ligands/ligand_001.pdbqt`	相对路径基准不对
AutoDock 可执行文件缺失	`OSError: autodock_gpu_128wi not found`	PATH 未包含安装目录
临时文件夹权限不足	`PermissionError: /tmp/autodock_xxx`	/tmp 空间满或挂载方式限制
日志输出路径不存在	`IOError: /results/logs/ cannot be created`	未自动创建目录层级

我的做法是这样的：

在配置文件中，所有路径都用相对目录，加上一个 BASE_DIR 变量。比如：

BASE_DIR = Path(__file__).resolve().parent
LIGANDS_DIR = BASE_DIR / "data" / "ligands"
RESULTS_DIR = BASE_DIR / "output" / "results"
AUTODOCK_BIN = "/usr/local/bin/autodock_gpu_128wi"

# 启动时自动检查路径存在性
for d in [LIGANDS_DIR, RESULTS_DIR]:
    d.mkdir(parents=True, exist_ok=True)

这样不管项目移到哪里，只要 BASE_DIR 是对的，其他路径自动跟着变。

2.4 第三方工具依赖——不可或缺的零件

AutoDock 本身是一回事，但批次质控里还要调用好几个辅助工具。这些工具装不好，质控流程就直接断掉了。

我在项目中遇到过好几次「漏装 ADT」的案例。ADT 是 AutoDock Tools 的命令行版本，负责处理受体和配体文件。没它，连 .pdbqt 文件都生成不了。

关键工具清单：

ADFR (AutoDock-FR)：用于柔性对接计算的辅助套件。版本必须与 AutoDock-GPU 匹配。
AutoDock Tools (ADT)：提供 prepare_receptor 和 prepare_ligand 等脚本。
OpenBabel：做分子格式转换，比如 .sdf → .pdbqt。
MGLTools：部分脚本依赖这个库，尤其是 prepare_gpf.py 和 prepare_dpf.py。

安装建议：

我曾经因为版本不一致吃过亏。现在我都用 conda 来管理这些工具，避免手动安装带来的路径混乱。

conda create -n autodock_env python=3.9
conda activate autodock_env
conda install -c conda-forge openbabel
conda install -c insilichem adfr
# ADT 需要单独下载安装包

嗯，这里要注意，conda 源的 adfr 可能不是最新版，建议到官网核实。

2.5 批次质控环境的标准化检查清单

每次开始新的批次质控前，我都按这个清单过一遍。说白了一个顺序检查的流程，省得半路出问题再回头找原因。

确认 Python 版本：3.8 ≤ version ≤ 3.11，建议用 3.9 或 3.10。
激活虚拟环境：确认 which python 指向的是虚拟环境内的解释器。
检查核心依赖：numpy、scipy、pandas、matplotlib 都装好了，版本在兼容范围内。
确认 AutoDock-GPU 可执行文件：跑一下 autodock_gpu_128wi --help 看是否正常。
测试 ADT 脚本：prepare_ligand.py -l test.pdb -o test.pdbqt
验证 OpenBabel：obabel test.sdf -O test.pdbqt
检查路径配置：配置文件中的 BASE_DIR 正确，所有子目录已创建。
权限确认：输出目录可写，临时文件夹有足够空间。

一个血的教训：我曾经在集群上跑批次质控，所有节点都配置好了，结果就一个节点没装 ADT，导致那批结果的 30% 都是空文件。查了一天才发现，原来安装脚本漏了那个节点。所以我后来都在主控脚本里加上环境检查，发现问题直接退出，不留隐患。

#!/bin/bash
# 环境预检脚本片段
if ! command -v autodock_gpu_128wi &> /dev/null; then
    echo "ERROR: AutoDock-GPU not found in PATH" >&2
    exit 1
fi
python -c "import numpy; print(numpy.__version__)" || exit 1

2.6 环境配置故障的快速诊断表

如果已经出问题了，别慌。按这个表对号入座，基本能迅速定位。

错误表现	可能原因	快速验证命令	常见修复
`ImportError: No module named 'numpy'`	虚拟环境未激活或未安装	`python -c "import numpy"`	`pip install numpy`
`FileNotFoundError: prepare_ligand.py`	ADT 未添加到 PATH	`which prepare_ligand.py`	将 ADT 的 `bin/` 目录加入 `~/.bashrc`
`Segmentation fault (core dumped)`	CUDA 版本不匹配或 GPU 驱动太旧	`nvidia-smi`	更新驱动或重装 CUDA 工具包
`Permission denied writing to /tmp`	临时目录空间满或权限受限	`df -h /tmp`	更换临时目录：`export TMPDIR=/your/scratch`
`ParserError: malformed PDBQT`	文件转换时 OpenBabel 版本不兼容	`obabel -V`	升级或降级 OpenBabel 至 3.1.x

说白了，环境配置没有捷径，但可以靠清单和自动化脚本来减少出错。我个人的习惯是，每次新建项目都跑一遍环境安装脚本，而不是手动敲命令。这样既重复性好，也方便其他同事复用。

嗯，环境这块先聊到这儿。记住一点：宁可花 10 分钟做环境预检，也别花一整天去排查因为环境导致的问题。