webmention-hub · Webmention 中心插件

本插件为安知鱼（Anheyu）内容管理平台接入 W3C Webmention 协议：接收并验证其它站点对本站文章的引用，发文时向正文中的外部链接发送通知。

• 维护者：白夜

• 项目主页：https://blog.byer.ink/

• 插件类型：eventhook（订阅文章事件）+ 自带 HTTP 服务

• 插件版本：1.5.3（端口 9801）

1. 概述

Webmention 是 W3C 的双向引用协议：A 站文章引用了 B 站，A 站向 B 站的接收端点 POST 一对 source/target，B 站抓取 A 站页面确认链接存在，再把这条引用展示在自己文章底部。

插件实现两个方向：

• 入站：POST /api/webmention 接收端点，验证来源页面确实链接了 target，套审核规则后落盘。

• 出站：文章发布或更新时，提取正文外链，发现对方端点并发送通知。

管理界面与文章底部展示由插件自带的脚本注入，默认端口 9801，当前版本 1.5.2。

2. 功能特性

3. 工作原理

3.1 进程模型

插件是 Anheyu 主程序以 go-plugin 拉起的独立子进程，与主程序拥有同等系统权限。main() 先启动自带 HTTP 服务（goroutine），再 sdk.Serve 注册 eventhook 能力。运行期日志写 stderr，stdout 留给握手。

3.2 鉴权链路

管理接口要求管理员身份，插件本身不持有 JWT 密钥：

浏览器 ──(Authorization: Bearer <JWT>)──► 插件 /api/*
                                            │
           插件把该 Bearer 转发到后端 admin_check_path
                                            │
   HTTP 200 且响应体 code==200 → 管理员，放行
   HTTP 401 → 提示重新登录；其余 → 403

免鉴权路径：/api/health、/api/login、/api/endpoint、/api/webmention、/api/public/*，以及两个注入脚本的加载器与指纹实现体。"通过"结果按 admin_cache_ttl（默认 30 秒）缓存。

3.3 出站发送

订阅 article.published 与 article.updated。send_enabled 默认 false，关闭时不创建队列，事件回调直接返回。

正文外链提取规则：

事件回调只做解析与入队，投递由后台队列完成：2 个 worker，队列长度 256，满则丢弃并记日志，不阻塞事件回调。发送前查重，同一文章对同一 target 已发送过则记为 skipped。

3.4 端点发现

按 W3C §3.1.2 顺序回退，前一级未命中才试下一级。第 4 级失败（404、不可达、空响应）静默返回未找到。

4. 环境要求

• Anheyu（社区版或 PRO）开启插件系统；App 版本 ≥ 1.0.0。

• site_url 必填，用于拼接文章绝对 URL 与判定 target 归属。

• 接收端点需对公网可达，由外部 Nginx 或 CDN 反代到插件端口。

• 插件与后端在 Docker 内网可达，用于回源管理员校验。

• 文章页需声明接收端点，其它站点才能发现并向本站发送。

5. 安装

1. 后台进入「插件管理」。

2. 上传安装包 webmention-hub.zip（内含 plugin.json 与各平台二进制）。

3. 安装成功后状态变为「运行中」。升级同 ID 插件会保留既有配置与禁用状态。

安装包内 plugin.json 必须位于压缩包根目录。

cd plugins/webmention-hub
./build.sh          # 交叉编译 5 平台并产出 webmention-hub.zip

6. 快速开始

1. 填 site_url，例如 https://blog.example.com。这是唯一必填项。

2. 反代接收端点到 9801，保留前缀（proxy_pass 结尾不带斜杠）：

location /webmention/ { proxy_pass http://127.0.0.1:9801; }

1. 在文章页声明接收端点：

<link rel="webmention" href="https://blog.example.com/webmention/api/webmention" />

1. 需要向别人发送通知时开启 send_enabled。

2. 建一个自定义页面挂载管理控制台，见 §9.2。

7. 配置参数参考

以下参数在 plugin.json 的 config_schema 中声明，由后台保存后以环境变量注入插件进程。

8. 使用指南

8.1 接收端点

POST /api/webmention，Content-Type: application/x-www-form-urlencoded，字段 source 与 target。成功返回 HTTP 202：

curl -i -X POST https://blog.example.com/webmention/api/webmention \
  -d 'source=https://other.example/posts/hello' \
  -d 'target=https://blog.example.com/posts/hi'

# 202
{ "code": 200, "message": "accepted", "data": { "id": "…", "status": "approved" } }

target 必须属于本站 host：等于 site_url 的 host，或与之互为子域。未配置 site_url 时不做这层过滤。

来源验证抓取 source 页面（超时 12 秒，读取上限 1MB），把页面内所有 <a href> 解析成绝对地址后与 target 等价比对：

规范比对未命中时，target 的等价写法（原样、去尾斜杠、https/http 互换）以明文出现且前方 60 字符内含 href，也算命中。

8.2 审核规则

按顺序判定，先命中先返回：

域名匹配为"相等或子域"：example.com 命中 example.com 与 a.example.com，不命中 notexample.com。

同一对 (source, target) 重复投递不新增记录，只刷新内容与更新时间；已有的人工 rejected / spam 不会被覆盖。

8.3 出站发送

只需开启 send_enabled。发布或更新文章后自动提取正文外链并投递。只订阅 published 与 updated，因为 article.created 多对应草稿，此时文章页还没有对外地址。

结果记录在 GET /api/sent，不会自动重试。

8.4 手动发送

为指定文章重新触发一次出站发送，不依赖事件。POST /api/send/manual，需要 send_enabled 已开启：

{
  "article_url": "https://blog.example.com/posts/hi",
  "content_html": "<p>正文里含有 <a href=\"https://other.example/x\">外链</a></p>"
}

content_html 可留空，留空时按 article_url 抓取页面后提取外链。响应的 queued 为入队条数。

9. 前端接入

9.1 文章底部展示

widget.js 运行时注入，免鉴权查询 GET /api/public/mentions?url=<文章绝对URL>，只返回 approved 的 mention。public_enabled=false 时接口返回 404，脚本静默退出。

<script src="https://blog.example.com/webmention/api/widget.js"></script>

挂载点按顺序查找，第一个命中的容器生效：

#webmention-widget > #post-content > .post-content > .article-content
> #article-content > article .prose > article .rich-content > article > main

可用 window.__WM_WIDGET__ 覆盖，写在引入脚本之前：

<script>
  window.__WM_WIDGET__ = {
    apiBase: "https://blog.example.com/webmention/api",
    target:  "https://blog.example.com/posts/hi",
    mount:   "#webmention-widget"
  };
</script>

没有任何 mention 时不渲染任何元素。

9.2 管理控制台

一、自定义页面注入。 后台「页面管理」新建页面，在「自定义 JS」里粘贴：

(function () {
  if (window.__WM_CONSOLE_INJECTED__) return;
  window.__WM_CONSOLE_INJECTED__ = true;
  var host = document.querySelector("article") || document.body;
  host.style.minHeight = "0";
  var hd = host.previousElementSibling;
  if (hd && hd.tagName === "HEADER") hd.style.display = "none";
  var s = document.createElement("script");
  s.id = "wm-console-entry";
  s.src = "https://blog.example.com/webmention/api/console.js";
  host.appendChild(s);
})();

「自定义 JS」字段按 new Function 执行 JS 源码，直接粘 <script> 标签会报 Unexpected token '<'。脚本带 id="wm-console-entry" 时，控制台挂进该脚本的父容器（正文 article）。

二、独立页。 serve_ui=true 后访问插件服务根路径，如 https://blog.example.com/webmention/。

登录态：控制台没有内置登录框，读取 localStorage 的 auth-storage 取 accessToken，因此需与站点同源。部署在独立域名时指定站点根 window.ANHEYU_SITE_ORIGIN = "https://blog.example.com"。未登录或令牌失效（401/403）时跳转 /login?redirect=<当前地址>。

配色跟随站点主题：读 <html> 的 dark 类或 data-theme 属性，切换实时生效；站点未声明时退回系统 prefers-color-scheme。文章底部挂件（widget.js）同样跟随。

脚本分两层：

<hash> 为最终字节的 SHA-256 前 10 位。页面里只粘固定加载器地址，升级不需要清缓存。

10. HTTP API 参考

直连插件时前缀为 /api/...；反代保留子路径前缀时插件会自行裁掉 /api/ 之前的部分。

统一响应封装，业务成功以 code=200 判定：{ "code": 200, "message": "ok", "data": { } }

列表类接口带 ?page=&page_size= 时返回 {list, total, page, page_size}，否则返回全量数组。page_size 默认 20，上限 100。

审核状态修改，status 取 approved / rejected / pending / spam：

{ "status": "approved", "reason": "" }

统计接口的 data：

{
  "incoming_total": 0, "incoming_approved": 0, "incoming_pending": 0, "incoming_rejected": 0,
  "incoming_by_type": { "mention": 0, "like": 0 },
  "outgoing_total": 0, "outgoing_dispatched": 0, "outgoing_no_endpoint": 0, "outgoing_failed": 0,
  "top_source_hosts": [], "top_targets": []
}

11. 安全说明

• SSRF 防护：发现、验证、发送都走带拨号层校验的客户端，拒绝回环、私网、链路本地、组播与 169.254.0.0/16；域名解析出多个 IP 时任一落入内部段即拒绝；重定向逐跳复验，限 5 跳。

• 限流：接收端点与公开查询各按来源 IP 每分钟限流（rate_limit_per_min，默认 30）；登录代理固定每来源 IP 每分钟 10 次。

• 来源 IP 判定顺序：X-Real-IP → X-Forwarded-For 首项 → RemoteAddr。

• 端口：9801 只应内网可达，外部统一经反向代理。同机部署可将 listen_host 设为 127.0.0.1。

• 存储上限：入站 mention 5000 条，出站日志 2000 条；超限优先淘汰最旧的未通过记录。

• 公开展示脱敏：公开接口不返回审核原因等内部字段；作者链接、来源、头像渲染前只放行 http / https。

• 凭据：插件不持有 JWT 密钥，不落盘任何凭据。数据文件以 0600 权限原子写入。

12. 故障排查

13. 常见问题

Q：不开 serve_ui 能用吗？ A：能。把自定义页面注入的片段挂上即可，两个注入脚本始终可取。

Q：为什么发送记录里出现 skipped？ A：同一文章对同一 target 之前已成功发送过，插件不重复通知对方。

Q：能只接收不发送吗？ A：可以。保持 send_enabled=false，入站接收与展示照常工作。

Q：endpoint_path 什么时候必须填？ A：反向代理剥掉了 /webmention 前缀时。保留前缀可以留空，插件会从请求路径感知。

Q：/.well-known/webmention 一定要配吗？ A：不必。它只是兜底，部分发送方会探测；不配也不影响 Link 头与 HTML 声明。

Q：审核状态能批量改吗？ A：接口按单条处理，控制台列表逐条操作。

14. 限制与已知事项

• microformats 提取基于正则，来源页面结构差异可能导致作者名、头像、摘要为空，不影响落盘。

• 事件负载字段名以后端为准，ArticlePayload 做了多写法兼容；拼不出绝对 URL 时跳过本次入队。

• 出站发送不自动重试，失败记录在日志里，需要时用「手动发送」重来。

• 存储是单文件 JSON，每次改动整份原子重写，适合 5000 / 2000 条这个量级。

• 已通过审核的 mention 不会重新抓取来源页面。