Rekor 透明日志完整教程 / 02 - 安装与配置
第 2 章：安装与配置
本章将介绍 Rekor 相关工具的安装方法，包括 rekor-cli 命令行工具、rekor-server 服务端、Docker 容器部署，以及 cosign 签名工具的集成配置。
2.1 组件概览
在开始安装之前，先了解需要安装的各个组件及其用途：
| 组件 | 类型 | 用途 | 是否必须 |
|---|---|---|---|
| rekor-cli | 命令行工具 | 与 Rekor API 交互、查询日志 | ✅ 推荐 |
| rekor-server | 服务端 | 运行私有 Rekor 实例 | 私有部署时需要 |
| cosign | 命令行工具 | 签名和验证容器镜像/文件 | ✅ 推荐 |
| trillian | 服务端 | Merkle Tree 后端存储 | 私有部署时需要 |
| fulcio | 服务端 | 证书颁发机构 | 私有部署时需要 |
2.2 安装 rekor-cli
rekor-cli 是与 Rekor 透明日志交互的主要命令行工具。
2.2.1 macOS 安装（Homebrew）
# 通过 Sigstore 官方 tap 安装
brew install sigstore/tap/rekor-cli
# 验证安装
rekor-cli version
# 预期输出示例：
# GitVersion: v1.3.6
# GitCommit: <commit_hash>
# GitTreeState: clean
# BuildDate: <build_date>
# GoVersion: go1.22.0
# Compiler: gc
# Platform: darwin/arm64
2.2.2 Linux 安装（二进制下载）
# 设置版本变量（请检查最新版本）
REKOR_VERSION="v1.3.6"
OS="linux"
ARCH="amd64"
# 下载 rekor-cli 二进制文件
curl -LO "https://github.com/sigstore/rekor/releases/download/${REKOR_VERSION}/rekor-cli-${OS}-${ARCH}"
# 移动到 PATH 目录并添加执行权限
sudo mv "rekor-cli-${OS}-${ARCH}" /usr/local/bin/rekor-cli
sudo chmod +x /usr/local/bin/rekor-cli
# 验证安装
rekor-cli version
2.2.3 Linux 安装（ARM64）
REKOR_VERSION="v1.3.6"
curl -LO "https://github.com/sigstore/rekor/releases/download/${REKOR_VERSION}/rekor-cli-linux-arm64"
sudo mv rekor-cli-linux-arm64 /usr/local/bin/rekor-cli
sudo chmod +x /usr/local/bin/rekor-cli
rekor-cli version
2.2.4 Windows 安装
# 使用 winget（推荐）
winget install Sigstore.Rekor
# 或者手动下载
# 1. 访问 https://github.com/sigstore/releases/releases
# 2. 下载 rekor-cli-windows-amd64.exe
# 3. 将文件重命名为 rekor-cli.exe 并添加到 PATH
2.2.5 从源码编译
# 前置条件：Go 1.22+
git clone https://github.com/sigstore/rekor.git
cd rekor
# 编译 rekor-cli
go build -o rekor-cli ./cmd/rekor-cli
# 移动到 PATH
sudo mv rekor-cli /usr/local/bin/
# 验证
rekor-cli version
2.2.6 验证安装完整性
下载后建议验证二进制文件的 checksum：
# 下载 checksum 文件
curl -LO "https://github.com/sigstore/rekor/releases/download/${REKOR_VERSION}/rekor_checksums.txt"
# 验证 checksum
sha256sum --check --ignore-missing rekor_checksums.txt
# 预期输出：
# rekor-cli-linux-amd64: OK
2.3 安装 cosign
cosign 是 Sigstore 生态中的签名和验证工具，与 Rekor 紧密集成。
2.3.1 macOS 安装
brew install cosign
# 验证安装
cosign version
# 预期输出示例：
# ______ ______ _______. __ _______ .__ __.
# / | / __ \ / || | / || \ | |
# | ,----'| | | | | (----`| | | (----`| \| |
# | | | | | | \ \ | | \ \ | . ` |
# | `----.| `--' | .----) | | | .----) | |\ |
# \______| \______/ |_______/ |__| |_______/|__| \__|
#
# cosign: Signing container images and other artifacts
# GitVersion: v2.4.1
2.3.2 Linux 安装
COSIGN_VERSION="v2.4.1"
curl -LO "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64"
sudo mv cosign-linux-amd64 /usr/local/bin/cosign
sudo chmod +x /usr/local/bin/cosign
cosign version
2.3.3 验证 cosign 安装
# 测试与公共 Rekor 服务器的连接
cosign initialize
# 预期输出：
# Root status:
# - CTFE public key: <hash>
# - Rekor public key: <hash>
# - Fulcio certificate: <hash>
# No TUF root available, using embedded root
# Sigstore root status updated to latest
2.4 Rekor 服务器安装
如果你需要运行私有 Rekor 实例（例如在企业内网中），需要安装 rekor-server。
2.4.1 从源码编译
# 克隆仓库
git clone https://github.com/sigstore/rekor.git
cd rekor
# 编译 rekor-server
go build -o rekor-server ./cmd/rekor-server
# 验证
./rekor-server version
2.4.2 预编译二进制
REKOR_VERSION="v1.3.6"
curl -LO "https://github.com/sigstore/rekor/releases/download/${REKOR_VERSION}/rekor-server-linux-amd64"
sudo mv rekor-server-linux-amd64 /usr/local/bin/rekor-server
sudo chmod +x /usr/local/bin/rekor-server
2.4.3 服务端依赖
rekor-server 需要以下后端服务：
| 依赖 | 用途 | 推荐版本 |
|---|---|---|
| Trillian | Merkle Tree 存储后端 | v1.6.x |
| MySQL / PostgreSQL | Trillian 数据库 | MySQL 8.0+ / PostgreSQL 14+ |
| Redis（可选） | 缓存和速率限制 | Redis 7.x |
2.5 Docker 安装
使用 Docker 是运行 Rekor 最便捷的方式，特别适合本地开发和测试。
2.5.1 拉取官方镜像
# 拉取 rekor-server 镜像
docker pull gcr.io/projectsigstore/rekor-server:v1.3.6
# 拉取 rekor-cli 镜像
docker pull gcr.io/projectsigstore/rekor-cli:v1.3.6
# 查看镜像
docker images | grep rekor
2.5.2 快速启动（单容器测试）
# 使用 docker run 启动一个测试实例
# 注意：生产环境请使用 Docker Compose（见第 9 章）
docker run --rm -p 3000:3000 \
gcr.io/projectsigstore/rekor-server:v1.3.6 \
serve \
--trillian_log_server.address=localhost \
--trillian_log_server.port=8090 \
--redis_server.address=redis
注意：单独运行 rekor-server 不够，它依赖 Trillian 和数据库。完整的 Docker Compose 部署请参见 第 9 章。
2.5.3 使用 Docker 运行 rekor-cli
# 通过 Docker 运行 rekor-cli 查询公共 Rekor 服务
docker run --rm gcr.io/projectsigstore/rekor-cli:v1.3.6 \
--rekor_server=https://rekor.sigstore.dev \
loginfo
2.6 密钥配置
2.6.1 生成签名密钥对
使用 cosign 生成用于签名的密钥对：
# 生成密钥对（会提示输入密码）
cosign generate-key-pair
# 预期输出：
# Enter password for private key:
# Enter again:
# Private key written to cosign.key
# Public key written to cosign.pub
生成的文件：
| 文件 | 说明 |
|---|---|
cosign.key | 私钥文件（PEM 格式，使用密码加密） |
cosign.pub | 公钥文件（PEM 格式，用于验证） |
2.6.2 查看生成的密钥
# 查看公钥内容
cat cosign.pub
# 预期输出（类似）：
# -----BEGIN PUBLIC KEY-----
# MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
# -----END PUBLIC KEY-----
2.6.3 密钥存储最佳实践
| 存储方式 | 安全级别 | 适用场景 |
|---|---|---|
| 本地文件系统 | ⭐⭐ | 个人开发、测试 |
| 环境变量 | ⭐⭐ | CI/CD 流水线（配合 Secret Manager） |
| HashiCorp Vault | ⭐⭐⭐⭐ | 企业级密钥管理 |
| 云 KMS（AWS/GCP/Azure） | ⭐⭐⭐⭐⭐ | 企业生产环境 |
| Kubernetes Secrets | ⭐⭐⭐ | K8s 环境（需配合 RBAC） |
2.6.4 使用环境变量传递密钥密码
# 设置环境变量（避免在命令行中明文输入）
export COSIGN_PASSWORD="your-secure-password"
# 非交互式签名
cosign sign --key cosign.key --yes \
--tlog-upload=true \
example-registry.io/image:tag
2.6.5 无密钥签名（Keyless）
使用 Sigstore 的无密钥签名模式，无需管理长期密钥：
# 无密钥签名（需要浏览器进行 OIDC 认证）
cosign sign --yes \
example-registry.io/image:tag
# CI/CD 环境中使用（自动检测 OIDC 环境）
# GitHub Actions
cosign sign --yes \
--identity-token=$ACTIONS_ID_TOKEN_REQUEST_URL \
example-registry.io/image:tag
无密钥签名流程：cosign 会自动向 Fulcio 请求短期证书，用临时密钥签名，然后将签名记录到 Rekor。整个过程无需手动管理任何密钥。
2.7 环境变量配置
2.7.1 rekor-cli 环境变量
| 环境变量 | 说明 | 默认值 |
|---|---|---|
REKOR_SERVER | Rekor 服务器地址 | https://rekor.sigstore.dev |
REKOR_FORMAT | 输出格式 | json |
REKOR_LOG_LEVEL | 日志级别 | info |
# 设置使用自定义 Rekor 服务器
export REKOR_SERVER=https://rekor.example.com
# 设置输出格式为 JSON
export REKOR_FORMAT=json
2.7.2 cosign 环境变量
| 环境变量 | 说明 |
|---|---|
COSIGN_PASSWORD | 私钥密码 |
COSIGN_REPOSITORY | 签名存储仓库 |
COSIGN_REKOR_URL | Rekor 服务器地址 |
COSIGN_FULCIO_URL | Fulcio 服务器地址 |
COSIGN_OIDC_ISSUER | OIDC 颁发者 URL |
COSIGN_EXPERIMENTAL | 启用无密钥签名（1） |
2.7.3 配置文件
rekor-cli 和 cosign 支持通过配置文件设置默认参数：
# 创建配置目录
mkdir -p ~/.config/rekor
# 创建 rekor-cli 配置
cat > ~/.config/rekor/config.yaml << 'EOF'
rekor_server: https://rekor.sigstore.dev
format: json
log_level: info
EOF
2.8 连接公共 Rekor 实例
2.8.1 公共实例信息
| 参数 | 值 |
|---|---|
| API 地址 | https://rekor.sigstore.dev |
| API 版本 | v1 |
| Swagger 文档 | https://rekor.sigstore.dev/api/v1/swagger.json |
| 日志 ID | 通过 rekor-cli loginfo 获取 |
2.8.2 测试连接
# 测试与公共 Rekor 的连接
rekor-cli loginfo --rekor_server=https://rekor.sigstore.dev
# 使用 curl 直接测试 API
curl -s https://rekor.sigstore.dev/api/v1/log | head -c 200
# 查看 API 版本
curl -s https://rekor.sigstore.dev/api/v1/version
2.8.3 网络代理配置
如果在企业内网需要通过代理访问：
# 设置 HTTP 代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
# 或者在命令行中指定
rekor-cli loginfo --rekor_server=https://rekor.sigstore.dev
# cosign 代理配置
export COSIGN_REKOR_URL=https://rekor.sigstore.dev
2.9 故障排除
2.9.1 常见安装问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
command not found: rekor-cli | 未在 PATH 中 | 检查 /usr/local/bin 是否在 $PATH 中 |
permission denied | 无执行权限 | 执行 chmod +x /usr/local/bin/rekor-cli |
certificate verify failed | SSL 证书问题 | 检查系统 CA 证书，或设置 --rekor_server 为 HTTP |
connection refused | 网络不通 | 检查防火墙和代理设置 |
dial tcp: lookup rekor.sigstore.dev | DNS 解析失败 | 检查 DNS 配置 |
2.9.2 诊断命令
# 检查 rekor-cli 安装路径
which rekor-cli
# 检查版本
rekor-cli version
# 检查网络连接
curl -v https://rekor.sigstore.dev/api/v1/log 2>&1 | head -20
# 检查 DNS 解析
nslookup rekor.sigstore.dev
# 使用详细日志级别
rekor-cli loginfo --log_level=debug
2.9.3 cosign 初始化失败
# 如果 cosign initialize 失败，尝试手动设置 TUF root
cosign initialize --mirror=https://tuf-repo-cdn.sigstore.dev
# 清除本地 TUF 缓存后重试
rm -rf ~/.sigstore/root
cosign initialize
2.10 本章小结
| 任务 | 命令 / 位置 |
|---|---|
| 安装 rekor-cli | brew install sigstore/tap/rekor-cli 或下载二进制 |
| 安装 cosign | brew install cosign 或下载二进制 |
| 生成密钥对 | cosign generate-key-pair |
| 测试连接 | rekor-cli loginfo |
| 设置服务器地址 | export REKOR_SERVER=https://rekor.sigstore.dev |
| Docker 拉取 | docker pull gcr.io/projectsigstore/rekor-server:v1.3.6 |
扩展阅读
下一章：03 - 基本操作 — 学习如何创建条目、查询日志、验证包含证明。