- 服务端开发
- 调试平台源码
服务端开发
调试平台源码
本教程指导您如何使用 Gitpod 运行和调试平台源码。
无论是使用华炎魔方作为开发工具来开发项目，还是调试运行华炎魔方平台源码，都需要安装开发环境，我们推荐使用 GitPod 来启动远程开发环境，以免去本地安装开发环境的繁琐过程。
远程开发环境已经安装并初始化好必须的组件，包括 nodejs, mongodb, redis, vscode 等，只需要在浏览器中输入地址 https://gitpod.io/#{Git仓库地址} 即可使用 Gitpod 启动远程开发环境。
商业客户请查看教程 开发环境部署 - DevOps 远程开发 使用我们为国内用户提供的华炎魔方DevOps服务，其中包含 GitLab DevOps 和 Gitpod 远程开发服务。
注册GitPod账户
如果没有 Github 账户和 GitPod 账户，请分别注册并使用浏览器登录它们。
远程开发魔方项目
Fork项目
请先Fork，即“派生” 华炎魔方模板项目，后续我们就可以把开发后的代码提交到Git仓库。
npx create-steedos-app启动远程开发环境
上面截屏动画演示了快速启动开发环境的过程，因为不是第一次启动，所以整个过程耗时非常短，如果是第一次启动远程开发环境，耗时会明显增加，它主要自动执行以下操作：
- 自动访问项目地址：https://gitpod.io/#{之前Fork下来的Git仓库地址} 来启动远程开发环境，比如上面动画截图访问的就是 华炎魔方模板项目 可以把
#号后面的Git仓库地址换成您希望运行的任何华炎魔方项目的Git仓库地址来启动其远程开发环境。 - 自动分配远程服务器资源创建一个新的Workspace。
- 把#号后面的Git仓库地址中的项目克隆到Workspace中并重定向到Workspace访问地址。
- 自动从网络下载并加载华炎魔方Docker镜像。
- 自动安装和配置Mongodb数据库，并以集群模式启动数据库。
- 自动安装、配置和启动Redis数据库。
- 自动安装必要的VS Code插件，包括元数据同步、简体中文语言包等。
- 自动执行
yarn安装项目依赖的NPM包。 - 自动执行
yarn start启动项目。
在浏览器上运行Gitpod启用远程开发环境打开项目时，我们会遇到Gitpod自动打开新的浏览器窗口时被拦截，也会经常遇到需要拷贝本地文件到Gitpod项目中的情况，这些也都可以通过浏览器设置来实现，详细请参考当前文档底部的附录小节 关于Gitpod。
本地VS Code
我们可以访问 Gitpod官网个人设置页面 勾选 Open in Desktop IDE 选项来开启使用本地VS Code打开远程Gitpod项目的功能，该功能开启后，就可以使用本地VS Code打开Gitpod项目了，使用浏览器还是本地VS Code主要看个人习惯，两种方式并没有太大区别。
运行项目
显示激活华炎魔方的初始化界面时，可以在控制台看到提示“请配置环境变量STEEDOS_CLOUD_SPACE_ID和STEEDOS_CLOUD_API_KEY”，激活后会自动配置这些环境变量，您无需手动配置它们。
激活华炎魔方
请在 华炎魔方客户门户 注册账户，使用浏览器登录该账户后再分别新建我的魔方和私有部署记录。
在我的魔方中设置的初始密码就是初始化华炎魔方项目时自动创建的初始管理员账户的默认密码。
输入激活参数
上面“复制激活参数”按钮复制的内容，已经包含了激活华炎魔方需要的两个环境变量，我们把它粘贴到之前运行项目时看到的初始化界面的输入框中，提交后即可激活华炎魔方了。
- 自动把包括用于激活华炎魔方、同步元数据等各种环境变量保存到
.env.local文件中。 - 连接 华炎魔方客户门户 服务激活本地的华炎魔方。
- 自动下载不限制用户数、不限制访问时间的许可证
- 在本地魔方项目中自动创建管理员账户并设置其初始密码。
- 获取当前魔方ID已购买的软件包并把它们自动安装到本地魔方项目中。
- 自动跳转到登录界面。
激活过程中自动填充的主要环境变量如下所示：
[metadata]
METADATA_SERVER=https://5000-steedos-steedosprojectt-el6sfckv2j9.ws-us27.gitpod.io/
METADATA_APIKEY=#会自动填充为初始界面中输入的环境变量值
[steedos-cloud]
STEEDOS_CLOUD_SPACE_ID=#会自动填充为初始界面中输入的环境变量值
STEEDOS_CLOUD_API_KEY=#会自动填充为初始界面中输入的环境变量值其中METADATA_SERVER 和 METADATA_APIKEY这两个环境变量是用于同步元数据，详细请参考文档 同步元数据。
激活成功后，我们使用私有部署的华炎魔方初始账户登录即可进入系统主界面。
项目访问地址
如果项目运行完成后没有自动打开浏览器窗口访问项目的话，可以手动在浏览器中输入Gitpod-Workspaces访问地址并加上要访问的项目端口号作为前缀即可访问它。
比如假设之前开启的远程开发环境打开的Workspaces访问地址为https://steedos-steedosprojectt-el6sfckv2j9.ws-us27.gitpod.io/，我们只要输入地址 https://5000-steedos-steedosprojectt-el6sfckv2j9.ws-us27.gitpod.io/ 即可访问刚运行起来的项目。
需要注意的是，默认情况下，使用Gitpod启用远程开发环境打开的项目在停止访问后，连续30分钟不访问该项目的话，相关资源会被自动释放，包括程序代码和数据库数据在内的所有资源都会被销毁，请参阅本文档底部的 “关于Gitpod - Pin” 小节了解如何锁定开发环境。
开发项目
请参考教程 软件包开发流程，基于软件包来开发华炎魔方项目中的各种功能需求，遵循该开发流程还能明显提升中大型项目中 多人协同开发 效率。
远程调试平台源码
Fork项目
如果要调试华炎魔方平台源码，请Fork，即“派生” 华炎魔方平台源码，后续我们使用GitPod在线开发Fork后的项目的话就可以把开发后的代码提交到Git仓库。
我们欢迎大家提交 PR 到平台源码，贡献智慧给华炎魔方开源社区。
调试魔方平台
运行项目
只要在浏览器中输入地址 https://gitpod.io/#{之前Fork下来的Git仓库地址} 即可使用 Gitpod 启动远程开发环境。
比如访问地址 https://gitpod.io/#https://github.com/steedos/steedos-platform 即可在线运行 华炎魔方平台源码 项目，可以把#号后面的Git仓库地址换成您希望运行的任何华炎魔方项目的Git仓库地址。
在浏览器中打开项目后，会自动在项目根目录执行yarn指令安装项目依赖项，并自动执行yarn start指令运行项目。
需要注意的是，平台源码项目根目录运行的是源码项目内的社区版项目，该项目路径为 steedos-projects/project-community，执行npx create-steedos-app命令创建的模板项目并不是来自于这个文件夹，而是来自单独的 华炎魔方模板项目。
跟运行魔方项目一样，第一次运行项目时会在控制台看到提示“请配置环境变量STEEDOS_CLOUD_SPACE_ID和STEEDOS_CLOUD_API_KEY”，但是我们也可以看到项目运行起来后自动打开了一个浏览器窗口访问运行好的华炎魔方，只是因为没有激活华炎魔方没有账户可以登录使用所以显示了激活华炎魔方的初始化界面。
请在云平台”管理控制台”应用的“我的魔方”中找到对应的私有部署记录，并在该初始化界面中输入点击私有部署记录详细界面右上角“复制激活参数”按钮复制的内容，其中已经包含了激活华炎魔方需要的两个环境变量，提交后会自动把相关环境变量值保存到路径为steedos-projects/project-community的社区项目的.env.local文件并且页面会自动跳转到登录界面，使用私有部署的华炎魔方初始账户登录即可进入系统主界面了。
[steedos-cloud]
STEEDOS_CLOUD_SPACE_ID=#会自动填充为初始界面中输入的环境变量值
STEEDOS_CLOUD_API_KEY=#会自动填充为初始界面中输入的环境变量值项目访问地址
如果项目运行完成后没有自动打开浏览器窗口访问项目的话，可以手动在浏览器中输入Gitpod-Workspaces访问地址并加上要访问的项目端口号作为前缀即可访问它。
比如假设之前开启的远程开发环境打开的Workspaces访问地址为https://white-silverfish-e5vy4oyh.ws-us25.gitpod.io，我们只要输入地址 https://5000-white-silverfish-e5vy4oyh.ws-us25.gitpod.io即可访问刚运行起来的项目。
调试魔方平台源码
按上面步骤运行起来模板项目后，我们就可以调试魔方平台源码了，这里指的源码是指下面两个文件夹中的代码。
- packages：该文件夹内存放的华炎魔方依赖的各种内核NPM包项目源码，可以参考该文件夹内的相关
README.md文件来了解相关项目的介绍说明。 - services：该文件夹内存放的华炎魔方依赖的各种微服务NPM包项目源码，可以参考该文件夹内的相关
README.md文件来了解相关项目的介绍说明。
在改动项目源码后，需要停止服务并重启来测试确认代码效果。
调试Creator项目
运行项目
要运行Creator项目源码，请在上面“运行模板项目”小节基础上执行以下步骤：
- 请先访问之前跑起来的模板项目，并输入华炎魔方初始账户和密码来确认之前已经成功激活和初始化好魔方项目。
- 按
CTRL + C来停止之前跑起来的模板项目。 - 命令行
cd进入creator文件夹。 - 执行
yarn命令安装项目依赖包，并确保最后没有报错日志。 - 执行
yarn start命令来运行creator项目。
运行该项目有以下注意事项：
.env.local文件中的端口号为3100，该端口号在package.json的start指令中写死了，不可以变更端口号，如果想换端口号的话，需要同时把start指令中的端口号参数同时改掉。- 请不要变更
.env.local文件中的MONGO_URL指向其他数据库，默认它指向的是之前运行模板项目时初始化过的数据库，否则无法使用华炎魔方初始账户来登录系统。
项目访问地址
上面的Creator项目运行起来后，是不会自动打开浏览器窗口来访问项目的，可以手动在浏览器中输入Gitpod-Workspaces访问地址并加上要访问的项目端口号作为前缀即可访问它。
比如假设之前开启的远程开发环境打开的Workspaces访问地址为https://white-silverfish-e5vy4oyh.ws-us25.gitpod.io，我们只要输入地址 https://3100-white-silverfish-e5vy4oyh.ws-us25.gitpod.io即可访问刚运行起来的项目。
调试Creator源码
按上面步骤运行起来Creator项目后，我们就可以调试Creator项目源码了，这里指的源码是指Creator文件夹内的代码，可以参考该文件夹内的相关README.md文件来了解相关项目的介绍说明。
在改动Creator项目源码后，不需要重启服务来测试确认代码效果，因为该项目有热启动功能，只要改动源码会自动重新编译运行项目。
需要注意的是，在Creator项目中的系统配置文件 steedos-config.yml 并没有生效，而是使用根目录下名为 settings.json 配置文件来配置系统参数，它支持的参数与前者是一样的，只是编写格式不一样而已。
Debug模式调试
使用Gitpod启动远程开发环境，在调试开发华炎魔方项目时，可以像在本地开发一样使用VS Code的Debug调试工具调试程序代码。
yarn start 命令启动服务就可以直接开始断点调试了。
源代码版本管理
使用Gitpod启动远程开发环境，无论是调试开发华炎魔方项目还是平台源码，都可以像在本地开发一样使用VS Code的源代码管理工具来更新、提交代码，或者查看代码提交历史等，只要启动Gitpod远程开发环境相关插件会在初始化时自动安装好，您可以直接使用它们，相关使用教程请参考 Visual Studio Code 源代码管理官网教程。
关于Gitpod
Gitpod是一个在线IDE，可以从任何GitHub页面启动，只需在任何GitHub-URL前加上https://gitpod.io#，或安装Chrome插件 Gitpod - Always ready to code 为GitHub页面添加一个按钮，点击它即可一键启动远程开发环境。
在几秒钟之内，Gitpod就可以为您提供一个完整的开发环境，包括一个VS Code驱动的IDE和一个可以由项目定制化配置的云Linux容器。
Gitpod旨在取代本地桌面开发，所以我们强烈推荐使用它来启动远程开发环境，以免去本地安装开发环境的繁琐过程，如果需要本地安装开发环境请参考文档：
浏览器设置
为了在使用Gitpod时获得最好的体验，我们建议您将 Gitpod 列入白名单，以获取您的浏览器上的以下权限：
- 将内容从剪贴板粘贴到Gitpod工作区。
- 弹出窗口，在一个新的浏览器选项卡访问您开发的服务。
以下是在Chrome浏览器中的配置方法，Gitpod官网 有详细说明，详情请参阅： https://www.gitpod.io/docs/configure/browser-settings。
设置好后你甚至可以把本地文件拖动到Chrome浏览器上Gitpod工作区中相关文件夹内来复制上传文件，大大提高开发效率。
剪贴板
- 在chrome浏览器中输入地址
chrome://settings/content/clipboard来打开“剪贴板”设置界面。 - 在右侧内容界面中找到“允许查看您的剪贴板”栏，点击其旁边的“添加”按钮。
- 在弹出的“添加网站”窗口中输入
[*.]gitpod.io然后点击添加按钮即可。
弹出式窗口和重定向
- 在chrome浏览器中输入地址
chrome://settings/content/popups来打开“弹出式窗口和重定向”设置界面。 - 在右侧内容界面中找到“允许发送弹出式窗口并使用重定向”栏，点击其旁边的“添加”按钮。
- 在弹出的“添加网站”窗口中输入
[*.]gitpod.io然后点击添加按钮即可。
华炎魔方为企业客户提供了 Gitpod 中国区域云服务，请把上面配置中的 [*.]gitpod.io 换成[*.]vscode.steedos.cn，了解更多请 联系我们。
使用本地VS Code
默认情况下，使用Gitpod启用远程开发环境是打开浏览器运行的，我们可以访问 Gitpod官网个人设置页面 勾选 Open in Desktop IDE 选项来开启使用本地VS Code打开远程Gitpod项目的功能，该功能开启后，每次打开Gitpod项目时就会提示用户是否使用本地VS Code打开项目。
Pin
默认情况下，使用Gitpod启用远程开发环境打开的项目在停止访问后，连续30分钟不访问该项目的话，相关资源会被自动释放，后面再次访问该项目的话会重新开启新的开发环境，这意味着上次访问该项目时未提交到Git仓库的所有代码以及数据库中数据都将丢失。
我们可以在 Gitpod官网Workspaces页面 看到之前打开过的所有Gitpod项目列表，在该列表上找到希望不自动释放资源的Workspace，点击右侧下拉菜单按钮，在展开的菜单中勾选“Pin”选项即可把该Gitpod项目设置为不自动释放资源。
Pin后的Gitpod项目，不但会保留未提交到Git仓库的代码，而且在开发环境中安装过的依赖项会持续留存于开发环境中，所以再次进入Pin后的项目启动服务速度比新开的项目快很多。
下载
我们可以在 Gitpod官网Workspaces页面 看到之前打开过的所有Gitpod项目列表，在该列表上找到想下载的Workspace，点击右侧下拉菜单按钮，在展开的菜单中点击“Download”选项即可把该Gitpod项目下载到本地，然后把下载之后的文件重命名，在其后缀名加上 .tar.gz 就可以解压缩，解压缩后的文件是 /workspace 文件夹中的所有文件，其中也包括MongoDB数据库文件。
分享
我们可以在 Gitpod官网Workspaces页面 看到之前打开过的所有Gitpod项目列表，在该列表上找到想分享的Workspace，点击右侧下拉菜单按钮，在展开的菜单中点击“Share”选项即可把该Gitpod项目设置为分享状态，再点击一次又可以把该Gitpod项目设置为非分享状态。
只要把处于分享状态的Workspace的项目访问地址发送给其他Gitpod用户就可以实时分享远程开发环境。
授权
访问MongoDB
使用Gitpod远程启动华炎魔方模板项目的开发环境中已经预先为VS Code安装了名为 MongoDB for VS Code 的插件，可以使用该插件来访问华炎魔方项目连接的MongoDB数据库，以便查看数据库中的数据调试程序。
重启远程开发环境
有时我们会因为某些原因希望重启整个远程开发环境而不希望开启全新的远程开发环境，比如端口被占用无法正常启动服务时可能重启整个开发环境服务是比较快捷的方式。
要重启远程开发环境，请在 Gitpod官网Workspaces页面 中浏览目前打开的所有Gitpod项目，然后在列表上找到希望重启服务的那条记录，点击其右侧下拉菜单按钮，在展开的菜单中勾选“Stop”选项即可停止该Gitpod项目，待停止成功后重新点击其中的“Open”选项即可重新打开该项目。
重启VS Code
有时我们会因为某些原因希望重启VS Code，在浏览器上的Gitpod远程开发环境中，只需要刷新浏览器即可重启VS Code，而不需要重启整个Gitpod开发环境，非常方便快捷。