Skip to content

tio-boot-web-hello:Java 单体应用 ​

案例概览 ​

这是一份真实执行过的部署记录:用 deploy-cli 把 tio-boot 示例应用 tio-boot-web-hello 部署到内网 Linux 服务器,由 systemd 托管,最终以开发机 curl 得到 HTTP 200 验收。

项值
源码https://gitee.com/ppnt/tio-boot-web-hello.git @ main
目标服务器192.168.31.97(Ubuntu,deploy-server 端口 10055)
工具链JDK /usr/java/jdk1.8.0_411、Maven 3.8.8、git、curl
发布目录/srv/apps/tio-boot-web-hello(app.jar + 外部配置)
服务端口10062(服务器 80 已被 nginx 占用,不能沿用 jar 内默认端口)
部署结果运行 #106 status=success,耗时 11.1s;curl http://192.168.31.97:10062/ 返回 200

六步脚本法 ​

平台里「项目 = 一个工作目录 + 一组 shell 命令」(见核心概念)。本案例把整个部署生命周期拆成六条命令,每条职责单一、可独立重跑:

#命令作用
1环境勘察(只读)主机、工具链、源码提交、本地 Maven 仓库、目标端口是否空闲
2Maven 构建生产包mvn -U clean package -Pproduction,产出可执行 fat jar
3发布产物与外部配置拷 jar 到发布目录,写外部端口配置
4注册 systemd 服务并重启写 unit、重启、确认端口真的监听
5健康检查轮询 GET / 直到 200,否则打印日志并以非零退出
6运行状态与日志(运维)日常巡检用,选择性运行,不触发重新构建

这个结构可以直接套用到任何「构建 jar → 发布 → systemd」的 Java 单体应用上。

项目定义 ​

项目用一份 project.json 描述,六段脚本分别存成 sh/01-recon.sh … sh/06-ops.sh,通过 scriptFile 引用:

json
{
  "key": "tio-boot-web-hello",
  "name": "tio-boot web hello",
  "workdir": "/srv/deploy/workspaces/tio-boot-web-hello",
  "useGit": true,
  "gitUrl": "https://gitee.com/ppnt/tio-boot-web-hello.git",
  "gitBranch": "main",
  "env": { "APP_PORT": "10062" },
  "commands": [
    { "name": "1. 环境勘察(只读)",        "scriptFile": "sh/01-recon.sh" },
    { "name": "2. Maven 构建生产包",       "scriptFile": "sh/02-build.sh" },
    { "name": "3. 发布产物与外部配置",      "scriptFile": "sh/03-publish.sh" },
    { "name": "4. 注册 systemd 服务并重启", "scriptFile": "sh/04-systemd.sh" },
    { "name": "5. 健康检查",              "scriptFile": "sh/05-healthcheck.sh" },
    { "name": "6. 运行状态与日志(运维)",  "scriptFile": "sh/06-ops.sh" }
  ]
}
bash
deploy project create --file project.json

把脚本存成文件再用 --file 创建,还避开了一个 Windows 陷阱:在 PowerShell 里把多行脚本作为参数传给原生 exe,引号与换行会被切碎,脚本里的 mvn -v 会被 CLI 当成自己的 -v 参数而报错。用文件方式或在 Git Bash / WSL 里操作即可。Git 准备的细节见 Git 准备。

关键脚本片段 ​

构建:显式 JDK 路径 + -U ​

bash
set -e
export JAVA_HOME=/usr/java/jdk1.8.0_411
export PATH="$JAVA_HOME/bin:$PATH"
cd "${WORKDIR:-/srv/deploy/workspaces/tio-boot-web-hello}"

# -U 强制向远程仓库核对更新:阿里云镜像对新发布的构件是「先有 pom、后有 jar」
# 的渐进缓存,不加 -U 可能命中半截缓存导致依赖解析失败。
mvn -U -B clean package -DskipTests -Pproduction -Dgpg.skip=true -Dmaven.javadoc.skip=true
ls -lh target/tio-boot-web-hello-*.jar

发布:外部配置覆盖 jar 内默认值 ​

jar 内写死了 server.port=80,而服务器 80 被 nginx 占用。tio-boot 按进程工作目录读取外部配置,且不同版本读取的文件名不一致,所以 app.properties 与 my.txt 各写一份:

bash
APP_DIR=/srv/apps/tio-boot-web-hello
PORT="${APP_PORT:-10062}"
JAR=$(ls -t "$WORKDIR"/target/tio-boot-web-hello-*.jar | grep -vE -- '-(sources|javadoc)\.jar$' | head -1)
mkdir -p "$APP_DIR/logs"
cp -f "$JAR" "$APP_DIR/app.jar"
printf 'server.port=%s\n' "$PORT" > "$APP_DIR/app.properties"
printf 'server.port=%s\n' "$PORT" > "$APP_DIR/my.txt"

systemd:先查端口归属,再重启 ​

unit 的 WorkingDirectory 必须等于发布目录,外部配置才生效。启动前判断「端口被占且本服务未运行」则直接失败,避免健康检查打到别的进程:

bash
if ss -ltn | grep -qE ":${PORT}\b" && ! systemctl is-active --quiet tio-boot-web-hello; then
  echo "端口 $PORT 已被其它进程占用"; exit 1
fi

unit 关键行(完整脚本另含 daemon-reload、enable、清空旧日志、重启后确认监听):

ini
[Service]
WorkingDirectory=/srv/apps/tio-boot-web-hello
ExecStart=/usr/java/jdk1.8.0_411/bin/java -jar /srv/apps/tio-boot-web-hello/app.jar
Restart=always
RestartSec=5
StandardOutput=append:/srv/apps/tio-boot-web-hello/logs/startup.log
StandardError=append:/srv/apps/tio-boot-web-hello/logs/startup-error.log

健康检查:以 HTTP 200 为判据 ​

平台的「成功」只代表脚本退出码为 0,systemctl active 也不代表应用真的能应答。健康检查轮询 30 次、每次间隔 2 秒,失败时打印启动日志尾部并 exit 1,让本次部署明确判为失败:

bash
CODE=000
for _ in $(seq 1 30); do
  CODE=$(curl -s -o /tmp/tbwh-body -w '%{http_code}' "http://127.0.0.1:$PORT/" || true)
  [ "$CODE" = "200" ] && break
  sleep 2
done
if [ "$CODE" != "200" ]; then
  tail -60 "$APP_DIR/logs/startup.log" 2>/dev/null || true
  tail -40 "$APP_DIR/logs/startup-error.log" 2>/dev/null || true
  exit 1
fi

执行部署 ​

bash
# 登录并命名服务器(不存在时自动创建);推荐用平台「个人设置 → API Token」的 dk_ 长效令牌
deploy login -a http://192.168.31.97:10055 -u admin -p '<管理员密码>' --name 97

# 一次调用拿终态:可判定成败、带退出码
deploy --server 97 run tio-boot-web-hello --wait --json
# {"buildNumber":2,"durationMs":11123,"exitCode":0,"runId":106,"status":"success"}

# 长部署可先触发再跟日志
deploy --server 97 run tio-boot-web-hello --json      # 拿 runId
deploy --server 97 logs <runId> -f                    # 实时跟随

不带 --wait / -f 时拿到的只是 queued,不能据此判断成功。详见运行生命周期。

选择性运行运维命令 ​

日常只想看状态和日志(第 6 条命令),不必重新构建。用 --command-id 选择性运行,但项目命令 ID 在每次 project update 后都会重新生成,所以运行前必须先 project get 拿当前 ID:

bash
# 先读当前的命令 ID,找到「6. 运行状态与日志(运维)」那条
deploy --server 97 project get tio-boot-web-hello --json

# 再用刚查到的 ID 单独执行(示例中为 82,你的环境会不同)
deploy --server 97 run tio-boot-web-hello --command-id 82 --wait

对比之下,任务的步骤 ID 是位置序号、update 后不变,这正是「日常巡检类作业更适合建成任务」的原因之一,参见从项目迁移到任务与案例 03。

需要适配的路径与端口 ​

套用本案例到自己的应用时,逐项检查:

项本案例取值适配要点
JDK 路径/usr/java/jdk1.8.0_411项目 maven.compiler.target=1.8;服务器 PATH 里的默认 java 版本不一定匹配,构建脚本与 unit 的 ExecStart 都要显式写绝对路径
服务端口APP_PORT=10062先跑第 1 条勘察命令确认端口空闲;jar 内默认端口被占时必须用外部配置覆盖
外部配置文件名app.properties + my.txt取决于框架版本;两者都写最稳妥
工作目录/srv/deploy/workspaces/<key>Git 工作区,与发布目录分离
发布目录/srv/apps/<key>必须与 systemd WorkingDirectory 一致

验证与排错 ​

最硬的证据是从开发机直接访问服务端口:

bash
curl -sS -i http://192.168.31.97:10062/
# HTTP/1.1 200 OK
# {"code":1,"msg":null,"ok":true,"error":null,"data":{}}

本案例踩过的坑归纳:镜像渐进缓存导致依赖 404(加 -U)、外部配置不生效偷偷监听 80(工作目录对齐)、健康检查打到别的进程(启动前查端口归属)、PowerShell 传多行脚本被切碎(用 --file)。更多通用排错思路见故障排查;如果你的应用还依赖未发布的私有库,继续读案例 02。