PyCharm远程开发指南（一）- 总览

本文译自PyCharm 2022.2官方文档

远程开发允许用户使用一台远程服务器作为开发环境，这里使用SSH连接以快速连接到服务器并且可以使用大多数PyCharm的特性。

1.1 架构与定义

PyCharm远程开发整体架构图如下：

为了更好的理解上图，我们做如下定义：

服务器

服务器是一个物理或虚拟的主机以存储源代码并且运行无头版PyCharm。无头版（Headless）Pycharm仅有后端的内容管理系统，不包含前端或表示层的部分，但是能够支持大部分IDE的特性。

需求：Linux

客户端

客户端是一个用户使用的物理主机用以连接到服务器并且提供一个瘦客户端以支持工作。瘦客户端是一个基本无需应用程序的计算哑终端，其通过特定协议与服务器通讯，将键鼠等输入传输到服务器处理，服务器再把处理结果回传至瘦客户端显示。举例来说，可以是你的笔记本电脑。不过，客户端并没有太多配置需求。

需求：macOS，Linux，Windows

IDE后端

这是一个在服务器上运行的高可适配的JetBrains IDE。IDE会作为服务器进程运行，并且没有可视化的用户界面（it's headless）。这可能和你正在运行的IDE是同一个可执行文件。

JetBrains客户端

在运行JetBrain网关并且建立了一个到服务器的连接之后可以见到的瘦客户端。它负责连接到IDE后端并且让你能够像在本地操作一样来进行远程开发。

与远程桌面方案不同的是，JetBrains客户端拥有一个更高级的，基于JetBrains Rider的RD协议的编辑器，这使得输入感觉非常顺畅。并且呢，PyCharm服务器上部署的高级智能代码模块会表现的如同在本地一样。

JetBrains客户端基于IntelliJ平台，因此它可以导入任何在本地机（客户端）上的本地IDE配置。举例来说，如果我们有一个PyCharm 2021.3安装在客户端，这个下载运行的客户端会自动导入配置并让远程开发系统为你做定制化的调整。

JetBrains客户端的版本需要与后端IDE的版本保持一致。

JetBrains网关

这是一个远程开发的入口点。网关在客户端上运行，并且允许你创建一个新的远程开发环境或者连接到现有的环境。在你向JetBrains网关请求了一个环境之后，网关会运行一个与请求环境对应的JetBrains客户端。

JetBrains网关将负责下列任务：

• 允许你建立一个远程连接到可连接到的任何种类的远程后端；
• 检索现有最近的远程开发项目；
• 连接到新的或者现有的项目；
• 从特定存储下载版本匹配的JetBrains客户端；
• 运行JetBrains客户端；
• 维持连接。JetBrains网关进程会配置并建立连接到服务器（SSH或者端口转发到其他任何自定义的连接）并且运行JetBrains客户端来对接开启的连接或者端口。除此之外，JetBrains网关会负责维持连接，处理重新连接（不管是否是UI发起的请求），并且指示当前连接的状态信息。

1.2 工作流

这里有两种远程开发的工作流可供选用：

• 服务器-客户端：当一个组织首先建立一个远程无头服务器，获取一个（自定义或者非自定义的）连接，该连接可以被你在客户端上（比如笔记本电脑）使用以连接到远程可用的服务器。
• 客户端-服务器：从客户端UI上使用SSH或者其他连接建立并安装远程服务器。

服务器-客户端工作流（连接到手动运行的远程IDE上的远程项目）

如果你在远程服务器上已经有一个PyCharm安装好了，你可以手动运行它并且在这个IDE中连接到远程项目，这和从JetBrains网关运行是差不多的。

如果你的公司有一个自定义的编排方式或者比如你的远程IDE可以自动开启运行，可以选用这种工作流。

简单来说，这个流程大致为：在远程IDE开启后端项目 -> 选择一个在后端生成的连接地址 -> 在你本地机器中打开项目。

运行一个远程IDE的主脚本是 remote-dev-server.sh ，位于解包IDE的子文件夹 bin 中。

*   对于macOS系统，如果后端被JetBrains网关安装了，那么默认路径为 /home/your_system_user/.cache/JetBrains/RemoteDev/dist/

* 运行 remote-dev-server.sh --help 以获取更多信息和可用的参数。 

* 请记住绑定的连接地址与特定项目是一一对应的。如果要连接到其他远程项目，你需要配置另一个连接。

连接到远程IDE

1. 确保你已经在本地机上下载并安装了独立或插件打包好的IDE；
2. 确保你有一个SSH连接到远程机上的PyCharm IDE；
3. 在远程服务器的终端上，运行下面指令：

   1. remote-dev-server.sh run /path_to_project/ --ssh-link-host host_server_address
      --ssh-link-user remote_side_user
      --ssh-link-port ssh_connection_port

   2. 如果不传入参数，会使用默认端口：22，系统用户作为用户名，主机名作为主机名。比如：

   3. ~/PY-213.5744.248/bin/remote-dev-server.sh run ~/home/jetbrains/PythonProjects/SampleApp/ --ssh-link-host ec2-13-50-136-85.eu-north-1.compute.amazonaws.com

4. 如果项目打开成功，作为输出，你应该能在终端中接收到接下来3个连接：
   1. 加入链接：tcp://127.0.0.1:5990...[]：包含本地地址和远程IDE正在监听的端口号。要使用它，确保远程机可以被本地地址访问。
   2. HTTP链接：https:///code-with-me.jetbrains.com/remoteDev...[]：包含你的主机-端口-用户信息，IDE和其版本号信息。在本地浏览器中打开时，会显示欢迎页面，并且尝试唤起本地网关应用并使用给出的设置参数进行连接。
   3. 网关链接：jetbrains-gateway://connect#idePath...[]：包含你的主机-端口-用户信息，IDE和其版本号信息。在本地浏览器打开时，它会直接运行本地的JetBrains网关应用，没有欢迎页面。
5. 复制生成的连接，粘贴到本地浏览器，并允许它运行「打开JetBrains网关」；
6. 所有的这些连接都能在刚刚运行的JetBrains网关中打开。粘贴连接地址到JetBrains网关的欢迎界面中「连接到运行中的IDE」的文本框中，并点击「连接」按钮。PyCharm会下载对应版本的JetBrains客户端，并且在客户端中打开远程项目。

注册先前安装的远程IDE

从版本221.5481开始，你可以在远程服务器上手动注册一个现有的后端IDE并且使它在网关中可见。

要注册一个已经安装的IDE并且使它在一系列构建中可见，需要遵循以下步骤：

1. 通过SSH进入远程服务器；
2. 定位到解包后的IDE所在的文件夹，进入 bin 文件夹；
3. 在命令行中输入并执行下列指令

   remote-dev-server.sh registerBackendLocationForGateway
   

   举例来说，

   sh WebStorm-221.5591.52/bin/remote-dev-server.sh registerBackendLocationForGateway

你可以在不同的连接情景中使用这些链接，比如通过SSH连接、通过自定义连接、或者通过浏览器连接等。

关于如何打开一个远程开发的会话，请参考《建立连接并与JetBrains网关一起工作》一文。 # todo: make text & add link

通过SSH连接

1. 打开JetBrains网关；
2. 选择通过SSH连接；
3. 调整SSH设置。JetBrains网关通过SSH连接，并从已经存在的后端中获得连接地址。网关会从连接地址中转发一个端口号到本地机，并且在JetBrains客户端仍然有效时准备一个新连接地址

配置自定义连接：

1. 打开JetBrains网关；
2. 选择一些JetBrains网关插件提供的自定义连接。一个自定义插件可能连接到某个云服务，从云服务中获取后端列表，或者创建后端等等。JetBrains网关会从这个自定义插件中获得连接地址（多数情况下会指向本地的主机和端口），并且根据这个连接来下载并运行JetBrains客户端。JetBrains客户端版本由连接指定。JetBrains网关会保持在后台运行以维持客户端到服务器的连接。

通过浏览器连接：

1. 在浏览器中，点击带有特定后端地址信息的，特别创建的连接。比如说像SSH连接的情况，它会包含用户名、主机名、SSH端口号、项目在服务器的地址等等。连接会指引到一个落地页，这个落地页会提示打开JetBrains网关或者下载JetBrains网关如果不存在。JetBrains网关会处理从浏览器中打开的连接并且连接到特定的后端。

客户端-服务器工作流

客户端-服务器工作流意味着你没有任何IDE在远程服务器中安装。在这种情况下，首先需要下载并安装JetBrains网关。更多信息请参考《运行JetBrains网关并连接到远程服务器》一文。 # todo

通过SSH连接

1. 下载并安装JetBrains网关。
2. 在JetBrains网关导引中，选择「通过SSH连接」。
3. 在导引的下一步中，选择想要连接的远程服务器。如果远程服务器中没有IDE，JetBrains网关会下载一个。根据用户偏好，IDE可能会从JetBrains服务器中下载、客户端上传、或者从自定义位置下载。RD协议在后端的每个版本都是特定的。JetBrains客户端对应的版本需要下载到远程服务器中。

连接之后，JetBrains网关会在远程机上开始PyCharm服务，建立TCP通道，并且以特定的参数配置开始JetBrains客户端使服务连接成功。

TCP连接格式如下：

tcp://127.0.0.1:PORT#jt=ONE_TIME_CONNECTION_TOKEN fp=SERVER_FINGERPRINT cb=THIN_CLIENT_BUILD jb=THIN_CLIENT_RUNTIME_VERSION

比如

tcp://127.0.0.1:5990#jt=3f2f2471-84f2-4d8b-ac67-c1698f5a1be7 fp=ABC88C383B0A62654C4EF75052C60D4D475885075DCA5B85733BD8D4B9E28CC
0 cb=213.2667 jb=11_0_11b1620.1

1.3 可扩展性

IDE后端

IDE后端是一个成熟的JetBrains IDE，只是运行在一个特殊无头并且无人管理的模式。

这个后端可以以PyCharm插件的最大可能性来扩展，主要方式如下：

• 通过解包需要的插件到 plugins/ 文件夹。
• 通过运行下列代码（需要能够通过网络连接到JetBrains插件市场）：

  ./bin/remote-dev-server.sh installPlugins
                          <pathtoproject>
                          <PLUGIN_ID1>
                          <PLUGIN_ID2>
                          ...

如果一个插件会提供一系列新的特性和外观，所有的这些都会体现到JetBrains客户端中。

如果某个插件过度的修改了UI，那么就不能通过远程开发安装，而是应该直接在JetBrains客户端中直接安装。

JetBrains网关SDK 

JetBrains网关可以像基于IntelliJ平台的其他产品一样的方式被扩展。

你可以使用一下任意的方式：

• 以Gradle plugin for building plugins for IntelliJ-based IDEs建立新项目（gradle-intellij-plugin版本应当>=1.4）
• 使用下列设置构建JetBrains网关插件：

  intellij {
  version.set("213.2667-CUSTOM-SNAPSHOT")
  type.set("GW")
  instrumentCode.set(false)
  }

         可以在  IntelliJ SNAPSHOTS repository 中找到所有可用的版本（看组 com.jetbrains.gateway）

 集成JetBrains网关/瘦PyCharm的客户端

除了通过基本SSH和Code With Me连接之外，软件供货商可以自定义JetBrains网关为自己的编排服务。这可以通过JetBrains和供货商定制化的协议来实现。

JetBrains网关基于IntelliJ平台，它拥有连接和与客户端交互的API。

参考这个案例：

一个大型组织希望开发自己的解决方案。考虑到安全因素，基本SSH流无法满足需求。这个组织开发了一个内部插件并且将其投放给开发者。开发者可以在JetBrains网关中或者笔记本电脑中的PyCharm中安装它。

这是一个非常简短的API介绍，并且也不是特别完整，但是基本上可以管中窥豹，大概看一下整体的思路以供参考。

JetBrains客户端

JetBrains客户端并没有被设计来在连接的部分进行扩展。但是你可以开发或者安装多种多样的PyCharm插件，这些插件能够修改UI、快捷键、主体样式或者其他部分来调整IDE UI的交互，但不改变其功能。