mirror of
https://github.com/l0ng-ai/openidea.git
synced 2026-11-14 16:07:52 +00:00
l0ng-ai
76faa39bc5
Tools › Start SSH Session ran the system `ssh -t` in a terminal, which never used the password saved in the SSH configuration and, on Windows, could not take a typed password either. The session now opens a login shell over the IDE's SSH connection: the terminal manager can attach a channel (here an SSH shell) next to local PTYs, with the same output batching, UTF-8 decoding and exit events. A password or passphrase that isn't saved is asked for in a dialog, and an unknown host key asks to be trusted, before reconnecting. Closing the tab hangs the shell up. Also: a remote process closed by this side now ends without waiting for a close that russh never forwards, and each connection attempt gets its own IPC channel, since a failed attempt invalidates the one it was given. Fixes #2874
115 lines
7.8 KiB
Plaintext
115 lines
7.8 KiB
Plaintext
---
|
||
title: "SSH"
|
||
description: "打开位于 SSH 主机或 WSL 发行版中的项目，IDE 后端在代码所在的机器上运行。"
|
||
---
|
||
|
||
远程开发让你在普通的 OpenIDEA 窗口里打开另一台机器上的项目文件夹。界面留在本机，IDE 后端
|
||
[`openidea-server`](/zh/guide/remote/server) 运行在远程主机上：索引、语言服务器、终端、运行配置、调试器、构建工具和 Git
|
||
都在代码旁边执行。
|
||
|
||
OpenIDEA 通过 SSH 连接；在 Windows 上也可以直接连入 WSL 发行版。开发容器见[容器](/zh/guide/remote/containers)。
|
||
|
||
## 前提条件
|
||
|
||
- SSH 主机运行 Linux（x86_64 或 aarch64）或 macOS（Apple 芯片或 Intel）。不支持 Windows 主机。
|
||
- 主机上有 POSIX shell 以及 `uname`、`gzip`、`mkdir`、`chmod`、`mv`、`find`，并启用了 SFTP 子系统（安装服务端和连接对话框里的**浏览**都要用到）。
|
||
- 首次连接时，本机会下载对应版本的 `openidea-server` 发布构建，再上传到主机。本机无法联网时，见[离线安装](/zh/guide/remote/server#离线安装)。
|
||
|
||
## 添加 SSH 配置
|
||
|
||
远程开发、运行目标、数据源隧道、部署服务器以及**启动 SSH 会话…**都使用应用级的 SSH 配置连接。
|
||
|
||
<Steps>
|
||
<Step title="打开 SSH 设置">选择**工具 › SSH 配置…**，或打开**设置 › 工具 › SSH 配置**。</Step>
|
||
<Step title="添加配置">点击 **+**（添加），填写**名称**、**主机**、**端口:** 和**用户名**。</Step>
|
||
<Step title="选择身份验证方式">在**身份验证类型**中选择一项（见下表）。</Step>
|
||
<Step title="测试连接">
|
||
点击**测试连接**。如果主机密钥还不在 `~/.ssh/known_hosts` 中，OpenIDEA
|
||
会显示该密钥并提供**信任主机并重试**，把它写入该文件。
|
||
</Step>
|
||
</Steps>
|
||
|
||
| 身份验证类型 | 使用的凭据 |
|
||
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| **密码** | 密码。勾选**保存密码**后存入系统凭据库。 |
|
||
| **密钥对（OpenSSH 或 PuTTY）** | **私钥文件**（例如 `~/.ssh/id_ed25519`）及其**密码短语**，勾选**保存密码短语**后存入凭据库。 |
|
||
| **OpenSSH 配置和身份验证代理** | `~/.ssh/config` 中的 `HostName`、`User`、`Port`、`IdentityFile` 和 `ProxyJump`，以及 SSH 代理中的密钥。**主机**可以填 `~/.ssh/config` 里的 `Host` 别名。 |
|
||
|
||
保存的密码和密码短语存放在 macOS 钥匙串、Windows 凭据管理器或 Linux 的 Secret Service 中，不会写进设置文件。列表上方的
|
||
**+**、**−** 和复制按钮用于添加、移除和复制配置。
|
||
|
||
### `~/.ssh/config` 支持
|
||
|
||
OpenIDEA 自带 SSH 客户端，自行读取 `~/.ssh/config`，支持 `Host`、`Match`、`Include`、`HostName`、`User`、`Port`、
|
||
`IdentityFile`、`ProxyJump`、`ProxyCommand`、`StrictHostKeyChecking` 和 `UserKnownHostsFile`。跳板机通过代理和身份文件认证，
|
||
配置里的密码或密码短语只用于目标主机。
|
||
|
||
主机密钥会与 `known_hosts` 比对。未知密钥需要先信任一次；密钥发生变化时会拒绝连接，除非对该主机关闭了主机密钥检查。
|
||
|
||
## 打开远程项目
|
||
|
||
<Steps>
|
||
<Step title="打开连接对话框">选择**文件 › 远程开发…**，或在欢迎页点击**远程开发**。</Step>
|
||
<Step title="选择主机">在 **SSH 配置：**中选择一项。还没有配置时，点击**配置…**打开 SSH 设置。</Step>
|
||
<Step title="选择文件夹">
|
||
在**项目目录：**中输入路径（`~` 和 `~/…` 相对于远程用户主目录），或点击**浏览**逐级选择远程文件夹。
|
||
</Step>
|
||
<Step title="打开">点击**打开**。如果当前已有打开的项目，再选择**当前窗口**或**新窗口**。</Step>
|
||
</Steps>
|
||
|
||
连接过程中，对话框会依次显示各个阶段：连接主机、检查主机上的 IDE 后端、按需下载或安装、启动后端、打开项目。第一次连接某台主机时需要上传服务端，
|
||
会慢一些；之后会复用已安装的版本。
|
||
|
||
项目打开后，和本地文件夹一样会询问是否信任该项目。
|
||
|
||
<Tip>首次连接前，先在 SSH 设置里运行一次**测试连接**：信任新主机密钥、输入密码或密码短语都在这里完成。</Tip>
|
||
|
||
## 在远程窗口中工作
|
||
|
||
- 窗口标题末尾显示主机名，状态栏显示 **SSH: `<host>`**，点击它会打开**远程开发**对话框。
|
||
- 远程项目会出现在欢迎页的最近项目列表中，可以从那里重新打开。
|
||
- OpenIDEA 安装的语言服务器、调试器等工具都装在远程主机的 `~/.openidea/data` 下。
|
||
- 快捷键、外观、编辑器字体和配色方案保留在本机；项目和工具相关的设置保存在主机上。
|
||
- 你的代码插件会同步到服务端，在项目所在的机器上运行。
|
||
- **文件 › 断开与远程主机的连接**会关闭项目并断开连接。
|
||
|
||
### 端口转发
|
||
|
||
远程窗口中有一个**端口**工具窗口。在**远程端口，例如 3000**处输入端口，点击**转发端口**后，远程主机上的 `localhost:<port>`
|
||
就可以在本机访问：本机同号端口空闲时使用同一端口，否则换一个空闲端口。每一行都可以在浏览器中打开、复制地址或停止转发。
|
||
|
||
转发的端口按主机和文件夹记住，下次连接时会自动重新转发。
|
||
|
||
### 重新加载环境
|
||
|
||
服务端启动时会读取你在主机上的登录 shell 环境。修改 shell 配置文件后，选择**文件 › 重新加载环境**，新开的终端、运行和工具就会拿到新值；
|
||
已经在运行的进程保持原来的环境。如果有变量发生变化，通知里会提供**重启语言服务器**。
|
||
|
||
如果远程项目包含 `.devcontainer/devcontainer.json` 或 `.devcontainer.json`，其中的 `remoteEnv` 也会生效，`postStartCommand`
|
||
会在每次服务端启动时运行一次。
|
||
|
||
## 打开 SSH 终端
|
||
|
||
**工具 › 启动 SSH 会话…**（或终端工具窗口新建标签菜单里的 **SSH 会话…**）会让你选择一个 SSH 配置，并在终端标签页中打开该主机的
|
||
Shell。IDE 内置的 SSH 客户端会使用配置里保存的密码、密钥或代理连接；密码或密码短语没有保存时会询问，遇到未知的主机密钥会询问是否信任。
|
||
不需要本机安装 OpenSSH 客户端。它不会打开远程项目。
|
||
|
||
## 连接 WSL（Windows）
|
||
|
||
在 Windows 上，只要装有至少一个 WSL 发行版，连接对话框就会出现**连接方式：**，可选 **SSH** 或 **WSL**。选择 **WSL**，
|
||
在 **WSL 发行版：**中选好发行版，再在**项目目录：**中填写发行版内的路径。OpenIDEA 通过 `wsl.exe` 在发行版内安装并启动
|
||
`openidea-server`，不需要 SSH 服务器。状态栏随后显示 **WSL: `<distribution>`**。
|
||
|
||
打开 `\\wsl.localhost\<distribution>\` 下的文件夹时，也会自动通过该发行版打开。WSL 方式不支持**浏览**。
|
||
|
||
## SSH 配置的其他用途
|
||
|
||
- **运行目标**（**设置 › 构建、执行、部署 › 运行目标**）可以在 SSH 主机上执行运行配置，见[运行配置](/zh/guide/run)。
|
||
- **数据源**可以通过 SSH 隧道连接，见[数据库](/zh/guide/database)。
|
||
- **工具 › 部署**通过 SFTP、FTP 或 FTPS 与服务器上传、下载和同步项目文件。
|
||
|
||
## 限制
|
||
|
||
- 一个远程窗口只对应一个项目：远程项目不能附加到其他窗口的项目中。
|
||
- SSH 主机必须是 x86_64 或 aarch64 上的 Linux 或 macOS。
|