1. 为什么你需要一个自己的以太坊私有链？

如果你刚开始接触以太坊智能合约开发，可能有过这样的经历：在公共测试网上部署一个合约，光是等待交易确认就花了好几分钟，调试起来更是麻烦，每次调用都得消耗测试币。更别提想研究一下区块生成、Gas消耗这些底层细节了，在庞大的公链数据面前，简直无从下手。几年前我刚入门的时候，也总被这些问题困扰，直到我开始在本地搭建自己的以太坊私有链，整个开发和测试体验才有了质的飞跃。

简单来说，一个私有链就是完全由你掌控的、独立于以太坊主网和公共测试网的迷你区块链网络。它运行在你的个人电脑或者服务器上，所有的节点、区块生成规则、初始账户和余额，都由你说了算。这听起来可能有点复杂，但用起来却异常简单和高效。想象一下，你有一个专属的、无限供应的“沙盒”，在这里，你可以瞬间挖出以太币，可以随意回滚交易状态，可以零成本、零延迟地测试任何复杂的合约逻辑。这对于开发者来说，尤其是进行合约功能验证、DApp前端联调和学习以太坊核心机制，简直是不可或缺的利器。

而 Geth，作为以太坊生态中最主流、最成熟的执行客户端，就是我们搭建这个私有沙盒的“瑞士军刀”。它用Go语言编写，性能强劲，功能全面，更重要的是，它提供了极其友好的开发者模式（--dev）和丰富的配置选项，让我们能在几分钟内就拉起一个可用的私有链节点。搭建好之后，我们还需要一个“遥控器”来指挥这个节点，这就是 JSON-RPC接口。通过它，你可以用任何熟悉的编程语言（比如JavaScript、Python）发送HTTP请求，来查询区块链状态、发送交易、调用合约函数，这构成了DApp与区块链交互的基石。

所以，这篇文章的目的，就是手把手带你走完从零搭建Geth私有链，到配置并熟练使用JSON-RPC接口的完整流程。我会把我自己踩过的坑、总结的最佳实践都揉进去，确保你跟着做一遍，就能拥有一个强大、顺手的本地以太坊开发环境。我们不仅要把链跑起来，更要理解每个参数背后的意义，知道怎么去“玩转”它。

2. 动手之前：理清概念与准备工具

在开始敲命令之前，我们花点时间把几个核心概念捋清楚，这样后面操作时你会更加心中有数。很多人一上来就照着教程复制粘贴，结果遇到报错就懵了，根本不知道从何查起。我们先打好基础。

2.1 以太坊客户端：执行层与共识层

自从以太坊完成了“合并”（The Merge），它的架构就变得更加清晰，分成了两个主要部分：执行层和共识层。你可以把它们想象成一家公司的“业务部门”和“决策委员会”。

  • 执行客户端（Execution Client）：这就是“业务部门”，负责处理具体的“业务”——也就是交易和智能合约。它验证一笔交易是否有效（比如签名对不对、账户余额够不够），然后执行交易中包含的智能合约代码，更新区块链的状态。我们本文的主角 Geth，就是执行客户端中最流行的一个，其他还有像Nethermind、Besu等。
  • 共识客户端（Consensus Client）：这是“决策委员会”，负责决定哪个区块能被添加到链上，维护网络的安全与一致性。它运行权益证明（PoS）算法，协调验证者来提议和投票确认新区块。

对于我们搭建私有链来说，尤其是在开发测试场景下，事情就简单多了。我们通常只关心“业务”部分，也就是执行层。Geth的开发者模式（--dev）已经内置了一个简化的共识机制，可以自动、快速地出块，所以我们暂时不需要单独部署一个复杂的共识客户端。这大大降低了入门门槛。

2.2 Geth：你的私有链核心引擎

Geth的全称是Go Ethereum，顾名思义，它是用Go语言实现的以太坊协议。你可以把它理解为一个功能强大的区块链节点软件。当你运行Geth时，它就会启动一个以太坊节点，这个节点可以连接公网、测试网，或者像我们即将做的那样，运行一个孤立的私有网络。

它提供了命令行界面（CLI），我们通过输入各种命令和参数来指挥它工作。除了最核心的启动节点功能，Geth还附带了一系列非常实用的工具，比如：

  • geth attach: 连接到运行中节点的JavaScript控制台，可以直接交互式地执行操作。
  • puppeth: 一个交互式向导，用来配置更复杂的私有网络（多节点、权限控制等），对于初学者了解网络配置很有帮助。
  • abigen: 这是一个神器，它能将Solidity智能合约的ABI（应用二进制接口）转换为Go语言或其他语言的绑定代码，让你能在Go程序里方便地调用合约。
  • evm: 以太坊虚拟机的独立工具，可以离线执行合约字节码，用于调试。

对于私有链搭建，我们主要使用geth主程序。它的可配置性极高，通过不同的启动参数，我们可以定制出符合我们需求的链。

2.3 JSON-RPC：与你的链对话的桥梁

链搭好了，节点跑起来了，我们怎么和它交互呢？总不能每次都去命令行敲吧。这时就需要JSON-RPC接口。RPC（远程过程调用）是一种技术，允许一个程序（比如你的DApp前端）调用另一个地址空间（通常是另一台机器上的Geth节点）里的函数或方法。

JSON-RPC就是用JSON格式来编码这些调用请求和响应结果的RPC协议。因为它基于HTTP，所以非常简单通用。你的网页JavaScript、后端的Python/Java程序，都可以通过发送一个HTTP POST请求到Geth节点的指定端口（比如8545），来执行诸如eth_getBalance（查询余额）、eth_sendTransaction（发送交易）这样的操作。

Geth启动时，通过--http等参数开启这个HTTP-RPC服务器，并设置好监听的端口和允许访问的地址。之后，你的应用程序就能像调用本地API一样，与远端的区块链节点进行交互了。这是所有以太坊DApp前端（如使用web3.js或ethers.js）与区块链后端通信的标准方式。

准备工作：

  1. 操作系统：Windows, macOS, 或 Linux 均可。本文命令以Windows为例，Mac/Linux用户只需注意文件路径和终端使用的差异。
  2. 下载Geth：访问以太坊官方网站的下载页面，找到最新稳定版的Geth。建议选择包含所有工具（通常标注为“Geth & Tools”）的安装包或归档文件。对于Windows用户，直接下载.exe安装程序或者.zip压缩包最方便。
  3. 安装/解压：如果下载的是安装程序，直接运行安装。如果下载的是压缩包（如geth-windows-amd64-1.x.x-xxxxxxx.zip），将其解压到一个你容易找到的目录，比如D:\Ethereum\Geth。解压后你会看到geth.exe以及其他工具的可执行文件。

好了，概念理清了，工具也备好了，接下来我们就进入最激动人心的实操环节——创建并启动我们的第一条私有链。

3. 从零到一：启动你的第一个Geth私有链节点

现在，我们打开命令行终端，进入到存放geth.exe的目录。我将带你逐行解析启动命令，确保你不仅知道怎么用，更明白为什么这么用。

3.1 初始化：创世区块的诞生

任何一条区块链都有它的起点——创世区块。在私有链中，这个区块的规则完全由我们定义。我们需要创建一个名为genesis.json的配置文件。在你喜欢的任意位置（例如，在geth.exe同目录下，或者专门创建一个项目文件夹）新建一个文本文件，命名为genesis.json，然后填入类似以下内容：

{
  "config": {
    "chainId": 12345,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "berlinBlock": 0,
    "londonBlock": 0,
    "ethash": {}
  },
  "difficulty": "0x400",
  "gasLimit": "0x8000000",
  "alloc": {
    "0xYourPreFundedAddressHere": { "balance": "0x200000000000000000000000000000000000000000000000000000000000000" }
  }
}

我来解释几个关键字段：

  • chainId: 这是你私有链的身份证号，一个整数。用来防止一条链上的交易被重复广播到另一条链上。你可以随便设一个，比如12345，只要不和主流网络冲突就行。
  • difficulty: 挖矿难度。在私有链中我们设得非常低（这里0x400很小），这样出块速度极快，便于测试。
  • gasLimit: 每个区块的Gas上限，决定了单个区块能包含多少计算量。这里设得很大，方便测试复杂合约。
  • alloc: 预分配账户。你可以在这里预先给一些地址充入巨额以太币，方便测试。地址需要加上0x前缀，余额用十六进制表示。注意：在实际操作中，我们通常用开发者模式自动创建账户，所以这部分可以留空或删除。

保存好genesis.json文件后，我们使用它来初始化Geth的数据目录。在命令行中执行：

geth --datadir "./my_private_chain_data" init genesis.json
  • --datadir: 指定区块链数据（区块、状态、密钥库等）存放的目录。这里我们创建了一个名为my_private_chain_data的新文件夹。强烈建议为每个私有链项目使用独立的datadir，避免数据混乱。
  • init: 初始化命令，后面跟上创世配置文件路径。

执行成功后，你会看到类似“Successfully wrote genesis state”的提示。这时，my_private_chain_data文件夹里就生成了初始的区块链数据结构。

3.2 启动节点：进入开发者模式

初始化完成后，我们就可以启动节点了。对于开发和测试，最方便的就是使用--dev开发者模式。我们使用一个功能比较完整的启动命令：

geth --datadir "./my_private_chain_data" --dev --dev.period 3 --networkid 12345 --http --http.port 8545 --http.addr 0.0.0.0 --http.corsdomain "*" --http.api "admin,debug,web3,eth,txpool,personal,clique,miner,net" --verbosity 3 console

这条命令有点长，我们拆开看每一个参数的作用：

  • --datadir "./my_private_chain_data": 指向我们刚才初始化好的数据目录。
  • --dev: 核心参数，启用开发者模式。在此模式下，Geth会：
    • 使用一个内存数据库（重启后数据丢失，干净利落）。
    • 自动创建一个预存有大量以太币的开发者账户。
    • 开启自动挖矿（默认有交易时才挖矿，配合--dev.period则定期挖矿）。
    • 关闭对等节点发现，不与任何外部网络连接。
  • --dev.period 3: 设置开发者模式下自动挖矿的出块间隔为3秒。即使没有待处理交易，也会每3秒生成一个空块。这保证了链的状态持续前进，对于需要依赖区块高度的测试很有用。
  • --networkid 12345: 网络标识符，需要和genesis.json里的chainId区分开，但为了方便通常设成一样的。它用于节点间发现和连接。在私有链中，只有networkid相同的节点才能彼此发现。
  • --http: 启用HTTP-RPC服务器。
  • --http.port 8545: RPC服务监听端口，默认就是8545。
  • --http.addr 0.0.0.0: 重要安全提示：127.0.0.1表示只允许本机访问。如果你需要从同一局域网内的其他设备（比如另一台电脑或手机）访问这个RPC接口，可以设置为0.0.0.0。在生产环境或对外暴露的服务器上，务必结合防火墙和身份验证，切勿随意使用0.0.0.0。
  • --http.corsdomain "*": 允许跨域请求的来源域名。"*"表示允许所有域名，这在开发DApp前端时是必需的，因为浏览器页面（通常运行在http://localhost:3000）需要访问RPC接口。同样，生产环境需要严格限制。
  • --http.api: 指定通过HTTP-RPC开放的API模块。这里我们开放了几乎所有常用的模块，包括账户管理personal、交易池txpool、挖矿miner等，方便全面测试。
  • --verbosity 3: 设置日志详细级别（0-5），3能提供比较适中的信息，方便观察节点运行状态。
  • console: 在启动节点的同时，附加一个交互式JavaScript控制台。这样节点启动后，你会直接进入一个>提示符的命令行环境，可以在这里直接操作区块链。

敲下回车，你会看到Geth开始启动，打印出许多日志信息，最后出现Welcome to the Geth JavaScript console!的提示。恭喜你，你的私有链节点已经成功运行，并且你正站在它的“控制中心”！

4. 在私有链上“为所欲为”：账户、交易与挖矿

现在节点跑起来了，控制台也打开了，我们来做一些有趣的事情，感受一下拥有一条私有链的“权力”。

4.1 账户管理与初始资金

在开发者模式下，Geth已经自动创建了一个账户并给了它很多以太币。我们在控制台里检查一下：

// 列出所有账户
> eth.accounts
// 输出类似：["0x7ef5a6135f1fd6a02593eedc869c6d41d934aef8"]

// 查看该账户的余额（单位是wei，1 ether = 10^18 wei）
> eth.getBalance(eth.accounts[0])
// 输出一个非常大的数字，例如：1.157920892373161954235709850e+77

这个余额大得离谱，是开发者模式为了方便测试而设置的。你可以用它来随意进行交易测试，完全不用担心“Gas费”。

我们也可以自己创建新账户：

// 创建一个新账户，会提示你输入密码（在控制台输入不可见），请牢记密码
> personal.newAccount("your_secure_password_here")
// 输出新账户的地址，例如："0x..."

创建后，再用eth.accounts查看，就会发现列表里多了一个地址。但是新账户的余额是0。怎么给它转钱呢？很简单，从那个“土豪”开发者账户转过去就行。

4.2 发送交易与自动挖矿

在开发者模式下，发送交易会被自动打包进区块。我们尝试转账：

// 首先解锁发送方账户（默认的第一个账户），以便签署交易。解锁有时限（这里300秒）。
> personal.unlockAccount(eth.accounts[0], "password", 300)
// 返回 true 表示解锁成功

// 发送1个以太币给新账户。注意单位：web3.toWei 用于转换单位。
> amount = web3.toWei(1, "ether")
> eth.sendTransaction({from: eth.accounts[0], to: eth.accounts[1], value: amount})
// 输出交易哈希，例如："0x..."

// 几乎同时，查看接收方账户余额
> eth.getBalance(eth.accounts[1])
// 输出：1000000000000000000 (即 1 ether)

你会发现，交易几乎是瞬间确认的，余额立刻到账。这就是--dev模式配合--dev.period的威力：它模拟了一个有矿工在持续工作的网络，但出块速度极快，且没有竞争。

4.3 深入控制台：查询链状态

控制台里内置了强大的web3和eth对象，可以查询几乎所有链上信息：

// 查看当前区块号
> eth.blockNumber
// 查看最新区块的详细信息
> eth.getBlock("latest")
// 查看指定交易的信息（使用刚才返回的交易哈希）
> eth.getTransaction("0x...你的交易哈希...")
// 查看当前Gas价格（在私有链上通常很低或为0）
> eth.gasPrice
// 查看当前是否在挖矿（开发者模式下应为true）
> eth.mining

多花点时间在控制台里探索这些命令，你能直观地看到每一笔交易如何改变区块链的状态，这对理解以太坊的工作原理非常有帮助。

5. 配置与使用JSON-RPC接口

控制台虽然强大，但我们的最终目标是要让外部程序能与我们的链交互。这就需要用到已经开启的JSON-RPC接口了。我们离开Geth控制台（输入exit回车），但让节点在后台继续运行（或者新开一个终端窗口，用不带console参数的命令启动节点）。

5.1 使用HTTP工具直接调用RPC

最直接的方式是用curl（命令行工具）或Postman这类API测试工具来调用。RPC调用是一个标准的HTTP POST请求，内容体是JSON格式。

例如，我们查询第一个账户的余额：

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0x7ef5a6135f1fd6a02593eedc869c6d41d934aef8", "latest"],
    "id": 1
  }'

解释一下这个JSON请求体：

  • jsonrpc: 固定为"2.0"。
  • method: 要调用的RPC方法名，这里是eth_getBalance。
  • params: 方法的参数列表。第一个参数是账户地址，第二个参数是区块状态，"latest"表示最新区块。
  • id: 请求ID，用于匹配响应，可以任意设置。

你会收到一个JSON响应，其中的result字段就是余额的十六进制表示。

5.2 在Node.js中使用Web3.js库

在实际的DApp开发中，我们更常用JavaScript库来封装RPC调用。web3.js是最经典的选择。首先，在一个新的Node.js项目中安装它：

npm install web3

然后，可以编写如下脚本：

const Web3 = require('web3');

// 连接到我们的私有链节点
const web3 = new Web3('http://localhost:8545');

async function main() {
    // 获取账户列表
    const accounts = await web3.eth.getAccounts();
    console.log('Accounts:', accounts);

    // 获取第一个账户的余额
    const balance = await web3.eth.getBalance(accounts[0]);
    console.log('Balance of account 0:', web3.utils.fromWei(balance, 'ether'), 'ETH');

    // 发送交易（需要先解锁账户，或在交易中提供私钥签名，这里仅演示）
    // 注意：在私有链测试中，可以通过Geth控制台解锁账户，或使用personal_sendTransaction RPC方法。
    const txHash = await web3.eth.sendTransaction({
        from: accounts[0],
        to: accounts[1],
        value: web3.utils.toWei('0.5', 'ether')
    });
    console.log('Transaction hash:', txHash);
}

main().catch(console.error);

通过web3对象，我们可以用非常直观的异步函数调用来完成所有区块链操作，这比直接写原始的JSON-RPC请求方便太多了。

5.3 安全配置与生产环境考量

在本地开发时，我们为了图方便，使用了--http.addr 0.0.0.0和--http.corsdomain "*"。这在实际部署或对外服务时是极其危险的，相当于把你的节点控制权暴露给了任何人。

对于需要远程访问或更安全的配置，应考虑：

  1. 限制访问地址：尽量使用--http.addr 127.0.0.1，只允许本机访问。如果必须远程访问，使用Nginx等反向代理，并配置IP白名单或防火墙规则。
  2. 精确控制CORS：将--http.corsdomain设置为你的DApp前端的确切域名，例如"http://myapp.com"或"http://localhost:3000"，而不是通配符。
  3. 启用身份验证：Geth支持通过--http.vhosts和--authrpc.*等参数配置JWT令牌认证，这是保护RPC端点更安全的方式。
  4. 使用HTTPS：如果RPC接口需要经过公网，务必配置SSL/TLS证书（--http.tls*参数），对通信进行加密。
  5. 限制开放的API模块：在生产环境，只开放必要的API。例如，如果只是查询，只开放eth, net, web3；如果需要发送交易，再考虑personal（但更推荐使用离线签名方式）。

6. 进阶：多节点私有网络与合约部署测试

单节点私有链对于基础学习和简单测试已经足够。但有时候，我们需要模拟更真实的网络环境，比如测试节点间同步、交易传播，或者进行共识机制的实验。这时就需要搭建一个多节点的私有网络。

6.1 使用Puppeth快速生成网络配置

Geth自带的puppeth工具可以交互式地引导你创建多节点私有网络的配置。它会帮你生成：

  • 统一的genesis.json（创世文件）。
  • 每个节点的静态节点列表（static-nodes.json），用于指定初始连接的对等节点。
  • 甚至可以为每个节点生成带有预存资金的账户和密码文件。

虽然puppeth的交互流程稍显复杂，但它能让你深刻理解一个以太坊网络是如何被“组装”起来的。基本流程是：运行puppeth，输入网络名称，选择“配置新的创世块”，选择共识引擎（对于私有测试网，Clique PoA共识是简单高效的选择），设置预分配账户，最后导出创世文件和节点配置。

6.2 启动多个节点并连接

假设我们有两个节点，NodeA和NodeB。

  1. 为每个节点创建独立的数据目录：./nodeA_data, ./nodeB_data。
  2. 用同一个genesis.json文件初始化两个目录。
  3. 获取NodeA的节点信息（enode地址）。可以在NodeA启动时加上--nodiscover，然后通过控制台的admin.nodeInfo.enode获取。
  4. 在NodeB的数据目录下创建static-nodes.json文件，内容就是NodeA的enode地址。这样NodeB启动时会主动连接NodeA。
  5. 分别启动两个节点，使用不同的端口（--port 30303和--port 30304），并确保它们的networkid相同。

启动后，在任意一个节点的控制台使用admin.peers命令，应该能看到已连接的对等节点信息。之后，你在一个节点上发起的交易，很快就能在另一个节点上查询到，这模拟了真实的网络广播。

6.3 部署与测试智能合约

私有链是测试智能合约的绝佳场所。你可以使用Truffle、Hardhat或Remix等开发框架。

  • 使用Remix IDE：在Remix的“Deploy & Run Transactions”模块中，将“Environment”选为“Web3 Provider”，然后输入你的私有链RPC地址（如http://localhost:8545）。Remix会自动连接上你的节点。编译好合约后，点击部署，交易会发送到你的私有链，并瞬间被确认。你可以在Remix上直接与合约交互，调用其函数。
  • 使用Hardhat：在Hardhat配置文件中，新增一个网络配置，指向你的私有链RPC。然后就可以用npx hardhat run scripts/deploy.js --network myPrivateChain这样的命令来部署合约了。

在私有链上测试合约，你可以肆意妄为：故意触发合约的异常状态、进行压力测试、反复部署和升级，而完全不用担心成本和链上数据污染。我个人的习惯是，任何合约在部署到测试网甚至主网之前，一定要在本地私有链上经过数十甚至上百次的完整流程测试。

搭建和玩弄自己的私有链，是深入理解以太坊的最佳途径之一。从单节点快速测试，到多节点网络模拟，再到通过JSON-RPC接口集成到完整的DApp开发流程中，每一步都充满了实践乐趣。希望这篇详尽的指南能帮你扫清入门障碍，真正把以太坊开发环境握在自己手中。如果在操作中遇到任何问题，多看看Geth启动时的日志输出，那里面通常包含了最直接的线索。祝你开发顺利！

# 以太坊
Logo
天工造物局

北京人形旗下天工造物具身智能开源社区，聚焦具身天工与慧思开物两大平台

更多推荐

deck.gl TripsLayer 出租车轨迹动画示例实战：从示例运行到着色器原理

TripsLayer 是 deck.gl 中用于渲染**随时间流动的轨迹动画**（如出租车行程、物流路径、迁徙路线）的核心图层。本文以仓库中的最小独立示例 [examples/website/trips](https://link.gitcode.com/i/1442af8f442f4cff39ff546e050fceb5) 为骨架，带你完成从安装依赖、启动应用、理解曼哈顿出租车数据格式，到深入

avatar 天工造物局

Foundry Anvil 中 eth_simulateV1 的 Blob 交易与 Blob Gas 字段规范化：原理、实现与测试验证

本篇技术指南以 [anvil-simulate-blob-transactions.md](https://link.gitcode.com/i/3d2ebe227262de169335eb290af80da8) 这条 changelog 条目为起点，深入剖析 Foundry Anvil 对 `eth_simulateV1` RPC 返回结果中 blob（EIP-4844）交易与 blob gas

avatar 天工造物局

LMCache CLI 实战：用 `lmcache kvcache clear` 管理运行中服务的 KV Cache 状态

本文是一份针对 LMCache 官方 CLI 命令 `lmcache kvcache` 的完整技术指南。该命令用于在**运行中的 LMCache 服务（MP HTTP server）**上管理 KV cache 状态，当前提供 `clear` 子命令，用于清空 L1（CPU 内存）层中缓存的全部 KV 数据。读完本文，你将掌握该命令的完整参数体系、退出码语义、终端/JSON/静默三种输出模式，并能

avatar 天工造物局