---
title: "安装 Cosigner"
description: "安装 cosigner-cli，验证已签名的运行时，与 Fystack 配对并启动 Cosigner。"
url: https://docs.fystack.io/zh/cosigner/installation
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# 安装 Cosigner

在 Linux 上使用 Docker 以常规模式运行。[Nitro Enclave](https://docs.fystack.io/cosigner/nitro-enclave.md) 支持即将推出。

_Diagram: 安装、验证、配对、连接_

## 前提条件

- **宿主机**：生产环境使用 Linux `amd64` 或 `arm64`。开发环境可使用 macOS 或 WSL 2。
- **Docker**：Engine 20.10+ 及 Compose v2。
- **cosign**：v3+。如未安装，安装程序会自动添加。
- **来自 Fystack**：一个配对令牌（`cps_...`）。请参阅[第 1 步](#step-1-get-a-pairing-token)。
- **回调服务器**：生产环境必需。请参阅[审批回调](https://docs.fystack.io/cosigner/approval-callback.md)。

**网络：** 无需入站端口。需要出站 HTTPS 访问 Apex、Fystack Gateway、`ghcr.io`、你的回调，以及 AWS KMS（无人值守配置）。

---

## 第 1 步：获取配对令牌

在 Fystack 控制台中，打开 **Cosigner** 标签页，点击 **Register Cosigner**，选择 **Server**，然后点击 **Continue**。

_Diagram: Register Cosigner 对话框，已选择 Server 选项_

为 Cosigner 输入名称。对话框会显示安装命令和配对令牌（`cps_...`）。请复制该令牌：它只能使用一次，60 分钟后过期，并且只显示一次。

完成以下步骤期间请保持对话框打开。它会显示 **Waiting for your cosigner to connect**，并在 Cosigner 配对后自动更新。

_Diagram: Register Cosigner 对话框，显示安装命令、配对令牌和等待连接状态_

## 第 2 步：安装 cosigner-cli

```bash
curl -sSL https://cosigner.fystack.io/install.sh | sh
```

该脚本会检查二进制文件的 SHA-256 和 Sigstore 签名，然后安装到 `/usr/local/bin`（或 `~/.local/bin`）。

| 选项 | 环境变量 | 作用 |
| --- | --- | --- |
| `--version vX.Y.Z` | `COSIGNER_VERSION` | 安装指定版本 |
| `--dir DIR` | `COSIGNER_INSTALL_DIR` | 安装位置 |
| `--skip-docker-check` |  | 跳过 Docker 检查 |

> **Note:** 如需在运行前验证安装程序，请参阅[供应链验证](https://docs.fystack.io/cosigner/security.md#supply-chain-verification)。

## 第 3 步：创建实例目录

在宿主机上合适的位置为该 Cosigner 新建一个空目录，并在该目录中运行其余命令。`cosigner-cli` 会将实例的所有配置、密钥和状态保存在其中。

## 第 4 步：检查宿主机

```bash
cosigner-cli doctor
```

检查 Docker、cosign 和配置。报告状态为 `unconfigured`、`configured but unpaired` 或 `paired`。

## 第 5 步：配对并启动

```bash
cosigner-cli up
```

`up` 随后会：

1. **询问** Fystack endpoint。按 Enter 保留默认值。
2. **验证**：在要求输入任何密钥之前，使用 cosign 验证最新的 `ghcr.io/fystack/cosigner` 版本并锁定其摘要。
3. **写入** 默认的 `config.yaml`（manual 配置，回调关闭）。
4. **提示** 输入存储密码和第 1 步获取的配对令牌。
5. **配对**：生成 Ed25519 身份，向 Apex 注册，并保存 `state/pairing.yaml`。
6. **启动** 容器，将其解锁并连接到 Gateway。

_Diagram: cosigner-cli up 输出：镜像已验证并锁定，存储已解锁，已与 Apex 配对，Cosigner 正在运行_

默认配置使用 **`manual`** 配置：存储密钥由你的密码封装，每次启动时都需要输入密码，且不会自动重启。如需改用 AWS KMS 实现开机自启，请参阅[无人值守配置](#unattended-profile)。

## 第 6 步：启用回调审批

生成的配置中为 `require_callback: false`，因此 Fystack 发送的任何请求都会被签名。请在创建钱包之前启用审批：

```bash
cosigner-cli callback add https://YOUR-CALLBACK-HOST \
  --server-public-key server-public.pem
```

该命令会就地修改 `config.yaml`，在 `secrets/` 中生成 Cosigner 的回调密钥，写入 `cosigner-public.pem` 并重启 Cosigner。请将 `cosigner-public.pem` 复制到你的回调服务器。请参阅[审批回调](https://docs.fystack.io/cosigner/approval-callback.md)。

现在的配置如下：

```yaml
storage:
  backend: sqlite
  sqlite:
    path: data/cosigner.db
  encryption:
    kek:
      type: password_envelope
      config:
        path: /run/secrets/storage-kek.enc
approval:
  require_callback: true
audit:
  type: file
  config:
    path: /var/lib/cosigner/audit.jsonl
callback:
  timeout: 30s
  retry_count: 1
  url: https://YOUR-CALLBACK-HOST/cosigner/approve
  private_key:
    type: file
    config:
      path: /run/secrets/cosigner-private.der.hex
  response_public_key_path: /run/secrets/server-public.pem
```

如需调整其他设置，例如 `timeout` 或 `retry_count`，请编辑该文件并运行 `cosigner-cli restart`。

- 在容器内，`/var/lib/cosigner` 对应实例的 `state/` 目录，`/run/secrets` 对应其 `secrets/` 目录（只读）。
- 请保持 `storage` 和 `audit` 为生成时的设置：`cosigner-cli` 要求使用位于 `data/cosigner.db` 的 SQLite 以及基于文件的审计日志。

## 第 7 步：验证

```bash
cosigner-cli status
cosigner-cli info
cosigner-cli logs -f
```

当 `status` 显示 ready 时，Cosigner 即已上线，可以参与密钥生成。

## 无人值守配置

默认配置仅支持 manual 配置。使用 **`unattended`** 时，存储密钥由你的 AWS KMS 密钥封装，Cosigner 会在开机时自动启动。请在第 5 步之前自行编写配置文件，并将其放在实例目录之外（`up` 会将其复制进来）：

```yaml
storage:
  backend: sqlite
  sqlite:
    path: data/cosigner.db
  encryption:
    kek:
      type: kms
      config:
        provider: aws
        region: YOUR-AWS-REGION
        key_id: YOUR-KMS-KEY-ARN
        ciphertext_blob_path: /run/secrets/storage-kek.kms
approval:
  require_callback: false
audit:
  type: file
  config:
    path: /var/lib/cosigner/audit.jsonl
```

使用你的 KMS 密钥加密一个随机的 32 字节密钥，并将 base64 编码的密文保存为实例目录中的 `secrets/storage-kek.kms`。容器需要通过 IAM 角色获得 `kms:Decrypt` 权限。然后运行：

```bash
cosigner-cli up \
  --profile unattended \
  --config /secure/config.yaml
```

继续执行[第 6 步](#step-6-turn-on-callback-approval)以启用回调审批。

## 实例目录结构

| 路径 | 内容 |
| --- | --- |
| `cosigner-cli.yaml` | Apex endpoint、锁定的镜像摘要、配置类型 |
| `config.yaml` | 运行时配置（只读） |
| `docker-compose.yaml` | 自动生成的加固版 Compose 文件 |
| `secrets/` | 封装后的存储密钥和回调密钥 |
| `state/pairing.yaml` | 来自 Apex 的配对记录 |
| `state/cosigner.key` | Ed25519 身份密钥 |
| `state/data/cosigner.db` | 加密的密钥分片和会话状态 |
| `state/audit.jsonl` | 已签名的审计日志 |

## 开机自启

仅适用于无人值守配置。请根据需要调整随附的 systemd unit：

```ini
[Unit]
Description=Fystack Cosigner (KMS unattended profile)
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
User=cosigner
Group=cosigner
SupplementaryGroups=docker
ExecStart=/usr/local/bin/cosigner-cli --home /var/lib/fystack-cosigner start
ExecStop=/usr/local/bin/cosigner-cli --home /var/lib/fystack-cosigner stop
TimeoutStartSec=360
TimeoutStopSec=60
UMask=0077

[Install]
WantedBy=multi-user.target
```

对于 manual 配置，可通过文件描述符传入密码：

```bash
COSIGNER_PASSWORD_FD=3 cosigner-cli start 3< /run/secrets/cosigner-pw
```

这种方式的安全性低于手动输入密码。请参阅[自动重启](https://docs.fystack.io/cosigner/operations.md#automate-restart)。

## 故障排查

| 现象 | 解决方法 |
| --- | --- |
| 镜像签名验证失败 | 不要绕过。请检查镜像引用并联系 security@fystack.io。 |
| identity already registered | 请从备份中恢复原始配对数据，而不是重新配对。 |
| 启动后立即退出 | 启动时的回调 ping 失败。请检查回调是否可访问，以及是否信任 `cosigner-public.pem`。 |
| AlreadyExists | 另一个使用相同身份的实例已连接。请将其停止。 |
| PermissionDenied | Cosigner 已被吊销，将不会重新连接。 |
| 首次启动后未就绪 | 正在生成 ECDSA 预参数。请等待最多 5 分钟。 |