
> [!WARNING]
> 这不是一篇严肃的 ActivityPub 教程，仅仅是一些基于个人实现时的简单概括。该网站并不支持所有 ActivityPub 协议要求。由于联邦宇宙实例众多而本人服务器资源有限，笔者可能会关闭本站 ActivityPub 服务。

[Aaron Swartz 于十年前的这个时候自杀了](https://www.nytimes.com/2013/01/13/technology/aaron-swartz-internet-activist-dies-at-26.html)。他起草的 [RSS (1.0) 协议](https://web.resource.org/rss/1.0/)、[和 John Gruber 一起设计、创造的 Markdown](https://daringfireball.net/projects/markdown/) 至今一直拥有大量互联网用户。这十年间互联网并没有因他的离世而产生 Open Web 原教旨主义者所期待的愿景。类似「剑桥分析公司」的事情你我都有耳闻。万维网的发明人 Tim Berners-Lee 博士后来提出了 [SoLiD 项目](https://solidproject.org/) —— 通过将用户数据和应用彻底分离，来实现用户对自身数据的完全掌控。ActivityPub 协议与之类似，但仅面向社交网站。如今，[ActivityPub 已经成为了 W3C 的推荐标准](https://www.w3.org/TR/activitypub/)；Elon Musk 收购 Twitter 公司之后，由于 "Hardcore Software Engineering" 所展露出的负外部性，Mastodon (长毛象)成为了最火热的分布式/去中心化社交网络平台，而 Mastodon 正是 ActivityPub 的实现之一。这个 [Implementation Report](https://activitypub.rocks/implementation-report/) 页面展示了一些实现了 ActivityPub 协议的网站列表。

折腾了几天，终于在百忙之中将这个小小的网站基本实现了 ActivityPub 最主要的接口。下面简单梳理一下大致实现的 Server to Server 接口，这些接口对于一个静态博客足矣。

本站点实现 ActivityPub 的所有 REST API 均系由 ▲ Vercel Serverless Function (JavaScript) 驱动。

## WebFinger

此 API 的定义参考 [RFC 7033](https://www.rfc-editor.org/rfc/rfc7033.html)。这个 WebFinger 协议目的是提供一种针对单个域名的**用户发现**方式。考虑到此 API 必须使用 `Content-Type: application/jrd+json` 作为 HTTP 的报文响应类型，因此不推荐直接使用静态文件托管 JSON，请使用 REST API 来构建此实现。

```plaintext
https://example.com/.well-known/webfinger?resource=acct:lawrence@example.com
```

`subject` 中的 URI 内容后半段和电子邮件非常像 —— ActivityPub 最终的实现效果也和电子邮件类似！

```json
{
  "subject": "acct:lawrence@lawrenceli.me",
  "aliases": [],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://lawrenceli.me/about"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://lawrenceli.me/api/activitypub/actor"
    }
  ]
}
```

`links` 中会添加上我们即将要实现的 Actor API。

**_除此 WebFinger 之外，以下所有 API 都必须设置 `Content-Type: application/activity+json` 作为响应头。ActivityPub 服务端（比如一个 Mastodon 实例）都会在请求头使用 `Accept: application/activity+json` 类似的形式来要求我们的实例返回对应的报文格式。_**

## Actor

Actor 就是 Activity 的参与者。WebFinger 会暴露此用户信息 (Profile) 接口。通过此 API，可以告知 ActivityPub 所有关于此用户的其他 API Endpoint，比如用户的 Outbox、Inbox、Followers 等等。所以这些 API 的具体 URL 都可以由自己去定义，而非一成不变。

除此之外，需要提供用户的 PublicKey 来验明身份。我们只需要在自己本地生成一对密钥就可以了。服务端通信中，发往不同 ActivityPub 的实例 HTTPS 请求都需要经过密钥加密。

```bash
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
```

```json
{
  "@context": ["https://www.w3.org/ns/activitystreams", "https://w3id.org/security/v1"],
  "id": "https://lawrenceli.me/api/activitypub/actor",
  "type": "Person",
  "name": "Lawrence Li",
  "preferredUsername": "lawrence",
  "summary": "Blog",
  "inbox": "https://lawrenceli.me/api/activitypub/inbox",
  "outbox": "https://lawrenceli.me/api/activitypub/outbox",
  "followers": "https://lawrenceli.me/api/activitypub/followers",
  "icon": ["https://lawrenceli.me/images/author/Lawrence.png"],
  "publicKey": {
    "id": "https://lawrenceli.me/api/activitypub/actor#main-key",
    "owner": "https://lawrenceli.me/api/activitypub/actor",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0RHqCKo3Zl+ZmwsyJUFe\niUBYdiWQe6C3W+d89DEzAEtigH8bI5lDWW0Q7rT60eppaSnoN3ykaWFFOrtUiVJT\nNqyMBz3aPbs6BpAE5lId9aPu6s9MFyZrK5QtuWfAGwv9VZPwUHrEJCFiY1G5IgK/\n+ZErSKYUTUYw2xSAZnLkalMFTRmLbmj8SlWp/5fryQd4jyRX/tBlsyFs/qvuwBtw\nuGSkWgTIMAYV71Wny9ns+Nwr4HYfF5eo2zInpwIYTCEbil79HcikUUTTO/vMMoqx\n46IiHcMj0SPlzDXxelZgqm0ojK2Z7BGudjvwSbWq/GtLoaXHeMUVpcOCtpyvtLr2\nYwIDAQAB\n-----END PUBLIC KEY-----"
  }
}
```

## Outbox

类似 RSS/JSON Feed, 类型为 `OrderedCollection`，必须按照时间顺序将最新内容放在 `orderedItems` 的最前。

```json
{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://lawrenceli.me/api/activitypub/outbox",
  "summary": "Blog",
  "type": "OrderedCollection",
  "totalItems": 1,
  "orderedItems": []
}
```

OrderedItems 数组中的单个 Item (一般为 Note) 可以是如下形式：

```json
{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "id": "https://lawrenceli.me/blog/ssg-ssr",
  "type": "Note",
  "published": "Thu, 20 Feb 2020 00:00:00 GMT",
  "attributedTo": "https://lawrenceli.me/api/activitypub/actor",
  "content": "<a href=\"https://lawrenceli.me/blog/ssg-ssr\">When to Use Static Generation v.s. Server-side Rendering</a><br>SSG & SSR",
  "url": "https://lawrenceli.me/blog/ssg-ssr",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://lawrenceli.me/api/activitypub/followers"]
}
```

在 ActivityPub 中，所有的对象都必须要提供一个 `id` 来作为唯一的全局标识符。而且，这个 id 必须是公开可访问的 URI，即可以通过此 id 来访问到此资源对象本身。 例上述如 Outbox 中的一项 Note 可以通过如下 curl 请求得到：

```bash
curl https://lawrenceli.me/blog/ssg-ssr -H "Accept: application/activity+json"
```

而如果你用浏览器直接打开这个 URL，你将会看到的是一个网页。原因就在于 `Accept` 这个请求头。

## Inbox

本质是一个必须支持 POST 请求的 WebHook。当联邦宇宙中其他用户对你的内容作出了一些交互(比如关注、回复、收藏、转发、删除等操作)，会触发此 WebHook。你需要根据 Activity 的类型去处理这些 Payload。一般来说，我们会使用自己的数据库来配合 Inbox Message 做 CRUD。

数据存在自己的数据库之后，你就可以直接在自己的站点上去展示它们。要保持数据于联邦宇宙中的一致性，你需要处理好所有消息类型，并做到接口的幂等 —— 因为 Mastodon 实例会有重试机制。

## Followers

关注者列表 API。当 Inbox 接收到来自其他用户的关注请求时，可以获取用户账户后保存到数据库然后通过此 API 展示出来。类型为 `OrderedCollection`。也是最简单的一个接口。

```json
{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://lawrenceli.me/api/activitypub/followers",
  "type": "OrderedCollection",
  "totalItems": 1,
  "orderedItems": ["https://mstdn.social/users/lawrence"]
}
```

## Note / Article

需要针对实现 Outbox 中的每一个 `orderedItem` 的 `id` 中的 URI 实现一个 JSON 输出。形式可以和 Outbox 中单个 Item 保持一致。
除了 `Note` 之外，ActivityPub 可以有其他类型的资源，比如长文章的 `Article`、视频资源 `Video`。不同 ActivityPub 的实现平台对不同资源的展示方式不尽相同。

我的博客页面地址和对应 Activity ID 的 URI 在 URL 形式上保持了一致。因此在实现此 API 后，用户可以在任何 Mastodon 实例的搜索栏中通过搜索我的博客文章页地址来发现它对应的 Mastodon 贴文(由 Outbox 生成)；在完全实现 Inbox 后，对贴文的交互数据就能够展示在我的网站上。比如文章页面最下方的 `Replies`。

## To Do

我的站点没有完全实现所有 ActivityPub 协议，比如 Inbox 消息目前仅处理了 Create Note 和 Accept Follower，还有许多消息类型亟待实现；大部分接受 GET 请求的接口也应当适当配置缓存；Inbox 要严格验证发送者的密钥。

## 社区实现

很巧合地发现 Cloudflare 也在同一时间段开发了兼容 Mastodon 的 ActivityPub 实现：[WildeBeest](https://github.com/cloudflare/wildebeest)，有兴趣可以直接用他们的商业化技术栈来部署一个小型实例，或者直接参考他们的代码，用自己擅长的服务端语言实现自己的 ActivityPub。

<div>
  <github user="cloudflare" repo="wildebeest"></github>
</div>

## Ref

- <https://www.w3.org/TR/activitypub/>
- <https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/>
- <https://s3lph.me/activitypub-static-site.html>
- <https://paul.kinlan.me/adding-activity-pub-to-your-static-site/>


我把我的博客搬进了联邦宇宙 (Fediverse) 。

ActivityPub 协议的简单实现


## Usage

The source code of this site is completely open: [GitHub - la3rence/site](https://github.com/la3rence/site).

<div>
<github user="la3rence" repo="site"></github>
</div>

Directly store the Markdown file (.md) in the `posts` folder to render the current file and make it a static page ([SSG](/blog/ssg-ssr)).

The homepage index directory of the blog is also generated synchronously without manual maintenance.

The **About** page is also generated based on the `readme.md` file.

Blog-related information configuration, such as title, author, etc., can be configured in the `lib/config.mjs` file.

It is recommended to use [pnpm](https://pnpm.io/) as a dependency management tool for node.js (compared to the official npm, pnpm has a great advantage: faster speed and space saving).

```shell
pnpm install
pnpm dev

# [Optional] install turbo via `pnpm i -g turbo`
# and you can try `turbo` for run any script in package.json like:
turbo dev
turbo build
```

Local preview: <http://localhost:3000>.

Use `pnpm build` to package, and `pnpm start` to start the production environment.
Use `pnpm fmt` to format all code and text.

This article shows all the media information that this blog project can display, such as code references, table displays, pictures, videos, Douban(Chinese IMDb) cards, etc.

2024/07 Update:

- The top navigation bar enables frosted glass dynamic suspension

- A new edge to edge design style that makes full use of the screen area to display code and images

## Technical details

This site is composed of the open source `Next.js` framework (from Vercel) and `TailwindCSS` style . The former is an open source SSG/SSR project based on React, and the latter is a popular atomic CSS library that allows me, who is not good at writing original CSS and has a weak foundation, to quickly write flexible styles.

Next.js will actively call some of the functions we have written (`getStaticProps()`) to allow the component to get data input, so that the React component can be rendered in advance **in the building phase**. `remark` library can compile native markdown syntax into DOM corresponding to HTML - In this project, we let it traverse the markdown files in the `posts` folder, compile them one by one, and use them as `props` of the dynamic routing page of `[id].js` to render blog posts:

```js caption="SSG in '[id].js': fetch data in build time" {3} showLineNumbers{38}
export const getStaticProps = async context => {
  const { id } = context.params;
  const mdData = await getMdContentById(id);
  return {
    props: mdData,
  };
};
```

There are many benefits to doing this:

- Suitable for CDN caching
- Excellent SEO performance
- Save network bandwidth and traffic
- O(1) time complexity [TTFB](https://en.wikipedia.org/wiki/Time_to_first_byte)

In a word, fast! If you try to turn off the JavaScript function of the current browser, bascially, this website can still render and display correctly.

Not only that, Next.js also provides **server-side rendering** capabilities, which can also bring a better SEO experience. I won’t go into details.

The above technology is called [JAMstack](#tables)：**J**avaScript, **A**PI & **M**arkup.

An interesting way to say it is that JAMstack is a CDN-first application.

> It's now possible, instead, to push content directly to the network and design frameworks that optimize for this capability. As a result, with optimizations like static asset hoisting, websites are now becoming faster and more reliable than ever before.

### Movie

You can write specific React components to make Markdown support richer page content, similar to `MDX`.
The source of this component is coded via react component in markdown!

Code:

```jsx
// filename: how.md
<div>
<douban id="3042261"></douban>
<div>
```

Result:

<div>
<douban id="3042261"></douban>
<div>

### Images

![Random Image](https://proxy.lawrenceli.me/picsum.photos/400/600?grayscale)

### Video

You can directly display videos from B station through `<bilibili />` component, based on iframe. And you can also make a tiny change to let it be `<youtube />`.

<div style="display: flex; justify-content: center;">
  <iframe width="900" height="480" src="https://www.youtube.com/embed/rR4n-0KYeKQ?si=gLjwn8rHDxYc4cUF"></iframe>
</div>

### Tweet / 𝕏

`<tweet />` component displays tweets:

<div>
<tweet id="20" />
</div>

### Open Graph

Open Graph (OG, Open Graph Protocol) is used to display specific rich media information when sharing web pages on social networks.

![Open Graph](https://lawrenceli.me/api/og?meta=This%20is%20Open%20Graph)

## Tables

JAMstack.

| ROLE |                                                  PROVIDED BY                                                   |
| :--: | :------------------------------------------------------------------------------------------------------------: |
|  J   |                   Client-side JS injected via React Hooks (state, event listeners, effects)                    |
|  A   |                                   API pages inside the pages/api directory.                                    |
|  M   | Pages with no data dependencies or pages with static data deps that trigger build-time static site generation. |

## GitHub Gist

`gist:darylwright/75332f27a6e9bff70bc0406114570829?file=gist-test.ts&highlights=1,3-5`

## WebSub for RSS

Powering WebSub based on GitHub Actions Standard, formerly PubSubHubbub. This allows RSS clients that support WebSub to not only get new articles immediately, but also reduce the number of polling and traffic between the client and the server. Details: [site/issue/324](https://github.com/la3rence/site/issues/324).

## ActivityPub

The website implements interaction with the federated universe through some basic ActivityPub and WebFinger protocols. [Implementation details](https://lawrenceli.me/blog/activitypub).

## I18n

The website supports internationalization through simple configuration. The middle suffix of the markdown file name and the Next.js native locale routing are used to distinguish between language types and display different texts.

## And more to do

Markdown currently uses GitHub Flavored Markdown ([GFM](https://github.github.com/gfm/)) and tries to add support for new syntax elements.

For example: <https://github.com/orgs/community/discussions/16925>

> [!NOTE]
> Critical content demanding immediate user attention due to potential risks.

## Ref Reference Links

- <https://nextjs.org>
- <https://tailwindcss.com>
- <https://rauchg.com/2020/static-hoisting>
- <https://jamstack.org>


This article is used to test the Markdown style end-to-end

How this website was built

## 使用方式

本站源码完全公开：[GitHub - la3rence/site](https://github.com/la3rence/site).

<div>
  <github user="la3rence" repo="site"></github>
</div>

直接将 Markdown 文件 (.md) 存放在 `posts` 文件夹下即可渲染当前文件，使之成为静态页面([SSG](/blog/ssg-ssr))。
博客的首页索引目录也为同步生成，而无需手动维护。

**About** 页面也同理基于 `readme.md` 文件生成而来。

博客相关的信息配置，如标题、作者等可在 `lib/config.mjs` 文件中配置。

推荐使用 [pnpm](https://pnpm.io/zh/) 来作为 node.js 的依赖管理工具（相比官方 npm，pnpm 拥有非常大的优势: 速度更快，且节省空间）。

```shell
pnpm install
pnpm dev

# [Optional] install turbo via `pnpm i -g turbo`
# and you can try `turbo` for run any script in package.json like:
turbo dev
turbo build
```

本地访问 <http://localhost:3000> 即可。

通过 `pnpm build` 来打包，`pnpm start` 则用于生产环境的启动。
通过 `pnpm fmt` 来将所有代码和文本进行格式化。

这篇文章展示了此博客项目所能展示的一切媒体信息，比如代码引用、表格展示、图片、视频、豆瓣卡片等等。

2024/07 更新：

- 顶部导航栏启用毛玻璃动态悬浮
- 全新的 edge to edge 设计风格，充分利用屏幕区域展示代码和图片

## 技术细节

此站点由 Vercel 公司开源的 `Next.js` 框架和 `TailwindCSS` 样式构成。前者是一项基于 React 的 SSG/SSR 开源项目，后者是一个目前流行的原子化 CSS 库，让不太会写 CSS、基础薄弱的我也能快速的写出灵活的样式。

Next.js 会主动调用我们写好的一些函数 (`getStaticProps()`)，让组件得到数据的输入，从而**在构建阶段**将 React 组件提前渲染完成。`remark` 库可以将原生的 markdown 语法编译成 html 对应的 dom - 在此项目中，我们让它固定遍历 `posts` 文件夹下的 markdown 文件，依次编译，让其作为 `[id].js` 的动态路由页面的 `props`，从而渲染出博客文章:

```js caption="SSG in '[id].js': fetch data in build time" {3} showLineNumbers{38}
export const getStaticProps = async context => {
  const { id } = context.params;
  const mdData = await getMdContentById(id);
  return {
    props: mdData,
  };
};
```

这样做的好处很多:

- 适合被 CDN 缓存
- 优秀的 SEO 表现
- 节省网络带宽、流量
- O(1) 时间复杂度的 [TTFB](https://en.wikipedia.org/wiki/Time_to_first_byte)

总之一个字，快！如果你尝试关闭当前浏览器的 JavaScript 功能，这个网站也一样能正确渲染并展现。

不光如此，Next.js 也提供了**服务端渲染**的能力，同样也能带来较好的 SEO 体验，不展开说了。

上述这种技术被称之为 [JAMstack](#tables)：**J**avaScript, **A**PI & **M**arkup.

一种有趣的说法是，JAMstack 是 CDN 优先的应用程序。

> It's now possible, instead, to push content directly to the network and design frameworks that optimize for this capability. As a result, with optimizations like static asset hoisting, websites are now becoming faster and more reliable than ever before.

### Movie

你可以编写特定的 React 组件来让 Markdown 支持更丰富的页面内容，这种实现方式和 `MDX` 类似。
The source of this component is coded via react component in markdown!

Code:

```jsx
// filename: how.md
<div>
  <douban id="3042261"></douban>
<div>
```

Result:

<div>
  <douban id="3042261"></douban>
<div>

### Images

![Random Image](https://proxy.lawrenceli.me/picsum.photos/400/600?grayscale)

### Video

可以直接通过 `<bilibili />` 组件展示来自于 B 站视频，基于 iframe.

<div>
  <bilibili bv="BV1gR4y1u76v"></bilibili>
</div>



### Tweet / 𝕏

`<tweet />` 组件展示推文：

<div>
  <tweet id="1138070453942009856" />
</div>

### Open Graph

Open Graph (OG, 开放图谱协议) 用于社交网络分享网页时展示特定的富媒体信息。

![Open Graph](https://lawrenceli.me/api/og?meta=This%20is%20Open%20Graph)

## Tables

JAMstack.

| ROLE |                                                  PROVIDED BY                                                   |
| :--: | :------------------------------------------------------------------------------------------------------------: |
|  J   |                   Client-side JS injected via React Hooks (state, event listeners, effects)                    |
|  A   |                                   API pages inside the pages/api directory.                                    |
|  M   | Pages with no data dependencies or pages with static data deps that trigger build-time static site generation. |

## GitHub Gist

`gist:darylwright/75332f27a6e9bff70bc0406114570829?file=gist-test.ts&highlights=1,3-5`

## WebSub for RSS

基于 GitHub Actions 来支持 WebSub 标准，即之前的 PubSubHubbub。这使得支持 WebSub 的 RSS 客户端不仅能立刻获取到新文章，也能减少客户端和服务端之间的轮询次数以及流量。细节: [site/issue/324](https://github.com/la3rence/site/issues/324).

## ActivityPub

网站通过最基本的一些 ActivityPub 和 WebFinger 协议部分实现了与联邦宇宙的交互。[实现细节](https://lawrenceli.me/blog/activitypub)。

## I18n

网站通过简单的配置以支持国际化。通过 markdown 文件名的中间后缀来和 Next.js 原生 locale 路由来实现区分语言类型展示不同文本。

## And more to do

Markdown 目前采用 GitHub Flavored Markdown ([GFM](https://github.github.com/gfm/)) ，并尝试添加新的语法元素支持。

例如：<https://github.com/orgs/community/discussions/16925>

> [!NOTE]  
> Critical content demanding immediate user attention due to potential risks.

## Ref 参考链接

- <https://nextjs.org>
- <https://tailwindcss.com>
- <https://rauchg.com/2020/static-hoisting>
- <https://jamstack.org>

此文用于端到端测试 Markdown 样式

B!og

包含标签 `guide`

包含标签 guide

包含标签 `guide`