---
title: "Cosigner 运维"
description: "cosigner-cli 参考、备份、恢复导出、更新与监控。"
url: https://docs.fystack.io/zh/cosigner/operations
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 运维

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` 在文件描述符上传入口令。

从文件读取：

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

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

```bash
COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart \
  3< <(gcloud secrets versions access latest --secret=cosigner-passphrase)
```

- `3` 是文件描述符编号。它必须大于等于 3，且两处保持一致。
- 文件中只能包含口令。末尾的一个换行符会被移除，任何其他多余字符都会导致解锁失败。
- 口令错误会立即失败，不会重试。

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

## 备份与恢复

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

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

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

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

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

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

## 恢复导出

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

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

请将口令与文件分开保存。完整操作流程请参阅[密钥恢复](https://docs.fystack.io/cosigner/recovery.md)。

## 更新

```bash
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. 按照你的保留策略保存最终备份和导出文件，然后删除实例目录。