管理容器智能合约

如果您按照链接中的教程尝试使用 DFINITY Canister Software Development Kit (SDK):tutorials-intro.html[Tutorials] 部分或通过从链接克隆示例link:https://github.com/dfinity/ examples[examples] 存储库，您已经熟悉如何将程序构建和部署为容器智能合约。 本节提供有关容器生命周期以及如何管理容器的附加信息。

获取容器智能合约标识符

根据您首选的开发工作流程，您可以在准备好编译程序之前或之后获取容器智能合约的唯一标识符。 例如，如果您想在编写任何代码之前在子网上为您的容器智能合约保留一个唯一标识符，您可以通过运行`dfx canister create` 命令来实现。 此命令实质上创建了一个空容器占位符，您以后可以在其中安装代码。 生成的容器将获得一个唯一标识符。

要获取容器的唯一标识符:

  1. 在本地计算机上打开一个新的终端窗口或选项卡。

  2. 通过运行类似于以下内容的命令，为您计划创建的容器创建一个新项目:

    dfx new YOUR-PROJECT-NAME

    请注意，您用于项目的名称也默认用作容器名称。

  3. 切换到您的新项目目录。

  4. 打开 dfx.json 配置文件并为您要使用的容器执行环境（例如 Internet Computer 区块链）设置主机和端口。

    如果您使用的是本地部署，则可以跳过此步骤。

    如果您想在编译代码之前为您认为需要的任何其他容器创建标识符，您还可以选择更改容器的名称或将容器设置添加到配置文件中。

  5. 如有必要，通过运行以下命令启动本地容器执行环境:

    dfx start --background

    在大多数情况下，仅当您在本地运行容器时才需要此步骤。

    如果您正在注册容器以在远程执行环境中运行，例如 Internet Computer 区块链，您将包括 --network 命令行选项以在此参数下指定的环境中执行任务。

  6. 通过运行以下命令为在 dfx.json 中定义的容器注册唯一标识符:

    dfx canister create --all

    该命令创建 .dfx/local 目录并将 +canister is.json 文件添加到该项目的目录中。

使用本地标识符构建容器智能合约

为项目编写源代码后，需要将其编译为 WebAssembly 模块，然后再将其部署为容器。

如果您只是为了本地调试而编译您的项目，您可以为您的项目生成一个本地定义的标识符。

要生成本地定义的标识符:

  1. 使用配置设置和程序逻辑创建一个项目以满足您的需求。

  2. 如有必要，启动本地容器执行环境。

    如果您正在编译容器以在远程执行环境中运行，例如 Internet Computer 区块链，您将包括 --network 命令行选项以在此参数下指定的环境中执行任务。

  3. 通过运行以下命令，为在 dfx.json 中定义的容器生成硬编码的本地标识符:

    dfx build --check

    请注意，您必须先注册唯一容器标识符以替换本地定义的标识符，然后才能在 Internet Computer 区块链上部署项目。

部署容器智能合约

编译程序后，您可以将编译后的代码安装在容器智能合约中，该合约在本地容器执行环境或 Internet Computer 区块链上运行。

预先或在构建过程中创建的容器标识符决定了您的代码在部署过程中的安装位置。

首次部署代码:

  1. 打开一个新终端并导航到您的项目目录。

  2. 如有必要，启动本地容器执行环境。

    在大多数情况下，仅当您在本地运行容器时才需要此步骤。

    如果您正在注册容器以在远程执行环境中运行，例如 Internet Computer 区块链，您将包括 --network 命令行选项以在此参数下指定的环境中执行任务。

  3. 验证您具有要部署的所有容器的容器标识符。

  4. 通过运行以下命令部署所有容器:

    dfx canister install --all

查找容器智能合约标识符

所有容器都有唯一标识符。 您经常需要使用这些标识符与容器交互。 例如，如果您想访问 dapp 的前端容器或使用 Candid Web 界面与服务交互，则必须指定适当的容器标识符。

因为标识符特定于容器部署的环境，所以用于存储信息的文件位于不同的目录中。 例如，本地部署的容器的标识符位于项目的 .dfx/local/canister_ids.json 文件中。

您可以通过运行 dfx canister id 命令来查找任何特定容器的容器标识符。 例如，要查找部署在本地容器执行环境中的 lookup 容器的容器标识符，您可以运行以下命令:

dfx canister id lookup

要查找部署在由 ic 别名指定的环境中的同一容器的容器标识符，您将运行以下命令:

dfx canister --network=ic id lookup

为现有的容器智能合约添加钱包

当您进行本地开发时，创建一个新项目会自动创建一个默认钱包，供您与该项目中的容器一起使用。 如果你想为之前创建的容器添加一个钱包，你可以通过几个手动步骤强制“dfx”生成一个。

要添加用于现有容器的钱包:

  1. 打开终端并导航到您的项目目录。

  2. 如有必要，通过运行以下命令停止本地容器执行环境:

    dfx stop

  3. 删除`.dfx`目录。

  4. 通过运行以下命令启动本地容器执行环境网络:

    dfx start --clean

重新安装容器智能合约

在开发周期中，您可能希望安装，然后在调试和改进程序时替换您的程序。

在这种情况下，您可能希望保留已注册的容器标识符，但不保留任何容器代码或状态。 例如，您的容器可能只有您不想保留的测试数据，或者您可能已决定完全更改程序但想要在您用于安装先前程序的容器标识符下重新安装。

要重新安装容器:

  1. 打开一个新终端并导航到您的项目目录。

  2. 如有必要，启动本地容器执行环境。

    在大多数情况下，仅当您在本地运行容器时才需要此步骤。

    如果您正在注册容器以在远程执行环境中运行，例如 Internet Computer 区块链，您将包括 --network 命令行选项以在此参数下指定的环境中执行任务。

  3. 验证您具有要重新部署的所有容器的容器标识符。

  4. 通过运行以下命令重新部署所有容器:

    dfx canister install --all --mode reinstall

请注意，您可以使用 reinstall 模式替换任何容器，无论容器是否具有与其关联的代码或状态。

设置身份以拥有容器智能合约

在大多数情况下，当您第一次运行 dfx canister create 命令时，会自动为您创建一个 default 用户身份。 此默认身份由为您的本地用户帐户生成的公钥和私钥对组成。 通常，这个 default 身份也是您创建的所有项目和部署的所有容器的默认所有者。 但是，您可以主动创建和使用您选择的身份来规避“default”用户身份的使用。

例如，以下场景说明了创建“registered_owner”身份，然后用于注册、构建、部署和调用“pubs”项目。

为项目设置标识:

  1. 通过运行以下命令创建一个新项目:

    dfx new pubs

  2. 通过运行以下命令切换到项目目录:

    cd pubs

  3. 通过运行以下命令在后台启动本地容器执行环境:

    dfx start --background

  4. 通过运行以下命令创建一个新的 registered_owner 身份:

    dfx identity new registered_owner

  5. 通过运行以下命令将活动用户上下文设置为使用 registered_owner 身份:

    dfx identity use registered_owner

  6. 通过运行以下命令为项目注册、构建和部署容器:

    dfx canister create --all
dfx build --all
dfx canister install --all

    这些命令使用 registered_owner 身份运行，使该用户成为部署的容器的所有者。

  7. 通过运行以下命令调用 greet 函数以验证部署是否成功:

    dfx canister call pubs greet '("Sam")'

管理容器智能合约的运行状态

部署容器后，它可以开始接收和处理来自用户和其他容器的请求。 可用于发送请求和接收回复的容器被视为处于 Running 状态。

尽管默认情况下容器通常处于运行状态，但在某些情况下，您可能希望暂时或永久停止容器。 例如，您可能希望在升级之前停止容器。 停止容器有助于确保正确处理任何正在进行的并且需要运行完成或回滚的消息。 作为删除容器的先决条件，您可能还希望停止容器以彻底清除其消息队列。

您可以通过运行 dfx canister status 命令查看所有容器或指定容器的当前状态。 例如，要查看在本地容器执行环境中运行的所有容器的状态，您可以运行以下命令:

dfx canister status --all

如果容器当前正在运行，此命令将返回类似于以下内容的输出:

…… 容器 status_check 的状态为 Running。 容器 status_check_assets 的状态为 Running。 ……

您可以通过运行 dfx canister stop 命令停止当前正在运行的容器。

dfx canister stop --all

此命令显示类似于以下内容的输出:

容器状态检查的停止代码，容器 ID 为 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaaa-aaaaa-q
容器 status_check_assets 的停止代码，带有 canister_id cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q

如果您要重新运行 dfx canister status 命令，您可能会看到状态为 Stopped 表示没有待处理的消息需要处理，或者状态为 Stopping 表示有消息在- 需要解决的航班。

要重新启动容器（例如，在容器升级成功后），您可以运行 dfx canister start 命令。 例如，要重新启动所有容器，您将运行以下命令:

dfx canister start --all

此命令显示类似于以下内容的输出:

容器状态检查的起始代码，容器 ID 为 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
容器 status_check_assets 的起始代码，带有 canister_id cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaaa-aaaaa-q

升级容器智能合约

与保留容器标识符但不保留状态的容器重新安装不同，容器升级使您能够保留已部署容器的状态并更改代码。

例如，假设您有一个管理专业资料和社交关系的 dapp。 如果您想向 dapp 添加新功能，您需要能够更新容器代码而不会丢失任何先前存储的数据。 容器升级使您能够使用程序更改更新现有容器标识符，而不会丢失程序状态。

注意:要在升级用 Motoko 编写的容器时保留状态，请务必使用 stable 关键字来标识要保留的变量。有关在 Motoko 中保留变量状态的更多信息，请参阅稳定变量和升级方法。 如果你正在升级一个用 Rust 编写的容器，你应该使用 pre_upgrade 和 post_upgrade 函数，如链接所示link:https://github.com/dfinity/cdk-rs/blob/master/examples/asset_storage /src/asset_storage_rs/lib.rs[Rust CDK 资产存储] 示例，以确保在容器升级后正确保留数据。

要升级容器:

如有必要，启动本地容器执行环境。

+ 在大多数情况下，仅当您在本地运行容器时才需要此步骤。

+ 如果您正在注册容器以在远程执行环境中运行，例如Internet Computer 区块链，您将包括 --network 命令行选项以在此参数下指定的环境中执行任务。 .验证您具有要升级的所有容器的容器标识符。

+ 请注意，您的程序必须通过在变量声明中使用 stable 关键字来标识要为其维护状态的变量。

+ 有关声明稳定变量的更多信息，请参阅_Motoko 编程语言指南_。 .通过运行以下命令升级所有容器:

+

dfx canister install --all --mode upgrade

删除容器智能合约

如果要永久删除给定部署（本地或远程）上特定项目的特定容器或所有容器，可以通过运行`dfx canister delete` 命令来实现。

删除容器会移除容器标识符、代码和状态。 但是，在您可以删除容器之前，您必须先停止容器以清除任何待处理的消息请求或回复。

要删除项目的所有容器:

如有必要，启动本地容器执行环境。

+ 在大多数情况下，仅当您在本地运行容器时才需要此步骤。

+ 如果您要删除容器以在远程执行环境中运行，例如Internet Computer 区块链，您将包括 --network 命令行选项以在此参数下指定的环境中执行任务。 .通过运行以下命令检查在本地容器执行环境中运行的项目容器的状态:

+

dfx canister status --all

  1. 通过运行以下命令停止所有项目容器:

    dfx canister stop --all

  2. 通过运行以下命令删除所有项目容器:

    dfx canister delete --all