Agent 命令行

概述

spire-agent 提供命令行接口用于运行和管理 SPIRE Agent。

服务命令

run

启动 SPIRE Agent：

# 基本启动
spire-agent run -config /path/to/agent.conf

# 使用 join token
spire-agent run -config /path/to/agent.conf -joinToken <token>

# 覆盖日志级别
spire-agent run -config /path/to/agent.conf -logLevel DEBUG

选项	描述
`-config`	配置文件路径
`-joinToken`	一次性 join token
`-logLevel`	覆盖日志级别
`-expandEnv`	展开环境变量

validate

验证配置文件：

spire-agent validate -config /path/to/agent.conf

healthcheck

检查 Agent 健康状态：

spire-agent healthcheck -socketPath /tmp/spire-agent/public/api.sock

选项	描述
`-socketPath`	Agent socket 路径
`-shallow`	浅层检查（不验证 Server 连接）

API 命令

api fetch

从 Workload API 获取身份。

获取 X.509-SVID

# 获取所有 SVID
spire-agent api fetch x509

# 指定 socket 路径
spire-agent api fetch x509 -socketPath /tmp/spire-agent/public/api.sock

# 写入文件
spire-agent api fetch x509 -write /path/to/output

# 静默模式
spire-agent api fetch x509 -silent

输出文件：

svid.0.pem: 第一个 SVID 证书
svid.0.key: 第一个 SVID 私钥
bundle.0.pem: 信任包

获取 JWT-SVID

# 获取 JWT
spire-agent api fetch jwt -audience https://api.example.org

# 多个受众
spire-agent api fetch jwt -audience https://api.example.org -audience https://web.example.org

# 指定 SPIFFE ID
spire-agent api fetch jwt -audience https://api.example.org -spiffeID spiffe://example.org/myworkload

选项	描述
`-audience`	JWT 受众（可多次使用）
`-spiffeID`	请求特定 SPIFFE ID
`-socketPath`	Agent socket 路径

api watch

持续监视 SVID 更新：

# 监视 X.509 SVID
spire-agent api watch

# 输出到文件
spire-agent api watch -output /path/to/output

api validate jwt

验证 JWT-SVID：

spire-agent api validate jwt -audience https://api.example.org -svid <jwt-token>

选项	描述
`-audience`	期望的受众
`-svid`	要验证的 JWT token

实用示例

调试工作负载证明

# 以当前用户身份获取 SVID
spire-agent api fetch x509 -socketPath /tmp/spire-agent/public/api.sock

# 查看返回的 SVID
openssl x509 -in svid.0.pem -text -noout

检查证书内容

# 获取 SVID 并检查
spire-agent api fetch x509 -write /tmp/svid -socketPath /tmp/spire-agent/public/api.sock

# 查看证书详情
openssl x509 -in /tmp/svid/svid.0.pem -text -noout

# 查看 SPIFFE ID
openssl x509 -in /tmp/svid/svid.0.pem -text -noout | grep URI

测试 mTLS

# 获取证书
spire-agent api fetch x509 -write /tmp/svid

# 使用 curl 测试
curl --cert /tmp/svid/svid.0.pem \
     --key /tmp/svid/svid.0.key \
     --cacert /tmp/svid/bundle.0.pem \
     https://api.example.org/

监控 SVID 轮换

#!/bin/bash
# 监控 SVID 轮换脚本

while true; do
    spire-agent api fetch x509 -write /tmp/svid -silent
    
    EXPIRY=$(openssl x509 -in /tmp/svid/svid.0.pem -enddate -noout | cut -d= -f2)
    SPIFFEID=$(openssl x509 -in /tmp/svid/svid.0.pem -text -noout | grep -o 'URI:spiffe://[^,]*')
    
    echo "$(date): $SPIFFEID expires $EXPIRY"
    sleep 30
done

JWT 验证测试

# 获取 JWT
JWT=$(spire-agent api fetch jwt -audience https://api.example.org | grep -o 'Token: .*' | cut -d' ' -f2)

# 解码 JWT（需要 jq）
echo "$JWT" | cut -d. -f2 | base64 -d | jq .

# 验证 JWT
spire-agent api validate jwt -audience https://api.example.org -svid "$JWT"

输出格式

X.509 获取输出

Received 1 svid after 0.123456789s

SPIFFE ID:              spiffe://example.org/myworkload
SVID Valid After:       2026-02-03 00:00:00 +0000 UTC
SVID Valid Until:       2026-02-03 01:00:00 +0000 UTC
CA #1 Valid After:      2026-02-03 00:00:00 +0000 UTC
CA #1 Valid Until:      2026-02-04 00:00:00 +0000 UTC

JWT 获取输出

Token: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlM2UVQ...

SPIFFE ID:      spiffe://example.org/myworkload
Issued At:      2026-02-03 00:00:00 +0000 UTC
Expires At:     2026-02-03 00:05:00 +0000 UTC
Audience:       [https://api.example.org]

故障排除

常见错误

无法连接 Agent：

# 检查 socket 文件
ls -la /tmp/spire-agent/public/api.sock

# 检查 Agent 进程
ps aux | grep spire-agent

# 检查 Agent 日志
journalctl -u spire-agent -f

无法获取 SVID：

# 检查注册条目
spire-server entry show

# 验证选择器
# 以目标用户身份运行
sudo -u appuser spire-agent api fetch x509

JWT 验证失败：

# 检查受众是否匹配
spire-agent api validate jwt -audience <correct-audience> -svid <token>

# 检查 JWT 是否过期
echo "<token>" | cut -d. -f2 | base64 -d | jq '.exp'

下一步

了解 Workload API 以编程方式使用 Workload API。