安装 Cosigner

在 Linux 上使用 Docker 以常规模式运行。Nitro Enclave 支持即将推出。

前提条件

• 宿主机：生产环境使用 Linux amd64 或 arm64。开发环境可使用 macOS 或 WSL 2。
• Docker：Engine 20.10+ 及 Compose v2。
• cosign：v3+。如未安装，安装程序会自动添加。
• 来自 Fystack：一个配对令牌（cps_...）。请参阅第 1 步。
• 回调服务器：生产环境必需。请参阅审批回调。

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

第 1 步：获取配对令牌

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

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

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

第 2 步：安装 cosigner-cli

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

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

第 3 步：创建实例目录

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

第 4 步：检查宿主机

cosigner-cli doctor

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

第 5 步：配对并启动

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。

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

第 6 步：启用回调审批

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

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 复制到你的回调服务器。请参阅审批回调。

现在的配置如下：

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 步：验证

cosigner-cli status
cosigner-cli info
cosigner-cli logs -f

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

无人值守配置

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

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 权限。然后运行：

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

继续执行第 6 步以启用回调审批。

实例目录结构

开机自启

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

[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 配置，可通过文件描述符传入密码：

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

这种方式的安全性低于手动输入密码。请参阅自动重启。

故障排查