# 快速上手

本教程将在 5 分钟内帮助您启动一个最小的 SPIRE 环境。

## 场景

我们将配置：

1. 一个 SPIRE Server
2. 一个 SPIRE Agent
3. 一个简单的工作负载注册

## 步骤 1：准备配置

### Server 配置

创建 `server.conf`：

```hcl
server {
    bind_address = "0.0.0.0"
    bind_port = "8081"
    socket_path = "/tmp/spire-server/private/api.sock"
    trust_domain = "example.org"
    data_dir = "./data/server"
    log_level = "DEBUG"
}

plugins {
    DataStore "sql" {
        plugin_data {
            database_type = "sqlite3"
            connection_string = "./data/server/datastore.sqlite3"
        }
    }

    NodeAttestor "join_token" {
        plugin_data {}
    }

    KeyManager "disk" {
        plugin_data {
            keys_path = "./data/server/keys.json"
        }
    }
}
```

### Agent 配置

创建 `agent.conf`：

```hcl
agent {
    data_dir = "./data/agent"
    log_level = "DEBUG"
    server_address = "localhost"
    server_port = "8081"
    socket_path = "/tmp/spire-agent/public/api.sock"
    trust_domain = "example.org"
    trust_bundle_path = "./conf/agent/bootstrap.crt"
}

plugins {
    NodeAttestor "join_token" {
        plugin_data {}
    }

    KeyManager "disk" {
        plugin_data {
            directory = "./data/agent"
        }
    }

    WorkloadAttestor "unix" {
        plugin_data {}
    }
}
```

## 步骤 2：启动 Server

```bash
# 创建数据目录
mkdir -p data/server data/agent

# 启动 Server
./bin/spire-server run -config server.conf &

# 等待启动
sleep 2

# 检查状态
./bin/spire-server healthcheck
```

## 步骤 3：生成 Join Token

```bash
# 生成引导证书
./bin/spire-server bundle show > conf/agent/bootstrap.crt

# 生成 join token
./bin/spire-server token generate -spiffeID spiffe://example.org/myagent
```

记下输出的 token，例如：`abc123def456...`

## 步骤 4：启动 Agent

```bash
# 使用 join token 启动 Agent
./bin/spire-agent run -config agent.conf -joinToken <your-token> &

# 等待启动
sleep 2

# 检查状态
./bin/spire-agent healthcheck
```

## 步骤 5：创建注册条目

```bash
# 为当前用户的工作负载创建条目
./bin/spire-server entry create \
    -spiffeID spiffe://example.org/myworkload \
    -parentID spiffe://example.org/myagent \
    -selector unix:uid:$(id -u)
```

## 步骤 6：验证

### 获取 SVID

```bash
# 使用 spiffe-helper 或直接调用 API
./bin/spire-agent api fetch x509 -socketPath /tmp/spire-agent/public/api.sock
```

### 查看输出

```
Received 1 svid after X.XXXXXXXXs

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
```

## 完整脚本

```bash
#!/bin/bash
set -e

# 清理旧数据
rm -rf data conf/agent/bootstrap.crt

# 创建目录
mkdir -p data/server data/agent conf/agent

# 启动 Server
./bin/spire-server run -config server.conf &
SERVER_PID=$!
sleep 3

# 生成引导证书
./bin/spire-server bundle show > conf/agent/bootstrap.crt

# 生成并使用 join token
TOKEN=$(./bin/spire-server token generate -spiffeID spiffe://example.org/myagent -output json | jq -r '.value')

# 启动 Agent
./bin/spire-agent run -config agent.conf -joinToken "$TOKEN" &
AGENT_PID=$!
sleep 3

# 创建注册条目
./bin/spire-server entry create \
    -spiffeID spiffe://example.org/myworkload \
    -parentID spiffe://example.org/myagent \
    -selector unix:uid:$(id -u)

# 获取 SVID
sleep 2
./bin/spire-agent api fetch x509

echo "SPIRE 环境已就绪！"
echo "Server PID: $SERVER_PID"
echo "Agent PID: $AGENT_PID"
```

## 常见问题

### Agent 无法连接 Server

确保：
- Server 已启动并监听 8081 端口
- `bootstrap.crt` 是最新的
- Join token 未过期（默认 10 分钟）

### 工作负载无法获取 SVID

确保：
- Agent socket 存在：`/tmp/spire-agent/public/api.sock`
- 注册条目的选择器匹配工作负载
- 工作负载有权限访问 socket

## 下一步

阅读 {doc}`/2.getting-started/first-workload` 了解如何在应用程序中集成 SPIRE。