文档

• 1: 概述
• 1.1: 什么是云原生IDE
• 1.2: 工作模式和使用场景
• 1.3: 开发语言和中间件支持
• 1.4: 产品架构
• 1.5: IDE支持
• 1.6: IDE配置文件
• 1.7: 远程工作区
• 1.8: SmartIDE插件市场
• 1.9: 开源协议
• 2: 开源工作体系
• 2.1: 如何选择拉取请求的不同合并方式
• 2.2: 如何清理Git历史记录中的敏感信息
• 3: 安装
• 3.1: CLI 安装说明
• 3.2: Server 部署手册
• 3.3: SmartIDE 插件市场安装说明
• 3.4: Docker 安装说明
• 3.4.1: Docker & Docker-Compose 安装手册 (Linux服务器)
• 3.4.2: Docker Desktop 安装手册 (MacOS)
• 3.4.3: Docker Desktop 安装手册 (Windows)
• 3.5: K8S环境初始化说明
• 4: 快速开始 - 开发从未如此简单
• 4.1: SmartIDE CLI 快速开始
• 4.2: SmartIDE Server 快速开始
• 4.3: Node 快速启动教程
• 4.4: .NET 快速启动教程
• 4.5: Java 快速启动教程
• 4.6: Jupyter Notebook 快速启动教程
• 5: 示例应用
• 5.1: Boathouse 计算器
• 5.2: 若依(RuoYi)项目
• 5.3: Gin-Vue-Admin
• 6: 镜像和模版
• 7: 操作手册
• 7.1: CLI
• 7.2: Server
• 7.3: SmartIDE插件市场操作手册
• 7.3.1: 配置IDE使用SmartIDE插件市场
• 7.3.2: 配置自动插件同步机制
• 7.3.3: 将你的插件发布到SmartIDE插件市场
• 7.3.4: 插件安装手册
• 7.3.5: 使用自签名证书进行插件市场私有化部署
• 7.4: 项目适配
• 7.5: IDE远程连接

1 - 概述

SmartIDE是一款 远程/云端工作区调度工具，其 核心价值是从根源上解决软件环境问题。当前，SmartIDE主要采用容器技术，比如：Docker和Docker-Compose；以及容器集群编排技术，比如：Kubernetes，来解决软件运行环境的一致性，标准化，快速获取，可扩张性和可维护性问题。

SmartIDE对IDE的边界重新进行了定义，我们认为任何当前应用所需要的代码编辑器，运行时，SDK，中间件，应用服务器，配置以及底层操作系统均属于我们所定义的IDE的一部分。与传统的IDE工具的不同之处主要在于E（Environment 环境）。开发者常用的Visual Studio, Visual Studio Code, JetBrains全系列以及Eclipse这些传统的IDE工具在 I (Integrated 集成性)和 D（Development）上面做的都非常出色，但是它们都没有为开发者彻底解决E的问题。这是因为在这些IDE产品出现的时候，软件本身的依赖环境还没有那么复杂，大多数的软件都是单体，微服务架构还未出现，通用中间件软件也不流行，大多数的开发者都可以在自己本地的开发机上完整整个应用（系统）的完整搭建，开发调试，测试以及打包发布过程。

当前的软件系统已经越来越复杂，越来越多的开发者在使用各种中间件来简化自己的软件开发过程，越来越多的团队在引入微服务架构来适应业务架构的敏捷性需求，云原生技术正在被更多团队接受，容器化和集群编排系统以及DevOps CI/CD流水线的引入也给软件工程引入了更多的复杂度。在这样的背景下，传统IDE产品的局限性日渐显现，开发者不得学习更多的技术，引入更多的工具，花费的更多的时间在软件环境的管理和维护上。在软件工程领域种，也出现了类似SRE这种专注于打通复杂软件工程系统协同的专业化工作角色/职责，软件环境在SRE的工作职责种占有非常高的比重（参考：Google SRE。即便如此，软件环境问题仍然是企业改进软件工程系统过程种最难解决的核心问题之一。 （参考：8 Key Challenges in Adopting DevOps)。对于希望通过改进软件工程工艺来提升研发效能的团队来说，解决环境的可获取能力是实现端到端持续交付能力的主要障碍。

也因为以上原因，IT行业内开始涌现了Docker, Kubernetes, Hashicrop等专注于解决软件环境问题的基础工具类软件。从2013年Docker引领的容器化浪潮开始，软件交付方式已经有了翻天覆地的变化，而且这种变化在逐步从生产环境向开发测试环境推进。这个趋势的核心实践，Infrastructure as Code（IaC 基础设施即代码）的思路正在影响着越来越多的DevOps实践者和工具厂商。可以说，在容器化浪潮的背后其实是IaC实践广泛应用，也因为此IaC实践被大多数DevOps实践者作为判断一个组织的软件工程能力的重要评估标准。

如下图所示：IaC实践（工具）正在从生产环境逐步左移

IaC实践左移实际上是从问题的表象逐渐触达实质的过程。容器化/IaC实践首先被用于生产环境的原因很容易理解，因为这个环境最贴近用户，最贴近业务，也是企业最愿意投入资金的部分；但随着生产环境的容器化进程推进，组织会逐步认识到生产环境的问题的根源其实并不在生产环境，而在其左侧的测试，流水线以及开发环境。开发环境作为产生环境的源头，如果不能被容器化，会对其下游（右侧）环境构成连锁问题效应，破坏容器化本应产生的效益，比如：为管理容器编排文件而专门设置的权限、人员角色和流程，因为开发人员引入的环境变更而引起的后续环境的连锁变更；运维人员为了防止以上问题影响系统稳定性而采取的保守管理策略，以及受到损伤的业务敏捷性。

应该说，在容器化进程发展到今天的将近10年以后，开发环境的非标准化已经成为阻碍整个持续交付体系效能提升的关键性障碍。同时，随着企业中的容器化平台（包括：各种类型的k8s以及很多企业习惯称之为PaaS的私有云平台）以及DevOps工具链的普及，已经为IDE上云提供了必要条件。

从传统IDE工具的演进来看，以 Visual Studio Code Remote 以及 JetBrains Gateway 为代表的远程开发能力已经被越来越多的开发者接受并喜爱；同时也出现了类似 Squash, telepresence, Nocalhost ，Bridge to Kubernetes (Visual Studio 插件 和 Visual Studio Code 插件) 这样专注于解决K8S环境下调试场景的特定工具（参考：[Debugging Microservices: The Ultimate Guide](https://lightrun.com/debugging/debugging-microservices-the-ultimate-guide/）。这些都代表着传统IDE工具的云化进程。

SmartIDE 定位于远程/云端工作区的调度，为传统IDE上云提供服务端的完整解决方案，依托于已经在大量企业普及的容器云和DevOps平台，为开发者提供更加安全，简单和高效的全新工作模式。最终实现在 探索阶段 就能确认软件的最终形态的目的，为后续的环节提供明确的状态基准。

1.1 - 什么是云原生IDE

SmartIDE CLI可以在 Windows/MacOS/Linux 三种操作系统上运行，并且支持x86/ARM两种CPU架构。因此无论开发者所使用的开发机使用了怎样的操作系统，均可以正常安装和使用CLI来完成工作区的管理。

很多人会觉得一个云原生IDE产品为什么要做跨平台支持，其实这个和我们对云原生的理解有关。我们认为云原生不能被简单的理解为使用k8s，而是要用利用云的能力让用户的工作和生活变得更加简单。对云原生IDE而言，这意味着它应该可以以云应用的特性（自助化、按需使用、可扩展和弹性）在任何地点运行，云应该无处不在。

相对于大众普遍理解的CloudIDE，SmartIDE希望可以在任何贴近应用最终运行环境的地方让开发者进行开发和调试，这意味着：

• 如果开发者希望使用自己的本地开发机作为自己的开发环境，那么开发者应该可以使用SmartIDE做到
• 如果开发者希望使用一台主机（本地、数据中心、私有云或者公有云）作为自己的开发环境，那么开发者应该可以使用SmartIDE做到
• 如果开发者希望使用Kubernetes作为自己的开发环境，那么开发者应该可以使用SmartIDE做到
• 如果开发者希望使用一台运行着ARM芯片的硬件作为自己的开发环境，那么开发者应该可以使用SmartIDE做到
• 如果开发者希望使用XXX作为自己的开发环境，那么开发者应该可以使用SmartIDE做到
• 在任何以上环境中进行编码开发，开发者应该有一致的体验和开发效率 因此，SmartIDE并不是一个单纯的CloudIDE产品，我们将其定位于云原生IDE。

1.2 - 工作模式和使用场景

SmartIDE支持3种模式，分别为本地模式，远程模式和k8s模式。

本地模式 支持开发者在本地开发机上使用 smartide start 指令启动工作区，这种模式主要现象个人开发者独立使用。开发者无需关心所启动环境所需要的开发语言，SmartIDE将确保环境的标准化和一致性。

远程主机模式 支持开发者通过增加 –host 参数将工作区部署到任意远程主机上，无论这台主机在什么地点运行，开发者都可以一键完成开发环境的部署并将使用远程主机来完成代码编译，打包，运行和测试过程。

k8s模式 支持开发者增加 –k8s 参数将工作区部署到任意k8s集群中，利用k8s所提供的调度能力，可扩展性和弹性，可以提供支持更加复杂的开发环境调度场景。

使用场景

虽然SmartIDE理论上可以支持任何应用的开发场景，但对于以下这些类型的应用来说可以提供比传统开发模式更好的体验。

• 代码安全管控： 对于非常关注代码安全性或者使用大量外包人员的组织来说，如何防止代码离开自己受控的服务器环境，同时又可以让开发者方便的完成代码开发一直都是一个矛盾。很多资金充裕的企业已经在使用的虚拟桌面（VDI）解决方案就是针对这种场景，但是VDI系统价格昂贵，资源占用量大而且无法动态调度资源，这也造成很多企业给开发者提供的虚拟桌面配置很低，开发效率非常低。SmartIDE所采用的容器化方案可以做到动态资源调度，根据项目本身的特性控制资源使用，同时开发者可以只需要浏览器即可访问这些资源。对于企业优化IT基础设置资源利用率，提升开发者体验和工作效率非常有帮助。

• 大数据和AI开发： 这些开发场景因为需要更强的算力并处理大量的数据，因此通过远程开发方式可以让开发者更好的利用云端资源更加便捷高效的完成开发。

• 微服务架构开发： 当系统中所设计的微服务数量到达一定量级之后，开发者无法在本地开发环境运行完整系统，利用SmartIDE所提供的远程工作区则可以利用云端的大量服务器资源轻松完成环境搭建。同时因为IDE工具与运行环境可以非常贴近，在开发调试过程中也可以避免因为网络延迟而造成的各种问题。

• 实验室/培训环境： 教育/培训行业往往休要同时提供多种不同的开发语言，工具的环境以便适应不同类型的课程的需要，但是因为课程本身的时效性问题，这些环境并不需要一直运行，而只需要在学员需要的时候启动，课程结束之后即可销毁。采用SmartIDE工作区可以非常便捷的快速为新课程配置环境，随用随起，用完即焚。

• 工业软件/硬件开发： 工业软件和硬件开发往往需要在特定硬件环境中才能进行调试和测试工作，传统模式下IDE是无法运行在这些硬件上的，开发者需要通过开发同步工具，命令行调试工具才能完成日常开发调试工作。这个过程往往非常繁琐，大幅降低了开发效率。SmartIDE所采用的集成了IDE工具的工作区可以很方便的部署到这些硬件环境中，让开发者直接在这些硬件上进行开发调试，大幅提升日常工作效率。

1.3 - 开发语言和中间件支持

SmartIDE中的开发语言支持只可扩展，可插拔的。通过IDE配置文件，开发者镜像和模板的配合，开发者可以将任何可以在容器中运行的开发语言SDK与SmartIDE进行适配，整个适配过程无需修改SmartIDE本身的代码逻辑。当前我们已经提供的开发语言支持包括：

• JavaScript/Node
• Java
• C# (跨平台版本，包括：.net core 和 .net 6以上，暂时不支持.net framework)
• Python
• Golang
• PHP
• C/C++
• Anacoda (Juypter Notebook)

对于各种类型的中间件的支持方式也是一样的，任何剋有在容器中运行的中间件均可以适配到SmartIDE工作区中使用。当前我们已经提供支持的中间件以及配套工具包括

• MySQL + PHPMyAdmin
• Redis
• Nacos

1.4 - 产品架构

SmartIDE 由4个组件组成，分别是CLI, Server，开发者镜像和模板，插件市场。

组件说明

CLI 是所有组件的核心，SmartIDE的远程/云端工作区能力全部都封装在这个大小只有50M左右的命令行工具中。可以说，这个小小的命令行工具的能力等同于一个CloudIDE系统（比如：Github Codespaces, AWS Cloud 9, 腾讯Code Studio等等），任何人都可以安装这个CLI工具并在自己选择的硬件/虚拟机/k8s上自助部署属于自己的CloudIDE系统。CLI的功能非常单纯，它只负责一件事情，就是按照 IDE配置文件（.ide.yaml）文件 的描述，完成对远程/云端工作区的生命周期管理。

Server 是在CLI的基础上提供的WebUI访问方式，为用户提供更加友好的交互方式以及承载企业级特性的平台。Server本身不会直接维护远程/云端工作区的状态，所有针对工作区的操作全部通过CLI完成。

开发者镜像 & 模板 是交付标准化环境的载体，通过提供预制的Docker镜像和环境模板，SmartIDE可以在无需修改系统代码的前提下适配各种不同类型的环境，包括：IDE工具，开发语言和SDK，应用依赖的中中间件，应用服务器以及专属工具等等。开发者镜像和模板支持用户自定义，用户可以自由的使用自有的镜像以及模板库来支持高度定制化的场景。

插件市场 是为IDE工具（当前只支持类VSCode IDE，未来也会支持JetBrains系列）提供的插件集中管理能力。

私有部署优先

SmartIDE 的设计目标是企业用户，因此我们优先支持私有部署，以上所有组件均可以在公网或者私有隔离网络中进行部署，为企业用户提供完整闭环的云端IDE解决方案。

CLI设计目标

全功能独立工作

CLI是SmartIDE产品架构中与其他类似产品最大的差异。大多数CloudIDE都会提供CLI工具，但是这些CLI都是作为辅助性工具存在的，也就是说用户使用CLI连接到CloudIDE服务来完成类似端口转发，如果脱离的CloudIDE服务，这些CLI本身是无法单独使用的。 SmartIDE的CLI则不同，用户可以使用CLI直接创建、停止，删除，清理远程/云端工作，这个过程无需CloudIDE服务（SmartIDE Server）的存在。 这样设计的目的是为了方便个人开发者可以非常轻量的管理自己的远程/云端工作区，无需预先部署Server。这样，个人开发者可以在需要的时候使用一个 smartide start 指令即可在任何资源上启动远程/云端工作。

快速迭代

从开发和调试的角度来说，CLI工具的迭代速度是带有WebUI或者API类型的应用无法比拟的。因为CLI极度简单的操作方式，我们无需处理界面的布局，美观，操作体验，各种边界条件等问题，可以专注于业务目标的实现。这种快速迭代能力让我们可以更早的触达用户，验证产品核心功能并及时调整产品方向。在过去的6个月，CLI的发布速度是平均每天3.8个版本。

可集成性

CLI封装了管理远程/云端工作区的所有能力，这让用户利用CLI来搭建自己的CloudIDE系统，实际上SmartIDE Sever 本身就是这样工作的，通过将 CLI 打包成 tekton流水线任务，SmartIDE Server 的所有工作区操作都不会直接调用虚拟机或者k8s集群，而是通过CLI来完成。借助CLI的快速迭代特性，我们的Sever开发人员可以更加专注于用户体验和企业级功能，而不用关心底层工作区调度问题。

对于希望构建企业内部CloudIDE平台的组织来说，利用CLI的这种可集成特性，可以非常快速底层本的完整平台的搭建，不用去关注与虚拟机以及k8s集群进行操作的细节问题。 我们当前已经提供了gitlab-ci的集成示例，未来我们会提供更多各种类型的DevOps系统场景。

• Issue: gilab ci extension

1.5 - IDE支持

作为工作区（远程/云端）与用户之间的交互方式（Interface），IDE工具是开发者的入口。为了能够让开发者使用自己喜欢的IDE工具，SmartIDE可以引入任何能够提供WebUI的工具作为IDE入口，从实现上来看，实际上就是一个WebApp而已。

当前，SmartIDE支持4种IDE接入方式，分别是

• WebIDE：任何可以提供WebUI的协助开发者进行软件开发的工具均被被认为是IDE的组件，比如
  • VSCode WebIDE：我们内置提供了基于OpenVSCode Server的WebIDE支持
  • JetBrains Projectors：Projectors是JetBrains提供的全系列IDE的WebUI版本，可以通过浏览器访问呢，界面和功能上和JetBrains的桌面IDE保持一致。当前我们内置提供了以下Projectors支持（根据不同的开发语言）。
    • IntelliJ IDEA
    • WebStorm
    • Goland
    • PyCharm
    • Rider
    • PHPStorm
    • Clion
  • OpenSumi：阿里蚂蚁开源的WebIDE开发框架
  • Eclipse Theia: Eclipse基金会旗下的开源WebIDE开发框架（有限支持）
• SSH Remote 接入：开发者可以通过SSH协议，使用本地的终端程序，VSCode Remote SSH插件，JetBrains Gateway或者任何支持SSH远程接入的工具连接到SmartIDE工作区进行操作。
• Web Terminal 接入：SmartIDE工作区提供 webterminal addon，可以在现有工作区上提供浏览器内访问的终端程序，并允许用户进入工作区内的任何容器进行操作。使用Web Terminal不需要工作区对外暴露SSH端口。
• 其他Web应用：开发者在工作中还需要各种类型的第三方工具来管理工作区种的各类资源，比如：如果工作区内使用了MySQL作为后天数据库，那么开发会希望使用PHPMyAdmin来通过浏览器管理数据库，协助完成日常开发调试。类似的场景均可以通过SmartIDE的IDE配置文件实现。当前已经支持的其他Web应用工具包括：
  • PHPMyAdmin
  • Nacos
  • Juypter Notebook

1.6 - IDE配置文件

IDE配置文件是SmartIDE的真正内核，无论是CLI, Server，开发者镜像和模板都是围绕IDE配置文件的规范进行实现的。IDE配置文件的设计灵感来自：如何让README文件活起来（参考：博客README.exe）。作为开发者，拿到一个新的代码库的时候一般都会先去看README文件，通过这个文件可以知道这套代码所需要安装的环境，工具和操作方式。但是README只能由人来阅读理解只有手工操作，这就引入了大量的不确定性，造成了很多开发者在搭建环境上浪费了太多时间。在开发过程中我们也经常会对环境进行变更而忘记更新README，这就会造成其他开发者的困扰以及后续持续交付流程的不稳定。

为了解决这个问题，我们设计了一个 IDE配置文件 (默认文件名 .ide.yaml）文件格式。这个文件中完整描述了运行当前代码所需要的环境配置，包括 基础环境SDK，应用服务器，应用端口，配置文件，网络依赖以及所使用的IDE工具。有了这个文件，开发者就可以真正实现一键启动开发调试，而不会再听到：“在我这里工作呀，是你的环境问题！” 这种骇人听闻的抱怨。

以下是一个典型的IDE配置文件的示例：

示例来源：https://gitee.com/idcf-boat-house/boathouse-calculator/blob/master/.ide/.ide.yaml

version: smartide/v0.3
orchestrator:
  type: allinone
  version: 3
workspace:
  dev-container:
    service-name: boathouse-calculator-dev
 
    ports: # 申明端口
      tools-webide-vscode: 6800
      tools-ssh: 6822
      apps-application: 3001
    
    ide-type: vscode  #vscode/jb-projector/theia/opensumi
    volumes: 
      git-config: true
      ssh-key: true
    command:
      - npm config set registry https://registry.npmmirror.com
      - npm install

  kube-deploy-files: "k8s-deployment.yaml" 
  docker-compose-file: "docker-compose.yaml"

这个文件内容非常通俗易懂，是个程序员应该都能看明白，不过我还是简单说明一下：

• orchestrator - 环境调度工具设置，用来制定调度容器环境的底层工具，我们当前支持3种调度方式
  • allinone：同时提供docker-compose和k8s mainfest，可以同时支持本地，远程主机和k8s模式
  • docker-compose: 仅使用Docker Compose进行调度，只适用于本地和远程主机模式
  • k8s: 仅使用k8s进行调度，只适用于k8s模式
• workspace - 工作区配置，工作区 是SmartIDE中最重要的概念，包含开发者用来进行开发调试的所有环境信息
  • dev-container - 开发者容器设置
    • service-name - 开发者容器所对应的 docker-compose 服务名称
    • ports - 开发者容器对外暴露的端口
    • ide-type - 开发者容器所所用的IDE类型，支持：vscode, sdk-only, jb-projector (Jetbrains系列全家桶）和 opensumi
    • volumes - 配置映射，支持将开发者的git-config和ssh密钥导入容器
    • commands - 开发环境启动脚本，对环境进行初始化；比如以上脚本中就完成了2个关键操作：1）设置npm国内镜像源 2）获取npm依赖。这部分脚本开发者可以根据自己代码库的情况设置，SmartIDE会在环境启动后自动运行这些脚本，让程序处于开发者所希望的状态上。
• kube-deploy-files：k8s模式所使用的k8s manifest文件路径，支持目录或者单一文件
• docker-compose-file: 本地和远程主机模式所使用的docker-compose文件路径

以上所使用的docker-compose和k8s manifest兼容业界标准的文件格式，开发者可以直接链接现有的编排文件。

IDE as Code

这种做法称为 IDE as Code 也就是 “集成开发环境即代码”，将你的开发环境配置变成一个 IDE配置文件 的配置文件放置在代码库中，然后根据这个配置文件生成对应的自动化脚本，完成“集成开发环境” 的创建。

IDE as Code 的做法源自DevOps的核心实践 Infrastructure as Code ，也就是 “基础设施即代码” 简称 IaC。其核心思想是将环境配置代码化，常见的k8s的yaml文件其实就是典型的基础设施即代码实现。在运维领域常用的工具比如chef/puppet/ansible，还有 HashiCorp 的 Terraform 也都是 IaC 的经典实现。IaC 的主要价值和目标就是将环境搭建过程标准化，让任何人在任何环境中都可以获得 一致、稳定、可靠 的环境搭建体验。SmartIDE所创造的 IDE配置文件 延续IaC了的使用场景，并将其基本思路应用到了开发测试环境中，这其实就是 SmartIDE 的产品核心能力。

基于 IDE as Code 的实现，SmartIDE在产品实现过程中一直秉承一个原则：能够让用户通过配置文件实现的东西，就不要通过代码实现。这个核心原则给予了SmartIDE非常强的灵活性，比如以下这段视频中所演示的 若依管理系统 项目。

描述性配置

描述性配置是IaC的核心原则，用户只需要告诉IaC系统目标是什么，而不用关心如何实现。在现代软件系统环境越来越复杂的背景下，如果开发者为了完整应用的开发还需要去学习容器，网络，集群编排，存储，安全配置等等内容是不现实的。因此SmartIDE将这些复杂度全部封装在CLI中，将那些用户需要控制的变量通过IDE配置文件交给用户管理，这样就可以让开发者享受云原生技术带来的好处而不必关心背后的复杂度。

IDE配置文件的解析工作全部通过CLI完成，作为外围界面的Sever无需了解IDE配置文件的结构和工作方式。CLI为最终用户提供了使用IDE配置文件的能力，Sever本身也只是一种“用户”类型。

开发者镜像和模板需要符合IDE配置文件的约定，确保这些镜像和模板可以被CLI调度。

1.7 - 远程工作区

远程工作区(Remote Workspace)是SmartIDE中的核心概念，远程工作区为开发人员提供某个应用开发所需要的完整组件，一般来说会包括：代码库、代码编辑器、开发语言SDK、开发调试工具、测试工具、依赖环境/中间件以及管理工具。SmartIDE使用一个叫做 .ide.yaml 的文件对这些组件进行描述，并通过容器的方式标准化这些组件的获取过程，达到简化开发环境管理的目标。

为什么一定要是 “远程”

远程工作区强调的是工作区与所在环境是隔离的（采用容器技术），开发者与工作区之间的互动是通过远程方式（api, 浏览器，ssh等方式）。远程工作区也可以运行在开发者的本地开发机上，只是工作区内的资源与开发者的机器上的其他资源一直保持隔离状态。更常见的场景是运行在远程主机或者k8s环境中。这样做的目的是为了能够将工作区的资源标准化和统一，并且允许在不同的工作区之间进行 工作区漫游。

工作区漫游

所谓漫游，就是允许开发者在不同的环境之间随意的迁移自己的工作上下文，而且在迁移过程中保持工作不中断。SmartIDE 的远程工作区采用了 IDE as Code 技术，所有工作区相关的内容都可以通过 3个标准化对象 完整保存和移动：

• 开发者镜像：提供远程工作区的标准化环境基础，包括：底层库、开发语言SDK和工具、IDE工具和其他配套工具；
• 代码库：提供当前项目的代码；
• 持久化数据集：开发者对环境的修改，临时配置变更和中间状态。

经过以上抽象，我们可以通过 IDE配置文件 将这3个标准化对象链接到一起，形成一个 远程工作区 的完整数据对象。SmartIDE 的所有工具处理逻辑都是围绕这3个标准化对象展开的。

有关 IDE as Code 的概念解释请参考以下文档和博客：

• README.exe

localhost访问

SmartIDE远程工作区集成了 SSH隧道 技术，无论你采用那种以下哪种方式启动远程工作区，SmartIDE CLI都会自动帮助你建立起本地开发机和远程工作区资源之间的隧道，并将远程工作区内部资源的端口转发到 localhost 上，这样你就可以完全通过 localhost:<port> 来访问这些资源，而不用关心这些资源具体运行在本地、远程主机或者k8s集群中。

这样做的另外一个好处是，如果你已经习惯了使用一些开发环境管理工具，比如：MySQL Workbench来连接你的MySQL服务器，那么对于SmartIDE远程工作区种的MySQL服务器就可以直接通过 localhost:3306 来访问；这种体验和MySQL服务器就运行在你本地开发机上完全一致，但是又不会占用你的本地资源。

使用 SSH隧道 技术的另外一项优势是：避免了在远程服务器环境（linux主机或者k8s集群）上对外暴露端口，因为所有的转发都通过 SSH隧道 完成，因此远程服务器资源只需要提供最基本的访问方式，而不必另外打通防火墙或者进行额外的网络配置。

一般来说SmartIDE远程工作区都提供WebIDE和SSH终端方式，那么你就可以通过

• http://localhost:6800 访问WebIDE （6800是SmartIDE内集成的WebIDE的惯用端口号）
• ssh smartide@localhost -p 6822 访问远程工作区的终端 (6822是SmartIDE远程工作区内置的SSH服务的惯用端口号)

注意： 为了避免因为端口占用造成端口转发失败，SmartIDE CLI会自动检测当前端口被占用的情况，并自动将端口值增加100以便避免冲突。

四类远程工作区

SmartIDE的远程工作区可以通过以下4种方式启动，覆盖开发者所需要的所有使用场景：

• 本地远程工作区：远程工作区运行在开发者自己的开发机上，开发机可以是Windows, MacOS或者是Linux均可。
• 主机远程工作区：远程工作区运行在linux主机上，这台linux主机可以运行在任何位置（本地虚拟机、局域网中或者云端），只要开发者可以通过SSH访问这台主机即可。
• k8s远程远程工作区：远程工作区运行在k8s集群中，一般来说一个远程工作区就是一个pod。
• server远程工作区：开发者在SmartIDE Server的网页上启动的远程工作区，可以以远程模式或者k8s模式运行。严格来说，Server模式并不是一个独立的模式，而是远程模式和k8s模式的另外一种操作方式。

本地远程工作区

本地远程工作区完全运行在开发者自己的开发机上面，但是采用容器的方式运行。开发者可以使用Windows，MacOS或者Linux三种操作系统中的任何一种运行本地远程工作区，唯一的前提条件是已经安装了 Docker桌面版 工具，具体的安装方式请参考我们的 安装 文档。

启动本地远程工作区的cli指令非常简单，只需要运行以下一个指令即可：

smartide start <代码库Url>

主机远程工作区

远程主机远程工作区运行在linux主机上，同样采用容器的方式运行。这台linux主机可以运行在任意位置，包括：本地虚拟机(VirutalBox/VMWare/HyperV)，本地网络上的服务器或者云服务器；唯一的要求是开发者可以通过SSH直接登录这台主机。

启动远程主机远程工作区并不需要开发者在远程主机上安装 SmartIDE CLI 工具，开发者只需要按照我们的 安装 文档对linux主机进行初始化以后，即可在本地开发机上使用 SmartIDE CLI 工具远程操作这台linux主机。在这种场景下，开发者本地的开发机也不需要安装 Docker桌面版 。

启动远程主机远程工作区的cli指令也非常简单：

## 添加远程主机到SmartIDE主机资源列表
smartide host add <远程主机的IP地址> --username <SSH登录用户名> --password <SSH密码/如果使用key的方式认证则不需要输入>
## 获取SmartIDE主机资源列表
smartide host list
## 通过<主机ID>在远程主机上启动项目
smartide start --host <主机ID> <代码库Url>

k8s远程工作区

k8s远程工作区运行在k8s集群中，采用容器的方式运行。开发者需要首先获取k8s集群的操作密钥并且在本地安装好Kubectl工具，接可以通过 SmartIDE CLI 工具在k8s其中启动远程工作区。在这种情况下，开发者本地的开发机也不需要安装 Docker桌面版 。

## 在K8s集群上启动项目
smartide start --k8s <实例名称> --namespace <命令空间名称> <代码库Url>

Server远程工作区

SmartIDE Server为用户管理远程工作区提供可视化的网页操作，但是Server远程工作区本质上仍然是运行在远程linux主机上的工作区或者运行在k8s集群中的工作区。SmartIDE Server允许用户讲自己的linux主机或者k8s集群注册到资源列表，并通过 远程工作区管理 页面创建server远程工作区。

在用户使用Server远程工作区的过程中，需要使用SmartIDE CLI执行 smartide connect 指令允许cli监听正在运行的Server远程工作区列表并建立 SSH隧道 以便用户可以继续使用 localhost:port 的方式访问远程工作区资源。

对于运行在k8s中的工作区，SmartIDE Sever会自动创建Ingress 3级域名映射，为每个工作区（及其资源）提供访问通道，同时可以提供基于SSH协议的远程终端访问能力。

1.8 - SmartIDE插件市场

SmartIDE插件市场是基于 Eclipse OpenVSX server 开源项目的一个fork，我们针对中国开发者的使用习惯和网络状况对这个开源项目进行了本地化，包括：界面的中文翻译处理和将插件同步到中国大陆的地址上供开发者下载使用。同时，对于无法直接使用微软官方marketplace的类VSCode IDE来说，比如：Codium, Code Server 和 OpenVSCode Server这些VSCode fork，可以使用SmartIDE 插件市场作为自己的插件市场，方便这些工具的使用者获取与VSCode类似的插件安装体验。

现今非常多的企业开发者在使用VSCode作为自己的主力IDE工具，但是由于很多企业对开发者连接互联网有严格的限制，大多数企业开发者都在采用离线安装的方式来获取VSCode的插件，这样做不仅操作繁琐，而且没有办法及时获取插件的更新，同时也会对企业的研发管理带来直接的安全隐患。

SmartIDE 插件市场 的目标并不是替代微软的Marketplace或者 Eclipse 的 open-vsx.org 而是希望为国内的开发者以及企业内部的开发者提供一种安全可靠，而且高效的插件管理机制。

SmartIDE 插件市场 与 Eclipse OpenVSX 一样是开源项目，并且我们提供了国内Gitee的开源库地址与Github保持同步，开源库地址如下：

• Github
• Gitee

相关文档和常见问题如下：

• 部署手册
• 操作手册
  • 配置连接 ：如何更新Visual Studio Code以及兼容IDE的配置文件连接到SmartIDE 插件市场，包括：VSCode, Codium, Code Server, OpenVSCode Server和OpenSumi
  • 插件安装：如何使用SmartIDE 插件市场安装插件
  • 插件同步：SmartIDE 插件市场 插件初始化同步机制
  • 插件发布：如何发布插件到 SmartIDE 插件市场
• 私有化部署

技术架构

SmartIDE插件市场各模块整体架构如下图所示

• 主体为OpenVSX-Server，spring boot框架的java服务，我们在部署时需要自行添加 application.yml 配置文件，并将其放置对应位置，以便Server启动后加载。
• 后台数据库使用PostgreSql，并使用Pgadmin进行数据库的管理和查询等操作，数据库的创建和表结构的初始化过程Server进程启动时会自动执行。
• 前端界面为NodeJS架构的Web UI，我们在部署时会将前端代码库构建的静态网站结果放入Server服务的对应文件夹，使其二者变为一个进程即Server进程加入前端界面。这也是Sprint Boot框架的灵活性功能，使用者可以基于Web UI代码库自定制前端界面，并将自定制的前端页面嵌入Server服务。
• 用户登陆验证，目前只支持OAuth Provider，官方文档中声明目前只支持Github AuthApp和 Eclipse OAuth，我们在部署时使用Github AuthApp。
• 插件存储可以使用数据库（默认）、Google Storage或 Azure Blob Storage三种模式，推荐添加Google Storage或 Azure Blob Storage以避免数据库过大的情况出现。
• 插件搜索服务支持数据库搜索和附加Elastic Search服务两种模式，推荐有条件的情况下添加Elastic Search搜索服务提高搜索效率，降低数据库压力。

1.9 - 开源协议

SmartIDE已经加入开放原子基金会，由基金会和LEANSOFT一同运营。欢迎社区的小伙伴参与项目的开发和共建。

SmartIDE的所有组件均采用开源的方式提供给个人，团队和企业使用；不同的组件采用了不同的开源协议。

• CLI 采用GPL 3.0开源协议
• Server 采用Apache 2.0 开源协议
• 开发者镜像 & 模板 采用 GPL 3.0开源协议
• 插件市场 采用EPL开源协议，是Eclipse OpenVSX Server的一个Fork

2 - 开源工作体系

作为一款面向开发者和开发团队的工具类产品，开源是SmartIDE选择为开发者提供最佳使用体验的方式，我们希望通过开源触达更多的开发者，也希望有更多的开发者加入SmartIDE的社区贡献者队伍，为我们自己打造一款爱不释手的工具。

目标

虽然从用户的角度来说，SmartIDE力求做到小而美（主要针对面向个人开发者的CLI而言），但其实这个小巧的工具背后其实是一套庞大的系统；另外，SmartIDE作为一款同时面向企业级市场的商用产品，我们还需要在开源的基础上提供企业级的扩展能力，因此采用完全在GitHub的开源库上进行所有的开发工作无法满足我们的所有要求。以下总结了SmartIDE开源工作体系的目标，供大家参考。

• 允许产品团队和社区贡献者并行工作，互不干扰的同时又可以流畅的实现代码合并；同时尽量保留足够多的历史记录。
• 允许产品团队使用专业化的产品设计和项目管理工具（Scrum & Kanban）实现高效的开发迭代；允许社区贡献者采用相对轻量的项目管理工具（Issues）实现足够的过程跟踪和协作。
• 允许产品团队使用专业化的CI/CD流水线工具实现全流程的自动化支撑，开发人员无需关心编码和测试之外所有可以自动化的工作流程，比如：代码编译构建（跨平台和多架构，SmartIDE支持三种操作系统Windows/MacOS/Linux和2种CPU架构AMD和ARM），自动化测试执行和反馈，代码扫描（包括安全和敏感信息），二进制包打包和发布，容器镜像打包和推送（国内+海外），统一的版本标签嵌入以及中英文双语等等。

受众

你可以从本文档获取的价值包括：

• 内部开发者：应该以本文档作为日常开发中需要遵照的流程范例，并随时根据情况提出对本文的改进意见。
• 外部开发者：了解这个流程对于社区开发者与我们互动，并且在过程中更加高效的协作会有所帮助。
• 其他：开源已经时当今构建软件一种主流方式，对于需要将开源集成到企业内部开发流程的团队来说，本文档可以作为范例使用。

工具选择和定位

为了达到以上3点目标，我们所选用的工具平台包括：

• Azure DevOps：作为已经持续迭代了17年的DevOps工具平台，微软的Azure DevOps是现在市场上同类产品中最优秀的工具。LEANSOFT团队最为中国以及整个亚太地区最熟悉这个产品的DevOps顾问实施团队几乎包揽了微软中国在过去10年所有的Azure DevOps实施落地项目。因此选择Azure DevOps作为我们的产品组内部工具是毫无疑问的。在 SmartIDE 这个产品上，我们使用 Azure DevOps 内置的电子看板作为日常项目管理跟踪工具，所有的产品特性和任务全部通过电子看板统一管理，支撑Scrum&Kanban过程；同时，我们使用Azure DevOps内置的Git代码仓库作为SmartIDE的内部代码托管，并利用分支策略将Git仓库与Azure DevOps内置的流水线进行集成，实现在不同级别的分支进行代码归并的过程中的代码质量控制以及所有的自动化操作。

下图展示了我们当前的看板

下图展示我们我们某条流水线在过去14天的统计数据

• 飞书：作为国内最优秀的企业级协同工具，飞书为SmartIDE提供了丰富灵活的协作方式。SmartIDE的产品创意、特性设计、技术调研、详细设计以及产品文档（包括本文）都是在飞书文档上完成。我们同时还使用飞书的即时通讯和在线会议完成日常的沟通和协作，SmartIDE的所有团队成员全部采用远程工作模式，并且分布在北京，青岛，广州，长沙等多个城市，我们日常Scrum会议，沟通和问题定位全部都通过飞书会议远程完成。

下图展示我们在飞书中的SmartIDE知识库wiki：

• GitHub：作为全球最大的开源社区，通过GitHub触达并与全球的开发者协作是必然选择。我们同时使用GitHub Action完成部分自动化操作。
• Gitee：作为中国最大的开源社区，Gitee为中国开发者提供了非常友好的本土化功能，对于国内开发者而言。使用Gitee相对于GitHub要方便很多。因此，SmartIDE会同步将代码推送至GitHub和Gitee，以便于我们与国内开源社区的贡献者进行协作。

工作流程

下图展示了完整的SmartIDE开源工作体系，需要说明的是这里展示的是一个流程范例或者工作思路，并不代表所有SmartIDE的组件完全遵照此范例执行。

扫描图中二维码加入早鸟群可以获取高清流程图

下面对图中出现的14个工作环节逐一进行说明：

1. 主库：SmartIDE主库同时存在于Azure DevOps (下简称ADS），GitHub和Gitee。并在三个主库副本的main分支上保持同步，具体的同步顺序是 ADS -> Github -> Gitee。SmartIDE的主库中包括CLI，Server，开发者容器三个核心部分的全部代码和脚本以及SmartIDE官网的所有内容（包括本文）。
2. main/主干：主干是SmartIDE唯一的代码基准，在任何时间点我们都保持主干上的代码质量满足产品级使用的需要，主干上的代码和我们稳定版通道的最新版本相对应。
3. release/发布分支：我们使用Scrum组织日常开发过程，迭代周期为2周，我们会在每个迭代开始时拉取对应的release分支，比如release-23就代表第23个迭代的代码变更。release分支的代码与每日构建版通道的版本保持一致。
4. feature/特性分支：特性分支是SmartIDE内部开发人员执行日常开发任务的分支，一般对应ADS看板上的一个卡片（可以是特性或者任务，具体使用哪个粒度由开发者自己决定）。特性分支上会执行CI流水线并将安装包推送到我们内部的特性发布通道，这个通道只对内部开发者开放。
5. feature-PR/特性分支拉取请求：当内部开发者认为当前特性已经可以推送到 release/发布分支 并通过每日构建通道提供给外部用户，就可以创建这个 feature-PR。feature-PR需要至少2名内部开发者的Code-Review以及流水线门禁的检查。这些条件全部满足后方可合并到release分支。这个过程中我们推荐采用普通的Merge方式以便保留完整的commit日志，但是如果在Code-Review过程中发现携带了敏感信息或者commit日志不够规范，我们会要求开发者使用 Squash（压缩） 方式合并PR，这将帮助我们剔除不必要的commit记录，但也会丢失一部分commit日志。
6. release-PR/发布拉取请求：在每个迭代过程中，我们会选择合适的时间点进行稳定版发布，这个时间点并不固定也并不限制在一个迭代只发布一次稳定版。只要我们认为当前release分支的代码质量达到了要求同时有必要进行稳定版发布，我们就会创建这个 release-PR。这个PR同样需要满足Code-Review的要求以及一系列的流水线门禁检查。在Code-Review过程中，产品经理 需要被引入以确保发布的内容足够明确。因为此时产品经理需要同步准备对应的产品文档，发布日志以，博客，市场宣传等内容。
7. Azure Pipeline/流水线：以上4/5/6三个环节中所涉及的流水线全部通过一个 azure-pipeline.yml 文件进行描述。流水线会负责执行各种繁琐的检查验证并反馈问题，同时按照SmartIDE的发布策略，完成Windows/MacOS/Linux以及AMD/ARM平台的编译构建，代码签名等动作，最终允许内外部开发者/用户方便的获取对应的版本。
8. 云存储/二进制包/配置文件：我们使用Azure Blob提供二进制包和配置文件的存储和发布，在这里包含了2个主要目录，分别是: /builds 每日构建通道，/releases 稳定版通道
9. docker/容器镜像包：SmartIDE大量使用了docker容器镜像，包括SmartIDE CLI和Server本身，开发者镜像以及其他的依赖包。所有这些镜像我们会同时推送到DockerHub和阿里云镜像仓库，后者是为了国内开发者访问方便。
10. ads-pipeline: sync2github：这是一个Azure Pipeline的流水线任务，会在代码合并到ADS主库的main分支时自动将代码同步到GitHub主库的main分支上。
11. GitHub Actions: 以上同步完成后，会触发两个Actions，分别是docs-publish用于将/docs目录中的内容构建成静态站点（使用hugo框架）并同时发布到官网上。另外一个action会将Github主库的main分支同步到Gitee主库的main分支上。
12. 官网：为了方便国内的开发者以及海外的开发者都能顺畅的使用SmartIDE的工具和服务，我们分别在国内（Azure北京数据中心）和美国（Azure 美中数据中心）部署了产品官网。两个站点采用不同的域名 smartide.cn (国内官网）和 smartide.dev (海外官网），官网本身内容上随时保持一致，提供中英文两种语言的内容。
13. 社区库：在GitHub或者Gitee上的社区小伙伴可以fork我们的主库并提交PR给我们的主库。
14. release-github/社区发布分支：社区小伙伴提交的PR一旦接受会合并到release-github分支上或者release-gitee分支上。这个过程中，我们会使用GitHub和Gitee所提供的Issue和PR功能与社区贡献者进行互动，完成整个代码合并过程的闭环，尽量保留所有的commit记录。在完成PR时采用Merge或者Squash方式的策略与feature-PR一致，尽量使用Merge并在必要的时候使用Squash。
15. Github-action: sync2ads：这个GitHub Action负责将当前的社区发布分支同步回到ADS中，以便我们将社区贡献合并到产品主干。
16. 社区发布分支（镜像）：以上sync2ads任务会将GitHub和Gitee上的贡献同步回到ADS，内部开发者会再创建 release-community-PR 将这些社区贡献合并到当前的内部 release 分支上以便按照日常发布流程发布出去。在这个 release-community-PR 上我们采用和 feature-PR 一致的审核策略。简单来说，我们将社区发布分支当作一个内部的特性分支来看待。

相关资料

另外，为了帮助开发者解决工作体系中的一些具体问题，下面列出了一些参考资料：

2.1 - 如何选择拉取请求的不同合并方式

不同PR合并方式的优缺点

在工作体系中，我们在不同的场景下会使用不同的PR合并方式。在大多数成熟的Git服务上都有至少三种PR合并方式：

• Merge (No Fast-forward)：普通合并，为当前的合并单独创建一条commit信息并保留分支上所有的commit。
• Rebase：变基合并，直接将分支上的commit在目标分支上重写，不会创建单独的合并commit信息。
• Squash：压缩合并，将分支上的所有commits压缩成一个commit，并将这条commit放入目标分支。

以上三种合并方式各有好处，以下从不同的角度比较以便大家在合并PR的时候做出正确的选择。

三张图片可以更加直观的看到区别

图1 - 使用Merge方式合并PR以后，原分支的提交历史和单独的PR合并提交历史记录全部被保留

图2 - 使用Rebase方式合并PR以后，只有原分支提交历史记录被暴露，没有PR合并记录

图3 - 使用Squash方式合并PR后，只有独立的PR合并记录，原分支的提交历史被清理掉了（压缩）

从以上比较可以看出，这3中合并方式各有优缺点，并没有办法选出一种适合所有场景的方法，因此需要实际操作PR合并的开发者充分了解以上的特点并做出选择。这里是几点通用的建议：

• 从使用PR的目的而言，我们是希望能够通过PR对需要合并的内容进行一定的控制，一般来说我们是希望这个过程被完整记录的。从合格角度来说，Merge和Squash都会在合并的时候针对PR本身创建独立的提交记录，相比Rebase更有优势。
• 作为版本控制本身的特点，历史记录一旦产生就非常难以被彻底剔除掉，这种特点对于我们跟踪代码变更是有优势的。但是在一种情况就会变得比较麻烦，就是当开发者不小心提交了一些敏感信息在代码中，这个特点就会造成麻烦，因为就算在下一个提交中删除掉了敏感信息，历史记录仍然会存在。在这种情况下，Squash（压缩合并）的优势就体现出来了。但代价是将丢失掉这次PR原分支上的所有的历史记录。

基于以上2点总结，一般性建议是在PR合并的时候尽量选择Merge的方式，这样有助于保留历史记录；但是如果发现这次PR所涉及的原分支历史中存在敏感信息，那么就要采用Squash的方式压缩掉敏感信息，牺牲掉历史记录的完整性。

参考资料：

• Why I’m against merging pull requests in squash mode or rebase mode?
• What’s the Difference Between the 3 Github Merge Methods?

2.2 - 如何清理Git历史记录中的敏感信息

在合并拉取请求的时候选择Squash方法，我们可以有效的利用PR本身的功能避免敏感信息进入Git代码库，但是如果已经不小心引入了敏感信息，那么我们就需要方法能够识别并清理这些信息，否则可能会造成严重的安全问题。

以下介绍集中识别、清理和预防敏感信息提交的方法。

检测敏感信息

1. 使用git log搜索特定的敏感信息

如果你自己清楚需要定位的敏感信息内容，比如特定的关键字，特定的密码或者文件，那么可以采用通过执行以下指令来定位这些敏感信息。

## 直接搜索git history for string
git log -S <敏感词/密码内容等> --oneline
## 直接搜索git history for file
git log --all --full-history -- "**/thefile.*"

执行效果如下

2. 使用Gitleaks定位敏感信息

Gitleaks是一款开源工具，可以自动根据预定义的规则扫描git库历史记录中可能的敏感信息，包括：密码，密钥，token等。Gitleaks的好处是无需提前知晓敏感信息内容，本身所提供的默认配置已经可以识别大多数可能的敏感信息内容，如果需要扩展也可以通过修改配置文件的方式（使用正则表达式）加入自己希望检测的pattern。

比如以下这个json就是gitleaks的一个可能包含了aws_secret的代码片段

{
        "Description": "AWS",
        "StartLine": 37,
        "EndLine": 37,
        "StartColumn": 19,
        "EndColumn": 38,
        "Match": "\t\t\"aws_secret= \\\"AKIAIMNOJVGFDXXXE4OA\\\"\":          true,",
        "Secret": "AKIAIMNOJVGFDXXXE4OA",
        "File": "checks_test.go",
        "Commit": "ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29",
        "Entropy": 0,
        "Author": "zricethezav",
        "Email": "thisispublicanyways@gmail.com",
        "Date": "2018-01-28 17:39:00 -0500 -0500",
        "Message": "[update] entropy check",
        "Tags": [],
        "RuleID": "aws-access-token"
}

相关链接

• Gitleaks开源地址 https://github.com/zricethezav/gitleaks
• Azure DevOps 插件地址 https://marketplace.visualstudio.com/items?itemName=Foxholenl.Gitleaks

3. 使用detect secrets检查敏感信息

Detect secrets 和gitleaks的功能类似，不过detect secrets提供了更强大的插件机制，允许用户自行编写pattern识别机制。

相关链接：

• Detect secrets 开源地址 https://github.com/Yelp/detect-secrets
• Code with Engineering Playbook 说明 https://microsoft.github.io/code-with-engineering-playbook/security/secret-detection/

清理敏感信息

以上3种方式都可以有效的定位git历史记录中的敏感信息，但是定位以后的清理工作仍然是个麻烦的事情。因为git本身是一个链式数据结构，任何一个commit都会和前后的commit有链接关系，我们很难直接清理掉一个commit。而且敏感信息可能在历史中出现多次，清理掉一个可能会发现还会有其他，操作起来会也非常繁琐。

最有效的清理方式是将包含了敏感信息的文件先备份，然后从历史记录中彻底清理这个文件的记录，再把文件加回来。这样可以非常有效而且彻底的清理掉敏感信息。

当然这样做也有一个非常大的弊端就是这个文件会从之前的历史中消失，如果需要从历史时间点再次构建代码就会因为缺少文件而造成无法编译。同时，修改历史记录会造成对整个git历史记录重写（重新生成所有的commit记录），这样会造成很多其他关联系统的链接失效（比如在issue中关联了commitID）。但是相对于遗留敏感信息在历史记录中，类似的问题可能就不那么重要了。

以下脚本可以将生成一个包含了所有已经从代码库中删除的文件的清单，然后根据这个清单彻底清理涉及这个文件的历史记录。

## 以下脚本只能在Linux上运行
## 生成已删除文件清单 deleted.txt
git log --diff-filter=D --summary <起始点的CommitID>..HEAD | egrep -o '*[[:alnum:]]*(/[[:alnum:].]*)+$' > deleted.txt

## 清理历史记录
for del in `cat deleted.txt`
do
    git filter-branch --index-filter "git rm --cached --ignore-unmatch $del" --prune-empty -- --all
    # The following seems to be necessary every time
    # because otherwise git won't overwrite refs/original
    git reset --hard
    git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d
    git reflog expire --expire=now --all
    git gc --aggressive --prune=now
done;

防止提交敏感信息

以上方法都只能起到亡羊补牢的作用，而且清理操作会造成破坏性的结果，对保持项目历史记录延续性非常不利。因此最有效的方式是从根本上防止问题的发生。

Gitleaks和detect secret这两个工具都可以设置成 git pre-commit hook（预提交检查），这样在开发者试图提交带有敏感信息的文件的时候就会直接拒绝commit的创建，从而从根本上解决敏感信息的问题。

具体操作方式可以参考：

• 设置Gitleaks作为预提交检查工具 https://github.com/zricethezav/gitleaks#pre-commit-hook
• 设置detect secret作为预提交检查工具 https://microsoft.github.io/code-with-engineering-playbook/security/secret-detection/#detect-secrets-pre-commit-hook

3 - 安装

3.1 - CLI 安装说明

先决条件

SmartIDE CLI 通过调用docker和docker-compose来实现容器化环境的管理，因此你需要确保在自己的环境中已经正确安装了这两个软件。如果你已经在使用这两个工具，那么可以直接进入以下 SmartIDE 安装手册 部分。

说明： 如果你只需要使用smartide远程主机模式，那么本地开发机上并不需要安装 Docker Desktop 工具，因为所有的环境调度都在远程主机上完成，但是你仍然需要确保远程主机上已经正确安装了docker和docker-compose工具。

如果您需要docker和docker-compose的安装指导，可以参考以下链接：

• 在 Windows 上安装 Docker 桌面版 (包含Docker-Compose)
• 在 MacOS 上安装 Docker 桌面版 (包含Docker-Compose)
• 在 Linux 服务器上安装 Docker 和 Docker-Compose

说明： 我们在国内提供了安装包镜像地址以及一键安装脚本以便提升大家的安装体验，具体请参考以上文档中的说明。

SmartIDE 安装手册

我们按照敏捷开发模式进行SmartIDE的开发，所有的版本都通过CI/CD流水线自动构建，打包，测试和发布。为了同时满足外部用户对于稳定性的要求和开发团队以及早期使用者对新功能快速更新的要求，我们提供以下两个发布通道。

稳定版通道

稳定版的发布按照sprint进行，我们采用2周一个sprint的开发节奏，每个sprint结束后我们会发布一个稳定版到这个通道。这个版本经过开发团队相对完整的测试，确保所提供的功能稳定可用，同时我们会在每个sprint结束时同时发布“版本发布说明”并对当前版本的性能和改进进行说明。

流水线状态

版本发布说明列表：

• MacOS
• Linux
• Windows

# SmartIDE 稳定版通道安装脚本
# 打开终端窗口，复制粘贴以下脚本即可安装稳定版SmartIDE CLI应用
# 再次执行此命令即可更新版本

# Intel芯片
curl -OL  "https://smartidedl.blob.core.chinacloudapi.cn/releases/$(curl -L -s https://smartidedl.blob.core.chinacloudapi.cn/releases/stable.txt)/smartide-osx" \
&& mv -f smartide-osx /usr/local/bin/smartide \
&& ln -s -f /usr/local/bin/smartide /usr/local/bin/se \
&& chmod +x /usr/local/bin/smartide

# Apple芯片（比如M1/M2系列）
curl -OL  "https://smartidedl.blob.core.chinacloudapi.cn/releases/$(curl -L -s https://smartidedl.blob.core.chinacloudapi.cn/releases/stable.txt)/smartide-osx-arm64" \
&& mv -f smartide-osx-arm64 /usr/local/bin/smartide \
&& ln -s -f /usr/local/bin/smartide /usr/local/bin/se \

# SmartIDE 稳定版通道安装脚本
# 打开终端窗口，复制粘贴以下脚本即可安装每日构建版SmartIDE CLI应用
# 再次执行此命令即可更新版本

# x86 架构处理器
curl -OL  "https://smartidedl.blob.core.chinacloudapi.cn/releases/$(curl -L -s https://smartidedl.blob.core.chinacloudapi.cn/releases/stable.txt)/smartide-linux-amd64" \
&& sudo mv -f smartide-linux-amd64 /usr/local/bin/smartide \
&& sudo ln -s -f /usr/local/bin/smartide /usr/local/bin/se \
&& sudo chmod +x /usr/local/bin/smartide

# arm 架构处理器
curl -OL  "https://smartidedl.blob.core.chinacloudapi.cn/releases/$(curl -L -s https://smartidedl.blob.core.chinacloudapi.cn/releases/stable.txt)/smartide-linux-arm64" \
&& sudo mv -f smartide-linux-arm64 /usr/local/bin/smartide \
&& sudo ln -s -f /usr/local/bin/smartide /usr/local/bin/se \
&& sudo chmod +x /usr/local/bin/smartide

# SmartIDE 稳定版通道安装脚本
# 打开PowerShell终端窗口，复制粘贴以下脚本即可自动下载稳定版SmartIDE MSI安装包，并启动安装程序
# 再次执行此命令即可更新版本
# 如果是第一次在Windows上安装，请重新打开PowerShell窗口以便PATH设置生效
Invoke-WebRequest -Uri ("https://smartidedl.blob.core.chinacloudapi.cn/releases/"+(Invoke-RestMethod https://smartidedl.blob.core.chinacloudapi.cn/releases/stable.txt)+"/SetupSmartIDE.msi")  -OutFile "smartide.msi"
 .\smartIDE.msi

每日构建版通道

SmartIDE CI/CD 流水线每晚8点（GMT+8 Beijing) 会自动将当天提交到sprint分支上的代码进行自动化构建和测试，并发布到每日构建版通道；产品组每天早上会对这个版本进行冒烟测试，确保基本功能可以正常运行，如果在冒烟测试过程中发现任何问题，我们会优先进行修复并立即通过这个通道发布修复后的版本。

每日构建版本通道的目标用户是产品组成员和早期试用社区用户，大家可以通过我们的SmartIDE GitHub首页提交issue或者通过微信公众号，B站等社区渠道提供反馈给我们。我们非常希望得到社区的反馈，并会尽力为社区用户提供最快速度的响应。

流水线状态

• MacOS
• Linux
• Windows

# SmartIDE 每日构建版通道安装脚本
# 打开终端窗口，复制粘贴以下脚本即可安装每日构建版SmartIDE CLI应用
# 再次执行此命令即可更新版本

# Intel芯片
curl -OL  "https://smartidedl.blob.core.chinacloudapi.cn/builds/$(curl -L -s https://smartidedl.blob.core.chinacloudapi.cn/builds/stable.txt)/smartide-osx" \
&& mv -f smartide-osx /usr/local/bin/smartide \
&& ln -s -f /usr/local/bin/smartide /usr/local/bin/se \
&& chmod +x /usr/local/bin/smartide

#  Apple芯片
# 打开终端窗口，复制粘贴以下脚本即可安装每日构建版SmartIDE CLI应用
# 再次执行此命令即可更新版本
curl -OL  "https://smartidedl.blob.core.chinacloudapi.cn/builds/$(curl -L -s https://smartidedl.blob.core.chinacloudapi.cn/builds/stable.txt)/smartide-osx-arm64" \
&& mv -f smartide-osx-arm64 /usr/local/bin/smartide \
&& ln -s -f /usr/local/bin/smartide /usr/local/bin/se \
&& chmod +x /usr/local/bin/smartide

# SmartIDE 每日构建版通道安装脚本
# 打开终端窗口，复制粘贴以下脚本即可安装每日构建版SmartIDE CLI应用
# 再次执行此命令即可更新版本

# x86架构处理器
curl -OL  "https://smartidedl.blob.core.chinacloudapi.cn/builds/$(curl -L -s https://smartidedl.blob.core.chinacloudapi.cn/builds/stable.txt)/smartide-linux-amd64" \
&& sudo mv -f smartide-linux-amd64 /usr/local/bin/smartide \
&& sudo ln -s -f /usr/local/bin/smartide /usr/local/bin/se \
&& sudo chmod +x /usr/local/bin/smartide

# arm架构处理器
curl -OL  "https://smartidedl.blob.core.chinacloudapi.cn/builds/$(curl -L -s https://smartidedl.blob.core.chinacloudapi.cn/builds/stable.txt)/smartide-linux-arm64" \
&& sudo mv -f smartide-linux-arm64 /usr/local/bin/smartide \
&& sudo ln -s -f /usr/local/bin/smartide /usr/local/bin/se \
&& sudo chmod +x /usr/local/bin/smartide

# SmartIDE 每日构建版通道安装脚本
# 打开PowerShell终端窗口，复制粘贴以下脚本即可自动下载每日构建版SmartIDE MSI安装包，并启动安装程序
# 再次执行此命令即可更新版本
# 如果是第一次在Windows上安装，请重新打开PowerShell窗口以便PATH设置生效
Invoke-WebRequest -Uri ("https://smartidedl.blob.core.chinacloudapi.cn/builds/"+(Invoke-RestMethod https://smartidedl.blob.core.chinacloudapi.cn/builds/stable.txt)+"/SetupSmartIDE.msi")  -OutFile "smartide.msi"
 .\smartIDE.msi

获取并理解版本号

安装好SmartIDE后，您可以通过以下命令获取当前版本号

# 键入以下命令获取当前版本
smartide version
# 输出如下
v1.0.23.4650
版本号: v1.0.23.4650
操作系统: Microsoft Windows 11 企业版
构建号: 20220729.4_4650_main_Manual
编译时间: 2022-07-29 03:22:35
提交记录: a26ef7a473eb2251f9a8276755d30b73c3142e4e
发行商: leansoftX.com

说明：

• Version number: 代表当前版本号，格式：[主版本].[小版本].[Sprint编号].[构建号]
• Build number: CI/CD流水线的完整构建编码，格式：[日期].[序号]_构建号_分支名_构建类型
• Commit record: 当前版本所对应的git commit hash
• Company: 发行商名称

3.2 - Server 部署手册

SmartIDE Server 是面向团队和企业的云原生容器化远程工作区管理平台，可以为开发团队提供统一的开发测试资源管理，基于浏览器的开发环境访问以及团队协作能力。SmartIDE Server 的 团队基础版 功能是开源而且免费的，任何人都可以按照本手册所提供的方式完成部署并免费使用，没有使用期限限制，没有用户数限制，也没有资源数量限制。

如果您所使用的服务器环境可以连接互联网，可以使用我们以下提供的全自动一键安装方式完成安装部署；如果你处于隔离网络（无法访问互联网），我们也提供可供下载导入到隔离网络中的离线安装方式，可以通过 提交技术支持申请 的方式获取这些资源。

架构图和组件说明

下图展示了SmartIDE Server环境的架构；总体来说，SmartIDE Server 采用了非常灵活并且可扩展的分布式架构，每个服务组件都可以进行独立的横向扩展以便确保可以应对不同规模的部署模式需求。

下面对上图中各个组件进行说明，以便对本手册中所涉及的内容进行准确理解：

• 核心服务：包括Server所提供的Web界面，API服务，后台的数据持久化（Redis & MySQL），以及提供对外访问的反向代理服务（nginx）。对Server的所有访问均通过反向代理服务进行统一控制，方便企业用户在部署时与现有网络架构进行整合。
  • 容器化部署：核心服务中的所有组件全部采用容器化部署方式，对于小型团队部署环境，我们提供docker-compose文件将所有服务部署在一台linux主机上，对于中大型团队中的部署模式，提供对应的k8s manifest文件以便部署在k8s集群中。
  • 辅助管理工具：phpMyAdmin提供MySQL数据的管理界面，Portainer提供docker容器环境的管理，可以用于服务节点的问题定位，日志查看和重启等操作。单机版部署模式下默认在docker-compose中包含这两个工具。
• 核心K8S服务：采用基于tekton流水线引擎提供的SmartIDE工作区弹性调度组件。远程工作区是SmartIDE中最重要的管理对象，对于远程工作区的所有调度任务均通过tekton流水线任务完成。在这些调度任务中，实际执行的就是 SmartIDE CLI。CLI中内置的 mode=server 模式就是为了在这个场景中使用而设计的，mode=server 模式最大化重用了 CLI 本身的能力，同时针对流水线调度环境进行了少量适配。采用这种架构，SmartIDE 可以简化调度动作的开发调试复杂度，同时将Server核心组件与工作区资源进行解耦，也就是说SmartIDE Server的核心服务不会直接连接工作区资源，这样就让核心服务可以专注于企业业务场景，而将远程工作区调度的工作职责全部交给CLI来完成。
  • 高可用性：tekton流水线引擎本身是一个 k8s CRD 实现，其可用性来自于k8s本身的高可用性。这样的设计可以确保 SmartIDE的核心能力直接集成企业云原生架构的可用性。
  • 弹性和扩展性：SmartIDE具体的调度工作全部都通过核心k8s服务集群完成，完全不依赖server核心服务的算力和资源，这样也确保了在大规模团队使用场景下的弹性扩展。
• 工作区资源：SmartIDE支持主机和k8s两类资源，管理员可以自行将资源注册到 SmartIDE Server 即可允许用户使用这些资源来运行远程工作区环境。SmartIDE实际的工作负载其实全部运行在这些工作区资源上，无论是 WebIDE，代码编译，测试以及工作所需要的中间件环境都完全不依赖server核心服务以及核心k8s集群的资源。企业管理员可以根据需要随时增加或者减少注册给SmartIDE的工作区资源以便确保企业内部资源的合理利用。
  • 主机类资源：和SmartIDE CLI一样，开发者只需要一台可以运行Docker的Linux主机即可将SmartIDE远程工作区部署在上面使用。对于还没有使用k8s的企业来说，可以将闲置的物理机，虚拟机注册在SmartIDE Server上统一管理并分配给开发者使用。这些主机也无需特别的网络配置，只需要开通SSH服务即可。
  • K8S类资源：管理员可以将一个或者多个k8s集群注册到Server，并分配给开发者使用。SmartIDE Server会自动完成对k8s集群的必要初始化操作，并利用命名空间（Namespace）隔离不同开发者的远程工作区环境，包括资源用量限制。

部署模式

SmartIDE Server 提供三种不同的部署架构以便适应不同规模的团队使用

• 单机版安装：只需要一台linux服务器就可以完成整个Server环境的安装和部署，包括核心服务和核心K8S集群均可以在一台主机上完成部署。在这个部署模式下，核心k8s集群会使用一个单节点的minikube来提供k8s的调度能力。对于小型团队来说，这种部署模式非常简单而且资源消耗很低。
• 多机版安装：可以将核心服务和k8s服务分别部署在2台或者多台主机中，这种部署模式适合中等规模的团队，或者没有k8s基础环境的企业。搭配主机类工作区资源，可以在完全没有k8s环境下使用SmartIDE Server。
• 集群安装：如果企业已经具备了现有的k8s环境，那么可以将SmartIDE Server的全部组件都部署到k8s集群中以提供高可用，弹性和可扩展性，满足中到大型团队的日常使用；同时在需要扩展用量的时候临时接入主机或者K8S集群来满足需求。

单机版安装操作

以下操作过程针对单机版环境安装进行描述，如果需要进行多机或者集群安装部署，请 提交技术支持申请 。

环境要求

单机版环境可以满足10-50人团队日常使用需求，根据团队规模情况，请选择以下环境最小化或者建议配置。

备注：

• 以上人数限制仅代表一个估计值，根据实际使用场景可能会有所不同；
• 以上环境仅代表核心服务和核心K8S（采用minikube单节点模式）的服务器节点需求，工作区资源（主机或者K8S）需要另外准备；
• 虽然可以将这个服务器也注册到Server的工作区资源列表中使用，但是非常不建议这样做，因为工作区调度任务会对节点进行文件操作和各种复杂控制，这个过程中很可能影响核心服务的运行；
• 请确保使用干净的操作提供环境，如果主机上已经安装或者运行其他应用可能会在本手册操作过程中被损坏或者影响本手册的操作结果。
• 当前只提供Ubuntu系统的一键安装脚本，其他发行版的脚本会陆续提供。

账号和权限要求

不支持使用root账号进行操作，请按照以下方式创建非root+免密码sudo账号进行操作。如果当前只有root账号，请使用root账号SSH登录到服务器以后执行以下操作。

## 新增用户smartide,并设置sudo权限
sudo useradd smartide
sudo passwd smartide

## 编辑 sudoers 文件配置免密码sudo操作
sudo vim /etc/sudoers
## 在 Allow root to run any commands anywhere 的root下方设置sudo免密权限
smartide   ALL=(ALL) NOPASSWD: ALL

配置用户使用bash作为默认的shell

SmartIDE安装脚本 使用一些特定的bash指令，因此请确保你所使用的用户或者以上所创建的smartide用户的默认shell为bash。

vim /etc/passwd

更新

smartide:x:1000:1000::/home/smartide:/bin/sh 

改为

smartide:x:1000:1000::/home/smartide:/bin/bash

完成以上操作后使用所创建的账号重新SSH登录系统，比如以上使用的是 smartide 账号，那么你的登录指令是：

ssh smartide@<server ip address> -p <server SSH port>

网络和防火墙要求

为了确保可以正常访问SmartIDE Sever的相关服务，请确保以下端口已经在网络防火墙或者网络策略中打通。

一键安装部署脚本

请确保执行以下脚本之前已经完成了环境要求、账号要求、网络要求的检查；并且，请确保执行脚本的主机环境与互联网保持畅通。

在以下脚本执行过程中，会频繁的通过网络下载文件或者拉取容器镜像，如果因为网络问题造成安装终端，请从新执行脚本。 为了适应国内/国际网络的不同特性，我们提供了2个不同的脚本分别使用国内/国外的文件和镜像源获取安装介质，请根据你的服务器所处的网络环境自行决定使用哪个脚本完成安装。 国内网络一键安装

curl -LO https://gitee.com/smartide/SmartIDE/raw/main/deployment/deployment_cn.sh -o deployment_cn.sh&& bash deployment_cn.sh

国际网络一键安装

curl -s https://gitee.com/smartide/SmartIDE/raw/main/deployment/deployment.sh -o deployment.sh&& bash deployment.sh

安装步骤中，需要输入SmartIDE Server对外服务的IP地址，在这里输入本地对外服务的IP：

请输入本机对外服务的IP地址：XX.XX.XX.XX

安装过程一般需要持续10分钟左右，以下是安装的完整日志

localadmin@Private-Online-Deploy:~$ curl -LO https://gitee.com/smartide/SmartIDE/raw/main/deployment/deployment_cn.sh -o deployment_cn.sh&& bash deployment_cn.sh
SmartIDE Server Deployment Start...
请输入本机对外服务的IP地址：20.2.72.212
SmartIDE Server Deployment : 1.Basic Component
SmartIDE Server Deployment : 1.1 docker and docker-compose
...
SmartIDE Server Deployment : 1.2 Git
SmartIDE Server Deployment : 1.3 Kubectl
SmartIDE Server Deployment : 1.Basic Component Installed Successfully.
SmartIDE Server Deployment : 2.MiniKube
SmartIDE Server Deployment : 2.1 Minikube Install
SmartIDE Server Deployment : 2.2 Build Minikube Env
🔥  Deleting "minikube" in docker ...
🔥  Deleting container "minikube" ...
🔥  Removing /home/localadmin/.minikube/machines/minikube ...
💀  Removed all traces of the "minikube" cluster.
😄  minikube v1.24.0 on Ubuntu 20.04
✨  Using the docker driver based on user configuration
❗  Your cgroup does not allow setting memory.
    ▪ More information: https://docs.docker.com/engine/install/linux-postinstall/#your-kernel-does-not-support-cgroup-swap-limit-capabilities
✅  Using image repository registry.cn-hangzhou.aliyuncs.com/google_containers
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
🔥  Creating docker container (CPUs=2, Memory=4096MB) ...
🐳  Preparing Kubernetes v1.22.3 on Docker 20.10.8 ...
    ▪ Generating certificates and keys ...
    ▪ Booting up control plane ...
    ▪ Configuring RBAC rules ...
🔎  Verifying Kubernetes components...
    ▪ Using image registry.cn-hangzhou.aliyuncs.com/google_containers/storage-provisioner:v5
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
    ▪ Using image registry.cn-hangzhou.aliyuncs.com/google_containers/nginx-ingress-controller:v1.0.4
    ▪ Using image registry.cn-hangzhou.aliyuncs.com/google_containers/kube-webhook-certgen:v1.1.1
    ▪ Using image registry.cn-hangzhou.aliyuncs.com/google_containers/kube-webhook-certgen:v1.1.1
🔎  Verifying ingress addon...
🌟  The 'ingress' addon is enabled
SmartIDE Server Deployment : 3.Tekton Pipeline
SmartIDE Server Deployment : 3.1 Kubectl Apply Tekton Pipeline And DashBoard
...
SmartIDE Server Deployment : 3.2 Kubectl Apply Tekton Trigger
...
SmartIDE Server Deployment : 3.3 Kubectl Apply Tekton SmartIDE Pipeline Configrate
...
SmartIDE Server Deployment : 3.Tekton Pipeline Installed Successfully.
SmartIDE Server Deployment : 4.SmartIDE Server
...
Network smartide-server-network is external, skipping
Creating gva-portainer ... done
Creating gva-mysql     ... done
Creating gva-myadmin   ... done
Creating gva-redis     ... done
Creating gva-server    ... done
Creating gva-web       ... done
SmartIDE Server Deployment : 4.SmartIDE Server Installed Successfully.
SmartIDE Server Deployment : 5.Build SmartIDE Server Network Connection With Minikube.
SmartIDE Server Deployment : 5.Build SmartIDE Server Network Connection With Minikube Successfully.
SmartIDE Server 服务地址：http://20.2.72.212:8080
SmartIDE Server Deployment Successfully！

请确保你的日志末尾出现 SmartIDE Server Deployment Successfully！的字样即表示安装已经顺利完成。

如果中途出现报错的情况，可以提交 Issue 与我们联系。

数据持久化与备份恢复

SmartIDE Server的数据均保存在MySQL数据库中。

• 备份：单机版部署中，MySQL数据已将久化到$HOME/smartide/mysql文件夹中，其中gva文件夹即为SmartIDE Server数据库。此时，只需在安装时的目录中，执行如下脚本停止Server服务后，拷贝gva文件夹即可完成备份，完成后重新启动服务。

# 停止SmartIDE Server服务
docker-compose -f docker-compose.yaml --env-file docker-compose_cn.env down
# 执行备份
cp -r $HOME/smartide/mysql/gva $HOME/smartide/gva-backup
# 重新SmartIDE Server服务
docker-compose -f docker-compose.yaml --env-file docker-compose_cn.env up -d

• 恢复：若在原主机中进行还原恢复，那么只需要将备份的gva文件夹，替换到$HOME/smartide/mysql/gva即可。若在其他机器中恢复，那么停止Server服务后，替换到$HOME/smartide/mysql/gva即可，完成后重新启动服务。

# 停止SmartIDE Server服务
docker-compose -f docker-compose.yaml --env-file docker-compose_cn.env down
# 执行备份
cp -r $HOME/smartide/gva-backup $HOME/smartide/mysql/gva
# 重新SmartIDE Server服务
docker-compose -f docker-compose.yaml --env-file docker-compose_cn.env up -d

访问环境

完成以上安装步骤后，就可以通过以下访问地址，访问部署好的Server了：

• 主服务 http://{deploment host ip}:8080
• MySQL管理工具phpMyAdmin（可选）http://{deploment host ip}:8090
  • 用户名：root，默认密码：SmartIDE@123
• Docker环境管理工具Portainer（可选） http://{deploment host ip}:9000
• Tekton流水线仪表盘（可选） http://{deploment host ip}:9097 注：若需使用Tekton仪表盘（可选）查看流水线执行情况，需在主机执行以下命令，后访问Tekton仪表盘，这个脚本会启用9097端口，请同时确保9097端口已经在网络中打通。

kubectl --namespace tekton-pipelines port-forward svc/tekton-dashboard 9097:9097 --address 0.0.0.0 &

初始账号和密码修改

初始超级管理员用户名密码

• 用户名：superadmin
• 默认密码：SmartIDE@123

强烈建议立即修改以上账号的密码，此账号（superadmin）为系统超级管理员账号，可以在系统中进行任何操作（包括一些可能损坏SmartIDE现有功能的操作）。因此建议安装完成后立即修改此账号的密码。

修改密码操作：点击Server版右上角【个人信息】，并且点击【修改密码】操作即可。

请注意，superadmin账号还用于tekton流水线的调度，因此在修改密码后还需要更新 server配置文件中的 token 信息。你可以通过 SmartIDE CLI 执行 se login 指令并连接到当前 server 的主服务地址上并使用superadmin账号登录，此时打开 .ide/.ide.config 文件可以获取新token信息。

将此token中内容更新到 server-server 容器中的配置文件里面：

• 进入到安装目录的smartide-install目录，vi config.docker.yaml

• 修改完毕后，执行以下命令，重启启动gva-server容器即可。

docker restart gva-server

验证Server工作情况

可以参考 Server快速开始 文档完成主机资源注册和工作区创建操作，即可验证当前SmartIDE Server的功能工作正常。

常见安装使用问题

• 问题1. MiniKube启动失败，导致新建工作区报错。

  • 原因1：MiniKube启动，不支持root账号，所以导致MiniKube启动失败，这样在新建工作区时，就会导致访问不到Tekton流水线，从而报错。
  • 原因2：默认脚本中MiniKube启动时指定CPU为2核，内存为4G。如果准备环境配置过低，则无法正常启动MiniKube，导致部署错误，从而新建工作区时报错。

• 问题2. 安装使用操作系统为非Ubuntu，导致安装出错。

  • 原因：目前安装脚本只支持Ubuntu版本，请根据环境要求准备环境。

技术支持

如果您在以上安装过程或者日常使用过程中遇到问题，请通过提交 Issue 的方式与我们取得联系。

也可以加入我们的 SmartIDE 早鸟群获取第一手的产品资料和技术支持。 对于隔离网络或者中大型部署模式的技术支持，请 提交技术支持申请 ，我们会尽快与您取得联系。

参考资料

• Docker & Docker-Compose 官方安装手册
• CLI 安装说明
• Docker & Docker-Compose 安装手册 (Linux服务器)
• Tekton 流水线引擎官网
• Minikube 官网

3.3 - SmartIDE 插件市场安装说明

SmartIDE Marketplace 是基于Eclipse OpenVSX 开源项目搭建的类VSCode插件市场，详细内容请参考 应用插件市场 Overview。 此文档旨在描述 SmartIDE Marketplace 的详细部署过程，内容分为简要介绍、组件介绍、部署细节三部分。

1. 简要介绍

SmartIDE Marketplace服务部署均使用容器化方式进行，Dock-Compose文件见docker-compose.yaml，部署的各模块整体架构如下图所示：

• 主体为OpenVSX-Server，spring boot框架的java服务，我们在部署时需要自行添加 application.yml 配置文件，并将其放置对应位置，以便Server启动后加载。
• 后台数据库使用PostgreSql，并使用Pgadmin进行数据库的管理和查询等操作，数据库的创建和表结构的初始化过程Server进程启动时会自动执行。
• 前端界面为NodeJS架构的Web UI，我们在部署时会将前端代码库构建的静态网站结果放入Server服务的对应文件夹，使其二者变为一个进程即Server进程加入前端界面。这也是Sprint Boot框架的灵活性功能，使用者可以基于Web UI代码库自定制前端界面，并将自定制的前端页面嵌入Server服务。
• 用户登陆验证，目前只支持OAuth Provider，官方文档中声明目前只支持Github AuthApp和 Eclipse OAuth，我们在部署时使用Github AuthApp。
• 插件存储可以使用数据库（默认）、Google Storage或 Azure Blob Storage三种模式，推荐添加Google Storage或 Azure Blob Storage以避免数据库过大的情况出现。
• 插件搜索服务支持数据库搜索和附加Elastic Search服务两种模式，推荐有条件的情况下添加Elastic Search搜索服务提高搜索效率，降低数据库压力。
• 除以上架构图中展现内容外，Marketplace网站需要配置HTTPS证书，这样才服务器的扩展才能够正确被IDE加载，我们使用Nginx进行服务器的部署端口转发。

2. 组件介绍

本章节将对架构中的各个组件进行逐一介绍。

2.1 OpenVSX Server

代码库：

• github SmartIDE/eclipse-openvsx/server

镜像：

• DockerHub: smartide/smartide-openvsx:4a5546b
• Aliyun: registry.cn-hangzhou.aliyuncs.com/smartide/smartide-openvsx:4a5546b
• DockerFile

Docker-Compose部分：

server:
  image: smartide/smartide-openvsx:4a5546b
ports:
  - "8080:8080"
volumes:
  - ./configurations:/home/openvsx/server/config
links:
  - "db:pgsql-server"`

2.2 OpenVSX WebUI

代码库：

• github SmartIDE/eclipse-openvsx/webui

镜像：

• DockerHub: smartide/smartide-openvsx:4a5546b
• Aliyun: registry.cn-hangzhou.aliyuncs.com/smartide/smartide-openvsx:4a5546b
• DockerFile

Docker-Compose部分：

server:
  image: smartide/smartide-openvsx:4a5546b
ports:
  - "8080:8080"
volumes:
  - ./configurations:/home/openvsx/server/config
links:
  - "db:pgsql-server"`

2.3 Postgresql + PgAdmin

Docker-Compose部分：

db:
  image: postgres:12.2
  restart: always
  environment:
    POSTGRES_DB: #{DATABASE}#
    POSTGRES_USER: #{DATABASE_USERNAME}#
    POSTGRES_PASSWORD: #{DATABASE_PASSWORD}#
    PGDATA: /var/lib/postgresql/data
  volumes:
     - ~/openvsx/postgresqldata:/var/lib/postgresql/data
  ports:
    - "5432:5432"
pgadmin:
  image: dpage/pgadmin4:4.18
  restart: always
  environment:
    PGADMIN_DEFAULT_EMAIL: #{PGADMIN_USERNAME}#
    PGADMIN_DEFAULT_PASSWORD: #{PGADMIN_PASSWORD}#
    PGADMIN_LISTEN_PORT: 80
  ports:
    - "8090:80"
  volumes:
    - ~/openvsx/pgadmin-data:/var/lib/pgadmin
  links:
    - "db:pgsql-server"

2.4 Application.yml

OpenVSX Server 进程启动时加载的配置文件，需要放到与docker-compose.yaml同级目录的Configurations文件夹下（在volumn中定义），内容见：Application.yml

由如下重点几部分构成：

Server端口：

server:
  port: 8080

Datasource(数据库链接):

datasource:
  url: jdbc:postgresql://pgsql-server:5432/#{DATABASE}#
  username: #{DATABASE_USERNAME}#
  password: #{DATABASE_PASSWORD}#

Security(用户认证方式)

security:
  oauth2:
    client:
      registration:
        github:
          client-id: #{OAUTH_CLIENT_ID}#
          client-secret: #{OAUTH_CLIENT_SECRET}#

Search方式：

ovsx:
  databasesearch:
    enabled: true
  elasticsearch:
    enabled: false

WebUi（前端地址）：

webui:
  url: https://marketplace.smartide.cn

Storage（插件存储）：

storage:
  azure:
    service-endpoint: #{STORAGE_SERVICE_ENDPOINT}#
    sas-token: #{STORAGE_SAS_TOKEN}#

Github AuthApp

用户登陆 https://marketplace.smartide.cn 使用的验证方式：

security:
  oauth2:
    client:
      registration:
        github:
          client-id: #{OAUTH_CLIENT_ID}#
          client-secret: #{OAUTH_CLIENT_SECRET}#

具体创建说明文档见： Creating an OAuth App - GitHub Docs 创建完毕后复制client-id和client-secret 加入到 Application.yml 中即可，注意权限要给足。

2.5 Azure Blob Storage

SmartIDE Marketplace 存储插件的文件存储，我们使用Azure Blob Storage作为存储介质，配置到Application.yml中来进行起作用：

storage:
  azure:
    service-endpoint: #{STORAGE_SERVICE_ENDPOINT}#
    sas-token: #{STORAGE_SAS_TOKEN}#

具体创建说明文档见： openvsx azure-setup (github.com)

2.6 ElasticSearch

暂无使用，可参考 Deploying-Open-VSX/elasticsearch 配置。

2.7 Nginx

SmartIDE Marketplace 需配置为https且certifacate为合规证书，方可被类vscode IDE使用，我们使用Nginx进行https设置：

• Docker-Compose：

    nginx:
      image: nginx:latest
      restart: unless-stopped
      volumes:
        - ~/openvsx/deployment/openvsx/nginx/nginx.conf:/etc/nginx/nginx.conf
        - ~/openvsx/deployment/openvsx/nginx/ssl:/ssl/
      ports:
        - 80:80
        - 443:443
      links:
        - "server:openvsx-server"
  

• Nginx.Conf 内容见链接 注意:

  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Host $host;
  proxy_set_header X-Real-IP  $remote_addr;
  proxy_set_header X-Forwarded-Proto $scheme;
  

  四个http request header的设置能够确保 server 进程收到的请求头是正确无误的，这样Server进程才能够正确识别请求并进行正确的转发！

3. 部署详细步骤

本章节将以https://marketplace.smartide.cn 生产环境的部署为例，以Azure 虚拟机做为服务器、Azure Blob Storage 作为插件存储，使用 Github OAuth App 进行用户认证，来描述部署的细节。

3.1 资源准备

在执行具体步骤之前，需要准备如生产服务器、插件存储Storage、用户认证 Oauth App等资源。

3.1.1 Azure Linux VM

准备一台Azure 虚拟机并做如下设置：

• 开通如下端口：22, 443, 80, 3000, 8080, 8090, 9000
• IP和DNS设置：IP设置为静态，设置独立唯一Azure DNS名称（此处可自由选择前缀，只需在之后和marketplace.smartide.cn域名绑定时对应即可）
• 登陆VM安装 Docker和Docker-Compose

3.1.2 Azure Blob Storage

准备一个Azure存储账户, 参照 链接 设置Storage Account、创建Container等：

• 设置Storage Account的 blob公共访问为打开（默认是打开的，检查一下）

• 创建名称固定为 openvsx-resources 的 Container（名称对应Application.yml中的ovsx.storage.azure.blob-container属性，采用默认名称的话，可以不设置此属性）并设置访问级别为Blob级别

• 设置Storage Account的 CORS策略如下： origin ："*" method “GET” allowed headers “x-market-client-id, x-market-user-id, x-client-name, x-client-version, x-machine-id, x-client-commit”

• 生成共享访问签名，并保存SAS_TOKEN （对应Application.yml中的ovsx.storage.azure.sas-token）

• 进入Service Endpoint模块，复制保存 Blob Service URL （对应Application.yml中的ovsx.storage.azure.service-endpoint）

3.1.3 Github OAuth App

参照 Creating an OAuth App - GitHub Docs 创建 Github OAuth App 提供用户验证机制。创建完毕后获取 Client ID 并生成 Client Secret，复制后存储供后续使用。

所有资源准备环境都已经就绪，接下来将会使用GitHub Action 进行生产环境的部署。

3.2 流水线配置 与 运行部署

3.2.1 流水线介绍

SmartIDE Marketplace生产环境使用GitHub Action进行部署，流水线定义文件位置： eclipse-openvsx/smartide-openvsx-deployment.yml 读者可以参考以上流水线定义的任务执行步骤进行部署准备和执行具体部署过程。

3.2.2 运行前准备

SmartIDE Marketplace 生产环境部署操作执行之前，需要配置流水线中所使用的项目的secrets，以便让流水线运行时替换掉对应配置文件（docker-compose.yml & application.yml）中的通配符，包括 3.1 准备步骤中创建的资源和其余的一些默认如数据库设置等配置，以下图片和列表列出需要修改的Key及其含义： 选中要修改的Secret，点击Update 更新

3.2.3 运行流水线执行部署

• 流水线触发执行的条件是：

    on:
      push:
        branches:    
          - master
        paths: 
          - deployment/openvsx/**
          - .github/workflows/smartide-openvsx-deployment.yml
  

即修改 deployment/openvsx 文件夹下任何内容或修改流水线定义文件本身会自动触发，当我们对上述path内容任意做完一次提交后，将会Actions的自动化执行： 如果进行的是本地部署，不使用GitHub Action的情况下，需要在服务器上自行运行Docker-Compose 命令，Docker-Compose文件为 Deployment/Openvsx/Docker-Compose.yml

3.3 环境测试

• 流水线部署完毕后，即可登录 http://{server-host}:9000 端口网站使用 Portainer 查看 Server 容器运行情况
• 使用 http://{server-host}:8090 访问 pgadmin服务，查看数据库初始化情况
• 访问 https://marketplace.smartide.cn

至此，Marketplace 部署过程全部结束。

3.4 - Docker 安装说明

3.4.1 - Docker & Docker-Compose 安装手册 (Linux服务器)

SmartIDE可以使用任意安装了docker和docker-compose工具的linux主机作为开发环境远程主机，你的主机可以运行在公有云、私有云、企业数据中心甚至你自己家里，只要这台机器可以和互联网连通，就可以作为SmartIDE的远程主机。本文档描述正确安装docker和docker-compose工具以便确保SmartIDE可以正常管理这台远程主机。

环境要求列表

使用SmartIDE的远程主机需要满足以下要求

• 操作系统：
  • Ubuntu 20.04LTS, 18.04LTS, 16.04LTS
  • CentOS 7.2 以上
• 软件需求：
  • Git
  • Docker
  • Docker-Compose

特别说明：你无需在linux主机上安装SmartIDE CLI命令行工具，因为所有的操作都可以在本地开发机（Windows/MacOS）上完成，SmartIDE本身内置使用SSH远程操作linux主机。

配置非root用户登陆服务器

使用SmartIDE远程控制的linux主机需要使用非root用户登陆，这是为了确保更加安全的开发环境以及主机和容器内文件系统权限的适配。请按照以下操作创建用户并赋予免密码sudo权限。

备注：以下操作需要使用root账号或者sudo方式运行。

以下脚本将创建一个叫做 smartide 的用户并赋予面密码的sudo权限。

## 创建用户及用户文件系统
useradd -m smartide
## 为用户设置密码，请在命令执行后输入你需要设置的密码，确保你将这个密码记录下来
passwd smartide
## 为用户添加sudo权限
usermod -aG sudo smartide
## 编辑 /etc/sudoers
vim /etc/sudoers

如果使用vim编辑器，按 “i” 进入插入编辑模式，编辑完成后按ESC退出编辑模式，输入 “:wq!” 保存退出。

在 /etc/sudoers 文件中添加如下内容

smartide   ALL=(ALL) NOPASSWD: ALL

同时修改开头为 %sudo 的行为以下内容

%sudo   ALL=(ALL) NOPASSWD: ALL

配置用户使用bash作为默认的shell

SmartIDE 使用一些特定的bash指令完成工作区调度，因此请确保你所使用的用户或者以上所创建的smartide用户的默认shell为bash。

vim /etc/passwd

更新

smartide:x:1000:1000::/home/smartide:/bin/sh 

改为

smartide:x:1000:1000::/home/smartide:/bin/bash

一键安装docker和docker-compose工具

使用以上创建的smartide用户或者其他符合要求的非root用户登陆服务器。

使用以下命令在Linux主机上安装docker和docker-compose工具，运行完成之后请从当前终端登出并从新登入以便脚本完成生效。

# 通过ssh连接到你的Linux主机，复制并粘贴此命令到终端
# 注意不要使用sudo方式运行此脚本
curl -o- https://smartidedl.blob.core.chinacloudapi.cn/docker/linux/docker-install.sh | bash
# 退出当前登录
exit

完成以上操作后，请运行以下命令测试 docker 和 docker-compose 正常安装。

docker run hello-world
docker-compose -version

如何可以出现类似以下结果，则表示docker和docker-compose均已经正常安装。

完成以上2项设置之后，你就可以继续按照 快速启动 中 远程模式 部分的说明继续体验SmartIDE的功能了。

配置Sysbox

SmartIDE 的部分开发者镜像内使用了 VM-Like-Container 的能力，比如需要在容器内运行完整的docker，也就是嵌套容器（Docker in Docker - DinD）。类似的能力需要我们在主机上针对容器运行时（container runtime）进行一些改进。为了满足类似的能力，SmartIDE 采用了开源项目 sysbox 提供类似的容器运行时。

以下文档描述了如何在主机上安装 Sysbox容器运行时，在执行此操作之前，请确保已经按照本文档的上半部分正确安装了 docker环境。

本文档针对 sysbox 社区版的安装过程进行说明，如果需要安装企业版，请自行参考 sysbox 官方文档。

## 国内安装地址
wget https://smartidedl.blob.core.chinacloudapi.cn/hybrid/sysbox/sysbox-ce_0.5.2-0.linux_amd64.deb

## 国际安装地址
wget https://downloads.nestybox.com/sysbox/releases/v0.5.2/sysbox-ce_0.5.2-0.linux_amd64.deb

安装前需要通过执行以下命令移除当前正在运行的容器

docker rm $(docker ps -a -q) -f

执行以下指令完成安装

sudo apt-get install ./sysbox-ce_0.5.2-0.linux_amd64.deb

安装成功后通过执行以下命令来验证Sysbox是否安装成功并已启动服务，注意查看 active (running) 的提示信息

sudo systemctl status sysbox -n20

输出的信息如下图：

3.4.2 - Docker Desktop 安装手册 (MacOS)

Docker 桌面版（Docker Desktop）可以在桌面操作系统上管理容器化环境，SmartIDE本地模式需要调用Docker桌面版以便管理容器环境。安装这个工具其实非常简单，但是安装之后最好对工具的一些默认设置进行一些调整，以便让SmartIDE运行得更加高效。

硬件和操作系统要求

硬件要求：

• 2016款以后的MacBook, MacBook Pro或者Air都可以
• 最少4核8G，建议8核16G以上配置
• 最好使用SSD硬盘，并有100G以上空余存储空间

操作系统要求：

• 高于 OS 10.12
• 建议更新到最新版操作系统

下载安装包

Docker桌面是一款免费工具，大家可以从以下两个渠道下载：

• 官网下载地址 Docker Desktop
• 国内镜像
  • Intel芯片版下载地址
  • Apple M1芯片版下载地址

运行安装程序

双击下载的安装包文件，启动安装程序

按照图中提示，将左侧的Docker图标拖放到右侧的Application（应用程序）文件夹中，等待复制过程完成

打开 访达 ｜ 应用程序 并双击 Docker 图标

这时系统会有安全提示，选择 打开 即可

Docker启动需要一段时间，等待启动完毕，就可以使用了

启动中状态

启动完成状态

配置Docker桌面版

默认情况下Docker桌面版会对其所使用的资源比例采取比较保守的策略，因为我们需要在容器中运行开发环境，你可以根据自己本地开发机的配置适当调高以下设置以便获得更好的体验。

建议：至少给Docker分配4个以上的CPU Core和8G以上内存。

验证 Docker桌面版 可以正常工作

打开命令行窗口运行以下命令：

docker run hello-world

如果你看到了类似如下的输出，则表示你的Docker桌面版已经正常工作，你现在就可以继续按照 快速启动 继续体验SmartIDE的功能了。

3.4.3 - Docker Desktop 安装手册 (Windows)

Docker 桌面版（Docker Desktop）可以在桌面操作系统上管理容器化环境，SmartIDE本地模式需要调用Docker桌面版以便管理容器环境。安装这个工具其实非常简单，但是安装之后最好对工具的一些默认设置进行一些调整，以便让SmartIDE运行得更加高效。

硬件和操作系统要求

硬件要求：

• 最低i5，推荐i7处理器
• 最少4核8G，建议8核16G以上配置
• 最好使用SSD硬盘，并有100G以上空余存储空间

操作系统要求：

• Windows 10 2004 (Build 19041或者更高版本)
• Windows 11

老版本的Windows不支持WSL2，必须要使用HyperV或者VirtualBox虚拟机才能运行Docker，这样对系统资源占用很大，不建议使用。

下载安装包

Docker桌面是一款免费工具，大家可以从以下两个渠道下载：

• 官网下载地址 Docker Desktop
• 国内镜像
  • Windows安装包下载地址

启用WSL2

WSL2 是 Windows Subsystem for Linux 二代的简称，WSL2允许用户在Windows上运行受支持的Linux发行版。当前的Docker桌面版可以使用WSL2作为其Linux后台运行。因此我们需要首先在Windows操作系统上激活WSL2功能才能使用Docker做面板。

说明：Windows版本的Docker桌面其实也支持Windows容器，但是默认情况下我们更多的使用Linux容器作为我们的开发环境，因此在本文档中不会涉及对于Windows容器的配置。SmartIDE当前也不支持使用Windows容器作为开发环境。

步骤1 - 启动PowerShell

点击 开始按钮 ｜ 输入 PowerShell，选择 以管理员身份运行

步骤2 - 启用WSL2功能

在 PowerShell终端 窗口中输入以下命令以便激活 WSL功能

# 复制并粘贴本段脚本到PowerShell终端窗口中执行
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

执行过程输出如下

步骤3 - 启用虚拟化平台功能

在 PowerShell终端 窗口中输入以下命令以便激活 虚拟化平台 功能

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行过程输出如下

步骤4 - 下载并安装Linux内核更新包

点击一下链接下载并安装

• 适用于x64计算机的WSL2 Linux内核更新包

步骤5 - 将WSL2设置为默认版本

打开 PowerShell，然后在安装新的 Linux 发行版时运行以下命令，将 WSL 2 设置为默认版本：

wsl --set-default-version 2

步骤6 - 从Windows Store安装所需要的Linux分发版

打开 Microsoft Store，并选择你偏好的 Linux 分发版，推荐使用Ubuntu 20.04这个版本

安装完成后，点击 开始按钮 ｜ 输入 Ubuntu 并选择 打开

第一运行需要先对这个环境设置你自己的用户名和密码

至此，你的Windows为安装Docker桌面版做好了准备

运行安装程序

双击打开下载的安装包，确保选中以下选项，并点击 OK

• Install required Windows componenets for WSL2

安装程序需要从网络下载一些资源，请确保安装过程网络畅通

安装完成后，点击 Close，关闭安装程序

点击 开始按钮 ｜ 输入 Docker | 点击打开

点击 Accept 接受用户协议

等待 Docker 启动完毕

出现以下界面表示 Docker 已经正常启动，可以使用了。

配置Docker桌面版

默认情况下Docker桌面版会对其所使用的资源比例采取比较保守的策略，因为我们需要在容器中运行开发环境，你可以根据自己本地开发机的配置适当调高以下设置以便获得更好的体验。

因为我们指定Docker使用WSL2作为后台，因此我们无法通过Docker桌面版的配置工具直接修改资源占用情况。如果你打开 Docker 配置工具 会看到如下提示，提示用户要通过wslconfig配置文件来控制WSL的资源使用，以便控制Docker的资源占用。

你可以在 ～/.wslconfig 位置创建如下内容的文件，然后从新启动 Docker桌面版 即可。

[wsl2]
memory=8GB # Limits VM memory
processors=4 # Makes the WSL 2 VM use two virtual processors

有关wslconfig的详细配置请参考 配置 Linux 分发版 官方文档

建议给予WSL2至少8G内存和4以上的CPU Core以便获得比较好的使用体验。

验证 Docker桌面版 可以正常使用

打开命令行窗口运行以下命令：

docker run hello-world

如果你看到了类似如下的输出，则表示你的Docker桌面版已经正常工作，你现在就可以继续按照 快速启动 继续体验SmartIDE的功能了。

3.5 - K8S环境初始化说明

所需资源

配置一个K8S类型的工作区资源，那么就需要具备2-3个基本条件：

• 1. 一个K8S集群，作为开发资源。这里可以是私有的K8S集群，也可以是云平台的K8S集群服务。
• 2. 一个域名，将域名指向K8S集群对外暴露的访问地址，这样就可以通过不同的域名地址访问到集群不同的工作区命名空间。这里可以是私有部署的DNS域名解析服务，或者共有云的域名解析。
• 3. 一对证书公私钥（可选），若要启用 https 访问工作区环境并使用静态证书保护访问请求，请预先准备一对证书的公私钥文件，如：ssl.crt 和 ssl.key。 如需创建自签名证书，请参考如下链接的 Part 1 内容：申请OpenSSL自签名证书

启用VMLC

如果需要在k8s集群中使用VMLC环境，需要首先运行以下脚本对集群进行初始化。

注意：此操作当前只支持Ubuntu节点，并且需要k8s版本在1.21-1.23范围内，具体请参考 sysbox官方文档

运行以下操作会造成节点上当前运行的所有pod重新启动，建议仅在新节点或者新集群上运行。

## 获取节点名称
kubectl get nodes
## 在节点上添加 sysbox-install=yes 的 label
kubectl label nodes <节点名称> sysbox-install=yes
## 安装 sysbox container runtime
### 国内安装地址
kubectl apply -f https://gitee.com/smartide/SmartIDE/raw/main/deployment/k8s/sysbox-install-cn.yaml
### 国际安装地址
kubectl apply -f https://raw.githubusercontent.com/SmartIDE/SmartIDE/main/deployment/k8s/sysbox-install.yaml

运行以上指令后需要观察 sysbox-deploy pod进入运行状态，并且其他运行在节点上的pod重启完毕后，如果没有报错，代表安装成功。

下图：sysbox-deploy pod创建中

下图：同节点上的其他pod重新启动中

注意：弹性扩展节点配置

若使用资源为弹性缩扩容节点时，为保证新节点可以自动启用VMLC特性，那么需要进行相应配置。

例如：在Azure K8S中，可通过如下命令对节点池进行设置，那么弹性扩展时，新节点将会自动打上sysbox-install安装标记，并自动完成VMLC特性的安装。

az aks nodepool update \
    --resource-group smartide-k8s-test \
    --cluster-name smartide-k8s-test \
    --name nodepool1 \
    --labels sysbox-install=yes \
    --no-wait

其中：

• resource-group : 资源组名称
• cluster-name : 集群名称
• name : 节点池名称

资源初始化

准备好所需资源后，就可以使用 SmartIDE Server 添加K8S资源功能自动初始化集群：

第一步，SmartIDE Server 添加 K8S 集群资源

在SmartIDE Server资源管理中，选择【新建K8S】创建资源：

填写对应K8S集群信息：

• 域名：预分配给当前集群的访问域名，如 ws-cn-east.smartide.cn
• 团队：当前资源所属的团队，团队成员可共享使用
• Kube Config：K8S配置信息，内容默认文件路径:~/.kube/config
• 集群应用设置支持三种证书策略：
  1. 仅http，不开启https： 用户选择不开启https验证，则集群的所有应用统一使用http的方式启动，如果用户不关心是否使用https访问IDE/应用地址，则可以选择使用此种方式。
  2. 静态 https： 用户可以使用自维护的静态证书来配置集群工作区的IDE/应用访问链接，这种策略要求用户提前准备一对证书的公私钥，并在创建集群时复制公私钥的内容粘贴到资源的信息中。 用户使用此证书策略配置集群之后，后续所有工作区的访问链接将默认使用用户提供的证书来加密。此策略适合在内网环境下开启https访问的场景。
  3. 动态 https： SmartIDE Server 同时也提供了系统自申请https证书的功能，用户可以在外网环境下选择使用动态 https证书策略，系统将会为每个工作区的每个应用地址自动化申请https证书。 此场景需要Server能够连通外网环境的支撑。

点击保存后，资源创建完毕，系统开始自动初始化集群：

• 创建 Ingress Controller 服务
• 根据证书策略，创建静态证书秘钥或安装动态证书所需的Cert-Manager服务
• 安装 Storage Class

初始化集群过程会持续几分钟，初始化完毕后，系统将会自动获取到 Ingress Controller 服务的 External IP 显示到资源详情界面上： 此IP是集群对外统一提供服务的地址，接下来需要将此IP地址和集群的预分配域名进行DNS绑定。

第二步，域名、泛域名配置。

通过DNS域名配置，将域名指向K8S集群的Ingress Controller Nginx服务，这样我们就可以通过域名访问到不同的工作区服务了。

在域名解析服务器上设置K8S对外服务域名解析，添加两条指向 External IP 的A记录。这里，可以参考如下的阿里云域名设置，这里添加了 ws-cn-east、*.ws-cn-east 两条解析记录：

域名配置完成后，就可以在SmartIDE Server中使用这个资源了！

SmartIDE Server使用方法，详见：SmartIDE Server 快速开始

技术支持

如果您在以上安装过程或者日常使用过程中遇到问题，请通过提交 Issue 的方式与我们取得联系。

也可以加入我们的 SmartIDE 早鸟群获取第一手的产品资料和技术支持。

4 - 快速开始 - 开发从未如此简单

4.1 - SmartIDE CLI 快速开始

作为开发者，你无需了解什么是云，什么是容器，也无需学习复杂的docker命令，你所需要的就是学会一个简单的命令（smartide start），即可真正实现“一键启动”开发环境.

你也无需在本地安装IDE软件，只需要浏览器就够了。SmartIDE内置了Web版的vscode，你只需要打开浏览器就可以进行编码，使用智能提示，设置断点并且进行交互式单步调试，就如同使用一个全功能的IDE软件一样的体验。

以下为文档演示视频，视频长度4:40，无快进无剪辑。

准备工作

请参考 安装手册 完成 SmartIDE 工具的安装。

本地模式

本地模式允许用户在已经安装了Docker Desktop的本地开发机上，运行并管理运行在容器中的开发调试环境。这种模式下SmartIDE会根据代码库中预置的配置文件（位于 .ide/.ide.yaml）完成拉取开发容器镜像，启动容器，代码目录映射以及WebIDE的启动。

1. 一键启动

运行以下脚本一键启动 Boathouse计算器 应用的 集成开发环境(IDE) 。

• MacOS
• Windows

# 在 MacOS 上打开 终端应用(Terminal) 并复制粘贴本段脚本
smartide start https://gitee.com/idcf-boat-house/boathouse-calculator.git 

# 在 Windows 上打开 PowerShell 并复制粘贴本段脚本
smartide start https://gitee.com/idcf-boat-house/boathouse-calculator.git 

运行后的效果如下：

2. 编码调试

SmartIDE会自动启动内置的WebIDE，你会看到一个类似vscode的IDE窗口在你的默认浏览器中出现。

同时，SmartIDE会自动启动 npm install 脚本的运行，自动完成依赖包的获取和安装。

说明: npm是node.js的包管理器，npm install 的作用是获取应用所需要的依赖包。一般来说，为了能够正确运行 node.js 应用，你首先需要安装 node.js 的 sdk 环境，但是 SmartIDE 已经为完成了这个动作，作为开发者的你不再需要关心开发环境搭建的问题。

完成以上操作后，你可以直接点击 WebIDE 左侧的调试工具栏，启动调试。

你也可以像我一样在 /api/controllers/arithmeticController.js 文件的 第47行 设置一个断点，并用另外一个浏览器打开 http://localhost:3001 即可进入交互式调试状态。现在，你可以尝试在计算机中进行一些加减乘除的操作，当你点击 = 按钮的时候，代码中的断点就会被触发，应用进入暂停状态，IDE会自动聚焦到断点所在的代码行，如下图所示：

到这里，你已经完成了 Boathouse计算器示例应用 的开发调试过程，一切的操作就像在本地使用vscode一样的顺畅。

远程模式

远程模式允许用户通过SSH调度远程linux主机，并在远程主机上根据预置在代码库中的配置文件（文件位置：.ide/.ide.yaml）完成拉取开发容器镜像，启动容器，代码映射和启动容器内的WebIDE的一系列动作；在开发容器启动成功后，SmartIDE CLI（命令行工具）会作为驻守程序监听远程容器中开发的端口并将这些端口通过SSH隧道的方式转发到本地开发机上，允许用户通过localhost访问，达到“远程开发，本地体验”的目录。

使用远程模式也非常简单，只需要2个步骤

1. 准备远程主机

按照 Docker & Docker-Compose 安装手册 (Linux服务器) 准备远程linux主机

2. 启动环境

使用以下命令添加主机记录并启动SmartIDE环境

• MacOS
• Windows

# 在 MacOS 上打开 终端应用(Terminal) 并复制粘贴本段脚本
## 添加远程主机
smartide host add <ip地址> --username <用户名> --password <密码> --port 22
## 获取远程主机ID
smartide host list 
## 使用远程主机ID和git库地址启动SmartIDE远程开发环境
smartide start --host <远程主机ID> https://gitee.com/idcf-boat-house/boathouse-calculator.git 

# 在 Windows 上打开 PowerShell 并复制粘贴本段脚本
## 添加远程主机
smartide host add <ip地址> --username <用户名> --password <密码> --port 22
## 获取远程主机ID
smartide host list 
## 使用远程主机ID和git库地址启动SmartIDE远程开发环境
smartide start --host <远程主机ID> https://gitee.com/idcf-boat-house/boathouse-calculator.git 

远程模式启动后的使用体验与本地模式保持一致。

各类技术栈的操作入口

Boathouse计算器 是一个已经适配好 SmartIDE 开发环境的应用，如果你希望了解如何使用 SmartIDE 从头创建一个全新的项目，我们还为你准备了一系列针对不同开发技术栈的快速启动教程：

• Node.JS
• Golang
• Java
• .NetCore
• Python
• PHP
• C/C++

开源项目项目SmartIDE适配

我们还对很多 开源项目 进行了SmartIDE适配，你可以通过 示例应用 获取更多示例应用的体验文档，示例部分所展示的全部都是真实项目的开发场景，包括 SmartIDE 本身其实都是使用 SmartIDE 开发环境进行开发的。

这些示例包括：

• IDCF黑客马拉松Boathouse应用前后端联调
• 使用SmartIDE开发smartide.dev网站
• 使用SmartIDE开发smartide-cli应用
• 使用SmartIDE开发smartide开发容器镜像
• Vue Element Admin
• Element UI
• iTop

更多示例会持续更新

已有私有项目SmartIDE适配

如果是自己或团队内的私有项目，也可以使用SmartIDE提供的开发容器进行开发。具体适配方式请参考 项目适配 文档

感谢您对SmartIDE的支持：Be a Smart Developer，开发从未如此简单。

4.2 - SmartIDE Server 快速开始

概述

SmartIDE Server 为开发团队提供对开发环境的统一在线管理和访问能力，企业管理者可以通过SmartIDE Server为开发团队提供统一的一致的开发环境，大幅降低开发者花费在搭建环境上的时间消耗，让开发者可以将更多的精力投入到业务需求开发和技术方案改进上。更为重要的是，SmartIDE Server提供了完全受控的开发测试环境，管理者可以通过工作区策略对开发环境进行管理，比如：

• 端到端的代码安全：通过策略配置实现开发者只能通过浏览器修改和发布代码，完全避免开发者将代码下载到个人开发机上；
• 质量左移：通过指定制定策略在开发者提交代码之前就进行质量门禁的验证，从而彻底杜绝有问题的代码进入代码仓库；
• 优化DevOps流水线：通过提供与生产环境一致的开发测试环境部署方式，大幅降低DevOps流水线的复杂度，并通过将更多的串行的流水线环节集成到开发编码过程中，大幅缩短流水线运行时间并提高部署成功率。

SmartIDE Server 使用容器和云原生技术，可以部署在任何标准的虚拟化或者k8s平台上，企业云管理员可以自行完成SmartIDE Server的私有部署，并将企业内部开发团队的开发测试环境纳入企业云的管理之中。开发测试环境一旦纳入云平台的管理可以有效降低企业内部开发测试环境的管理复杂度，提高资源利用率；容器化开发测试环境可以根据开发者的需要动态的创建或者销毁环境，为开发测试环境提供弹性伸缩能力。与当前企业中大量使用的基于VDI的开发测试环境管理模式相比，基于容器的开发测试环境将大幅提高资源利用率，同时大幅降低成本。

对于开发者而言，使用SmartIDE Server可以完全消除开发者搭建环境的技能要求，避免因为环境不一致或者工具/SDK版本，安装配置问题所造成的时间浪费，让开发者将更多的精力投入到更有价值的应用开发中去。对于团队而言，当一个团队成员开始使用SmartIDE以后，其他开发者就可以完全重用这个环境，而不必重新配置；如果一名成员变更了环境配置，其他的成员也可以通过一个简单的git pull就可以获取到这个变更后的开发环境。

操作视频

为了便于大家更直观地了解和使用SmartIDE Server，我们在B站提上提供了视频供大家参考，视频如下：

跳转到B站： https://www.bilibili.com/video/av553362128

操作手册

使用SmartIDE你可以在5分钟内完成任何开发语言，任何代码的开发环境搭建。以下，我们以IDCF Boathouse 计算器应用为例，说明如何使用SmartIDE Server进行这个应用的开发和调试过程。

1. 登录

首先，让我们登录到SmartIDE Server，我们提供了托管的SmartIDE Server环境，当前这个环境仍然处于内测阶段，账号需要我们的管理员为您创建，暂时不开放自助注册功能。如果您需要访问我们托管的SmartIDE Server，可以扫描以下二维码加入我们的社区早鸟计划。

a. 请访问SmartIDE Server版网站：http://dev.smartide.cn/，登录Server版：

b. 输入已分配的账号、密码，以及验证码，点击【登录】：

c. 登录后，进入SmartIDE首页：

到这里，我们就完成了SmartIDE Server端登录。

d. CLI客户端登录

说明：当前，SmartIDE仅支持通过cli建立安全隧道（SSH Tunnel）的方式的方式访问工作区，所以这里我们需要安装并通过CLI客户端完成登录，连接Server。未来我们会提供完全在线的方式，这样就可以通过一个简单的URL来访问你的工作区。
CLI具体安装操作见：客户端安装。

通过 se connect 命令连接server工作区：

这样我们本地计算机就通过CLI客户端与Server的建立起连接了。

2. 创建资源

资源是SmartIDE Server用于管理主机和k8s的方式，用户可以将自己的主机或者k8s集群加入到SmartIDE Server中进行统一管理。一旦资源纳入SmartIDE Server的管理，就可以通过以下的工作区管理功能在对应的资源上运行容器化开发环境，并通过WebIDE的方式进行访问。

说明：当前仍未开放k8s资源的管理特性，请持续关注我们的开发进展，我们会在第一时间通知您最新的特性列表。

a. 点击左侧【资源管理】菜单，进入资源管理列表后，点击【新增Linux主机】按钮，添加主机资源：

说明：添加主机前，需要主机已完成 SmartIDE初始化配置 。

在这里，需要填写以下信息：

• 名称：自定义资源的名称，后续在新建工作区时，可以选择工作区所部署的资源。
• 资源类型：选择Linux主机。
• HOST：已准备好的Linux主机IP地址。
• 用户名/密码：已配置好SmartIDE初始化环境的主机用户名密码。不推荐使用root账号。

填写完毕后，点击【确定】按钮。

b. 创建成功后，列表中，可以看到刚刚添加的记录。

3. 创建并连接在线工作区，进行编码及调试

工作区是SmartIDE中用于管理开发环境的单元，每个代码版本对应一个工作区。当你完成了资源创建后，就可以通过工作区管理，在这些资源上创建工作区了。

注意：我们使用的Boathouse计算器中已经适配了SmartIDE工作区，如果你需要在SmartIDE中运行其他代码的开发环境，请参考 项目适配 文档。

a. 资源创建完毕后，点击【工作区管理】，进入工作区列表，此时点击【新增工作区】按钮。

这里输入工作区名称，选择刚刚建立的主机资源，并且输入git克隆地址，点击【确定】按钮。

b. 新增工作区后，在工作区列表中查看到工作区记录及其运行状态。点击工作区【详情】按钮，进入工作区。

c. 工作区详情中，我们可以看到工作区已经处于部署之中，并且会刷新状态。启动成功后，工作区变为【已启动】状态，并且因为我们在项目中通过SmartIDE配置文件.ide.yaml进行了IDE及端口声明，所以可以明确地看到工作区要对应的IDE图标以及应用访问地址，如下图所示：

d. 点击IDE图标，打开WebIDE界面，如下图：

e. 这时，就可以在打开的WebIDE界面中，像使用本地IDE那样，进行代码的开发以及调试了：

说明：有关如何在WebIDE中开发和调试Node.js应用的方法，请参考 cli快速启动 和 node快速启动 文档。

私有化部署

SmartIDE Server提供私有化部署，你可以在任何公有云/私有云，甚至虚拟机上完成私有部署。有关私有部署的详细操作手册，请持续关注此文档。

感谢您对SmartIDE的支持：Be a Smart Developer，开发从未如此简单。

4.3 - Node 快速启动教程

SmartIDE内置了node.js开发环境模板，你可以通过一个简单的指令创建带有WebIDE的开发环境，并立即开始编码和调试。

如果你还没有完成SmartIDE安装，请参考 SmartIDE 安装手册 安装SmartIDE命令行工具。

说明：SmartIDE的命令行工具可以在Windows、MacOS和Linux操作系统上运行，对大多数命令来说，操作是完全一致的。本文档中虽然使用的是MacOS上的截图，但是其他操作系统环境的所有日志和工作状态完全一致。对于脚本格式有区别的地方，我们会同时提供2套脚本。

VSCode

1. 创建开发环境

运行以下命令创建node开发环境：

# 在 MacOS/Windows 上打开 终端（Terminal）或者 PowerShell 应用
# 执行以下命令
mkdir sample-node-vscode 
cd sample-node-vscode  
smartide new node -T vscode

运行后的效果如下，你可以通过命令窗口中的日志详细了解 SmartIDE 的启动过程，当 SmartIDE 启动完毕之后，会自动打开浏览器窗口并导航 WebIDE 界面。

启动WebIDE内置的Terminal

后续的操作我们会通过 WebIDE 内置的 Terminal 来完成，默认情况下 Web Terminal 应该已经自动打开，如果没有的话，可以通过 WebIDE 内置菜单的 Terminal | New Terminal 打开新的 Web Terminal 窗口。

Web Terminal 开启后如下图所示：

2. 创建并配置项目

注意：如果没有特别提示，后续的命令都是在这个 Web Terminal 中运行的。

运行以下命令将 node 包管理器 npm 的源地址设置到国内淘宝镜像，这样可以明显改善后续的操作流畅性。

npm config set registry https://registry.npmmirror.com

运行以下命令安装 express 脚手架工具并创建 node express 项目基础代码结构

npm install -g express-generator
express --view=pug myapp

执行完毕后的效果如下，左侧文件管理器里面已经出现了 myapp 文件夹，并在其中创建了 node express 应用的基础代码结构，右侧 Terminal 窗口中列出了创建过程的日志信息。

使用以下内容对 /myapp/package.json 文件进行全文替换，这里我们设置了几个关键配置

• 设置了 npm start 启动脚本使用 production 环境变量和 3001 端口
• 设置了 npm run dev 启动脚本使用 development 环境变量、 3001 端口，并且使用 nodemon 工具提供更好的调试体验

{
  "name": "myapp",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "start": "NODE_ENV=production PORT=3001 node ./bin/www",
    "dev": "NODE_ENV=development PORT=3001 nodemon --inspect --exec node ./bin/www"
  },
  "dependencies": {
    "cookie-parser": "~1.4.4",
    "debug": "~2.6.9",
    "express": "~4.16.1",
    "http-errors": "~1.6.3",
    "morgan": "~1.9.1",
    "pug": "2.0.0-beta11",
    "nodemon": "~2.0.15"
  }
}

创建 /.vscode/launch.json 文件，并写入如下内容：

注意：.vscode 目录一定要放置在工作区根目录中

• 此文件为 vscode 的调试器启动配置文件，因此我们的代码结构兼容使用vscode桌面版直接进行开发调试
• 配置了 debugger 的启动命令为 package.json 所定义的 npm run dev 脚本

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch via NPM",
            "type": "node",
            "request": "launch",
            "cwd": "${workspaceFolder}/myapp/",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run","dev"],
            "port": 9229 
        }
    ]
}

现在我们可以运行脚本完成 npm 依赖包的安装

cd myapp
npm install

运行后的效果如下：

3. 开发调试

完成以上配置之后，你的代码已经完全准备好，可以开始进行编码调试了。

在 /myapp/routes/users.js 文件的 第6行 代码处 单击设置断点

点击 左侧菜单栏 ｜ 调试按钮 ｜ 点击 启动按钮 启动交互式调试

启动调试后，请注意 smartide 的日志输出，SmartIDE 会在后台持续监控容器内的进程情况，并将所有端口转发到 localhost 上

现在你可以开启一个新的浏览器，按照日志中所提示的 3001 端口，打开 http://localhost:3001，就可以访问这个应用了。进入交互式调试状态的 SmartIDE 开发环境如下图：

现在，让我们打开 http://localhost:3001/users 以便触发我们之前所设置的断点，注意下图中的几个关键点

1. 通过打开 http://localhost:3001/users 这个地址触发我们预设的断点
2. 将鼠标移动到特定的变量上以后，IDE 会自动加载当前变量的结构体以及赋值状态（实时），方便开发者观察运行时状态
3. Variables (变量) 窗口实时显示当前运行时内的变量状态
4. Call Stack (调用堆栈) 窗口实时显示当前运行时堆栈状态

保持以上调试状态，直接对代码进行修改，打开 /myapp/routes/users.js 文件并将 第6行 按下图进行修改，修改完成后保存文件，并按下 调试控制拦 上的 继续按钮

此时，你可以看到左侧应用运行窗口中已经按照你的修改自动加载了修改后的代码。

此功能借助 nodemon 对代码文件进行性监控，并在检测到改动的时候自动进行重新编译；以上我们所配置的 package.json 和 launch.json 的配置是实现这一场景的关键性配置。如果你发现你的环境无法完成以上操作，请仔细检查这两个文件的内容。

至此，我们已经使用 SmartIDE 完成了一个 Node Express 应用程序的创建，配置和编码调试过程。

4. 提交并分享

SmartIDE 环境中已经内置了 Git 的支持，你可以点击 菜单栏左侧 ｜ 源代码管理 ｜ 点击 Initialize Repository 按钮 将当前工作区初始化成一个 Git代码库。

在 提交注释 中填写 使用SmartIDE创建，然后点击 提交按钮

点击 Remote | Add Remote 按钮，添加一个远端 Git库 地址。SmartIDE 支持任何Git服务，包括：GitHub, Gitlab, Azure DevOps, Gitee 等等。

这时，我们可以将创建的这份代码推送到了类似Gitee的代码仓库上，代码库地址类似如下 https://gitee.com/smartide/sample-node-vscode

至此，我们已经使用 SmartIDE 完成了一个 Node Express 应用从环境搭建，创建基础代码结构，配置调试环境，完成编码开发到提交代码的全过程。

现在可以将你的代码库发送给其他的小伙伴，让他通过以下指令一键启动你的应用。

smartide start https://gitee.com/smartide/sample-node-vscode

是不是很爽！

JetBrains WebStorm

1. 新建开发环境

运行以下命令创建React前端项目开发环境：

mkdir sample-node-webstorm
cd sample-node-webstorm
smartide new node -T webstorm

运行后的效果如下，你可以通过命令窗口中的日志详细了解 SmartIDE 的启动过程，当 SmartIDE 启动完毕之后，会自动打开浏览器窗口并导航 WebIDE 界面。

2. 创建并配置项目

• 点击创建项目

这里我们选择创建一个React 前端项目，注意修改项目默认保存的路径和Node版本

SmartIDE提供的WebStorm镜像中，集成了三个版本的NodeJS和nvm，分别为：V14.17.6(默认)、V12.22.7、V16.7.0, 如果要切换node版本，可以使用nvm指令，比如如果想切换到V16.7.0,可以在Terminal输入命令：nvm use 16.7.0

点击创建后，WebStorm 会自动下载依赖包，等待下载完。

国内环境有可能会下载失败，可能需要修改npm registry 为国内淘宝源。

启动WebIDE内置的Terminal

后续的操作我们会通过 WebIDE 内置的 Terminal 来完成，点击窗口底部的 Terminal 即可打开命令行窗口

注意：如果没有特别提示，后续的命令都是在这个 Web Terminal 中运行的。

运行以下命令将 node 包管理器 npm 的源地址设置到国内淘宝镜像，这样可以明显改善后续的操作流畅性。

npm config set registry https://registry.npmmirror.com
npm config get registry

如果项目初始完成后，可以看到以下内容，这时可以启动项目进行预览了。启动前，先打开文件app.tsx，添加一段代码:Hello SmartIDE!

3. 启动项目

然后在Terminal输入启动命令：PORT=3001 npm start

等启动后，可以看到以下内容，在本机浏览器输入：http://localhost:3001/ , 即可查看Web应用

4. 提交并分享

先初始化git仓库

在 提交注释 中填写 使用SmartIDE创建，然后点击 提交按钮

添加一个远端 Git库 地址。SmartIDE 支持任何Git服务，包括：GitHub, Gitlab, Azure DevOps, Gitee 等等。

最后推送代码

这时，我们可以将创建的这份代码推送到了类似Gitee的代码仓库上，代码库地址类似如下 https://gitee.com/smartide/sample-node-webstorm

至此，我们已经使用 SmartIDE 完成了一个React前端 应用从环境搭建，创建基础代码结构，完成编码开发到提交代码的全过程。

现在可以将你的代码库发送给其他的小伙伴，让他通过以下指令一键启动你的应用。

smartide start https://gitee.com/smartide/sample-node-webstorm

是不是很爽！

OpenSumi

1. 创建开发环境

运行以下命令创建node开发环境：

# 在 MacOS/Windows 上打开 终端（Terminal）或者 PowerShell 应用
# 执行以下命令
mkdir sample-node-opensumi 
cd sample-node-opensumi 
smartide new node -T opensumi

运行后的效果如下，你可以通过命令窗口中的日志详细了解 SmartIDE 的启动过程，当 SmartIDE 启动完毕之后，会自动打开浏览器窗口并导航 WebIDE 界面。

启动WebIDE内置的Terminal

后续的操作我们会通过 WebIDE 内置的 Terminal 来完成，默认情况下 Web Terminal 应该已经自动打开。

Web Terminal 开启后如下图所示：

2. 创建并配置项目

注意：如果没有特别提示，后续的命令都是在这个 Web Terminal 中运行的。

运行以下命令将 node 包管理器 npm 的源地址设置到国内淘宝镜像，这样可以明显改善后续的操作流畅性。

npm config set registry https://registry.npmmirror.com

运行以下命令安装 express 脚手架工具并创建 node express 项目基础代码结构

npm install -g express-generator
express --view=pug myapp

执行完毕后的效果如下，左侧文件管理器里面已经出现了 myapp 文件夹，并在其中创建了 node express 应用的基础代码结构，右侧 Terminal 窗口中列出了创建过程的日志信息。

使用以下内容对 /myapp/package.json 文件进行全文替换，这里我们设置了几个关键配置

• 设置了 npm start 启动脚本使用 production 环境变量和 3001 端口
• 设置了 npm run dev 启动脚本使用 development 环境变量、 3001 端口，并且使用 nodemon 工具提供更好的调试体验

{
  "name": "myapp",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "start": "NODE_ENV=production PORT=3001 node ./bin/www",
    "dev": "NODE_ENV=development PORT=3001 nodemon --inspect --exec node ./bin/www"
  },
  "dependencies": {
    "cookie-parser": "~1.4.4",
    "debug": "~2.6.9",
    "express": "~4.16.1",
    "http-errors": "~1.6.3",
    "morgan": "~1.9.1",
    "pug": "2.0.0-beta11",
    "nodemon": "~2.0.15"
  }
}

创建 /.sumi/launch.json 文件，并写入如下内容：

注意：.sumi 目录一定要放置在工作区根目录中

• 此文件为 opensumi 的调试器启动配置文件
• 配置了 debugger 的启动命令为 package.json 所定义的 npm run dev 脚本

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch via NPM",
            "type": "legacy-node",
            "request": "launch",
            "cwd": "${workspaceFolder}/myapp/",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run","dev"],
            "port": 9229 
        }
    ]
}

现在我们可以运行脚本完成 npm 依赖包的安装

cd myapp
npm install

运行后的效果如下：

3. 开发调试

完成以上配置之后，你的代码已经完全准备好，可以开始进行编码调试了。

在 /myapp/routes/users.js 文件的 第6行 代码处 单击设置断点

点击 左侧菜单栏 ｜ 调试按钮 ｜ 点击 启动按钮 启动交互式调试

启动调试后，请注意 smartide 的日志输出，SmartIDE 会在后台持续监控容器内的进程情况，并将所有端口转发到 localhost 上

现在你可以开启一个新的浏览器，按照日志中所提示的 3001 端口，打开 http://localhost:3001，就可以访问这个应用了。进入交互式调试状态的 SmartIDE 开发环境如下图：

现在，让我们打开 http://localhost:3001/users 以便触发我们之前所设置的断点，注意下图中的几个关键点

1. 通过打开 http://localhost:3001/users 这个地址触发我们预设的断点
2. 将鼠标移动到特定的变量上以后，IDE 会自动加载当前变量的结构体以及赋值状态（实时），方便开发者观察运行时状态
3. Variables (变量) 窗口实时显示当前运行时内的变量状态
4. Call Stack (调用堆栈) 窗口实时显示当前运行时堆栈状态

至此，我们已经使用 SmartIDE 完成了一个 Node Express 应用程序的创建，配置和编码调试过程。

4. 提交并分享

SmartIDE 环境中已经内置了 Git 的支持，你可以点击 菜单栏左侧 ｜ 源代码管理 ｜ 点击 Initialize Repository 按钮 将当前工作区初始化成一个 Git代码库。

在 提交注释 中填写 使用SmartIDE创建，然后点击 提交按钮

点击 Remote | Add Remote 按钮，添加一个远端 Git库 地址。SmartIDE 支持任何Git服务，包括：GitHub, Gitlab, Azure DevOps, Gitee 等等。

至此，我们已经使用 SmartIDE 完成了一个 Node Express 应用从环境搭建，创建基础代码结构，配置调试环境，完成编码开发到提交代码的全过程。

这时，我们可以将创建的这份代码推送到了类似Gitee的代码仓库上，代码库地址类似如下 https://gitee.com/smartide/sample-node-opensumi

现在可以将你的代码库发送给其他的小伙伴，让他通过以下指令一键启动你的应用。

smartide start https://gitee.com/smartide/sample-node-opensumi

是不是很爽！

远程开发

上面我们已经使用SmartIDE的本地工作区模式完成了一个应用的创建和开发过程，这个过程和你所熟悉的开发模式有2个区别，1）我们使用了VSCode/Webstorm/OpenSumi WebIDE；2）开发环境全部通过容器获取并运行。

在这个过程中你的项目代码也已经具备了远程开发的能力，你可以按照以下文档中的说明使用任意一种远程工作区来开发调试你的应用

• 远程主机工作区
• k8s工作区
• Server工作区

另外，你也可以通过VSCode或者JetBrains内置的远程开发模式进行Hybird模式的远程开发，具体请参考

• IDE远程开发操作手册

感谢您对SmartIDE的支持：Be a Smart Developer，开发从未如此简单。

4.4 - .NET 快速启动教程

SmartIDE内置了.NET 6开发环境模板，你可以通过一个简单的指令创建带有WebIDE的开发环境，并立即开始编码和调试。

如果你还没有完成SmartIDE安装，请参考 SmartIDE 安装手册 安装SmartIDE命令行工具。

说明：SmartIDE的命令行工具可以在Windows和MacOS操作系统上运行，对大多数命令来说，操作是完全一致的。本文档中虽然使用的是MacOS上的截图，但是Windows环境的所有日志和工作状态完全一致。对于脚本格式有区别的地方，我们会同时提供2套脚本。

VSCode

1. 创建开发环境

运行以下命令创建.NET 6开发环境：

# 在 MacOS/Windows 上打开 终端（Terminal）或者 PowerShell 应用
# 执行以下命令
mkdir sample-dotnet-vscode 
cd sample-dotnet-vscode
smartide new dotnet -T vscode

运行后的效果如下，通过命令窗口中的日志详细了解SmartIDE的 启动过程，会自动打开浏览器窗口并导航到VSCode界面，输入

#检查dotnet sdk 版本
dotnet --version

你可以看到dotnet sdk 6.0已经安装完毕。

2. 创建ASP.NET Core minimal web API 项目

基于刚才搭建的环境中已经集成了dotnet sdk，现在只需要打开VS Code编辑器的命令行终端执行如下指令来初始化一个基于 ASP.NET Core 的minimal web API项目

# 初始化dotnet minimal web api 项目
dotnet new webapi -minimal -o TodoApi

执行成功后Web Api项目已经初始化成功了如下图：

打开VS Code 命令终端执行如下命令安装EntityFrameworkCore工具包：

# 访问TodoApi项目文件夹
cd TodoApi
# 安装Nuget包（Microsoft.EntityFrameworkCore.InMemory）
dotnet add package Microsoft.EntityFrameworkCore.InMemory
# 安装Nuget包（Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore）
dotnet add package Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore

修改Program.cs文件，代码如下：

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseSwagger();
app.UseSwaggerUI();

app.MapGet("/", () => "Hello World!");

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id)
        is Todo todo
            ? Results.Ok(todo)
            : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);

    if (todo is null) return Results.NotFound();

    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;

    await db.SaveChangesAsync();

    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.Ok(todo);
    }

    return Results.NotFound();
});

app.Run();

class Todo
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

class TodoDb : DbContext
{
    public TodoDb(DbContextOptions<TodoDb> options)
        : base(options) { }

    public DbSet<Todo> Todos => Set<Todo>();
}

继续执行如下命令确保当前项目初始化正确：

# 编译dotnet TodoApi项目
dotnet build
# 启动dotnet TodoApi项目
dotnet run

如果输出结果如下图，说明当前初始化项目能编译通过并且可以正常启动

通过启动项目输出的日志了解当前初始化项目默认设置的端口为7163与5105 与SmartIDE初始化的环境开放的端口不一致，访问.ide文件夹下的.ide.yaml

你会看到端口是可以通过当前文件进行配置的，这里默认开放的端口如下：

• 6822映射容器的22端口用于ssh连接访问
• 6800映射容器的3000端口用于web ide窗口访问
• 5000映射容器的5000端口用于对你当前开发项目的访问

访问TodoApi项目下的Properties文件夹下的launchSettings.json文件

修改 applicationUrl 属性如下：

"applicationUrl": "http://0.0.0.0:5000",

由于localhost指的是127.0.0.1是一个回环地址，这个地址发出去的信息只能被自己接受，所以宿主机是无法通过这个IP地址访问进来的，0.0.0.0表示的是所有的IPV4地址，如果当前的宿主机有多个IP地址，并且0.0.0.0开放了5000端口，那么该端口均可以被这些IP访问到，再次启动项目，访问地址 http://localhost:5000/swagger 如下图：

3. 开发调试

通过之前的操作我们已经可以对项目进行编译运行的操作了，想要对当前项目进行调试操作还需要做额外配置，点击 VS Code 的 Run and Debug 中的 create a launch.json file 按钮如下图：

点击后并选择 .NET 5+ and .NET Core，执行完上述操作后会创建一个名为.vscode的文件夹里面包含两个文件如下图：

修改 vscode文件夹下的 launch.json 文件中的args属性如下：

 "args": ["--urls","http://0.0.0.0:5000"],

回到 Run and debug 页面点击Run and debug 按钮，VS code会出现 Start Debugging 按钮点击它或者按F5键即可进入该项目的调试模式，如下图：

设置调试断点，如下图：

访问swagger页面触发标记断点的api接口，访问 http://0.0.0.0:5000/ 可以看到当前的Http请求停止在了已设置的断点

之前添加的代码是通过minimal api 完成的增删改查的操作，触发Post/ todoitems 的api可以完成插入数据的操作如下图：

通过触发api Get/ todoitems可以直接查询到之前插入过的数据，如下图：

JetBrains Rider

JetBrains Rider 是由JetBrains公司开发的一个跨平台的.NET IDE工具，不同于VSCode，JetBrains Rider构建.Net 项目并不需要单独配置调试环境

1. 新建开发环境

运行以下命令创建基于JetBrains Rider的.Net环境

mkdir sample-dotnet-rider
cd sample-dotnet-rider
smartide new dotnet -T rider

运行后效果如下：

然后根据配置向导逐一完成操作，最终会到配置Licenses的页面如下图：

到这里你需要登录你自己的Jetbrains 账号（第一次使用Jetbrains 软件的用户会有一年的免费试用期），配置完如下图：

2. 创建ASP.NET Core Web Api项目

点击New Solution 选择ASP.NET Core Web Application选项，由于Rider目前并未集成minimal web api类型，因此这里项目类型选择Web Api如下图：

点击create 创建项目，操作完成后如下图：

3. 开发调试

编译项目确保默认初始化项目没有问题，点击Build Solution编译项目操作如下图：

编译成功后如下图：

与配置基于VS Code的.NET 环境一样我们需要确认当前SmartIDE开发环境的配置端口信息，访问宿主机的sample-dotnet-rider文件夹下的.ide文件夹中的.ide.yaml文件如下图：

通过ide.yaml文件确认将默认初始化的项目端口设置为5000即可，修改项目中的Properities文件夹中的launchSettings.json文件如下图：

修改 applicationUrl 属性如下：

"applicationUrl": "http://0.0.0.0:5000",

修改完成后点击Debug进入调试模式，访问该项目的Swagger页面并触发Api WeatherForecast如下图：

远程开发

上面我们已经使用SmartIDE的本地工作区模式完成了一个应用的创建和开发过程，这个过程和你所熟悉的开发模式有2个区别，1）我们使用了WebIDE；2）开发环境全部通过容器获取并运行。

在这个过程中你的项目代码也已经具备了远程开发的能力，你可以按照以下文档中的说明使用任意一种远程工作区来开发调试你的应用

• 远程主机工作区
• k8s工作区
• Server工作区

另外，你也可以通过VSCode或者JetBrains内置的远程开发模式进行Hybird模式的远程开发，具体请参考

• IDE远程开发操作手册

感谢您对SmartIDE的支持：Be a Smart Developer，开发从未如此简单。

4.5 - Java 快速启动教程

SmartIDE内置了Java开发环境模板，你可以通过一个简单的指令创建带有WebIDE的开发环境，并立即开始编码和调试。

如果你还没有完成SmartIDE安装，请参考 SmartIDE 安装手册 安装SmartIDE命令行工具。

说明：SmartIDE的命令行工具可以在Windows和MacOS操作系统上运行，对大多数命令来说，操作是完全一致的。本文档中虽然使用的是MacOS上的截图，但是Windows环境的所有日志和工作状态完全一致。对于脚本格式有区别的地方，我们会同时提供2套脚本。

VSCode

完整操作视频

为了便于大家更直观地了解和使用SmartIDE创建Java环境，并开始Spring Web项目的开发和调试，我们在B站提上提供了视频供大家参考，视频如下：

跳转到B站： https://www.bilibili.com/video/av852887843

1. 创建开发环境

运行以下命令创建Java开发环境：

# 在 MacOS/Windows 上打开 终端（Terminal）或者 PowerShell 应用
# 执行以下命令
mkdir sample-java-vscode 
cd sample-java-vscode
smartide new java -T vscode

运行后的效果如下，你可以通过命令窗口中的日志详细了解 SmartIDE 的启动过程，当 SmartIDE 启动完毕之后，会自动打开浏览器窗口并导航到 WebIDE 界面。

2. 安装Java及Spring常用插件包

Spring Boot应用，本质上是Java应用，所以我们需要Java和Spring两方面的扩展支持。VS Code为了方便安装，提供一种Extension Pack的方式，把相关技术的多个常用Extension打包成一个Pack，可以实现一键安装，所以我们可以直接安装以下两方面的扩展包即可：

1. Java支持：Java Extension Pack(vscjava.vscode-java-pack）

   功能包括：流行的Java开发扩展，提供Java自动补全、调试、测试、Maven/Gradle支持、项目依赖管理等等。

2. Spring支持：Spring Boot Extension Pack(pivotal.vscode-boot-dev-pack)

   功能包括：用于开发Spring Boot应用程序的扩展集合。

SmartIDE已经通过初始化脚本的方式，为开发环境自动安装了这两个扩展包。在WebIDE启动后请稍等片刻，SmartIDE会自动启动Terminal并执行以上两个插件的安装脚本，安装完毕后，如下图所示：

对应初始化插件包安装脚本如下：

脚本供参考，你无需手工执行这些脚本

# 安装Java扩展包集合（Extension Pack for Java）
code --install-extension vscjava.vscode-java-pack
# 安装Spring扩展包集合（Spring Boot Extension Pack）
code --install-extension pivotal.vscode-boot-dev-pack

3. 创建并配置项目

使用快捷键运行Spring向导，快速创建一个Spring Boot应用。

使用快捷键Ctrl + Shift + P，然后输入Spring Initializr，选择 Spring Initializr:Create a Maven Project… 创建项目，进入创建向导：

在这里指定 Spring Boot 版本，2.6.4，如下图：

指定语言，Java，如下图：

输入maven项目Group Id: cn.smartide，并回车，如下图：

输入maven项目Artifact Id: smartide-demo，并回车，如下图：

指定打包方式: Jar，如下图：

指定 Java (JDK) 版本: 11，如下图：

选择项目依赖: Spring Web Web，如下图：

可对依赖进行多选，这里我们直接回车确认不再添加其他依赖包，如下图：

代码目录：/home/project，如下图：

确认后，扩展将为我们创建Spring Boot Web项目。

创建成功后，IDE的右下方会给出提示，点击：Add to Workspace，添加项目到工作区，如下图：

执行完毕后的效果如下，左侧文件管理器里面已经出现了 smartide-demo 文件夹，并在其中创建了 spring web 应用的基础代码结构。如下图：

此时，IDE会自动打开Java项目并进行初始化构建操作，如下图所示：

点击查看详细信息，查看项目的初始化构建情况，如下图所示：

初始化完成后，如下图所示，所有操作都显示为Done：

工作区添加完毕后，会提示项目导入成功，如下图：

默认，构建时会通过maven官方源下载依赖，我们可以修改 pom.xml，将依赖拉取地址改为国内阿里源。在 pom.xml 中 第5行 ，添加：

<repositories>
    <repository>
        <id>alimaven</id>
        <name>aliyun maven</name>
        <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>alimaven</id>
        <name>aliyun maven</name>
        <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

这样可以更快地拉取依赖，进行maven构建。新建终端，执行命令：

# 进入spring web项目目录
cd /home/project/smartide-demo
# 运行mvn构建安装
mvn install

4. 开发调试

完成以上配置之后，你的代码已经完全准备好，可以开始进行编码调试了。

首先，我们建立一个controller包，路径为cn.smartide.smartidedemo.controller，并且新建一个类：SmartIDEController.java，代码如下

/*SmartIDEController.java*/

package cn.smartide.smartidedemo.controller;

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@EnableAutoConfiguration
public class SmartIDEController {
    @RequestMapping("/home")
    String home(@RequestParam String language) {
        String hello = "Hello, SmartIDE Users!";
        return hello + " The dev language is:" + language + ".";
    }
}

新建完成后，在启动类 SmartideDemoApplication.java 点击Debug，通过Debug模式启动项目。启动调试后，请注意 smartide 客户端的日志输出，SmartIDE 会在后台持续监控容器内的进程情况，并将所有端口转发到 localhost 上

在SmartIDEController.java文件的 第13行 代码处 单击设置断点

在浏览器中输入地址： http://localhost:8080/home?language=Java 触发我们之前所设置的断点，

现在，进入到调试状态，注意上图中的几个关键点

1. 通过打开 http://localhost:8080/home?language=Java 这个地址触发我们预设的断点
2. 将鼠标移动到特定的变量上以后，IDE 会自动加载当前变量的结构体以及赋值状态（实时），方便开发者观察运行时状态
3. Variables (变量) 窗口实时显示当前运行时内的变量状态
4. Call Stack (调用堆栈) 窗口实时显示当前运行时堆栈状态

点击单步运行，并跳出断点，页面将返回输出结果，如下图所示：

至此，我们已经使用 SmartIDE 完成了一个 Spring Web 应用程序的创建，配置和编码调试过程。

5. 提交并分享

SmartIDE 环境中已经内置了 Git 的支持，你可以点击 菜单栏左侧 ｜ 源代码管理 ｜ 点击 Initialize Repository 按钮 将当前工作区初始化成一个 Git代码库。

在 提交注释 中填写 使用SmartIDE创建，然后点击 提交按钮

点击 Remote | Add Remote 按钮，添加一个远端 Git库 地址。SmartIDE 支持任何Git服务，包括：GitHub, Gitlab, Azure DevOps, Gitee 等等。

这时，我们可以将创建的这份代码推送到了类似Gitee的代码仓库上，代码库地址类似如下 https://gitee.com/smartide/sample-java-vscode

至此，我们已经使用 SmartIDE 完成了一个 Spring Boot 应用从环境搭建，创建基础代码结构，配置调试环境，完成编码开发到提交代码的全过程。

现在可以将你的代码库发送给其他的小伙伴，让他通过以下指令一键启动你的应用。

smartide start https://gitee.com/smartide/sample-java-vscode

是不是很爽！

JetBrains IntelliJ IDEA

1. 新建开发环境

运行以下命令创建Spring Web项目开发环境：

mkdir sample-java-idea
cd sample-java-idea
smartide new java -T idea

运行后的效果如下，你可以通过命令窗口中的日志详细了解 SmartIDE 的启动过程，当 SmartIDE 启动完毕之后，会自动打开浏览器窗口并导航到 WebIDE 界面。

2. 创建并配置项目

SmartIDE启动的JetBrains IDEA环境为 社区版，在新建Spring Web项目时，建议安装Spring初始化插件，这样新建项目会更加方便。 这里我们安装第三方插件：Spring Initializr and Assistant。

点击插件，在搜索框输入：Spring Initializr and Assistant，并安装插件。

接受第三方插件安装:

安装完毕后，新建项目：

使用 Spring Initializr向导 新建项目：

输入项目信息：

选择项目依赖项目信息，这里我们选择了两个依赖，分别是：

• 1）Developer Tools -> Lombok
• 2）Web -> Spring Web

修改项目名称，以及默认 保存路径：

至此，Spring Web项目已创建完成。

下面，打开File—Project Structure—Modules ( Win快捷键：Ctrl+Alt+Shift+S，Mac快捷键 Command+; ) ，设置Maven项目的目录结构：

• 1）src/main/java：Sources文件夹
• 2）src/main/resources：Resources文件夹
• 3）src/test/java：Tests文件夹

接着，我们设置依赖拉取地址为国内阿里源，在pom.xml中第5行，添加：

<repositories>
    <repository>
        <id>alimaven</id>
        <name>aliyun maven</name>
        <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>alimaven</id>
        <name>aliyun maven</name>
        <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

设置完毕后，在pom.xml文件中，指定spring-boot-maven-plugin插件版本：

点击Reload All Maven Projects，重新加载Maven项目。Maven项目加载完毕后，点击mvn install，触发依赖下载与安装：

至此，我们设置完毕项目所有的Maven依赖，这时可以启动Spring Web项目了。

3. 开发调试

完成以上配置之后，基础代码已经完全准备好，就可以开始进行编码调试了。

首先，我们建立一个controller包，路径为cn.smartide.demo.controller，并且新建一个类：SmartIDEController.java，代码如下:

/*SmartIDEController.java*/

package cn.smartide.demo.controller;

import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@EnableAutoConfiguration
public class SmartIDEController {
    @RequestMapping("/home")
    String home(@RequestParam String language) {
        String hello = "Hello, SmartIDE Users!";
        return hello + " The dev language is:" + language + ".";
    }
}

新建完成后，在启动类 SmartideDemoApplication.java 上右键点击Debug，通过Debug模式启动项目。启动调试后，请注意 smartide 客户端的日志输出，SmartIDE 会在后台持续监控容器内的进程情况，并将所有端口转发到 localhost 上

在SmartIDEController.java文件的 第15行 代码处 单击设置断点

在浏览器中输入地址：http://localhost:8080/home?language=Java 触发我们之前所设置的断点，

现在，进入到调试状态，注意上图中的几个关键点

1. 通过打开 http://localhost:8080/home?language=Java 这个地址触发我们预设的断点
2. 将鼠标移动到特定的变量上以后，IDE 会自动加载当前变量的结构体以及赋值状态（实时），方便开发者观察运行时状态
3. Variables (变量) 窗口实时显示当前运行时内的变量状态
4. Debugger (调试) 窗口实时显示当前运行时堆栈状态

点击单步运行，并跳出断点，页面将返回输出结果，如下图所示：

至此，我们已经使用 SmartIDE 完成了一个 Spring Web 应用程序的创建，配置和编码调试过程。

4. 提交并分享

环境中已内置了git命令，这里我们通过命令行的方式，将代码提交到远端 Git库。 SmartIDE 支持任何Git服务，包括：GitHub, Gitlab, Azure DevOps, Gitee 等等。

下面我们执行git提交命令：

# 初始化git仓库
git init
# 添加项目文件
git add .
# 提交
git commit -m "使用SmartIDE创建smartide-java-demo"
# 添加远端地址
git remote add origin https://gitee.com/smartide/sample-java-idea
# 推送到远端
git push -u origin "master"

这时，我们可以将创建的这份代码推送到了类似Gitee的代码仓库上，代码库地址类似如下 https://gitee.com/smartide/sample-java-idea

至此，我们已经使用 SmartIDE 完成了一个Spring Web 应用从环境搭建，创建基础代码结构，完成编码开发调试到提交代码的全过程。

现在可以将你的代码库发送给其他的小伙伴，让他通过以下指令一键启动你的应用。

smartide start https://gitee.com/smartide/sample-java-idea

是不是很爽！

5. 快速创建Spring Boot项目

SmartIDE模板中提供了创建Spring Boot的示例模板，可以更快速地创建一个Spring Web项目。

命令如下：

smartide new java -T springboot-idea

详情请参考：https://gitee.com/smartide/smartide-springboot-template

基于Spring Boot并包含前端、数据库等的Java项目，可参考示例应用-若依项目。

远程开发

上面我们已经使用SmartIDE的本地工作区模式完成了一个应用的创建和开发过程，这个过程和你所熟悉的开发模式有2个区别，1）我们使用了WebIDE；2）开发环境全部通过容器获取并运行。

在这个过程中你的项目代码也已经具备了远程开发的能力，你可以按照以下文档中的说明使用任意一种远程工作区来开发调试你的应用

• 远程主机工作区
• k8s工作区
• Server工作区

另外，你也可以通过VSCode或者JetBrains内置的远程开发模式进行Hybird模式的远程开发，具体请参考

• IDE远程开发操作手册

感谢您对SmartIDE的支持：Be a Smart Developer，开发从未如此简单。

4.6 - Jupyter Notebook 快速启动教程

概述

远程工作区的一个重要优势就是可以帮助开发者更好的利用远程主机的强大算力和数据处理能力，在这个领域中 Jupyter Notebook 无疑是非常典型的应用类型。SmartIDE 提供了对 Jupyter Notebook 的远程工作区支持，开发者只需要一个简单的指令就可以启动一个预装了 Jupyter Notebook 的远程工作区，并通过 --host 参数将这个工作区漫游到任意主机或者 k8s 环境中。

在这个快速开始教程中，我们将一起使用 SmartIDE 创建一个基于 Jupyter Notebook 的开箱即用的环境，并利用 Jupyter 的数据分析能力针对新冠疫情数据进行简单的分析。这个示例的目的是帮助使用 Jupyter 的开发者了解 SmartIDE 的能力，并希望有更多的开发者加入 SmartIDE 开发者的行列。

完整操作视频

为了便于大家更直观地了解和使用 SmartIDE 创建 Jupyter Notebook 环境，并开始项目的开发，我们在B站提上提供了视频供大家参考，视频如下：

1. 开发环境设置

Jupyter Notebook 默认需要运行在 Python 环境下，并且需要引入 Numpy， Pandas，Matplotlib 等常用的组件， 为此 SmartIDE 参考社区镜像，制作了开箱即用的模板，并内置了中文字体。用户只需要简单的命令即可快速创建出一个 JupyterNotebook 的开发环境。

1.1 使用SmartIDE模板创建开发环境

本地启动

# 在 MacOS/Windows 上打开 终端（Terminal）或者 PowerShell 应用，执行以下命令

# 创建空文件夹
mkdir sample

# 进入到目录下
cd sample

# 创建开发环境
smartide new anaconda -T jupyter
# done！

远程启动

# 添加远程主机到SmartIDE
smartide host add <IP-Address> --username <user> --password <pwd> --port <ssh port | 22>
# 获取新添加的hostId
smartide host list
# 创建开发环境
smartide new --host <hostId> anaconda -T jupyter -w <workspace-name>
# done！

1.2 基于已有仓库创建开发环境

这里，我们以 SmartIDE 官方的 Jupyter Notebook 示例仓库为例， 运行以下命令创建开发环境：

# 在 MacOS/Windows 上打开 终端（Terminal）或者 PowerShell 应用，执行以下命令
# 克隆示例仓库
git clone https://github.com/SmartIDE/sample-anaconda-jupyter.git

# 进入到仓库目录下
cd sample-anaconda-jupyter

# 启动开发环境
smartide start
# done!

1.3 (可选）远程主机模式创建开发环境

如果你是一个 SmartIDE 的高级用户，并且已经用 SmartIDE 关联了远程开发机器，可以直接用远程模式创建 Jupyter Notebook 开发环境

# 添加远程主机到SmartIDE
smartide host add <IP-Address> --username <user> --password <pwd> --port <ssh port | 22>
# 获取新添加的hostId
smartide host list
# 启动
smartide start --host <hostId> https://github.com/SmartIDE/sample-anaconda-jupyter.git

运行后的效果如下，你可以通过命令窗口中的日志详细了解 SmartIDE 的启动过程，当 SmartIDE 启动完毕之后，会自动打开浏览器窗口并导航到 WebIDE 界面。

2. 访问 Jupyter Notebook 页面，浏览目录下的文件

Jupyter Notebook 服务端会自动在开发环境环境启动后运行，默认会监听 8888 端口， 通过浏览器访问 http://localhost:8888/ 可以进入 JupyterNotebook 主界面。 Jupyter Notebook 中展示的文件列表和当前所在的文件目录保持一致，我们可以访问到当前仓库中所有的示例 notebooks。

3. 运行 sample-03 Notebook

进入 sample3 目录， 打开示例文件后，点击上方的 Run 按钮，运行 notebook 到最底部后，将绘制出疫情数据统计图形。 这个示例中综合利用了 Numpy， Pandas, 和 Matplotlib 等 Jupyter Notebook 中常用的lib，并在图表的组件中设置了中文字体。

4. 回到 Web IDE主界面，进入 Source Control 侧边栏， 进行 Git 常规操作

在上一步的运行过程中，我们在 notebook 中动态从 API 中获取了最新的数据，并把数据保存到了 csv 文件中。回到我们的 Web IDE 页面，点击 Source Control 侧边栏，可以查看变化的文件（如果没有显示文件，可以点击上面的刷新按钮）。 点击第一个变化的 csv 文件，查看文件差异，可以清楚的看到文件里增加了一些新的数据

点击 .ipynb 文件，也可以在右侧看到 notebook 中产生的差异信息

5. 提交修改

将发生变化的文件提交并同步到远程仓库。

6. Great Job!

通过上面的几个步骤， 我们初步实现了一个 Jupyter Notebook的 Dev Loop。通过 WebIDE 和 Jupyter Notebook 相互结合使用，给开发者带来了流畅的开发体验。 另，SmartIDE 在开发环境中内置了 Anaconda 和 常用的 packages， 方便开发者对环境和 package 进行管理。内置的 packages 可通过下面的命令查看：

conda list

感谢您对SmartIDE的支持：Be a Smart Developer，开发从未如此简单。

5 - 示例应用

5.1 - Boathouse 计算器

整体说明

本demo示例提供两个场景，开发人员通过本地运行SmartIDE可以使用webide和使用本地开发工具链接SmartIDE生成的开发容器进行代码调试，全程无需再安装调试所需环境。 SmartIDE将通过隧道技术以及动态端口映射机制提供开发人员与本地开发调试一样的开发体验。

• SmartIDE本地运行，使用WebIDE方式调试
• 使用本地VScode链接SmartIDE开发容器调试

场景1.SmartIDE本地运行，使用WebIDE方式调试

1. clone代码库

git clone https://github.com/idcf-boat-house/boathouse-calculator.git
cd boathouse-calculator

2. 快速创建并启动SmartIDE开发环境

smartide start 

在打开的WebIDE 中打开 terminal，并启动项目

npm install 
npm start 

可以看到应用已在容器3001端口启动，这时通过隧道转发机制，我们可以直接通过 http://localhost:3001/ 打开应用

3.添加断点调试程序

在终端中，使用‘Ctrl+z’终止进程

添加断点 /api/controllers/arithmeticController.js 的line47

输入 F5 启动调试，打开 http://localhost:3001/ 即可通过使用计算器进入调试步骤

场景2.使用本地VScode链接SmartIDE开发容器调试

1.VScode安装插件 Remote Development

2.新建SSH连接并保存到配置文件

3.打开SSH连接，中间需要多次输入密码

4.打开远程容器目录

5.npm i安装依赖包，运行和调试

5.2 - 若依(RuoYi)项目

使用SmartIDE开发调试若依项目(前端分离版)

SmartIDE是下一代的云原生IDE，可以帮助你一键启动项目的集成开发环境，直接进入编码调试，免除安装SDK、IDE和其他相关工具的麻烦。

我们已经对Ruoyi-Vue进行了SmartIDE适配，可以一键启动包含以下工具的 标准化全栈开发环境(SFDE - Standard Fullstack Development Environment)：

• 完整支持Vue的Node.js开发工具语言包（SDK）
• 完整支持Java语言Spring框架的开发工具语言包（SDK）
• 用户可以选择2种WebIDE来加载项目进行前后端联调，VSCode WebIDE，JetBrains IDE 社区版 WebIDE
• 配置好的中间件，包括：MySQL和Redis服务器环境
• 数据管理工具PHPMyAdmin用于管理MySQL数据库

1. 完整操作视频

为了便于大家更直观的了解使用SmartIDE开发调试RuoYi的过程，我们在B站提上提供了视频供大家参考，视频如下：

跳转到B站： https://www.bilibili.com/video/av851717139

2. 本地模式启动项目

使用SmartIDE启动RuoYi的开发调试非常简单，仅需要两个步骤

1. 按照 安装手册 完成 SmartIDE 本地命令行工具的安装
2. 使用以下命令一键启动SFDE

## SmartIDE是一款跨平台开发工具，您可以在Windows或者MacOS上执行同样的指令
smartide start https://gitee.com/SmartIDE/RuoYi-Vue.git

注意：第一次启动因为下载容器镜像，需要较长时间，大概需要十分钟。SmartIDE所使用的容器镜像全部托管于阿里云在国内的镜像仓库上，因此一般不会出现无法拉取镜像的情况。如果你的网络过于不稳定，多尝试几次即可。

以上命令会在当前目录自动完成代码克隆，拉取开发环境镜像，启动容器，自动开启WebIDE的动作。

以上动作完成后，即可看到类似如下的WebIDE窗口，默认情况下将使用JetBrains Projector模式的 IntelliJ IDEA 社区版

WebIDE的地址是 https://localhost:6800

JetBrains Projector是一款基于JetBrains产品的WebIDE，提供通过浏览器操作并与桌面IDE保持一致的操作体验，第一次打开 JetBrains Projector 的时候需要进行简单的初始化操作如下：

在 Welcome to IntelliJ IDEA 页面中，点击 Open 然后选择 /home/project 目录，然后点击 OK

在以下对话框中选择 Trust Project

加载完毕的Web版IntelliJ IDEA如下

3. 远程主机模式启动项目

远程主机模式允许你将SmartIDE的开发环境一键部署到一台安装了Docker环境的远程主机上，并远程连接到这台主机进行开发，对于比较复杂的项目来说这样做可以让你扩展本地开发机的能力，实现云端开发体验。

使用远程模式也仅需要两个步骤

注意：远程主机模式下你不必在本地安装Docker环境，只需要安装好SmartIDE的命令行工具即可

1. 按照 Docker & Docker-Compose 安装手册 (Linux服务器) 准备好一台远程主机，建议使用Ubuntu 18.04 LTS以上版本的Linux环境。
2. 按照以下指令启动项目

# 将远程主机添加到SmartIDE中
smartide host add <IpAddress> --username <SSH-UserName> --password <SSH-Password> --port <SSH-Port默认为22>

# 获取主机ID
smartide host list

# 使用远程主机启动项目
smartide start --host <主机ID> https://gitee.com/SmartIDE/RuoYi-Vue.git

4. 启动前后端开发调试

使用SmartIDE启动环境后，我们即可启动前后端联调操作，为了避免SmartIDE的配置影响RuoYi的默认配置，我们扩展了application.yml中的配置，为SmartIDE提供了单独的日志、MySQL和Redis配置。

1. 切换spring配置使用SmartIDE环境

如果要使用SmartIDE进行联调，请先打开 /ruoyi-admin/src/main/resources/application.yml，将 spring.profiles.active 的值设置为 smartide

# Spring配置
spring:
  profiles:
    active: smartide

2. 创建ry-vue数据库

说明：使用SmartIDE运行开发环境的一个好处就是一键启动所有相关环境，我们已经在你的环境中内置了专门用于RuoYi项目开发的MySQL数据库，并且为了方便你的操作，也提供了PhpMyAdmin这个工具方便你进行数据管理操作。

打开SmartIDE内置的PHPMyAdmin工具，地址是：http://localhost:8090

• 服务器：ruoyi-db
• 用户名：root
• 密码：password

点击 新建 并输入 ry-vue 作为数据库名称，点击 创建 按钮

然后在这个数据库中依次执行以下两个脚本：

• sql/ry_20210908.sql
• sql/quartz.sql

执行完毕之后的状态如下：

3. 编译并安装所有RuoYi后端组件，并启动后端调试

然后，我们需要打开IDEA内置的terminal，并执行以下指令以确保RuoYi所有模块都已经编译并放入共享组件库中

## 请在RuoYi项目根目录执行
mvn package
mvn install

点击 File | Project Structure 设置当前项目的JDK版本，环境中已经内置了OpenJDK-11这个版本，如果希望使用其他JDK版本也可以选择 Add JDK 自行下载。

右键点击 ruoyi-admin/src/main/java/com.ruoyi/RuoYiApplication.java 文件，并启动 Debug 模式

注意 Console 中出现 若依启动成功 的字样，表示后端应用启动成功。

4. 编译并启动前端项目

现在我们可以进入 ruoyi-ui 项目，启动前端项目

后端启动后，我们可以通过命令启动前端，使用内置的 terminal 运行以下命令以便进入 ruoyi-ui 项目并启动前端服务

cd ruoyi-ui
npm install
npm run dev

执行完毕后，检查 terminal 中出现了 App running at 的字样就表示前端项目启动成功了

注意：我们的环境运行在容器中，我们将容器内的80端口映射到了你本地的8000端口。

现在打开 http://localhost:8000 即可访问若依项目了

5. 设置断点，进入交互式单步调试状态

如果你按照刚才的操作方式用 Debug 模式启动了后端项目，那么现在可以在任何位置创建断点，并进入断点调试模式

比如，你可以在 /ruoyi-admin/src/main/java/com.ruoyi/web/controllers/system/SysUserController.java 的 第59行 设置断点，然后进入 若依管理系统 ｜ 系统管理 ｜ 用户管理 菜单，即可触发此断点，注意下图中的IDEA已经中断在代码行59.

其他调试相关的入口如下：

• 容器内项目目录 /home/project
• WebIDE入口 http://localhost:6800
• 数据库管理PHPMyAdmin http://localhost:8090
• 前端应用入口 http://localhost:8000

注意：如果你本地的以上端口有被占用的情况，SmartIDE会自动在当前端口上增加100，具体转发情况请参考SmartIDE命令的日志输出。

5. 停止和恢复环境

如果需要停止和恢复环境，可以使用SmartIDE的状态管理指令如下

## 获取已经创建好的开发环境列表
smartide list
## 停止一个开发环境
smartide stop <ID>
## 启动一个开发环境
smartide start <ID>
## 清理一个开发环境
## 参数说明：-f 强制删除 -y 跳过确认 -p 删除磁盘上的代码库 -i 删除容器镜像
smartide remove <ID> -fypi

6. 相关链接

• 若依项目SmartIDE仓库地址：https://gitee.com/SmartIDE/RuoYi-Vue.git
• 若依项目（前后端分离版）：https://gitee.com/y_project/RuoYi-Vue
• 若依项目SmartIDE PR：https://gitee.com/y_project/RuoYi-Vue/pulls/432

7. 技术支持

特别说明: SmartIDE本身是开源产品，并且对独立开发者提供免费使用授权。

大家可以通过以下链接获取SmartIDE的技术支持

• 产品官网 https://SmartIDE.cn

  • 通过产品官网上的二维码可以加入 [Smart早鸟群] 与其他的 Smart Developer 一起交流

• 开源首页：SmartIDE采用GitHub和Gitee双通道开源模式（自动同步代码），方便国内开发者访问

  • https://githbu.com/SmartIDE
  • https://gitee.com/SmartIDE

  大家自选以上任意渠道提交Issue，产品组的小伙伴会及时给予反馈。

  如果大家喜欢我们的产品，请给予 Star 支持

• B站频道：我们定期组织直播，为大家更新产品开发进展

  • https://space.bilibili.com/1001970523

  如果大家喜欢我们的产品和视频，一定要记得 “三连”

感谢您对SmartIDE的支持：Be a Smart Developer，开发从未如此简单。

5.3 - Gin-Vue-Admin

使用SmartIDE开发和调试Gin-Vuew-Admin

SmartIDE是下一代的云原生IDE，可以帮助你一键启动项目的集成开发环境，直接进入编码调试，免除安装SDK，IDE和其他相关工具的麻烦。

我们已经对Gin-Vue-Admin进行了SmartIDE适配，可以一键启动包含以下工具的 标准化全栈开发环境(SFDE - Standard Fullstack Development Environment)：

• 完整支持Vue的Node.js开发工具语言包（SDK）
• 完整支持Go语言Gin框架的开发工具语言包（SDK）
• 前端开发工具VSCode WebIDE
• 后端开发工具JetBrain GoLand WebIDE
• 数据管理工具PHPMyAdmin用于管理Gva后台的MySQL数据库

本文档对如何使用SmartIDE进行Gin-Vue-Admin项目的前后端联调进行描述。

1. 完整操作视频

为了便于大家更直观的了解使用SmartIDE开发调试Gin-Vue-Admin的过程，我们在B站提上提供了视频供大家参考，视频如下：

跳转到B站：https://www.bilibili.com/video/BV1eL4y1b7ep

2. 本地模式启动项目

使用SmartIDE启动Gin-Vue-Admin的开发调试非常简单，仅需要两个步骤

1. 按照 安装手册 完成 SmartIDE 本地命令行工具的安装
2. 使用以下命令一键启动SFDE

## SmartIDE是一款跨平台开发工具，您可以在Windows或者MacOS上执行同样的指令
smartide start https://gitee.com/smartide/gin-vue-admin.git

注，也可使用GVA项目SmartIDE适配所对应的GitHub代码仓库：https://github.com/SmartIDE/gin-vue-admin.git

以上命令会在当前目录自动完成代码克隆，拉取开发环境镜像，启动容器，自动开启VSCode WebIDE以及自动恢复vue前端项目的npm依赖包，启动前端项目等一系列动作。

以上动作完成后，即可看到类似如下的VSCode WebIDE窗口。

VSCode WebIDE的地址是 https://localhost:6800

我们的环境中还内置了JetBrain GoLand WebIDE

JetBrain WebIDE的地址是 https://localhost:8887

注意：如果你本地的以上端口有被占用的情况，SmartIDE会自动在当前端口上增加100，具体转发情况请参考SmartIDE命令的日志输出。

3. 远程主机模式启动项目

上文第1部分中B站操作视频中使用的是远程主机模式，远程主机模式允许你将SmartIDE的开发环境一键部署到一台安装了Docker环境的远程主机上，并使用WebIDE远程连接到这台主机进行开发，对于比较复杂的项目来说这样做可以让你扩展本地开发机的能力，实现云端开发体验。

使用远程模式也仅需要两个步骤

注意：远程主机模式下你不必在本地安装Docker环境，只需要安装好SmartIDE的命令行工具即可

1. 按照 Docker & Docker-Compose 安装手册 (Linux服务器) 准备好一台远程主机
2. 按照以下指令启动项目

# 将远程主机添加到SmartIDE中
smartide host add <IpAddress> --username <SSH-UserName> --password <SSH-Password> --port <SSH-Port默认为22>

# 获取主机ID
smartide host list

# 使用远程主机启动项目
smartide start --host <主机ID> https://gitee.com/smartide/gin-vue-admin.git

4. 前后端联调

使用SmartIDE启动环境后，前端应用已经自动启动；此时只需要启动后端调试模式即可开始调试Gin-Vue-Admin。进入联调模式的环境状态如下

调试相关的入口如下：

• 容器内项目目录 /home/project
• VSCode WebIDE http://localhost:6800
• 前端应用 http://localhost:8080
• JetBrain GoLand WebIDE http://localhost:8887
• 后端应用(Swagger-UI) http://localhost:8888/swagger/index.html
• 数据库管理PHPMyAdmin http://localhost:8090

注意：如果你本地的以上端口有被占用的情况，SmartIDE会自动在当前端口上增加100，具体转发情况请参考SmartIDE命令的日志输出。

5. 相关链接

• GVA项目SmartIDE GitHub仓库地址：https://github.com/SmartIDE/gin-vue-admin.git

• GVA项目仓库地址：https://gitee.com/pixelmax/gin-vue-admin

6. 技术支持

特别说明: SmartIDE本身是开源产品，并且对独立开发者提供免费使用授权。

大家可以通过以下链接获取SmartIDE的技术支持

• 产品官网 https://SmartIDE.cn

  • 通过产品官网上的二维码可以加入 [Smart早鸟群] 与其他的 Smart Developer 一起交流

• 开源首页：SmartIDE采用GitHub和Gitee双通道开源模式（自动同步代码），方便国内开发者访问

  • https://githbu.com/SmartIDE
  • https://gitee.com/SmartIDE

  大家自选以上任意渠道提交Issue，产品组的小伙伴会及时给予反馈。

  如果大家喜欢我们的产品，请给予 Star 支持

• B站频道：我们定期组织直播，为大家更新产品开发进展

  • https://space.bilibili.com/1001970523

  如果大家喜欢我们的产品和视频，一定要记得 “三连”

感谢您对SmartIDE的支持：Be a Smart Developer，开发从未如此简单。

6 - 镜像和模版

开发者镜像

SmartIDE 提供了 主流开发语言的SDK 的容器镜像，包括 node/javascript、java、golang、python、dotnet/C#、php、C/C++、，集成了VSCode和JetBrains两大主流IDE体系，并在近期完成了对OpenSumi国产IDE的node SDK支持。开发者可以直接使用这些作为自己的通用开发环境，或者以这些镜像为基础来构建自己专属的开发镜像。

SmartIDE所提供的开发者容器镜像中已经针对开发调试和测试场景进行了一系列的优化，相对于自己从头构建容器镜像来说，使用SmartIDE的开发者镜像会有一系列的好处：

• 非root用户运行：docker默认采用root方式运行容器，这带来了很多方便的同时也造成一些不安全的因素，比如用户可能在容器内越权操作主机系统，在容器内创建的文件如果被映射到主机将会作为root用户所有等等。这些问题对于使用容器单纯运行应用不易构成太大的问题，但是对于直接使用容器进行应开发来说就会造成巨大的安全隐患以及不方便。SmartIDE所提供的所有开发者容器镜像均采用普通用户权限运行，并且允许用户在启动容器时指定容器内用户的密码，方便开发者控制容器内环境同时也避免容器内操作越权。
• 内置SSH服务支持：对于开发者来说，对容器内环境需要非常高的操作便利性，提供SSH访问能力可以极大的方便开发者对自己的开发环境进行各类操作和控制。这一点上与运维用途的容器也非常不同，一般来说运维用途的容器会尽量避免用户直接进入，而尽量采用 不可变 原则来进行管理，而开发者容器在利用 不可变 原则提供环境一致性的同时还要允许开发者进行定制，因此提供SSH直接访问就非常的重要。

国内国外双托管

为了同时兼顾国内和国外开发者使用，所有SmartIDE的镜像同时托管至阿里云和Docker Hub，方便开发者根据自己的地理位置选择最快速的拉取地址

• 国内阿里云地址：registry.cn-hangzhou.aliyuncs.com/smartide/<镜像名称:TAG>
• 国外 Docker Hub 地址：registry.hub.docker.com/smartide/<镜像名称:TAG>

对于以下列表中所列出的所有镜像，均可以通过替换地址前缀的方式更换拉取源。

模版库

为了方便开发者使用我们所提供的开发者镜像，我们在 SmartIDE CLI 中内置了环境模版功能，开发者可以使用 smartide new 指令获取所有可用的模版，这些模版与以上的开发者镜像一一对应，可以用来一键创建标准化的开发环境。

SmartIDE模版库本身是开源的，地址为

• 国内Gitee: https://gitee.com/smartide/smartide-templates
• 国外GitHub: https://github.com/smartide/smartide-templates

完整的指令列表如下

## 完整技术栈和IDE匹配列表
smartide new node|java|golang|dotnet|python|php|cpp [-T (vscode|vscode-vmlc)|(webstorm|(idea|idea-vmlc)|rider|goland|pycharm｜phpstorm|clion)|opensumi|vmlc]

各个技术栈相关的模版启动指令如下：

Node/JavaScript/前端

#########################################
# Node/JavaScript 前端技术栈
#########################################

## 创建带有node全版本sdk的开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入
smartide new node
## 创建带有node全版本sdk的VMLC开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入。只支持linux操作系统
smartide new node -T vmlc
## 创建带有node全版本sdk的开发容器，使用VSCode WebIDE
smartide new node -T vscode
## 创建带有node全版本sdk的VMLC开发容器，使用VSCode WebIDE。只支持linux操作系统
smartide new node -T vscode-vmlc
## 创建带有node全版本sdk的开发容器，使用JetBrains WebStorm WebIDE
smartide new node -T webstorm
## 创建带有node全版本sdk的开发容器，使用Opensumi WebIDE
smartide new node -T opensumi

Java语言

#########################################
# Java语言
#########################################

## 创建带有JDK的开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入
smartide new java
## 创建带有JDK的VMLC开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入。只支持linux操作系统
smartide new java -T vmlc
## 创建带有JDK开发容器，使用VSCode WebIDE
smartide new java -T vscode
## 创建带有JDK的VMLC开发容器，使用VSCode WebIDE。只支持linux操作系统
smartide new java -T vscode-vmlc
## 创建带有JDK开发容器，使用JetBrains IntelliJ IDEA WebIDE
smartide new java -T idea
## 创建带有JDK的VMLC开发容器，使用JetBrains IntelliJ IDEA WebIDE。只支持linux操作系统
smartide new java -T idea-vmlc

Go语言

#########################################
# Go语言
#########################################

## 创建带有Go的开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入
smartide new golang
## 创建带有Go开发容器，使用VSCode WebIDE
smartide new golang -T vscode
## 创建带有Go开发容器，使用JetBrains Goland WebIDE
smartide new golang -T goland

DotNet (跨平台版本)

#########################################
# DotNet (跨平台版本)
#########################################

## 创建带有.Net的开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入
smartide new dotnet
## 创建带有.Net开发容器，使用VSCode WebIDE
smartide new dotnet -T vscode
## 创建带有.Net开发容器，使用JetBrains Rider WebIDE
smartide new dotnet -T rider

Python

#########################################
# Python
#########################################

## 创建带有Python的开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入
smartide new python
## 创建带有Python开发容器，使用VSCode WebIDE
smartide new python -T vscode
## 创建带有Python开发容器，使用JetBrains PyCharm WebIDE
smartide new python -T pycharm

PHP

#########################################
# PHP
#########################################

## 创建带有PHP的开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入
smartide new php
## 创建带有PHP开发容器，使用VSCode WebIDE
smartide new php -T vscode
## 创建带有PHP开发容器，使用JetBrains PhpStorm WebIDE
smartide new php -T phpstorm

C/C++

#########################################
# C/C++
#########################################

## 创建带有C/C++的开发容器，无IDE，可通过VSCode SSH Remote或者JetBrains Gateway接入
smartide new cpp
## 创建带有C/C++开发容器，使用VSCode WebIDE
smartide new cpp -T vscode
## 创建带有C/C++开发容器，使用JetBrains Clion WebIDE
smartide new cpp -T clion

镜像和模版指令列表

为了方便开发者使用我们的镜像，当前所有公开镜像的地址公布如下并会持续更新。有关以下镜像体系的详细说明，请参考 SmartIDE Sprint 9 (v0.1.9）发布说明

SmartIDE开发者镜像分成3层提供，分别提供不同的能力。

L0 - 基础镜像

提供基础能力，比如：认证，权限，SSH,git；使用Ubuntu满足日常开发基础组件的需求，还有一些其他的基础工具，如下：

• libsecret：是一个用于存储和获取密钥和其他私密信息的库。它使用 DBUS 与“私密服务”进行通讯,
• apt-utils: 与软件包管理相关的工具程序
• [moreutils](Debian – 在 sid 中的 moreutils 软件包详细信息)一些通用库扩展
• jq：json文件处理和解析工具
• zip: 压缩/解压工具
• vim: 命令行编辑器
• iputils-ping： 网络命令ping
• telnet：远程登陆
• lsof: 列出当前系统打开文件的工具

除此之外，vmlc的基础镜像还包括了以下工具：

• docker && docker-compose
• kind、helm、k9s、Dapr、Kubectl

L1 - SDK镜像

SDK镜像提供开发语言环境支持能力，同时提供SDK Only的使用方式，允许本地IDE将SDK镜像作为开发环境直接使用，不嵌入WebIDE

L2 - WebIDE镜像

WebIDE镜像，在SDK镜像的基础上嵌入常用的IDE

VSCode WebIDE

JetBrains Projector WebIDE

OpenSumi WebIDE

7 - 操作手册

7.1 - CLI

7.2 - Server

7.3 - SmartIDE插件市场操作手册

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

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 问题，请自行基于此修改方式创建镜像。

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

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 获取插件总数：
• 界面上可以根据分类或排序和关键字搜索对应插件：

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

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 中 安装使用，安装使用请参考 配置连接手册。

7.3.4 - 插件安装手册

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

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

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

• 搜索插件
• 安装使用

7.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的插件市场链接地址
• 搜索插件
• 安装使用

7.4 - 项目适配

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。

7.5 - IDE远程连接