没有任何应用能封禁你。

你会得到什么

• 一个只读节点。Farcaster 上每一条 cast、每一个反应、关注和资料的完整、经过验证的副本，并与网络保持同步。任何人都可以运行。
• 一个客户端。你关注的人的首页信息流、个人资料、讨论串、发帖、回复、点赞、转发、关注。它还会显示每条 cast 由哪个应用签名，并允许你按应用隐藏或显示 cast。
• 你自己的应用密钥。客户端用一把属于你、由你亲自添加到账户上的密钥签名。只要你的节点在线，中间没有任何人能替你发帖、隐藏你的信息流或拦截你的写入。

实测数据

来自演示节点：Hetzner cx43（8 vCPU、16 GB），位于法尔肯施泰因，1 TB 卷，2026 年 10 月，Snapchain 0.14.3。

开始之前

动手时间约 10 分钟。之后节点会自行同步，大约需要一天中的大部分时间。

第 0 步 · 准备服务器

curl -fsSL https://raw.githubusercontent.com/townhall-fc/townhall/main/install/provision.sh | HCLOUD_TOKEN=your_token bash

$env:HCLOUD_TOKEN="your_token"; irm https://raw.githubusercontent.com/townhall-fc/townhall/main/install/provision.ps1 | iex

它依次做这些事：

1. 使用你的 SSH 密钥（~/.ssh/id_ed25519.pub，Windows 上是 C:\Users\你\.ssh\id_ed25519.pub；没有就创建）并上传到 Hetzner，只有你能登录。
2. 在该机房选择至少 4 vCPU、16 GB 内存的最便宜机型。
3. 创建防火墙，只开放 SSH（22）、客户端用的 HTTP/HTTPS（80、443），以及 Snapchain 节点之间通信用的 UDP 3382。
4. 创建 Ubuntu 24.04 服务器并挂载一块数据卷：账户允许就用 2 TB，否则用允许的最大值。1 TB 就够（见实测数据）。
5. 等到能 SSH 登录后，打印接下来两条已填好 IP 的命令。

在 Windows 上，PowerShell 版本执行相同的步骤；创建 SSH 密钥时可能需要按两次回车。第 1、2 步在 PowerShell 中可直接运行。

可选参数：LOCATION=nbg1、SERVER_TYPE=…、VOLUME_GB=…（写在 bash 前面；Windows 上先设置，例如 $env:LOCATION="nbg1"）。服务器存在期间按时计费，见费用与清理。

第 1 步 · 运行 Snapchain 只读节点

ssh root@YOUR_IP 'curl -fsSL https://raw.githubusercontent.com/townhall-fc/townhall/main/install/node.sh | bash'

1. 安装 Docker。
2. 找到剩余空间最大的磁盘（你的数据卷），把节点放在那里。
3. 从最新的 Snapchain 发布版下载官方的 docker-compose.mainnet.yml 和 validators.toml，不做修改。该文件本身就配置为只读节点（read_node = true）。
4. 启动节点。它先下载网络快照，然后从对等节点重放最近的区块，直到追上。
5. 启动一个小的快照守护程序。首次启动时，节点会把下载的每个快照文件一直保留到最后，这就是文档要求 2 TB 的原因。守护程序在节点用完每个文件后立即删除它，因此演示节点首次同步的峰值约 800 GB，而不是约 1.5 TB。同步完成后它会自行退出。
6. 安装 townhall-status，一条命令显示每个分片落后多少。

$ ssh root@YOUR_IP townhall-status
shard 0: height 48485756  blocks behind: 1
shard 1: height 49161526  blocks behind: 0
shard 2: height 48996914  blocks behind: 1
In sync when every 'blocks behind' is in the single digits.

这是演示节点同步完成后的输出。追块期间，“blocks behind” 会不断减少；演示节点从几万降到个位数用了大约 10 小时。

节点在 3381 端口提供 Snapchain 的 HTTP API。在服务器上试试：curl -s localhost:3381/v1/castsByFid?fid=1 | jq '.messages[0].data.castAddBody.text'

第 2 步 · 创建你的客户端

ssh root@YOUR_IP 'curl -fsSL https://raw.githubusercontent.com/townhall-fc/townhall/main/install/client.sh | bash'

1. 克隆本仓库，在一次性的 Node 容器里构建客户端。
2. 启动 Caddy，为 YOUR-IP.sslip.io 申请 HTTPS 证书（一个指向你 IP 的免费通配 DNS 名；设置 DOMAIN=your.domain 可使用你自己的域名）。
3. 提供客户端，并把 /v1/* 转发到你的节点。浏览器只和你的服务器通信：同源、无 CORS、无第三方 API。
4. 启动一个小服务，为分享的 cast 生成链接预览：把 /c/<fid>/<hash> 这样的链接贴到 Farcaster 或 Telegram 时，会显示作者和内容。

随时重新运行同一条命令即可更新客户端。

使用客户端

只读

输入你的用户名。客户端在你的节点上把它解析成 FID，加载你关注的人，用他们最新的 cast 组成信息流。不签名，也不向任何地方发送任何东西。

连接你的账号（用于发帖）

1. 粘贴助记词并点击 Connect。页面从助记词推导出你的托管地址（custody address），并从 Optimism 上的 IdRegistry 合约读取你的 FID。此时什么都不会发送。
2. 页面为这个客户端生成密钥。页面生成一对新的 Ed25519 密钥（你的应用密钥），并从你的节点读取当前密钥 nonce（/v1/signersByFid → currentUserNonce）。然后你的托管账户签署两条 EIP-712 消息：SignedKeyRequest（哪个应用请求该密钥，这里是你自己的 FID）和 KeyAdd（密钥本身、可签署的消息类型、有效期、下一个 nonce）。
3. 它作为一条消息发送到你的节点。两个签名都放在一条 KEY_ADD 消息里，而这条消息的外层由新密钥本身签名，以证明你持有它。你的节点校验后像转发 cast 一样转发它。大约十秒后密钥生效。页面清除助记词，只在本浏览器中保留应用密钥。

发帖、回复、点赞、转发、关注

每个操作都会构建一条协议消息，在浏览器里用你的应用密钥签名，再把原始字节提交给你的节点。像 @alice 这样的提及会在你的节点上解析，并作为协议级提及保存。

图片和视频，存在你自己的服务器上

点文本框下方的图片按钮，可以附上最多两个图片或视频（JPEG、PNG、GIF、WebP 最大 10 MB；MP4、MOV、WebM 最大 100 MB）。Farcaster 应用把媒体上传到它自己的主机；自托管客户端没有这样的主机，所以用你的服务器。文件通过 /api/upload 上传，存放在 /opt/townhall/media，并从你的域名的 /media/<hash>.<ext> 提供。cast 把这个 URL 作为 embed 携带，和任何链接一样，所以每个 Farcaster 客户端都能显示。

只有持有你的节点认定为有效的 app key 的人才能上传：浏览器用这把密钥签名文件的哈希，服务器检查签名并向你的节点确认这把密钥。如果只允许自己上传，用 UPLOAD_FIDS=<你的 fid> 重新运行第 2 步。空间上限为 20 GB（MEDIA_QUOTA_GB）。代价是：关掉服务器，你旧 cast 里的媒体就无法加载。

频道

频道 cast 就是一条普通 cast，它的 parentUrl 是频道的 URL，例如 https://farcaster.xyz/~/channel/dev。这一部分属于协议，所以你的节点像存储任何 cast 一样存储并转发它。频道列表（名称、URL、谁可以发帖）在 Farcaster 客户端 API 里，不在协议里，所以你的服务器在那里查一次频道 URL 并缓存。不需要任何 key。

点文本框下方的 /，输入频道名即可发到该频道。点任何 cast 上的 /频道 标签，或搜索 /dev，即可阅读频道：所有带这个 parentUrl 的 cast，直接来自你的节点。在仅限成员的频道里，Farcaster 应用可能会在频道信息流中隐藏非成员的 cast；这条 cast 仍然存在于网络和你的节点中。

按应用包含或排除 cast

每条 cast 都由某个应用密钥签名，而每个应用密钥都记录了请求它的应用（该应用自己的 FID）。客户端在你的节点上为每位作者查询这一信息，显示为 via farcaster、via own key 等。点击信息流上方的应用名即可隐藏或显示它的 cast。你的选择会保存在本浏览器中。

Live：你的节点眼中的网络

Live 显示网络接受的每一条消息，在你的节点收到后一两秒内出现：cast、点赞、关注、资料修改，以及有人超出存储上限时被修剪掉的消息。它读取你节点的事件日志（/v1/events，每个分片一份）和区块高度（/v1/info）。这里没有任何数据来自别人的服务器。

查看一条 cast 的底层消息

点击任意 cast 下方的 { }，即可看到它背后的协议消息：BLAKE3 哈希、签名它的 Ed25519 密钥、请求该密钥的应用，以及指向你节点上原始 JSON 的链接。你的节点在检查完这三项之后才会保存这条 cast。

搜索

输入用户名或 FID。你的节点通过 /v1/userNameProofByName 解析名字；关注者和关注数来自它的关系存储。

只看投票者

在 Farcaster 网络投票中接受社会契约的人，持有 Base 上的 VOTE NFT，其 token id 就是他们的 FID（合约）。客户端直接向 Base 查询 ownerOf(fid)，并把这些作者标记为 voted。打开 Voters only，信息流只显示参与投票的人。拒绝不会铸造任何东西，所以链上只能看到“同意”。

来自互关的回复

Replies 汇总对你最近 cast 的回复和提及你的 cast，全部从你的节点读取。默认只显示互关的人，也就是你关注且也关注你的人。想看全部时切换到 everyone。

在手机上

打开你的客户端地址，选择添加到主屏幕（Safari：分享菜单；Chrome：⋮ 菜单）。它会像应用一样全屏打开，依然只和你的节点通信。

可选：不用助记词登录

三条命令得到的客户端用你的助记词添加它的密钥。这是最直接的方式，但助记词能控制整个账号，所以请用测试账号。如果别人也会用你的 townhall，或者你根本不想粘贴助记词，可以加上委托登录：用户在 Farcaster 应用里批准 townhall，就像登录任何 Farcaster 应用一样，客户端无需看到助记词就能拿到密钥。

ssh -t root@YOUR_IP 'curl -fsSL https://raw.githubusercontent.com/townhall-fc/townhall/main/install/signin.sh | IMPORT=1 bash'

• 需要一个应用账号。密钥请求要写明是哪个应用在请求，而应用就是一个 FID。IMPORT=1 会在你的服务器上以隐藏输入的方式，询问一个备用账号的助记词，让它充当应用；只保存它的密钥，存放在只有 root 能读的文件里。不加 IMPORT=1 时，脚本会新建一个密钥，你往它打印的地址转少量 Optimism 上的 ETH 后，为它注册新的 FID。
• 用户看到什么。登录页提供两种方式：Farcaster 应用（电脑上扫二维码，手机上点按钮）或自己的密钥。在应用里批准后，密钥被添加到他们的账号；密钥本身在他们的浏览器里生成，也只留在那里。
• 你的服务器保存什么。只有应用账号的密钥，用来签署请求。没有用户密钥、没有助记词、没有资金。

核心概念，用大白话说

FID

你的 Farcaster ID，一个数字。它存放在 Optimism 上的 IdRegistry 合约里。用户名、密钥和每条消息都指向它。

托管地址与助记词

拥有你 FID 的以太坊账户。助记词就是它的私钥。谁拥有助记词，谁就拥有这个账号，所以这里只在本地使用一次，用来添加应用密钥。

应用密钥（signer）

为你的消息签名的 Ed25519 密钥。你可以有很多把，每个应用一把。本客户端添加的是免 gas 密钥：一条由托管地址授权的 KEY_ADD 消息，无需交易。它有三条规则。权限范围：密钥列出它可以签署的消息类型（这里是 cast、反应、关注、资料），而且永远不能添加或移除其他密钥。滑动有效期：闲置一段时间后过期（最长 90 天，本客户端申请最长期限），每签一条消息都会重新计时。Nonce：每条 KEY_ADD 都带一个比该 FID 上一次更大的数字，旧的授权无法被重放。

旧方式依然可用：在 Optimism 上调用 KeyGateway.add，需要交易和 gas。这类链上密钥没有权限范围和有效期。你的节点在 /v1/signersByFid 同时列出两种。

消息

你做的每件事都是一条小小的签名消息：CAST_ADD、CAST_REMOVE、REACTION_ADD（点赞或转发）、LINK_ADD（关注）、USER_DATA_ADD（资料）。每条都有 BLAKE3 哈希和 Ed25519 签名，任何节点都能在不信任任何人的情况下校验它。

Snapchain

对这些消息进行排序和存储的网络。验证者运行共识并出块。消息按 FID 分到不同分片；分片 0 为其他分片排序。

只读节点与验证者

只读节点跟随链，校验每个区块上验证者的签名，存储完整状态并提供 API。它不投票，也不保留内存池（mempool）。任何人都能运行；验证者是一组固定的运营者。

存储

存储是租用的，在 Optimism 上链上支付（StorageRegistry 合约），按单位计算。每个单位一段时间后到期，所以是续租，而不是一次买断。每个单位对每类消息（cast、反应、关注、资料）分别设上限。超出上限不会报错：该类中你最旧的消息会被修剪以腾出空间。这适合时间线，但也意味着非常活跃的账号可能失去旧的关注或 cast。租约到期后，网络会拒绝你的新消息。Snapchain 就是这样控制状态规模、在不按条收费的情况下防止垃圾信息的。

在你的节点上查看：/v1/storageLimitsByFid?fid=YOUR_FID 列出每类存储的 limit 和 used，以及你的存储单位和到期时间。租约和密钥事件也是你节点索引的链上事件：/v1/onChainEventsByFid?fid=YOUR_FID&event_type=EVENT_TYPE_STORAGE_RENT。

用户名（fname）

通过签名证明映射到 FID 的可读名称。你的节点响应 /v1/userNameProofByName?name=…。

客户端

应用只是替你保管应用密钥、并从某个节点读取数据的程序。Farcaster 官方应用是其中之一，这是另一个。它们看到的都是同一个网络。

一条 cast 的旅程

1. 你点击 Cast。浏览器构建一条包含你的 FID、正文和提及的 CAST_ADD 消息，计算哈希，用你的应用密钥签名，并编码为 protobuf。
2. 它被提交到你服务器上的 /v1/submitMessage，Caddy 再转发给你的只读节点。
3. 你的节点校验它：FID 存在、密钥对该 FID 有效、哈希和签名正确、你有存储空间。任何一项不对都会立即返回错误。
4. 只读节点不保留内存池，所以它通过 gossip（mempool 主题）把有效消息转发给验证者。
5. 某个验证者把它打包进区块。你的节点同步这个区块，cast 出现在你的信息流里，通常只需几秒。

安全模型

• 像对待 rm -rf 一样对待助记词。它控制整个账号。请用测试账号来跑这个教程。一般来说，只把助记词粘贴到你自己运行的软件或你信任的开发者的软件里，并且尽可能使用委托登录（由持有你账号的应用为你批准一把密钥）。
• 你的助记词不会离开这个页面。它只在你的浏览器里用来签署两份密钥授权，随后即被清除。它不会被发送到你的服务器，也不会被保存。你的节点唯一收到的是签好名的 KEY_ADD。
• 应用密钥保存在本浏览器中（local storage）。它的权限范围允许签署 cast、反应、关注和资料修改，但永远不能转移你的 FID 或添加密钥。要停用，打开 Settings → Revoke this key on the network：密钥会签署自己的 KEY_REMOVE，无需助记词。如果设备丢失，可以从托管地址撤销，或者干脆不用：闲置的密钥在有效期结束后会自动过期。
• 你节点的 API 通过客户端地址公开：任何人都能通过它读取（这些本来就是公开数据），也能提交签名有效的消息，而你的节点只负责转发。

“没有任何应用能封禁你”是什么意思，边界在哪里

你的账号属于你的托管密钥，而不属于任何应用。即使某个应用隐藏你或关停，你的 cast、关注和资料依然在网络上，这个客户端会通过你自己的节点读取和发布它们。它改变不了的是：区块由一小组固定的 Snapchain 验证者产生，理论上他们可以拒绝你的消息；而且网络只接受已支付存储租金的 FID 的消息。你的节点让你独立于应用和 API 提供商，而不是独立于协议本身的规则。

搭建过程中踩过的坑

下面每一条都是在搭建演示节点时真实遇到的。现在脚本都已处理，但了解原因很有帮助。

• Hetzner 报 “error during placement”。该机房没有这个机型的容量了。现在第 0 步会依次尝试法尔肯施泰因、纽伦堡、赫尔辛基。
• Hetzner 拒绝了 2 TB 的卷。新账号的卷总量上限是 1 TB，而且申请提额因为账号太新被拒。现在第 0 步会退回到允许的最大容量，下面的守护程序让 1 TB 足够用。
• 快照放不下。Snapchain 会保留每个下载的分块，再为每个分片写一个完整的 tar，然后解压，直到最后才清理。单个分片的峰值约 1.5 TB。现在 node.sh 会启动一个小守护程序，在节点用完分块和 tar 后立即删除，峰值保持在 800 GB 左右。
• 节点因指标错误反复崩溃重启。官方主网 compose 文件把指标指向一个 statsd 服务，它也需要启动。node.sh 会同时启动两者。
• df 参数冲突（-P 与 --output）导致 Ubuntu 上的磁盘检查中断。已修复。
• 应用密钥机制在开发途中变了。第一版通过 Optimism 交易添加密钥，需要 1 美元的 ETH。现在 Snapchain 接受免 gas 密钥（KEY_ADD），这一步和 ETH 都不需要了。官方的 hello-world 示例仍在用交易，所以我们向上游提交了修复：hub-monorepo#2748。
• 密钥 nonce 没有文档。免 gas 的 KEY_ADD 需要账号当前的 nonce，它来自 /v1/signersByFid。指南指向了这个接口，但 API 参考里只有旧的、仅限链上的接口，所以我们只能从节点源码里读出来。我们向上游补充了这两个签名者接口的文档：snapchain#1080。
• 一次网络升级让旧节点停了下来。10 月 23 日主网切换到新的引擎版本，仍在运行 Snapchain 0.14.3 的节点不再跟上区块。镜像标签是 :latest，而以前重新运行第 1 步会沿用旧镜像。现在它会先拉取最新镜像，所以更新节点只需重新运行第 1 步。
• 两份官方指南说法不一。Snapchain 的指南用免 gas 方式添加密钥，而 docs.farcaster.xyz 上的 Hello World 仍在用交易（而且密钥请求签错了对象）。我们把它改成一致：docs#473。
• 助记词混淆。Farcaster 应用里有两个助记词：账号的恢复助记词和钱包的助记词。只有账号的那个拥有你的 FID；客户端会在签名之前显示托管地址和 FID，方便你分辨。

常见问题

我的助记词会被发到哪里？

哪里都不会。它在你的浏览器里推导出 custody 地址、签署密钥授权，然后从页面清除。经过网络的只有：你的 custody 地址（不是助记词），发给公共 Optimism RPC 用来查询 FID；以及一条发给你节点的 KEY_ADD 消息，里面是新的公钥和签名，也就是全网都能看到的数据。可以在 client/src/keys.ts 里核对。

那安全吗？

助记词不会离开浏览器，但有两个真实风险。提供页面的人可以改它的代码：在你自己的节点上就是你自己，从这个开源仓库构建；在别人的 townhall 上就是对方。另外，被入侵的电脑或恶意浏览器扩展能读到你输入的任何内容。所以建议用测试账号，或者通过 Farcaster 应用登录，那样完全不用输入助记词。

应该用哪个账号？

在客户端里用一个有存储空间的备用账号：你粘贴的就是它的助记词。如果你在帮别人测试这个教程，请用你平时使用的账号发布测试报告，让大家知道是谁运行的。

如果有人拿到了应用密钥，能做什么？

以该账号签署 cast、反应、关注和资料修改，直到你撤销它（设置 → Revoke），或者 90 天不用后自动过期。它不能转移你的 FID、更改 custody 地址或添加其他密钥。

每个人都需要自己的服务器吗？

不需要。一个节点可以服务整个社区：大家打开 townhall 登录即可，什么都不用运行。三条命令是给想要自己副本的人：社区、开发者、任何不应依赖单一运营者的人。正因为谁都可以这样做，才没有哪个应用能决定谁的声音被听到。

Snapchain 文档要求 2 TB，为什么 1 TB 就够？

网络本身大约 560 GB。多出来的空间是给首次同步用的：节点会把下载的每个快照文件留到最后；快照守护在每个文件用完后立即删除，所以演示节点的峰值约 800 GB。如果要长期运行，请随网络增长扩容磁盘。

可以在 Windows 上运行吗？

可以。使用 PowerShell：第 0 步和清理命令有 Windows 版本（命令上方的 Windows 标签），第 1、2 步可直接运行。

要花多少钱，怎么停止计费？

演示节点最初 12 小时花费约 2 美元。服务器和磁盘存在期间 Hetzner 按小时计费；清理命令会把两者都删除。

故障排查

费用与清理

Hetzner Cloud 按小时计费，服务器和卷分别计费。演示节点（服务器加 1 TB 卷）前 12 小时约 2 美元，所以完整测试一次只需几美元。运行一个月大约一百多美元；请以 Hetzner 控制台的当前价格为准。如果要长期运行，带大硬盘的独立服务器更便宜。添加应用密钥不花钱。

要停止计费，需要删除服务器和卷。下面这条命令会在确认后完成删除：

curl -fsSL https://raw.githubusercontent.com/townhall-fc/townhall/main/install/destroy.sh | HCLOUD_TOKEN=your_token bash

$env:HCLOUD_TOKEN="your_token"; irm https://raw.githubusercontent.com/townhall-fc/townhall/main/install/destroy.ps1 | iex

你的 Farcaster 账号不受影响。如果还想撤销应用密钥，请在删除服务器之前在客户端的 Settings → Revoke 中操作。

在帮别人测试这个教程？

谢谢你。有用的测试报告是诚实的，包括失败的地方。请：

1. 用你的主账号发布报告；在客户端里使用备用账号。
2. 在客户端里使用一个有存储的 Farcaster 测试账号，不要用对你重要的账号。
3. 在一台干净的机器上运行这三条命令，并记录时间。
4. 等客户端显示节点已同步后：发一条 cast、关注一个人、点一个赞，并用筛选隐藏某个应用的 cast。
5. 也在手机上打开看看。
6. 运行清理命令（destroy.sh，Windows 上是 destroy.ps1），停止计费。
7. 用你的主账号在 Farcaster 上发帖说明过程，好的坏的都写，以及花了多长时间。

永远不要把你的助记词或 Hetzner 令牌发给任何人，包括作者本人。如果你的服务器费用或时间得到了报销，请在帖子里注明。