运行节点

环境要求

Rust（stable），并安装 wasm32-unknown-unknown target
C++ 工具链和 clang（RocksDB 从源码构建）
运行 gateway 需要 Node.js 18+
构建需要几 GB 的磁盘空间

构建

节点内嵌了两个系统合约，因此要先构建它们：

bash

cd neurochain
rustup target add wasm32-unknown-unknown

for c in nrc20 ncert; do
  (cd contracts/$c && RUSTFLAGS="-C link-arg=--allow-undefined" \
     cargo build --release --target wasm32-unknown-unknown)
done

cargo build -p neurochain-node --bin neurochain        # → target/debug/neurochain

如果跳过合约这一步，节点构建会以 couldn't read …/nrc20.wasm 失败。--allow-undefined 标志让合约的宿主导入能在当前 Rust 版本下完成链接；新合约也可以改为声明 #[link(wasm_import_module = "env")]（参见 NeuroWASM）。

首次构建需要几分钟（RocksDB）；之后的构建只需几秒。本地测试以外的场景请使用 --release。

单个本地节点

bash

CHAIN_ENV=testnet \
NEUROCHAIN_DATA_DIR=./data \
NEUROCHAIN_MODELS_DIR=./models \
NEUROCHAIN_P2P_PORT=30333 \
NEUROCHAIN_RPC_PORT=9933 \
NEUROCHAIN_NODE_ADDR=localhost:30333 \
NEUROCHAIN_MIN_VALIDATORS=1 \
RUST_LOG=neurochain=info \
./target/debug/neurochain

CHAIN_ENV=testnet 会开启水龙头并放宽签名检查，供开发使用。任何正式用途都不要设置它（即采用 mainnet 规则）。
未设置 NEUROCHAIN_GENESIS_VALIDATORS 时，节点会把自己设为唯一的验证者（neuro:node-1.node），并立即开始出块。在 mainnet 规则下它需要一个所有者：将 NEUROCHAIN_VALIDATOR_OWNER 设为运营它的 .human 钱包，否则节点拒绝启动。
NEUROCHAIN_MIN_VALIDATORS=1 会关闭验证者少于 7 个时的警告。

检查节点：

bash

curl -s http://localhost:9933/health
# {"status":"ok","height":6,"validator_count":1,"bft_quorum":1,"bft_ready":false,…}

然后启动 gateway。

多验证者网络

所有验证者都必须从同一个创世配置启动，其中列出了每个验证者及其共识公钥。仓库为本地网络提供了自动化脚本：

bash

cd neurochain
scripts/net-test/net-test.sh keys 4    # 创建 4 个验证者密钥，写入共享的创世验证者集合
scripts/net-test/net-test.sh up 4      # 启动它们（先启动节点 1，其余节点从它引导）
scripts/net-test/net-test.sh check     # 高度一致、持续出块、赞助 gas 一致
scripts/net-test/net-test.sh down

它使用 9941 起的 RPC 端口、30341 起的 P2P 端口，数据放在 .net-test/ 下，因此不会影响普通的 ./data 节点。

手动操作：

为每个验证者创建密钥。 用各自的 NEUROCHAIN_DATA_DIR、NEUROCHAIN_NODE_ADDR 和端口将每个节点启动一次。它会把密钥写入 <data dir>/shard0/bft_key.bin 并输出日志：
```
Consensus validator … — ML-DSA-65 pubkey (put in NEUROCHAIN_GENESIS_VALIDATORS): 6e80bab8…
```
停止节点，删除 <data dir>/shard0/state_rdb 和 <data dir>/shard0/wal。保留 bft_key.bin。
编写创世验证者集合——每个节点使用相同的值：
```
NEUROCHAIN_GENESIS_VALIDATORS='neuro:val1.node|host1:30333|1000000|0.9|<pubkey1>|neuro:<owner1>.human,neuro:val2.node|host2:30333|1000000|0.9|<pubkey2>|neuro:<owner2>.human,…'
```
字段依次为：验证者地址、其 P2P 地址（必须与该节点的 NEUROCHAIN_NODE_ADDR 一致）、以 NRO 计的质押量、初始信任值（仅用于展示）、ML-DSA-65 公钥，以及所有者——运营该验证者的 .human 钱包（资料、解除监禁、质押、佣金）。bft_key.bin 中的共识密钥只用于签署区块，永远不控制验证者的账户。没有公钥的条目会被排除在共识之外；在 mainnet 规则下，没有所有者的条目会使节点在启动时停止。
启动第一个节点，然后用 NEUROCHAIN_BOOTSTRAP=host1:30333 启动其余节点。如果验证者数量少于 7，将 NEUROCHAIN_MIN_VALIDATORS 设为实际的验证者数量。

共识消息通过同一个 P2P 端口传输；没有单独的共识端口。节点通过将 NEUROCHAIN_NODE_ADDR 与创世集合中的 P2P 地址匹配来识别自己是哪个验证者。

创世验证者集合永不改变

之后加入的验证者通过注册 .node 并质押来加入（参见质押）；他们不会修改 NEUROCHAIN_GENESIS_VALIDATORS。使用不同创世集合或余额启动的节点会拒绝其他节点的区块，并输出日志 STATE DIVERGENCE。

Docker Compose

在仓库根目录下：

bash

cp .env.example .env        # 按需修改
docker compose up -d        # 节点、gateway、Web 应用
docker compose --profile monitoring up -d   # 外加 Prometheus 和 Grafana

镜像会分阶段构建合约和节点。节点数据存放在 node1-data 卷中；AI 模型文件以只读方式从 neurochain/models 挂载。

数据目录

路径	内容
`<data dir>/shard<N>/bft_key.bin`	节点的共识与签名密钥——务必备份，切勿泄露
`<data dir>/shard<N>/state_rdb/`	分片 N 的 RocksDB 链状态
`<data dir>/shard<N>/wal/`	共识预写日志，重启后重放

从快照启动

新节点可以从运行中的节点加载签名的状态快照，从而跳过历史重放：

bash

NEUROCHAIN_CHECKPOINT_URL=http://trusted-node:9933 ./target/debug/neurochain

在空数据目录上，节点会获取 /api/v1/state/snapshot，应用它，然后从该高度开始追赶。快照会暴露所有余额和质押；请用 NEUROCHAIN_SNAPSHOT_TOKEN 保护该端点（客户端随后需发送 Authorization: Bearer <token>）。

暴露范围与 TLS

在 mainnet 规则下 RPC 监听 localhost，在 CHAIN_ENV=testnet 下监听 0.0.0.0；可通过 NEUROCHAIN_RPC_HOST 指定。
设置 NEUROCHAIN_TLS_CERT 和 NEUROCHAIN_TLS_KEY（PEM 路径）即可通过 HTTPS 提供 RPC。
面向用户的应是 gateway，而不是节点。
NEUROCHAIN_INTERNAL_TOKEN 通过 X-Internal-Token 请求头保护内部端点（oracle 日志写入、AI 数据导出）。

监控

GET /metrics 提供 Prometheus 指标：

指标	含义
`nc_block_height`, `nc_bft_round`	链的进度
`nc_bft_validators_active`, `nc_bft_quorum_size`	验证者集合
`nc_peer_count`, `nc_mempool_size`, `nc_tx_total`	网络与负载
`nc_total_staked`, `nc_base_fee`, `nc_fees_burned`	经济指标（金额以 uNRO 计）
`nc_deploy_rejected_total{rule_id}`	被 VMGuardian 拒绝的部署，按规则统计
`nc_model_active_count`, `nc_model_voting_count`, `nc_model_version{…}`, `nc_model_confirms_needed`, `nc_model_voting_deadline_remaining_blocks`	AI 模型注册表
`nc_sentinel_flagged_total{category}`, `nc_sentinel_held_total`, `nc_sentinel_released_total{how}`	Sentinel

monitoring/ 中包含 Prometheus 抓取配置和预置的 Grafana 仪表盘，并带有针对内存池过大、对等节点少于 2 个以及部署被集中拒绝的告警。

备份与恢复

bash

./scripts/backup.sh [data_dir] [backup_dir]     # 在线复制；节点继续运行
./scripts/restore.sh <backup_dir> [data_dir]    # 先停止节点

备份中包含 bft_key.bin——请像保管密钥本身一样安全地保管备份。

值得了解的日志

日志行	含义
`consensus decided, committing height=…`	一个区块已最终确定
`Below minimum: n/7 active validators`	验证者数量少于 `NEUROCHAIN_MIN_VALIDATORS`
`STATE DIVERGENCE`	本节点的状态与提议者的不一致；在问题解决前它拒绝投票
`genesis validator(s) missing ML-DSA pubkey`	创世集合中有条目缺少公钥，已被排除

全部变量：环境变量。

运行节点 ​

环境要求 ​

构建 ​

单个本地节点 ​

多验证者网络 ​

Docker Compose ​

数据目录 ​

从快照启动 ​

暴露范围与 TLS ​

监控 ​

备份与恢复 ​

值得了解的日志 ​

运行节点

环境要求

构建

单个本地节点

多验证者网络

Docker Compose

数据目录

从快照启动

暴露范围与 TLS

监控

备份与恢复

值得了解的日志