Fedimint闪电网络网关

<p align="center"> <img src="images/gateway/gateway_icon.png" alt="Fedimint Lightning Gateway" width="200"> </p>

Lightning Gateway 将 Fedimint 联盟连接到 Lightning Network，使用户能够使用其联盟的电子现金发送和接收闪电支付。本指南涵盖什么是 Gateway、如何部署以及如何运营。

---

什么是 Lightning Gateway？

Lightning Gateway 是一种服务，将 Fedimint 联盟与更广泛的 Lightning Network 连接起来。它使联盟用户能够：

• 接收闪电支付 - Gateway 接收传入的闪电支付，并将接收者的联盟余额记入电子现金
• 发送闪电支付 - Gateway 代表用户支付闪电发票，减少其电子现金余额
• 在联盟间路由 - 单个 Gateway 可以服务多个联盟，促进它们之间的支付
• 赚取费用 - Gateway 通过路由传出或传入支付来赚取费用

<details> <summary><strong>工作原理</strong></summary>

当联盟用户想要接收闪电支付时：

1. 用户加密一个原像，并将其存储在他们希望接收电子现金的联盟中。
2. 用户向 Gateway 请求一张发票。
3. Gateway 使用其闪电节点和用户原像的支付哈希来创建一个 HOLD 发票。
4. 当发票被支付时，Gateway 从联盟购买原像，将电子现金记入用户账户。
5. Gateway 使用解密后的原像完成传入支付。

当联盟用户想要发送闪电支付时：

1. 用户在联盟强制执行的 HTLC 合约中锁定电子现金，并指示 Gateway 支付一张闪电发票。
2. Gateway 使用其闪电节点支付发票，并使用原像索取 HTLC 合约中锁定的电子现金。
3. Gateway 为此服务收取少量费用。

</details>

<details> <summary><strong>关键概念</strong></summary>

• Gateway 运营者 - 运行 Gateway 软件和闪电节点的个人或实体
• 联盟余额 - Gateway 在其服务的每个联盟中持有的电子现金金额
• 流动性 - Gateway 既需要闪电流动性（用于路由支付），也需要电子现金流动性（用于在入站支付中贷记用户）

</details>

---

支持的闪电后端

Gateway 支持两种闪电后端：

<details> <summary><strong>LDK（集成）</strong></summary>

LDK 后端 使用由 LDK Node 驱动的嵌入式闪电节点。

优点：

• 更简单的设置和配置
• 一体化解决方案

最适合：

• 新的 Gateway 运营者
• 希望使用一站式解决方案的运营者
• 小规模部署

</details>

<details> <summary><strong>LND（外部）</strong></summary>

LND 后端 连接到现有的 Lightning Network Daemon (LND) 节点。如果你已经运营一个闪电节点，这是理想的选择。

优点：

• 使用现有的闪电节点和流动性
• 也可以作为路由节点
• 对通道管理有更多控制

最适合：

• 现有的 LND 节点运营者
• 希望利用现有流动性的运营者
• 希望对闪电操作进行细粒度控制的人

</details>

---

部署选项

<details> <summary><strong>Docker</strong></summary>

对于大多数运营者来说，Docker 是推荐的部署方法。仓库中提供了一个即用型的 Docker Compose 配置。

前提条件

• 已安装 Docker 和 Docker Compose
• 一台至少有 1GB RAM 和 10GB 磁盘空间的服务器
• 端口访问：Gateway UI（8176）、Iroh P2P（8177/UDP）和闪电（10010）

快速开始

1. 下载 Docker Compose 文件：

mkdir fedimint-gateway && cd fedimint-gateway
curl -O https://raw.githubusercontent.com/fedimint/fedimint/master/docker/gatewayd/docker-compose.yaml

或者从仓库 docker/gatewayd/docker-compose.yaml 复制。

2. 生成密码哈希：

docker run fedimint/gatewayd:v0.11.1 gateway-cli create-password-hash YOUR_PASSWORD_HERE | sed 's/\$/$$/g'

3. 配置 Gateway：

编辑 docker-compose.yaml，将 FM_GATEWAY_BCRYPT_PASSWORD_HASH 设置为你生成的密码哈希。

4. 启动 Gateway：

docker compose up -d

5. 访问 Gateway UI：

在浏览器中打开 http://localhost:8176。

配置选项

Docker Compose 文件中包含了不同设置的注释配置选项。编辑环境变量以自定义部署：

闪电后端：

• 默认配置使用 LDK 后端（嵌入式闪电节点）
• 要使用 LND，将命令更改为 gatewayd lnd，并取消注释 LND 环境变量（FM_LND_RPC_ADDR、FM_LND_TLS_CERT、FM_LND_MACAROON）

比特币后端：

• 默认配置使用 Esplora（mempool.space）——无需额外设置
• 要使用自己的 Bitcoin Core 节点，注释掉 FM_ESPLORA_URL 并取消注释 Bitcoind 变量（FM_BITCOIND_URL、FM_BITCOIND_USERNAME、FM_BITCOIND_PASSWORD）

查看 docker/gatewayd/docker-compose.yaml 中的注释以获取所有可用选项。

</details>

<details> <summary><strong>Start9</strong></summary>

Start9 提供即插即用的家庭服务器解决方案。Fedimint Gateway 尚未在 Start9 市场中提供，但你可以手动侧载该服务。

安装 Gateway

1. 从 Fedimint Gateway 发布页面 下载最新的 .s9pk 文件（查找 fedimint-gatewayd-vX.Y.Z.s9pk）

2. 打开你的 Start9 仪表板，导航到 系统 > 侧载服务

3. 上传你下载的 .s9pk 文件

4. 等待安装完成

初始配置

安装后，Gateway 将显示“需要配置”状态。点击配置以设置你的 Gateway。

配置 LDK 后端

对于集成的闪电节点：

1. 将后端类型设置为“LDK（集成）”
2. 为你的闪电节点输入一个节点别名（例如，“Fedimint LDK Gateway”）
3. 选择你的比特币后端（如果你在 Start9 上安装了 Bitcoin Core，则推荐使用）
4. 输入一个强Gateway 密码
5. 点击保存

配置 LND 后端

要连接到外部 LND 节点：

1. 将后端类型设置为“LND（外部）”
2. 选择你的比特币后端（如果你在 Start9 上安装了 Bitcoin Core，则推荐使用）
3. 输入一个强Gateway 密码
4. 点击保存

访问 Gateway

配置后，从 Gateway 的服务页面点击启动 UI 以打开 Web 界面。如果你使用的是 LDK，Gateway 需要时间同步。

</details>

<details> <summary><strong>Umbrel</strong></summary>

Umbrel 对 Fedimint Gateway 的支持即将推出。

关注进展：umbrel-apps PR #4554

</details>

---

运营你的 Gateway

部署 Gateway 后，使用 Web UI 管理联盟、监控流动性以及配置设置。

<details> <summary><strong>连接联盟</strong></summary>

要为联盟处理闪电支付，你的 Gateway 必须首先连接到该联盟。

如何连接

1. 从联盟守护者处获取联盟邀请码
2. 在 Gateway UI 中导航到连接一个新联盟部分
3. 将邀请码粘贴到邀请码字段中
4. 点击提交

连接后，你的 Gateway 将拥有该联盟的电子现金钱包。该联盟将出现在仪表板中，余额为零。

恢复联盟连接

如果你要从备份恢复 Gateway，可以恢复你的联盟连接：

单个联盟恢复：

1. 输入联盟邀请码
2. 选中恢复复选框
3. 点击提交

从备份文件批量恢复： 加入联盟后，建议备份所连接的所有联盟的邀请码。可以通过点击导出邀请码来完成。

要从导出的邀请码 JSON 文件恢复：

1. 点击从文件恢复
2. 上传你的 gateway-invite-codes.json 备份文件
3. Gateway 将依次恢复备份中的所有联盟
4. 查看恢复结果，显示哪些联盟已恢复、跳过或失败

</details>

<details> <summary><strong>注册你的 Gateway</strong></summary>

连接到联盟后，你的 Gateway 拥有一个电子现金钱包，但联盟用户尚无法发现它。守护者必须明确注册你的 Gateway 以使其可用。

为什么需要注册

守护者控制哪些 Gateway 可以为其联盟提供闪电服务。这可确保服务质量并保护用户免受不可靠 Gateway 的侵害。

如何注册

1. 在仪表板的Gateway 网络信息卡片中找到你的 Gateway URL
2. 复制 Iroh URL 或 HTTP URL

3. 联系你希望服务的联盟的守护者
4. 向他们提供你的 Gateway URL
5. 守护者将通过其守护者 UI 注册你的 Gateway

</details>

<details> <summary><strong>为联盟提供资金</strong></summary>

你的 Gateway 在每个联盟中需要有电子现金才能处理传入的闪电支付。当用户通过你的 Gateway 接收闪电支付时，你给他们电子现金并保留闪电支付。

支付方向	Gateway 需要什么
传入（用户接收闪电）	给用户的电子现金 + 入站闪电流动性
传出（用户发送闪电）	出站闪电流动性以支付发票

存入比特币换取电子现金

1. 导航到你要注资的联盟卡片
2. 点击存入选项卡
3. 点击新存入地址以生成一个 peg-in 地址

4. 将显示二维码和可复制地址
5. 从任何钱包向此地址发送比特币
6. 等待所需的确认数（通常为 10 个区块，由联盟的 finality_delay 设置）
7. 你的电子现金余额将自动更新

提取电子现金换取比特币

要将资金从联盟提取回链上比特币：

1. 导航到联盟卡片
2. 点击提现选项卡
3. 输入金额（以聪为单位）或选择“全部”
4. 输入目标比特币地址
5. 点击预览以查看费用和交易详情
6. 查看明细：金额、费率、交易大小、提现费、铸币费估算
7. 点击确认提现以执行

直接接收电子现金

你也可以直接接收电子现金票据（带外传输）：

1. 导航到联盟卡片
2. 点击接收选项卡

3. 将电子现金票据粘贴到文本区域
4. 点击接收电子现金
5. 成功兑换后余额立即更新

花费电子现金

要创建用于带外传输的电子现金票据：

1. 导航到联盟卡片
2. 点击花费选项卡
3. 以毫聪为单位输入金额
4. 点击花费
5. 复制生成的电子现金票据字符串
6. 与接收者分享（他们可以在任何 Fedimint 钱包中兑换）

如果联盟启用了铸币费，由于可用票据面额的原因，花费电子现金有时会多花费约 512 毫聪。

</details>

<details> <summary><strong>管理你的闪电节点</strong></summary>

闪电节点卡片提供对 Gateway 闪电操作的完全控制。

连接信息

查看你的闪电节点配置：

• 节点类型 - 外部 LND 或内部 LDK
• 网络 - 比特币主网、signet 或 regtest
• 区块高度 - 闪电节点的比特币区块高度
• 状态 - 已同步、同步中或未连接
• 别名 - 闪电节点的别名
• 公钥 - 闪电节点的公钥
• LND 或 LDK 配置 - 特定于 LND 或 LDK 的连接信息和配置选项

链上钱包

管理闪电节点的链上比特币钱包：

查看余额： 显示当前链上余额（以聪为单位）。

接收比特币：

1. 点击钱包选项卡
2. 点击接收以生成新地址
3. 将显示二维码和可复制地址

发送比特币：

1. 点击钱包选项卡
2. 输入目标比特币地址
3. 输入金额（以聪为单位）或“全部”
4. 输入费率（聪每 vbyte）
5. 点击确认发送

通道管理

查看和管理你的闪电通道：

通道列表：

• 远程对等节点的公钥和别名
• 通道大小和资金输出点
• 活动/非活动状态
• 可视化流动性条，显示出站（绿色）和入站（蓝色）容量

打开通道：

1. 点击通道选项卡
2. 输入远程节点的公钥
3. 输入主机地址（例如 1.2.3.4:9735）
4. 以聪为单位输入通道大小
5. 点击确认打开

关闭通道：

1. 在列表中找到通道
2. 点击 X 按钮
3. 可选地勾选强制关闭（仅在对等节点无响应时使用）
4. 输入费率（聪每 vbyte）
5. 点击确认关闭

闪电支付

直接从你的 Gateway 发送和接收闪电支付：

发送支付：

1. 点击支付选项卡
2. 粘贴 BOLT11 发票或 BOLT12 报价。BOLT12 仅在 LDK 上支持。
3. UI 自动检测支付类型并显示详细信息
4. 对于 BOLT12，可选输入金额和付款人备注
5. 点击发送

接收支付：

1. 点击支付选项卡
2. 输入金额（BOLT12 可选）。BOLT12 仅在 LDK 上支持。
3. 输入可选的描述
4. 点击创建
5. 复制 BOLT11 发票或 BOLT12 报价（每个都有选项卡）
6. 提供二维码以便轻松分享

交易历史

查看过去的闪电交易：

1. 点击交易选项卡
2. 使用日期过滤器，或点击最后一天将过滤器重置为最后一天。
3. 查看支付种类、方向、状态、金额和时间戳
4. 展开条目以查看支付哈希和原像详情

注意 此交易列表将包含此节点发送/接收的所有闪电交易，而不仅仅是它代表 Fedimint 用户促成的支付。

</details>

<details> <summary><strong>备份你的 Gateway</strong></summary>

定期备份可保护你的 Gateway 资金和配置。

备份你的私钥短语（助记词）

你的 Gateway 的 12 词恢复短语可以恢复你的闪电钱包和 Gateway 身份：

1. 导航到Gateway 私钥短语卡片
2. 输入你的 Gateway 密码
3. 点击显示以显示助记词
4. 按顺序写下所有 12 个词并安全存储
5. 完成后点击隐藏

安全说明：

• 切勿与任何人分享你的恢复短语
• 将其离线存储在安全位置

导出联盟邀请码

如上所述，加入联盟后，建议备份所连接的所有联盟的邀请码。可以通过点击导出邀请码来完成。

1. 在仪表板标题中点击导出邀请码
2. 将下载一个 gateway-invite-codes.json 文件
3. 存储此文件。它仅包含公共数据，可以备份到云存储帐户或你自己的计算机上。

此备份让你在恢复 Gateway 时能够恢复所有联盟连接。加入或离开联盟后，系统会提醒你导出。

恢复过程

要从备份恢复 Gateway：

1. 部署一个新的 Gateway 实例
2. 在设置过程中，选择恢复钱包而不是创建新钱包
3. 输入你的 12 词恢复短语
4. Gateway 启动后，使用从文件恢复来恢复联盟连接

5. 你的余额和配置将恢复

</details>

<details> <summary><strong>自定义路由费用</strong></summary>

你可以自定义 Gateway 为每个联盟的路由闪电支付或联盟间兑换收取的费用。

费用类型

费用	描述
闪电基础费	每笔传出闪电支付收取的固定费用（以毫聪为单位）
闪电 PPM	按传出支付金额的百万分之几计算的变动费用
交易基础费	联盟间兑换收取的固定费用（以毫聪为单位）
交易 PPM	联盟间兑换收取的变动费用

如何设置费用

费用按每个联盟配置：

1. 导航到联盟卡片
2. 点击费用选项卡（默认显示）
3. 点击编辑费用
4. 为每种费用类型输入值：
   • 闪电基础费（毫聪）
   • 闪电 PPM
   • 交易基础费（毫聪）
   • 交易 PPM
5. 点击保存费用

</details>

<details> <summary><strong>监控你的 Gateway</strong></summary>

有效的监控可确保你的 Gateway 平稳运行并盈利。

流动性概览

监控所有三个层的流动性：

层	监控内容	为何重要
链上	闪电节点钱包余额	用于打开通道的资金
闪电	每个通道的入站/出站容量	决定闪电支付路由能力
电子现金	每个联盟的余额	限制每个联盟的传入闪电支付

需要关注的关键指标：

• 入站流动性 - 他人可以通过闪电向你发送多少（通道条中的蓝色部分）
• 出站流动性 - 你可以通过闪电发送多少（通道条中的绿色部分）
• 每个联盟的电子现金 - 你处理传入支付的能力（显示在联盟卡片标题中）

支付摘要

支付摘要卡片显示过去 24 小时的汇总统计：

传出支付：

• 成功/失败的支付总数
• 收取的总费用
• 平均延迟和中位延迟

传入支付：

• 与传出相同的统计信息

使用此信息了解你的 Gateway 的吞吐量和可靠性。

支付事件日志

如果你有兴趣了解特定支付的详细信息，支付事件选项卡提供详细的交易历史。这些事件将仅包含 Gateway 代表 Fedimint 用户促成的支付，不包括由闪电节点发起的交易。

过滤选项：

• 按联盟过滤
• 按事件类型过滤（闪电、钱包、电子现金事件）

事件类型：

• 闪电： 传出/传入开始、成功、失败
• 钱包： 链上提现和存入
• 电子现金： 票据花费、票据重新发行

每个事件显示：

• 事件种类和时间戳
• 可展开的 JSON 详细信息用于调试

使用支付日志：

• 调试失败的支付
• 跟踪特定交易
• 审计 Gateway 活动
• 分析支付模式

</details>

---

常见问题

<details> <summary><strong>HTTP 和 Iroh 端点有什么区别？</strong></summary>

它们为 Fedimint 客户端提供相同的功能，唯一的区别是客户端如何连接到 Gateway。HTTP 端点需要有效的域名、TLS 证书，并且 Gateway 必须在可公开访问的服务器上运行。在上述默认的 Docker、Start9 和 Umbrel 部署中，默认仅启用 Iroh 端点。Iroh 端点不需要有效的域名、TLS 证书，并且可以在 NAT 后面的自托管基础设施上运行。

• HTTP 端点： 客户端通过 HTTP 连接到你的 Gateway URL。要求你的 Gateway 可公开访问或已进行端口转发。
• Iroh 端点： 客户端使用 Iroh 协议连接。无需可公开访问的服务器即可实现直接连接。更适合位于 NAT 或防火墙后面的 Gateway。

</details>

<details> <summary><strong>我从未向我连接的联盟注册我的 Gateway，但我仍然能够路由闪电支付</strong></summary>

如果你正在运行 LND Gateway 并且联盟支持 LNv1，这是预期行为。

较旧的闪电协议（LNv1）不需要守护者明确许可，即可注册你的 Gateway。LND Gateway 会自动注册到支持 LNv1 的联盟。Gateway 设计为对闪电协议透明，LND Gateway 同时支持 LNv1 和 LNv2 协议。

关键点：

• 只有 LND Gateway 支持 LNv1（LDK Gateway 不支持）
• 所有新联盟都支持 LNv1 和 LNv2
• LND Gateway 可以通过 LNv1 路由支付，无需显式的守护者注册
• 要使用 LNv2（提供一些改进），你需要向守护者注册

如果你想确保使用更新的 LNv2 协议，你需要与联盟的守护者完成注册流程。

</details>

<details> <summary><strong>LNv1 和 LNv2 有什么区别？</strong></summary>

Fedimint 有两种闪电协议：LNv2 和 LNv1。我们计划弃用 LNv1。主要区别如下：

方面	LNv1	LNv2
Gateway 注册	Gateway 自动向联盟注册	需要守护者明确批准
发票创建	由 Fedimint 客户端创建	由 Gateway 创建
后端支持	仅 LND	LND 和 LDK
传入支付检测	HTLC 拦截	HOLD 发票

LNv1 使用 HTLC 拦截，Gateway 监控所有传入的 HTLC 并拦截那些发往 Fedimint 用户的 HTLC。这允许无需许可的 Gateway 操作，但仅适用于 LND。

LNv2 使用由 Gateway 直接创建的 HOLD 发票。用户将其支付请求发送到特定的 Gateway，该 Gateway 创建闪电发票。

有关详细的协议图，请参阅：

• 闪电模块 V1 协议
• 闪电模块 V2 协议

</details>

<details> <summary><strong>我的 Gateway 无法启动。我应该检查什么？</strong></summary>

• 检查日志： 运行 docker compose logs gatewayd 以查看错误消息
• 验证密码哈希： 确保 FM_GATEWAY_BCRYPT_PASSWORD_HASH 设置正确。记得在 docker-compose.yaml 中将 $ 转义为 $$
• 端口冲突： 确保端口 8176、8177 和 10010 未被其他服务占用

</details>

<details> <summary><strong>为什么我的支付失败？</strong></summary>

• 检查流动性： 确保你有足够的闪电通道容量（发送时出站，接收时入站）和电子现金余额（用于联盟的传入支付）
• 验证通道： 确认你的闪电通道处于活动状态，并且对等节点在线
• 查看支付日志： 检查 Gateway UI 中的支付事件选项卡，获取失败支付的特定错误消息

</details>

<details> <summary><strong>我无法连接到联盟。如何修复？</strong></summary>

• 守护者不可用： 你正在连接的守护者可能已关闭。尝试来自其他守护者的邀请码，或稍后重试
• 验证邀请码： 确保邀请码完整且有效。它应该是一个长字符串，请务必完全复制
• 查看 Gateway 日志： 运行 docker compose logs gatewayd 并查找特定的连接错误消息

</details>

<details> <summary><strong>丢失服务器后如何恢复我的 Gateway？</strong></summary>

1. 使用相同的部署方法（Docker、Start9 等）部署一个新的 Gateway 实例
2. 在初始设置期间，选择恢复钱包而不是创建新钱包
3. 输入你的 12 词恢复短语
4. Gateway 启动后，点击从文件恢复并上传你的 gateway-invite-codes.json 备份
5. 你的联盟连接和余额将恢复

有关创建备份的详细信息，请参阅备份你的 Gateway。

</details>

<details> <summary><strong>为什么我需要电子现金来处理传入的闪电支付？</strong></summary>

当联盟用户通过你的 Gateway 接收闪电支付时：

1. 发送方通过闪电向你的 Gateway 节点支付
2. 你的 Gateway 向联盟中的接收方提供电子现金
3. 你保留闪电支付（减去你应付的费用）

如果该联盟中没有电子现金，你就没有东西可以给接收方，因此无法完成传入支付。

</details>

---

其他资源

• Fedimint 文档
• GitHub 讨论 - 社区支持
• Discord 服务器 - 运营者的 #mint-ops 频道
• 闪电模块文档 - 闪电集成的技术细节

• 原文链接： github.com/fedimint/fedi...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～