编程 用 verna 在 Ubuntu 上做编译型应用的蓝绿部署:systemd 双 slot 加 Caddy admin API 切流

2026-11-20 21:31:14

用 verna 在 Ubuntu 上做编译型应用的蓝绿部署:systemd 双 slot 加 Caddy admin API 切流

项目地址:https://github.com/jackc/verna

verna 面向 Go、Rust、C 等预编译二进制,把它们部署到 Ubuntu 服务器:进程交给 systemd,入口交给 Caddy,产物用 SSH 传输。不需要 Docker,也不需要 buildpack,服务器上不编译。

工作模型

每个应用两个 slot(blue / green),各自是一个 systemd service 实例,监听固定的本地端口。任一时刻只有一个 slot 在线,Caddy 反向代理到它。部署总是打到非活跃 slot,健康检查通过后 Caddy 才切流,旧 slot 保留着,可以立即回滚。

不引入 Docker,意味着服务器上只需要 systemd、journald 和 root SSH,不用维护镜像仓库和容器运行时;代价是运行时依赖得由 systemd unit 和系统包管理来承担。

部署序列

  1. 确定非活跃 slot

  2. 上传 tarball 产物

  3. 解包到不可变的 release 目录

  4. 校验可执行文件存在且有执行权限

  5. 把该 slot 的 symlink 指向新 release

  6. 如果当前 verna 版本生成的 systemd unit 与已装的不同,更新 unit

  7. 如果应用的 setup 脚本内容相对上次成功运行有变化,执行它

  8. 重启该 slot 的 systemd unit

  9. 对新实例做健康检查

  10. 把 Caddy 的上游切到新 slot

  11. 原子写入新的活跃 slot 状态

  12. 停掉旧 slot

  13. 按保留上限清理旧 release

健康检查失败时旧 slot 继续在线,线上什么都不变。如果切流之后写状态失败,verna 会把路由恢复回旧 slot,并停掉新目标。

安装

go install github.com/jackc/verna/cmd/verna@latest

配置

没有本地配置文件,服务器连接信息通过全局 flag 逐次传入:

verna --ssh-host myserver.example.com

--ssh-host 必填,--ssh-user 默认 root,--ssh-port 默认 22,另有 --ssh-key-file、--actor,都支持 VERNA_ 前缀的环境变量。

应用级配置(域名、环境变量、健康检查、端口)全部存在服务器上的 /var/lib/verna/verna.json。端口对在 app init 时自动分配,环境变量写入每个 slot 的 .verna/env/runtime.env。

服务器状态

verna.json 记录应用配置、部署状态、Caddy 生命周期归属(external / package / custom)以及最近一次成功安装的 receipt。每次写状态都带单调递增的 revision,在远端 flock 下比对,落后的并发命令会被拒绝并报出期望值与当前值。CI 里应固定 actor:

VERNA_ACTOR=production-release-pipeline verna --ssh-host myserver app --app myapp deploy myapp.tar.gz

应用契约

  • 读取 PORT 环境变量,并监听该端口
  • 提供健康检查端点(默认 GET /health),就绪时返回 HTTP 200
  • 处理 SIGTERM,优雅退出

使用

初始化服务器

verna --ssh-host myserver server init

在服务器上创建 /var/lib/verna/ 和空的 verna.json。

安装 Caddy

Caddy 是必需的。新服务器上:

verna --ssh-host myserver server caddy install --source package

package 模式会安装官方 Cloudsmith stable 源及其签名密钥,安装 Caddy 和 unattended-upgrades,禁用 caddy.service,启用包自带的 caddy-api.service;verna 不写也不替换这两个 unit。自动包更新属于 package 模式的契约:verna 写 /etc/apt/apt.conf.d/52verna-caddy,启用 apt-daily.timer 和 apt-daily-upgrade.timer,并在记录成功安装 receipt 之前跑 unattended-upgrade --dry-run --debug。

自编译(xcaddy)走 binary 模式:

verna --ssh-host myserver server caddy install --source binary --binary ./caddy
verna --ssh-host myserver server caddy upgrade --binary ./caddy-new
verna --ssh-host myserver server caddy rollback

可选的 build manifest(caddy_version + modules)会让 verna 在激活自带二进制前校验声明的核心版本和完整的非标准模块集合;未知字段、重复模块包、未限定的模块路径、版本不符都会被拒绝。

也可以从 Caddy 托管下载服务取产物:--source download-api。客户端在上传后校验 ELF 架构,并把解析出的核心、模块、SHA-256 写进 receipt。

激活之前,verna 通过 admin API 读取完整的线上 /config/,只要有 verna_* 路由与 verna.json 不一致就拒绝继续;快照留在 /usr/local/lib/verna/caddy/snapshots/,随后执行 caddy validate。生命周期操作使用由内核释放的远端 flock,并发的 install/adopt/upgrade/rollback 会直接失败而不是叠加执行。

verna --ssh-host myserver server caddy status
verna --ssh-host myserver server caddy sync --dry-run
verna --ssh-host myserver server caddy sync --prune
verna --ssh-host myserver server doctor

sync 只重建 verna.json 声明的应用路由,保留其他所有 Caddy 配置。指向另一个蓝绿 slot 的路由会被判定为歧义,永不自动覆盖。并发的 Caddy 变更由 ETag/If-Match 校验加有界重试保护。verna_ 开头的 route ID 是保留的,非 verna_ 路由不会被 prune。

审计

每个变更类命令通过 root 所有的 SSH 通道,向目标机的系统 journal 写一对 started/finished 记录,两条共享同一个 UUID operation ID。字段:SYSLOG_IDENTIFIER=verna、MESSAGE_ID、VERNA_OPERATION_ID、VERNA_ACTION、VERNA_PHASE、VERNA_OUTCOME、VERNA_ACTOR、VERNA_CLIENT_USERNAME、VERNA_VERSION、VERNA_APP、VERNA_STATE_REVISION_BEFORE/AFTER。

verna --ssh-host myserver server audit --app myapp --action app.deploy --phase finished --outcome failure --since "2 hours ago"
verna --ssh-host myserver server audit --json --follow

查询依赖 journald 的 _UID=0 可信元数据。审计记录不包含原始 CLI 参数、SSH 命令、环境变量值和原始错误字符串。

初始化应用

verna --ssh-host myserver app --app myapp init --domain myapp.example.com --exec-path bin/myapp

创建目录结构、系统用户、systemd 模板 unit 和 Caddy 路由,并把应用以自动分配的端口注册进 verna.json。

选项:--exec-path(必填,相对路径,不允许 ..)、--caddy-handle-template-path(默认 deploy/caddy-handle-template.json)、--domain(必填,可重复)、--health-check-path(默认 /health)、--exec-arg、--memory-max(MemoryMax=)、--cpu-quota(CPUQuota=)。

Caddy handle 模板

一个 Go text/template,产出 Caddy handler 的 JSON 数组,放在项目里随部署产物上传。变量:{{.Dial}}(如 127.0.0.1:18001)和 {{.SlotDir}}(如 /var/lib/verna/apps/myapp/slots/blue)。预设:proxy(默认)、static-proxy(先静态文件再反代,支持预压缩的 gzip/zstd/brotli)、spa-proxy(/assets/* 不可变缓存,/api/* 反代,回退 index.html)。每次部署都从产物里读模板,所以不同版本可以有不同路由;回滚会恢复上一版部署的路由。

列表与应用配置

verna --ssh-host myserver app list

只读 verna.json,不逐应用探测;--quiet 只打印名字。

verna app config list / get exec-path / set --domain newdomain.example.com --health-check-timeout 30

重新生成的 systemd unit 在安装前用 systemd-analyze verify 校验。改 --exec-path、--exec-arg、--memory-max、--cpu-quota 或 drop-in 会重启活跃 slot 并做健康检查——与部署不同,这次重启没有蓝绿保护,健康检查失败会明确报出来。

部署

mkdir -p dist/bin
GOOS=linux GOARCH=amd64 go build -o dist/bin/myapp .
tar czf myapp.tar.gz -C dist .
verna --ssh-host myserver app --app myapp deploy myapp.tar.gz

每次成功部署后会清理超出保留上限的旧 release(默认 5)。

状态与回滚

verna --ssh-host myserver app --app myapp status
verna --ssh-host myserver app --app myapp rollback

回滚会重启上一个 slot,对它做健康检查,然后把 Caddy 切回去。

服务器前置条件

Ubuntu,带 systemd 和 journald;Caddy 在运行且开启 admin API(默认 localhost:2019);root SSH 访问;服务器上有 curl;journalctl 和支持 --journald 的 util-linux logger。

verna 是开源项目,但不接受外部贡献,按作者个人使用需求设计。

复制全文 生成海报 systemd 蓝绿部署 Caddy Go 运维

推荐文章

程序员茄子在线接单