====== PWstudio cpu 版 windows11_wsl2 安装指南 ======

适用系统：window11\\

<wrap important>
在开始之前，强烈建议先看一遍 [[pwstudio:readme|PWstudio 安装前必看]]，建立一个整体概念。
</wrap>

----

<wrap em>采用 wslc 起 PWstudio cpu 容器</wrap>

<wrap tip>
下面这部分是通过 wslc（WSL 自带的容器工具）来启动 PWstudio cpu 容器的方式。
</wrap>

===== 1. wsl 安装与更新 =====

温馨提示：
通过以下命令均在 **PowerShell** 中执行

**若是在本机（自己的电脑）进行安装：**直接右击开始键，选择以管理员身份打开 PowerShell；或者在 "开始" 菜单搜索 ''PowerShell'', 右键选择 "以管理员身份运行"，打开终端操作界面

**若是在安有windows系统的服务器上进行安装：**则需要先按照以下步骤连接到远程服务器上，具体操作步骤如下

>（1）打开远程桌面连接工具
>• 按下键盘上的 Win + R 组合键，打开“运行”对话框。
>• 在弹出的对话框输入 mstsc，然后点击“确定”或按回车键。
>
>（2）输入服务器信息
>• 在弹出的“远程桌面连接”窗口中，找到 “计算机” 一栏。
>• 输入目标服务器的 IP 地址：例如 192.168.97.23。 
>• 点击左下角的 “显示选项” ，展开更多设置。在 “用户名” 一栏输入 对应的用户名，例如 lxkt。 
>• 点击 “连接”。
>
>（3）输入登录凭据
>• 系统会弹出“Windows 安全中心”窗口，要求输入用户名的密码作为凭据。
>• 在 “用户名” 字段，输入 lxkt（如果上一步已填，此处会自动显示）。
>• 在 “密码” 字段，输入密码，例如 lxkt。
>• 确认信息无误后，点击 “确定”。
>
>（4）确认安全证书
>• 如果是第一次连接此服务器，系统可能会提示“无法验证此远程计算机的身份，是否仍要连接”。
>• 这是正常的安全提醒，检查 IP 地址无误后，点击 “是” 即可继续连接
>
>连接成功后，即可登录到远程服务器的windows界面，再对远程服务器直接右击开始键，选择以管理员身份打开 PowerShell；或者在 "开始" 菜单搜索 ''PowerShell'', 右键选择 "以管理员身份运行"，打开终端操作界面。
 
1. 若系统没有wsl，需要先运行以下命令进行安装
<code powershell>
wsl --install
</code>

2. 更新到 WSL 预发布版：运行以下命令

<code powershell>
wsl --update --pre-release
</code>

3. 重启 WSL 服务: 更新完成后, 运行此命令让更改生效

<code powershell>
wsl --shutdown
</code>

4. 验证 wslc 是否可用: 关闭并重新打开你的终端(PowerShell 或 Windows 终端)

<code powershell>
wslc --version
</code>

如果看到类似版本号的输出（比如 2.9.3.0），说明可以继续下一步了。

===== 2 宿主机安装 server.py 服务 =====

安装说明：点击链接, [[pwstudio:serverwin|在 Windows 下安装 server.py 服务]] 跟着文档安装好证书服务, 再进行下一步。

===== 3. 导入镜像 =====

<code powershell>
wslc pull ccr.ccs.tencentyun.com/lxkt/qflowcpu:latest
</code>

这一步是下载 PWstudio cpu 版镜像，体积较大，根据网速可能需要几分钟到十几分钟，请耐心等待。

>**注：若在拉取镜像时报错**“由于未安装所需的特性，无法启动操作 错误代码:HCS_E_SERVICE_NOT_AVAILABLE”时，
>这个错误 HCS_E_SERVICE_NOT_AVAILABLE 的核心原因是 WSL2 所需的虚拟化服务 (vmcompute) 未能正常运行。wslc 依赖于 WSL2 的虚拟化功能来创建和管理容器，因此当底层服务不可用时，wslc pull 命令就会失败。
>
>**解决方案：修改 WSL2 网络模式为镜像模式（Mirrored）**
>这会令 WSL2 与 Windows 共享同一网络栈，从而解决 TLS 问题。
>
>（1）在文件资源管理器地址栏输入 %UserProfile%，进入用户目录。
>（2）新建或编辑 .wslconfig 文件（注意文件名有英文点号）。
>（3）在上述文件里粘贴以下内容：
><code powershell>
ini
[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=false
</code>
>（4）保存文件，然后关闭所有 WSL 相关的终端和程序。
>（5）在 PowerShell 中执行 wsl --shutdown 重启 WSL。
>（6）重新打开终端，再次尝试 wslc pull ccr.ccs.tencentyun.com/Lxkt/qflowcpu:Latest。
>
>如果成功，则问题解决。
===== 4. 启动容器 =====

在启动容器之前，需要先在宿主机的powershell 终端执行 ''ipconfig'' 查看对应 WSL 虚拟网卡的 ip（取以太网适配器 vEthernet (WSL (Hyper-V firewall))栏下的 IPv4 地址）。

<note tip>注意：若在宿主机执行完ipconfig命令之后，若没有查到WSL 虚拟网卡的 ip，则需要安装ubuntu，可以通过以下命令进行安装

<code bash>
wsl --install -d Ubuntu
</code></note>

以下起容器的第一行命令中的172.20.192.1是通过ipconfig 查到的 WSL 虚拟网卡的 ip

在 powershell 中:

<code powershell>
wslc run -d --name qflowcpu -e SERVERIP=172.20.192.1 `
  -v $env:TEMP\pwmat:/var/tmp/pwmat_host_secret:ro `
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --shm-size=128G `
  -e SELINUX=disabled -p 80:80 -p 81:81 -p 2297:2297 -p 5010:5010 `
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowcpu:latest
</code>

在 cmd 中:

<code powershell>
wslc run -d --name qflowcpu -e SERVERIP=172.20.192.1 ^
  -v %TEMP%\pwmat:/var/tmp/pwmat_host_secret:ro ^
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --shm-size=128G ^
  -e SELINUX=disabled -p 80:80 -p 81:81 -p 2297:2297 -p 5010:5010 ^
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowcpu:latest
</code>

<WRAP center round info 10%>
注：在 powershell 或 cmd 下启动容器时，必须要把ip修改成 ipconfig 查看对应 WSL 虚拟网卡的 ip, 否则提交作业会报错。 修改指定 ip 启动容器的命令也可参考该页面的[[pwstudio:qa:q106|第二条]]

-e SERVERIP=172.20.192.1 `中的172.20.192.1需要改成通过ipconfig 查到的 WSL 虚拟网卡的 ip

或设置镜像网络
</WRAP>

以上两段powershell 或 cmd 二选一，根据你习惯用的终端类型执行即可，不要两个都执行。若执行后没有报错，会输出一长串字符（容器 ID），说明容器已经启动。

<WRAP center round todo 10%>
windows系统下：

通过如下命令查看正在运行的容器：

<code bash>
wslc ps
</code>

通过如下命令查看所有容器(启动的 或 停止的)：

<code bash>
wslc ps -a
</code>

执行后能看到一个表格，如果表格里有一行 ''NAMES'' 列显示 ''qflowcpu''，''STATUS'' 列显示 ''Up ...''（比如 "Up 5 minutes"），就说明容器正在正常运行。

启动一个已经存在、但当前处于停止状态的容器

<code bash>
wslc start qflowcpu
</code>

启动容器前，如有同名容器占用，需停止和删除旧容器：

<code bash>
wslc stop qflowcpu
</code>

删除同类型旧容器：
<code bash>
wslc rm qflowcpu
</code>

停止、删除之后，再重新执行上面的 ''wslc run'' 命令即可。

<WRAP center round alert 60%>
  - 删除容器, 容器里的数据也会被删除❗
  - 容器里的 qflow 工作流不能导出
</WRAP>

</WRAP>


===== 5. 对容器登录、上传下载 =====

  * 通过 SSH 客户端登录、上传、下载<wrap notice>推荐</wrap>

^ 地址        ^ 端口号  ^ 用户名  ^ 密码             ^
| [宿主机ip]  | 2297    | pwmat   | PWmat2022        |
| [宿主机ip]  | 2297    | root    | PWmatSimplyBest  |

上表 ''[宿主机ip]'' 替换成127.0.0.1，其它按表格填写即可，不需要修改。


<wrap tip>
以上安装，若是通过本机连接到远程服务器的windows版进行安装，这里需要在远程服务器上，用管理员的身份登录到powershell中，通过ssh 用户名@127.0.0.1 -p 2297直接登录到容器里（本机通过127.0.0.1是无法访问的）
</wrap>

**注意：登录到容器后，使用容器在命令行提交作业时，可使用example01里的slurm.sh脚本文件进行作业提交，但是需要将脚本里的IP改成 ipconfig 查看对应 WSL 虚拟网卡的IP，即将脚本中最后一条提交作业的命令（ mpirun -np $SLURM_NPROCS PWmat -host 172.20.192.1 50001 | tee output）中的IP（172.20.192.1）改成 WSL 虚拟网卡的 IP**
===== 6. qstudio、qflow 访问登录 =====

从这一步开始，改为使用**网页浏览器**操作（推荐 Chrome 或 Edge），访问地址：%%http://[宿主机ip]%%   宿主ip就填写127.0.0.1

**注意：**如果是安装在远程服务器上，这步是需要在远程服务器的浏览器进行操作

^ 账号         ^ 密码       ^
| 15000000000  | PWmat2022  |

如果粘贴密码提示错误，可能是浏览器兼容性问题，手动输入密码即可。

~~DISCUSSION:off~~


----

**若是通过本机连接到远程服务器安装的，想通过本机访问，可查看下文：**

如果是在本机（自己的电脑）安装，以上访问方式和下面这种访问均可，如果是通过本机连接到远程服务器进行安装，只需要在远程服务器上进行访问，可以采用上面这种访问方式（不可以通过本机直接访问），但如果想通过本机直接访问访问，可以通过以下这种方式（通过真实宿主IP的方式进行访问），该方式可实现在远程服务器进行访问，也可以直接通过本机进行访问：

具体如下：

启动容器时，需要通过以下方式进行启动（与上述启动容器的的区别加了三段0.0.0.0）：

<code bash>
wslc run -d --name qflowgpu -e SERVERIP=172.20.192.1 `
  -v $env:TEMP\pwmat:/var/tmp/pwmat_host_secret:ro `
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --gpus all --shm-size=128G `
  -e SELINUX=disabled -p 0.0.0.0:80:80 -p 0.0.0.0:81:81 -p 0.0.0.0:2297:2297 -p 5010:5010 `
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest
</code>

启动成功后，

**访问容器时：**可以通过本机powershell/本机Xshell或者MobaXterm/远程服务器的powershell/远程服务器的xshell等，进行访问登录，访问时，宿主IP可通过ipconfig命令获取到以太网适配器 Onboard LAN2下的IPv4地址，即为真实宿主IP（例如，192.168.97.23）。而端口，用户名和密码参考上文对容器访问的表格

**访问qflow和qstudio时：**采用真实宿主IP进行访问，具体方式，直接在本机的浏览器/远程服务器搜索 %%http://[宿主机ip]%%（宿主IP:通过ipconfig命令获取到以太网适配器 Onboard LAN2下的IPv4地址）

~~DISCUSSION:off~~