这是本节的多页打印视图。点击此处打印.

操作手册

对SmartIDE各个组件的功能进行完整说明

1: CLI
2: Server
3: SmartIDE插件市场操作手册

3.1: 配置IDE使用SmartIDE插件市场
3.2: 配置自动插件同步机制
3.3: 将你的插件发布到SmartIDE插件市场
3.4: 插件安装手册
3.5: 使用自签名证书进行插件市场私有化部署

4: 项目适配
5: IDE远程连接

1 - CLI

SmartIDE CLI 操作手册

2 - Server

SmartIDE 服务器操作手册

3 - SmartIDE插件市场操作手册

SmartIDE Marketplace的使用方法，包括配置连接手册、插件安装手册、插件发布手册和插件同步机制。

3.1 - 配置IDE使用SmartIDE插件市场

本文档描述如何更新Visual Studio Code以及兼容IDE的配置文件连接到SmartIDE插件市场，包括：VSCode, Codium, Code Server, OpenVSCode Server和OpenSumi。

1. 原理

参考自Using-Open-VSX-in-VS-Code，通过修改IDE product.json 文件中 extensionsGallery.serviceUrl & extensionsGallery.itemUrl & linkProtectionTrustedDomains 节点的值，让IDE链接应用市场时改变API指向达到链接SmartIDE插件市场的目的。

"extensionsGallery": {
    "serviceUrl": "https://marketplace.smartide.cn/vscode/gallery",
    "itemUrl": "https://marketplace.smartide.cn/vscode/item"
}

"linkProtectionTrustedDomains": [
    "https://marketplace.smartide.cn"
]

2. 配置

VSCode

打开 VSCode 安装目录按照如下路径找到 product.json
关闭VSCode 正在运行的进程，用其他编辑器打开 product.json，并参照第1章节修改对应内容
打开 VSCode 进入扩展页面查看插件市场

VSCodium

打开 VSCodium 安装目录按照如下路径找到 product.json
关闭 VSCodium 正在运行的进程，用其他编辑器打开 product.json，并参照第1章节修改对应内容
打开 VSCodium 进入扩展页面查看插件市场

Code Server

打开 Code Server 安装目录按照如下路径找到 product.json，如下图是 mac 系统通过 Brew 安装的 Code Server，则安装目录为 /usr/local/Cellar/code-server
用其他编辑器打开 product.json，并参照第1章节修改对应内容
重新启动 Code Server 服务
打开 Code Server 页面进入扩展页面查看插件市场
另外使用者也可以参考 code-server 文档修改插件市场指向

OpenVSCode Server

容器启动后，打开WebIDE(默认端口3000)，并使用open folder功能打开 OpenVSCode Server 程序目录：/home/.openvscode-server
在左侧搜索窗口搜索关键字 open-vsx.org 全部替换为 marketplace.smartide.cn
重新启动容器
再次打开服务进入扩展页面查看插件市场
以上步骤仅展示修改原理，如果想彻底解决修改 product.json 问题，请自行基于此修改方式创建镜像。

Opensumi

容器启动后，打开WebIDE(默认端口8080)，并修改URL指向 http://http://localhost:8080/?workspaceDir=/release，打开 Opensumi 程序目录：/release
在左侧搜索窗口搜索关键字 open-vsx.org 全部替换为 marketplace.smartide.cn
重新启动容器
再次打开服务进入扩展页面查看插件市场
以上步骤仅展示修改原理，如果想彻底解决修改 product.json 问题，请自行基于此修改方式创建镜像。

3.2 - 配置自动插件同步机制

本文档描述SmartIDE Marketplace 插件初始化同步机制

1. 插件同步介绍

SmartIDE Marketplace 服务搭建初始化后，默认没有插件存在，需要基于 open-vsx.org 已经筛选好的插件列表将插件通过API下载和 ovsx 工具（命令行或npm package）上传的方式同步到 marketplace.smartide.cn 中。

为支持 SmartIDE Marketplace 的插件同步和私有化部署中企业内网的插件同步场景，我们创建了 publish-extensions NodeJS 程序（参考了open-vsx/publish-extensions），并设计了下面2、3、4 三个章节描述的功能分别进行：2: 所有插件的下载， 3. 下载文件夹的所有插件上传，4: 插件边下载边上传操作。

使用者可以使用第4章节功能结合 github action 进行外网插件发布；也可以搭配使用2 和 3 步骤将下载和上传步骤分开在外/内网中进行来初始化企业内外的服务器插件全集。

下面将分别介绍下载、发布、边下边发布三个场景。

注意：对原理不感兴趣或熟悉的请直接跳转第 5 章节内容

2. 插件下载

代码库 eclipse-openvsx/download-extensions.js 中包含插件下载的所有逻辑，从 open-vsx.org API中获取 open-vsx.org 的所有插件列表，并使用多线程的方式，依次将插件的 vsix 文件（其中包含插件的所有内容）下载至指定文件夹中。

open-vsx.org 为外网网站，国内访问速度可能会慢很多，插件全集 API 获取地址可以改为 https://marketplace.smartide.cn。（直接改地址即可，其余API等均无需更改）
代码库下载后，npn install 完毕后使用 npm run download 命令即可启动下载进程。

3. 插件发布

代码库 eclipse-openvsx/publish-extensions.js 中包含插件发布的所有逻辑，从 open-vsx.org API 中获取 open-vsx.org 的所有插件列表，并使用多线程的方式，挨个将下载目录中已下载的插件 vsix文件（其中包含插件的所有内容) 发布至指定服务器。

发布逻辑包含插件比对算法，即在发布之前会先进行同命名空间同名称插件的版本比对，对比双方为本地vsix文件解析的信息和要发布至的服务器的插件信息，本地vsix文件的解析使用了微软的vsce库，服务器上插件的获取调用了marketplace API。
发布至服务器的 Registry URL 和 Publisher Token（生成方式见Marketplace 使用文档）均从环境变量传入，环境变量名称为：OVSX_REGISTRY_URL 和 OVSX_PAT。 注意：使用适当的账号创建的 OVSX_PAT，因为所有插件的发布者将会变成此PAT的创建者。
代码下载 npm install 完毕后，修改环境变了值，运行 npm run publish 即可开启发布进程。

4. 顺序同步

代码库 eclipse-openvsx/sync-extensions.js 综合了dowload和publish的功能，将全部下载后全部上传的逻辑合并成为边下载边上传的方式进行，实现方式依旧使用多线程进行 open-vsx.org API 插件全集中每个插件的下载并上传功能，适用于纯外网情况下的插件同步（https://marketplace.smartide.cn 即使用此方式）。

用户在使用时同样需要设置环境变量 OVSX_REGISTRY_URL 和 OVSX_PAT 来进行发布过程，代码下载并 npm install 完毕后，运行 npm run sync 即可开启同步进程。

5. SmartIDE Marketplace 同步插件

此章节内容描述如何使用 publish-extensions 程序和 github action 进行 https://marketplace.smartide.cn 生产环境的插件同步工作。

5.1 准备工作：

5.1.1 申请token

登陆 https://marketplace.smartide.cn
输入github登陆信息：
授权登陆：
登陆成功进入个人设置界面：
Access Token页面生成Token：
复制生成的Token：

5.1.2. 流水线Secret 更改

更改 SmartIDE/eclipse-openvsx 流水线 Secret: OVSX_REGISTRY_URL 和 OVSX_PAT 为正确的Server地址及Token值

5.2 运行流水线

进行插件同步的GitHub Action流水线为：Actions · SmartIDE/eclipse-openvsx (github.com)
默认的触发条件为提交代码至 smartide-marketplace 分支，修改如下path文件
运行流水线过程中，会使用Action的代理机进行同步插件，流水线步骤如下：
插件同步中：

5.3 检查同步结果

流水线运行时长根据同步的插件数量决定，整个时长可能会超过2个小时，等待同步运行结束后，可以调用 https://marketplace.smartide.cn 的 Swagger API 获取插件总数：
界面上可以根据分类或排序和关键字搜索对应插件：

3.3 - 将你的插件发布到SmartIDE插件市场

本文档描述如何发布插件到 SmartIDE Marketplace

SmartIDE Marketplace 允许用户上传自定制插件并进行下载使用，在插件上传之前需要用户登陆生成个人Token，并基于此 Token 使用 ovsx 工具进行命名空间的创建和插件上传操作。命名空间是插件的集合概念，插件不可脱离命名空间存在，因此需要先创建命名空间，或使用已有的命名空间再进行上传。

1. 登陆 SmartIDE Marketplace 生成 Token

打开 https://marketplace.smartide.cn 点击右上角头像使用github账号登陆：
输入github登陆信息：
授权登陆：
登陆成功进入个人设置界面：
Access Token页面生成Token：
复制生成的Token：

2. 使用 ovsx 工具创建命名空间

参照 Download and install node and npm 安装 node & npm 工具
安装 ovsx 工具
```
npm install --global ovsx
```
运行命令创建命名空间
```
ovsx create-namespace <name> -p <token> -r https://marketplace.smartide.cn
```
命名空间创建完毕后，创建者会默认变为命名空间的“贡献者”角色，如若想要变为命名空间的所有者，请提交 issue 进行申请。

3. 使用 ovsx 工具发布插件

ovsx 发布功能支持直接发布.vsix 文件或基于插件开发目录打包并发布
对于已经有 .vsix 插件文件的使用者，运行如下命令进行发布插件
```
 ovsx publish <file> -p <token> -r https://marketplace.smartide.cn
```

也可以进入插件开发根目录代码库中执行如下命令进行发布

 npm install | yarn
 ovsx publish -p <token> -r https://marketplace.smartide.cn

ovsx 工具内部调用 vsce 的功能工作，即运行定义于 packages.json中的 vscode:prepublish 脚本。如果插件代码使用 Yarn 运行脚本，可增加 –yarn 参数。

4. 验证发布效果

使用 ovsx 工具发布成功后，便可以在 https://marketplace.smartide.cn 站点中找到已发布的插件，也可以在 IDE 中安装使用，安装使用请参考配置连接手册。

3.4 - 插件安装手册

本文档描述如何使用SmartIDE Marketplace安装插件

1. 配置本地 IDE 的插件市场链接

参考配置连接手册配置 VSCode 及类 IDE的插件市场链接地址

2. 使用 IDE 扩展模块搜索并安装插件

搜索插件
安装使用

3.5 - 使用自签名证书进行插件市场私有化部署

本文档描述如何使用自签名证书进行的私有化部署

插件市场需要部署为HTTPS站点才能够被IDE顺利连通使用，在企业内外进行私有化部署的时候通常使用自签名证书来绑定HTTPS站点服务，本教程将对如何生成OpenSSL自签名证书和应用证书到插件市场站点进行详细描述。

1. 申请OpenSSL自签名证书

certs-maker 使用容器化的方式封装了OpenSSL繁杂的自签名证书生成过程，让使用者仅需要一条Docker指令即可快速生成证书：

docker run --rm -it -e CERT_DNS="domain.com" -v `pwd`/certs:/ssl soulteary/certs-maker

2. 将自签名证书配置到插件市场

参照 SmartIDE插件市场安装说明部署完毕插件市场服务之后，使用SFTP的方式替换 deployment/openvsx/nginx/ssl 目录下的证书：

名称改为 nginx.conf 中指定的名称 ssl_cert.crt 和 ssl_key.key：

ssl_certificate /ssl/ssl_cert.crt;
ssl_certificate_key /ssl/ssl_key.key;

使用SFTP方式上传证书到对应服务器目录
重启 nginx服务

3. 本机导入自签名根证书并设置信任

以 mac OS系统为例导入自签名证书并设置为信任

打开钥匙串拖动 crt 证书放到默认钥匙串“登录”中
设置该证书信任状态
浏览Marketplace网站查看是否可以正常访问

4. VSCode及类IDE连通插件市场验证

参考配置连接手册配置 VSCode 及类 IDE的插件市场链接地址
搜索插件
安装使用

4 - 项目适配

本文档主要描述：SmartIDE核心配置文件示例介绍，以及如何在一个已有项目上完成SmartIDE适配，并快速切换到SmartIDE开发模式。

SmartIDE通过一个yaml格式的配置文件识别代码库的开发环境，实现对开发环境的编排，通常这个文件放置在代码库根目录下的.ide目录中，默认的文件名为 .ide.yaml。

1. 配置文件示例

你可以参考 Boathouse Calculator 的示例代码了解这个文件的详细内容，SmartIDE产品团队使用这个Boathouse Calculator 代码库作为我们的冒烟测试应用。

Boathouse Calcualtor 代码库地址 : https://gitee.com/idcf-boat-house/boathouse-calculator

.ide 配置文件夹的位置如下：

典型的.ide.yaml文件内容如下，文件路径为：/.ide/.ide.yaml

version: smartide/v0.3
orchestrator:
  type: docker-compose
  version: 3
workspace:
  dev-container:
    service-name: boathouse-calculator
    
    ports: # 申明端口
      tools-webide-vscode: 6800
      tools-ssh: 6822
      apps-application: 3001
    
    ide-type: vscode  #vscode/theia
    volumes: 
      git-config: true
      ssh-key: true
    command:
      - npm config set registry https://registry.npmmirror.com
      - npm install
  services:
    boathouse-calculator:
      image: registry.cn-hangzhou.aliyuncs.com/smartide/smartide-node-v2-vscode:all-version
      restart: always
      environment:
        ROOT_PASSWORD: root123
        LOCAL_USER_PASSWORD: root123       
      volumes:
      - .:/home/project
      ports:
        - 3001:3001
        - 6822:22
        - 6800:3000
      networks:
        - smartide-network

  networks:
    smartide-network:
      external: true

以上文件关键配置说明：

Workspace : 工作区相关配置
- Dev-container: 工作区所使用的开发者容器配置
  - Service-name: 指定services中作为开发者容器的service名称
  - Ports: 对外暴露的端口列表，以及每个端口的说明，端口说明使用前缀方式标识端口的类型，当前支持以下前缀
    - Tools 工具类端口
    - Apps 应用类端口
  - Ide-type: 开发者容器内置的IDE类型，目标前有4个选项
    - Vscode - 内置基于OpenVSCode的WebIDE
    - Jb-projector - 内置基于JetBrians Projector的WebIDE，包括：IntelliJ IDEA, PyCharm, WebStorm, PHPStorm, CLion, GoLand等
    - Opensumi - 国内阿里开源的WebIDE
    - sdk-only - 无WebIDE，此类环境一般用于VSCode Remote或者JetBrains Gateway进行远程连接使用
  - Volumes: 向容器内注入的相关配置项
    - Git-cofnig - 注入当前用户的git config配置
    - Ssh-key - 注入当前用户的ssh密钥
  - Commands: 在开发者容器启动中自动执行的脚本，当前只支持vscode
- services：这个配置节点以下的内容就是一个标准的docker-compose文件内容
  - Image: 当前开发者容器所使用的镜像，请参考镜像和模版文档获取SmartIDE所支持的所有镜像地址

2. 适配已有项目

如果希望使用SmartIDE来开发调试已有项目，只需要将以上.ide.yaml配置放置在已有项目的根目录下的.ide目录中即可。

对于不同开发语言的环境，可以从 smartide-template（模版库）中获取对应的默认配置文件。

下图列出了SmartIDE模版库的结构，可以看到以开发语言命名的目录名称。在每个开发语言的目录中，都有一个 _default 的文件夹，这个文件的内容就是针对这个开发语言技术栈的默认SmartIDE配置文件，比如：下图列出了 java/_default 目录的内容。将这些文件复制到你的java项目的根目录中即可完成对你的java项目的适配，如果你的目录中已经存在.gitignore文件，请将以上.gitignore文件的内容合并到现有的文件中。

完成以上操作之后，即可使用标准的 smartide start 指令启动项目，同样也可以在 SmartIDE Server 中使用你的项目了，详见：快速开始 - SmartIDE Server。

5 - IDE远程连接

使用VSCode或者JetBrains远程开发模式连接SmartIDE工作区