docs: 补充脚本编写文档.

This commit is contained in:
LamGC 2021-08-20 16:40:41 +08:00
parent 342087cd01
commit 3fcd506f0c
Signed by: LamGC
GPG Key ID: 6C5AE2A913941E1D
3 changed files with 113 additions and 0 deletions

View File

@ -0,0 +1,36 @@
## 可用的触发器
### Once 触发器
Once 触发器只会在启动后执行一次,适用于初始化等操作。
示例:
```groovy
trigger ("once") {
run {
// do something...
}
}
```
参数:
- (没有参数)
`it` 对象:无
### Timer 触发器
Timer 触发器通过设定的 Cron 时间表达式,根据时间触发执行,可用于定时检查等操作。
示例:
```groovy
trigger ("once") {
time "0 0 12 * * ? *"
run {
// do something...
}
}
```
参数:
- `time`Cron 时间表达式
`it` 对象:无

View File

@ -0,0 +1,54 @@
## 开始使用 SSH
哨兵为脚本包装了一个 SSH 客户端,通过 SSH 客户端,脚本可以通过 SSH 连接实例并执行命令、通过 Sftp 访问文件、设置端口转发。
### 创建一个 SSH 会话
SSH 会话不止一个,一个脚本可以创建多个 SSH 会话来同时做不同的事情,也可以多个脚本创建多个会话来做不同事情,会话之间互不干扰。
创建会话的方法很简单,只需要这么做:
```groovy
def session = instance.ssh().createSession()
```
这样就能创建一个会话了,至于 SSH 的连接认证什么的,只需要交给哨兵完成即可!
> 注意:会话不保证创建成功,如果创建失败,方法将抛出一个异常。
### 通过 SSH 执行命令
在得到 SSH 会话后,就可以开始执行命令了。
首先需要创建一个命令执行会话(虽然本质上是一个通道):
```groovy
def execSession = session.createExecSession("date")
```
设定后,我们还需要设置命令的标准输出和标准输入,以方便我们获得命令的输出,和向命令输入内容(比如参数):
```groovy
// 这里如果不需要获取并处理的话,可以不设置,
// 也可以将输出设定为哨兵的标准输出,也是可以的。
execSession.setOut(System.out)
// 这里也设置为哨兵的标准输入,可以由管理员主动输入内容。
execSession.setIn(System.in)
```
最后,调用 `exec()` 方法,执行命令并等待命令运行完成即可。
如果需要执行命令后自动输入之类的异步操作呢?可以改用 `exec(true)` 进行异步执行,然后使用 `waitFor()` 等待命令执行完成即可。
命令执行完成后,除了可以检查输出内容来检查程序执行结果外,还可以通过退出代码了解,只需要调用 `exitCode()` 获取退出码即可:
```groovy
if (execSession.exitCode() == 0) {
println "命令执行成功!"
} else {
println "命令执行失败,退出代码不为 0退出码${execSession.exitCode()}"
}
```
### 完整示例代码
```groovy
run {
def session = instance.ssh().createSession()
def execSession = session.createExecSession("date")
execSession.setOut(System.out)
execSession.setIn(System.in)
// 同步执行,并等待命令执行结束。
execSession.exec()
// 除了上述的 if 判断外,也可以使用 Groovy 的字符串嵌入语法。
println "命令执行完成,退出代码:${execSession.exitCode()}"
}
```

View File

@ -0,0 +1,23 @@
## 注册并使用触发器
触发器可以在适当的时候执行脚本所注册的运行代码,使用触发器,哨兵可以在某项事件发生时,触发脚本执行某些操作,而无需脚本手动检查。
### 注册触发器
注册触发器的方法非常简单:
```groovy
trigger("timer") {
// timer 触发器的参数 "time", 填写 Cron 时间表达式.
time "0 0 12 * * ? *"
run {
// 这里编写当到达时间时所需执行的动作.
}
}
```
其中,`"timer"`是触发器名称,`time` 是触发器参数,不同的触发器有不同的参数,也可能没有参数(比如 Once 触发器),`run` 代码块是每个触发器必须有的当满足条件时run 代码块将会被执行。
run 代码块有个隐藏参数 `it`,如果触发器有参数,将通过该参数传递至 run 代码块,供脚本使用。
> 注意:每个触发器所能提供的东西并不一样,具体信息见[触发器文档](可用的触发器.md)。
当注册好了触发器后,只需要等待触发器,在合适的时机触发执行任务即可!