Linera 应用部署实战指南：从本地网络到 Testnet 的完整流程

本篇技术指南以 Linera 协议官方后端文档为核心，系统讲解如何将基于 linera-sdk 编写的 Wasm 应用部署到本地网络、Devnet 与 Testnet，涵盖钱包配置、publish-and-create 命令的完整参数解析，以及通过 Node Service 与 GraphQL 与应用交互的实战方法。读完本文，你将掌握从构建合约字节码、发布链上应用到查询应用状态的全套部署技能，并理解其底层源码调用链。

部署前准备：先配置一个可用的钱包

在 Linera 中，部署应用的第一步是配置一个开发者钱包（developer wallet）。钱包决定了应用最终被部署到哪里：本地网络（local net）还是公共部署（Devnet / Testnet）。

钱包由三个核心状态文件组成（详见 钱包概念）：

• wallet.json：钱包的私密状态（包含链 ID、密钥对等）；
• keystore.db（或 keystore.json）：私钥存储；
• wallet.db：钱包内嵌节点的本地状态存储。

linera CLI 默认会按操作系统约定的配置路径查找钱包文件。当需要同时管理多个网络、多套钱包时，建议通过以下三个环境变量显式指定钱包位置（摘自 Hello, Linera）：

DIR=$HOME/my_directory
mkdir -p $DIR
export LINERA_WALLET="$DIR/wallet.json"
export LINERA_KEYSTORE="$DIR/keystore.json"
export LINERA_STORAGE="rocksdb:$DIR/wallet.db"

设置好这三个环境变量后，publish-and-create 命令即可直接使用该钱包作为发布目标。之所以要"一个网络一套钱包"，是因为钱包始终与其创建时的网络绑定：本地网络每次重启后，旧钱包都必须删除并重新创建。

提示：开发阶段由 linera CLI 操作的钱包仅用于测试与开发。生产环境的用户钱包通常由浏览器扩展、移动应用或硬件设备管理。

部署到本地网络

1. 启动本地开发网络

使用 linera net up 启动一个本地验证器网络（可同时启动 faucet）：

linera net up --with-faucet --faucet-port 8080

该命令会启动一个带默认分片数量的验证器，并拉起一个 faucet 服务。

2. 初始化本地钱包

在另一个终端中，通过本地 faucet 创建钱包并申请一条新的微链：

linera wallet init --faucet http://localhost:8080
linera wallet request-chain --faucet http://localhost:8080

详细步骤参见 Getting Started 的 Hello, Linera 章节。

3. 编译应用为 Wasm 字节码

Linera 应用以 WebAssembly 字节码形式运行，每个验证器和客户端都内置了 Wasm 虚拟机。以官方 counter 示例为例（源码位于 examples/counter）：

cd examples/counter && cargo build --release --target wasm32-unknown-unknown

在 examples/counter/Cargo.toml 中可以看到，合约与服务分别被编译为两个独立的二进制：

[[bin]]
name = "counter_contract"
path = "src/contract.rs"

[[bin]]
name = "counter_service"
path = "src/service.rs"

因此构建产物会形如 target/wasm32-unknown-unknown/release/counter_{contract,service}.wasm。

4. 发布并创建应用

使用 publish-and-create 一次性完成"发布字节码 + 创建应用实例"，需要指定三样东西：

1. 合约字节码（contract bytecode）的位置；
2. 服务字节码（service bytecode）的位置；
3. JSON 编码的初始化参数（instantiation argument）。

linera publish-and-create \
  target/wasm32-unknown-unknown/release/my_counter_{contract,service}.wasm \
  --json-argument "42"

其中 {contract,service} 是 shell 的花括号展开语法，等价于分别传入 my_counter_contract.wasm 与 my_counter_service.wasm；--json-argument "42" 表示以数字 42 作为应用初始状态。

部署到 Devnet / Testnet

公共测试网络的部署流程与本地网络几乎一致，区别仅在于钱包的获取方式：通过公共 faucet 获取钱包与代币，而不是本地 faucet。

1. 通过 faucet 初始化钱包并申请微链

linera wallet init --faucet https://faucet.{{RELEASE_DOMAIN}}.linera.net
linera wallet request-chain --faucet https://faucet.{{RELEASE_DOMAIN}}.linera.net

{{RELEASE_DOMAIN}} 是文档模板变量，在 docs/RELEASE_DOMAIN 中定义，当前仓库对应的值为 testnet-conway，即完整 faucet 地址为 https://faucet.testnet-conway.linera.net。

第一步 wallet init --faucet 会初始化钱包并与当前 Testnet 的验证者网络建立连接；第二步 wallet request-chain --faucet 向 faucet 申请一条新的微链。Faucet 会为新链注入一些代币，这些代币可用于后续部署应用（即支付部署应用时产生的链上费用）。如果命令报错，请确认本地 linera 工具链版本与当前 Testnet 兼容（参考 安装指南）。

2. 发布并创建应用

拿到代币后，即可使用与本地网络完全相同的 publish-and-create 命令部署应用：

linera publish-and-create \
  target/wasm32-unknown-unknown/release/my_counter_{contract,service}.wasm \
  --json-argument "42"

publish-and-create 命令深度解析

为了让部署命令"可复制、可调参"，这里结合源码给出 publish-and-create 的完整参数说明。命令定义位于 linera-service/src/cli/command.rs，支持以下参数：

参数	说明	默认值
path	Linera 项目根目录路径，用于定位字节码文件	当前工作目录
name	项目名，用于定位生成的字节码文件（格式为 <name>_{contract,service}.wasm）	Cargo.toml 中的包名（- 替换为 _）
publisher	发布模块的链 ID，不指定则使用钱包默认链	钱包默认链
--vm-runtime	使用的虚拟机运行时	wasm
--json-parameters	共享参数（JSON 字符串）	无
--json-parameters-path	包含共享参数的 JSON 文件路径	无
--json-argument	实例化参数（JSON 字符串）	无
--json-argument-path	包含实例化参数的 JSON 文件路径	无
--required-application-ids	该应用所依赖的其他应用 ID 列表（可多个）	无

补充说明：--json-parameters 用于传递应用的共享参数（同一字节码的多个应用实例可共用），而 --json-argument 用于传递该实例的初始化参数。若参数较长，可改用 --json-parameters-path / --json-argument-path 指向 JSON 文件，避免 shell 转义问题。

从源码调用链看，publish-and-create 实际是把合约字节码、服务字节码、VM 运行时、JSON 参数与 JSON 参数全部序列化后，组装成一条部署事务提交到指定链上。测试工具封装位于 linera-service/src/cli_wrappers/wallet.rs：它先构造 linera publish-and-create <contract> <service> --vm-runtime <runtime> --json-parameters <params> --json-argument <arg> 命令，若有依赖应用则追加 --required-application-ids，命令成功后在 stdout 输出新创建的 ApplicationId。该封装被集成测试广泛使用，例如 linera-service/tests/local_net_tests.rs 中通过它部署 fungible 应用并传入 Parameters 与 InitialState 两个 JSON 结构，验证了"编译示例 → 发布 → 创建应用 → 基准测试"的完整链路。

与已部署应用交互：Node Service 与 GraphQL

部署完成后，需要通过 Node Service（节点服务）与应用交互。运行 linera service 即可让客户端进入服务模式：

linera service --port 8080

从源码看，linera-service/src/cli/main.rs 中 Service 模式要求钱包存在默认链（否则报错 "Service requires a default chain in the wallet"），随后会启动一个本地 GraphQL 服务。节点服务承担三个职责（详见 Node Service 概念）：

1. 执行区块（executes blocks）；
2. 暴露 GraphQL API 与 IDE（GraphiQL），用于动态与应用和系统交互；
3. 监听验证器通知并自动同步本地链。

通过 GraphiQL 查询应用

服务启动后，在浏览器中访问 http://localhost:8080 即可打开 GraphiQL IDE。首先查询默认链上部署的应用列表：

query {
  applications(chainId: "...") {
    id
    description
    link
  }
}

其中 chainId 替换为 linera wallet show 显示的默认链 ID。返回 JSON 中的 link 字段指向该应用的专属 GraphQL 端点（形如 http://localhost:8080/chains/<chain-id>/applications/<application-id>），把该链接复制到新标签页打开，即可查询应用状态。对 counter 应用，查询当前计数值：

query {
  value
}

会返回 42——即部署时通过 --json-argument "42" 传入的初始化参数。

系统级 GraphQL API

Node Service 同时暴露系统操作对应的 GraphQL API，点击 GraphiQL 左侧的 MutationRoot 可浏览全部系统级操作，可用于链管理、跨链消息等操作。

部署流程总结与常见问题

完整部署流程一览：

阶段	本地网络	Devnet / Testnet
启动网络	linera net up --with-faucet	无需（使用公共网络）
配置钱包	LINERA_WALLET / LINERA_STORAGE / LINERA_KEYSTORE 环境变量	同左
获取链与代币	wallet init + request-chain（指向 http://localhost:8080）	wallet init + request-chain（指向公共 faucet）
构建字节码	cargo build --release --target wasm32-unknown-unknown	同左
部署应用	publish-and-create <contract> <service> --json-argument "<init>"	同左
交互查询	linera service --port 8080 + GraphiQL	同左

常见问题与注意事项：

• 钱包与网络生命周期绑定：钱包仅在所属网络的生命周期内有效。本地网络每次重启后，必须删除并重新创建钱包（包括清空 LINERA_WALLET / LINERA_STORAGE / LINERA_KEYSTORE 指向的文件）。
• 版本兼容：访问公共 Testnet 失败时，请检查 linera 工具链版本是否与当前 Testnet 兼容（参考 安装指南）。
• 多钱包切换：可通过 linera --wallet <file> --keystore <file> --storage rocksdb:<file> 参数或环境变量在多套钱包间切换；定义 LINERA_WALLET_$I / LINERA_KEYSTORE_$I / LINERA_STORAGE_$I 后，可用 linera --with-wallet $I（简写 -w $I）快速切换。
• 发布者指定：不带 publisher 参数时，应用发布到钱包默认链；需要发布到指定链时，在 publish-and-create 后追加链 ID 参数。

至此，你已经掌握了在本地网络与 Testnet 上部署 Linera 应用的完整链路：配置钱包 → 获取微链与代币 → 编译 Wasm 字节码 → publish-and-create 发布 → 通过 Node Service 的 GraphiQL 查询应用状态。若需继续深入，可参阅 应用开发、微链模型 与 钱包管理 等章节。