一、前置条件
1. 内网 Windows 主机要求
- Win10（Build 19041+）/Win11 专业版/企业版；
- 已开启「适用于 Linux 的 Windows 子系统」「虚拟机平台」（控制面板→程序→启用或关闭 Windows 功能）；
输入 OptionalFeatures，然后按回车键。这将打开'启用或关闭 Windows 功能'窗口。在这里，勾选「Hyper-V」「适用于 Linux 的 Windows 子系统」「虚拟机平台」以启用虚拟机功能。
- 管理员权限（安装 WSL、导入系统包）。
2. 联网主机准备（Win11/有网 Win10）
需提前下载 2 个核心文件（拷贝到内网主机）：
| 文件名称 | 用途 | 下载地址/方式 |
|---|---|---|
| Ubuntu 22.04 WSL 离线包 | 系统核心包 | 微软官方：https://aka.ms/wslubuntu2204（.appx 格式，≈400MB） |
| WSL2 内核更新包（Win10） | 适配 Win10 WSL2 内核 | 微软官方：https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi |
二、步骤 1：联网主机预处理离线包
- 将下载的
Ubuntu2204.appx重命名为Ubuntu2204.zip（修改后缀）； - 用 7-Zip 解压到
D:\WSL 离线包\Ubuntu2204目录（避免中文/空格路径）； - 确认解压后
D:\WSL 离线包\Ubuntu2204\tools\distro目录下有install.tar.gz文件（核心系统包）； - 将
Ubuntu2204文件夹 +wsl_update_x64.msi拷贝到内网主机（U 盘/内网传输），存放路径建议：D:\WSL 离线包\。
三、步骤 2：内网 Windows 主机离线安装
1. 安装 WSL2 内核更新包（Win10 必做，Win11 可选）
- 双击
wsl_update_x64.msi（管理员权限），按提示完成安装（无需联网）； - 安装完成后无需重启，直接进入下一步。
2. 导入 Ubuntu 22.04 到 WSL2（核心步骤）
- 以管理员身份打开 PowerShell（Win+X → 终端 (管理员)）；
- 命令说明：
Ubuntu-22.04：分发版名称（后续启动用）；D:\WSL\Ubuntu2204：WSL 系统数据存储路径；--version 2：强制使用 WSL2（必须加）；
- 执行后等待 1-2 分钟，无报错即导入成功。
- 命令说明：
执行导入命令（替换为你的实际路径）：
wsl --import Ubuntu-22.04 D:\WSL\Ubuntu2204 D:\WSL 离线包\Ubuntu2204\tools\distro\install.tar.gz --version 2
创建 WSL 数据存储目录（非 C 盘，避免占用系统空间）：
mkdir -p D:\WSL\Ubuntu2204 # 自定义路径，无中文/空格即可
3. 初始化 Ubuntu 22.04（创建普通用户）
- 此时直接进入
root用户（提示符：root@localhost:~#）；
- 设置默认登录用户（避免每次进 root）：
- 退出 Ubuntu：
exit；
- 退出 Ubuntu：
保存后重启 WSL：
wsl --shutdown
在打开的文件中添加以下内容（无文件则新建）：
[Ubuntu-22.04] default=username:dify_dev
在 PowerShell 执行：
notepad "$env:USERPROFILE\.wslconfig"
创建普通用户（适配 Dify 部署，建议用户名 dify_dev）：
# 创建用户并生成主目录
useradd -m dify_dev
# 设置密码（输入 2 次，无回显，记好密码）
passwd dify_dev
# 赋予 sudo 权限（执行管理员命令）
usermod -aG sudo dify_dev
启动导入的 Ubuntu：
wsl -d Ubuntu-22.04
4. 验证离线安装结果
- 自动以
dify_dev用户登录（提示符：dify_dev@localhost:~$）；
验证用户权限：
sudo apt update # 输入密码后无「权限拒绝」报错，说明 sudo 生效
正常输出：
NAME STATE VERSION * Ubuntu-22.04 Running 2
验证 WSL 版本：
wsl -l -v
重新启动 Ubuntu：
wsl -d Ubuntu-22.04
四、步骤 3：离线配置 Ubuntu 基础环境（适配 Dify）
内网 Ubuntu 无网，需从联网主机拷贝「系统依赖包」和「Python 依赖包」：
1. 拷贝系统依赖包（联网主机预处理）
# 联网主机的 Ubuntu 中，下载 Dify 所需编译依赖到本地
sudo apt download -d -o dir::cache=~/system-debs/ \
build-essential gcc g++ make \
libcurl4-openssl-dev libssl-dev libpq-dev \
meson ninja-build libcairo2-dev python3.11-dev
- 将
~/system-debs目录拷贝到内网 Ubuntu 的/mnt/d/WSL 离线包/；
内网 Ubuntu 中离线安装：
sudo cp /mnt/d/WSL 离线包/system-debs/* /var/cache/apt/archives/
sudo dpkg -i /var/cache/apt/archives/*.deb
2. 拷贝 Python 3.11（可选，若内网 Ubuntu 无 Python 3.11）
- 联网主机下载 Python 3.11 离线包：
sudo apt download -d python3.11 python3.11-dev； - 内网 Ubuntu 中执行
sudo dpkg -i python3.11*.deb安装。
五、关键避坑点
- 路径问题：解压/导入路径不能有中文、空格（如「WSL 离线包」→ 改为「WSL 离线包」）；
- 内核问题：Win10 若未装 WSL2 内核更新包，导入时会提示「版本不支持」，必须先装；
- 用户问题：禁止长期用 root 运行 Dify，必须创建普通用户并赋予 sudo 权限；
- 权限问题：PowerShell 必须以管理员身份运行，否则
wsl --import会报错「拒绝访问」。
六、常见异常处理
| 异常现象 | 解决方案 |
|---|---|
| 导入时提示「文件不存在」 | 检查 install.tar.gz 路径是否正确，确保后缀是 .tar.gz 而非 .tar |
| 启动 Ubuntu 提示「分发版未注册」 | 重新执行 wsl --import 命令，确认分发版名称无拼写错误 |
| 离线安装依赖包提示「依赖缺失」 | 联网主机下载时加 -o APT::Get::Missing-Since=0，下载完整依赖链 |
总结
核心要点：
- 离线安装核心是「导入
install.tar.gz系统包」，而非在线下载； - 关键步骤：解压离线包 → 导入 WSL2 → 创建普通用户 → 离线安装依赖；
- 验证标准：
wsl -l -v显示 Ubuntu-22.04 的 VERSION=2，普通用户有 sudo 权限。
后续衔接：
安装完成后，可将联网主机准备的「Dify 源码」「Python 离线依赖包」拷贝到内网 Ubuntu 的 ~/dify-offline/ 目录，继续配置 Poetry、安装 Dify 依赖，完成离线部署。
