详细说明¶

创建应用，填写基本信息¶

在 “我的应用” 页面点击 “添加新应用” 按钮可以新建应用。选择 “普通应用（新建）” 选项创建一个空白应用，或者选择一个已有应用作为模板创建。

先填写应用的基本信息：

• 应用图标：展示用图标，具体效果请见 应用卡片

• 应用名称：应用在数据库中的名称，必须是唯一的，若重复，则无法提交

• 应用标题：展示给用户的标题

• 应用描述：一段简短的描述，用于介绍应用的基本信息，背景、用途等

• 应用类型：定义应用的类型

  • 容器云作业：一次性运行的容器作业，结束/失败后不重试，常用于计算任务

  • 容器云服务：作为服务持续运行的作业，结束/失败后自动尝试重启，常用于部署服务

  • 高性能作业：直接向 slurm 提交裸金属作业

• 类型标签：将应用与一个或多个类型关联起来，方便用户在 应用列表 页分类查看、检索

填写基础命令¶

一个应用的运行通常需要执行一条或多条命令。星光提供了两种应用运行逻辑的定义方式。

命令模式¶

一个命令可以分为多段来定义，例如 echo -e "hello world!\n" 这条命令，包含 “命令名”、“参数名”、“参数值”，我们可以分 3 次输入。

输入完成后可预览执行命令如下：

"echo" "-e" "hello world!\n"

脚本模式¶

如果需要执行多条命令，或者执行逻辑比较复杂，就需要使用 脚本 运行模式，在该模式下，我们可以编写一个脚本文件（可以是 shell、python 等任何目标执行环境支持的脚本文件）。

将 执行方式 开关切换到 脚本 模式来使用这个功能。

脚本内容 编辑框已经支持 shell 脚本和 python 脚本的语法高亮，我们可以通过 脚本类型 的下拉选项来切换使用 sh、bash 或 python。

如果需要使用其它脚本语言，也可以直接修改 脚本类型，填写所需使用的脚本解释器。

从 运行命令 一栏可以确认实际运行的指令。

添加控件，关联到命令¶

一个应用（软件）的运行一般需要使用者提供相应的输入参数，比如命令参数、文件等。星光提供了所见即所得的 应用表单 编辑方式，使用 “控件” 来实现通过表单设置应用输入参数。

添加控件¶

表单编辑面板包含了三部分，从左到右分别为控件面板，预览面板和属性面板。预览面板的上半部分显示的是命令的预览，下半部分显示的是 应用运行 应用表单 页面的表单预览。

移动光标至左侧控件面板选择区，在所需要的控件上方（此时光标变化为可移动标志 ）摁住鼠标左键并移动至中间的表单区，放开左键即可完成一个控件的添加。

如果需要重新排序表单区中已经添加的控件，点击控件以选中它，在其左上角的移动标志 上点击并摁住鼠标左键，上下移动至所期望的位置时松开左键。

应用的输入参数通过控件转换成相应的变量，并传递至程序或脚本。不同控件类型用于处理不同类型的变量，下面列出了各控件对应的变量类型：

编辑控件¶

鼠标单击控件可以选中一个控件，此时右侧的面板可以编辑这个控件的信息，包括 变量名称 、 变量类型 、 控件标签 等等。

此外，也可以直接与编辑面板中的控件互动，设置其默认值。

绑定到命令行¶

要让用户在控件中填写的参数值能被程序或脚本中所使用，可以将其绑定到命令行。

点击一个控件，在右侧面板的 行为属性 面板启用 绑定到命令行参数 即可将其绑定到实际要执行的命令上。您可以在 应用执行命令 面板预览绑定的结果：

绑定到环境变量¶

程序或脚本有时需要从环境变量中读取变量值，而不是通过命令行参数。

星光提供了控制环境变量的方法：

在 配置信息/运行环境/环境变量设置 处增加一个变量来将用户输入的值绑定到环境变量上。此时，“环境变量值” 处可以输入 $(inputs.ValueName) 来获取输入的变量（将 ValueName 替换为目标控件的 “变量名称”）。

更详细的指南请参考 环境变量

设置运行资源¶

应用编辑者可以设置应用可运行的集群、分区和套餐，同时设置其运行可以使用的容器镜像等，以此 限制应用在特定的环境上运行。

集群、分区与套餐¶

点击 配置信息 、 资源需求 , 在 集群类型 处点击 “设置” 按钮，打开 “运行设置” 面板，配置该应用可用的运行集群、分区和套餐。

指定集群分区¶

设定作业运行所用的集群、分区、套餐或节点数，设置后用户将仅能以指定的资源提交作业。

可用于为容器类应用指定固定套餐，或为高性能类应用指定运行的集群分区以及节点规模。

目标集群分区¶

用于设定作业可运行的集群、分区范围，设置后用户可在设定的范围内根据自身需要选择作业所用资源

• 如完全不添加任何条目，则默认为所有符合应用类型（K8s 或 HPC）的环境均可提交；

• 若添加的条目仅设定了集群，则默认为该集群的所有分区均可提交；

• 若添加的条目设定了集群和其对应的若干个分区，则该应用可以在这个规定的范围内提交。

展开 “节点设置” 项还可以对高性能类应用提供节点数的定义，可以设置默认值、最大值、最小值、是否允许用户修改等。

容器镜像¶

对于容器类应用，需要设置其容器镜像。在 配置信息/资源需求/容器镜像设置 处可以选择星光平台提供的镜像，输入框中支持输入关键字进行镜像搜索。

环境变量¶

应用运行时所需使用的环境变量可在 配置信息/运行环境/环境变量设置 处设置。如果设置固定值的环境变量，直接输入需要的值即可；如果需要通过用户的输入计算，则可以输入一个表达式。

表达式是一个内嵌 JavaScript 的字符串，通过 $() 来嵌入简单 JS 表达式，通过 ${} 来嵌入匿名函数；通过访问变量 inputs 以获取某变量的输入值。详细的表达式使用请参考 环境变量表达式，以下是两个示例：

1. 使用文本控件绑定的变量 text1 作为环境变量的值：

   $(inputs.text1)
   

2. 根据开关控件绑定的变量 enable 为环境变量赋值：

   $(inputs.enable?"--debug":"--info")
   

   该示例中，开关控件打开， enable 为真，表达式输出值为 "--debug"。

访问入口¶

访问入口提供从公网访问应用运行后创建的网络服务（ SSH 服务、HTTP 服务等）的渠道。通过在 配置信息/运行环境/访问入口设置 处点击 “添加” 按钮可以进行访问入口创建，设置需要的协议、目的端口后，即可创建一个访问入口。

对于 HTTP 和 HTTPS 协议，星光提供权限验证服务：

• 私有：只有运行应用、提交作业的用户可以访问；

• 登录用户：只有星光平台的用户可以访问；

• 不验证：任何用户可以访问（注意：除非所创建的网络服务本身已经具备完善的身份验证、授权功能，否则 不 应启用该项设置）。

访问入口也可以由用户在提交作业时（ 容器应用高级配置 ）或作业成功运行后（ 访问入口 ）自行创建。

兼容工作流¶

设置输出¶

由于在工作流中不同步骤间的应用是通过输入、输出来衔接，为了让应用能够嵌入到工作流中，需要进一步显式地定义应用的输出信息。在 配置信息/结果参数 可以设置该应用结束时输出的变量。

点击 “添加” 按钮可以新建一个输出变量并定义应用如何输出该变量。

新建变量时，需要先选择变量的类型，除了在下拉列表中选择需要的类型之外，还可以在打开下拉列表后的选项，将其设置为 “单项值” 或 “值列表” 以及是否 “允许空值”。

• 如果选择 “单项值” 模式，表示该变量类型即为而所选类型；

• 如果选择 “值列表” 模式，表示该变量类型是所选类型的数组；

• 如果启用 “允许空值” ，则表示该变量可以为空（仅选择 “单项值” 模式时，才支持启用 “允许空值”）。

1. 最经常被使用的输出类型是文件类型，一般对应着应用运行过程中产生的日志或结果文件；为了匹配这些文件，可以在 “匹配文件” 处输入一个匹配模式。匹配模式可以使用 CWL 的表达式，也可以使用 shell 中基础的通配符，参考下列示例：

   • 匹配所有日志（以 .log 为后缀）： *.log

   • 匹配以输入控件中定义的文件名开头的文件： $(inputs.filename)*

2. “标准输出” 和 “标准错误输出” 则是两种特殊的文件类型，它们分别代表命令的 stdout 流和 stderr 流。定义这两种类型的输出类似于在执行命令时把指令输出重定向到文件中，即：

   ./application param 1>out.log 2>err.log
   

3. 有时，我们会希望应用的输出结果是文件以外的其他类型，例如数字，字符串或数组，而由于匹配模式只能匹配文件，此时则需要使用 “表达式” 功能将文件处理为其他类型：

   # 将匹配到的文件列表转换为字符串列表
   $(self.map(function(file){ return file.contents }))
   

   备注

   此处的 self 为内置变量，它是一个包含所有匹配到的文件对象的数组。如果没有匹配到文件，则 self 长度为 0 ；如果匹配到单个文件，则 self 的值是一个包含单个元素的数组。

附录¶

容器访问工具¶

除了 进阶使用（访问运行中的容器） 中提到的 ttyd 之外，星光平台还提供了以下以下容器访问工具：

openssh¶

如果您的容器中安装有 openssh ，那么您可以启动一个标准的 openssh 服务器。

openssh 的启动通常需要 root 身份，而一般容器作业的用户并不是 root ，为此星光提供了一个工具来帮助您启动 openssh：

/app/bin/sshdctl start

webssh¶

“webssh” 同时提供了 SSH 和网页终端两种访问模式，用户可以使用其中任意一种方式访问容器的终端。它具有以下特性与限制：

1. 只需要以 普通用户身份 启动一个 “webssh” 服务，就可以同时提供简单的 ssh 服务和网页终端服务。

2. “webssh” 具有 会话 机制；会话概念类似于 “termux” 中的会话，每个会话独立记录用户的上下文，保存用户执行的操作。您可以暂时退出当前会话加载一个新的会话，在需要时回到之前的会话；也可以让多个网页或 SSH 链接共享一个会话。

3. “webssh” 服务的网页访问采用与星光平台相同的鉴权方式，使用 token 进行身份验证，在使用时有如下限制：

   1. 需要通过星光平台的访问入口进入；

   2. 无法共享给其他用户；

   3. 无法在修改了运行模式的容器中使用。

4. “webssh” 提供的 ssh 服务 不是全功能 的，仅提供基本的交互式会话，因此一些依赖 ssh 服务器高级功能的需求将无法满足，例如通过 vscode 远程链接、访问 sftp 服务器、执行 X11 转发等；如果有类似的需求，请参考 openssh

启动¶

请使用星光提供的管理程序来启动 “webssh” 服务：

/app/bin/websshctl start

# 先设置环境变量
export SL_WEBSSH_PORT=9022
export SL_WEBSSH_WEB=9023
# 然后再执行管理程序
/app/bin/websshctl start

需要在访问入口处增加 ssh 和网页的访问入口：

code-server¶

“code-server” 服务器，可以让您通过浏览器访问并使用 vscode 的绝大部分功能。

访问 “/app/common/code-server” 查看可用的 “code-server” 版本。确定您希望使用的版本后，执行对应文件夹的 “bin/code-server” 可执行程序可以启动程序。

假设希望使用的版本是 “4.20.1” ，对应执行指令为：

/app/common/code-server/4.20.1/bin/code-server --cert --bind-addr 0.0.0.0:8080 .

该指令会启动一个监听 8080 端口的 code-server 服务器。如果是第一次执行，code-server 会在用户家目录生成一个默认配置文件，位于 “${HOME}/.config/code-server/config.yaml”。

查看这个文件，可获取随机生成的密码，或者自行修改该文件并重新启动 “code-server” 以应用新的密码。

为了访问该服务，需要在访问入口中添加 code-server 的入口 8080。

入口脚本¶

为了更方便的启动上述的几个访问服务，星光提供了一个入口脚本，您可以使用该入口脚本来启动上述程序。该脚本路径为 “/app/entrypoints/runfile-with-option.sh”。

使用脚本¶

如果您的应用没有默认的入口脚本，可以直接将该脚本作为应用要运行的命令：

如果您原本有需要执行的入口脚本，可以将原本的脚本作为一个参数传递给前置脚本。这里我们假设原来需要执行的脚本是 /app/entrypoints/ngc-services.sh ：

/app/entrypoints/runfile-with-option.sh /path/to/my/script arg1 arg2

启用功能¶

默认情况下，该入口脚本不启动任何网络服务，需要设置环境变量来开启需要的功能。在应用编辑页的 配置信息/运行环境/环境变量设置 处，添加一个名为 SL_FEAT_OPT 的变量，并且在 环境变量值 处填写所需要启用的功能。功能之间使用英文逗号 , 隔开，不要包含空格。

目前可用的功能如下：

• init ：等待星光将容器初始化完成后再继续操作，如果要使用，需要放在第一位

• sshd ：启动 sshd 服务器，需要容器内有对应软件；一般监听 22 端口

• ttyd ：启动 ttyd 服务器；监听 7681 端口

• code-server ：启动一个 code-server 服务器；监听 8080 端口

• webssh ：启动一个 webssh 服务器；监听 8022(ssh) 和 8023(web) 端口

• proxy ：为其他需要启动的服务设置上网代理，如果要使用，需要放在其他服务之前