Pomerium v0.33.4 常用 CLI 命令详解

Pomerium 的命令行界面出乎意料地克制：主程序 pomerium 是一个以"读取配置并运行服务"为核心的多子命令工具，另有健康检查、云服务导入与 shell 补全三个辅助子命令。本文全部命令与回显均来自 v0.33.4 实测（Ubuntu 22.04.5 + systemd 环境，与安装篇同一实验机）。

主命令结构总览

$ pomerium --help
Usage:
  pomerium [flags]
  pomerium [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  health
  help        Help about any command
  zero        Interact with the Pomerium Zero cloud service

Flags:
      --config string   Specify configuration file location
  -h, --help            help for pomerium
  -v, --version         version for pomerium

Use "pomerium [command] --help" for more information about a command.

两点解读：

pomerium [flags]（不带子命令）即启动服务——等价于 systemd 单元里的 ExecStart=/usr/sbin/pomerium --config /etc/pomerium/config.yaml。没有独立的 serve/start 子命令。
子命令一共三个：health（健康检查）、zero（云控制面导入）、completion（shell 补全）。

版本取证与服务启动

$ pomerium --version
pomerium version pomerium: 0.33.4+5cd94927f, envoy: 20261001211751-8b998d0f6ff3

回显同时给出控制面版本与内嵌 Envoy 构建号，是升级后核对版本的首选命令（deb 包管理器视角可用 dpkg -l pomerium 交叉确认）。

前台启动（排障时最常用）：

$ pomerium --config /etc/pomerium/config.yaml

配置文件路径错误、参数校验失败都会在这一步暴露。实测注入非法密钥：

$ pomerium --config /tmp/bad.yaml
Error: config: options from config file "/tmp/bad.yaml": validation error config: invalid shared secret: illegal base64 data at input byte 0
{"level":"fatal","error":"config: ... invalid shared secret ...","message":"cmd/pomerium"}

利用这一行为可以做配置变更前的预检：在 systemctl restart 之前，先以前台方式跑一次（几秒后 Ctrl-C），配置有问题就不会波及运行中的服务。

pomerium health：健康检查组

pomerium health 是一个独立可执行的探活工具，默认连 127.0.0.1:28080 的健康端点：

Usage:
  pomerium health [flags]
  pomerium health [command]

Available Commands:
  watch       watch the grpc health stream for health updates

Flags:
  -e, --exclude stringArray   list of health checks to exclude from consideration
  -a, --health-addr string    port of the pomerium health check service (default "127.0.0.1:28080")
  -v, --verbose               prints extra health information

三种用法实测：

① 普通模式（脚本友好，退出码 0/非 0）：

$ pomerium health && echo ALIVE
{"level":"info",...,"message":"health check succeeded"}
ALIVE

② verbose 模式：输出全部组件的健康状态 JSON，是"一眼看全局"的运维利器：

$ pomerium health -v
{
  "statuses": {
    "authenticate.service": { "status": "RUNNING" },
    "authorize.service":    { "status": "RUNNING" },
    "proxy.service":        { "status": "RUNNING" },
    "databroker.cluster":   { "status": "RUNNING" },
    "envoy.server":         { "status": "RUNNING" },
    "xds.route-configuration": { "status": "RUNNING" }
  },
  "checks": [
    "authenticate.service",
    "authorize.service",
    "config.databroker.build",
    "databroker.cluster",
    "databroker.sync.initial",
    "envoy.server",
    "proxy.service",
    "storage.backend",
    "xds.cluster",
    "xds.listener",
    "xds.route-configuration"
  ]
}

11 项 check 覆盖了四个服务角色、存储后端与 xDS 数据面配置流，任何一个子组件异常都会在这里反映为非 RUNNING。

③ watch 模式：订阅 gRPC 健康流，适合指向远程组件（如拆分部署时的 databroker gRPC 端口）。实测注意两点：不带参数运行时它不知道目标地址，报 invalid target address "": missing address 退出；把地址指到 HTTP 健康端点（28080）时会持续报 Unimplemented ... 404——watch 需要的是 gRPC 端口（启动日志中的 grpc-port 字段），而非 HTTP 健康端点。

pomerium zero：托管控制面导入

pomerium zero import 把现有配置导入 Pomerium Zero（官方托管控制面），用于自管集群向云控制面的迁移：

$ pomerium zero --help
Interact with the Pomerium Zero cloud service

Available Commands:
  import      Import an existing configuration to a Zero cluster

Flags:
      --config string   Specify configuration file location
      --token string    Pomerium Zero Token (default: $POMERIUM_ZERO_TOKEN)

实测中未创建 Zero 集群（需要官方控制台的集群 token），故仅验证了命令与参数语义：--token 支持环境变量 POMERIUM_ZERO_TOKEN 注入，避免 token 落盘。

pomerium completion：shell 补全

$ pomerium completion bash | wc -l
426
$ pomerium completion bash | head -1
# bash completion V2 for pomerium                             -*- shell-script -*-

支持 bash、fish、powershell 三种 shell（zsh 亦在 help 列表中），按官方惯例写入 /etc/bash_completion.d/pomerium 后重进 shell 生效。

pomerium-cli：客户端程序（简述）

除服务端主程序外，Pomerium 官方还发布一个独立的客户端工具 pomerium-cli（用于在用户侧建立 TCP 透传、kubectl 集成与信任根证书安装等），它不包含在 deb 主包中——实测 dpkg -L pomerium 与 which pomerium-cli 均确认不存在。pomerium-cli 需从官方 GitHub Releases（pomerium/cli 项目）按平台下载，或通过包管理器安装其独立包。因实验环境网络受限未能实测，本文不展开其子命令细节，使用前请以官方文档为准。

运维组合技（systemd + CLI）

装完服务后的日常操作，推荐固定的几条命令（均已实测）：

# 状态与日志
systemctl is-active pomerium
journalctl -u pomerium -f --output=cat        # 跟踪结构化 JSON 日志

# 健康三连
curl -s http://127.0.0.1:28080/healthz        # 简单探活
pomerium health -v                            # 组件级健康全景
curl -s http://127.0.0.1:9090/metrics | head  # Prometheus 指标（需配置 metrics_address）

# 版本与配置预检
pomerium --version
pomerium --config /etc/pomerium/config.yaml   # 前台预检，确认无 fatal 再 restart

小结

Pomerium 的 CLI 面围绕"跑服务、看健康"两件事构建：主命令加 --config 即服务本体，health -v 一次给出四服务 + 存储 + xDS 的全景状态，zero import 承担向托管控制面迁移的桥接，completion 补齐 shell 体验。记住三个高频细节：配置改动先用前台启动预检、health watch 要指向 gRPC 而非 HTTP 端口、pomerium-cli 是需要单独安装的客户端程序。