# 使用 JetBrains Gateway 连接 CNB 云原生开发环境

本文档说明如何在 **CNB 云原生开发环境（Workspaces）** 中，
通过 **JetBrains Gateway** 使用 JetBrains 系列 IDE（IDEA / GoLand / PyCharm 等）进行远程开发。

------

## 一、适用范围

适用于希望：

- 使用 **JetBrains Gateway**
- 连接 **CNB 云原生开发环境**
- 在远端容器中运行 JetBrains IDE Server

的开发者。

------

## 二、核心结论（重要）

**CNB 是否展示 `JetBrains Gateway` 入口，仅取决于以下条件：**

当云原生开发环境启动时所使用的 **Docker 镜像** 中，同时满足：

1. 安装并可用 **SSH 服务**（`openssh-server`）
2. JetBrains IDE 安装在 **`/ide_cnb` 目录下**

> ⚠️ 注意
>
> - Gateway 是否可用 **与 CI / Pipeline 配置无关**
> - 与是否安装 code-server、Node、语言运行时无关
> - 与 Dockerfile 是否复杂无关

------

## 三、工作原理说明

当用户点击 **「启动云原生开发环境」** 时，CNB 会：

1. 读取仓库根目录中的 `.cnb.yml`
2. 根据 `$: vscode:` 配置拉取并启动指定的 Docker 镜像
3. 对启动后的容器进行能力探测
4. 若检测到 `/ide_cnb` 目录中存在 JetBrains IDE
   → 在界面中展示 **JetBrains / Gateway** 入口

> 换言之：
> **Gateway 是 Workspaces 能力，而非构建能力。**

------

## 四、最小可运行示例（推荐）

以下示例提供一个 **最小可用配置**，用于快速验证 JetBrains Gateway 是否可正常使用。

### 4.1 仓库目录结构

```text
.
├── .cnb.yml
└── Dockerfile
```

> 说明：
>
> - 本示例无需业务代码
> - 仅用于验证 Gateway 能力是否可用

------

### 4.2 Dockerfile（远程开发环境镜像）

```dockerfile
FROM ubuntu:22.04

# 安装 SSH 服务和必要工具
RUN apt-get update && \
    apt-get install -y wget unzip openssh-server && \
    rm -rf /var/lib/apt/lists/*

# CNB 约定：JetBrains IDE 必须安装在 /ide_cnb
RUN mkdir -p /ide_cnb

# 示例：安装 GoLand
RUN wget -q https://download.jetbrains.com/go/goland-2025.2.5.tar.gz && \
    tar -xzf goland-2025.2.5.tar.gz -C /ide_cnb && \
    rm goland-2025.2.5.tar.gz

ENV LANG=C.UTF-8
```

#### 关键说明

- `openssh-server`
  JetBrains Gateway 通过 SSH 连接远程环境
- `/ide_cnb`
  CNB 用于识别 JetBrains IDE 的固定约定目录
- IDE 可安装多个（IDEA / PyCharm / GoLand 等）

------

### 4.3 `.cnb.yml`（Workspaces 启动配置）

```yml
$:
  vscode:
    - services:
        - docker
        - vscode
      docker:
        image: docker.cnb.cool/<你的命名空间>/<镜像名>:latest
```

> 说明：
>
> - `image` 必须是 **已构建并推送成功的镜像**
> - `.cnb.yml` 仅决定 Workspaces 启动所用镜像
> - 不负责构建或推送镜像

------

## 五、使用方式

1. 提交 `.cnb.yml` 和 `Dockerfile` 至仓库
2. 构建并推送 Docker 镜像至 CNB 制品库
3. 在 CNB 页面点击 **「启动云原生开发环境」**
4. 环境创建完成后：
   - 若镜像满足条件，将显示 **JetBrains / Gateway** 入口
5. 点击入口，自动唤起 **JetBrains Gateway**
6. 选择对应 IDE 并连接

------

## 六、成功判定标准

配置成功后，应满足以下条件：

- 云原生开发环境启动成功
- 页面展示 **JetBrains / Gateway** 按钮
- JetBrains Gateway 可通过 SSH 正常连接
- 本地 JetBrains IDE 成功打开远程项目

------

## 七、常见问题排查

| 现象                | 可能原因                      |
| ------------------- | ----------------------------- |
| 未显示 Gateway 按钮 | IDE 未安装在 `/ide_cnb`       |
| Gateway 连接失败    | 镜像中未安装 `openssh-server` |
| 启动失败            | `.cnb.yml` 指向的镜像地址错误 |
| 无法连接            | 本地未安装 JetBrains Gateway  |

------

## 八、总结

> **JetBrains Gateway 是否可用，
> 只取决于云原生开发环境启动时所使用的镜像内容。**

------