运行你自己的网关

验证一条 Label 309 记录，无需向任何人索取什么——不用账号、不用服务器、也不用密钥。发布则是另一半：它要向 Cardano 写入一笔交易，而这会产生手续费。网关就是替你付这笔钱的那一环。它持有为记录做锚定的、已注资的 Cardano 钱包（以及一个存放密封文件的 Arweave 钱包），负责构建并提交交易，追踪它直至确认，再把记录返回出来供独立验证。

多数时候，你会把 SDK 或 CLI 指向别人的网关。但整个后端都是开源的——label-309-gateway，一个 Rust 二进制文件加上 Postgres——所以你完全可以跑自己的。你可以只为自己的应用私下运行一个，也可以作为付费服务为别人运营：它从设计上就是多租户的，一个实例下可容纳许多账号和 API 密钥。本指南会带你从零开始，用参考版 Docker Compose 一路走到第一份带价格的报价。

开始之前

你需要 Docker 和 Docker Compose，以及一台有几个 GB 空闲磁盘的主机。下面的一切都针对 Cardano preprod 网络——这是让部署稳妥上线的做法。切换到主网，是你日后才刻意去做的一步，要等部署完成注资、验证无误之后再进行。

获取代码并写好配置

克隆仓库，然后在 deploy/ 目录下操作——参考版的 docker-compose.yml 就放在那里。复制示例配置，再按你的部署把它改好——网络、手续费区间、存储和定价：

git clone https://github.com/cardanowall/label-309-gateway
cd label-309-gateway/deploy
cp ../gateway.example.toml gateway.toml

这份示例带有注释，而且已经默认指向 preprod，所以第一次跑的时候原样就能启动。

创建密钥环

网关用到的每一把签名密钥，都存在同一个用 age 加密的密钥环文件里。先创建它，再依次加入一把 Cardano 密钥（preprod）、一把 Arweave 密钥，以及一把 webhook-wrap 密钥。这几步 keyring 命令是直接运行 gateway 二进制的——密钥环本就应当在一台可信的机器上创建，只把它加密后的文件拷进容器，所以单单这一步，请从仓库里取一个发布版构建来用。

mkdir -p secrets
printf '%s' 'a-strong-passphrase' > secrets/gateway-keyring-passphrase
export GATEWAY_KEYRING_PASSPHRASE="$(cat secrets/gateway-keyring-passphrase)"

gateway keyring init             --path secrets/gateway-keyring.age
gateway keyring add-cardano      --path secrets/gateway-keyring.age --network preprod
gateway keyring add-arweave      --path secrets/gateway-keyring.age
gateway keyring add-webhook-wrap --path secrets/gateway-keyring.age
chmod 600 secrets/*

每个 add- 步骤都会打印出它刚创建的地址。给打印出的这两个地址注资：Cardano 地址用来支付锚定手续费，Arweave 地址用来为密封文件充值存储额度。然后设置好 compose 会读取的数据库密码：

echo 'POSTGRES_PASSWORD=a-strong-db-password' > .env

启动服务

先把运营方初始化好。这一步会应用数据库迁移，并仅此一次地打印出根密钥——把它妥善存好，这是控制平面的主控凭证：

docker compose run --rm gateway operator bootstrap --label acme

然后启动 Postgres 和网关：

docker compose up -d

注册钱包、账号和密钥

这份 compose 有意不对外暴露任何主机端口：数据平面和控制平面共用同一个套接字，所以一旦暴露端口，控制平面也会跟着暴露。请在容器内部操作控制平面。打开一个 shell：

docker compose exec gateway sh

把 gateway 命令指向本地的控制平面——凭据就用 bootstrap 打印出的那个根密钥——然后注册那个已注资的 Cardano 钱包（也就是 keyring add-cardano 打印出的地址），创建一个账号、给它充值，再签发一把作用域限定为发布的、数据平面的 API 密钥：

export GATEWAY_CONTROL_URL=http://127.0.0.1:8080/control/v1
export GATEWAY_CONTROL_TOKEN='ctl_…the root secret from bootstrap…'

gateway admin wallet register primary addr_test1… preprod
gateway admin account create
gateway admin account fund <account_id> 10000000 "starter credit"   # $10
gateway admin key create <account_id> poe:create,poe:read,account:read

key create 会打印出驱动数据平面的那把 API 密钥。这把密钥，再加上 base URL，就是一个应用所需的全部。

拿下你的第一份报价

搭建阶段若想从主机访问数据平面，请在 docker-compose.yml 里取消对回环 ports 映射（127.0.0.1:8080:8080）的注释，再跑一次 docker compose up -d——只绑回环地址，千万别用 0.0.0.0。然后用你刚签发的那把 API 密钥锁定一个价格：

curl -sS -X POST http://127.0.0.1:8080/api/v1/poe/quote \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"record_bytes":256,"recipient_count":0,"file_bytes_total":0}'

响应里会带上一个有效期 15 分钟的 quote_id，外加一份成本明细。发布调用会在扣减余额的同时，原子性地消费掉这个 quote_id——正是 SDK 指南里那套先锁定价格、再提交的两步流程。你的网关已经上线了。

下一步去哪儿

运行中的二进制本身就提供一份交互式的 API 参考——数据平面在 /api/v1/docs，控制平面在 /control/v1/docs，两者都完全离线渲染。仓库里还有两份更深入的文档：运营方手册讲的是注资、凭证、资金语义和日常运维，集成方指南讲的是如何在它之上打造产品。

你网关的数据平面，正是 SDK 和 CLI 指南里所说的 base URL。把 https://your-gateway.example 换成你如今掌控的地址，把 API 密钥发出去，然后通过一个完全属于你的后端来发布你的第一份 PoE。