TLDR页#

整个内容以科研编程入门为主线串联，更加适合新生入学学习，内容有点多，Too Long; Didn’t Read（TLDR），所以这里我们提供一个手册页，主要以串联日常使用平台需要的操作为主，具体内容会有链接提供。

手册主要包括以下几个部分：

  1. 连接研发中心内网：通过研发中心VPN；或者本地/远程连接到在研发中心/411教研室的计算机

  2. 平台JupyterHub账号注册与登录：团队搭建了Jupyterhub，注册、登录即可进入

  3. 登录后使用JupyterLab：编写markdown与jupyter notebook

  4. 与他人协作：使用Git、GitHub或者GitLab

  5. 使用集成开发环境工具：用VSCode连接平台使用或贡献代码

  6. 技术研发类项目的数字化管理：联合使用各类工具，与大家分享各种资源

这些内容我们会单独录制一个工具使用视频，培训结束后推出供大家参考。

1 连接研发中心内网#

有电脑在研发中心或者411的同志就比较容易了，不需要做任何操作，可以跳过这一步。

其他教研室因为各方面原因，暂时还没有或不方便开通内网连接，所以推荐大家在本地电脑安装使用研发中心VPN。

VPN的安装使用方式请参考这里

2 平台JupyterHub账号注册与登录#

注册与登录和一般网站的没有区别，当你连接入内网后，在浏览器中输入： http://jupyterhub.waterism.com:666/ 就能访问。

如果你需要注册和登录的详细介绍请参考这里

3 使用JupyterLab#

关于JupyterLab与JupyterHub还有Jupyter Notebook之间的联系，可以参考这里，简而言之，我们不用管Hub，我们用的是Lab，写的是Notebook

写Notebook的时候主要写代码和文字：

  • 代码主要是Python，另外平台还添加了对R、Julia和Java的支持，但是对Java的支持并不友好，所以还是推荐大家使用前面几种语言编写脚本程序。推荐Python或者R等的原因，主要是因为它们更加简单，且开源资源更丰富，如果您会使用Java编写一些计算程序，那学习使用Python或R只有很少的时间成本。不推荐Java的原因还有它更加适合于软件开发，尤其是部署运行各类软件系统的程序，科学工程计算中使用它的相对还是比较少。如果您对计算效率有很高的要求，那建议用C/C++或者Julia来编写相关程序，前者仍然是最常见的高效率编程语言，后者是近10年来发展起来的，学习成本和Python相当，运算效率还很高，已被地学相关领域广泛使用。教程提供了Python基础的介绍，详见这里

  • 文字主要通过markdown来编写，在Jupyter Notebook中和在后缀名为.md的文件中均可编写。markdown能够帮助我们在使用少量格式标记的情况下，就能编写格式漂亮的文档，从而让我们专注于制作内容，功能虽不如word强大，但是已经足够我们日常使用，且非常轻量级，易于在网页端和其他人分享您写的内容。关于markdown的写法以及如何在jupyterlab上写markdown文件请点击这里查看。

使用JupyterLab的一个完整示例可以参考这个例子，这是一个深度学习水文建模的简单实例。这里您可以在网页看看就行了，具体怎么运行它，完成下一步（4.与他人协作）的相关操作后就能掌握。

另外，大家如果遇到问题，不是太好解决的，可以考虑保存好自己的文件后重启自己的jupyter:

选中后，点击“stop my server”，然后再“start my server”，即可重启。

4 与他人协作#

平台借助Git和GitHub/GitLab等工具实现团队协作。现代科技的进步越来越依赖团队协作，即便是前沿科研，对于我们这种工科类学科，单兵作战的局限性也越来越强，对于技术研发更是如此。

Git是一个版本控制工具，可以帮助我们有效地管理本地代码等文件的历史版本，通过GitHub或GitLab这类Git云软件服务，结合本地Git的使用，能够有效地支持多人协作。关于它们的介绍，可以参考这里。

平台上已经预置了Git，就不必再安装了，连接到平台后可以直接使用。如果您想在自己电脑上也使用git，Windows下默认是没有的，所以需要去git官网下载git软件并安装，安装时候一路默认即可。

我们在平台Jupyter上安装有Git插件，能支持大家可视化操作Git（如下图所示），可以配合终端来使用Git，结合终端和可视化界面能帮助我们更灵活地使用计算机。

关于Linux终端的一些特别常用的命令介绍可以参考这里，通过简单练习，就能掌握一些基本使用方法来操作文件和文件夹以及使用一些软件。更多的Linux终端Bash指令，可以参考这里。

平台上打开终端只需要如下图所示操作即可：

最开始常用的Git指令包括以下几个：

# 下载代码，xxx表示git仓库的远程地址
git clone xxxxx
# git提交三连操作
git add -A
git commit -m "说明文字，说明本次提交的内容主要是什么"
git push

其他常用的git指令可以参考这里

Github的账号需要自己注册，去GitHub官网注册，Github是国外的网站，所以访问不是特别稳定，但是它上面汇集了全球的开源资源，例如awesome-open-hydrology列出了很多和水文相关的开源资源，还是非常值得大家在上面参考借鉴的。

Github现在已经不支持HTTPS协议下对代码的推送（可以简单理解为不支持输入用户名密码的验证方式了），所以我们需要通过SSH来建立本地和Github服务器上我们的代码仓之间的连接（可以简单理解为一种密钥配对的验证方式），我们需要首先在本地生成一对密钥，一个公钥一个私钥，公钥上传到GitHub上，私钥留在本地以配对验证。具体的方式可以参考这里。

因为Github访问不是特别稳定，且适合开源代码，大家可以自行想办法解决访问不稳定的问题，如果不能访问GitHub，团队还提供了内部GitLab服务，GitLab和GitHub是一种东西，只不过这里我们用它来管理内部不便于公开的代码等文件（也有公开的）。GitLab的注册在这里：http://124.93.160.156:18888/users/sign_up ，您实名注册后，管理员会通过，GitLab的使用和Github相似，熟悉一种，另一种的使用就很简单了。不过GitLab上面主要是我们内部提供的资源，相对没那么丰富。

掌握这些工具后，您应该就能在平台上fork并clone Github上本教程内容或者GitLab上本教程的内容，并运行其中代码。

5 使用集成开发环境工具#

Jupyter是很好的工具，但是也存在一些局限，典型地是它对代码调试不是特别友好，基本上只能在Notebook一个计算单元内调试，另外，对于比较成体系的代码项目，尤其是模型算法等的自主研发，使用它不是很好的选择，所以这里给出使用集成开发环境（IDE）工具来编写代码的方式，并重点介绍关于如何连接到平台的数据和计算资源方面的内容。

因为VSCode是一个以插件驱动各类编程语言开发环境的工具，能有效应对多语言，所以这里就以它为主介绍，这部分内容我们在这里提供了详细的步骤介绍，大家可以跟着一步步执行。

6 技术研发类项目的数字化管理#

本教程主要还是初级内容，但是内容已经不少了，所以就不再继续涉及过多关于技术研发所需的编程相关内容了，等大家熟练掌握这些工具使用后，并且觉得这种教程形式还不错的话，那么后续我们还会推出新的教程介绍更多研发用得到的东西。但是这里还是有必要提一提关于研发项目的数字化管理的重要性。

要开展研发工作，信息化、交流、汇报的模式也应转型到真正研发队伍的模式，构建信息化开发的标准流程，文档、文献、代码全部升级管理，这些内容对形成团队力量特别重要。没有良好的数字化管理，有再好的想法和问题引领也很难有效率、有质量地实施，尤其对于技术类的项目内容。实质上，科研工作有了这些东西，开展也会更顺利。

这里推荐以语雀为管理项目研发的主要交流阵地，我们常用的工具大多是即时通讯工具或者流程管理工具，例如微信和钉钉，它们并不是知识管理工具，实际上，和钉钉一样，语雀也是阿里自己开发使用的。因为项目研发的内容通常还是需要有所沉淀，即时通讯工具在这方面并不能很好地胜任，通过语雀我们能较好地管理我们的研发内容，例如：

资源的共享能让进入小组的同志快速地了解组内已有内容，不至于因为信息不足导致实力不能发挥。