Upscayl：免费开源跨平台 AI 图像超分工具，离线放大老照片与低清图｜部署与使用全指南

本文基于 Upscayl v2.15.0（2024-12-25 发布）撰写。Upscayl 目前 GitHub star 数约 5.1 万，由 Nayam Amarshe 与 TGS963 维护，是最受欢迎的开源图像超分辨率（Super-Resolution）桌面应用之一。

Upscayl 是一款免费开源的跨平台 AI 图像放大工具：它基于 Real-ESRGAN 算法与 NCNN Vulkan 推理架构，在本地 GPU 上把低分辨率、像素化的图片放大 2x/3x/4x，同时"脑补"出细节，让老照片、游戏截图、二次元图恢复清晰。它提供 Windows/macOS/Linux 桌面 GUI 与命令行工具 upscayl-ncnn，全程离线运行，不上传任何图片。

一、项目介绍与适用场景

1.1 Upscayl 是什么

Upscayl = 桌面 GUI（Electron 应用）+ NCNN Vulkan 推理后端（upscayl-ncnn，独立开源、AGPLv3）+ 多个 Real-ESRGAN 系模型。用户选择图片（或整个文件夹），挑选模型与倍率，点一下 "UPSCAYL" 即可本地完成放大，输出比原图大数倍且更清晰的新图片。

它不是"去模糊"工具：AI 依靠猜测重建细节，适合低分辨率、像素化、压缩失真的图；对完全失焦的模糊照片无能为力。

1.2 适用人群

1.3 不适合的场景

• 无 Vulkan 兼容 GPU 的机器：NCNN Vulkan 必须要 GPU，绝大多数核显（iGPU）与纯 CPU 无法运行（官方 FAQ 明确说明，部分 Windows/Linux 机器可试 #390 issue 中的 workaround）；

• 需要在线、批量 API 化的云服务场景——官方未提供云端 API；

• 需要修复严重失焦照片——请用专门的去模糊/修图工具。

二、核心功能逐条拆解

1. 多种放大倍率：支持 2x、3x、4x 放大，输入输出长宽比保持不变。

2. 内置多模型：自带 Upscayl Standard、Upscayl Lite、Ultrasharp、Ultramix Balanced、Remacri、High Fidelity（HFA2k）等模型，分别适配普通照片、大图、二次元、艺术图等场景。

3. Double Upscayl：一次处理做两遍放大（等效更高倍率），适合极限放大需求。

4. Batch Upscayl（批量）：选择一个文件夹批量超分，输出到指定目录，适合素材库整库处理。

5. TTA 模式：启用后对图像做多次变换再融合，提升细节但耗时约 8 倍。

6. 自定义模型：支持指定本地自定义模型目录，导入社区模型（官方提供 https://github.com/upscayl/custom-models 模型合集）。

7. 缩放/输出控制：可设置输出宽度（custom width），输出格式可选 PNG/JPG 等。

8. GPU 选择：多显卡机器可指定使用哪块 GPU（GPU ID）。

9. 全离线：所有推理在本地 GPU 完成，无账号、无上传、无水印、无次数限制。

10. 跨平台一致体验：Windows exe、macOS dmg、Linux AppImage/deb/Flatpak/Snap/AUR 全覆盖。

11. CLI 工具 upscayl-ncnn：独立开源的后端命令行工具，可脚本化、可嵌入流水线。

12. 主题与界面：支持深色/浅色主题（界面内切换），界面简洁三步式操作。

三、全套官方链接

四、硬件与环境前置要求

重要：官方 FAQ 明确说明"大多数核显（iGPU）和 CPU 无法运行"，但可以试一试。详细显卡兼容情况见官方 Compatibility List Wiki。

五、多平台部署步骤

5.1 Windows

1. 打开 https://github.com/upscayl/upscayl/releases/latest ；

2. 下载 upscayl-x.x.x-win.exe；

3. 双击运行。如出现 SmartScreen 警告，点击"更多信息"→"仍要运行"（或在未验证发布者弹窗点"是"）；

4. 按安装向导完成安装，启动 Upscayl。

5.2 macOS（12 及以上）

# 方式一：Homebrew（官方推荐命令）
brew install --cask upscayl

方式二：手动安装 dmg：

1. 从 Releases 或官网下载 upscayl-x.x.x-mac.dmg；

2. 双击 dmg，把 Upscayl 图标拖入 Applications；

3. 打开 Finder → 应用程序，右键 Upscayl → "打开"，在弹窗中再点"打开"（绕过 Gatekeeper 首次校验）。

5.3 Linux

AppImage（便携，任意发行版）：

chmod +x upscayl-x.x.x-linux.AppImage   # 赋予执行权限
./upscayl-x.x.x-linux.AppImage          # 直接运行

DEB（Debian/Ubuntu 系）：

sudo dpkg -i upscayl-x.x.x-linux.deb
sudo apt-get install -f   # 补齐依赖（如需要）

Flatpak：

flatpak install flathub org.upscayl.Upscayl
flatpak run org.upscayl.Upscayl

Snap：

sudo snap install upscayl

Arch Linux（AUR）：

yay -S upscayl-bin

官方 README 说明：大多数发行版的应用商店中也能直接搜到 Upscayl（Flatpak/Snap 源）。

5.4 源码运行/构建（开发模式）

官方开发流程（需 Node.js，推荐用 Volta 安装）：

git clone https://github.com/upscayl/upscayl
cd upscayl
npm install        # 安装依赖
npm run start      # 启动开发服务器，日志输出到终端

npm run dist       # 打包安装包

5.5 CLI 后端 upscayl-ncnn

GUI 之外的命令行工具是独立仓库 upscayl-ncnn（AGPLv3），从其 GitHub Releases 下载对应平台二进制，或按官方 README 源码编译：

# Linux 编译依赖（官方 install_deps.sh 自动安装）
./install_deps.sh   # cmake、gcc-9、libomp-dev、libvulkan-dev、glslang-tools
git clone --recursive https://github.com/upscayl/upscayl-ncnn.git
cd upscayl-ncnn
export CC="gcc-9" CXX="g++-9"
mkdir build && cd build
cmake ../src
cmake --build . -j 2

macOS 需 brew install libomp cmake 并按官方 README 使用带 MoltenVK 参数的 cmake 命令编译。

5.6 Docker

官方未提供 Docker 镜像或容器化部署方式。 原因是 Upscayl 依赖 Vulkan GPU 直通与桌面 GUI，官方以桌面应用形态分发。替代方案：

• 无界面批量处理请使用 upscayl-ncnn CLI：在宿主机（有 Vulkan GPU）用脚本循环调用即可达到"容器化批量"的效果；

• 如确需容器，可自行基于已启用 --device /dev/dri（GPU 直通）的镜像封装 upscayl-ncnn 二进制，但属于非官方方案，需自行维护。

六、配置文件全部参数解释

Upscayl 是桌面应用，没有传统配置文件；设置通过应用内 Settings 页保存（持久化在系统用户配置目录，如 Linux ~/.config/Upscayl、Windows %APPDATA%\Upscayl、macOS ~/Library/Application Support/Upscayl）。主要设置项：

自定义模型目录使用要点：

• 模型文件为成对的 模型名.param 与 模型名.bin，放入自定义目录后重启应用即可在下拉框中看到；

• 官方社区模型仓库：https://github.com/upscayl/custom-models ；

• 自行转换模型见官方 Wiki 的 Model Conversion 教程。

upscayl-ncnn CLI 的完整参数（模型路径、缩放倍数、输入输出路径等）以仓库 README 与 --help 输出为准，本文不虚构具体旗标名。

七、启动、后台常驻、开机自启、改端口

Upscayl 是桌面 GUI 应用，不是常驻服务，因此：

• 启动：安装后从开始菜单/启动台/应用列表点击图标运行；AppImage 用户直接双击运行。

• 后台常驻：无后台服务组件，关闭窗口即退出，无需也不应常驻。

• 开机自启：官方未提供内置自启选项，可按需在系统层面设置：

• Windows：Win+R 输入 shell:startup，把 Upscayl 快捷方式放入启动文件夹；

• macOS：系统设置 → 通用 → 登录项，添加 Upscayl；

• Linux GNOME：gnome-tweaks → 开机启动程序；或创建 ~/.config/autostart/*.desktop 文件。

• 改端口：不适用——Upscayl 不监听任何网络端口，完全本地离线，无反向代理场景。

如需无人值守/定时批量超分，正确做法是用 upscayl-ncnn CLI 配合 cron/计划任务，而非让 GUI 常驻：

# Linux crontab 示例：每天 3 点处理 ~/to_upscale 下所有图片（命令参数以 upscayl-ncnn README 为准）
0 3 * * * cd ~/pictures && for f in to_upscale/*; do upscayl-ncnn -i "$f" -o done/; done

八、功能实操教程

8.1 单张图片放大（基础流程）

1. 启动 Upscayl，点击 Select Image（或把图片拖入窗口）；

2. 在右侧 Select AI Model 下拉选择模型：普通照片选 Upscayl Standard，动漫/插画选 High Fidelity，追求锐利选 Ultrasharp；

3. 选择倍率（如 4x）；

4. 点击大按钮 UPSCAYL，等待进度条完成；

5. 在输出目录查看 xxx_upscayl_4x.png 结果。

8.2 批量放大整个文件夹（Batch Upscayl）

1. 切换到 Batch Upscayl 页签；

2. 选择输入文件夹与输出文件夹；

3. 选模型与倍率，点击 UPSCAYL，等待全部完成；

4. 注意：若中途取消，可能存在尚未压缩/缩放完成的文件——官方 FAQ 说明模型不支持的动作会等全部超分结束后统一后处理，请等待进程结束。

8.3 启用 TTA 提升细节

Settings 中打开 TTA Mode，重新执行 8.1 的流程。效果更细腻，但处理时间约增至 8 倍，适合少量珍贵照片。

8.4 使用自定义/社区模型

1. 从 https://github.com/upscayl/custom-models 下载模型（.param + .bin）；

2. Settings → Add Custom Models 指定模型文件夹；

3. 回到主界面，模型下拉框中选择新导入的模型，正常执行超分。

8.5 Double Upscayl 极限放大

在倍率处选择 Double Upscayl，等效执行两次超分（例如 4x+4x），适合把很小的图片放到印刷尺寸。注意显存占用与耗时都会显著增加，超大图建议先 4x 一次，再对输出图二次处理。

8.6 多显卡指定 GPU

Settings 中找到 GPU ID 设置，填入要使用的 GPU 编号（从 0 开始）。官方 Wiki 说明：Windows 上若系统未设为性能模式，电源策略可能覆盖该选择。

8.7 CLI 脚本化批量处理

# 下载 upscayl-ncnn 对应平台 Release 后（以 README 用法为准）：
upscayl-ncnn -i input.jpg -o output.png -m models/ -s 4
# 参数含义：-i 输入、-o 输出、-m 模型目录、-s 缩放倍数；完整参数以仓库 README 为准

九、全套报错故障排查

十、升级、回滚与卸载

10.1 版本查看与升级

• 应用内 Settings 页可查看当前版本；

• 官网/Releases 查看 最新版本号。

# Windows：下载新版 exe 覆盖安装
# macOS：
brew upgrade --cask upscayl        # Homebrew 方式升级
# 或重新下载 dmg 覆盖到 Applications
# Linux：
sudo dpkg -i upscayl-新版-linux.deb          # deb 覆盖安装
flatpak update org.upscayl.Upscayl           # Flatpak 升级
sudo snap refresh upscayl                    # Snap 升级
yay -S upscayl-bin                           # AUR 升级

10.2 回滚到指定版本

1. 打开 https://github.com/upscayl/upscayl/releases ，找到目标历史版本（如 v2.14.0）；

2. 下载该版本对应平台的安装包；

3. 覆盖安装即可（配置会保留；如遇配置不兼容可先备份并删除用户配置目录）。

10.3 完整卸载清理清单

# Windows
# 1) 设置 → 应用 → 卸载 Upscayl
# 2) 清理残留配置
Remove-Item "$env:APPDATA\Upscayl" -Recurse -Force

# macOS
rm -rf /Applications/Upscayl.app
rm -rf ~/Library/Application\ Support/Upscayl

# Linux (deb)
sudo apt remove --purge upscayl
rm -rf ~/.config/Upscayl
# Flatpak / Snap / AUR 分别用：
flatpak uninstall org.upscayl.Upscayl
sudo snap remove upscayl
sudo pacman -Rns upscayl-bin

十一、商用许可与合规风险提示

• License：Upscayl 主仓库与 upscayl-ncnn 后端均为 AGPL-3.0。个人使用完全免费；但如果你把基于它的代码嵌入自己的网络服务并对用户提供，必须开源你的修改（AGPL 传染性），这是与 MIT/Apache 类项目的关键区别。

• 模型版权：内置的 Remacri、Ultrasharp、Ultramix、HFA2k 等模型来自第三方作者（见官方 Credits），各自许可不同，商用分发前逐一确认。

• 输出图版权：对他人作品进行超分并发布可能涉及著作权问题，请确保你对输入图片拥有相应权利。

• 无费用与额度：本地运行，无 API 费用、无次数限制、无水印。

• 数据隐私：图片不出本机、无遥测账号体系，隐私风险低。

• 生产风险：GUI 面向个人桌面场景，批量自动化请走 upscayl-ncnn CLI；不要基于 GUI 做生产流水线。

附录：命令速查

# 安装
brew install --cask upscayl                    # macOS
flatpak install flathub org.upscayl.Upscayl    # Linux Flatpak
sudo snap install upscayl                      # Linux Snap
yay -S upscayl-bin                             # Arch AUR

# Linux AppImage 便携运行
chmod +x upscayl-*.AppImage && ./upscayl-*.AppImage

# 源码开发
git clone https://github.com/upscayl/upscayl && cd upscayl
npm install && npm run start                   # 开发运行
npm run dist                                   # 打包

# CLI（upscayl-ncnn，参数以官方 README 为准）
upscayl-ncnn -i in.jpg -o out.png -m models/ -s 4

# 排错
xattr -d com.apple.quarantine /Applications/Upscayl.app   # macOS 门禁
sudo apt install libfuse2                                  # AppImage 依赖
# GPU ID / TTA / 自定义模型：应用内 Settings 页设置