GPEN部署教程（Windows WSL2）：Linux镜像在Windows环境运行
1. 为什么要在WSL2里跑GPEN？
你可能已经试过直接在Windows上装Python环境跑AI模型——依赖冲突、CUDA版本打架、PyTorch编译报错……一连串红色报错让人头皮发麻。而GPEN这类基于PyTorch+OpenCV+FFmpeg的视觉增强模型，对Linux环境的兼容性远高于原生Windows。好消息是：现在不用双系统、不用虚拟机，只要打开Windows自带的WSL2，就能原生运行专为Linux优化的GPEN镜像。
这不是“模拟”，而是真·Linux内核；不是“兼容层”，而是完整POSIX环境。你获得的是和服务器一致的执行体验：GPU加速可用、文件系统直通、端口映射稳定。更重要的是——整个过程不需要你手动编译一个库，也不用查三小时“ModuleNotFoundError”。
本教程将带你从零开始，在Windows 11（或Windows 10 21H2+）中启用WSL2，拉取预配置好的GPEN镜像，一键启动Web界面，并完成首张老照片修复。全程无需命令行高阶知识，所有操作都附带可复制粘贴的命令和截图级说明。
2. 前置准备：让WSL2真正准备好
2.1 启用WSL2功能（仅需一次）
请以管理员身份打开PowerShell（右键开始菜单 → “Windows PowerShell（管理员）”），依次执行以下三条命令：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完毕后，必须重启电脑。这是硬性要求，跳过会导致后续失败。
2.2 安装WSL2内核与默认发行版
重启后，访问 Microsoft WSL官方安装页（直接点击即可下载），运行下载的wsl_update_x64.msi安装包。完成后，在PowerShell中运行：
wsl --update wsl --set-default-version 2接着安装Ubuntu 22.04（推荐，兼容性最佳）：
wsl --install -d Ubuntu-22.04首次启动会引导你设置用户名和密码（记牢！后面要用）。完成后，输入wsl -l -v应看到类似输出：
NAME STATE VERSION * Ubuntu-22.04 Running 2表示WSL2已就绪。
2.3 验证GPU支持（可选但强烈推荐）
如果你的Windows主机配有NVIDIA显卡（GTX 10系及以上），请额外安装 NVIDIA CUDA on WSL 驱动。只需两步：
- 在Windows中安装最新Game Ready驱动（官网下载）
- 在WSL终端中运行：
curl -s -L https://nvidia.github.io/libnvidia-container/wsl/ubuntu22.04/nvidia-container-toolkit-config.sh | sudo bash
验证是否生效：
nvidia-smi若能看到GPU型号和显存占用，说明CUDA已直通成功——GPEN修复速度将提升3–5倍。
3. 一键拉取并运行GPEN镜像
3.1 安装Docker Desktop for WSL2
GPEN镜像基于Docker容器封装，因此需先安装Docker。注意：必须使用Docker Desktop（非Docker Engine），因其专为WSL2深度集成。
- 下载地址：https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe
- 安装时勾选“Use the WSL 2 based engine”和“Enable integration with my default WSL distro”
- 安装完成后，启动Docker Desktop，等待右下角鲸鱼图标变为绿色
小提示：Docker Desktop首次启动会自动配置WSL2集成，无需手动
dockerd。若遇到“Docker daemon not running”，请右键任务栏图标 → Restart。
3.2 拉取GPEN镜像并启动服务
打开Ubuntu终端（可在开始菜单搜索“Ubuntu”），执行以下命令：
# 拉取已预装GPEN的轻量镜像（约2.1GB，国内源加速） sudo docker pull registry.cn-hangzhou.aliyuncs.com/modelscope-repo/gpen:latest # 启动容器，映射端口8080，挂载当前目录为图片上传根目录 sudo docker run -it --gpus all -p 8080:8080 \ -v $(pwd)/images:/app/images \ --name gpen-server \ registry.cn-hangzhou.aliyuncs.com/modelscope-repo/gpen:latest关键参数说明：
--gpus all：启用全部GPU（若未装NVIDIA驱动则自动降级为CPU模式，仍可运行）-p 8080:8080：将容器内Web服务端口映射到Windows本地8080-v $(pwd)/images:/app/images：把当前目录下的images文件夹作为上传区，修复后的图也保存在此
执行后你会看到日志滚动输出，最后停在：
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)服务已就绪。
4. 使用GPEN Web界面：三步完成人脸修复
4.1 访问界面与上传图片
打开Windows浏览器，访问：
http://localhost:8080
你会看到简洁的GPEN操作界面：
- 左侧为“上传区域”，支持拖拽或点击选择
- 右侧为实时预览区，显示原始图与修复后对比
注意：上传前请确保已在WSL终端中创建了images文件夹：
mkdir -p ~/images cd ~ # 然后重新运行docker run命令（加上 -v $(pwd)/images:/app/images）上传一张模糊人像（手机自拍、扫描老照片、AI生成废片均可），格式支持 JPG/PNG/BMP。
4.2 一键修复与效果观察
点击 ** 一键变高清** 按钮后，界面会出现进度条。根据图片尺寸和硬件不同：
- CPU模式：约8–15秒（1080p人像）
- GPU模式：约2–5秒（同尺寸）
修复完成后，右侧自动显示左右分屏对比：
- 左：原始模糊图（带红框标出检测到的人脸区域）
- 右：修复后高清图（细节锐利，皮肤纹理自然，瞳孔清晰）
你可以用鼠标滚轮缩放查看局部——重点观察睫毛根部、鼻翼阴影、嘴唇边缘等易失真区域。你会发现，GPEN并非简单插值放大，而是通过生成先验“重建”缺失结构。
4.3 保存与批量处理
修复图默认保存在WSL的~/images目录中，文件名格式为input_filename_restored.png。在Windows中，你可直接访问该路径：
\\wsl$\Ubuntu-22.04\home\你的用户名\images\（将“你的用户名”替换为你WSL中设置的名称）
右键图片 → “另存为”即可保存到Windows任意位置。
如需批量处理多张照片，只需将所有待修复图放入~/images文件夹，然后在Web界面中逐张上传——无队列限制，无并发瓶颈。
5. 效果调优与常见问题实战指南
5.1 什么图效果最好？什么图要谨慎？
| 场景类型 | 效果表现 | 实操建议 |
|---|---|---|
| 2000年代数码相机直出（如索尼DSC系列） | 极佳。低噪点+中等模糊，AI能精准补全五官结构 | 直接上传，无需预处理 |
| 扫描黑白老照片（带折痕、泛黄） | 良好。肤色还原稍偏暖，但轮廓清晰度跃升 | 上传前用手机APP简单去污渍，避免折痕干扰人脸定位 |
| Midjourney V6生成废片（眼神歪斜、牙齿错位） | ☆ 优秀。能修正几何畸变，恢复自然神态 | 优先选择“Face Close-up”构图，避开全身照 |
| 严重运动模糊（如夜景手持拍摄） | ☆ 较弱。动态拖影超出GAN先验范围 | 建议先用传统算法（如DeblurGAN）粗修，再交GPEN精修 |
| 多人合影（小脸+远距离） | 中等。主脸效果好，侧脸/后排人脸可能细节不足 | 使用截图工具单独裁出每张人脸，分别修复 |
5.2 修复后皮肤太光滑？这是正常现象
GPEN的生成先验包含“健康肌肤”统计分布，因此修复结果普遍比原图更细腻。这不是缺陷，而是设计使然——它在“真实感”与“观感舒适度”间做了工程权衡。
如需保留更多原始肤质（如皱纹、痣、雀斑），可在代码层微调（进阶）：
# 进入容器修改推理参数（需基础Python知识） docker exec -it gpen-server bash nano /app/app.py # 找到 'enhance_face' 函数，调整 'skin_smoothness=0.3'（默认0.6）但对绝大多数用户，当前默认值已是最优平衡点。
5.3 常见报错与秒解方案
报错：
CUDA out of memory
→ 解决：在docker run命令中添加--gpus device=0（指定单卡），或改用CPU模式（删掉--gpus all参数）报错：
Connection refused访问localhost:8080失败
→ 解决：检查Docker Desktop是否运行；执行sudo docker ps确认容器状态为Up；若已退出，运行sudo docker start gpen-server上传后无反应，界面卡在“Processing…”
→ 解决：检查WSL中~/images权限，执行chmod -R 755 ~/images；确认图片小于20MB（超大会触发内存保护）
6. 总结：你刚刚掌握了一项实用AI技能
你已完成一项看似复杂、实则门槛极低的AI部署实践：
在Windows上启用了专业级Linux子系统
用一条命令拉取并运行了阿里达摩院研发的GPEN模型
通过浏览器完成了老照片修复、AI废片拯救、数字美容等真实任务
掌握了效果判断标准与常见问题应对方法
这不再是“调API”或“点按钮”的黑盒体验，而是你亲手搭建的、可控可调的AI工作流。下一步，你可以尝试：
- 将修复流程封装为Python脚本，实现“拖入文件夹→自动修复→导出”
- 把GPEN集成进Photoshop动作，一键批处理图库
- 用Gradio重写前端，增加风格化选项（复古胶片/水墨风/赛博朋克）
技术的价值，不在于它多酷炫，而在于它能否安静地解决你手边那个具体的问题——比如，让奶奶年轻时的照片重新清晰起来。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
