DSL 配置详解
# 整体结构
DSL 项目的 YAML 只有四个顶层节点,除 run 外都可以不写:
description: 项目描述(随便写,仅用于说明)
run: # 生命周期流程,status 必填
start: {}
status: {}
stop: {}
restart: {}
reload: {}
fileChangeReload: false # 文件变动时是否自动执行 reload
execPath: ./ # 在哪个目录执行脚本
file: # 项目文件备份 / 版本快照(可选)
backupCount: 5
backupSuffix: [ '.jar', '.html' ]
backupPath: /data/jpom_backup
diffBackup: true
versionCount: 3
versionPath: /data/jpom_version
config: # 其它开关(可选)
autoBackToFile: true # 是否自动备份控制台日志
log: # 项目自己的运行日志文件(可选,见下)
- name: 应用日志
path: logs/app.log
charset: UTF-8
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# run 下的五个流程
| 流程 | 什么时候执行 | 是否必填 |
|---|---|---|
start | 点【启动】 | 建议必填 |
status | 定时轮询项目状态、启动/停止后校验结果 | 必填(不写保存会报错) |
stop | 点【停止】 | 建议必填 |
restart | 点【重启】。配了就跑它,没配则自动 stop + start | 可选 |
reload | 点【重载】;fileChangeReload: true 时文件变动也会触发 | 可选(仅 Dsl 项目支持) |
每个流程内部结构完全一样:
start:
scriptId: project.sh # 要执行的脚本(三种来源,见下)
scriptArgs: start # 传给脚本的参数,按空格切分
scriptEnv: # 额外的环境变量(可选)
BOOT_ACTIVE: test
JAVA_OPTS: -Xms512m
2
3
4
5
6
scriptArgs 的细节
- 按空格切分后追加在脚本路径后面,等价于
bash project.sh start - 参数里需要带空格的场景,建议改用
scriptEnv传,别在scriptArgs里写引号
# scriptId 的三种来源(按顺序匹配)
| 写法 | 含义 | 前提 |
|---|---|---|
G@xxxx | 引用【系统管理】->【资产管理】->【脚本库】里的脚本,xxxx 是脚本库脚本的标记 | 脚本要已同步到该节点 |
| 节点脚本的 scriptId | 引用【脚本管理】->【节点脚本列表】里的脚本 | 该脚本已下发到当前逻辑节点 |
文件名,如 project.sh | 项目目录内的脚本文件(相对项目目录) | 文件必须真实存在 |
三种来源都没命中
启动时日志会提示「脚本模版不存在」或「缺少脚本」,并带出具体 scriptId。先确认脚本是否已同步到这台节点。
# 脚本里能拿到哪些变量
| 变量 | 内容 |
|---|---|
PROJECT_ID | 项目 ID |
PROJECT_NAME | 项目名称 |
PROJECT_PATH | 项目目录(绝对路径) |
PROJECT_LOG_FILE | 该项目控制台日志文件的绝对路径 |
变量覆盖顺序
工作空间变量 → 项目 DSL 环境变量 → scriptEnv,后者覆盖前者;
而 PROJECT_ID / PROJECT_NAME / PROJECT_PATH / PROJECT_LOG_FILE 由 Jpom 注入,不要用同名变量去覆盖。
| JPOM_EXEC_PATH | YAML 里 execPath 的值 |
| 工作空间环境变量 | 【脚本管理】->【环境变量】里配置的变量 |
| 项目 DSL 环境变量 | 项目详情里【DSL环境变量】填的 key=value&key2=value2 |
| scriptEnv | YAML 里该流程单独配的变量(会覆盖工作空间变量与项目 DSL 环境变量) |
# 脚本在哪个目录执行
| 配置 | 实际工作目录 |
|---|---|
execPath: /root/xxx(绝对路径) | 该绝对目录 |
execPath: ./ 或 sub/dir(相对路径) | 项目目录/execPath |
不配 execPath | 脚本文件所在目录 |
不配 execPath 的坑
不配 execPath 时,脚本在脚本文件所在目录执行,而不是项目目录。
如果业务程序用相对路径写日志,就会写到意料之外的位置——这正是常见问题里「日志文件找不到」的根因。
# config.log:在项目控制台直接查看应用日志
DSL 项目启动的应用通常自己写日志文件(nohup java -jar app.jar > logs/app.log),这些内容不在 Jpom 的控制台日志里。
在 config.log 里声明后,项目【控制台】右上角会多出一个日志文件下拉框,可以像控制台日志一样实时跟踪。
config:
log:
- name: 应用日志 # 下拉框里显示的名称,不写则用文件名
path: logs/app.log # 相对项目目录,或绝对路径
charset: UTF-8 # 可选,默认跟随项目/全局日志编码
- name: 错误日志
path: ${PROJECT_PATH}/logs/error.log
2
3
4
5
6
7
| 写法 | 解析结果 |
|---|---|
logs/app.log、./logs/app.log | 项目目录/logs/app.log(不允许用 ../ 跳出项目目录) |
/data/app/logs/app.log | 直接使用该绝对路径 |
${PROJECT_PATH}/logs/app.log | 项目目录下的日志文件 |
${PROJECT_ID}、${PROJECT_NAME} | 项目 ID / 项目名称 |
使用说明
- 保存 DSL 配置后刷新项目控制台,日志文件下拉框即可选择;切换后从文件末尾开始跟踪,历史内容按控制台日志的初始行数显示。
- 文件暂时不存在也会出现在下拉框(名称后标注「日志文件不存在」),应用产生日志后重新选择即可。
- 目前只支持具体文件路径,不支持通配符;日志按天/按大小切割时,请把当前文件名写在
path里。 - 客户端只回传日志标识(配置内容的摘要),真实路径由插件端解析,相对路径被限制在项目目录内。
# 状态协议(最容易踩坑的地方)
Jpom 只读 status 脚本输出的最后一行,格式必须是:
running:<PID>[:<PORT>]
| 输出 | Jpom 判定 |
|---|---|
running:1234 | 运行中,PID = 1234 |
running:1234,5678 | 运行中,主 PID = 1234,同时记录多个 PID |
running:1234:8080 | 运行中,PID = 1234,端口 8080(列表里会显示端口) |
running | 未运行(没有 PID 就视为失败) |
stopped / 空 / 其它文本 | 未运行 |
前面可以有别的输出
Jpom 会把这一行按 - 切分取最后一段再解析,所以脚本前面 echo 的日志不影响结果。
但最后一行必须是 running:...,前后不能有多余字符。
# 启动 / 停止的等待与超时
点【启动】后,Jpom 会按「检测间隔 × 等待次数」轮询 status 判断是否成功:
- 等待次数与间隔来自插件端
conf/application.yml:jpom.project.status-wait-time(默认 10)与status-detection-interval(默认 500 毫秒) - 默认最多等约 5 秒,启动慢的应用(ES、Nacos)容易「超时但实际已起来」,请调大等待次数
启动前还有两个检查
- 项目已经是运行状态 → 直接返回「程序已经在运行」
- 项目目录里没有任何文件 → 返回「项目目录下没有任何文件」,先去【文件】里上传
# file 与 config 节点
| 字段 | 说明 |
|---|---|
file.backupCount | 项目文件备份保留个数,> 0 才备份 |
file.backupSuffix | 只备份这些后缀(支持正则),不配则备份全部 |
file.backupPath | 备份存放目录,默认在插件端数据目录下 |
file.diffBackup | 是否只备份有变化的文件(默认开启) |
file.versionCount | 构建发布时保留的完整版本快照个数,0 关闭 |
file.versionPath | 版本快照目录,默认 data/project_file_version |
config.autoBackToFile | 是否自动备份控制台日志 |
没有特殊需求时这些都可以不写,跟随插件端全局配置。
# 从 2.8 / 2.9 迁移过来要注意
| 旧写法 | 2.11 写法 |
|---|---|
| DSL 内容直接是一段 shell(内含 start / stop / status 函数) | YAML 里用 scriptId 指向那段 shell 文件 |
Jpom 自动把操作名作为 $1 传入 | 每个流程显式写 scriptArgs: start / status / stop |
${PROJECT_ID} 等变量直接可用 | 仍然可用,另外新增 PROJECT_LOG_FILE、JPOM_EXEC_PATH |
没配 run.status 也能保存 | 必须配 run.status,否则保存报错 |