Cosigner 运维

CLI 参考、备份、更新与监控。

命令

全局参数：--home（实例目录，默认依次使用 COSIGNER_HOME 和当前目录）以及 --docker。

命令 作用 参数
up 校验、配对并启动新实例。配对完成后等同于 start。 --apex-endpoint --config --profile --image --token-file
start 启动。在 manual 配置下会要求输入密码。
stop 停止并保留状态。最多花 25 秒排空会话。
restart 重新创建容器。
status ready, state, participant_id, active_sessions.
logs 容器日志。 --tail -f
doctor 检查主机、配置和镜像签名。
info 公钥、镜像、回调指纹。
callback add 要求回调审批。 --url --server-public-key --ca --no-restart
callback remove 不再要求审批。 -y --no-restart
backup 加密的实例备份。必须先停止 cosigner。 --out
restore 恢复到一个空目录中。 --in
export 写入 .mshare 恢复文件。需为 manual 配置且已停止。 --wallet --out-dir --list
update 先备份，再校验并安装更新的版本。 --version --backup-out --dry-run
version CLI 版本。

环境变量

变量 用途
COSIGNER_HOME 实例目录
COSIGNER_PASSWORD_FD 从文件描述符读取存储密码
COSIGNER_RECOVERY_PASSWORD_FD 从文件描述符读取备份密码
COSIGNER_NO_UPDATE_CHECK=1 隐藏更新提示

配置模式

manual unattended
存储密钥 密码（Argon2id） AWS KMS
启动 每次都需输入密码 开机时自动启动
Docker 重启策略 no on-failure:5
.mshare 导出 支持 不支持

在 up 时设置，之后无法更改。

自动重启

在 manual 配置下，start 和 restart 会要求输入存储口令。如需从脚本中运行，请通过 COSIGNER_PASSWORD_FD 在文件描述符上传入口令。

从文件读取：

chmod 600 /etc/cosigner/passphrase
COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart 3< /etc/cosigner/passphrase

从 secret store 读取，这样口令不会写入磁盘：

COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart \
  3< <(gcloud secrets versions access latest --secret=cosigner-passphrase)
  • 3 是文件描述符编号。它必须大于等于 3，且两处保持一致。
  • 文件中只能包含口令。末尾的一个换行符会被移除，任何其他多余字符都会导致解锁失败。
  • 口令错误会立即失败，不会重试。

这比手动输入口令的安全性更低。任何能够读取口令文件或 secret 并运行 cosigner-cli 的人都可以解锁 cosigner。请将口令保存在实例目录之外，切勿与 secrets/storage-kek.enc 放在一起，并限制可读取它的人员。相比文件，优先使用 secret store。

备份与恢复

backup 会写入一个归档文件，其中包含配置、secrets、身份、配对记录、加密数据库和审计日志。该归档使用单独的恢复密码加密（Argon2id + AES-256-GCM）。

cosigner-cli stop
cosigner-cli backup --out /backups/cosigner-2026-10-12.cosrec
cosigner-cli start

请将其写入实例目录之外。实例数据上限为 128 MiB。

cosigner-cli --home /srv/cosigner-restored restore --in /backups/cosigner-2026-10-12.cosrec
cosigner-cli --home /srv/cosigner-restored start

请先停止或吊销旧实例。切勿同时运行同一个 cosigner 的两个副本。

请定期在干净的主机上测试恢复。

恢复导出

export 会为每个钱包写入一个 .mshare 文件，并使用只打印一次的六词口令加密。这些文件是 cosigner 提供给 Fystack Recovery 的输入，后者可以在离线状态下用达到门限数量的分片重建密钥。单个文件无法重建密钥。

cosigner-cli stop
cosigner-cli export --out-dir /secure/recovery
cosigner-cli start

请将口令与文件分开保存。完整操作流程请参阅密钥恢复。

更新

cosigner-cli update --dry-run
cosigner-cli update --backup-out /backups/pre-update.cosrec
  1. 选择最新版本（或 --version 指定的版本）。不支持降级。
  2. 校验签名和容器约定。
  3. 停止 cosigner 并写入备份。
  4. 固定新的 digest 并启动。

不会自动回滚。请保留备份，直到新版本已签名过真实交易。

监控

健康检查：每 10 秒检查一次，超过 15 秒未更新即视为过期。出现以下情况时应告警：

  • 首次启动设置完成后仍为 ready: false。
  • state: callback_unavailable。
  • 容器退出（manual 配置永远不会自动重启）。

审计日志：state/audit.jsonl，经过签名并以哈希链式连接。事件包括：session_start、session_end、session_abort、callback_decision、kek_use、identity_sign、backup_created、restore_performed。请将其传送到主机之外，Docker 不会对其进行轮转。

日志：Docker json-file，10 MB x 5。

下线

  1. 请 Fystack 吊销该 cosigner。
  2. cosigner-cli stop。
  3. 按照你的保留策略保存最终备份和导出文件，然后删除实例目录。