{{htmlmetatags>metatag-robots=(index, follow)}}
====== PWstudio 安装前必看 ======

<wrap em>本篇是整套安装文档的"总入口"，强烈建议新手从头到尾完整看完本篇，再去看对应系统的安装篇章。文档中已经尽量把常见的坑都提前说明了，遇到问题先回来看看本篇有没有提到。</wrap>

如果本篇没有能解答你的问题，欢迎使用 AI 工具（比如问 ChatGPT、豆包、DeepSeek 等）搜索报错信息，绝大多数 Linux 报错都能查到解决办法；也可以在 [[pwstudio:qa2|安装问题 Report / 解答 / 查询 / 讨论]] 里留言。

----

===== 0 先建立一个整体概念（新手必看） =====

在动手安装之前，强烈建议先花 5 分钟看完这一节，建立一个整体概念，很多"卡住"都是因为一开始概念没搞清楚。

==== 0.1 PWstudio 到底是什么 ====

PWstudio 这个软件包里包含三个部分：

  * **Qstudio**：建模工具，用来搭建/编辑原子结构模型
  * **Qflow**：工作流工具，用来把计算任务可视化地"拖拽"编排起来
  * **PWmat**：真正做第一性原理(DFT)计算的核心计算程序

==== 0.2 "装在哪" 和 "在哪用" 是两件事 ====

这是新手最容易搞混的一点，务必先搞清楚：

  * 除了 Windows 系统（通过 WSL）之外，PWstudio 这个软件包**安装**在 Linux 系统上（比如你的 GPU 服务器、工作站）。
  * 但是安装好以后，日常**使用**（建模、拖拽工作流、看计算结果）是通过**网页浏览器**来完成的，不需要你一直守在服务器跟前敲命令。
  * 所以：你的 Linux 服务器需要能联网，并且你用来打开浏览器的这台电脑（可能是另一台 Windows/Mac 电脑），需要能够访问到这台 Linux 服务器（比如同一个局域网，或者服务器有公网/内网可访问的 IP）。
  * 如果你是高级用户，也完全可以不用浏览器，直接在 Linux 命令行上用命令提交计算任务，具体见 [[pwstudio:cmd|PWstudio 在命令行提交]]。
  * 推荐浏览器：**Google Chrome** 或 **Microsoft Edge**（其它浏览器可能出现兼容性问题，比如密码粘贴不进去等）。
  * Qstudio 建模界面需要用鼠标做很多拖拽、旋转、点选操作，建议准备一个鼠标，不要只用触控板。

==== 0.3 你需要准备一台"能登录 Linux 服务器"的工具 ====

因为安装过程中的绝大部分操作，都是在 Linux 服务器的命令行上完成的，所以你需要一个能够：

  - 登录到 Linux 服务器（远程连接，类似"远程桌面"，但这里是文字终端）
  - 在你自己的电脑（Windows/Mac）和 Linux 服务器之间**互传文件**（比如把从网页下载好的驱动、Docker 安装包，传到服务器上）

这样的工具很多，比较常见、新手友好的是 **[[https://mobaxterm.mobatek.net/|MobaXterm]]**（Windows 上免费好用，同时支持登录终端和图形化拖拽传文件），也可以用 PuTTY + WinSCP 组合，或者 Xshell 等，效果都类似，选一个顺手的就行。

<wrap important>
如果你还不会用这类工具登录服务器、上传下载文件，我们专门写了一篇保姆级教程，请先看这里：[[pwstudio:mobaxterm|新手教程：如何用 MobaXterm 登录服务器并上传下载文件]]
</wrap>

==== 0.4 复制粘贴，是新手最好的朋友 ====

在安装过程的命令行部分，**绝大多数情况下你只需要"复制 + 粘贴"命令，而不需要自己一个字一个字去敲**。原因很简单：手动敲命令非常容易打错字符，尤其是一些长得很像的字符（比如字母 <wrap hi>l</wrap>（小写 L）和数字 <wrap hi>1</wrap>（数字 1）很容易看混），打错一个字符命令就会报错甚至造成意料之外的后果。所以本教程强烈建议：

  - 先在网页文档上，把要执行的命令整行选中并复制（Windows/Linux 上是 ''Ctrl+C''，Mac 上是 ''Cmd+C''）
  - 切换到你的终端窗口（比如 MobaXterm 的终端），**对于一些终端软件，只需要在终端里点击鼠标右键，就会自动把刚才复制的内容粘贴进去**（这是很多终端工具，包括 MobaXterm、xshell 等的默认行为）。如果右键不能粘贴，可以尝试 ''Shift + Insert'' 组合键，或者看终端软件菜单里的"粘贴"选项。
  - 粘贴之后，按回车执行

<wrap important>
**极其重要的提醒**：命令行前面那一段形如 ''[lxkt@localhost ~]$'' 或者只有一个 ''$'' / ''#'' 的部分，叫做"命令提示符"，它**不是命令本身**，只是终端用来提示"当前在等你输入"的符号。**复制命令的时候，千万不要把提示符也一起复制进去**，只需要复制提示符后面真正的命令内容。如果你把提示符也当成命令的一部分粘贴执行，终端会报类似 "command not found" 的错误，这是新手很常遇到的问题，一定要注意。
</wrap>

==== 0.5 命令里"看起来奇怪"的部分，通常不需要改 ====

安装文档里，你会看到一些命令中包含形如 ''$(uname -r)'' 、 ''$USER'' 这样的写法，例如：

<code bash>
sudo yum install -y gcc kernel-devel-$(uname -r) kernel-headers-$(uname -r)
</code>

这里的 ''$(uname -r)'' **是命令的一部分，你不需要，也不应该把它替换成别的内容**（比如替换成你自己的用户名）。''uname -r'' 是一个 Linux 系统命令，作用是"查询当前系统内核的版本号"，''$(...)'' 表示"先执行括号里的命令，再把结果代入到外面这条命令里"。所以整条命令的意思是"自动查出我当前系统的内核版本号，然后安装与这个版本号匹配的开发包"。**你只需要原样整行复制粘贴即可，不需要做任何修改**。

同样地，命令里出现的 ''$USER'' 也是系统自动变量，会自动被替换成你当前登录的用户名，同样不需要你手动修改。

==== 0.6 一个字符都不能错：几个常见的"看错"字符 ====

  * ''nvidia-smi'' 这个命令，''nvidia'' 和 ''smi'' 中间是一个短横线 ''-''，**没有空格**。有些人会不小心敲成 "nvidia - smi" 或 "nvidia smi"，这样会报错说命令找不到。
  * 注意区分小写字母 ''l''（L）和数字 ''1''，很多命令和路径里两者都出现，看起来非常像。
  * 同理还是建议：能复制粘贴，就不要手动敲。

==== 0.7 权限要求 ====

显卡(GPU)驱动的安装、Docker 的安装、nvidia-container-toolkit 的安装，都需要服务器的 **root 权限（或者 sudo 权限）**。如果你自己没有这个权限，请联系服务器管理员，为你开通 sudo 权限，或者请管理员按照本教程帮你安装。

==== 0.8 你的机器需要满足的最低条件 ====

  - CPU 必须是 ''x86_64'' 架构
  - 如果要用 GPU 版本，显卡必须是 **NVIDIA** 显卡。支持市面上绝大多数计算显卡如 1080ti、3080ti、3090、4090、5090 等等 **(或同等架构的显卡)**. 可以在此链接[[mstation:gpu|gpu 卡性能对比]]查询显卡型号和对应架构。
  - 内存建议 128G 以上；128G 以下只能安装体验测试，不适合真正拿来跑 qflow 计算作业
  - 宿主机显卡驱动版本要能支持 CUDA 12.1 及以上（1080ti 显卡的驱动版本不要超过 CUDA 12.8，否则可能不兼容）
  - 假设你的 Linux 工作站已经装好了操作系统（CentOS 7.9 / Rocky 8.10 / Ubuntu 24.04，更高版本一般也可以），但还没装任何 PWstudio 相关的软件
  - 如果是 Windows 系统，需要先安装 WSL（Windows 上的一个 Linux 子系统），具体见 [[pwstudio:win11_gpu|windows11_wsl2 安装]] 或 [[pwstudio:win11_cpu|windows11_wsl2 cpu 安装]]。Windows WSL 目前只提供 CPU 版本。

==== 0.9 安装的下载方式说明（很重要，容易被忽略） ====

安装过程中要用到的几个安装包（NVIDIA 显卡驱动、Docker 离线包、nvidia-container-toolkit 离线包等），下载链接都是**普通的网页链接**，
也就是说你需要**用浏览器**去下载它们，而不是在 Linux 服务器的命令行里直接下载（当然如果你的服务器能直接访问外网，也可以在命令行用 ''wget'' 直接下载，文档里也给出了对应的命令）。

如果你是在自己的电脑上用浏览器下载好安装包，那么接下来还需要把这些下载好的文件，**上传**到 Linux 服务器上，才能继续安装。
这一步就要用到前面 0.3 节提到的 MobaXterm（或 WinSCP 等）这样的工具了——它既能让你登录服务器命令行，也能让你把本地文件拖拽上传到服务器。
如果还不熟悉，请先看 [[pwstudio:mobaxterm|MobaXterm 新手教程]]。

<WRAP download 80%>
安装指南中在需要下载的地方, 会有下载链接。

如果下载速度过慢, 请访问此链接: [[https://pan.baidu.com/s/10Iwbs1iF1Nj8RhskRqxdFA?pwd=lxkt|pwstudio 所需离线包]]

它包含了安装所需的所有离线包
</WRAP>

===== 1 安装说明 =====

  - 显卡(GPU卡)驱动的安装, docker 的安装, nvidia-container-toolkit 的安装需要服务器的root权限,
  - 建议使用安装了 linux 系统的 gpu 服务器来安装, 个人 windows 系统 pc的算力可能不够

===== 2 硬件配置 =====

  - cpu 必须是 x86_64
  - 显卡(GPU卡)必须是 nvidia, 目前支持 1080ti, 3080ti, 3090, 4090 d, 4090 等
  - 内存建议是 128 G 以上, 128 G 以下只能安装测试, 不适合跑 qflow 作业

===== 3 软件配置 =====

  - 宿主机显卡驱动的版本要能支持 cuda 12.1 及以上
  - 1080ti 显卡的显卡驱动不要超过 cuda 12.8

查看服务器是否有显卡：如果命令有输出（能看到一行包含显卡型号的信息），说明识别到了显卡；如果什么都没输出，说明没有识别到显卡，或者服务器本身没插显卡。
<code bash>
lspci | grep -i nvidia
</code>


查看显卡驱动是否安装及显卡驱动对应的版本，如果能看到显卡型号、驱动版本、CUDA 版本等信息，说明驱动已安装，可以跳过对应安装步骤；如果提示 "nvidia-smi: command not found" 或者 "-bash: nvidia-smi: 未找到命令"，说明驱动还没装，需要按照后面篇章安装。
<code bash>
nvidia-smi
</code>

<wrap tip>
注意：''nvidia-smi'' 中间是短横线连接，没有空格，输错很容易导致命令找不到，建议直接复制粘贴。
</wrap>

===== 4 系统版本查看 =====

  * centos/rocky 系列 linux 查看系统版本

<code bash>
cat /etc/redhat-release
</code>

  * ubuntu/debain 系列 linux 查看系统版本

<code bash>
cat /etc/os-release
</code>

===== 5 文档查看思路 =====

  - 通过本篇获得系统版本
  - 自己判断是要安装 cpu 版本，还是 gpu 版本
  - 根据系统版本和对应 cpu/gpu 版本，进入[[pwstudio:start|对应篇章]]进行安装
  - 安装中遇到问题可以查看 [[pwstudio:qa|常见问题]]篇章 或 通过 AI 工具查询
  - 通过 [[pwstudio:test|PWstudio 工作流功能验证]] 篇章验证
  - 遇到问题或有什么安装心得可以在 [[pwstudio:qa2|问题 Report]]留言和评论

总结（安装大致要经过哪些步骤，心里先有个数）：

  * **cpu 版本**：安装 Docker → 安装 license 许可服务 → 启动容器
  * **gpu 版本**：安装显卡驱动 → 安装 Docker → 安装 nvidia-container-toolkit → 安装 license 许可服务 → 启动容器

以上四五个步骤中，如果你的机器已经装过驱动/Docker 了，对应的步骤可以跳过。
整个流程如果是第一次装，全部步骤走下来（包含几次系统重启、以及大约 12G 大小的 qflow 镜像包下载，下载可能需要 15 分钟左右），
预计总共需要 30 分钟到 1 小时，具体取决于你的网络速度和机器性能，请耐心一点，不用担心是不是卡住了。

<WRAP important 60%>
> 安装过程会涉及到机器重启，请大家在安装前备份好数据!
>
> 安装过程中系统损坏, 数据丢失，概不负责!
</WRAP>

~~DISCUSSION:off~~