使用 CLI 部署 Solana 程序

加密女士
发布于 2025-03-19 18:37
阅读 370

要部署程序，请使用Solana工具与链上加载器交互以：初始化程序帐户将程序的共享对象（程序二进制文件.so）上传到程序账户的数据缓冲区（可选）验证上传的程序通过将程序帐户标记为可执行来完成该程序。一旦部署，任何人都可以通过向集群发送引用该程序的交易来执行该程序。如何部署程序要

要部署程序，请使用 Solana 工具与链上加载器交互以：

* 初始化程序帐户
* 将程序的共享对象（程序二进制文件`.so`）上传到程序账户的数据缓冲区
* （可选）验证上传的程序
* 通过将程序帐户标记为可执行来完成该程序。

一旦部署，任何人都可以通过向集群发送引用该程序的交易来执行该程序。

## 如何部署程序

要部署程序，您将需要程序共享对象（程序二进制文件`.so`）的位置：

```
solana program deploy <PROGRAM_FILEPATH>
```

部署成功会返回已部署程序的程序id，例如：

```
Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
```

在部署命令中指定密钥对以部署到特定的程序 id：

```
solana program deploy --program-id <KEYPAIR_FILEPATH> <PROGRAM_FILEPATH>
```

如果命令行中没有指定程序 ID，工具将首先查找与之匹配的密钥对文件`<PROGRAM_FILEPATH>`，或者内部生成一个新的密钥对。

匹配的程序密钥对文件与程序的共享对象位于同一目录中，名为 \<PROGRAM_NAME>-keypair.json。匹配的程序密钥对由程序构建工具自动生成：

```
./path-to-program/program.so
./path-to-program/program-keypair.json
```

## 显示程序帐户

要获取有关已部署程序的信息：

```
solana program show <ACCOUNT_ADDRESS>
```

示例输出如下：

```
Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g
Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU
Last Deployed In Slot: 63890568
Data Length: 5216 (0x1460) bytes
```

* `Program Id``program_id`是调用程序时可以在指令字段中引用的地址 。
* `Owner`：部署此程序时使用的加载器。
* `ProgramData Address`是与保存程序数据（共享对象）的程序帐户关联的帐户。
* `Authority`是程序的升级权限。
* `Last Deployed In Slot`是程序最后部署的插槽。
* `Data Length`是为部署预留的空间大小。当前部署的程序实际使用的空间可能更小。

## 重新部署 Solana程序

可以将程序重新部署到同一地址，以方便快速开发、修复错误或升级。如果未提供程序 ID，则程序将部署到默认地址`<PROGRAM_NAME>-keypair.json`。此默认密钥对是在第一次程序编译期间生成的。

该命令看起来与部署命令相同：

```
solana program deploy <PROGRAM_FILEPATH>
```

默认情况下，程序会部署到与原始程序文件大小匹配的帐户。但是，如果重新部署的程序较大，则重新部署将失败。为避免这种情况，请指定一个`max_len`至少为程序预期大小（以字节为单位）的 （加上一些回旋余地）。

```
solana program deploy --max-len 200000 <PROGRAM_FILEPATH>
```

## 扩展程序

如果已经部署了程序，并且重新部署超出了 `max_len`帐户的范围，则可以扩展该程序以适应更大规模的重新部署：

```
solana program extend <PROGRAM_ID> <ADDITIONAL_BYTES>
```

## 恢复失败的部署

如果程序部署失败，将有一个挂起的中间缓冲帐户，其中包含非零余额。为了收回该余额，您可以通过向新的调用提供相同的中间缓冲来恢复失败的部署 `deploy`。

部署失败将打印一条错误消息，指定恢复生成的中间缓冲区的密钥对所需的种子短语：

```
==================================================================================
Recover the intermediate account's ephemeral keypair file with
`solana-keygen recover` and the following 12-word seed phrase:
==================================================================================
valley flat great hockey share token excess clever benefit traffic avocado athlete
==================================================================================
To resume a deploy, pass the recovered keypair as
the [BUFFER_SIGNER] to `solana program deploy` or `solana program write-buffer'.
Or to recover the account's lamports, pass it as the
[BUFFER_ACCOUNT_ADDRESS] argument to `solana program drain`.
==================================================================================
```

要恢复密钥对：

```
solana-keygen recover -o <KEYPAIR_PATH>
```

当系统询问时，输入 12 个字的种子短语。

然后发出新`deploy`命令并指定缓冲区：

```
solana program deploy --buffer <KEYPAIR_PATH> <PROGRAM_FILEPATH>
```

## 关闭程序和缓冲区帐户并回收其端口

计划账户和缓冲账户均可关闭，并将其 Lamport 余额转移到收款人的账户中。

如果部署失败，将有一个剩余的缓冲账户用于保存 lamport。缓冲账户可用于 恢复部署或关闭。

必须有程序或缓冲账户的权限才能关闭账户，列出所有符合默认权限的打开的程序或缓冲账户：

```
solana program show --programs
solana program show --buffers
```

要指定不同的权限：

```
solana program show --programs --buffer-authority <AUTHORITY_ADDRESS>
solana program show --buffers --buffer-authority <AUTHORITY_ADDRESS>
```

关闭单个账户：

```
solana program close <ADDRESS>
```

要关闭单个帐户并指定与默认权限不同的权限：

```
solana program close <ADDRESS> --buffer-authority <KEYPAIR_FILEPATH>
```

要关闭单个帐户并指定非默认收件人：

```
solana program close <ADDRESS> --recipient <RECIPIENT_ADDRESS>
```

关闭与当前权限相关的所有缓冲帐户：

```
solana program close --buffers
```

显示所有缓冲账户，无论其权限如何

```
solana program show --buffers --all
```

## 设置程序的升级权限

必须具有程序的升级权限才能部署程序。如果在程序部署期间未指定权限，则使用默认密钥对作为权限。这就是为什么上述步骤中重新部署程序不需要明确指定权限的原因。

可以在部署期间指定权限：

```
solana program deploy --upgrade-authority <UPGRADE_AUTHORITY_SIGNER> <PROGRAM_FILEPATH>
```

或者部署后使用默认密钥对作为当前权限：

```
solana program set-upgrade-authority <PROGRAM_ADDRESS> --new-upgrade-authority <NEW_UPGRADE_AUTHORITY>
```

或者部署后并指定当前权限：

```
solana program set-upgrade-authority <PROGRAM_ADDRESS> --upgrade-authority <UPGRADE_AUTHORITY_SIGNER> --new-upgrade-authority <NEW_UPGRADE_AUTHORITY>
```

默认情况下，`set-upgrade-authority`需要新机构的签名。此行为可防止开发人员将升级权限授予他们无权访问的密钥。此`--skip-new-upgrade-authority-signer-check` 选项放宽了签名者检查。这对于新升级权限是离线签名者或多重签名的情况非常有用。

## 不可变程序

`--final`可以通过在部署期间指定标志将程序标记为不可变，从而防止所有进一步的重新部署：

```
solana program deploy <PROGRAM_FILEPATH> --final
```

或者之后的任何时间：

```
solana program set-upgrade-authority <PROGRAM_ADDRESS> --final
```

## 将程序转储到文件

已部署的程序可能会被转储回本地文件：

```
solana program dump <ACCOUNT_ADDRESS> <OUTPUT_FILEPATH>
```

转储文件将与部署文件相同，因此对于共享对象（程序二进制文件`.so`），转储文件将是一个功能齐全的共享对象。请注意，该`dump`命令会转储整个数据空间，这意味着输出文件将在共享对象的数据后保留尾随零，直到`max_len`。有时，转储和比较程序以确保它与已知程序二进制文件匹配很有用。转储文件可以进行零截断、哈希处理，并与原始程序文件的哈希值进行比较。

```
$ solana dump <ACCOUNT_ADDRESS> dump.so
$ cp original.so extended.so
$ truncate -r dump.so extended.so
$ sha256sum extended.so dump.so
```

## 使用中间缓冲账户

可以将程序写入中间缓冲账户，而不是直接部署到程序账户。中间账户对于多实体治理程序等非常有用，其中治理成员首先验证中间缓冲内容，然后投票允许使用它进行升级。

```
solana program write-buffer <PROGRAM_FILEPATH>
```

缓冲帐户由权限管理。要创建缓冲区并指定与默认权限不同的权限，请执行以下操作：

```
solana program write-buffer <PROGRAM_FILEPATH> --buffer-authority <BUFFER_AUTHORITY_SIGNER>
```

只有缓冲区授权者可以写入缓冲区，因此`--buffer-authority`上述内容必须是 **签名者**，而不是地址。此要求限制了离线签名者的使用。要使用离线地址作为缓冲区授权者，必须使用在线密钥对初始化缓冲区帐户并写入，然后必须使用以下方式分配缓冲区授权者 `solana program set-buffer-authority`：

```
solana program set-buffer-authority <BUFFER_ADDRESS> --new-buffer-authority <NEW_BUFFER_AUTHORITY>
```

与程序账户不同，缓冲账户不能标记为不可变，因此它们不支持该`--final`选项。

缓冲账户一旦完全写入，就可以传递给`deploy`部署程序：

```
solana program deploy --program-id <PROGRAM_ADDRESS> --buffer <BUFFER_ADDRESS>
```

注意，缓冲区的权限必须与程序的升级权限相匹配。在部署期间，缓冲区帐户的内容被复制到程序数据帐户中，并且缓冲区帐户被设置为零。来自缓冲区帐户的 Lamport 被退还到溢出帐户。

缓冲区也支持`show`，`dump`就像程序一样。

## 使用离线签名者作为权限

一些安全模型要求将签名过程与交易广播分开，这样签名密钥可以完全与任何网络断开连接，也称为离线签名。

本节介绍程序开发人员如何使用离线签名来升级他们的程序，与上一节不同，上一节假设机器已连接到互联网，即在线签名。

请注意，只有该`upgrade`命令才能在离线模式下执行。初始程序部署**必须**从在线机器执行，并且只有后续程序升级才能利用离线签名。

假设您的程序已部署并且其升级权限已更改为离线签名者，则典型的设置将由 2 个不同的签名者组成：

* 在线签名者（上传程序缓冲区和升级程序的付费者）
* 离线签名者（程序升级权限）

总体流程如下：

1. （在线）创建缓冲区并向其中写入新程序
2. （在线）设置缓冲区权限给离线签名者
3. （可选，在线）验证缓冲区的链上内容
4. （离线）签署交易以升级程序
5. （在线）使用此签名广播升级交易

```
# (1) (use online machine) create buffer
solana program write-buffer <PROGRAM_FILEPATH>

# (2) (use online machine) set buffer authority to offline signer
solana program set-buffer-authority <BUFFER_PUBKEY> --new-buffer-authority <OFFLINE_SIGNER_PUBKEY>
```

（3）（可选）您可以验证上传的程序是否与构建的二进制文件匹配。请参阅将程序转储到文件以了解更多信息和细节。

```
# (4) (use offline machine) get a signature for your intent to upgrade program
solana program upgrade <BUFFER_PUBKEY> <PROGRAM_ID> --sign-only --fee-payer <ONLINE_SIGNER_PUBKEY> --upgrade-authority <OFFLINE_SIGNER> --blockhash <VALUE>

# (5) (use online machine) use this signature to build and broadcast the upgrade transaction on-chain
solana program upgrade <BUFFER_PUBKEY> <PROGRAM_ID> --fee-payer <ONLINE_SIGNER> --upgrade-authority <OFFLINE_SIGNER_PUBKEY> --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>
```

笔记：

* 通常，前一个命令的输出将包含一些对后续命令有用的值， 例如`--program-id`，，`--buffer``--signer`
* 您需要在离线/在线模式下为具有 相同名称的参数指定匹配（或相应）的值（`--fee-payer`，，，，，）`--program-id``--upgrade-authority``--buffer``--blockhash`
* 您应该预先填写除 之外的所有值`blockhash`，一旦您准备好采取行动，您将需要查找最近的`blockhash`并粘贴它以生成离线交易签名。`blockhash`大约 60 秒后过期。 如果您没有及时完成 - 只需获取另一个新的哈希并重复直到成功，或者考虑使用持久交易随机数。

要部署程序，请使用 Solana 工具与链上加载器交互以：

初始化程序帐户
将程序的共享对象（程序二进制文件.so）上传到程序账户的数据缓冲区
（可选）验证上传的程序
通过将程序帐户标记为可执行来完成该程序。

一旦部署，任何人都可以通过向集群发送引用该程序的交易来执行该程序。

如何部署程序

要部署程序，您将需要程序共享对象（程序二进制文件.so）的位置：

solana program deploy &lt;PROGRAM_FILEPATH>

部署成功会返回已部署程序的程序id，例如：

Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL

在部署命令中指定密钥对以部署到特定的程序 id：

solana program deploy --program-id &lt;KEYPAIR_FILEPATH> &lt;PROGRAM_FILEPATH>

如果命令行中没有指定程序 ID，工具将首先查找与之匹配的密钥对文件<PROGRAM_FILEPATH>，或者内部生成一个新的密钥对。

匹配的程序密钥对文件与程序的共享对象位于同一目录中，名为 \<PROGRAM_NAME>-keypair.json。匹配的程序密钥对由程序构建工具自动生成：

./path-to-program/program.so
./path-to-program/program-keypair.json

显示程序帐户

要获取有关已部署程序的信息：

solana program show &lt;ACCOUNT_ADDRESS>

示例输出如下：

Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g
Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU
Last Deployed In Slot: 63890568
Data Length: 5216 (0x1460) bytes

Program Id``program_id是调用程序时可以在指令字段中引用的地址。
Owner：部署此程序时使用的加载器。
ProgramData Address是与保存程序数据（共享对象）的程序帐户关联的帐户。
Authority是程序的升级权限。
Last Deployed In Slot是程序最后部署的插槽。
Data Length是为部署预留的空间大小。当前部署的程序实际使用的空间可能更小。

重新部署 Solana程序

可以将程序重新部署到同一地址，以方便快速开发、修复错误或升级。如果未提供程序 ID，则程序将部署到默认地址<PROGRAM_NAME>-keypair.json。此默认密钥对是在第一次程序编译期间生成的。

该命令看起来与部署命令相同：

solana program deploy &lt;PROGRAM_FILEPATH>

默认情况下，程序会部署到与原始程序文件大小匹配的帐户。但是，如果重新部署的程序较大，则重新部署将失败。为避免这种情况，请指定一个max_len至少为程序预期大小（以字节为单位）的（加上一些回旋余地）。

solana program deploy --max-len 200000 &lt;PROGRAM_FILEPATH>

扩展程序

如果已经部署了程序，并且重新部署超出了 max_len帐户的范围，则可以扩展该程序以适应更大规模的重新部署：

solana program extend &lt;PROGRAM_ID> &lt;ADDITIONAL_BYTES>

恢复失败的部署

如果程序部署失败，将有一个挂起的中间缓冲帐户，其中包含非零余额。为了收回该余额，您可以通过向新的调用提供相同的中间缓冲来恢复失败的部署 deploy。

部署失败将打印一条错误消息，指定恢复生成的中间缓冲区的密钥对所需的种子短语：

==================================================================================
Recover the intermediate account's ephemeral keypair file with
`solana-keygen recover` and the following 12-word seed phrase:
==================================================================================
valley flat great hockey share token excess clever benefit traffic avocado athlete
==================================================================================
To resume a deploy, pass the recovered keypair as
the [BUFFER_SIGNER] to `solana program deploy` or `solana program write-buffer'.
Or to recover the account's lamports, pass it as the
[BUFFER_ACCOUNT_ADDRESS] argument to `solana program drain`.
==================================================================================

要恢复密钥对：

solana-keygen recover -o &lt;KEYPAIR_PATH>

当系统询问时，输入 12 个字的种子短语。

然后发出新deploy命令并指定缓冲区：

solana program deploy --buffer &lt;KEYPAIR_PATH> &lt;PROGRAM_FILEPATH>

关闭程序和缓冲区帐户并回收其端口

计划账户和缓冲账户均可关闭，并将其 Lamport 余额转移到收款人的账户中。

如果部署失败，将有一个剩余的缓冲账户用于保存 lamport。缓冲账户可用于恢复部署或关闭。

必须有程序或缓冲账户的权限才能关闭账户，列出所有符合默认权限的打开的程序或缓冲账户：

solana program show --programs
solana program show --buffers

要指定不同的权限：

solana program show --programs --buffer-authority &lt;AUTHORITY_ADDRESS>
solana program show --buffers --buffer-authority &lt;AUTHORITY_ADDRESS>

关闭单个账户：

solana program close &lt;ADDRESS>

要关闭单个帐户并指定与默认权限不同的权限：

solana program close &lt;ADDRESS> --buffer-authority &lt;KEYPAIR_FILEPATH>

要关闭单个帐户并指定非默认收件人：

solana program close &lt;ADDRESS> --recipient &lt;RECIPIENT_ADDRESS>

关闭与当前权限相关的所有缓冲帐户：

solana program close --buffers

显示所有缓冲账户，无论其权限如何

solana program show --buffers --all

设置程序的升级权限

可以在部署期间指定权限：

solana program deploy --upgrade-authority &lt;UPGRADE_AUTHORITY_SIGNER> &lt;PROGRAM_FILEPATH>

或者部署后使用默认密钥对作为当前权限：

solana program set-upgrade-authority &lt;PROGRAM_ADDRESS> --new-upgrade-authority &lt;NEW_UPGRADE_AUTHORITY>

或者部署后并指定当前权限：

solana program set-upgrade-authority &lt;PROGRAM_ADDRESS> --upgrade-authority &lt;UPGRADE_AUTHORITY_SIGNER> --new-upgrade-authority &lt;NEW_UPGRADE_AUTHORITY>

默认情况下，set-upgrade-authority需要新机构的签名。此行为可防止开发人员将升级权限授予他们无权访问的密钥。此--skip-new-upgrade-authority-signer-check 选项放宽了签名者检查。这对于新升级权限是离线签名者或多重签名的情况非常有用。

不可变程序

--final可以通过在部署期间指定标志将程序标记为不可变，从而防止所有进一步的重新部署：

solana program deploy &lt;PROGRAM_FILEPATH> --final

或者之后的任何时间：

solana program set-upgrade-authority &lt;PROGRAM_ADDRESS> --final

将程序转储到文件

已部署的程序可能会被转储回本地文件：

solana program dump &lt;ACCOUNT_ADDRESS> &lt;OUTPUT_FILEPATH>

转储文件将与部署文件相同，因此对于共享对象（程序二进制文件.so），转储文件将是一个功能齐全的共享对象。请注意，该dump命令会转储整个数据空间，这意味着输出文件将在共享对象的数据后保留尾随零，直到max_len。有时，转储和比较程序以确保它与已知程序二进制文件匹配很有用。转储文件可以进行零截断、哈希处理，并与原始程序文件的哈希值进行比较。

$ solana dump &lt;ACCOUNT_ADDRESS> dump.so
$ cp original.so extended.so
$ truncate -r dump.so extended.so
$ sha256sum extended.so dump.so

使用中间缓冲账户

solana program write-buffer &lt;PROGRAM_FILEPATH>

缓冲帐户由权限管理。要创建缓冲区并指定与默认权限不同的权限，请执行以下操作：

solana program write-buffer &lt;PROGRAM_FILEPATH> --buffer-authority &lt;BUFFER_AUTHORITY_SIGNER>

只有缓冲区授权者可以写入缓冲区，因此--buffer-authority上述内容必须是 签名者，而不是地址。此要求限制了离线签名者的使用。要使用离线地址作为缓冲区授权者，必须使用在线密钥对初始化缓冲区帐户并写入，然后必须使用以下方式分配缓冲区授权者 solana program set-buffer-authority：

solana program set-buffer-authority &lt;BUFFER_ADDRESS> --new-buffer-authority &lt;NEW_BUFFER_AUTHORITY>

与程序账户不同，缓冲账户不能标记为不可变，因此它们不支持该--final选项。

缓冲账户一旦完全写入，就可以传递给deploy部署程序：

solana program deploy --program-id &lt;PROGRAM_ADDRESS> --buffer &lt;BUFFER_ADDRESS>

缓冲区也支持show，dump就像程序一样。

使用离线签名者作为权限