飞牛OS 路径穿越漏洞敲响警钟：仅靠强密码无法防御软件漏洞。

本文详解如何用 mTLS（双向 TLS 认证）保护自建 NAS、Web 服务、API 等，包含反向代理配置（以 Traefik 为例）、OpenSSL 生成证书、浏览器/App 导入证书的指南。

引子：强密码==安全？

相信各位都有所耳闻，最近，国产NAS系统飞牛OS爆出了一个高危漏洞：

2026年初，多位用户和安全社区相继披露：飞牛OS的某些版本存在严重的路径穿越（Path Traversal）0day漏洞。攻击者无需任何身份验证，只需构造特定的URL请求，就能直接读取NAS设备上的任意文件——从系统配置文件、用户存储的照片视频、私钥证书，到家庭相册、财务表格、个人隐私文档……全部暴露在黑客眼前。简单来说，你的NAS瞬间变成了一个“无需密码的公开网盘”，黑客想看什么就能看什么，想下载什么就能下载什么。

这个漏洞影响范围极广，尤其是那些将飞牛NAS通过公网端口、官方内网穿透（fn connect）等方式暴露到互联网上的用户，几乎处于完全裸奔状态。社区反馈显示，大量设备在漏洞曝光前已被批量扫描和利用，甚至出现数据被窃取、设备被植入后门、沦为僵尸网络的情况。飞牛官方随后通过静默推送修复补丁（例如1.1.15及更高版本）试图阻断攻击链，但早期缺乏及时公告、漏洞细节披露迟缓，也引发了不少用户对厂商安全响应态度的质疑。

这件事给我们敲响了警钟：仅仅依赖“强密码 + 登录认证”并不一定安全。

为了方便访问，自建服务（NAS、个人云盘、家庭服务器、内部管理后台等）大多跑在公网上~~（当然你自建VPN也可以）~~。软件本身再怎么加固账号密码、再怎么限制弱口令、再怎么开启两步验证，一旦程序逻辑出现哪怕一个低级但致命的漏洞（如路径穿越、命令注入、认证绕过），攻击者就能完全绕过表层的“密码防线”，直接拿到最高权限的数据访问能力。飞牛OS的这次事件，正是最典型的“认证再强也挡不住代码漏洞”的案例。

密码可以改，密钥可以重置，但如果攻击者已经提前把你的所有文件都拷贝走，一切防护都成了马后炮。

那么，面对这类“软件自身漏洞导致的越权访问”，我们还能做些什么？有没有一种机制，能在应用层认证之外再加一道更强硬、更底层的防护墙，让即便软件本身出现严重漏洞，黑客也很难真正拿到有效数据？

答案就是本文要重点探讨的：mTLS（Mutual TLS，双向证书认证）。

mTLS 简介

Mutual TLS（简称 mTLS，双向 TLS 认证），也叫双向证书认证，是 TLS 协议的一种扩展认证模式。

默认情况下，TLS 协议只通过 X.509 证书向客户端证明服务器的身份，而客户端到服务器的身份验证则交给应用层处理（比如用户名/密码、Token 等）。不过 TLS 本身也支持通过客户端侧的 X.509 证书来实现客户端身份认证。只不过因为需要提前为每个客户端分发证书、管理证书生命周期，而且对普通终端用户来说体验较差（不像输入密码那么简单），所以在面向消费者的互联网应用中几乎从不使用这种方式。

因此，**mTLS（Mutual TLS）更多出现在企业到企业（B2B）**场景中：客户端数量有限、类型相对统一（大多是程序、脚本、微服务、内部工具等）、运维负担可控，同时对安全性的要求远高于消费级环境。在这类场景下，mTLS 能让通信双方在 TLS 握手阶段就完成双向强身份验证——服务器验证客户端证书，客户端也验证服务器证书——从而建立起真正的“双方互信”通道。

——来自维基百科 - Mutual authentication

简单一句话总结就是：

mTLS = 标准 TLS（服务器证书认证） + 强制要求客户端也提供并验证有效的 X.509 证书。

其工作原理如图所示：

这种机制把身份验证从“应用层”下沉到了“传输层加密协议”本身，极大降低了应用代码出现漏洞时被绕过的风险。正如飞牛OS事件所暴露的：即使应用层认证逻辑被路径穿越或命令注入击穿，只要连接本身没有通过 mTLS 建立，黑客就能直接发起请求；反之，如果连接必须持有有效客户端证书才能建立，攻击者即便知道了 URL 和漏洞，没有提供正确的客户端证书，连 TLS 握手都完不成，何谈漏洞利用？

本文不会过多纠结于 mTLS 的密码学细节或理论模型，而是聚焦于最实操的部分：

• 如何便捷的为自建服务配置 mTLS
• 如何生成、管理、签发客户端证书（我写了个简单的一键式脚本）
• 以 Immich 和 BitWarden 为例看看套上 mTLS 后应用是否能正常运行

为自建服务配置 mTLS

生成自签名根证书

在 mTLS 环境中，我们需要一个根证书（Root CA） 来签发服务器证书和客户端证书。这个根证书是整个信任链的起点，自签名即可（因为我们自己控制信任，不需要公网 CA）。

这一步非常简单，并且只需要执行一次，使用 OpenSSL 生成自签名的根 CA 证书和私钥：

openssl req -new -x509 -nodes -sha256 -days 3650 -newkey rsa:4096 \
  -keyout ca.key -out ca.crt \
  -subj "/C=US/O=OrganizationName/CN=CommonName"

解释一下参数：

• -nodes：no DES 的缩写，不对私钥进行加密（不设置密码）
• -days 3650：CA证书有效期设为 3650 天
• -subj：这里直接指定证书的主题，只是用来标识。可以选的字段有：
  • C=：国家（Country）
  • ST=：省/州（State/Province）
  • L=：城市（Locality）
  • O=：组织（Organization）
  • CN=：通用名称（Common Name）这个必须有，并且Chrome选择证书时只会显示这一项

执行后，你会得到两个文件：

• ca.key：根 CA 的私钥
• ca.crt：根 CA 的公钥证书

这两个文件务必好好保存，以后签子证书要用到。

配置反向代理

这里主要以 Traefik 为例，如果你使用 Nginx，参考 Nginx - Module ngx_http_ssl_module。如果你对Traefik不了解，可以看看我的另一篇文章：使用 Traefik 作为 Docker 的反向代理

首先，需要在动态配置文件中定义 mTLS 策略，创建或编辑 /etc/traefik/dynamic.yml（或你使用的动态配置文件），添加如下键值对：

tls:
  options:
    # 自定义一个名字，例如 mtls
    mtls:
      clientAuth:
        caFiles:
          # 前面生成的根 CA 证书路径（容器内路径）
          - /etc/traefik/ca/ca.crt
        # 表示强制要求客户端提供证书且必须验证通过
        clientAuthType: RequireAndVerifyClientCert

然后在 entrypoint 或 router 上启用该 mTLS 策略即可，Traefik 的配置非常灵活，你可以选择在 entrypoint 上启用 mTLS，这样其下的全部 router 都会应用此规则。相反，如果你只希望部分域名启用 mTLS，只需在其对应的 router 下配置 mTLS。

1. 全局强制所有 HTTPS 流量都走 mTLS

   entryPoints:
     websecure:
       address: ":443"
       http:
         tls:
           # mtls 是签名 tls 配置的名称
           # file 是动态配置文件的名称
           options: mtls@file
   

2. 只对特定服务启用 mTLS

   http:
     routers:
       jellyfin-admin:
         rule: "Host(`admin.mydomain.com`)"
         service: jellyfin
         entryPoints:
           - websecure
         tls:
           # 只在此 router 启用 mTLS
           options: mtls@file
       nextcloud:
         rule: "Host(`cloud.mydomain.com`)"
         service: nextcloud
         entryPoints:
           - websecure
         tls:
           # 同样启用
           options: mtls@file
   

这样服务端的配置就完成啦~

生成客户端子证书

客户端证书（也叫子证书、Leaf Client Cert）是由我们刚刚生成的根 CA（ca.crt / ca.key） 签发的，用于证明客户端的身份。它与根 CA 的关系是信任链： 根 CA 是信任锚点 → 签发客户端证书 → Traefik 只信任由这个根 CA 签发的证书 → 实现 mTLS 双向强认证。

考虑到生成证书的命令参数过多，非常麻烦，我写了一个脚本 make-client.sh，建议直接放到存放 ca.crt 和 ca.key 的目录下运行（例如 ~/ca/），修改脚本开头的几个变量，每次为一个新设备运行一次即可。

#!/usr/bin/env bash

organization_name="Skyone"       # 你的组织/个人的标识
client_name="Windows 10 laptop"  # 设备/用途的描述性名称
client_name_file="win10laptop"   # 保存的文件名（简短且无空格）

set -e

# 创建客户端私钥（RSA 4096）
openssl genrsa -out client.key 4096

# 创建客户端的证书请求 (CSR)
openssl req -new -sha256 \
  -key client.key -out client.csr \
  -subj "/C=US/O=$organization_name/CN=$organization_name $client_name mTLS Client"

# 用 CA 给客户端证书签名, 730 天（约 2 年）
openssl x509 -req -sha256 -days 730 \
  -in client.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out client.crt

# 导出 PKCS#12/.p12 证书 （不带证书链）
# 便于 Windows / macOS / iOS / Android 导入
openssl pkcs12 -export \
  -inkey client.key -in client.crt \
  -out "client-$client_name_file.p12" -name "$client_name_file"

rm client.csr client.key client.crt

运行时会提示你输入导出密码，这是导入到系统密钥链/浏览器时用的密码，建议设置一个临时好记的密码，导入完设备后就可以删除 .p12 文件了。

导入客户端证书

我们刚刚通过 make-client.sh 生成了 PKCS#12 格式的客户端证书文件（.p12），里面同时包含了私钥和证书本身。现在需要将这个 .p12 文件安全拷贝到目标设备上，然后导入系统/浏览器的证书存储中。导入成功后，访问 mTLS 保护的服务时，浏览器或客户端工具就会自动（或手动选择）使用这个证书完成双向认证。

Windows 设备

1. 将 .p12 文件拷贝到 Windows 电脑（U 盘、局域网共享、加密邮件等方式，完成后立即删除源文件）。
2. 双击 .p12 文件，系统会启动证书导入向导。
3. 在“证书存储位置”页面，选择 当前用户 → 下一步。
4. 输入导入时设置的导出密码（脚本运行时提示输入的那个密码）。
5. 存储位置选择 个人（Personal / My） → 下一步 → 完成。
6. 导入成功后，可通过 certmgr.msc（Win + R 输入）打开证书管理器，在“个人 → 证书”下看到刚导入的证书（名称通常是你设置的 $organization_name $client_name mTLS Client）。

macOS 设备

1. 双击 .p12 文件，系统会自动打开“钥匙串访问”应用。
2. 输入导出密码，钥匙串会提示选择存储位置（推荐“登录”钥匙串）。
3. 导入后，在钥匙串访问中搜索证书名称，可在“我的证书”分类下找到。

iOS / iPadOS

1. 进入 设置 → 通用 → VPN 与设备管理 → 已下载的描述文件（或直接搜索“证书”）。
2. 安装描述文件，输入导出密码。
3. 安装完成后，证书会出现在 设置 → 通用 → 关于本机 → 证书信任设置（部分版本）或直接在 Safari 使用时自动弹出选择。

Android 设备

不同厂商 ROM 路径略有差异（小米/华为/One UI 等可能名字不同），以Pixel手机为例：

1. 进入 设置→安全与隐私→更多安全和隐私设置 → 加密与凭据（或直接搜索“证书”）。
2. 选择“安装证书”→ 找到 .p12 文件，输入导出密码。
3. 安装完成后，证书会出现在“用户证书”列表中。

使用浏览器测试

访问被 mTLS 保护的站点，浏览器会弹出“选择证书”，直接选择刚导入的证书（通常显示你设置的 CN 名称，如 “Skyone Windows 10 laptop mTLS Client”），点击确定。

通过认证后，一切操作都不会有影响。因为 mTLS 是在 TLS 握手时实现的，而 HTTP 协议位于 TLS 内，应用程序根本感受不到 mTLS 的存在，后端程序不需要任何修改。

一些特定应用的说明

启用 mTLS 后，并非所有客户端和服务都会“自动适配”——这取决于应用本身如何处理 TLS 连接和客户端证书。以下我遇见过的常见自建服务场景的实际表现与应对方式，供参考。

浏览器访问的 Web 应用

几乎所有基于浏览器的 Web 应用（包括但不限于我测试过的： Jellyfin、Immich、Nextcloud、Home Assistant、Photoprism、FileBrowser、Portainer、Traefik Dashboard、Vaultwarden、Bitwarden Web 等） 都会照常工作，就像 mTLS 不存在一样，服务端不需要任何配置。

现代浏览器（Chromium based、Firefox、Safari）在 TLS 握手阶段都能自动处理客户端证书。

诸如 Bitwarden 的浏览器插件也是如此，因为它们本身也就是一个 Web 页面。

原生 App

移动端 App 的证书处理能力差异很大，主要取决于其底层网络库：

• 基于 Android 原生 HttpURLConnection 或 OkHttp 的 App 都能自动调用 Android 系统级证书，无需额外配置。
• 自带独立 HTTP 客户端的 App（尤其是基于 Flutter、React Native 的应用）不走系统 TLS 证书存储，需要 App 开发者显式支持证书导入。例如基于 Flutter 开发的 Immich 在 App 的“设置” → “高级” 里有 “SSL 客户端证书”的导入选项。
• 基于 Web 的套壳 App 实际上大多使用的是 WebView，和浏览器访问一样。

你是否遇到过需要为不支持认证的服务添加认证的情况？TinyAuth 是一个轻量级的认证代理，可以帮助你为这些服务添加基本的认证。本文将介绍如何使用 TinyAuth 和 Traefik 实现简单的认证代理。

TinyAuth 支持包括 GitHub OAuth、简单密码认证在内的多种认证方式，这里我使用 Pocket ID 为例。

准备工作

在开始之前，请确保你已经正确配置了 Traefik，并且可以通过 Traefik 访问你的服务。如果你还没有配置 Traefik，可以参考 使用 Traefik 作为 Docker 的反向代理 进行配置。

此外，我这里使用 Pocket ID 作为认证方式，你可以自行选择其他认证方式，参考 TinyAuth 的文档。

现在假设有一个 echo 服务，需要添加认证，其域名是 echo.skyone.dev，我们需要在 .skyone.dev 下的任意子域名上部署 TinyAuth（与 echo 服务的域名在同一个域下），这里我使用 auth.skyone.dev。

在 Pocket ID 中注册应用

首先，你需要访问 Pocket ID 的管理面板，在 OIDC Clients 标签页中点击 Add OIDC Client。会出现一个新菜单，提示你提供一些信息。我们只需要设置其中的两个字段：

1. Client ID: 这是你的应用的唯一标识符，可以随意设置。
2. Redirect URI: 这是 TinyAuth 的回调地址，格式为 https://tinyauth.domain/api/oauth/callback/generic 。例如，我的回调地址是 https://auth.skyone.dev/api/oauth/callback/generic 。

其他的选项都可以保持默认。创建完成后，你会得到一个 Client ID 和 Client Secret，这两个值稍后会用到。

部署 TinyAuth

接下来，我们需要配置 TinyAuth。首先，创建一个名为 tinyauth 的 Docker Compose 文件，内容如下：

name: tinyauth

services:
  tinyauth:
    image: ghcr.io/steveiliop56/tinyauth:v3
    container_name: tinyauth
    restart: unless-stopped
    networks:
      - proxy
    env_file:
      - docker.env
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.tinyauth.rule=Host(`tinyauth.skyone.dev`)"
      - "traefik.http.routers.tinyauth.entrypoints=websecure"
      - "traefik.http.routers.tinyauth.service=tinyauth"
      - "traefik.http.services.tinyauth.loadBalancer.server.port=3000"
      - "traefik.http.middlewares.tinyauth.forwardAuth.address=http://tinyauth:3000/api/auth/traefik"

networks:
  proxy:
    external: true

这里需要修改的部分是 tinyauth.skyone.dev，将其替换为你自己的域名。

这里 labels 的最后一行为 Traefik 指定了一个中间件 tinyauth，这个中间件会在请求到达 tinyauth 服务之前进行认证，http://tinyauth:3000 是 TinyAuth 在容器内部的地址。

接下来，创建一个名为 docker.env 的环境变量文件，内容如下：

# --- Required Environment Variables ---
TINY_AUTH_DOMAIN="tinyauth.example.com"
POCKET_ID_DOMAIN="pocket-id.example.com"

POCKET_ID_NAME="Pocket ID"
SECRET=some-random-32-chars-string
GENERIC_CLIENT_ID="your-pocket-id-client-id"
GENERIC_CLIENT_SECRET="your-pocket-id-client-secret"

# --- DO NOT EDIT BELOW THIS LINE ---
APP_URL="https://${TINY_AUTH_DOMAIN}"
GENERIC_AUTH_URL="https://${POCKET_ID_DOMAIN}/authorize"
GENERIC_TOKEN_URL="https://${POCKET_ID_DOMAIN}/api/oidc/token"
GENERIC_USER_URL="https://${POCKET_ID_DOMAIN}/api/oidc/userinfo"
GENERIC_SCOPES="openid email profile groups"
GENERIC_NAME="${POCKET_ID_NAME}"

注释已经写得很清楚了，这里需要修改的部分是：

• TINY_AUTH_DOMAIN: TinyAuth 的域名。
• POCKET_ID_DOMAIN: Pocket ID 的域名。
• GENERIC_CLIENT_ID: 在 Pocket ID 创建应用时获得的 Client ID。
• GENERIC_CLIENT_SECRET: 在 Pocket ID 创建应用时获得的 Client Secret。
• POCKET_ID_NAME: Pocket ID 的名称，可以随意设置，不会影响功能。
• SECRET: 使用 openssl rand -hex 16 生成一个随机字符串，用于加密和签名。

编辑好 docker.env 后，运行 docker compose up -d 即可启动。

为 echo 服务启用认证代理

接下来，我们需要为 echo 服务添加 Traefik 的 labels，以便使用 TinyAuth 进行认证。echo 服务的 Docker Compose 文件如下：

name: echo

services:
  echo:
    container_name: echo
    image: luotianyi/echo:latest
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "tinyauth.domain=echo.skyone.dev"
      - "traefik.enable=true"
      - "traefik.http.routers.echo.entrypoints=websecure"
      - "traefik.http.routers.echo.rule=Host(`echo.skyone.dev`)"
      - "traefik.http.routers.echo.service=echo"
      - "traefik.http.services.echo.loadbalancer.server.port=5000"
      - "traefik.http.routers.echo.middlewares=tinyauth"

networks:
  proxy:
    external: true

只需要注意两行：

• tinyauth.domain=echo.skyone.host: 这里的域名需要与 echo 服务的域名一致。
• traefik.http.routers.echo.middlewares=tinyauth: 这行表示使用 TinyAuth 进行认证，这个中间件来自 tinyauth 容器的 labels。

你可以将这两行添加到你的任意需要认证的服务中，不需要别的操作即可实现认证。

测试认证

现在，你可以访问 https://echo.skyone.dev，会被重定向到 TinyAuth 的登录页面。登录后，你将被重定向回 echo 服务。

注意，这里 TinyAuth 生成的 Cookie 位于 .skyone.dev 域名下，这就是 TinyAuth 和 echo 服务需要在同一个域名下的原因。

权限管理

TinyAuth + Pocket ID 的组合可以实现简单的权限管理。你可以在 Pocket ID 的管理面板中为不同的用户分配不同的权限。

例如，我希望 echo 服务只能被 admin 组的用户访问，可以在 Pocket ID 的管理面板中创建一个 admin 组，并将用户添加到该组中。然后在 echo 服务的 labels 中添加以下行：

- "tinyauth.oauth.groups=admin"

完成，当用户访问 echo 服务时，TinyAuth 会检查用户是否属于 admin 组，如果不属于，则会被拒绝访问。

同样的，也可以通过用户的邮箱来限制访问，例如：

- "tinyauth.oauth.whitelist=user1@example.com,/@regex\\.com$/,user2@example.com"

可以看到，支持正则表达式（注意转义），还是很不错的。

通过这种方式，TinyAuth 不仅能提供统一的登录入口，还能与 Pocket ID 的用户和组管理结合，实现精细化的访问控制。

【完】

我一直使用 Cloudflare tunnel 来隐藏 Misskey 的 IP 地址，但是昨天晚上忽然想到，由于 misskey 是基于 ActivityPub 协议的，在服务器与其他服务器之间的通信中，IP 地址是公开的，如果攻击者构造了一个恶意的 ActivityPub 实现，马上就能拿到 Misskey 源站的 IP 地址。

想要避免这种情况，只能为 Misskey 的源站添加代理，而 Cloudflare Warp 就是一个不错的选择。本文根据大佬们的经验完成了 Misskey 的 Cloudflare Warp 配置。

Cloudflare Warp 简介

Cloudflare Warp 是 Cloudflare 提供的一个 VPN 服务，旨在提供更快、更安全的互联网连接。它通过 Cloudflare 的全球网络来加密和优化用户的网络流量，从而提高访问速度并保护用户隐私¹。

Warp 是限速的，为了获取不限量的 Warp+（速度更快），我们需要绑定 Cloudflare Zero Trust 的账号²。

准备工作

如果你决定不使用 Warp+，可以跳过这一步。

注册 Cloudflare 账号，如果你还没有 Cloudflare 账号，注册一个。

在 Cloudflare Zero Trust 中创建一个团队，登录 Cloudflare 后，访问 Cloudflare Zero Trust 并创建一个新团队。

在 Cloudflare Zero Trust 配置 Warp 为 Proxy 模式

找到 设置 -> WARP 客户端 -> 配置文件设置，如图所示

将服务模式改为“代理模式”，然后点击“保存更改”。

在 网络 -> Tunnels 中，点击“添加隧道”，创建一个 Warp 隧道，拿到 Warp 令牌（warp-cli connector new 后面的那一串字符串）。

构建 Warp 容器

确保你的服务器上安装了 Docker 和 Docker Compose。

下面是我的 docker-compose.yml 文件内容³：

services:
  cloudlare-warp:
    container_name: cloudflare-warp
    image: luotianyi/cloudflare-warp:latest
    restart: unless-stopped
    build:
      context: build
    volumes:
      - "./data:/app"
    environment:
      WARP_TOKEN: ChangeMe
    networks:
      - proxy

networks:
  proxy:
    external: true

将 WARP_TOKEN 替换为你在 Cloudflare Zero Trust 中获取的 Warp 令牌。

下面的 Dockerfile 放到 build 目录下：

FROM debian:bookworm-slim

WORKDIR /app
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        ca-certificates \
        curl \
        gnupg \
        lsb-release && \
    rm -rf /var/lib/apt/lists/*
RUN curl https://pkg.cloudflareclient.com/pubkey.gpg | gpg --yes --dearmor --output /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg && \
    echo "deb [arch=amd64 signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/cloudflare-client.list && \
    apt-get update && \
    apt-get install cloudflare-warp -y --no-install-recommends && \
    rm -rf /var/lib/apt/lists/* && \
    curl -L https://github.com/go-gost/gost/releases/download/v3.2.3/gost_3.2.3_linux_amd64.tar.gz -o gost.tar.gz && \
    tar -xzf gost.tar.gz -C /usr/local/bin/ && \
    rm gost.tar.gz /usr/local/bin/LICENSE /usr/local/bin/README.md /usr/local/bin/README_en.md
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

CMD ["/entrypoint.sh"]
VOLUME ["/app"]
EXPOSE 1080/tcp

下面是 entrypoint.sh ⁴，同样放在 build 目录下：

#!/usr/bin/env sh

nohup /usr/bin/warp-svc > /app/warp.log &

sleep 3

if [ -n "$WARP_TOKEN" ]; then
    echo "Using WARP token from environment variable"
    warp-cli --accept-tos connector new "$WARP_TOKEN"
    warp-cli --accept-tos connect
else
    echo "No WARP token provided, using default connector"
    warp-cli --accept-tos registration new
    warp-cli --accept-tos mode proxy
    warp-cli --accept-tos connect
fi

gost -L=http://:1080 -F=socks5://127.0.0.1:40000

解释一下这个容器的功能，它会后台启动 Cloudflare Warp 服务，然后使用 warp-cli 命令连接到 Cloudflare 的 Warp 网络。由于 Warp 只支持 socks5 协议，所以我们使用 gost 将其转换为 HTTP 代理，监听在 1080 端口。

实际上这个容器并不完善，因为使用了 nohup 命令来后台运行 warp-svc，在关闭容器时必然要等到超时强制 kill。不是很优雅的做法，但凑合用吧，不想折腾 s6-overlay 了。

启动容器 docker-compose up -d，然后让我们测试一下：

curl -x http://<warp-container-ip>:1080 https://ipinfo.io

应该会告诉你你的 IP 属于 Cloudflare Warp。

配置 Misskey 使用 Warp 代理

这一步非常简单，只需要在 Misskey 的配置文件中添加以下内容：

proxy: http://cloudflare-warp:1080

如果你修改了容器名，这里自行同步修改。

然后重启 Misskey 容器即可 docker restart misskey。打开浏览器，看看你的 Misskey 能不能获取其他服务器的信息吧。

如你所见，博客已经有一段时间没有更新了，今天抽空来除除草，也让大家这个网站还在持续更新。

最近工作比较忙，项目在赶进度，确实是没有多少时间来写博客。虽然如此，最近还是有一些事情可以分享的，那么就开一个新的系列「随笔」吧，不定期 记录最近做的有趣的事(实际上就是水文(。

N100 小主机

最近我买了一台 N100 的小主机，替换了我那工作了5年的树莓派4B。N100 是英特尔的低功耗处理器，性能比树莓派4B 强很多，而且同样功耗也很低。

目前配了 16G 内存 + 1T SSD 固态，运行着 Docker 和一些自建服务。外网访问用的是 WireGuard 组网 + 另外购买的 frp 服务。

密码管理器

对于密码管理，最开始我是直接记在C盘下的一个文件夹里的，后来觉得不安全，恰好那时候开始给 Git 提交上了 GPG 签名，就采用 GPG 加密的方式存储密码，这个方案一直到现在都是可用的。

但是这样做有两个显著的缺点：

1. 每次忘记密码都要去解密文件，比较麻烦。
2. 完全没有同步功能，密码只能存储在本地。最开始我就一台电脑，没有什么问题，去年又买了台台式机，经常为了查密码而切换电脑，比较麻烦。

于是，我调研了一下密码管理器，发现有很多不错的开源项目。

存密码的东西当然是优先用开源的啦，我最开始试的是 KeePassXC + Syncthing，确实没啥问题，但手机上每次密码变更都要手动打开 Syncthing 同步，还是比较麻烦。

这个月我试着将 KeePassXC 换成了 Bitwarden 的 Rust 实现 vaultwarden，使用 Docker 在自己的服务器上部署了一份，目前用起来还不错。compose 文件在 skyone-wzw/compose。

Bitwarden 的 Rust 实现 vaultwarden 轻量级很多，运行起来资源占用很小。它的更倾向于个人或小团队使用，没有 OSS 等大型组织的支持，由于其完全开源（包括在 Bitwarden 里需要购买许可证的功能），现在它在GitHub 上的 Star 已经超过原本的 Bitwarden 项目了。

Immich 私人相册

最近我还部署了一个私人相册，使用的是 Immich，这是一个开源的照片和视频备份解决方案，支持自动备份手机上的照片和视频。

警告

需要注意的是，Immich 目前正处于积极开发状态，并未稳定，可能出现破坏性变更，不建议将其作为唯一的备份方案。

Immich 比较吃配置，不太可能在云服务器上运行，我将其部署在上面提到的家里的 x86 小主机上。

实际用下来，网页端完全没问题，很好看，很像 Google Photos。而手机端一开始也挺不错的，支持按相册分类自动上传，上传后会自动加入云端对于的相册。然而，当我在另一部手机上也安装了 Immich 并登录同一个账号时，发现手机端的相册列表会变成「全部照片」，而不是之前的「相册」分类，并且会有一些 Bug，例如已经上传的照片会重复上传（虽然最后会自动合并），这让我有点不爽。不过毕竟是开发中，期待后续的改进。

Misskey

自从今年3月部署了 Misskey 之后，我就一直在用它作为个人的主要社交网络。欢迎大家关注我的 Misskey 账号 @skyone@social.akk.moe！

结语

最近的情况就是这样，希望能在接下来的时间里有更多的时间来写博客和分享有趣的事情。

封面图片来自 Pixiv 126375185

去年从 ext4 文件系统切换到了 btrfs，当时主要看中的是快照功能。最开始使用的是 timeshift，能用，但是可定制性不够，遂尝试 直接手动创建快照。

自从用了快照，最显著的变化是：折腾各种危险的东西再也不需要使用虚拟机，直接host开搞，最坏不过回滚一下快照，重新生成一下 GRUB，一个健康的系统就又回来了。

当然，快照大多了，就开始考虑怎么自动化，于是简单写了个脚本，试了一下还不错，放在本文后面了。

我使用的 ArchLinux 使用了如下的分区方案：

╭────────────┬────────┬───────┬────────┬────────────────╮
│ Mounted on │ Size   │ Type  │ Volume | Filesystem     │
├────────────┼────────┼───────┼────────┼────────────────┤
│ /          │ 937.6G │ btrfs │ @      | /dev/nvme0n1p4 │
│ /boot      │ 920.7M │ ext4  │        | /dev/nvme0n1p2 │
│ /boot/efi  │ 475.1M │ vfat  │        | /dev/nvme0n1p1 │
│ /home      │ 937.6G │ btrfs │ @home  | /dev/nvme0n1p4 │
╰────────────┴────────┴───────┴────────┴────────────────╯

我将快照保存在 Btrfs 根分区的 .snapshots 目录，就像这样：

[/]
├─ [@]
├─ [@home]
╰─ .snapshots
   ├─ [@-20250101] (ro)
   ╰─ [@home-20250101] (ro)

其中子卷使用 [] 表示。

日常使用不挂载 [/] 子卷，也就是说，无论怎么玩都不会破坏快照。

请注意！建议在 fstab 中不要指定 subvolid ，而是使用 subvol 直接指定子卷名称，这样恢复快照会更方便，下面的所有例子都以此为前提。

创建快照

当需要创建快照时，先挂载 [/] 子卷

mount -o compress=zstd:3,subvol=/ /dev/nvme0n1p3 /mnt

创建只读快照

btrfs subvolume snapshot -r /mnt/@ /mnt/.snapshots/@-`date +"%Y%m%d"`
btrfs subvolume snapshot -r /mnt/@ /mnt/.snapshots/@home-`date +"%Y%m%d"`

取消挂载 [/]

umount /mnt

恢复快照

可以通过修改 fstab 实现只重启两次即可恢复快照，不需要进入LiveCD模式。

具体思路是创建一个快照到 @-restore @home-restore

mount -o compress=zstd:3,subvol=/ /dev/nvme0n1p3 /mnt
btrfs subvolume snapshot /mnt/.snapshots/@-yyyymmdd /mnt/@-restore
btrfs subvolume snapshot /mnt/.snapshots/@home-yyyymmdd /mnt/@home-restore

编辑 /etc/fstab ，把 @ 子卷和 @home 子卷改成 @-restore 和 @home-restore。

这里修改 /etc/fstab 的作用是提示 grub 根分区的位置，而真正起作用的是 /mnt/@-restore/etc/fstab

cp /etc/fstab /mnt/@-restore/etc/fstab
grub-mkconfig -o /boot/grub/grub.cfg

重启电脑。

重启之后，再把两个子卷的名字改回去：

mount -o compress=zstd:3,subvol=/ /dev/nvme0n1p3 /mnt
btrfs subvolume delete /mnt/@
btrfs subvolume delete /mnt/@home
btrfs subvolume snapshot /mnt/.snapshots/@-yyyymmdd /mnt/@
btrfs subvolume snapshot /mnt/.snapshots/@-yyyymmdd /mnt/@home

编辑 /etc/fstab ，把 @-restore 子卷和 @home-restore 子卷改回 @ 和 @。

grub-mkconfig -o /boot/grub/grub.cfg

再次重启电脑。

重启之后，把临时的 restore 分区删了

mount -o compress=zstd:3,subvol=/ /dev/nvme0n1p3 /mnt
btrfs subvolume delete /mnt/@-restore
btrfs subvolume delete /mnt/@home-restore
umount /mnt

结束

恢复快照（LiveCD）

如果你的系统已经没办法引导了，也可以使用LiveCD恢复快照，这个过程甚至比上面的要简单。

进入LiveCD环境，修改 @ 和 @home 就结束了，什么配置都不用改。

mount -o compress=zstd:3,subvol=/ /dev/nvme0n1p3 /mnt
btrfs subvolume delete /mnt/@
btrfs subvolume delete /mnt/@home
btrfs subvolume snapshot /mnt/.snapshots/@-yyyymmdd /mnt/@
btrfs subvolume snapshot /mnt/.snapshots/@-yyyymmdd /mnt/@home
umount /mnt

重启即可。

快照脚本

自动创建快照，创建快照前会删除 Pacman 缓存，如果你不使用ArchLinux，请自行修改 make_snapshot 函数第2行为对应的包管理器

#!/usr/bin/env sh

set -e

run() {
    if [ -z "$is_fake" ] || [ "$is_fake" = false ]; then
        echo -e "sh: \033[1;32m$*\033[0m"
        sudo "$@" > /dev/null
    else
        echo -e "> \033[1;32m$*\033[0m"
    fi
}

make_snapshot() {
    NOW_DATE=$(date +"%Y%m%d")
    run pacman -Sc --noconfirm
    run mount -o compress=zstd:3,subvol=/ "$DEVICE" /mnt
    
    SNAPSHOT_FROM="/mnt/@"
    SNAPSHOT_TO="/mnt/.snapshots/@-$NOW_DATE"
    SNAPSHOT_NAME=".snapshots/@-$NOW_DATE"
    if [ "$is_fake" = false ] && sudo btrfs subvolume list /mnt -o | grep -q "$SNAPSHOT_NAME"; then
        run btrfs subvolume delete "$SNAPSHOT_TO"
    fi
    run btrfs subvolume snapshot -r "$SNAPSHOT_FROM" "$SNAPSHOT_TO"

    SNAPSHOT_FROM="/mnt/@home"
    SNAPSHOT_TO="/mnt/.snapshots/@home-$NOW_DATE"
    SNAPSHOT_NAME=".snapshots/@home-$NOW_DATE"
    if [ "$is_fake" = false ] && sudo btrfs subvolume list /mnt -o | grep -q "$SNAPSHOT_NAME"; then
        run btrfs subvolume delete "$SNAPSHOT_TO"
    fi
    run btrfs subvolume snapshot -r "$SNAPSHOT_FROM" "$SNAPSHOT_TO"

    run umount /mnt
}

DEVICE=$(findmnt -n -o SOURCE / | sed 's/\[.*\]//')

echo "List all devices"
df -h | grep nvme
echo -e "Selected device: \033[1;32m$DEVICE\033[0m"
echo
echo "Following commands will be executed:"
is_fake=true
make_snapshot

read -r -p "Are you sure? [y/N] " input
input=${input,,}
echo

if [ "$input" = "y" ]; then
    is_fake=false
    make_snapshot
fi

列出全部快照，会自动检查 @ 和 @home 的快照是否成对出现

#!/usr/bin/env sh

set -e

run() {
    echo -e "sh: \033[1;32m$*\033[0m"
    sudo "$@"
}

list_snapshots() {
    run mount -o compress=zstd:3,subvol=/ "$DEVICE" /mnt
    snapshot_dates=$(ls /mnt/.snapshots | grep '@-' | sed 's/@-//' | sort -u)
    
    if [ -z "$snapshot_dates" ]; then
        echo -e "\033[1;31mNo snapshots found.\033[0m"
        run umount /mnt
        return
    fi

    # Check if each date has a corresponding home snapshot
    for date in $snapshot_dates; do
        if ! ls /mnt/.snapshots | grep -q "@home-$date"; then
            echo -e "\033[1;33mWarning: No home snapshot for date $date!\033[0m"
        fi
    done

    # Display the list of dates
    echo -e "\n\033[1;32mSnapshots found for the following dates:\033[0m"
    for date in $snapshot_dates; do
        echo -e "\033[1;36m$date\033[0m"
    done

    run umount /mnt
}

DEVICE=$(findmnt -n -o SOURCE /home | sed 's/\[.*\]//')

echo "List all devices"
df -h | grep nvme
echo -e "Selected device: \033[1;32m$DEVICE\033[0m"
echo

list_snapshots

最近发现博客的评论系统后端有点问题，占用内存过于的大了（基于 Node.js + PostgreSQL，RES 内存占用 200MB+55MB），这不正常。而且我在国内的唯一一个服务器只有 2G 内存，很容易就被干满了。所以决定使用一个编译型语言重写一下。

最开始选的其实是 Golang，因为被网上传的 Rust 入门太难吓住了😂，试了一下发现 Golang 的 ORM 实在是太难用了，而且我非常讨厌 Golang 的语法，所以还是决定用 Rust 了。

挑选各种 crate

不得不说，Rust 确实有被吹的资格，在编译型无 GC 语言中，cargo这个包管理感觉能排进第一梯队。

另外，Rust 的很大基本功能也是在 crate 中实现，例如 异步运行时、随机数、加密、数据库等，都没有一个官方的实现，而是由社区维护的 crate 提供。

这么做可以说是有优点也有缺点，优点是社区可以更快的迭代，缺点是可能产生很多重复的工作，以及各个库之间需要手动糊在一起，不能统一接口。

最终我选择了以下 crate：

• 异步运行时：tokio

  这个没什么好说的，就俩选择，就挑了一个感觉更火的。

• 数据库：sqlx

  干简单活嘛，SQL 一共就没几句，用这个就足够了，不需要 ORM。但这个库有点坑，后面提到。

• 序列号：serde

  这个也没什么好说的，基本上以经成为既定标准了。

• HTTP 服务器：axum

  据说这个与 tokio 配合的很好，而且写起来符合我的习惯（或者说很像 express）。

• 模板引擎：tera

  据说用的是 jinja2 的语法，很出名。

嘛，主要就这些了，后面一些小工具陆陆续续加了点，提到的话再说。

一点小坑

由于是第一次写 Rust，很多东西都是边学边用，所以遇到了不少坑，这里简单记录一下。

sqlx 的坑

首先来拷打这个库，这个库的文档写地有点不清不楚，对 sqlx::query! 的在线模式的描述不够清楚，导致调试运行没问题，release 编译不通过。。。

在线模式指的是，在项目文件夹创建一个 .env 文件，里面配置 DATABASE_URL 环境变量，sqlx::query! 会读取这个环境变量，以提供实时的 SQL 语句检查和类型生成。这个 DATABASE_URL 的格式是 sqlite:C:/path/to/db.sqlite。

然而，这个 .env 文件不能添加到 git 里！这会导致 CI 里编译不通过！因为 CI 里并没有调试用的数据库，而如果想要生成这个数据库需要 cargo install sqlx-cli，编译一次需要十几分钟。。。

后来，在一个文档的拐角找的了：运行 cargo sqlx prepare 会生成一个 .sqlx 文件夹，把这个文件夹加到 git 里，在 CI 里编译的时候，sqlx 会读取这个文件夹里的配置以生成类型。

此外，SqliteConnectOptions::new().filename(database_path) 中的 database_path 并不是上面的 DATABASE_URL 那样的格式，而是数据库文件的路径 C:/path/to/db.sqlite 或相对路径 ./db.sqlite。试了半天才发现这个坑。

tera 的坑

我想要实现最终只有一个可执行程序，不需要别的资源文件，因此必须把模板文件编译进编译产物里。tera 的文档里没有内设这个功能，但是可以提供 include_dir! 这个宏配合 tera 的手动加载模板的功能实现。类似这样：

#[cfg(not(debug_assertions))]
static EMBED_TEMPLATE: include_dir::Dir = include_dir!("templates");

#[cfg(not(debug_assertions))]
pub fn make_template() -> Tera {
    let mut tera = Tera::default();
    for file in EMBED_TEMPLATE.files() {
        let name = match file.path().to_str() {
            Some(name) => name,
            None => continue,
        };
        let content = match file.contents_utf8() {
            Some(content) => content,
            None => continue,
        };
        if let Err(_) = tera.add_raw_template(name, content) {
            std::process::exit(1);
        }
    }
    tera
}

#[cfg(debug_assertions)]
pub fn make_template() -> Tera {
    Tera::new("templates/**/*").expect("Failed to load templates")
}

通过 cfg 宏来判断是否在 debug 模式下，如果是则从文件夹加载模板，否则从编译产物加载模板。兼具了开发和生产的需求。

嵌入静态资源

嵌入静态资源其实和嵌入模板差不多，只是需要让 axum 和 include_dir 配合。通过一个 /static/{*path} 路由来处理静态资源：

static EMBED_STATIC: include_dir::Dir = include_dir!("static");

pub async fn static_path(Path(path): Path<String>) -> impl IntoResponse {
    let path = path.trim_start_matches('/');
    let mime_type = mime_guess::from_path(path).first_or_text_plain();

    match EMBED_STATIC.get_file(path) {
        None => (StatusCode::NOT_FOUND, "Not Found").into_response(),
        Some(file) => {
            let body = file.contents();
            let mut header = HeaderMap::new();
            if let Ok(mine_type) = mime_type.to_string().parse() {
                header.insert(http::header::CONTENT_TYPE, mine_type);
            }
            #[cfg(not(debug_assertions))]
            if let Ok(cache_control) = "public, max-age=86400".parse() {
                header.insert(http::header::CACHE_CONTROL, cache_control);
            }
            (StatusCode::OK, header, body).into_response()
        }
    }
}

管理后台的身份认证

管理后台的身份认证我选择使用 HTTP Basic Auth，但是没找到合适的中间件，所幸这个功能并不复杂，也就自己试着写了一个，核心思想就是用 axum 提供的 axum::middleware::from_fn_with_state 简化编写中间件的复杂度，和写 header 其实差不多。

#[derive(Clone)]
pub struct BasicAuthorize {
    name: String,
    password: String,
}

impl BasicAuthorize {
    pub fn new(name: String, password: String) -> BasicAuthorize {
        BasicAuthorize { name, password }
    }

    pub async fn handler(
        State(state): State<BasicAuthorize>,
        request: Request,
        next: Next,
    ) -> impl IntoResponse {
        let auth = request.headers().get("authorization");
        if let Some(token) = auth {
            if let Ok(token) = token.to_str() {
                if token.starts_with("Basic ") {
                    let token = token.trim_start_matches("Basic ");
                    if let Ok(token) = base64::prelude::BASE64_STANDARD.decode(token.as_bytes()) {
                        if let Ok(token) = String::from_utf8(token) {
                            let parts: Vec<&str> = token.splitn(2, ':').collect();
                            if parts.len() == 2 {
                                if parts[0] == state.name && parts[1] == state.password {
                                    return next.run(request).await;
                                }
                            }
                        }
                    }
                }
            }
        }

        let mut headers = HeaderMap::new();
        headers.insert("WWW-Authenticate", "Basic".parse().unwrap());
        (http::StatusCode::UNAUTHORIZED, headers, "Unauthorized").into_response()
    }
}

然后和通过 axum::middleware::from_fn_with_state 注册这个中间件：

let auth = auth::BasicAuthorize::new(admin_username, admin_password);
let private_api = Router::new()
    .nest("/api/admin", admin::admin_routes())
    .layer(axum::middleware::from_fn_with_state(auth.clone(), auth::BasicAuthorize::handler));

还是挺直观的。

总结

首先讲讲个人感受，一句话：Rust 的学习难度不过如此嘛~。从0开始写一个简单的服务我只用了 2 天（业余时间）。

可以看出，Rust 确实融合了很多语言的特性，但这都不是事，因为：

• Rust 的所有权说的复杂，其实和 C++ 的智能指针差不多，只是 Rust 是强制性的。由于之前写过 V8 的拓展，对 RAII 也有些熟悉，所以这个没什么难度，只是需要适应思维的转变。
• Rust 的异步和 Kotlin 的协程差不多，看两眼就猜的出来。恰巧之前大量用过 Kotlin Coroutine，这一点基本没废什么时间。
• Rust 的模式匹配和函数式编程，但我写过 Haskell，满满的熟悉感。
• Rust 的 impl 和 trait 说实话让我想到了 Kotlin 的 Extension Function，只是 Rust 用 trait 替代了 interface。此外这和 Golang 的 interface 也有点像。我本身也是不太喜欢完全的 OOP，所以 Rust 的这种设计我还挺喜欢的。

总的来说，这次写这个服务还是挺顺利的，Rust 的文档和社区都很好，遇到问题基本上都能在网上找到答案。但是 Rust 的生态还是不够完善，很多库都是半成品，需要自己去糊在一起，这一点和 Node.js 的生态差距还是很大的。

通过这次对 comment-server 的重构，内存占用从 200MB+55MB 降到了 10MB，可以说是非常成功了。而且 Rust 的编译产物也非常小，只有 17MB （在内嵌模板和静态资源的情况下）。

偏点题，评论系统的前端使用 React + Material-UI。管理面板使用前面提到的 Tera 模板渲染，使用 TailwindCSS + daisyui。

以前一直觉得 React 更好，这次发现拿模板渲染真的快，4 个页面一小时就写好了。

通知系统用的是 TelegramBot ，简单方便。后续计划实现基于 Email 的回复通知。

【完】感谢阅读！

PeerTube 是一个自由开源的去中心化视频分享平台，它使用 WebTorrent 技术来实现 P2P 视频流传输。本来想用 PeerTube 来搭建一个视频分享平台，但是发现 PeerTube 的 Docker 部署文档有很多缺失的细节，所以写了这篇文章来记录一下 PeerTube 的 Docker 部署过程。

我已经搭建好了一个示例，大家可用访问 https://video.akk.moe 查看效果。

再贴一个 PeerTube 的嵌入式标签：

Docker Compose

我的 Docker Compose 文件是根据官方的 docker-compose.yml 修改而来的，官方的配置非常不实用 包含了很多不必要的配置，比如官方自定义了一个 nginx 容器，实在没必要；而且还用到了 PostFix 邮箱服务，一般人都不会用到。

下面是我的 Docker Compose 文件：

services:
  nginx:
    container_name: peertube-nginx
    image: nginx:alpine
    restart: "unless-stopped"
    networks:
      - proxy
      - peertube
    volumes:
      - "./nginx:/etc/nginx/conf.d"
      - "./logs:/var/log/nginx"
      - "./data:/var/www/peertube/storage"
      - "assets:/var/www/peertube/peertube-latest/client/dist:ro"
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.peertube.rule=Host(`video.example.com`)"
      - "traefik.http.routers.peertube.entrypoints=web"
      - "traefik.http.services.peertube.loadbalancer.server.port=9000"

  peertube:
    container_name: peertube
    image: chocobozzz/peertube:production-bookworm
    restart: "unless-stopped"
    networks:
      - peertube
    env_file:
      - docker.env
    #ports:
    #  - "1935:1935" # Comment if you don't want to use the live feature
    volumes:
      - "assets:/app/client/dist"
      - "./data:/data"
      - "./config:/config"
    depends_on:
      - database
      - redis

  database:
    container_name: peertube-database
    image: postgres:13-alpine
    restart: "unless-stopped"
    networks:
      - peertube
    env_file:
      - docker.env
    volumes:
      - "./database:/var/lib/postgresql/data"

  redis:
    container_name: peertube-redis
    image: redis:6-alpine
    restart: "unless-stopped"
    networks:
      - peertube
    volumes:
      - "./redis:/data"

networks:
  proxy:
    external: true
  peertube:
    name: peertube

volumes:
  assets:
    name: peertube-assets

主要修改了：

• 使用 nginx 容器代理，不再使用官方的 chocobozzz/peertube-webserver 容器，这样可用方便自定义 nginx 配置。
• 去掉了 PostFix 邮箱服务，直接使用外部 SMTP 服务。
• 去掉了 certbot 容器，直接使用 Traefik 的 Let's Encrypt 功能。
• 使用了 Traefik 代理，具体请看使用 Traefik 作为 Docker 的反向代理，当然你也可以使用其他代理。

要使用的话，只需要将 video.example.com 替换成你的域名。

下面是对应的 docker.env 文件：

# Postgres configuration
POSTGRES_USER=peertube
POSTGRES_PASSWORD=
POSTGRES_DB=peertube

# PeerTube configuration
PEERTUBE_DB_NAME=${POSTGRES_DB}
PEERTUBE_DB_USERNAME=${POSTGRES_USER}
PEERTUBE_DB_PASSWORD=${POSTGRES_PASSWORD}
PEERTUBE_DB_HOSTNAME=peertube-database
PEERTUBE_REDIS_HOSTNAME=peertube-redis

PEERTUBE_WEBSERVER_HOSTNAME=
PEERTUBE_TRUST_PROXY=["127.0.0.1/8", "loopback", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]

PEERTUBE_SECRET=

# E-mail configuration
PEERTUBE_SMTP_USERNAME=
PEERTUBE_SMTP_PASSWORD=
PEERTUBE_SMTP_HOSTNAME=smtp.office365.com
PEERTUBE_SMTP_PORT=587
PEERTUBE_SMTP_FROM=
PEERTUBE_SMTP_TLS=false
PEERTUBE_SMTP_DISABLE_STARTTLS=false
PEERTUBE_ADMIN_EMAIL=

PEERTUBE_OBJECT_STORAGE_UPLOAD_ACL_PUBLIC="public-read"
PEERTUBE_OBJECT_STORAGE_UPLOAD_ACL_PRIVATE="private"
PEERTUBE_WEBSERVER_HTTPS=true
#PEERTUBE_LOG_LEVEL=info

要修改的项目有：

• POSTGRES_PASSWORD：Postgres 数据库密码。
• PEERTUBE_SECRET：PeerTube 密钥，可以使用 openssl rand -hex 32 生成。
• 一些 SMTP 邮箱配置。
• PEERTUBE_TRUST_PROXY：可信任的代理 IP 地址，需要添加你的 docker daemon 的地址池，一般我给出的这个就够用了。
• PEERTUBE_WEBSERVER_HOSTNAME：PeerTube 的域名。
• PEERTUBE_ADMIN_EMAIL：管理员邮箱。PeerTube 会自动创建一个名为 root 的账户，使用此邮箱，一般不建议使用这个账户传视频，因此此邮箱可以随便填（只要邮箱的域名不会被有心人控制）。

这里默认你将 docker.env 和 docker-compose.yml 放在了 /app/path 目录下。

Nginx 配置

Nginx 的配置同样是从官方的 chocobozzz/peertube-webserver 中抄来的，做了如下修改：

• 去掉了 certbot 相关的 SSL 证书配置。
• 监听 9000 端口，由于专门用来代理 PeerTube，所以不需要填 server_name。

upstream backend {
    server peertube:9000;
}

server {
    listen 9000;

    access_log /var/log/nginx/peertube.access.log; # reduce I/0 with buffer=10m flush=5m
    error_log  /var/log/nginx/peertube.error.log;

    ##
    # Application
    ##

    location @api {
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;

        client_max_body_size  100k; # default is 1M

        proxy_connect_timeout 10m;
        proxy_send_timeout    10m;
        proxy_read_timeout    10m;
        send_timeout          10m;

        proxy_pass http://backend;
    }

    location / {
        try_files /dev/null @api;
    }

    location ~ ^/api/v1/videos/(upload-resumable|([^/]+/source/replace-resumable))$ {
        client_max_body_size    0;
        proxy_request_buffering off;

        try_files /dev/null @api;
    }

    location ~ ^/api/v1/users/[^/]+/imports/import-resumable$ {
        client_max_body_size    0;
        proxy_request_buffering off;

        try_files /dev/null @api;
    }

    location ~ ^/api/v1/videos/(upload|([^/]+/studio/edit))$ {
        limit_except POST HEAD { deny all; }

        # This is the maximum upload size, which roughly matches the maximum size of a video file.
        # Note that temporary space is needed equal to the total size of all concurrent uploads.
        # This data gets stored in /var/lib/nginx by default, so you may want to put this directory
        # on a dedicated filesystem.
        client_max_body_size                      12G; # default is 1M
        add_header            X-File-Maximum-Size 8G always; # inform backend of the set value in bytes before mime-encoding (x * 1.4 >= client_max_body_size)

        try_files /dev/null @api;
    }

    location ~ ^/api/v1/runners/jobs/[^/]+/(update|success)$ {
        client_max_body_size                      12G; # default is 1M
        add_header            X-File-Maximum-Size 8G always; # inform backend of the set value in bytes before mime-encoding (x * 1.4 >= client_max_body_size)

        try_files /dev/null @api;
    }

    location ~ ^/api/v1/(videos|video-playlists|video-channels|users/me) {
        client_max_body_size                      6M; # default is 1M
        add_header            X-File-Maximum-Size 4M always; # inform backend of the set value in bytes before mime-encoding (x * 1.4 >= client_max_body_size)

        try_files /dev/null @api;
    }

    ##
    # Websocket
    ##

    location @api_websocket {
        proxy_http_version 1.1;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   Upgrade           $http_upgrade;
        proxy_set_header   Connection        "upgrade";

        proxy_pass http://backend;
    }

    location /socket.io {
        try_files /dev/null @api_websocket;
    }

    location /tracker/socket {
        # Peers send a message to the tracker every 15 minutes
        # Don't close the websocket before then
        proxy_read_timeout 15m; # default is 60s

        try_files /dev/null @api_websocket;
    }

    # Plugin websocket routes
    location ~ ^/plugins/[^/]+(/[^/]+)?/ws/ {
        try_files /dev/null @api_websocket;
    }

    ##
    # Performance optimizations
    # For extra performance please refer to https://github.com/denji/nginx-tuning
    ##

    root /var/www/peertube/storage;

    # Enable compression for JS/CSS/HTML, for improved client load times.
    # It might be nice to compress JSON/XML as returned by the API, but
    # leaving that out to protect against potential BREACH attack.
    gzip              on;
    gzip_vary         on;
    gzip_types        # text/html is always compressed by HttpGzipModule
                      text/css
                      application/javascript
                      font/truetype
                      font/opentype
                      application/vnd.ms-fontobject
                      image/svg+xml;
    gzip_min_length   1000; # default is 20 bytes
    gzip_buffers      16 8k;
    gzip_comp_level   2; # default is 1

    client_body_timeout       30s; # default is 60
    client_header_timeout     10s; # default is 60
    send_timeout              10s; # default is 60
    keepalive_timeout         10s; # default is 75
    resolver_timeout          10s; # default is 30
    reset_timedout_connection on;
    proxy_ignore_client_abort on;

    tcp_nopush                on; # send headers in one piece
    tcp_nodelay               on; # don't buffer data sent, good for small data bursts in real time

    # If you have a small /var/lib partition, it could be interesting to store temp nginx uploads in a different place
    # See https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_temp_path
    #client_body_temp_path /var/www/peertube/storage/nginx/;

    # Bypass PeerTube for performance reasons. Optional.
    # Should be consistent with client-overrides assets list in client.ts server controller
    location ~ ^/client/(assets/images/(icons/icon-36x36\.png|icons/icon-48x48\.png|icons/icon-72x72\.png|icons/icon-96x96\.png|icons/icon-144x144\.png|icons/icon-192x192\.png|icons/icon-512x512\.png|logo\.svg|favicon\.png|default-playlist\.jpg|default-avatar-account\.png|default-avatar-account-48x48\.png|default-avatar-video-channel\.png|default-avatar-video-channel-48x48\.png))$ {
        add_header Cache-Control "public, max-age=31536000, immutable"; # Cache 1 year

        root /var/www/peertube;

        try_files /storage/client-overrides/$1 /peertube-latest/client/dist/$1 @api;
    }

    # Bypass PeerTube for performance reasons. Optional.
    location ~ ^/client/(.*\.(js|css|png|svg|woff2|otf|ttf|woff|eot))$ {
        add_header Cache-Control "public, max-age=31536000, immutable"; # Cache 1 year

        alias /var/www/peertube/peertube-latest/client/dist/$1;
    }

    location ~ ^(/static/(webseed|web-videos|streaming-playlists/hls)/private/)|^/download {
        # We can't rate limit a try_files directive, so we need to duplicate @api

        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;

        proxy_limit_rate 5M;

        proxy_pass http://backend;
    }

    # Bypass PeerTube for performance reasons. Optional.
    location ~ ^/static/(webseed|web-videos|redundancy|streaming-playlists)/ {
        limit_rate_after            5M;

        set $peertube_limit_rate  5M;

        # Use this line with nginx >= 1.17.0
        limit_rate $peertube_limit_rate;
        # Or this line with nginx < 1.17.0
        # set $limit_rate $peertube_limit_rate;

        if ($request_method = 'OPTIONS') {
          add_header Access-Control-Allow-Origin  '*';
          add_header Access-Control-Allow-Methods 'GET, OPTIONS';
          add_header Access-Control-Allow-Headers 'Range,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
          add_header Access-Control-Max-Age       1728000; # Preflight request can be cached 20 days
          add_header Content-Type                 'text/plain charset=UTF-8';
          add_header Content-Length               0;
          return 204;
        }

        if ($request_method = 'GET') {
          add_header Access-Control-Allow-Origin  '*';
          add_header Access-Control-Allow-Methods 'GET, OPTIONS';
          add_header Access-Control-Allow-Headers 'Range,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
        }

        # Enabling the sendfile directive eliminates the step of copying the data into the buffer
        # and enables direct copying data from one file descriptor to another.
        sendfile on;
        sendfile_max_chunk 1M; # prevent one fast connection from entirely occupying the worker process. should be > 800k.
        aio threads;

        # web-videos is the name of the directory mapped to the `storage.web_videos` key in your PeerTube configuration
        rewrite ^/static/webseed/(.*)$ /web-videos/$1 break;
        rewrite ^/static/(.*)$         /$1        break;

        try_files $uri @api;
    }
}

一个字都不用改，所以直接复制粘贴即可，放到 /app/path/nginx/peertube.conf。

登录 PeerTube 网页

上面的配置弄完直接 docker-compose up -d ，这里不多说，下面讲讲怎么使用。

访问你的 PeerTube 网页，PeerTube 在首次启动时会自动创建一个名为 root 的账户，密码通过 docker logs peertube | head -n 50 可用找到，该账户的邮箱是你在 docker.env 中填的 PEERTUBE_ADMIN_EMAIL。

先用这个账户登录，在设置中修改密码，然后创建一个新账户，这个账户就是你的主账户，可以上传视频，记得将这个账户设置为管理员。

然后就可以退出 root 账户，登上新创建的账户，上传头像、设置 banner ...... 等的装饰性操作。

再创建一个频道，PeerTube 的视频是以频道为容器的，所以你需要先创建一个频道，然后再上传视频。

主页面可用使用 markdown 编写，下面是我写的一个例子，只需要将网站名字替换一下即可：

本网站使用使用 PeerTube 搭建的个人测试视频站，名为 **XXXTube**。

请注意，使用此网站即代表您同意 [XXXTube 隐私政策](/about/peertube)。

This website is a personal test video site powered by PeerTube, called **AkkTube**.

Please note that by using this site you agree to the [XXXTube Privacy Policy](/about/peertube).

<peertube-container data-layout="col" data-title="本地视频" data-description="只包含在本网站上传的视频">
  <peertube-videos-list data-count="10" data-only-local="true" data-max-rows="4"></peertube-videos-list>
</peertube-container>

看起来不错~

【完】

写了很多 Next.js 的代码，总结了一下 Server Component 和 Client Component 的规律，希望对后来者有用。如果有错误，欢迎大佬指正！

如何区分Client Component？

我总结了以下规律，可以快速区分一个组件是否为服务端组件：

1. 默认导出（export default）为 async 函数的组件为 Server Component。
2. 标记了 use client; 的源文件里的组件都是 Client Component。
3. 其余情况下，组件既是 Server Component 也是 Client Component。也就是说，既可以在服务端运行，又可以在客户端运行。为了方便描述，下面我将这种组件称为 Server/Client Component

我们知道 Next.js 官方说的是 “在 App Router 下不标明 use client 的为 Server Component”，但是我强烈建议**任何不应该被发送到客户端的 Server Component 都加上 async ，即使该组件没有用到异步逻辑！**原因下一节提到。

正确使用 Server Component

我们都知道，Server Component 不能访问浏览器 API（如 window 对象），也不能使用常规 React Hook，这一点理所当然，不在这里赘述。

顾名思义，Server Component 就是在服务端运行的组件，可以访问浏览器端不存在的Node API，例如连接数据库等。

这些服务端操作通常是异步的，所以 Next.js 允许我们的 Server Component 返回 Promise，而 Client Component 则不行。因此，加上 async 可以保证我们的组件（以及组件内部的变量）永远不会被发送到 Client。如下面的例子：

interface User {
    name: string;
    email: string;
}

interface Props {
    user: User;
    content: string;
}

async function UserComment({comment}: Props) {
    const {user, content} = comment;
    return (
        <dir>
            <p>{user.name}</p>
            <img src={gravatarUrl + tools.md5(user.avatar)}/>
            <p>{content}</p>
        </dir>
    );
} 

显然，这个函数没有用到异步逻辑，但是，我将其标为 async ，为什么呢？我们不能把评论者的 email 暴露出来，只是通过 email 的 md5 显示 gravatar 头像。

如果不添加 async ，而这个组件因为某种原因（后面会将）被当作 Client Component，这个组件的参数当然也会一并被发送到浏览器，评论者的邮箱就暴露了！

而一旦添加了 async ，这个组件就只能是 Server Component，里面的数据不存在泄漏到客户端的风险。

还有一点，上面的例子中，tools.md5 一般都是 Node API 实现的，显然只能在 Server Component 中运行，添加 async 也能帮助你排除错误。一旦你试图在 Client Component 里使用 Server Component，Next.js 就会立刻向你报错。而当你在 Client Component 里使用 Server/Client Component （既可以作为 Server Component 又可以作为 Client Component 的组件）时，Next.js 只会在运行时向你报错“我在浏览器里找不到 crypto 包啊”。

正确使用 Browser API

何时使用浏览器API？Next.js 官方告诉我们，只有在标记了 "useclient" 的组件里才能使用浏览器 API。然而我觉得这句话并不十分正确，就像下面的代码一定会报错：

"use client";

function Demo() {
    // 找不到 window 对象
    window.alert("233")
    
    return <p>233</p>
}

为什么报错？所谓 Client Component 并不是一定在浏览器里运行的，实际上，Client Component的首次渲染在服务端，Node当然找不到 window.alert。Next.js 的对 Client 的处理是：只运行一遍主要逻辑，不运行Hook。也就是说，useEffect 里的函数是确确实实在浏览器运行的，因此，这段代码应该改成：

"use client";

function Demo() {
    useEffect(() => {
        window.alert("233");
    });
    
    return <p>233</p>
}

我相信下面这个例子一定能帮你理解：

"use client";

function Counter() {
	const [count, setCount] = useState(0);
    const handleClick = useCallback(() => setCount(prev => prev + 1), []);
    
    useEffect(() => {
        console.log("始终在浏览器终端");
    });
    
    console.log(`count = ${count}`);
    
    return (
        <div>
            <p>{count}</p>
            <button onClick={}>Click me</button>
        </div>
    );
}

直接放到 /src/app/page.tsx ，打开网页并点几下按钮，观察一下控制台。

其中服务端控制台会显示一次 count = 0，只会的都显示在浏览器控制台。而 "始终在浏览器终端" 则只会在浏览器控制台显示。

除了 Hook，浏览器 API 还能在一切”副作用“中使用。什么是副作用呢？比如说用户点击按钮产生的事件、监听用户鼠标移动产生的事件等等。也就是说，onClick 、onChange 等里面也可以使用浏览器 API。

相互调用

Server Component 能不能调用 Client Component？反过来行不行？答案是：Server Component 能调用 Client Component，Client Component 不能直接调用 Server Component。

还是以例子来说明，例如下面的 Server Component 能调用 Client Component：

async function SomeServerComponent() {
    // ...
    return <SomeClientComponet props={props}/>;
    // props 不能传递 function 等不可序列化的数据
}

下面的 Client Component 不能调用 Server Component：

"use client";

function SomeClientComponent() {
    // ...
    return <SomeServerComponet/>; // ❌ 错误
}

而Client Component 能使用作为参数传递的、已经实例化的 Server Component：

// SomeServerComponent.tsx
export default async function SomeServerComponent() {
    return <p>SomeServerComponent</p>;
}

// SomeClientComponent.tsx
"use client";

interface Props {
    children: ReactNode;
}

export default function SomeClientComponent({children}: Props) {
    return (
        <DataProvider>
            {children}
        </DataProvider>
    );
}

// somepage/layout.tsx
export default async function SomePageLayout() {
    return (
    	<SomeClientComponent> {/* SomePageLayout 使用 Client Component */}
            <SomeServerComponent/>
            {/* SomePageLayout 使用 Server Component 并将结果传递给 Client Compoent */}
        </SomeClientComponent>
    )
}

例子中 SomePageLayout 使用 Server Component 并将结果传递给 Client Compoent，因为ReactNode本身是可以序列号的，所以 SomePageLayout 作为 Server Component 可以调用 Server Component 并将其结果序列化后传递给 Client Compoent。

Server/Client Component

最后来讲讲我第一节定义的 Server/Client Component，它是既可以作为 Server Component 又可以作为 Client Component 的组件，可以实现服务端客户端的逻辑共用，但代价是什么呢？Server/Client Component 继承了 Server Component 和 Client Component 的全部限制。

具体来说：Server/Client Component 不能使用 Browser API 和 Hook（因为可以在服务端运行），不能使用 Node API（因为可以在客户端运行）。

也就是说，Server/Client Component 只能做从数据到 dom 树的转化，不能获取数据，不能拥有状态，也不能持有包含隐私的数据。

正是因为这么多限制，Server/Client Component 可以在 Server Component 和 Client Component 中随意使用。它就是个纯函数，或者说从 data 到 ReactNode 的 Map。

【完】

在上一篇文章 使用 YubiKey 解密 LUKS 分区 之后我发现了两个问题：

• 使用 Yubikey FIDO2 解密并不稳定，有时候还算要使用密码解密
• 有时候强制使用 Yubikey 解密，不支持回退到密码解密

最近又查看了一下 ArchWiki¹，最终解决了以上两个问题。写下这篇文章以作记录。

计划分盘

由于GRUB只识别基础的文件系统，解密根分区任务位于 initramfs 之中，因此内核镜像和 initramfs 不能被加密。具体步骤是：

• UEFI 识别到 /dev/sda1 下的 /EFI/arch/grubx64.efi ，将控制权交给 grub
• grub 根据 /dev/sda2 下的 /grub.cfg 显示引导选项，选择 arch 后使用 /dev/sda2 下的内核镜像和 initramfs 调用内核
• initramfs 下的内核使用 initramfs 中的 /etc/crypttab 提示用户解密分区
• initramfs 下的内核使用 /dev/mapper/system 中的 /etc/fstab 挂载分区，引导结束

本次分区假设如下²：

/dev/sda1 1GB   -> /boot/efi FAT32
/dev/sda2 500MB -> /boot     FAT32
/dev/sda3 other -> /dev/mapper/system btrfs
                   |- /
                   |- /@          -> /
                   |- /@home      -> /home
                   |- /.snapshots

进行之前先确保已经能使用密码解密系统，具体参考使用 YubiKey 解密 LUKS 分区。

配置 Yubikey

首先安装相关依赖³，然后将 Yubikey 插入电脑，检查是否出现 /dev/hidrawX 设备，完成后将 Yubikey FIDO2 插入密钥槽：

systemd-cryptenroll --fido2-device=auto /dev/sda3

可选参数：

配置 crypttab

编辑 /etc/crypttab.initramfs ，systemd 会将这个文件打包到 initramfs 的 /etc/crypttab

# name  device                                     password  options
system  UUID=2f9a8428-ac69-478a-88a2-4aa458565431  none      fido2-device=auto,token-timeout=30

意思是：使用 FIDO2 设备将 /dev/sda3 解密到 /dev/mapper/system ，如果超过 30 秒未使用 FIDO2 设备则回退到密码解密。

• fido2-device=auto 指定使用 FIDO2 密钥解密
• token-timeout=30 超过 30 秒未使用 FIDO2 则回退到密码解密（token-timeout in systemd man page）

配置 initramfs

BusyBox 模式下并不支持这些功能⁴，我们需要改用 systemd 模式。幸好这个过程并不复杂。

编辑 /etc/mkinitramfs.conf ，修改其中的 HOOKS （参考 dm-crypt/System configuration#mkinitramfs），要确保：

• 如果包含 keymap 或 consolefont ，去掉，就地换成 sd-vconsole
• 如果包含 udev ，就地换成 systemd
• 如果包含 encrypt ，就地换成 sd-encrypt ，否则在 sd-vconsole 之后加上 sd-encrypt

重新生成 initramfs

mkinitramfs -p linux

修改内核参数

如果你之前配置过 luks 相关的内核参数，需要修改一下。

编辑 /etc/default/grub ，修改其中的 GRUB_CMDLINE_LINUX ，与 luks 相关的 cryptdevice 等参数全部删掉，因为这是用于 encrypt hook 的，而我们现在用的是 sd-encrypt hook，这个 hook 会自动识别 /etc/crypttab 中的配置（由 systemd 自动从 /etc/crypttab.initramfs 复制到 initramfs 中的 /etc/crypttab ）。

只需要保留 root=/dev/mapper/system 即可。例如

GRUB_CMDLINE_LINUX="root=/dev/mapper/system rw loglevel=3 quiet"

这里的 /dev/mapper/system 不需要使用 UUID，因为这个是由我们 /etc/crypttab 中的 name 指定的，不会改变。

改完记得 grub-mkconfig -o /boot/grub/grub.cfg 。

去年11月我写了一篇ArchLinux安装GNOME桌面，也正是那时候我将电脑的主要系统从Windows转到了ArchLinux。诚然， gnome 很好，如果你需要一个不需要折腾就能用的桌面环境，那么 gnome 是一个不错的选择。

我一开始也是这么想的，直到……今年 KDE Plasma 6 发布了。我不得不说，KDE Plasma 6 的演示视频真的很吸引人，所以我决定尝试一下，于是我又折腾了一遍系统，这次安装的是 KDE Plasma 桌面。新的大版本发布，肯定有大量的问题，尤其是搭配 NVIDIA 和 Wayland 这两个离谱的玩意。Wayland 由于 x11 历史包袱太重，经常出现兼容问题（尤其是 Chromium），而 NVIDIA 一直以来都是 Linux 用户的痛点，Linus 骂的一点都不冤。

现在新系统用了也有一段时间了，是该动笔记录一下，免得下次装又到处找资料。这次文章分两部分：安装 KDE Plasma 桌面和常见问题解决。欢迎大家在评论区补充。

安装 KDE Plasma 桌面

Arch Linux 的安装已经老生常谈了，见安装 ArchLinux & Windows 双系统。这里只记录安装 KDE Plasma 桌面的步骤。

首先，经过一系列的安装步骤，你应该已经进入了 ArchLinux 命令行，并有了一个属于 wheel 组的非 root 用户。接下来，我们就可以安装 KDE Plasma 桌面了。

sudo pacman -S plasma-meta sddm networkmanager bluez-utils

官方提供了多个包，plasma-meta 是一个元包，包含了 KDE Plasma 桌面的所有组件基本组件。此外，你也可以选择 plasma 包组，它包含的软件和 plasma-meta 是一样的，关于元包和包组的区别，可以参考ArchWiki | Meta package and package group。还有两个可选的包：kde-applications 和 kde-applications-meta，它们包含了一些额外的应用程序，比如 Dolphin 文件管理器、Konsole 终端等。但是这里我选择后续自己安装需要的应用程序。

sddm 是 KDE Plasma 的默认登录管理器，networkmanager 是网络管理器，bluez-utils 是蓝牙管理工具。

不要急着启动桌面，这时候我们还没安装终端模拟器，进去就出不来了（笑）。接下来我们安装终端模拟器、文件管理器。

sudo pacman -S konsole dolphin

konsole 是 KDE Plasma 的终端模拟器，dolphin 是 KDE Plasma 的文件管理器。

接下来我们启用 sddm 服务，这样就会直接进入 KDE Plasma 桌面了。

sudo systemctl enable --now sddm

在桌面环境下打开 konsole 终端，启动 networkmanager 和 bluetooth 服务。

sudo systemctl enable --now NetworkManager bluetooth

常见配置

中文字体

我推荐 noto-fonts-cjk，它是 Google 的开源字体，支持中日韩文。此外，noto-fonts-emoji 是支持 emoji 表情的字体，noto-fonts-extra 是支持更多语言的字体。

sudo pacman -S noto-fonts-cjk noto-fonts-emoji noto-fonts-extra

然后进入系统设置，把语言设置为中文，注销重新登录。

一些常用程序推荐

• 浏览器：Firefox firefox、firefox-i18n-zh-cn 或 Chromium chromium，我选择两个都要~
• 图片查看器：Gwenview gwenview
• 多媒体播放器：VLC vlc
• 文本编辑器：Kate kate
• 截屏工具：Spectacle spectacle
• 压缩包管理器：Ark ark
• DNS 工具：bind bind，提供 dig, nslookup 等命令
• 以及其他的命令行工具就不解释了，只是提一下，iwd、jq、htop、duf、bat、pkgfile、unzip

输入法

最重要的当然是输入法了，我使用 fcitx5。

sudo pacman -S fcitx5 fcitx5-chinese-addons fcitx5-qt fcitx5-gtk fcitx5-configtool

网上一堆教程全是基于 x11 的，到了 wayland 就不好使了。我自己试了很久，过程如下：

在设置的 “键盘” - “虚拟键盘” 里面选择 fcitx5 即可让输入法自动启动，编辑 /etc/environment 文件，添加：

XMODIFIERS=@im=fcitx
SDL_IM_MODULE=fcitx

注意不要包含 GTK_IM_MODULE 和 QT_IM_MODULE，这是 x11 的设置，wayland 不需要，如果有的话，注释掉。

设置里 “语言和时间” - “输入法” 添加简体中文即可，甚至不需要注销即可使用。

在最新的 chromium 里，一开始出现的无法输入中文的问题已经解决了，不需要特殊处理。

万恶的 NVIDIA 驱动

尽管 Arch Linux 提供里开箱即用的 NVIDIA 驱动包，但在 plasma + wayland 仍然有问题。首先安装 nvidia 驱动：

sudo pacman -S nvidia

这时一定不要重启，否则会进不去桌面。先创建 /etc/modprobe.d/nvidia_drm.conf 文件，添加：

options nvidia-drm modeset=1

再编辑 /etc/mkinitcpio.conf 文件，修改 HOOKS 行，将 kms 去掉，然后重新生成 initramfs：

sudo mkinitcpio -P

最后重启电脑，应该就可以进入 KDE Plasma 桌面了。

kvm 虚拟机

尽管日常生活大部分工作都可以在 Linux 下完成，但有时候还是需要 Windows 的，比如 Office 就无可替代。我使用 virt-manager + qemu + kvm 来运行 Windows 虚拟机。

sudo pacman -S qemu-full libvirt virt-manager dnsmaq

其中 qemu-full 包含了全部的 qemu 组件，比较省事，反正也没多大；libvirt 是虚拟化管理工具的后端；virt-manager 是图形化的虚拟机管理工具；dnsmaq 是 DNS 服务器，用于虚拟机的网络。

将自己加入 libvirt 组，这样就不用每次都 sudo 了：

sudo usermod -aG libvirt $USER

启动 libvirtd 服务：

sudo systemctl enable --now libvirtd

之后就可以打开 virt-manager 创建虚拟机了，顺便写写如何在 virt-manager 下安装 Windows 10 LTSC。

Windows 10 LTSC 虚拟机

首先下载 Windows 10 LTSC 镜像，然后打开 virt-manager，点击 “创建新虚拟机”，选择 “本地安装媒体”，选择下载的镜像文件。

选择引导为 UEFI，系统类型选择 Windows 10，内存和 CPU 根据自己的电脑配置选择，其中 CPU 的拓扑从上到下分别是 sockets（指的是 CPU 插槽）、cores（指的是 CPU 核心）、threads（指的是 CPU 线程），比如我的电脑是 6 核 12 线程，那么我选择 1、6、12。

硬盘选择 qcow，类型设置为 virtio，也就是半虚拟化的硬盘，性能非常出色。

网络我选择 nat。

还需要准备一个 virtio 驱动，下载地址：Fedora VirtIO Drivers ISO，在虚拟机设置里添加一个光驱，选择这个 ISO 文件。

整个安装过程基本和实体机一样，但在选择安装位置的时候，需要先加载 virtio for win10 x64 驱动，然后才能看见硬盘。

安装完成后还要进入刚刚挂载的 virtio 驱动光盘，安装 virtio 网卡驱动，不然网络无法使用。以及显卡驱动 qxldod，不然分辨率很低。安装 spice 驱动，可以让虚拟机和宿主机共享剪贴板。安装 qeumu-guest-agent，可以让虚拟机和宿主机通信。

常见问题解决

无法进入桌面

上面的安装 KDE Plasma 桌面里提到了，安装完 NVIDIA 驱动后，一定要修改 /etc/modeprobe.d/nvidia_drm.conf 文件，添加：

options nvidia-drm modeset=1

如果还是没有效果，按键盘 Ctrl + Alt + F2 进入命令行，登录后执行：

cat /sys/module/nvidia_drm/parameters/modeset

如果返回 N，则说明没有生效，执行，那就换个方案，删除 /etc/modeprobe.d/nvidia_drm.conf 文件，然后编辑 /etc/default/grub 文件，修改 GRUB_CMDLINE_LINUX_DEFAULT 行，在引号里添加：

nvidia-drm.modeset=1

然后更新 grub 配置：

sudo grub-mkconfig -o /boot/grub/grub.cfg
# 这里的路径根据自己的系统配置而定，也可能是 /boot/efi/grub/grub.cfg

重启电脑，应该就可以进入 KDE Plasma 桌面了。

无法输入中文

如果实在无法输入中文，可以尝试按照 x11 的方式配置，尽管不推荐，但是仍然可以使用。具体来说，编辑 /etc/environment 文件，添加：

GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx
XMODIFIERS=@im=fcitx
SDL_IM_MODULE=fcitx

在设置里 “自动启动” 里添加 fcitx5，然后注销重新登录。

gpg 导致关机时间很慢

经过多次测试，确认是 KDE 的 gpg GUI kleopatra 无法正常退出导致的。这个目前没法解决，只能等待修复，在这之前要么关机前手动退出 kleopatra，要么卸载 kleopatra。

卸载了 kleopatra git 的签名就无法验证了，需要额外安装 pinentry：

sudo pacman -S pinentry

在 ~/.gnupg/gpg-agent.conf 文件中添加：

pinentry-program /usr/bin/pinentry-qt

备注

本文是 MDN | @scope 的翻译，并根据我自己的理解进行了适当地修改和补充。采取与原文相同的许可证。

截至 2025 年 5 月，Firefox 仍然不支持 @scope 规则，但是 Chrome 与 Safari 已经支持。详情查看 Can i use @scope。

@scope 可以让我们精确的定位 DOM 子树中的元素，而无需编写难以覆盖的过于特定的选择器，并且不会将选择器与 DOM 结构耦合得太紧密。

在 JavaScript 里，可以使用 CSSScopeRule 访问 @scope 规则。

语法

@scope 包含一个或多个规则集（称为作用域样式规则），并定义将它们应用于选定元素的范围。 @scope 可以通过两种方式使用：

1. 像其他 at 规则一样，作为 CSS 中的独立块，可以指定规则的作用域上限和下限。

   @scope (scope root) to (scope limit) {
     rulesets
   }
   

2. 作为内联样式（ <style> 标签内的样式）包含在 HTML 中的，在这种情况下，两个限定参数可以被省略，并且包含的规则集自动将范围限定为 <style> 元素的封闭父元素。

   <parent-element>
     <style>
       @scope {
         rulesets
       }
     </style>
   </parent-element>
   

描述

复杂的 Web 文档可能包括页眉、页脚、新闻文章、地图、媒体播放器、广告等组件。随着复杂性的增加，有效管理这些组件的样式变得更加困难，而通过限定样式的范围有助于我们管理这种复杂性。让我们考虑以下 DOM 树：

body
└─ article.feature
   ├─ section.article-hero
   │  ├─ h2
   │  └─ img
   │
   ├─ section.article-body
   │  ├─ h3
   │  ├─ p
   │  ├─ img
   │  ├─ p
   │  └─ figure
   │     ├─ img
   │     └─ figcaption
   │
   └─ footer
      ├─ p
      └─ img

如果想选择带有 article-body 类的 <section> 内的 <img> 元素，可以执行以下操作：

• 编写一个选择器，例如 .feature > .article-body > img。然而，它具有很高的特异性，因此很难被覆盖，并且与 DOM 结构紧密耦合。如果 DOM 结构发生变化，可能需要重写 CSS。

• 写一些不太具体的内容，例如 .article-body img。但是，这将选择该部分内的所有图像。我们的目的是选择 <section> 的直接子级 <img> ，但是 figure 内的 img 也符合这个 CSS 选择器。

这就是 @scope 有用的地方。它可以定义一个精确的范围，让 CSS 选择器只作用于这个范围之内。例如，上述问题可以这么解决：

@scope (.article-body) to (figure) {
  img {
    border: 5px solid black;
    background-color: goldenrod;
  }
}

由于 .article-body 指定了 CSS 规则生效的上限，而 <figure> 指定了下限。CSS 规则只作用于 .article-body 与 <figure> 之间的元素，不会选择 <figure> 元素内的元素。

备注

这种具有上限和下限的范围通常称为环形范围。

如果你想选择带有 article-body 类的 <section> 内的所有图像，也可以省略范围限制：

@scope (.article-body) {
  img {
    border: 5px solid black;
    background-color: goldenrod;
  }
}

或者，你可以采用刚刚提到的第二种写法，将 @scope 块内联包含在 <style> 元素内，该元素又位于 <section> 内：

<section class="article-body">
  <style>
    @scope {
      img {
        border: 5px solid black;
        background-color: goldenrod;
      }
    }
  </style>

  <!-- ... -->
</section>

重要

需要注意的是，虽然 @scope 将选择器的应用隔离到特定的 DOM 子树，但它并不能完全隔离这些子树内应用的样式。这在继承中最为明显——子级继承的属性（例如颜色或字体系列）仍然会被继承，超出任何设置的范围限制。

:scope 伪类

在 @scope 块的上下文中，:scope 伪类代表作用域根，它提供了一种从作用域内部将样式应用到作用域根本身的简单方法：

@scope (.feature) {
  :scope {
    background: rebeccapurple;
    color: antiquewhite;
    font-family: sans-serif;
  }
}

事实上，会被 :scope 隐式地添加到所有作用域样内的式规则的前面。也就是说，任何 @scope 作用域内的 CSS 选择器前面都会被浏览器自动加上 :scope ，但是不计入 CSS 特异性。

以下的三条规则是等价的 （但特异性不相等，查看@scope 的特异性）：

@scope (.feature) {
  img { ... }

  :scope img { ... }

  & img { ... }
}

注意事项

• 范围限制可以使用 :scope 来指定范围限制和根之间的特定关系要求。例如：

  /* 指定下限为 .article-body 的直接 figure 子级 */
  @scope (.article-body) to (:scope > figure) { ... }
  

• 范围限制可以使用 :scope 引用范围根之外的元素，也就是说上下限都是单纯的 CSS 选择器，并不要求下限必须从上限开始选择。例如：

  @scope (.article-body) to (.feature :scope figure) { ... }
  

• 下限必须是上限的子孙元素（原文是：Scoped style rules can't escape the subtree）。像 :scope + p 这样的选择是无效的，因为该选择将位于上限的子树之外。

• 选择器的上限可以指定多个，在这种情况下将视为定义多个范围。在以下示例中，样式将应用于 <section> 内具有 article-hero 或 article-body 类的任何 <img>，而如果 <img> 嵌套在 <figure> 内，则不会被选中：

  @scope (.article-hero, .article-body) to (figure) {
    img {
      border: 5px solid black;
      background-color: goldenrod;
    }
  }
  

@scope 的CSS特异性

简单来说， @scope 不会改变其内部规则的特异性，例如：

@scope (.article-body) {
  /* img 的特异性是 0-0-1 */
  img { ... }
}

但是，如果显式地将 :scope 伪类添加到作用域选择器之前，则在计算其特异性时需要将其考虑在内。:scope 与所有常规伪类一样，具有 0-1-0 的特异性。例如：

@scope (.article-body) {
  /* :scope img 的特异性为 0-1-0 + 0-0-1 = 0-1-1 */
  :scope img { ... }
}

当在 @scope 块内使用 & 选择器时，& 代表作用域根选择器（上限选择器）；它在内部计算为包装在 :is() 伪类函数内的选择器。可能听不懂，直接看例子就明白了：

@scope (figure, #primary) {
  & img { ... }
}

& img 等价于 :is(figure, #primary) img。:is() 选择器的特异性为它内部生效的最大的 CSS 选择器的特异性，在这个例子中是 #primary ，特异性为 1-0-0 ，因此这个条规则的特异性为 1-0-1。

:scope 与 & 的不同之处

:scope 表示匹配的作用域根（指定的是元素本身），而 & 表示用于匹配作用域根的选择器（是选择器而不是选中的元素）。因此，可以多次应用 &（选择器可以重复使用多次）。但是，只能使用 :scope 一次（作用域根不能作为自身的子元素）。

@scope (.feature) {
  /* .feature 内的 .feature */
  & & { ... }

  /* 错误 */
  :scope :scope { ... }
}

解决 @scope 冲突

@scope 为 CSS 添加了一个新标准：范围邻近度。这表明当两个作用域具有冲突的样式时，将应用 DOM 树层次结构中到作用域根的跳跃次数最少的样式。让我们看一个例子来看看这意味着什么。

采用以下 HTML 片段，其中不同主题的卡片相互嵌套：

<div class="light-theme">
  <p>Light theme text</p>
  <div class="dark-theme">
    <p>Dark theme text</p>
    <div class="light-theme">
      <p>Light theme text</p>
    </div>
  </div>
</div>

下面的 CSS 很符合直觉，但可惜是错误的：

.light-theme {
  background: #ccc;
}

.dark-theme {
  background: #333;
}

.light-theme p {
  color: black;
}

.dark-theme p {
  color: white;
}

最里面的段落的文字应该被设置为黑色，因为它位于浅色主题卡内。但是，它是 .light-theme p 和 .dark-theme p 选择器的目标。由于 .dark-theme p 规则在源代码中出现得较晚，因此应用了该规则，因而该段落最终被错误地设置为白色。

可以使用 @scope 解决此问题，如下所示：

@scope (.light-theme) {
  :scope {
    background: #ccc;
  }
  p {
    color: black;
  }
}

@scope (.dark-theme) {
  :scope {
    background: #333;
  }
  p {
    color: white;
  }
}

现在，最里面的段落已正确着色为黑色。这是因为它距离 .light-theme 作用域根仅一级 DOM 树层次结构，但距离 .dark-theme 作用域根两级。因此，.light-theme 被应用。

重要

范围邻近性原则会覆盖源代码顺序原则，但其本身会被其他更高优先级的样式（例如 !importance、@layers 和特异性）所覆盖。

例子

@scope 内的基本样式

在此示例中，我们使用两个单独的 @scope 块分别将元素内的链接与 .light-scheme 和 .dark-scheme 类进行匹配。请注意 :scope 如何用于选择作用域根本身并为其提供样式。在此示例中，范围根是应用了类的 <div> 元素。

指定作用域根和范围限制

在此示例中，我们有一个匹配 DOM 结构的 HTML 片段。该结构代表了一个典型的文章摘要。需要注意的关键特性是 <img> 元素，它嵌套在结构的各个级别中。

这个示例的目的是展示如何使用作用域根和限制来样式化从层次结构的顶部开始的 <img> 元素，但仅限于（不包括）<figure> 元素内的 <img> —— 实际上创建了一个环形范围。

最近在写一个碧蓝档案学生 Pixiv 收藏数统计的网站，想要实现两个炫酷的功能：模仿碧蓝档案游戏内什亭之匣的页面切换动画和圆形扩散的明暗主题切换动画（就像 Android 版 Telegram 那样）。

本来已经把 SVG 和动画的关键帧画好了，忽然发现一个问题，我的网站是基于 Next.js App Router 的，但是 App Router 不支持监听 Router 事件，也就是说，我并不知道下一个页面什么时候完成加载，也就没办法选择合适的时机播放页面进入的动画。

一搜 Google，千篇一律全是使用 Framer Motion 或者 React Transition Group，但是我 CSS 的 @keyframes 动画已经写好了，不想再重写一遍，难道只用纯 CSS 不能实现？

正好昨天在 MDN 上看到了 View Transitions API 的介绍，这个 API 拿来做动画是真的方便，于是去 Can I use 查了一下，发现现在只有 Chrome 支持，不过也没关系，先实现再说。

经过一番尝试，终于实现了两个动画效果，本文就来介绍一下 View Transitions API 的基本用法。

示例网站

View Transitions API 快速入门

是什么？

简单来说，View Transitions API 是用来简化创建页面切换动画的 API，它目前只能用于 SPA (Single Page Application) 中，也就是说，只能用于页面内的切换动画。根据设计者的说法，这个 API 的目标是让开发者能够更容易地实现页面切换动画，而不需要关心页面切换的时机，同时针对 MPA (Multi Page Application) 的支持也在计划中。

View Transitions API 提供了一个新的 JavaScript API: document.startViewTransition()，以及几个新的 CSS 属性:

• view-transition-name
• ::view-transition
• ::view-transition-group()
• ::view-transition-image-pair()
• ::view-transition-old()
• ::view-transition-new()

其中 document.startViewTransition() 在最新的 TypeScript 中任然没有定义，我们可以使用下面的代码来定义它：

type StartViewTransitionFunc = () => void | Promise<void>;
type StartViewTransitionReturn = {
    updateCallbackDone: Promise<void>;
    ready: Promise<void>;
    finished: Promise<void>;
}
type StartViewTransition = (func: StartViewTransitionFunc) => StartViewTransitionReturn;

declare global {
    interface Document {
        startViewTransition?: StartViewTransition;
    }
}

可以看到，document.startViewTransition() 接受一个函数作为参数，这个函数会在页面切换的时候被调用，返回一个对象，包含了三个 Promise 对象，分别表示页面切换动画的三个阶段：updateCallbackDone、ready 和 finished。

在调用 document.startViewTransition() 后，浏览器会立即对当前页面进行快照，并且停止全部渲染流程，这一段时间，用户看到的是当前页面的快照，而不是真实的页面。这时的页面不能响应用户的交互。startViewTransition() 接受的参数函数会在这个时候被调用，执行页面的更新操作（比如页面路由，但具体的操作是什么，完全由开发者自己决定）。

在 startViewTransition() 的参数函数执行完成后（如果是异步函数，会等待兑现），浏览器在后台进行一次渲染，并对新的页面进行快照，这个操作对用户是不可见的。

当旧的页面和新的页面的快照都准备好后，updateCallbackDone 的 Promise 对象会被 resolve。这时，浏览器会开始播放页面切换动画，这个动画是由开发者自己定义的 CSS 动画（也可以是 document.documentElement.animate 产生的动画）。

当动画播放完成后，finished 的 Promise 对象会被 resolve，这时，浏览器会停止播放动画，移除两个页面的快照，恢复页面的交互。

至于页面快照的位置，浏览器会在顶层（ <body> 标签之上，<html> 标签之下）创建一个新的层级，这个层级的 z-index 是最高的，所以页面快照会覆盖在所有的元素之上。包含以下伪元素：

html
|  ::view-transition
|  |  ::view-transition-group(root)
|  |  |  ::view-transition-image-pair(root)
|  |  |  |  ::view-transition-old
|  |  |  |  |  old page snapshot
|  |  |  |  ::view-transition-new
|  |  |  |  |  new page snapshot
|  |  ::view-transition-group(custom)
|  |  |  ::view-transition-image-pair(custom)
|  |  |  |  ::view-transition-old
|  |  |  |  |  old page snapshot
|  |  |  |  ::view-transition-new
|  |  |  |  |  new page snapshot
|  <body>
......

可以像对普通 HTML 元素一样对这些伪元素进行样式的设置。

如何使用？

以页面切换为例，先看看 碧蓝档案 Pixiv 作品排序 作为例子。

这是一个使用 SVG 和 @keyframes 实现的页面切换动画，注意到，动画中一共有 7 个三角形的方块和一个背景图，由于 View Transitions API 会对设置了 view-transition-name 的元素进行快照，显然 <path> 元素不能离开 <svg> 元素，所以我们需要把这个 SVG 拆成 8 份分别设置动画。这样也方便我们定义每一个三角形的运动轨迹。CSS 类似下面这么写：

::view-transition-old(D1TranslateAnimation),
::view-transition-old(D2TranslateAnimation),
::view-transition-old(D3TranslateAnimation),
::view-transition-old(D4TranslateAnimation),
::view-transition-old(D5TranslateAnimation),
::view-transition-old(R1TranslateAnimation),
::view-transition-old(R2TranslateAnimation),
::view-transition-old(R3TranslateAnimation) {
    --svg-width: max(100vw, 100vh / 9 * 16);
    --svg-px: calc(var(--svg-width) / 1920);
    transform-origin: center;
    transform-box: fill-box;
    animation-duration: 610ms;
    animation-timing-function: linear;
}

::view-transition-old(D1TranslateAnimation) {
    animation-name: d1-translate-animation;
}

::view-transition-old(D2TranslateAnimation) {
    animation-name: d2-translate-animation;
}

::view-transition-old(D3TranslateAnimation) {
    animation-name: d3-translate-animation;
}

::view-transition-old(D4TranslateAnimation) {
    animation-name: d4-translate-animation;
}

::view-transition-old(D5TranslateAnimation) {
    animation-name: d5-translate-animation;
}

::view-transition-old(R1TranslateAnimation) {
    animation-name: r1-translate-animation;
}

::view-transition-old(R2TranslateAnimation) {
    animation-name: r2-translate-animation;
}

::view-transition-old(R3TranslateAnimation) {
    animation-name: r3-translate-animation;
}
.d1TranslateAnimation {
    transform:  translate(-50%, -50%) translate(calc(var(--svg-px) * -675), calc(var(--svg-px) * -246)) scale(0.4) rotate(0deg);
    view-transition-name: D1TranslateAnimation;
}

.d2TranslateAnimation {
    transform:  translate(-50%, -50%) translate(calc(var(--svg-px) * -391), calc(var(--svg-px) * -440)) scale(0.28) rotate(-67deg);
    view-transition-name: D2TranslateAnimation;
}

.d3TranslateAnimation {
    transform:  translate(-50%, -50%) translate(calc(var(--svg-px) * 56), calc(var(--svg-px) * -515)) scale(0.34) rotate(-52.5deg);
    view-transition-name: D3TranslateAnimation;
}

.d4TranslateAnimation {
    transform:  translate(-50%, -50%) translate(calc(var(--svg-px) * 512), calc(var(--svg-px) * -362)) scale(0.42) rotate(-76.4deg);
    view-transition-name: D4TranslateAnimation;
}

.d5TranslateAnimation {
    transform:  translate(-50%, -50%) translate(calc(var(--svg-px) * 153), calc(var(--svg-px) * -19)) scale(0.22) rotate(174deg);
    view-transition-name: D5TranslateAnimation;
}

.r1TranslateAnimation {
    transform:  translate(-50%, -50%) translate(calc(var(--svg-px) * -725), calc(var(--svg-px) * 412)) scale(0.395) rotate(173.3deg);
    view-transition-name: R1TranslateAnimation;
}

.r2TranslateAnimation {
    transform:  translate(-50%, -50%) translate(calc(var(--svg-px) * -180), calc(var(--svg-px) * 370)) scale(0.40) rotate(37deg);
    view-transition-name: R2TranslateAnimation;
}

.r3TranslateAnimation {
    transform:  translate(-50%, -50%) translate(calc(var(--svg-px) * 415), calc(var(--svg-px) * 450)) scale(0.41) rotate(114deg);
    view-transition-name: R3TranslateAnimation;
}

然后在 JavaScript 中使用 document.startViewTransition() 来实现页面切换：

const router = useRouter();
const [show, setShow] = useState(false);

const handleRoute = (target: string) => {
    flushSync(() => {
        setShow(true);
    });
    const start = performance.now();
    const vt = document.startViewTransition(() => {
        flushSync(() => {
            router.push(target);
        });
    });
    vt.finished.then(() => {
        // 这里会有问题，后面会讲到
        setShow(false);
    });
    
    return show && (<>...</>)
};

在本地调试一点问题都没有，但是线上运行，发现如果网络条件不好，会导致新的页面还没加载完毕就开始播放动画，放完页面还没变的尴尬情况。可见 Next.js 并不保证 flushSync 里的路由以及渲染完成。我们只能自己撸一套轮子。。。详见：Next.js: Add support for View Transition API #46300

最终我的解决方案和 @AaronLayton 的评论类似，由于太长了就不贴出来了，有兴趣的可以看看那位老哥的代码，已经很清晰了。

（最后我还是放弃了 View Transitions API，因为需要兼容 FireFox，我自己搞了一套，效果基本一模一样）

简单但完整的例子

一个简单的明暗模式切换，相对于使用 CSS 滤镜，这种方案不需要对页面中的图片等彩色元素进行特殊处理。

【图中奇怪的格子是录屏转 GIF 格式的问题】

CSS 里禁用动画，使用 JavaScript 根据点击位置动态计算圆形扩散的半径，然后使用 document.documentElement.animate 播放动画。

::view-transition-old(root),
::view-transition-new(root) {
    animation: none;
    mix-blend-mode: normal;
}

首先实现一个明暗模式切换的 Context，没什么好说的，就是一个简单的 Context。我使用 <body> 标签的 class 来切换明暗模式，所以需要在 ColorModeProvider 中设置 class，但后面的颜色就都自动适配了。

"use client";

type ColorMode = "light" | "dark" | "system";
type CurrentColorMode = "light" | "dark";

type ColorModeContext = {
    colorMode: ColorMode;
    currentColorMode: CurrentColorMode;
    setColorMode: (colorMode: ColorMode) => void;
    toggleColorMode: () => void;
}

const ColorModeContext = createContext<ColorModeContext>(null!);

interface ColorModeProviderProps {
    children: ReactNode;
}

function ColorModeProvider({children}: ColorModeProviderProps) {
    const [colorMode, _setColorMode] = useState<ColorMode>("light");
    const [currentColorMode, setCurrentColorMode] = useState<CurrentColorMode>("light");

    const setColorMode = (colorMode: ColorMode) => {
        localStorage.setItem("pattern.mode", colorMode);
        if (colorMode === "light") {
            document.documentElement.classList.add("light");
            document.documentElement.classList.remove("dark");
        } else if (colorMode === "dark") {
            document.documentElement.classList.add("dark");
            document.documentElement.classList.remove("light");
        } else {
            document.documentElement.classList.remove("light");
            document.documentElement.classList.remove("dark");
        }
        _setColorMode(colorMode);
    };
    useEffect(() => {
        const colorMode = localStorage.getItem("pattern.mode");
        if (colorMode === "system" || colorMode === "dark") {
            setColorMode(colorMode);
        } else {
            setColorMode("light");
        }
    }, []);
    useEffect(() => {
        if (colorMode === "system") {
            const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
            if (mediaQuery.matches) {
                setCurrentColorMode("dark");
            } else {
                setCurrentColorMode("light");
            }
            const listener = (e: MediaQueryListEvent) => {
                if (e.matches) {
                    setCurrentColorMode("dark");
                } else {
                    setCurrentColorMode("light");
                }
            };
            mediaQuery.addEventListener("change", listener);
            return () => {
                mediaQuery.removeEventListener("change", listener);
            };
        } else {
            setCurrentColorMode(colorMode);
        }
    }, [colorMode]);

    const toggleColorMode = () => {
        if (colorMode === "light") {
            setColorMode("dark");
        } else if (colorMode === "dark") {
            setColorMode("system");
        } else {
            setColorMode("light");
        }
    };

    return (
        <ColorModeContext.Provider value={{colorMode, currentColorMode, setColorMode, toggleColorMode}}>
            {children}
        </ColorModeContext.Provider>
    );
}

export default ColorModeProvider;

export function useColorMode() {
    return useContext(ColorModeContext);
}

然后实现一个按钮，点击按钮时，根据点击位置计算圆形扩散的半径，然后播放动画。

很简单，就是使用 flushSync 强制 React 完成同步渲染，等待新旧页面快照就绪，然后使用 document.documentElement.animate 播放动画。

type StartViewTransitionFunc = () => void;
type StartViewTransitionReturn = {
    updateCallbackDone: Promise<void>;
    ready: Promise<void>;
    finished: Promise<void>;
}
type StartViewTransition = (func: StartViewTransitionFunc) => StartViewTransitionReturn;

declare global {
    interface Document {
        startViewTransition: StartViewTransition;
    }
}

type ColorMode = "light" | "dark" | "system";

function getColorModeIron(mode: ColorMode) {
    if (mode === "light") {
        return <LightModeIcon/>;
    } else if (mode === "dark") {
        return <DarkModeIcon/>;
    } else {
        return <SystemModeIcon/>;
    }
}

function HeaderColorToggle() {
    const {toggleColorMode, colorMode} = useColorMode();
    
    const listener: MouseEventHandler = async (e) => {
        if (!document.startViewTransition) {
            toggleColorMode();
            return;
        }
        const x = e.clientX;
        const y = e.clientY;
        const radius = Math.hypot(Math.max(x, window.innerWidth - x), Math.max(y, window.innerHeight - y));

        const vt = document.startViewTransition(() => {
            flushSync(() => {
                toggleColorMode();
            });
        });
        await vt.ready;
        const frameConfig = {
            clipPath: [
                `circle(0 at ${x}px ${y}px)`,
                `circle(${radius}px at ${x}px ${y}px)`,
            ],
        };
        const timingConfig = {
            duration: 200,
            pseudoElement: "::view-transition-new(root)",
        };
        document.documentElement.animate(frameConfig, timingConfig);
    };

    return (
        <button onClick={listener} aria-label="切换颜色模式" title="切换颜色模式" type="button"
                className={clsx("px-3 py-2 shrink-0 flex rounded cursor-pointer items-center hover:bg-bg-hover hover:text-link-hover fill-current")}>
            {getColorModeIron(colorMode)}
        </button>
    );
}

【完】