GPEN启动失败怎么办？run.sh脚本执行问题排查指南
1. 为什么run.sh会启动失败？先搞清这三件事
GPEN图像肖像增强工具在本地部署后，最常遇到的不是效果不好，而是根本跑不起来——点开终端输入/bin/bash /root/run.sh，结果卡住、报错、没反应，或者Web界面打不开。别急着重装，90%的启动失败问题都出在三个基础环节：环境依赖没到位、权限配置不对、路径或配置写错了。
你可能已经照着教程一步步操作，但Linux系统对执行权限、路径引用、环境变量极其敏感。一个空格、一个斜杠、一次忘记加sudo，都可能导致整个脚本静默退出。这篇指南不讲高深原理，只聚焦“你现在终端里看到什么→它意味着什么→你该敲哪条命令解决”，每一步都有对应现象和可验证动作。
我们以真实用户高频报错为线索，把排查过程拆成“看日志→查权限→验环境→调配置”四步闭环。不需要你背命令，只需要对照自己终端当前画面，找到匹配项，照着做就行。
2. 第一步：看日志——从输出信息里找关键线索
启动失败时，终端不会直接告诉你“缺Python包”，而是用一串看似无关的报错掩盖真正原因。你需要学会快速抓取有效信息。执行/bin/bash /root/run.sh后，请立即观察终端最末尾3-5行输出，重点关注以下几类关键词：
2.1 “Permission denied”（权限拒绝）
/bin/bash: /root/run.sh: Permission denied说明：脚本没有执行权限，Linux默认不运行任何.sh文件，哪怕你是root用户。
立刻解决：
chmod +x /root/run.sh /bin/bash /root/run.sh注意：
chmod +x是给文件添加“可执行”属性，不是改内容。执行后无需重启终端。
2.2 “Command not found”（命令未找到）
/root/run.sh: line 5: python3: command not found说明：脚本第5行试图调用python3，但系统里压根没装，或没加到PATH环境变量。
验证方法：单独在终端输入
python3 --version- 如果返回
command not found→ 确认未安装Python3； - 如果返回版本号（如
Python 3.10.12）→ 说明PATH异常，脚本里写的python3路径和系统不一致。
分情况解决：
- 未安装Python3（Ubuntu/Debian系）：
apt update && apt install -y python3 python3-pip - PATH异常：编辑
/root/run.sh，将开头类似python3 app.py的行，改为绝对路径：/usr/bin/python3 app.py # 先用 which python3 查到真实路径再替换
2.3 “No module named”（模块缺失）
ModuleNotFoundError: No module named 'torch'说明：Python依赖库没装全。GPEN依赖torch、gradio、PIL等，缺一不可。
一键安装所有依赖（确保已进入GPEN项目目录）：
cd /root/gpen-webui # 替换为你实际的项目路径 pip3 install -r requirements.txt如果提示
pip3: command not found，先装pip：apt install -y python3-pip
2.4 “CUDA out of memory”或“CUDA unavailable”
RuntimeError: CUDA out of memory ... OSError: CUDA unavailable说明：脚本检测到GPU但显存不足，或CUDA驱动未正确安装。
快速判断：
nvidia-smi # 能显示GPU状态 → 驱动正常；显示"command not found" → 缺NVIDIA驱动应对策略：
- 若驱动正常但显存不够 → 在
run.sh中强制指定CPU模式（找到启动命令行，末尾加--device cpu）； - 若驱动缺失 → 去NVIDIA官网下载对应显卡型号的.run驱动安装。
3. 第二步：查权限——root用户也不代表万事大吉
很多用户以为用root账号执行就高枕无忧，其实Linux对/root/目录、/dev/shm共享内存、甚至/tmp临时目录都有独立权限控制。以下三类权限问题最隐蔽：
3.1/root/目录写入限制
GPEN运行时会在/root/gpen-webui/outputs/下保存图片，如果outputs目录不存在或无写权限，脚本会静默失败。
检查并修复：
ls -ld /root/gpen-webui/outputs # 正常应显示 drwxr-xr-x root root # 若显示 "Permission denied" 或 权限不含"w" → 执行： mkdir -p /root/gpen-webui/outputs chown -R root:root /root/gpen-webui/outputs chmod 755 /root/gpen-webui/outputs3.2/dev/shm空间不足（尤其Docker环境）
GPEN使用共享内存加速图像处理，若/dev/shm只有64MB（Docker默认值），会直接崩溃。
验证与扩容：
df -h /dev/shm # 查看当前大小 # 若小于2GB → 临时扩容（重启失效）： mount -o remount,size=2G /dev/shm # 永久生效（需修改Docker启动参数或宿主机fstab）3.3 WebUI端口被占用（8000端口冲突）
GPEN默认监听0.0.0.0:8000，若Nginx、Jupyter或其他服务占用了该端口，脚本会报错后退出。
查端口占用：
lsof -i :8000 # 显示占用进程PID # 或更通用的： netstat -tuln | grep :8000释放端口：
- 杀掉占用进程：
kill -9 <PID> - 或修改GPEN端口：编辑
run.sh，找到gradio launch相关行，在末尾加--server-port 8080
4. 第三步：验环境——绕过“我以为装好了”的陷阱
用户常犯的错误是：看到python3 --version有输出，就认为环境OK。但GPEN需要的是特定版本+编译选项的Python环境。以下验证必须逐项执行：
4.1 Python版本必须≥3.8且≤3.11
GPEN不兼容Python 3.12+（因PyTorch尚未适配），也不支持3.7及以下（缺少类型提示等特性）。
精准验证：
python3 --version # 必须显示 3.8.x ~ 3.11.x # 若为3.12+ → 安装Python3.11： apt install -y python3.11 python3.11-venv update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 14.2 PyTorch必须带CUDA支持（GPU用户）
仅pip install torch会安装CPU版，导致GPU加速失效，且部分模型无法加载。
GPU用户必用此命令安装（根据CUDA版本选）：
# 查CUDA版本 nvcc --version # 如显示 12.1 # 安装对应PyTorch（以CUDA 12.1为例）： pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu1214.3 Gradio版本必须≥4.0.0
旧版Gradio（<4.0）不支持GPEN的实时预览组件，会导致WebUI白屏或按钮无响应。
升级Gradio：
pip3 install --upgrade gradio # 验证： python3 -c "import gradio as gr; print(gr.__version__)" # 必须≥4.0.05. 第四步：调配置——修改run.sh的3个关键位置
run.sh是启动入口，但它的健壮性取决于3处配置是否合理。打开文件（nano /root/run.sh），按顺序检查：
5.1 工作目录是否正确（cd命令）
常见错误：脚本开头是cd /root，但GPEN实际在/root/gpen-webui。结果Python找不到app.py。
修正方法：
将cd /root改为
cd /root/gpen-webui # 确保路径与你实际存放位置一致5.2 Python解释器路径是否绝对
脚本中写python3 app.py，但某些系统python3指向/usr/local/bin/python3，而依赖库装在/usr/bin/下。
保险写法：
/usr/bin/python3 app.py --share # 用which python3确认真实路径5.3 启动参数是否完整
原生GPEN需传参启用WebUI，漏掉--share或--server-name 0.0.0.0会导致无法访问。
推荐启动行（替换脚本中最后一行）：
/usr/bin/python3 app.py --share --server-name 0.0.0.0 --server-port 8000
--share生成公网链接（调试用）；--server-name 0.0.0.0允许局域网访问；--server-port指定端口。
6. 终极验证：5分钟快速自检清单
当你完成上述步骤，仍无法启动，请按此清单逐项执行（全程5分钟）：
| 步骤 | 命令 | 预期结果 | 不通过则 |
|---|---|---|---|
| 1. 检查脚本权限 | ls -l /root/run.sh | 显示-rwxr-xr-x | 执行chmod +x /root/run.sh |
| 2. 检查Python路径 | which python3 | 返回/usr/bin/python3类似路径 | 用该路径替换run.sh中python3 |
| 3. 检查核心依赖 | python3 -c "import torch, gradio, PIL; print('OK')" | 输出OK | 运行pip3 install torch gradio pillow |
| 4. 检查端口空闲 | ss -tuln | grep :8000 | 无任何输出 | 改run.sh端口为8080 |
| 5. 手动启动测试 | /usr/bin/python3 /root/gpen-webui/app.py --server-port 8080 | 终端显示Running on public URL: http://... | 复制URL在浏览器打开 |
只要第5步成功，说明环境完全OK，此时再运行/root/run.sh必然成功。如果第5步失败，问题一定在app.py代码或模型文件损坏，需重新下载GPEN项目。
7. 预防下次失败：3个部署好习惯
启动成功不是终点，而是长期稳定使用的开始。养成以下习惯，能避免80%的后续问题：
7.1 永远用虚拟环境隔离依赖
不要在系统Python里装GPEN依赖，避免与其他项目冲突：
cd /root/gpen-webui python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # 启动时也进虚拟环境： source venv/bin/activate && python app.py7.2 把run.sh加入systemd服务（开机自启）
避免每次重启都要手动运行：
cat > /etc/systemd/system/gpen.service << 'EOF' [Unit] Description=GPEN WebUI After=network.target [Service] Type=simple User=root WorkingDirectory=/root/gpen-webui ExecStart=/usr/bin/bash /root/run.sh Restart=always RestartSec=10 [Install] WantedBy=multi-user.target EOF systemctl daemon-reload systemctl enable gpen systemctl start gpen7.3 定期清理outputs目录
outputs/文件夹持续增长会占满磁盘，导致脚本因写入失败退出：
# 添加定时任务，每天凌晨清理7天前的文件 echo "0 0 * * * find /root/gpen-webui/outputs -type f -mtime +7 -delete" | crontab -获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
