# Agent 命令行

## 概述

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

## 服务命令

### run

启动 SPIRE Agent：

```bash
# 基本启动
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

验证配置文件：

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

### healthcheck

检查 Agent 健康状态：

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

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

## API 命令

### api fetch

从 Workload API 获取身份。

#### 获取 X.509-SVID

```bash
# 获取所有 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

```bash
# 获取 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 更新：

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

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

### api validate jwt

验证 JWT-SVID：

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

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

## 实用示例

### 调试工作负载证明

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

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

### 检查证书内容

```bash
# 获取 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

```bash
# 获取证书
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 轮换

```bash
#!/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 验证测试

```bash
# 获取 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：**

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

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

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

**无法获取 SVID：**

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

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

**JWT 验证失败：**

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

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

## 下一步

了解 {doc}`/5.agent/workload-api` 以编程方式使用 Workload API。