Hatsu 0.3.5 介绍与选型指南

目标：面向「拥有一个静态站点/博客，想让站点以 ActivityPub 账号身份接入联邦宇宙（可被搜索、可被关注、新文章自动推送到粉丝时间线、评论可回流显示）」的读者，讲清 Hatsu 是什么、怎么工作、边界在哪，并与 Bridgy Fed、Bridgy、Mastodon 机器人账号三条替代路线做量化对比。本文为认知溯源篇，全部信息来自官方文档站、官方 GitHub 仓库与发布订阅的联网取证，查询日期统一为 2026-11-02，未做本地实测；部署实测见本专栏《Docker Compose 部署指南》。

一、环境信息

本章说明本文的信息检索口径，供读者复核每一条结论的来源。

• 组件与版本：Hatsu v0.3.5（代号 "Strobe Nights"，查询当日官方 Releases 最新稳定版，发布于 2026-10-01，来源：https://github.com/importantimport/hatsu/releases.atom，查询日期 2026-11-02）。
• 官方代码仓库：https://github.com/importantimport/hatsu（GitHub 仓库数字 ID 668140281）。⚠️ 早期资料/候选清单中的 sunemu/hatsu 系项目迁移前地址，查询当日访问返回 404（查询日期 2026-11-02）——Hatsu 现由 importantimport 组织维护，本文一律按 importantimport/hatsu 书写。
• 官方文档站：https://hatsu.cli.rs（mdBook 构建，源码位于仓库 docs/ 目录；任务早期给出的 hatsu.dev 查询当日不可达，以 hatsu.cli.rs 为准）。
• 代码许可：AGPL-3.0（来源：仓库 README「Licensed under AGPLv3」及 LICENSE 徽章，查询日期 2026-11-02）。
• 热度锚点：GitHub 星数 258（来源：仓库页 HTML stargazerCount 字段与 shields.io 徽章双重取证，查询日期 2026-11-02）；最近一次提交时间 2026 年 10 月（来源：shields.io last-commit 徽章，查询日期 2026-11-02）。
• 运行环境要求：Rust MSRV 1.85+（来源：README 顶部 MSRV 徽章，查询日期 2026-11-02）；官方制品为 ghcr.io 容器镜像与二进制 Release，支持 x86_64 与 aarch64。
• 本文性质：A1 认知篇，仅联网溯源；实测数据（部署回显、资源占用、命令输出）见本专栏部署、配置与命令各篇。

二、软件概述

本章回答「Hatsu 是什么、解决什么问题、由谁维护」。

Hatsu（「初」）是一个自托管、全自动化的静态站点 ActivityPub 桥接器（ActivityPub Bridge for Static Sites）。它本身不是社交网络服务端，而是站在你的静态站点背后，以站点的身份与联邦宇宙（Fediverse）交互（来源：官方文档站 Introduction 与仓库 README，查询日期 2026-11-02）。官方给出的四件事：

1. 用户可搜索：联邦用户搜索 @你的站点域名@你的域名（如 @catch-all@example.com）时，经 WebFinger 重定向到 Hatsu 实例上的对应账号；
2. 文章可搜索：联邦用户搜索 https://example.com/hello-world 这类站点 URL 时，重定向到 Hatsu 实例上对应的 Note 对象；
3. 关注即订阅：接受 Follow 请求，站点发布新文章（Feed 出现新条目）时自动向全部粉丝的收件箱推送 Create(Note)；
4. 互动可回流：接收联邦用户的回复/点赞/转发，通过 backfeed 机制回显到静态站点上。

官方强调「这些全部是自动化的——设置一次，之后什么都不用做」（README：Just set it up once and you won't need to do anything else）。

维护方：Hatsu 由 importantimport 社区组织维护（同组织还产出 KKna、Aoba 等配套项目，见第四章），主开发者 @kwaa 同时是 Nixpkgs 中 hatsu 包的维护者；项目通过 Matrix 房间 #importantimport:matrix.org 沟通（来源：README 徽章与文档站 Packaging Status 一节，查询日期 2026-11-02）。

核心事实速览（均标注来源，查询日期 2026-11-02）：

💡 说明：Hatsu 官方文档明确「Hatsu is still a Work-In-Progress」——0.x 版本线、扩展字段声明「不遵循 semver、随时可能破坏性变更」（Hatsu JSON Feed Extension 一节）。选型时必须把它当作快速演进的年轻项目而非成熟基础设施对待（查询日期 2026-11-02）。

三、核心架构

本章拆解 Hatsu 的内部组成与联邦协议层。

3.1 单进程桥接器 + 一个数据库

Hatsu 是单个 Rust 可执行文件（hatsu run）承载全部职责：WebFinger/NodeInfo/host-meta 等发现端点、ActivityPub 收件箱/发件箱、Feed 轮询器、Admin API。外部依赖只有一个数据库（SQLite 或 PostgreSQL），无 Redis、无消息队列、无搜索引擎组件（来源：文档站 Environments 与 Install 各节，查询日期 2026-11-02）。这一「单二进制 + 单库」形态直接决定了它的资源占用属于联邦组件中最轻的一档（实测数字见本专栏部署篇）。

数据流主线：站点 Feed →（定时拉取解析）→ Hatsu 数据库 →（Create/Update Note 活动）→ 粉丝实例收件箱；反向 联邦实例 →（Follow/Like/Announce/Create 活动投递）→ Hatsu 收件箱 →（入库供 backfeed 查询）→ 静态站点前端组件。

3.2 联邦协议栈与 HTTP 签名

官方文档「Federation in Hatsu」一节列出的协议与标准（查询日期 2026-11-02）：

• ActivityPub（Server-to-Server）：发送 Accept(Follow)、Create(Note)、Update(Note)；接收 Follow(Actor)、Undo(Follow)、Create(Note)、Like(Note)/Undo(Like)、Announce(Note)/Undo(Announce)；
• HTTP Signatures：README 明确启用 signed_fetch_actor——每个出站请求都带 HTTP 签名，从而兼容开启 secure fetch 模式的 Mastodon 实例与 GoToSocial（两者的访问控制都要求签名拉取）；同时默认开启 http_signature_compat 以兼容 Pleroma 的旧签名实现；
• WebFinger / NodeInfo / Web Host Metadata：账号发现与实例元数据；
• 支持的 FEP：FEP-67ff（FEDERATION.md）、FEP-f1d5（NodeInfo in Fediverse Software）、FEP-fffd（Proxy Objects）、FEP-4adb（用 WebFinger 解标识符）、FEP-2c59（从 AP actor 发现 WebFinger 地址）；
• ** notable 差异**：无共享收件箱（No shared inbox）——每个 actor 独立 inbox，与 Mastodon 的实例级 shared inbox 模型不同。

💡 技术拓展：联邦宇宙的服务间协议不止 ActivityPub 一种。主要选项对比——

协议	代表实现	特点
ActivityPub	Mastodon、Lemmy、Akkoma、Hatsu	W3C 标准，收件箱/发件箱模型，生态事实标准
Nostr	各类 relay/client	密钥即身份，无服务器账户概念
AT Protocol	Bluesky	中心化 PDS + 独立 firehose 模型
Zot/Zot6	Hubzilla	跨实例身份漫游

Hatsu 官方明确「Hatsu is ActivityPub only, which means it doesn't handle Nostr, AT Protocol (Bluesky) or other protocols」——只接 AP 生态，这是它与 Bridgy Fed 最大的能力差异（来源：文档站 Comparison 一节，查询日期 2026-11-02）。

3.3 数据源层：Feed 而非 microformats2

与上一代桥接器（Bridgy/Bridgy Fed 依赖 Webmention + microformats2 标记）不同，Hatsu 用标准 Feed 订阅作为唯一数据源：站点首页 <link rel="alternate"> 自动发现 JSON/Atom/RSS feed，解析优先级 JSON > Atom > RSS；JSON Feed 用 serde 一等公民解析，Atom/RSS 经 feed-rs 转换（来源：文档站 Feed 一节，查询日期 2026-11-02）。这意味着任何 SSG（Hugo/Jekyll/Lume/Astro 等）默认产出的 feed.xml 即可接入，无需给 HTML 加微格式标记，也无需站点能收发 Webmention。

对象 ID 采用可预测映射：https://hatsu.local/posts/https://example.com/foo/bar——帖子 URL 直接编码进 Hatsu 的对象地址，因此重定向规则可以在纯静态文件层面写死（见 4.2）。

3.4 发现与重定向层

站点域名要让联邦「搜得到」，需要两类重定向（文档站 Redirecting 一节，查询日期 2026-11-02）：

1. .well-known/*（webfinger/nodeinfo/host-meta）→ 指向 Hatsu 实例；
2. 接受 application/activity+json 的页面请求 → 指向 https://hatsu.local/posts/<页面URL>。

官方给出四种实现路径：静态文件+markup（把 well-known 内容抓成静态文件、页面加 AS2 alternate link，适用一切 SSG/托管）、_redirects 文件（Netlify/Cloudflare Pages）、平台配置（netlify.toml / vercel.json）、Aoba 中间件（Lume 插件 + Hono 中间件，importantimport 同生态项目）；另有 FEP-612d 的 DNS TXT 记录方式（_apobjid.example.com https://hatsu.local/users/example.com）。

四、功能特性

本章列举与接入决策直接相关的功能面（依据官方文档站，查询日期 2026-11-02）。

4.1 接入与自动化

• 全自动订阅发布：账号创建后 Hatsu 定期拉取站点 Feed，新条目自动以 Create(Note) 广播给粉丝，更新条目发 Update(Note)；
• v0.3.5 起出站请求携带 User-Agent（releases.atom 变更日志 #97），便于目标站点识别与放行；
• 多账号单实例：一个 Hatsu 实例可桥接多个静态站点域名（Admin API 按域名建号，见本专栏命令篇）；
• 实例封禁：Admin API 支持 block-url/unblock-url，path 为 / 时按实例封禁、精确到 actor 时按账号封禁，收到活动时逐条匹配（文档站 Block Instances or Actors 一节）。

4.2 backfeed（互动回流）

把收到的联邦回复显示回静态站点的三条官方路线（文档站 Backfeed 一节，查询日期 2026-11-02）：

4.3 生态与配套

• Hatsu JSON Feed Extension：在 JSON Feed 里加 _hatsu 键定制账号头像/banner/别名（FEP-4adb/2c59 用），官方声明实验性、不守 semver；
• Aoba：Lume/Hono 的 Hatsu 集成插件与中间件；
• 打包状态：Nixpkgs（稳定版）、NUR sn0wm1x（含 beta）、Flakes（未测试）、AUR 均有维护者；macOS 不支持 Nix 路线。

4.4 兼容性矩阵现状

官方 Compatibility Chart 目前仅填了 Mastodon 一行（发送 Create(Note)/Accept(Follow) 与接收 Follow 均 ✅），GoToSocial、Misskey、Pleroma 行为空待测；官方口径是「Akkoma、Sharkey 等 fork 应随上游兼容，不单独列」（来源：文档站 Compatibility Chart，查询日期 2026-11-02）。矩阵未填 ≠ 不兼容（HTTP 签名设计正是为了过 GoToSocial/Mastodon 安全模式），但选型时应把「官方实测面只有 Mastodon」当作已知风险。

五、快速开始（最小可用示例）

官方 Docker 路线的最小配置形态（来源：文档站 Docker Installation 一节，原文照录，查询日期 2026-11-02）：

docker run -d \
  --name hatsu \
  --restart unless-stopped \
  -p 3939:3939 \
  -v /opt/hatsu/hatsu.sqlite3:/app/hatsu.sqlite3 \
  -e HATSU_DATABASE_URL=sqlite://hatsu.sqlite3 \
  -e HATSU_DOMAIN={{hatsu-instance-domain}} \
  -e HATSU_LISTEN_HOST=0.0.0.0 \
  -e HATSU_PRIMARY_ACCOUNT={{your-static-site}} \
  -e HATSU_ACCESS_TOKEN=123e4567-e89b-12d3-a456-426614174000 \
  ghcr.io/importantimport/hatsu:{{version}}

要点：镜像三通道 latest（稳定）/beta/nightly；环境变量必须一次给全（无交互式初始化）；HATSU_PRIMARY_ACCOUNT 是实例的签名主体账号且不可删除。本节仅为官方形态速览，可运行的完整实测部署（含 SQLite 与 PostgreSQL 两种后端、启动验证与排障）见本专栏《Hatsu 0.3.5 Docker Compose 部署指南》。

六、适用场景与限制

6.1 适用场景

• 个人博客/作品集等静态站点想获得「被 @ 即可关注」的联邦身份，不想运营 Mastodon 实例；
• 已有 Hugo/Jekyll/Astro 等 SSG 产出 feed，不愿改造 HTML 微格式的作者（对比 Bridgy 路线）；
• 需要低资源常驻服务（单二进制 + SQLite，树莓派级硬件即可，资源实测见部署篇）；
• 多站点：一个实例桥接多个域名。

6.2 限制与风险

1. 0.x 项目，接口未稳定：官方自述 WIP，JSON Feed 扩展明确「subject to breaking changes」；
2. 仅 ActivityPub：要同时接 Bluesky/Nostr 的读者应选 Bridgy Fed；
3. 无公开公共实例（截至查询日）：文档站写明「Until then, you'll need to self-host the instance or find a person running a Hatsu instance」——自托管几乎是唯一路径；
4. 主账号必须真实可达且有有效 Feed：启动时校验 HATSU_PRIMARY_ACCOUNT，拉不到 Feed 直接退出（该行为实测复现与排障见部署篇常见问题）；
5. 兼容性矩阵大部分未填（见 4.4）；
6. 无共享收件箱：对强依赖 shared inbox 优化的对端实例可能有额外投递开销；
7. backfeed 前端需自己拼：评论回流是前端组件级集成（KKna/oom-comments），不是开箱 UI；Webmention 回流未实现。

七、同类选型对比

「静态站点接入联邦」这一需求下的主要路线对比（星数与活跃度均经 shields.io/仓库页取证，查询日期 2026-11-02）：

选型结论：

• 站点已有良好 microformats2 标记、且想要 Bluesky/Nostr 多协议 → Bridgy Fed；
• 只想把博客变成「@example.com@你的域名 可关注」的 AP 身份、厌恶改造 HTML、希望一条 compose 起服务 → Hatsu；
• 不想自托管、接受身份寄生在公共 Mastodon 实例 → 机器人账号路线。

💡 技术拓展：桥接器实现联邦身份的方式存在两种模型——「代理 actor」（桥接器为站点域名铸造 actor，站点通过重定向把发现流量让渡给它，Hatsu/Bridgy Fed 属此类）与「镜像账号」（在真实实例上注册账号搬运内容，机器人路线属此类）。前者身份域名=你的站点域名、可迁移；后者实现最快但身份不受站点控制。本文推荐的 Hatsu 属前者。

八、参考链接

• 官方文档站：https://hatsu.cli.rs（查询日期 2026-11-02）
• 官方仓库：https://github.com/importantimport/hatsu（查询日期 2026-11-02）
• 发布订阅：https://github.com/importantimport/hatsu/releases.atom（查询日期 2026-11-02）
• 容器镜像：https://github.com/importantimport/hatsu/pkgs/container/hatsu（查询日期 2026-11-02）
• Hatsu JSON Feed Extension：https://github.com/importantimport/hatsu/issues/1（查询日期 2026-11-02）
• Activitypub-Federation（与 Lemmy 同库）：https://github.com/LemmyNet/activitypub-federation-rust（查询日期 2026-11-02）
• Bridgy Fed：https://github.com/snarfed/bridgy-fed、Bridgy：https://github.com/snarfed/bridgy（查询日期 2026-11-02）
• FEP-612d / FEP-2c59 / FEP-4adb 等：https://w3fep.github.io/#/（查询日期 2026-11-02）