Aperture — L402 闪电网络反向代理

Aperture 是一个实现 L402 协议的反向代理，可通过 Lightning Network（闪电网络）实现按支付访问 API 的能力。它部署在后端服务之前，在授予客户端访问权限前要求其完成闪电网络微支付。

源码地址：github.com/lightninglabs/aperture

快速上手

# 1. 安装 aperture
skills/aperture/scripts/install.sh

# 2. 生成配置文件（自动连接本地 lnd）
skills/aperture/scripts/setup.sh

# 3. 确保 invoice.macaroon 文件存在（L402 发票创建所必需）
#    若不存在，可使用 macaroon-bakery 技能生成：
skills/macaroon-bakery/scripts/bake.sh --role invoice-only 
    --save-to ~/.lnd/data/chain/bitcoin/mainnet/invoice.macaroon

# 4. 启动 aperture
skills/aperture/scripts/start.sh

# 5. 使用 lnget 测试
lnget -k --no-pay https://localhost:8081/api/test

Aperture 工作原理

1. 客户端通过 Aperture 请求受保护资源
2. Aperture 返回 HTTP 402 状态码，并在 WWW-Authenticate: L402 响应头中携带一个 macaroon 和一张闪电网络发票
3. 客户端支付该发票并获取 preimage（支付原像）
4. 客户端重试请求，携带 Authorization: L402 : 头
5. Aperture 验证令牌有效性，并将请求代理至后端服务

安装

skills/aperture/scripts/install.sh

该脚本将执行以下操作：

• 验证 Go 是否已安装
• 执行 go install github.com/lightninglabs/aperture/cmd/aperture@latest
• 验证 aperture 是否已加入 $PATH

如需手动安装：

go install github.com/lightninglabs/aperture/cmd/aperture@latest

或从源码构建：

git clone https://github.com/lightninglabs/aperture.git
cd aperture
make install

初始化配置

skills/aperture/scripts/setup.sh

该脚本基于配置模板生成 ~/.aperture/aperture.yaml，其中包含合理默认值，并自动探测本地 lnd 节点路径。

可选参数：

# 自定义网络
setup.sh --network testnet

# 自定义 lnd 路径
setup.sh --lnd-host localhost:10009 
         --lnd-tls ~/.lnd/tls.cert 
         --lnd-macdir ~/.lnd/data/chain/bitcoin/mainnet

# 自定义监听端口
setup.sh --port 8081

# 禁用 TLS（仅限开发环境）
setup.sh --insecure

# 禁用鉴权（不强制支付）
setup.sh --no-auth

运行 Aperture

启动

skills/aperture/scripts/start.sh

以后台进程方式启动 aperture，并读取 ~/.aperture/aperture.yaml 配置文件。

可选参数：

start.sh --foreground         # 前台运行
start.sh --config /path/to   # 指定自定义配置路径

停止

skills/aperture/scripts/stop.sh

配置

配置文件路径：~/.aperture/aperture.yaml

发票 Macaroon 要求

Aperture 需要位于配置项 macdir 下的 invoice.macaroon 文件，用于为 L402 挑战生成闪电网络发票。该文件不同于admin.macaroon。若缺失此文件，Aperture 将无法启动，或在客户端请求付费资源时返回错误。

使用 macaroon-bakery 技能生成 invoice macaroon：

skills/macaroon-bakery/scripts/bake.sh --role invoice-only 
    --save-to ~/.lnd/data/chain/bitcoin/mainnet/invoice.macaroon

setup.sh 脚本会在预期路径未找到 invoice.macaroon 时发出警告。

最小化 Agent 配置示例

以下是最简配置，适用于在本地运行 lnd 节点并托管付费接口的 Agent：

listenaddr: "localhost:8081"
insecure: true
debuglevel: "info"
dbbackend: "sqlite"
sqlite:
  dbfile: "~/.aperture/aperture.db"

authenticator:
  network: "mainnet"
  lndhost: "localhost:10009"
  tlspath: "~/.lnd/tls.cert"
  macdir: "~/.lnd/data/chain/bitcoin/mainnet"

services:
  - name: "my-api"
    hostregexp: ".*"
    pathregexp: "^/api/.*$"
    address: "127.0.0.1:8080"
    protocol: http
    price: 100

服务配置说明

每个 services 条目定义一个待保护的后端服务：

services:
  - name: "service-name"
    # 通过 host 正则表达式匹配请求。
    hostregexp: "^api.example.com$"

    # 通过 path 正则表达式匹配请求。
    pathregexp: "^/paid/.*$"

    # 代理目标后端地址。
    address: "127.0.0.1:8080"

    # 协议类型：http 或 https。
    protocol: http

    # 固定价格（单位：satoshi）。
    price: 100

    # 基础层级授予的 macaroon 权限。
    capabilities: "read,write"

    # 令牌过期时间（单位：秒；31557600 = 1 年）。
    timeout: 31557600

    # 免费访问路径白名单（正则表达式）。
    authwhitelistpaths:
      - "^/health$"
      - "^/public/.*$"

    # 按路径粒度设置速率限制（令牌桶算法）。
    ratelimits:
      - pathregexp: "^/api/query.*$"
        requests: 10
        per: 1s
        burst: 20

认证后端

直连 LND

authenticator:
  network: "mainnet"
  lndhost: "localhost:10009"
  tlspath: "~/.lnd/tls.cert"
  macdir: "~/.lnd/data/chain/bitcoin/mainnet"

Lightning Node Connect（LNC）

authenticator:
  network: "mainnet"
  passphrase: "your-pairing-phrase"
  mailboxaddress: "mailbox.terminal.lightning.today:443"

禁用认证

authenticator:
  disable: true

数据库后端

SQLite（推荐用于 Agent 场景）：

dbbackend: "sqlite"
sqlite:
  dbfile: "~/.aperture/aperture.db"

PostgreSQL：

dbbackend: "postgres"
postgres:
  host: "localhost"
  port: 5432
  user: "aperture"
  password: "secret"
  dbname: "aperture"

TLS 配置

# 启用自动 Let's Encrypt 证书。
autocert: true
servername: "api.example.com"

# 或禁用 TLS（仅限开发/本地环境）。
insecure: true

若上述两项均未设置，Aperture 将在 ~/.aperture/ 目录下自动生成自签名证书。

动态定价

可对接 gRPC 定价服务，替代静态定价：

services:
  - name: "my-api"
    dynamicprice:
      enabled: true
      grpcaddress: "127.0.0.1:10010"
      insecure: false
      tlscertpath: "/path/to/pricer/tls.cert"

为 Agent 托管付费内容

一种常见模式是托管其他 Agent 需付费才能访问的信息：

# 1. 启动一个简单的 HTTP 后端提供内容
mkdir -p /tmp/paid-content
echo '{"data": "valuable information"}' > /tmp/paid-content/info.json
cd /tmp/paid-content && python3 -m http.server 8080 &

# 2. 配置 aperture 对其进行保护
skills/aperture/scripts/setup.sh --insecure --port 8081

# 3. 启动 aperture
skills/aperture/scripts/start.sh

# 4. 其他 Agent 可发起支付并获取内容
lnget --max-cost 100 https://localhost:8081/api/info.json

与 lnget 和 lnd 的集成

当三个组件均正常运行时：

# 验证 lnd 是否正在运行
skills/lnd/scripts/lncli.sh getinfo

# 启动 aperture（复用同一 lnd 实例生成发票）
skills/aperture/scripts/start.sh

# 获取付费资源
lnget --max-cost 1000 https://localhost:8081/api/data

# 查看已存储的令牌
lnget tokens list

关键文件路径

故障排查

端口已被占用

修改配置中的 listenaddr 为其他端口，或使用 setup.sh --port 参数指定新端口。

LND 连接被拒绝

确认 lnd 正在运行且钱包已解锁。检查配置中 lndhost、tlspath 和 macdir 是否指向正确的 lnd 实例。

未返回 402 挑战响应

确认请求路径匹配某项服务的 pathregexp，且未落入 authwhitelistpaths 白名单中。同时确保 authenticator.disable 未设为 true。

令牌验证失败

客户端必须精确提交挑战响应中提供的 macaroon，并附带正确的 preimage。请验证该 preimage 是否与付款哈希一致。