JetBrains Remote Development
窗口已经打开，为什么项目仍然不能构建
开发者在本地安装了正确 JDK，Gateway 也顺利打开远端项目，但 Gradle 同步仍提示找不到 Java。关闭窗口后，云主机 CPU 继续被索引进程占满；本地代理能下载 JetBrains Client，远端 Maven 却始终无法访问私服。三个现象指向同一个误解：Remote Development 不是远端目录映射，也不是把服务器桌面画面传回来，而是把 IDE 拆成 Client 与 backend 两个运行边界。
本地 JetBrains Client 负责窗口、输入和交互；远端 IDE backend 持有源码、项目模型、索引、SDK、构建工具、功能型插件和项目进程。Gateway、Toolbox App 或本地 IDE 只是建立连接的入口。Remote Development FAQ对这套结构的描述意味着：给本地机器增加内存不能治愈远端索引，关闭 Client 不等于停止 backend，本地代理也不会自动成为远端构建工具的代理。
受控安装入口与远端基线
Gateway 安装说明提供三种入口：IDE 内置的 Remote Development Gateway 插件、Toolbox App，以及独立 Gateway。完整 IDE 已纳入组织版本治理时，优先启用其 bundled 插件；团队同时管理多个 JetBrains 产品与本地版本时，Toolbox 更便于统一入口；薄客户端或受控软件分发场景可使用独立 Gateway。三种入口最终都会选择或部署远端 backend，并启动与 backend 构建匹配的 JetBrains Client。
安装前在官方系统要求页核对本地操作系统、远端系统、CPU 架构、存储与开放端口。SSH Gateway 当前主要面向可运行第三方软件的远端主机，共享 Web 主机因端口和资源限制不受支持；大型项目优先使用本地块存储、足够的 CPU/RAM 和 swap。不要用“SSH 能登录”替代产品支持判断，也不要把 NFS/SMB 上的偶然可运行写成团队基线。
远端账号使用普通用户、独立项目目录和明确磁盘配额。连接前先从系统终端验证 SSH 和主机事实，让 Gateway 只处理 IDE 部署与连接：
ssh dev@example.com
uname -a
df -h "$HOME"
git --version预期 SSH 成功，hostname、用户、磁盘和 Git 都与资源申请一致。示例账号与域名是占位符；团队应优先复用经批准的 ~/.ssh/config、短期 SSH 证书或硬件保护密钥，不要把密码、私钥和跳板信息写入仓库。随后在入口中执行 Check Connection and Continue，明确选择 IDE 产品、backend 构建、安装路径和项目根。
SSH 连接向导支持由远端下载 backend、从企业内部 URL 获取，或从本地上传安装包。下载通道受限时，内部镜像必须保存产品、构建号、校验值和来源；不要把来源不明的解压目录注册为 backend。版本更新采用新旧 backend 并行验证：先用代表性项目确认索引、构建、运行、调试和插件，再从 Manage IDE Backends 卸载旧构建。Gateway 免费并不代表 backend 免费；许可说明要求本地有效许可与远端 IDE 产品匹配，许可校验发生在本地，不应复制到远端主机。
先建立 Client / Backend 心智模型
一次 SSH Remote Development 的主链路是：本地入口读取 SSH 配置，登录远端，选择或部署匹配版本的 IDE backend；backend 在远端打开项目并完成索引；本地下载与 backend 匹配的 JetBrains Client；两端通过 Remote Development 协议交互。
因此，代码导航、静态分析、构建、运行、调试和大多数功能型插件都依赖远端资源。本地主要承担绘制界面、键盘鼠标、剪贴板和连接管理。网络抖动会影响交互，但把 CPU 或内存只加在本地通常不能解决远端索引过慢。
进入远程窗口后立即在 IDE Terminal 取证：
printf 'host=%s\nuser=%s\n' "$(hostname)" "$(id -un)"
pwd
git rev-parse --show-toplevel预期显示远端主机、远端用户和目标仓库根。若出现本地路径、错误账号或仓库父目录，应退出并修正连接与项目路径；继续安装 SDK 或清索引只会扩大错误状态。
还可以做一次不会修改业务数据的进程边界反向实验。在 Backend Control Center 记录当前项目为 Running，关闭 JetBrains Client 窗口，再从独立 SSH 会话观察当前用户的 JetBrains 进程与监听端口：
ps -fu "$(id -un)" | grep -E 'remote-dev|jetbrains|idea' | grep -v grep
ss -lntp若 backend 仍在，说明“关闭 Client 就释放远端资源”的假设是错的。回到 Gateway 的 Recent Projects，对准确项目执行 Stop IDE Backend，然后重新运行观察命令；目标项目进程和转发端口应消失。不要用 pkill -f idea 代替这个步骤，同一用户可能同时运行多个项目或 backend 构建。
选择正确入口
Toolbox App：管理本地入口和连接
Toolbox App 适合团队把本地 JetBrains 产品、版本和 Remote Development 入口放在同一处。当前产品页强调它可以导入 OpenSSH 配置，并支持 ProxyJump、MFA、IdentityFile 和替换 SSH binary 等现有能力。它不会替团队创建远端主机，也不会让不受支持的服务器变成受支持环境。
在 Toolbox 中选择 Remote Development，导入批准的 SSH host，执行连接检查，再选择产品、backend 版本和项目路径。创建前确认界面显示的产品与组织许可证匹配，避免把 IDEA、PyCharm 或其他产品 backend 当作可互换实例。
本地 IDE：上下文连续但仍会启动 Gateway
在本地 IDE 欢迎页选择 Remote Development，或在已打开 IDE 中选择 File | Remote Development。当前文档说明该入口依赖 bundled 的 Remote Development Gateway 插件，连接后仍由 Gateway 部署 backend 并打开 JetBrains Client。
这个入口适合开发者已经按团队基线安装本地 IDE 的场景。它不意味着本地 IDE 直接执行远端项目，也不应据此把本地插件、JDK 或 Maven 缓存视为远端已有。
独立 Gateway：隔离连接入口
独立 Gateway 适合薄客户端、受控软件分发或不希望安装完整本地 IDE 的机器。它本身免费，但连接到付费 IDE backend 时仍需有效许可。团队需要单独管理其更新、SSH 配置、代理、日志和卸载，不能因为安装包轻量就省略客户端治理。
跑通第一个 SSH Backend
在 Gateway 的 SSH provider 中新建连接，优先选择 Parse config file ~/.ssh/config 或组织批准的 OpenSSH 流程。先执行 Test Connection，成功后再进入 backend 页面。
backend 安装有三条实用路径：
远端能访问 JetBrains 下载域名时，让 Gateway 自动获取。企业内网通过受控制品库提供 .tar.gz 下载链接。远端不能访问公网时，从本地上传已校验的官方安装包。
默认 backend 分发缓存位于：
~/.cache/JetBrains/RemoteDev/dist如果 $HOME 配额有限，在向导的安装选项中改为经过容量和权限治理的本地块存储路径。不要放在 NFS 或 SMB 上；官方当前不支持网络文件系统作为 Remote Development 存储。
选择远端项目根后点击 Start IDE and Connect。首次连接会经历安装包传输、解压、backend 启动、项目导入和索引，不能只以“窗口已经出现”判断成功。
连接后用项目自己的 CLI 合同做最小验证。以一个已有的 Maven Wrapper 项目为例：
./mvnw -q -DskipTests package预期退出码为 0，随后在 IDE 中运行同一个应用或测试，并设置一个不会改变业务数据的断点。断点命中、变量可读取、停止后目标进程退出，才证明“远端工具链、IDE 模型、运行和调试”整条链路成立。若仓库不是 Maven 项目，应替换成其 README 或 CI 使用的权威命令，不要为了演示新增第二套构建入口。
SSH、WSL 与 Dev Container 不是三个皮肤
SSH 模式把代码、backend 和工具链放在远端 Linux 主机上，生命周期主要由远端用户目录和 backend 进程承担。它适合已有开发主机、云 VM 或企业开发环境，但机器镜像、账号、磁盘和关机仍由平台负责。
WSL 模式把 backend 放在本机 Windows 的 WSL2 发行版中。它解决 Windows UI 与 Linux 工具链协同，不是跨网络服务器。JetBrains 对 WSL 入口的发行版、资源和发布通道要求仍可能随构建变化，启用前应从当前 IDE 帮助页核对支持矩阵，并用团队锁定构建完成连接、索引和调试。项目应放在 Linux 文件系统，避免跨 /mnt/c 扫描放大索引与构建 IO。
Dev Container 模式把项目工具链和 backend 进一步放入 Docker 容器。它的事实源是 devcontainer.json、镜像或 Dockerfile 及其生命周期命令。远端 Dev Container 向导会在远端 Docker 环境构建容器，再由 JetBrains Client 连接其中的 backend。原生同窗、远端项目和 Docker 连接方式的支持边界仍在演进，选型时必须以团队锁定构建对应的帮助页为准，并实际验证本地 Docker CLI、构建上下文、远端 daemon 和 Client/backend 组合。
选择原则很简单：已有稳定开发主机选 SSH；单机 Windows 需要 Linux 工具链选 WSL；需要把工具链定义提交进仓库并隔离依赖时选 Dev Container。不要为了“环境统一”把生产服务器作为 backend，也不要把 WSL 当作团队共享云工作区。
端口、代理与网络分层
远端应用监听的是 backend 所在环境。运行 Web 项目后，从 JetBrains Client 顶部的 backend 名称进入控制窗口，在 Ports 页检查转发端口。端口存在、状态正常，再通过提供的转发入口访问；不要把远端 localhost:8080 误当成本机同名端口。
若服务没有出现，先在远端 Terminal 判断进程是否真的监听：
ss -lntp | grep ':8080'
curl -fsS http://127.0.0.1:8080/health预期看到监听记录，健康检查返回成功状态。服务未监听属于项目问题；服务已监听但 Ports 中没有转发，才进入 IDE 端口诊断。管理端、调试端和数据库端口不应随意暴露，使用完要停止转发并终止目标进程。
代理至少有三层：本地 Gateway/Client 访问 JetBrains 账号、许可和下载服务；SSH 自身通过 jump host 或代理连接远端；远端 backend、Git、Maven、Gradle、npm 和容器运行时访问各自外部服务。Gateway SSH 配置中的 HTTP/SOCKS Proxy 不能自动替代项目工具链代理。
内网部署时，先决定安装包由远端下载、内部 URL 提供还是本地上传。若项目依赖私服，在远端分别验证 DNS、TLS 和工具链配置。不要把代理密码写入 .idea、共享 run configuration、命令历史或截图；企业 CA 应通过操作系统与运行时的受控信任链部署，而不是全局关闭证书校验。
许可证、插件与凭证落点
Gateway 是免费启动器，远端 IDE backend 仍受对应产品许可约束。许可在本地客户端侧检查，不传入或保存到远端；本地许可证产品必须与 backend 匹配。组织仍在使用旧 Floating License Server 时，应按 JetBrains 的迁移说明评估 License Vault 或合同允许的当前方案，不能把旧 FLS 继续写成新环境基线。
插件要按执行位置判断。代码分析、语言和框架能力通常安装到远端 backend；主题、快捷键等界面插件可能落在 Client 或两侧。当前官方帮助还提示 backend 插件按项目安装。团队应在 Plugins 页面确认位置和版本，不要用“我本地装过”解释远端缺少能力。
远端项目凭证存储说明显示，backend 默认可用 KeePass 把数据库凭证、GitHub token 等保存到磁盘。高敏感、短会话环境可以在用户级 $HOME/.config/JetBrains/CredentialStore/ 或系统级 /etc/xdg/JetBrains/CredentialStore/ 设置两个文件：defaultProvider 写入 MEMORY_ONLY，availableProviders 只列出组织允许的 provider。MEMORY_ONLY 会在 IDE 重启后清除凭证；KEEPASS 支持跨重启持久化，也意味着远端磁盘、备份和管理员成为凭证边界。
修改后重启目标 backend，在 Appearance & Behavior | Passwords 确认只出现批准的 provider，再用低权限测试凭证完成一次登录、重启和失效验证。需要持久化时也应使用最小权限开发凭证，不要转发个人 SSH 私钥，不要在远端放生产 kubeconfig，也不要把未经脱敏的诊断包直接上传工单。
缓存、性能与版本管理
Remote Development 会在远端留下 backend 分发、IDE 系统目录、索引、插件、项目构建缓存和源码本身。磁盘增长不能只盯 ~/.cache/JetBrains/RemoteDev/dist，还要区分可重新下载的 backend、可重建索引、项目依赖缓存和唯一未提交代码。
先在 Backend Control Center 的 Performance 页看 CPU、RAM、Disk 和 Ping。项目打开后持续高 CPU，先检查导入和生成目录；内存不足再评估 -Xmx，不要把最大堆调到挤压系统页缓存和构建进程。官方当前建议本地 SSD 和 swap，大项目应按索引与构建并发配置资源。
升级采用“新 backend 构建并行验证”，不要直接删除唯一可工作的版本。Gateway 的 recent project 菜单可以切换 backend 版本；验证项目导入、索引、构建、运行、调试、插件和端口后，再从 Manage IDE Backends 卸载旧分发。
后端日志与故障闭环
SSH 检查成功，Backend 启动失败
连接测试通过，安装或启动阶段中断。 检查远端磁盘、写权限、架构、下载可达性和可用端口；查看 Backend Control Center 的 Output。 默认缓存目录配额不足、安装包下载被代理或证书阻断、系统不受支持，或主机禁止额外监听端口。 改用受控安装路径或本地上传包，修正网络信任；共享 Web 主机直接判为不适用。 backend 进程启动，Client 打开项目，Output 不再出现同类错误。
窗口能打开，但索引和构建很慢
输入延迟不高，代码分析和构建却持续卡住。 分开看 Ping、远端 CPU、RAM、Disk、项目导入和 CLI 构建时长。 瓶颈在远端资源或存储，不是本地绘制；也可能误用 NFS / SMB、打开仓库父目录或扫描生成物。 使用本地块存储，修正项目根和排除目录，按证据增加远端资源。 CLI 与 IDE 导入都收敛，重连后不依赖清缓存恢复。
Client 可用，依赖下载失败
界面和许可正常，Maven、Gradle、npm 或插件下载失败。 在远端执行对应 CLI 的网络诊断，并区分 Client 代理、SSH 代理和 backend 代理。 本地代理只覆盖 Gateway，远端没有 DNS、CA、私服认证或 egress。 在正确层配置受控代理、CA 和最小权限凭证。 远端 CLI 与 IDE 使用同一私服和证书链成功下载。
端口存在但页面打不开
Ports 显示端口，访问仍失败。 远端 ss 与 curl 验证应用，再看转发状态和应用绑定地址。 应用已退出、健康检查失败、端口选错，或连接重建后旧入口失效。 先恢复项目进程，再重新建立必要转发。 远端环回访问和 Client 转发访问同时成功。
需要完整证据时
Backend Control Center 的 Output 只显示远端日志尾部。问题无法定位时，使用 Collect Host and Client Logs 同时采集两侧日志；必要时选择 Show Main Window 进入 backend 主窗口，再通过 Help | Show Log 和 Diagnostic Tools 检查。提交前清除账号、主机名、项目路径、仓库 URL、代理、token 和业务源码片段。
退出、停止与清理
关闭 JetBrains Client 只结束本地窗口，官方明确说明远端项目不会自动关闭。短暂离开且团队允许复用时，可以保留 backend；结束工作或释放资源时，回到 Gateway 的 Recent SSH Projects，选择 Stop IDE Backend，再验证项目进程和转发端口已停止。
远端取证可使用：
ps -fu "$(id -un)" | grep -E 'remote-dev|jetbrains|idea' | grep -v grep
ss -lntp
du -sh ~/.cache/JetBrains/RemoteDev 2>/dev/null这些命令用于观察，不应直接把匹配到的进程全部杀掉。一个主机可能承载多个项目或版本；先通过 Gateway 停止目标 backend，再按 owner 和路径清理。
卸载旧 backend 使用 Manage IDE Backends，而不是手工删除正在运行的分发目录。Dev Container 还会留下 jb_devcontainers_shared_volume、源码 volume、Feature 镜像和构建缓存；官方 FAQ 表明部分无用镜像目前仍需手工删除。删除前确认没有其他项目复用，并把容器、volume、镜像和 backend 分开发现与回收。
架构取舍与团队治理
Remote Development 适合源码不应落到笔记本、项目索引和构建资源较重、需要统一 Linux 工具链或从低配终端访问开发环境的团队。代价是对网络时延、远端 CPU/内存/块存储、backend 版本、许可证和远端凭证治理提出了更高要求。
若项目小、离线工作频繁、本地硬件足够，本地 IDE 的故障面更小；若环境必须由仓库定义，Dev Container 比裸 SSH 主机更可复现；若还需要工作区供应、自动停止、配额和审计，应在 CodeCanvas、Codespaces 或其他开发环境平台层解决，不能让 Gateway 兼任云资源编排器。
团队基线至少记录：允许的本地入口和版本、受支持 backend 产品与构建、许可证来源、SSH 身份与跳板策略、远端主机镜像、存储类型和配额、项目根、SDK 与 wrapper、代理和 CA、插件清单、端口暴露规则、凭证存储模式、日志留存、空闲停止、旧 backend 清理与 owner。
升级前选择代表性项目做并行验证；离职或项目结束时回收 SSH 访问、停止 backend、撤销开发凭证、删除无主源码与缓存，并保留不含敏感内容的审计证据。团队真正要治理的不是 Gateway 图标，而是“谁能在什么远端环境，用哪种 IDE 与许可，执行哪份源码并访问哪些网络和凭证”。
交付前从当前窗口读取 hostname、用户、项目根、SDK 和构建入口，确认它们都落在预期远端。Toolbox、IDE 内入口与独立 Gateway 属于不同启动路径，许可证必须匹配实际 backend 产品；SSH、WSL、Dev Container 和原生同窗模式也只能按代表项目的当前构建结果比较，不能从一个入口推断另一个入口可用。
CLI、IDE Run、Debug 与端口转发要穿过同一目标环境。Client、SSH、backend 和项目工具链各自处理代理与 CA，任何一层都不关闭 TLS 校验；backend 分发、索引、插件、源码和构建缓存则分别记录路径、配额和 owner。这样磁盘满、插件失效或依赖下载失败时，故障不会统称成“Gateway 连不上”。
关闭 Client 以后再检查 backend 进程，才能看清空闲成本。日常退出由 Gateway 停止会话，旧版本按受控入口卸载；Host/Client 日志和诊断包脱敏后才进入工单。版本升级、空闲停止、权限回收和环境退役各有负责人，项目结束时能撤销 SSH 与开发凭证，并处理无主源码和缓存。