
## Flyway 是什么

[Flyway](https://flywaydb.org/) 是一款开源的，基于 Java 实现的数据库内容变更控制工具。它提供了 CLI、Java API、Maven/Gradle Plugin 等多种方式方便开发人员将数据库的表结构改动、内容变动以可追溯的代码形式进行管理和部署。Flyway 支持包括大多数主流的关系型数据库：MySQL、SQL Server、Oracle Database、PostgreSQL、SQLite、TiDB、MariaDB 等，对于 MongoDB 的支持尚在预览阶段（更推荐 Mongock），同类竞品有 Liquibase，但 Liquibase 的使用相比 Flyway 更复杂，有额外的概念作为学习成本。

<div>
  <github user="flyway" repo="flyway"></github>
</div>

## 配合 Spring Boot 使用

遵循 SpringBoot 广为人知的约定大于配置，Spring 官方提供了 [Flyway 的自动配置实现](https://github.com/spring-projects/spring-boot/tree/main/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/flyway)。

```java {2-4} showLineNumbers
@AutoConfiguration(after = { DataSourceAutoConfiguration.class,JdbcTemplateAutoConfiguration.class,HibernateJpaAutoConfiguration.class })
@ConditionalOnClass(Flyway.class)
@Conditional(FlywayDataSourceCondition.class)
@ConditionalOnProperty(prefix = "spring.flyway", name = "enabled", matchIfMissing = true)
@Import(DatabaseInitializationDependencyConfigurer.class)
@ImportRuntimeHints(FlywayAutoConfigurationRuntimeHints.class)
public class FlywayAutoConfiguration { /*...*/ }
```

全限定类名 `org.springframework.boot.autoconfigure.flyway.FlywayAutoConfiguration` 会在检测到以下几种状态下实现自动配置：

1. 存在 `Flyway` 类 (即 `org.flywaydb.core.Flyway`)
2. 满足 `FlywayDataSourceCondition` 类中的 Bean 或 Properties 条件，其实就是 `DataSource` 和数据库 URL 等连接配置存在
3. 存在 `spring.flyway.enabled=true` 属性配置

对于 MySQL 而言，除了必须的 JDBC 依赖之外，需要引入 Flyway 自身依赖，SpringBoot 已经在 pom 中声明过版本号，因此此处无需额外定义版本字段:

```xml
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-mysql</artifactId>
</dependency>
```

具体使用有两种方式：

1. 原生 SQL
2. Java API

Flyway 会基于默认配置的文件夹路径 classpath:db/migration 发现版本变更文件或实现类。

```shell
V{VERSION}__{DESCRIPTION}.sql
V{VERSION}__{DESCRIPTION}.java
```

`VERSION` 可使用包含小数点、下划线的字符串版本，`DESCRIPTION` 则是简单的描述文本。中间的分割符是两个下划线。可通过 spring.flyway 配置自定义前后缀。

`V{VERSION}__{DESCRIPTION}.sql` 文件需要存放在 src/main/resources/db/migration 文件夹下; Java 类则需要定义包名 `db.migration` 并且继承父类 `BaseJavaMigration`，重写如下方法:

```java
void migrate(Context context) throws Exception;
```

按照官方的写法，我们就可以在 `migrate()` 方法中去用 Java 代码实现数据库内容版本变动了，但是这里有一个缺点，那就是我们在 Spring 环境下无法针对 `V{VERSION}__{DESCRIPTION}.java` 进行依赖注入，只能尝试通过原生 JDBC 的方式、静态方法等去写比较朴素的 SQL 实现，而不能充分成分利用现有的 DAO 接口来做业务数据的更新。因此需要自定义配置 Flyway。

## 向 Flyway Migration 实现类进行依赖注入

```java
package me.lawrenceli.migration.config;

import jakarta.annotation.PostConstruct;
import org.flywaydb.core.Flyway;
import org.flywaydb.core.api.migration.JavaMigration;
import org.flywaydb.core.api.output.MigrateResult;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Configuration;

import javax.sql.DataSource;

@Configuration
public class FlywayConfig {
    // 自定义迁移历史表名
    private static final String SCHEMA_HISTORY_TABLE = "schema_changes";

    @Autowired
    private DataSource dataSource;

    @Autowired
    private ApplicationContext applicationContext;

    @PostConstruct
    public void migrate() {
        log.info("Flyway, 启动!");
        // 通过 Spring 容器获取所有迁移实现类
        // 这样一来，所有实现类就不再需要定义在 package `db.migration` 下，可以放在任何支持 Bean 扫描的位置。
        JavaMigration[] migrationBeans = applicationContext
                .getBeansOfType(JavaMigration.class)
                .values()
                .toArray(new JavaMigration[0]);
        Flyway flyway = Flyway.configure()
                .dataSource(dataSource) // 通过原本的 DataSource Bean 实现无需配置 flyway 自身的 JDBC URL
                .locations("db/migration") // 默认迁移脚本路径
                .table(SCHEMA_HISTORY_TABLE) // 默认迁移历史表为 `flyway_schema_history`
                .baselineOnMigrate(true) // 默认 false, 对以存在的数据库做首次迁移必须设置开启
                .baselineVersion("0") // 默认 "1"
                .executeInTransaction(true) // 将迁移作为事务，你懂的
                .installedBy(applicationContext.getId()) // 将微服务名作为迁移执行者
                .javaMigrations(migrationBeans) // 注册迁移类
                .load();
        MigrateResult migrate = flyway.migrate(); // 执行迁移，依次调用子类实现
        log.info("Flyway 迁移了 {} 版. {}", migrate.migrationsExecuted, migrate.success);
    }
}
```

由于 Flyway 的配置基于这种手动配置，因此需要在 SpringBoot 启动类上排除原有的自动配置类，以防止自动配置存在加载冲突。

```java
@SpringBootApplication(exclude = FlywayAutoConfiguration.class)
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}
```

最后，定义一个 Component Bean 去实现 `BaseJavaMigration`:

```java {12} showLineNumbers caption="Example Migration Component"
package me.lawrenceli.balabala.migration;

import org.flywaydb.core.api.migration.BaseJavaMigration;
import org.flywaydb.core.api.migration.Context;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Component
public class V2__QueryExample extends BaseJavaMigration {

    @Autowired
    private MyMapper myMapper; // Bean of DAO

    @Override
    public void migrate(Context context) throws Exception {
        Data data = myMapper.selectById(2024L);
        // ... other CRUD codes with Java
    }
}
```

这样，所有的迁移类都可以方便地使用依赖注入来愉快地做 CRUD 了。经过实践，Flyway 会在数据库连接配置后、HTTP 服务暴露(也就是 Servlet 容器监听端口)前同步地执行完所有迁移，因此无需担心执行时机影响线上服务。

## 参考

- <https://github.com/flyway/flyway/issues/1062>


在 Flyway 迁移类中实现依赖注入


## What is Flyway

[Flyway](https://flywaydb.org/) is an open-source database version control tool implemented in Java. It offers various methods such as CLI, Java API, Maven/Gradle Plugin, etc., making it convenient for developers to manage and deploy changes to database table structures and contents in traceable code form. Flyway supports most mainstream relational databases, including MySQL, SQL Server, Oracle Database, PostgreSQL, SQLite, TiDB, MariaDB, etc. Support for MongoDB is still in the preview stage (Mongock is recommended instead). Its counterpart, Liquibase, is more complex to use compared to Flyway, with additional concepts serving as a learning curve.

<div>
  <github user="flyway" repo="flyway"></github>
</div>

## Integration with Spring Boot

Following Spring Boot's well-known convention-over-configuration principle, the Spring team provides [Flyway Auto Configuration](https://github.com/spring-projects/spring-boot/tree/main/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/flyway).

```java {2-4} showLineNumbers
@AutoConfiguration(after = { DataSourceAutoConfiguration.class, JdbcTemplateAutoConfiguration.class,HibernateJpaAutoConfiguration.class })
@ConditionalOnClass(Flyway.class)
@Conditional(FlywayDataSourceCondition.class)
@ConditionalOnProperty(prefix = "spring.flyway", name = "enabled", matchIfMissing = true)
@Import(DatabaseInitializationDependencyConfigurer.class)
@ImportRuntimeHints(FlywayAutoConfigurationRuntimeHints.class)
public class FlywayAutoConfiguration { /*...*/ }
```

The fully qualified class name `org.springframework.boot.autoconfigure.flyway.FlywayAutoConfiguration` will perform automatic configuration when the following conditions are detected:

1. The `Flyway` class exists (class name: `org.flywaydb.core.Flyway`)
2. Bean or properties conditions are met in the `FlywayDataSourceCondition` class, meaning connection configurations such as `DataSource` and database URL exist.
3. The property configuration `spring.flyway.enabled=true` exists.

For MySQL, besides the required JDBC dependency, you need to include Flyway's own dependencies. Spring Boot has already declared the version number in the POM, so no additional version field is needed here:

```xml
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-mysql</artifactId>
</dependency>
```

There are two ways to use it:

1. Native SQL
2. Java API

Flyway will discover version change files or implementation classes based on the default configured folder path `classpath:db/migration`.

```shell
V{VERSION}__{DESCRIPTION}.sql
V{VERSION}__{DESCRIPTION}.java
```

`VERSION` can be a string version containing dots and underscores, and `DESCRIPTION` is a simple description text. The separator in the middle is two underscores. Custom prefixes and suffixes can be configured through spring.flyway.

The `V{VERSION}__{DESCRIPTION}.sql` file needs to be placed in the `src/main/resources/db/migration` folder, while Java classes need to define the package name as db.migration and inherit the superclass `BaseJavaMigration`. We need to do is overriding the following method:

```java
void migrate(Context context) throws Exception;
```

According to the official documentation, we can implement database content version changes using Java code in the `migrate()` method. However, the drawback here is that we cannot perform dependency injection for `V{VERSION}__{DESCRIPTION}.java` in the Spring environment. We can only attempt to use plain SQL implementations through native JDBC methods, static methods, etc., rather than fully utilizing existing DAO interfaces for business data updates. Therefore, custom configuration of Flyway is required.

## Performing Dependency Injection into Flyway Class

```java
package me.lawrenceli.migration.config;

import jakarta.annotation.PostConstruct;
import org.flywaydb.core.Flyway;
import org.flywaydb.core.api.migration.JavaMigration;
import org.flywaydb.core.api.output.MigrateResult;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Configuration;

import javax.sql.DataSource;

@Configuration
public class FlywayConfig {
    // Custom migration history table name
    private static final String SCHEMA_HISTORY_TABLE = "schema_changes";

    @Autowired
    private DataSource dataSource;

    @Autowired
    private ApplicationContext applicationContext;

    @PostConstruct
    public void migrate() {
        log.info("Flyway, starting!");
        // Retrieving all migration implementation classes through the Spring container
        // All implementation classes no longer need to be defined in the `db.migration` package,
        // they can be placed in any location that supports Bean scanning
        JavaMigration[] migrationBeans = applicationContext
                .getBeansOfType(JavaMigration.class)
                .values()
                .toArray(new JavaMigration[0]);
        Flyway flyway = Flyway.configure()
                .dataSource(dataSource) // No need to configure flyway JDBC URL by using the original DataSource
                .locations("db/migration") // Default migration script path
                .table(SCHEMA_HISTORY_TABLE) // Default migration history table is `flyway_schema_history`
                .baselineOnMigrate(true) // Default false, must be set to true for initial migration on existing databases
                .baselineVersion("0") // Default "1"
                .executeInTransaction(true) // Performing migration as a transaction
                .installedBy(applicationContext.getId()) // Using microservice name as migration executor
                .javaMigrations(migrationBeans) // Registering migration classes
                .load();
        MigrateResult migrate = flyway.migrate(); // Executing migration by calling subclass implementations sequentially
        log.info("Flyway migrated {} versions. {}", migrate.migrationsExecuted, migrate.success);
    }
}

```

Since Flyway's configuration is based on manual configuration like this, it's necessary to exclude the original auto-configuration classes in the Spring Boot startup class to avoid conflicts in auto-configuration loading.

```java
@SpringBootApplication(exclude = FlywayAutoConfiguration.class)
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}
```

Finally, define a Component Bean to implement `BaseJavaMigration`:

```java {12} showLineNumbers caption="Example Migration Component"
package me.lawrenceli.balabala.migration;

import org.flywaydb.core.api.migration.BaseJavaMigration;
import org.flywaydb.core.api.migration.Context;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Component
public class V2__QueryExample extends BaseJavaMigration {

    @Autowired
    private MyMapper myMapper; // Bean of DAO

    @Override
    public void migrate(Context context) throws Exception {
        Data data = myMapper.selectById(2024L);
        // ... other CRUD codes with Java
    }
}
```

Now, all migration classes can easily use dependency injection to perform CRUD operations. In practice, Flyway will execute all migrations synchronously after database connection configuration and before HTTP service exposure, ensuring that timing does not affect online services.

## Reference

- <https://github.com/flyway/flyway/issues/1062>


Increase reliability of deployments by versioning your database

Dependency Injection with Flyway


最近看到很多博主在 [App Defaults](https://defaults.rknight.me/) 中分享了他们的默认应用程序。以下是我自己的：

- 📨 邮件客户端
  - Apple 邮件
- 📮 邮件服务器
  - Outlook（中国大陆可用）
  - [Lark 邮件](https://www.larksuite.com/mail) `hi@lawrenceli.me`。
- 📝 注释
  - Apple Notes（使用 [montaigne.io](https://montaigne.io)，可以将 Apple Notes 成为一个静态网站）
- ✅ 待办事项
  - Apple 提醒
- 📷 iPhone 照片拍摄
  - Apple 相机
- 🟦 照片管理
  - Apple 照片与 iCloud 同步
- 📆 日历
  - 服务：iCloud 日历
  - 客户端：Apple 日历
- 📁 云文件存储
  - iCloud 云盘 (iCloud+)
  - [阿里云盘](https://www.aliyundrive.com/)（适用于 Apple TV）
- 📖 RSS
  - iOS 上的 [Reeder](https://reederapp.com/)
  - macOS 上的 [ReadKit](https://readkit.app/)
  - 自托管 [FreshRSS](https://freshrss.org/index.html)，出色的 PWA 和 Web 推送。
- 🙍🏻‍♂️ 通讯录
  - N/A，没有联系人。
- 🌐 浏览器
  - Mac 上的 Firefox
  - iOS 上的 Safari
- 💬 聊天
  - [微信](https://www.wechat.com/)（中国必备应用）
  - [Microsoft Teams](https://apps.apple.com/ph/app/microsoft-teams/id1113153706)（上班用）
- 🔖 书签
  - [Instapaper](https://www.instapaper.com/)
- 📑 稍后阅读
  - Reeder + Instapaper
- 📜 文字处理
  - [ONLYOFFICE](https://www.onlyoffice.com/)（开源 Office，与微软完全兼容）
  - [Obsidian](https://obsidian.md/)（流行的 Markdown 编辑器，可通过 iCloud 同步）
- 📈 电子表格
  - ONLYOFFICE（开源 Office）
- 📊 演示
  - [Slidev](https://sli.dev/)（通过 Markdown 生成幻灯片）
- 🛒 购物清单
  - 在 Apple 提醒共享提醒列表
- 🍴 膳食计划
  - 无
- 💰 预算和个人理财
  - 以前用过 [iOS 的 Finances 2](https://hochgatterer.me/finances/ios/)，目前正在尝试 [BeanWise](https://apps.apple.com/us/app/beanwise/id6446314789?ref=https://lawrenceli.me)
- 📰 新闻
  - [Solidot](https://solidot.org) (中文版的 [slashdot](https://slashdot.org))
  - [路透社](https://www.reuters.com/)
  - [Hacker News](https://news.ycombinator.com/)
- 🎵 音乐
  - [Apple Music](https://music.apple.com/)（学生订阅只需每月 6 元）
  - [网易云音乐](https://music.163.com/)（作为 Apple Music 的补充）
- 🎤 播客
  - [Apple Podcast](https://www.apple.com/apple-podcasts/) 推荐泛用型播客客户端，无内容审查
- 🔐 密码管理
  - iCloud KeyChain
  - [2FAS](https://2fas.com) 多因素身份验证

## 额外默认设置

- 🚀 自托管
  - [Cloudflare](https://lawrenceli.me/blog/cloudflare)（用于 CDN 和 DNS）
  - [Vercel](https://vercel.com) Next.js 的最佳部署体验
  - [Cloudflare Workers](https://developers.cloudflare.com/workers/) 基于 Cloudflare 节点的 Serverless
  - [fly.io](https://fly.io) 可免费运行 Docker 实例，需提供信用卡
- 🤖 自动化
  - [IFTTT](https://ifttt.com) IF This Then That
  - [Apple 快捷指令](http://workflow.is/)（前 Workflow）
  - [ActivePieces](https://www.activepieces.com/) 开源的自动化工具
- 🛜 网络工具
  - [Tailscale](https://tailscale.com/) 零配置组网工具
  - [Cloudflare WARP](https://1.1.1.1) 基于 DoH 的零信任网络
  - [MerlinClash](https://mcreadme.gitbook.io/mc/) 梅林固件的网络工具
  - [WireGuard](https://github.com/WireGuard) 下一代 VPN 协议
  - [ShadowRocket](https://apps.apple.com/us/app/shadowrocket/id932747118?l=zh-Hans-CN) 最流行的网络工具


My default apps in 2024. Inspired by https://defaults.rknight.me/

我的默认应用


I just saw many bloggers share their defalut apps in [App Defaults](https://defaults.rknight.me/). Here's my list:

- 📨 Mail Client
  - Apple Mail
- 📮 Mail Server
  - Outlook (available in China Mainland)
  - [Lark Mail](https://www.larksuite.com/mail). `hi@lawrenceli.me`.
- 📝 Notes
  - Apple Notes (with [montaigne.io](https://montaigne.io) you can make your Apple Notes be a website)
- ✅ To-Do
  - Apple Reminders
- 📷 iPhone Photo Shooting
  - Apple Camera
- 🟦 Photo Management
  - Apple Photos with iCloud Sync
- 📆 Calendar
  - Service: iCloud Calendar
  - Client: Apple Calendar
- 📁 Cloud File Storage
  - iCloud Drive (iCloud+)
  - [Aliyun Drive](https://www.aliyundrive.com/) (for Apple TV)
- 📖 RSS
  - [Reeder](https://reederapp.com/) on iOS
  - [ReadKit](https://readkit.app/) on macOS
  - Self-hosted [FreshRSS](https://freshrss.org/index.html), great PWA and web notification support.
- 🙍🏻‍♂️ Contacts
  - N/A, No contacts.
- 🌐 Browser
  - Firefox on macOS
  - Safari on iOS
- 💬 Chat
  - [WeChat](https://www.wechat.com/) (a must app in China)
- 🔖 Bookmarks
  - [Instapaper](https://www.instapaper.com/)
- 📑 Read It Later
  - Instapaper in Reeder
- 📜 Word Processing
  - [ONLYOFFICE](https://www.onlyoffice.com/) (open source office, offers complete compatibility with Microsoft ones)
  - [Obsidian](https://obsidian.md/) (popular markdown editor, sync up via iCloud)
- 📈 Spreadsheets
  - ONLYOFFICE (open source office)
- 📊 Presentations
  - [Slidev](https://sli.dev/) (Generate the slide/ppt online by markdown)
- 🛒 Shopping Lists
  - Shared Reminder List with Apple Reminders
- 🍴 Meal Planning
  - N/A
- 💰 Budgeting and Personal Finance
  - Previously [Finances 2 on iOS](https://hochgatterer.me/finances/ios/), currently trying [BeanWise](https://apps.apple.com/us/app/beanwise/id6446314789?ref=https://lawrenceli.me)
- 📰 News
  - [Solidot](https://solidot.org) (Chinese version of [slashdot](https://slashdot.org) )
  - [Reuters](https://www.reuters.com/)
  - [Hacker News](https://news.ycombinator.com/)
- 🎵 Music
  - [Music](https://music.apple.com/) (Student subscription only cost 5 RMB per month)
  - [NetEase Music](https://music.163.com/) (As a complement to Apple Music)
- 🎤 Podcasts
  - [Apple Podcast](https://www.apple.com/apple-podcasts/) Universal Podcast Client, no censorship
- 🔐 Password Management
  - iCloud Keychain
  - [2FAS](https://2fas.com) for 2FA

## My extra defaults

- 🚀 Self Hosting
  - [Cloudflare](https://lawrenceli.me/blog/cloudflare) (for CDN & DNS)
  - [Vercel](https://vercel.com) Best experience with Next.js
  - [Cloudflare Workers](https://developers.cloudflare.com/workers/) Serverless plarform by Cloudflare
  - [fly.io](https://fly.io) Hosting you Docker container for free. Credit card required
- 🤖 Automation
  - [IFTTT](https://ifttt.com) IF This Then That
  - [Apple Shortcuts](http://workflow.is/) (previously Workflow)
  - [ActivePieces](https://www.activepieces.com/) open source automation tool
- 🛜 Network Tools
  - [Tailscale](https://tailscale.com/) zero config VPN
  - [Cloudflare WARP](https://1.1.1.1) zero trust network with DoH
  - [MerlinClash](https://mcreadme.gitbook.io/mc/) network tools for merlin router
  - [WireGuard](https://github.com/WireGuard) the next generation vpn
  - [ShadowRocket](https://apps.apple.com/us/app/shadowrocket/id932747118?l=zh-Hans-CN) popular network tool


My App Defaults


NET: <trade symbol="NET" />

Cloudflare 是一家在业内比较知名的 CDN 服务商，提供包含 DNS 解析、WAF 防火墙、CDN 加速、DDoS 防护，后续推出了一系列比较方便开发人员的许多功能：Cloudflare Workers、KV、Zero Trust Tunnel、WARP... 一切都是为了提供一个安全、快速的互联网环境。如果说 Vercel 给前端开发人员提供了基础设施，那 Cloudflare 则为数千万网站后端流量提供了基础设施。

今年年初，[Cloudflare 缓解了破纪录的 7100 万个请求/秒的 DDoS 攻击](https://blog.cloudflare.com/zh-cn/cloudflare-mitigates-record-breaking-71-million-request-per-second-ddos-attack-zh-cn/)。

## Vercel & CDN

三年前，我把我的博客从 WordPress 迁移到了 [Vercel](https://vercel.com)，老用户们或许都记得，那时候的域名可还都是 `*.now.sh`。初次使用 Vercel 的感受可以说是如获至宝，在今天看来可能显得很幼稚了——如果不是自己知道如何从 0 到 1 申请域名去部署一个全栈的 Web 项目的话，很难理解 Vercel 这种平台背后做了哪些复杂工作。这是我所理解的美国公司的一贯作法 —— 他们总是把庞大、精密、复杂的技术或基础设施掩盖在简约、优雅的产品外观之下。而我每次都会保持警惕和观察力，如果换我做，我怎么来实现？后来我便学习起了 Kubernetes。

说回 Cloudflare。从我第一次买域名（2015 年）一直到现在，我全部把解析权安排在 Cloudflare 上。归因于 [Vercel 的一次网络问题](https://isdown.app/integrations/vercel/incidents/50745-errors-accessing-from-china)，国内的网络受某种不可抗力在 2021 年的时候突然无法访问 Vercel 的部分域名了，尽管我的博客每天仅有为数不多的访客，但作为一个以中文为主的博客，还是有必要保持国内网络访问的畅通。根据官方提供的新的 CNAME 值，我在 Cloudflare 上更换了解析记录，也算顺利解决。也就在当时，我才注意到 DNS Records 控制台之前一个一直忽视的选项：

<figure>
  <img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDQgMzkuNSI+PGRlZnM+PHN0eWxlPi5jbHMtMXtmaWxsOiM5OTk7fS5jbHMtMntmaWxsOiNmNjhhMWQ7fS5jbHMtM3tmaWxsOiNmZmY7fTwvc3R5bGU+PC9kZWZzPjx0aXRsZT5Bc3NldCAxPC90aXRsZT48ZyBpZD0iTGF5ZXJfMiIgZGF0YS1uYW1lPSJMYXllciAyIj48ZyBpZD0iTGF5ZXJfMS0yIiBkYXRhLW5hbWU9IkxheWVyIDEiPjxwb2x5Z29uIGNsYXNzPSJjbHMtMSIgcG9pbnRzPSIxMDQgMjAuMTIgOTQgMTAuNjIgOTQgMTYuMTIgMCAxNi4xMiAwIDI0LjEyIDk0IDI0LjEyIDk0IDI5LjYyIDEwNCAyMC4xMiIvPjxwYXRoIGNsYXNzPSJjbHMtMiIgZD0iTTc0LjUsMzljLTIuMDgsMC0xNS40My0uMTMtMjguMzQtLjI1LTEyLjYyLS4xMi0yNS42OC0uMjUtMjcuNjYtLjI1YTgsOCwwLDAsMS0xLTE1LjkzYzAtLjE5LDAtLjM4LDAtLjU3YTkuNDksOS40OSwwLDAsMSwxNC45LTcuODEsMTkuNDgsMTkuNDgsMCwwLDEsMzguMDUsNC42M0ExMC41LDEwLjUsMCwxLDEsNzQuNSwzOVoiLz48cGF0aCBjbGFzcz0iY2xzLTMiIGQ9Ik01MSwxQTE5LDE5LDAsMCwxLDcwLDE5LjU5LDEwLDEwLDAsMSwxLDc0LjUsMzguNWMtNC4xMSwwLTUyLS41LTU2LS41YTcuNSw3LjUsMCwwLDEtLjQ0LTE1QTguNDcsOC40NywwLDAsMSwxOCwyMmE5LDksMCwwLDEsMTQuNjgtN0ExOSwxOSwwLDAsMSw1MSwxbTAtMUEyMCwyMCwwLDAsMCwzMi4xMywxMy40MiwxMCwxMCwwLDAsMCwxNywyMnYuMTRBOC41LDguNSwwLDAsMCwxOC41LDM5YzIsMCwxNSwuMTMsMjcuNjYuMjUsMTIuOTEuMTIsMjYuMjYuMjUsMjguMzQuMjVhMTEsMTEsMCwxLDAtMy42MS0yMS4zOUEyMC4xLDIwLjEsMCwwLDAsNTEsMFoiLz48L2c+PC9nPjwvc3ZnPg==" width="48px" height="48px"></img>
  <figcaption style="text-align: center">Proxied</figcaption>
</figure>

我好奇地把它启用了，即从灰色 `DNS only` 换成了这个橙色的 `Proxied`，那时我还没意识到，其实 Cloudflare 从那刻起已经完全接管了我的网站的全部流量并进行任播 (Anycast)；换句话说，我在现有的 Vercel CDN 之上，又套了一层 Cloudflare CDN。是的，这迎来了两个问题：

1. Vercel 后台警告 CNAME 解析异常
2. 缓存时间问题
3. 客户端 IP 全部被识别 Cloudflare IP，所有发往 Vercel 的请求都会从 Cloudflare 数据中心发出

不可能没人像我这样做吧？事实上，[Vercel 并不推荐在其基础上使用另一层 CDN](https://vercel.com/guides/why-running-another-cdn-on-top-of-vercel-is-not-recommended)。后续我也依次找寻到了解决方案：对于 CNAME 来说，Vercel 会定时访问网站跟路径下的 `.well-known` 路径下的资源来识别包括 CNAME、HTTPS 证书这类配置验证网站控制权信息，因此我们可以直接在 Cloudflare 的 WAF 中，把这类路径作为白名单让 WAF 跳过其他安全规则直接放行。对于客户端 IP，可以参考 [Available Managed Transforms](https://developers.cloudflare.com/rules/transform/managed-transforms/reference/)，将一些客户端原始信息置于请求头中。缓存时间方面，还是要熟悉 MDN 上的一些标准 HTTP 协商协议，细粒度地对不同资源设置不同的 TTL，尽可能发挥 Cloudflare CDN 和浏览器自身缓存的优势 - 一个博客而已，是不是有点大炮打蚊子了？

Cloudflare 的整体防御从 L3 到 L7，遍布了所有能覆盖的防御范围。一个请求进入 Cloudflare 所代理的网站流量会经历顺序由上到下：

| Traffic Sequence in Cloudflare |
| :----------------------------: |
|              DDoS              |
|          URL Rewrites          |
|           Page Rules           |
|          Origin Rules          |
|          Cache Rules           |
|      Configuration Rules       |
|         Redirect Rules         |
|        IP Access Rules         |
|              Bots              |
|              WAF               |
|      Header Modification       |
|             Access             |
|            Workers             |

这些流量经过内部的层层筛选，以及我们自己定义的一些 Rule，最终反代到源站。因此，在决定使用任何 CDN 产品的时候，有必要将服务端源站 IP 妥善隐藏，尽可能不暴露任何历史解析值，否则一切防御都是徒劳。如果源站 IP 已经暴露，只能及时更换新的地址。在新的规则录入好后，Cloudflare 的全球网络会立刻应用规则并实时生效，这里或多或少要归功于大佬 [agentzh 章亦春](https://mp.weixin.qq.com/s/xfphy67PTbtjeggo7LpjSA) 开源的高性能网关 [OpenResty](https://openresty.org/cn/)。

## Cloudflare Workers & Serverless

我们可以将一个个「函数」部署在公有云的「边缘计算节点」之上，并暴露 Socket 给这些节点上的函数，来实现无需忽略底层服务器，直接部署可随意伸缩的 HTTP 服务的能力。当然，这要求这些函数尽可能无状态。在没有任何请求，闲置一定时间时，这些函数进程会直接消失以腾出计算资源，直到下次事件驱动它们迅速重新启动并继续提供服务。这便是老生常谈的 Serverless。

初次了解 Serverless 也是非常惊讶。AWS Lambda 竟能将 function 如此商业化 (FaaS)，Vercel 在此之上也做到了开箱即用。借助 Cloudflare 现有的数据中心，Cloudflare 也推出他们的 Serverless 解决方案 - [Cloudflare Workers](https://blog.cloudflare.com/introducing-cloudflare-workers/)。不同的是，Cloudflare Workers 相比原始的 Vercel Serverless Function 而言能够做 Server Sent Event、WebSocket 这类支持长连接的请求。尽管后续 Vercel Edge Function 也能实现，但是它能支持的 Node.js Module 实在太少了。（作者注：后来我才了解到 Vercel Edge Function 其实构建于 Cloudflare Workers 之上）

前不久，Cloudflare [开源了 Workers 运行时 workerd](https://blog.cloudflare.com/workerd-open-source-workers-runtime/)。

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

Cloudflare Workers 有许多应用场景。比如实现一个简单的[短 URL 重定向服务](https://lucjan.medium.com/free-url-shortener-with-cloudflare-workers-125eaf87b1ec)、[GitHub Proxy](https://github.com/hunshcn/gh-proxy)、以及一大堆各自实现的 ChatGPT API Proxy...方便了太多国内用户。

Node.js 作者 Ryan Dahl 这几年给 JavaScript 写的另一个全新运行时 [Deno 也有类似的 Serverless 服务](https://dash.deno.com)，体验也很友好，同样[支持 Web Standard API](https://twitter.com/la3rence/status/1642798082294251520)。

为了实现 Serverless 的更多数据持久化功能，他们也各自推出了自家的 KV 存储实现服务，或者说是 Serverless 数据库。

## Cloudflare 在 TLS 协议上的努力

### Client Hello - SNI

再来谈谈技术方面的一些进展。很多读者都知道 Server Name Indication（服务器名称指示，SNI）的存在，它是 TLS/SSL 协议在最初的 Client Hello 阶段由客户端发往服务端的一个字段，内容是网站的主机名或域名。引用 Cloudflare 的形象解释：

> SNI 有点像邮寄包裹到公寓楼而不是独栋房子。将邮件邮寄到某人的独栋房子时，仅街道地址就足以将包裹发送给收件人。但是，当包裹进入公寓楼时，除了街道地址外，还需要公寓号码。否则，包裹可能无法送达收件人或根本无法交付。许多 Web 服务器更像是公寓大楼而不是独栋房子：它们承载多个域名，因此仅 IP 地址不足以指示用户尝试访问哪个域名.....当多个网站托管在一台服务器上并共享一个 IP 地址，并且每个网站都有自己的 SSL 证书，在客户端设备尝试安全地连接到其中一个网站时，服务器可能不知道显示哪个 SSL 证书。这是因为 SSL/TLS 握手发生在客户端设备通过 HTTP 指示连接到某个网站之前。

有点类似于 HTTP 协议中的 `Host` 请求头（如果在同一台服务器上用 Nginx 配置过多个虚拟主机应该都熟悉），但是 SNI 是作用在 L4，而且在 TCP 握手前完成。起初它并不是 TLS 协议的一部分，最早在 2003 年作为扩展字段增加到 TLS 协议中 ([RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066#section-3))。现代浏览器等客户端都早已支持这个字段。我们会发现一个细节问题，对基于同一 CDN 的网站的 HTTPS 请求，我们传入的 TLS `SNI` 和 HTTP Header `Host` 会有不一致的情况，在不严格校验 SNI 的情况下，这类请求有可能被路由到 `Host` 所定义的主机上，本质也就无视了 `SNI`，因此对于某些防火墙来说，由于它们能通过 SNI 来侦测到用户所请求的 HTTPS 站点，它们无法得到后续 TLS 握手后的 HTTP 报文内容，在客户端更换了 Header `Host` 后，实际返回的 HTTP 报文内容其实已被调包 —— 这种攻击方式，或者说叫伪装方式被称为[域前置(Domain Fronting)](https://zh.wikipedia.org/zh-cn/%E5%9F%9F%E5%89%8D%E7%BD%AE)技术。Cloudflare、CloudFront 都会校验二者的一致性返回 403，但依然有部分 CDN 对这一做法采取保留，比如 Fastly。

我们可以用 WireShack 抓包获取到 `SNI` 字段。应用这个过滤条件 `ssl.handshake.extensions_server_name`，尝试抓包发送一次 TLS 请求

```sh
openssl s_client -connect lawrenceli.me:443 -servername lawrenceli.me -state -debug < /dev/null
```

![SNI](/images/cloudflare/sni-field.png)

可以从结果看出，SNI 确实使用了明文进行传输，这就导致了前文提到的一个问题 - 就算经过 TLS/HTTPS 加密的流量，仍然明文地暴露了我们在访问的域名。「这又如何？DNS 不也暴露了嘛？」好问题 - DoH 解决了 DNS 请求的明文风险 ([RFC 8484](https://datatracker.ietf.org/doc/html/rfc8484))。因此，实际上 TLS 目前唯一在数据上有泄密风险的就只有这个字段了。Cloudflare 先后搬出了两个解决方案：[ESNI](https://www.cloudflare-cn.com/learning/ssl/what-is-encrypted-sni/) 以及 [ECH](https://blog.cloudflare.com/encrypted-client-hello/)。

我们可以使用 Chrome 的开关 `chrome://flags/#encrypted-client-hello` 来开启浏览器 ECH 的客户端支持。通过 Chrome DevTool 的 Security Tab 能够查看 HTTPS 流量的安全性信息。我们可以通过[这个链接](https://crypto.cloudflare.com/cdn-cgi/trace)来测试客户端对这个方案的支持情况，当然，这些需要服务端做相应的配置才能完全启用。话题就此结束，我不能再细说了。

Updated：[2023 年 9 月底，Cloudflare 宣布向所有基于 TLS 1.3 的代理站点启用 ECH](https://blog.cloudflare.com/announcing-encrypted-client-hello/)，目前默认全部启用且改选项不可关闭。

### Client Hello - JA3

利用 Client Hello 来做安全保护的另一个实践是 TLS 客户端指纹: JA3 & JA3S。这一设计灵感来源于信息安全专家 Lee Brotherston 的研究 [TLS fingerprinting](https://blog.squarelemon.com/tls-fingerprinting/)。

具体的工程实践可以参考 [Salesforce 开源的 JA3](https://github.com/salesforce/ja3).

<div>
  <github user="salesforce" repo="ja3"></github>
</div>

简而言之，TLS 握手过程中客户端发送的字节数组，也就是 Client Hello 阶段的一些字段和扩展名，通过固定方式拼接，基于摘要 MD5 来生成一个唯一的字符串，称为 JA3 指纹。不同的浏览器或 TLS 客户端有不同指纹。在大量的数据采样中，Cloudflare 就能够基于此数据 (JA3 & JA3S，后者包含了 Server Hello 阶段的服务端指纹) 统计出哪些请求来自于僵尸网络、机器人爬虫、Python 库还是正常用户的浏览器、或者手机访问。这也就解释了很多同学写爬虫时，利用 HTTP 协议更换 `User-Agent` 这一请求头无效的情况，因为 Cloudflare 的防御处在更底层的 L4 TLS 阶段。ChatGPT 的 Web 端也部署了 [Cloudflare 的 TLS JA3 指纹鉴定 WAF (仅限 Enterprise 账户)](https://developers.cloudflare.com/bots/concepts/ja3-fingerprint/)；GitHub 上我也找到了相关的代码实现通过更换 TLS Client 的方式来绕过这一防御。对于多数人来说，这已经有很大的防爬门槛了；而且 Cloudflare 可以随时更换 WAF 策略让旧的指纹失效。

JA3 由来自 salesforce 的三位工程师共同实现：John Althouse, Jeff Atkinson & Josh Atkins。看到这里，想必你也知道为什么 JA3 叫 `JA3` 了。

## 盈利模式

和 Vercel，Netlify 如出一辙，Cloudflare 采用「免费试用，付费增值」的商业模式。Cloudflare CEO Matthew Prince 曾在 StackOverflow 上回答过这个问题：「[How can Cloudflare offer a free CDN with unlimited bandwidth?](https://webmasters.stackexchange.com/questions/88659/how-can-cloudflare-offer-a-free-cdn-with-unlimited-bandwidth)」：

- 更多的免费用户意味着更多的数据，这些数据能更好地帮助保护付费用户
- 很多大客户的来源正是由于这些公司的员工是 Cloudflare 的免费用户，他们在工作中向公司推荐了 Cloudflare
- 免费这一举措就是在做宣传，可以减少招聘成本，能雇到全球最厉害的工程师
- 免费用户体验新功能的同时也能就帮助了这个新功能的测试，缩短了迭代周期
- 带宽成本的鸡生蛋、蛋生鸡问题：用户数量庞大才能在面对全球各地的电信营运商时有议价权

2019 年，Cloudflare 在纽交所上市，股票代码：NET。发行价 US $15，目前 US $63，上涨了 320%。画外音：现在买它还来得及吗？

在中国目前和京东云合作，仅限企业用户。500 强企业中目前有三分之一使用 Cloudflare，还有很多上升空间。OpenAI 的 [ChatGPT](https://chat.openai.com) 上线后，Cloudflare 获得了大量曝光，防御了大量滥用用户和潜在威胁请求。

## 价值观

Cloudflare 因坚持网络中立原则受到了一些批评。

比较典型的一件事是 Cloudflare 因舆论和法律的压力[终止对 8chan 的服务](https://blog.cloudflare.com/zh-cn/terminating-service-for-8chan-zh-cn)。Cloudflare 声称自己是一家私营公司，并且 Cloudflare 半数营收来自于美国之外的地区，可以不受美国宪法第一修正案的约束，其服务的客户对象是整个互联网市场。由于业务量大，有些包含恐怖主义、仇恨言论的网站也免不了会使用其服务。这也是大多数大型互联网公司所面临的问题。和快播王欣事件类似，他们都不愿扮演内容仲裁者。互联网诞生至今，法律的步伐总是跟不上技术的发展。

## 尾声

OpenAI 的 ChatGPT 对 Cloudflare 作了一次很好的展示，我向读者推荐 Cloudflare。一方面是因为它一直提供永久的个人免费服务，另一方面是它的易用性以及全球视野。我也用过国内某套路厂商的 WAF 产品，界面纷繁错乱，一看账单都不知道为什么收费，套路太深，价格高昂（可能怪我太穷）。


一家免费提供 DDoS 防护的 CDN 厂商。

Cloudflare


APPLE: <trade symbol="AAPL" />

过年回老家看电视，运营商送的网络电视盒子主屏幕花花绿绿，我一个程序员都费了好久才找到地方卫视的直播频道。

索性去电商平台搜搜看有没有更好的硬件、翻看各种测评文章和视频。清晰了需求定位后，我果断找了一家有现货的店铺下单了一款美版 Apple TV 2022 (4K)。

![Apple TV](/images/apple-tv/tv.jpg)

一直担心年前收不到货，没想到快递很敬业地发过来了。

由于购买之前就已经熟悉了大部分使用细节，所以安装、使用的时候毫不费力；像是把玩过很久的玩具一样自然流畅。

用美区 Apple ID 购买了很多付费应用，主要都是一些国内独立开发者的作品。

- Alplayer
- APTV
- IIVA
- Miao Projects
- VidHub

很难想象不少开发者会为国内极其小众的平台开发上架了如此小而美的 tvOS App。

搜集一些电视直播源，我就反常地看起了 CCTV。比期待的画质高出不少。遥控器的金属质感像第一次摸到棱角分明的 iPhone 5S 一样爱不释手！还用它和我爸玩了一局桌球游戏。

种种体验让我想起[知乎上一个回答](https://www.zhihu.com/question/477077785/answer/2425144012)：

> 长这么大，听过最清晰的《义勇军进行曲》是在 Apple Music。


Apple TV


[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 协议的简单实现


## Tech

技术方面今年依旧学习了很多新的内容。

首先从 0 到 1 使用 Next.js 重构了此 lawrenceli.me 的整个站点。由原先基于 Notion 私有 REST API 的 hacking 方式换成基于纯 Markdown 文本的 SSG（静态页面生成）和 ISR （增量静态再生成）并完成了几乎没有太多压力的 [Next.js 13 升级](https://nextjs.org/docs/upgrading#upgrading-from-12-to-13)。所有文章内容均和代码共存，这样能在所有页面上自由发挥，甚至可以在纯 Markdown 文件中直接使用 React/JSX 组件（基于 HTML 抽象语法树 - AST）。依赖的版本也基于 GitHub 自动的 PR 保持了最新。 React/JSX 写的也比去年熟练多了。
另外简单研究了一下 TailWind CSS，上手很快，也在此站点上用上了。

[Node.js 模版项目](https://github.com/la3rence/node-express-example) 完工，一个快速使用 JavaScript 开发 REST API 的脚手架项目，各种测试、CI/CD、Code Coverage、日志、Open API (Swagger)、JWT 等基础设施都加上了。摒弃了古老的 CommonJS 而基于纯 ES Module。

<div>
  <github user="la3rence" repo="node-express-example"></github>
</div>

[WebSocket Cluster](https://github.com/la3rence/websocket-cluster) 项目在 GitHub 上也快到达 100 stars 了，每周都会看到一两个国人参考我那很久没维护但精妙绝伦的代码。

年底 Spring 6 和 [Spring Boot 3 的 GA](https://spring.io/blog/2022/11/24/spring-boot-3-0-goes-ga) 同样令人欣喜。我们终于可以基于 GraalVM 的 AOT 去做 Spring Native on Cloud Native 了。JDK 8 仍有接近 7 年的寿命。JDK 17 的 ZGC 是最值得研究学习的，另外下个 JDK LTS (JDK 21?) 应该会让协程 (虚拟线程) GA，目前仍在孵化阶段。学 JavaScript / TypeScript 就是玩玩，真正企业级大型项目还得看 Java。为什么这么说，你去看看 [Nest.js](https://docs.nestjs.com/controllers) 就知道了。

另外又用上了一个比较简单可靠的托管服务（关键是免费）：[fly.io](https://fly.io/)，除常规项目外，它可以部署 Docker 容器，并提供大概 3 GB 额度的免费磁盘挂载。大多静态页面和轻量 Serverless 都依赖 Vercel 或 Cloudflare Workers，一旦遇到需要更加复杂的场景（比如 WebSocket 或 SSE），我会选择使用 fly.io 来部署。

Solidot Robot 已稳定运行将近一千天了，目前依旧基于 Vercel Serverless Function。异常稳定。[Solidot](https://www.solidot.org/) 依旧是我每天都会逛的科技新闻源。

## Work

公司内的 OpenShift 今年并没有花太多时间研究，权限、开发环境问题无法在本地快速调试容器。当然我依旧对 Kubernetes 保持高昂的学习热情，并用半个工作日的时间完成公司对所有开发人员提供的 immersive training。

我对所在团队 (CVA Trading Desk[^1] in XVA) 的业务有了一定的认知：
CVA Trading Desk 其实是一家内部保险公司。负责保障 Business Line Trading 在 couterparty (交易对手) 有可能失信、违约的风险下，可以得到来自 CVA Trader 专门针对此 couterparty 的风险做 Hedge 交易而得到的利润补偿；当然 Business Line Trader 会向我们 CVA Desk 定期支付保险费用。

![CVA Desk](/images/2022-in-review/cva-desk.gif)

每天有数以百计的 Batch Job 去处理这些 Trade 数据。最累的还是作为一个开发去解决各种突如其来的 production issue。

## Life

### WFH & COVID

新冠瘟疫给我带来的除了处于长期封控下的 WFH，~~没有额外影响~~。我可能是相对幸运的一批了 —— 从未因此损失什么，反而得出了类似「[草台班子](/blog/makeshift-troupe/)」的观点。

经历上海的封控后，我现在已经会炒相对好吃一点的蛋炒饭了。还给前不久程序员做饭指南 How to Cook 出圈之前贡献了一份[可乐鸡翅的 PR](https://github.com/Anduin2017/HowToCook/pull/159)。我发现中国人花在食物烹饪的时间成本上有点高，我依然点了不少的外卖。等各方面条件具备后我会尽可能花少的时间做简单的西餐来替换现有的饮食方式、并持续减少盐分、高油脂的摄入。

2022-12-27 后续更新: 发布此文后一周，我感染了新冠病毒。多次高烧突破 40 度，目前仍有些许低烧、乏力、困倦、多汗，并几乎同时丧失了味觉和嗅觉。我的父母也几乎同步感染，尽管我目前和他们不生活在一起。和多数人一样，可能是有生之年最痛苦的一次发烧经历。

### Music

周杰伦的今年新专马马虎虎。力荐的那当然是今年 The 1975 的新专 [_Being Funny In A Foreign Language_](https://music.163.com/#/album?id=153050699)。另外附上 Matty 在 Apple Music 的真诚采访：

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

### Movie

毕业后的这几年看观影、观剧的时间不那么充裕了。今年相对好了一点，但在豆瓣也仅标记了 20 多部。漫威自从复联四结束后最近这两年口碑有点差了，《雷神 4》拍得稀烂，希望来年有新的精彩故事线。今年看的比较好的商业片里印象深刻的有：《瞬息全宇宙》《壮志凌云 2：独行侠》《投行风云》《西线无战事》以及三季《Barry / 巴瑞》，尤其是这部 HBO 的犯罪片，讲述退役兵逐梦演艺圈的故事，很久都没有两三天一口气刷完好几季的感觉了，现在无比期待 2023 年的第四季。

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

## Things

软件领域，我把我常用的《极光词典》换成了《欧路词典》，导入了 iOS 内置的 mdx 词库文件。理由是《极光词典》不具备单词本功能，复习新单词无任何操作入口，但我仍然保留了它，因为作为词典这种功能型应用，已然完全胜出市面 99% 的同类产品了。

效率工具方面接下来我会重点去使用 [Retool](https://retool.com/) 开发一套自己的 Workflow，类似于 IFTTT 的平台但复杂度比 IFTTT 高许多。搜索领域我开始用了 ChatGPT Chrome Extension 搭配 Google。

文本编辑器方面，我开始尝试使用 [Obsidian](https://obsidian.md/)。目前桌面端和移动端都有一些 bug，作为 Markdown 编辑器，它的使用门槛对小白来说很低 —— 单纯的码字工具而已，而它的上限对习惯折腾的玩家来说也很高 —— 丰富多元的社区第三方插件。

最后不得不提的便是 Cloudflare 的优秀网络工具 [WARP+](https://1.1.1.1/)。他们开会期间我完全依赖它才能正常上网。使用期间发现 WARP 有流量限制，利用 API 刷到了几十 TB 的额度后发现其下「零信任网络[^2]」是完全免费且不限流量的 —— 我果断切换成此模式，同时仍然续费另外一项网络协议工具互为备选方案来帮我维持突破网络封锁的高可用。

## Have fun, secretly

今年 10 月中下旬，我的网易云账号因在某天评论了一首歌被禁言 366 天。微博帐号也只因**点赞**评论某事件[^3]的微博而被永久封禁。对此我的态度只有：

> 😅

[^1]: [The Role of a CVA Desk - O'Reilly](https://www.oreilly.com/library/view/counterparty-credit-risk/9781118316665/c18anchor-2.html)

[^2]: [Cloudflare Zero Trust](https://www.cloudflare.com/zh-cn/products/zero-trust/)

[^3]: [现状不可描述](https://bit.ly/3V5V1NG)


写在 2022 年末


鲁迅童年时代看的那些社戏，也叫草台戏，草台班子得名于此。通常有三五人在乡村空旷处搭上一处简陋布篷，水平不一的戏曲演员唱些群众喜闻乐见的戏曲，天黑了收点门票钱就拆台收东西继续赶往下一处演出。我很小的时候在外婆家有幸听过一回，都是老人带着小孩去听戏，内容全无印象。

后来，见到有位网友有如下生动总结：

> 我工作以后才发现，大家都是草台班子。XX 草台，企业草台，我也草台，大家都草台，凑合赚钱过日子。一个企业，看着像一台奔驰在高速公路上的豪华轿车，里面其实是几个人蹬着自行车顶个壳。路上的车都是这样，大家谁都不戳破。

我们童年时代看大人们做事、参与各种社会活动，可能总会觉得他们应该是清晰、明确地知道自己在做什么，并且知道自己为什么要这样做，甚至基于此会构建出科学理性的决策。毕业多年后，结合我所经历的一些工作（长三角地区，囊括上市公司、外企、创业团队），以及所认识的在诸多行业、诸多企事业单位的打工人经历，愈加肯定上述观点。

马某去年在[某峰会上的一席话](https://finance.sina.com.cn/money/bank/bank_hydt/2020-10-24/doc-iiznezxr7822563.shtml)，正是启发我找到类似观点的导火线：「中国金融没有系统性风险，因为中国的金融基本没有系统」。

他所谓的「系统」是什么？会不会是一系列共识协议？或者法律条文？亦或是由上到下的多级政府部门？还是说某类高度复杂的中心化组织？... 我不知道，听众也不知道，或许马某自己也不知道。这个系统是什么我们无从得知，但唯一确定的是，它一定不是草台。

我不相信「车到山前必有路」。我一直坚信，人一定会犯错；而且往往出于本位主义的影响，会形成对现状的误判。系统性的思维有助于减少这类情况的发生，无论现状是如何的草台。拥有系统性思维的人却总是那么少。你不可能对于一项没有经历过的事物、事件产生全面的、全局的、深刻的洞见，这种看待事物的方式往往被人形容成「上帝视角」。问题来了，没有上帝，如何拥有系统性认知？现代工业提供了一种可能，机器。机器永远不会欺骗我们。我们可以利用计算机软件，按照既定的领域 (Domain) 规则，使用恰当的计算机语言，构建出运行在物理硬件设备上的、具备现实意义的[真正的系统](https://zh.wikipedia.org/wiki/%E5%86%AF%C2%B7%E8%AF%BA%E4%BC%8A%E6%9B%BC%E7%BB%93%E6%9E%84) —— 只要它有确定的规则和输入。

除了计算机领域，我目前没有见到所谓类似的系统了。软件工程已经教我们用科学的方法论去驾驭计算机科学，但人类社会总会有一些草台班子的案例：

- 2020.1 「能」「明白」
- 2021.1 大连车务段，全力攻关一昼夜
- 2022.2 某外交部发言人对俄乌战争开战前的评论：M 国情报就是个笑话
- 2022.6 某岛国公务员：因醉酒丢失包含 46 万公民信息的 U 盘
- 2022.7 某地某公权力部门：十亿公民数据泄露
- 2022.8 某地大数据中心：4850 万数据泄露
- 2022.9 某地隔离转运大巴车侧翻致 27 人遇难
- ...

人们愿意相信使用计算机技术所展现出来的数据给人带来安全感，一种「啊，都在系统中」的幻象，一种不那么草台的假象。当然，上述草台案例虽然看似和技术息息相关，本质上和它关系不大，更多时候是工程问题和流程问题，本质还是人的问题。对于数据泄露事件，他们决口不会承认，甚至会采取[审查](https://s.weibo.com/weibo?q=%23%E5%8D%81%E4%BA%BF%E5%85%AC%E6%B0%91%E6%95%B0%E6%8D%AE%E6%B3%84%E9%9C%B2%23)措施防止事件放大，至少邻国事件的主角还会假装鞠一躬以应付公众。

除上述领域外，方方面面都有类似的草台班子。「微博办案」、苏州和服事件、「专家建议」，无一不彰显司法或舆论的草台。法治的道路还有很远要走，十年前的[宪政梦](https://zh.wikipedia.org/zh-cn/2013%E5%B9%B4%E3%80%8A%E5%8D%97%E6%96%B9%E5%91%A8%E6%9C%AB%E3%80%8B%E6%96%B0%E5%B9%B4%E7%89%B9%E5%88%8A%E4%BA%8B%E4%BB%B6)也至今仍然不让做。

现代社会发展的历史，也是革草台命的历史。或许有人会因为工业化的成就而沾沾自喜，但在[脱节的国度](https://books.google.com.hk/books?id=lINbEAAAQBAJ&printsec=frontcover&dq=%E8%84%B1%E8%8A%82%E7%9A%84%E5%9B%BD%E5%BA%A6&hl=zh-CN&sa=X&ved=2ahUKEwiKi8r2_fP5AhVaslYBHdv5AR4Q6AF6BAgIEAI#v=onepage&q=%E8%84%B1%E8%8A%82%E7%9A%84%E5%9B%BD%E5%BA%A6&f=false)里我反而希望有更多冒名顶替综合征患者。加入外企一年多，我感受到 M 国公司为 Business Continuity 做出的基础设施投入相比国内的草台来说高了不少，也让员工产生出「你处于我们的系统之中」这样的幻想，但是我们不能保证这些基础设施都不是草台，因为供应链攻击是常有的事。一个恰当的 meme：

![Mordern Infrastructor](/images/makeshift-troupe/infra.png)

大多数人原本或许并不草台，当他们加入某个草台团体时，会因团体的草台而被迫草台，或者离开。死海效应则是最佳例证。西语也有类似观点：

> Culture eats strategy for breakfast.

不可否认，所有有人的地方都会有草台班子的影子，从真正的草台戏到硅谷华尔街，从派出所到外交部。毛主席就讲过:

> ......只是一个空架子，其内面全没有什么东西...... 生息了四千多年，不知干什么去了？一点没有组织，一个有组织的社会看不见，一块有组织的地方看不见...... 没有科学脑筋，不知分析与概括的关系，有小的细胞才有大的有机体，有分子的各个才有团体。 _《毛泽东早期文稿》_

或许有人说，这个社会需要草台，因为草台少了唱戏的可能会饿死，社会达尔文可不是闹着玩的。但更多时候这会让自己意识到：时刻保持谦卑和同理心，降低对群体的期望，厘清群己权界，才能和这个草台世界和解 —— 那是机器不曾具备的素质。

倘若消极看待整个人类社会，荒诞的草台班子或许是唯一最终能看到的答案。之所以荒诞，是因为对客观世界的认知能力没能达到一定层次而造成的心理落差 —— 这个世界的本质就是荒诞，只是草台现象的必然发生超出人类的合理认知；悲观的人一次次看到这种落差的存在会陷入本不该有的精神内耗。对此也许我们可以改变自身的眼光，始终抱以善意、同情的态度去解释所谓草台班子的行为，并积极参与、鼓励、帮助改变不合理的、荒诞的规则，构建符合当代人类认知的合理的但不绝对合理甚至未来还显得荒诞的社会意识。

生命的力量在于不顺从，或许我所能发现人类社会中的唯一不草台的地方在于人类不接受草台的设定本身，

本文受下列文章启发有所感：

- <https://successfulsoftware.net/2022/06/19/no-one-knows-what-they-are-doing/>


出自 S1 社区的草台班子理论，全员草台。

草台班子

## 使用方式

本站源码完全公开：[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 样式

这个网站是如何构建的


## 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


聊着天就把活干了。

---

公司的运维一直由我来帮助实施。去年将所有微服务容器化后，运维的成本面临新的挑战。本着解放生产力的目标，顺带回忆不太熟悉的 Go 基本语法，笔者写了一个钉钉机器人来帮助我做一些运维的活。效果也不错，就把大体做法在这里讲讲。

做这个之前有一系列的必要（也可替换的）基础设施和概念以及 HTTP 服务端开发的认知，能实现这套聊天运维离不开每一个环节以及诸多细节。简单概括一下我是怎么实践的。

### 技术栈依赖

实践 ChatOps 至少需要的基础设施：一个 CI / CD 服务，一个暴露在公网的 HTTP 服务，一个远程 VCS 和一个能提供收发消息 API 的即时通信工具。

本项目采用：

- [Jenkins](https://www.jenkins.io/) (CI / CD，经典的持续集成工具，提供公网可访问的 REST API)
- [Git](https://git-scm.com/) (VCS，本项目使用公司正在用的 [Gitee.com](https://gitee.com) - 可使用 [GitHub.com](http://github.com) 或 GitLab，提供 REST API 或 SDK)
- [Serverless](https://vercel.com/docs/serverless-functions/introduction) (用来暴露核心的 HTTP 端点，只是无需运维而已；也不是必须，否则需要有公网服务器)
- DingTalk (限制[企业内部机器人](https://ding-doc.dingtalk.com/document/app/develop-enterprise-internal-robots)，能提供 WebHook 和收发消息的 SDK 即可，或其他类似 Slack 的聊天应用: 企业微信、飞书等等)

### 系统拓扑

![ChatOPS](/images/chat-ops/1.png)

懒汉只会和机器人以聊天的形式交互，[其余的脏活累活重复劳动交给机器人做](/blog/the-world-as-i-see-it)。大致流程如图，重点实现：

- 迎接聊天机器人的 HTTP 请求
- 根据请求文本触发行为
  - Git Workflow
    - Approve Pull Request
    - Test Pull Request
    - Merge Pull Request
    - Show PR list
  - CI / CD
    - CI Test
    - Deploy to Production

很显然，核心的开发工作的都在 Message Handler 那里。根据聊天机器人提供的 Event Hook（每次聊天机器人收到消息时会自动向某个服务器发送 HTTP 请求，会携带发送消息的用户、消息内容等 Payload），可以设计一个 HTTP 端点，在服务端解析这些请求（钉钉需要按照企业内部机器人开发，[参考这篇开发文档](https://ding-doc.dingtalk.com/document/app/develop-enterprise-internal-robots)）。

我们按照 [Kubernetes Prow 的设计语言](/blog/prow)，用一个 `/` 来作为 Tag，形式如同 `/test xxx` .

因此这里必然需要做字符串处理了。除了判断 Tag 的存在之外，要取 Tag 后面的参数。项目用 Go 实现，很简单，贴其中一工具函数的代码：

```go
func StringIndexOf(originalArray []string, wordToFind interface{}) []int {
    length := len(originalArray)
    interfaceArray := make([]interface{}, length)
    for i, v := range originalArray {
        interfaceArray[i] = v
    }
    var indexArray []int
    for i:=0 ; i < length; i++ {
      if strings.Compare(wordToFind.(string), originalArray[i]) == 0 {
        indexArray = append(indexArray, i)
      }
    }
	return indexArray
}
```

拿到参数后继续判断，比如机器人收到了这个指令：

`/merge 233`

即合并第 #233 个 Pull Request。要通过代码来合并，那操作 Git 就需要 SDK 或接口了。考虑到之前写 [Issue Ops Bot](https://github.com/la3rence/OpsBot) 的经验，Google 开源的 GitHub 的 [Go-GitHub](https://github.com/google/go-github) 写起来很方便，Gitee 应该也有人搞吧？果然搜到了华为的 OpenEuler 团队的仓库：[Go-Gitee](http://gitee.com/openeuler/go-gitee)。看来只有大厂才会给这些基础设施写 SDK 啊！果断加依赖:

```sh
go get -u gitee.com/openeuler/go-gitee
```

版本下载下来给的时间戳居然就是这两天的，虽然没有任何测试代码，但看似更新蛮活跃，大胆直接用上了。后面写了一些接口，发现 SDK 提供的一些 API 也不全，比如没有审核通过 PR 和测试通过 PR 的 API，就自己顺带拿 `net/http` 参考着 [Gitee 的 REST API](https://gitee.com/api/v5/swagger) 自己实现了，但是代码太丑陋（本来想模仿项目的写法去写，但是一心只想把功能完成），也没给华为提 issue，等回头有机会写下给它提个 PR 嘿嘿（除此之外我还发现 Gitee 的合并方式没有 `rebase` 选项，只提供 `merge` 和 `squash` ，在所谓的社区企鹅群里和他们提了一下建议，理都不理)。

如果机器人收到类似这样的指令:

`/jenkins test myservice` 或 `/deploy myservice`

那就直接对接 [Jenkins 的 REST API](https://www.jenkins.io/doc/book/using/remote-access-api/) 了。可以直接凭状态码判断响应，安全方面 Jenkins 自身提供了 HTTP BASIC 认证。就不细说了。

之前没有用 Go 写过 HTTP Server，这次也没有写——如果运维一套服务已经很麻烦了，开发出的一套帮助运维的辅助服务本身也需要运维（公网服务器、域名解析、持续的测试和部署等服务器资源以及[注意力资源](https://zh.wikipedia.org/wiki/%E6%B3%A8%E6%84%8F%E5%8A%9B%E7%B6%93%E6%BF%9F)），我就没有使用传统的后端服务，而是使用了自己熟悉的 [Vercel Serveless for Go](https://vercel.com/docs/runtimes#official-runtimes/go)。公开一个 Handler 方法即可，`*http.Request` 结构体指针的 `Body` 就是机器人发来的消息了。

下面是整个 Handler 的大致逻辑，伪代码：

```go
func Handler(w http.ResponseWriter, r *http.Request) {
  defer fmt.Fprintf(w, "ok")
  chatMessage, _ := ioutil.ReadAll(r.Body)
  if strings.Contains(chatMessage, "/deploy") {
     serverName := getServerNameFromMessage(chatMessage)
     jenkinsSDK.deploy(serverName)
  }
  if strings.Contains(chatMessage, "/merge") {
     pullRequestNumber := getPullRequestNumberFromMessage(chatMessage)
     giteeSDK.mergePullRequest(pullRequestNumber)
  }
  ...
 }
```

期待某天 Vercel 能够支持 JVM 语言甚至是 Spring 的 Serverless。

### 效果

比如让机器人展示下仓库目前的 Pull Request，然后测试这个 PR，通过后批准这个 PR，最终合并 PR，上线生产，聊天记录会是这样的：

```plaintext
Users 命令: /pr
Robot 回复: 当前仓库的 PullRequest 列表...
          [#709] fix: typo
          [author] username

Users 命令: /jenkins test micro-server 709
Robot 回复: 开始测试 PullRequest 709
CIBot 回复:
          [jenkins] micro-server ci
          -------------------------
          任务：#666
          状态：开始
          持续时间：0 分 1 秒
          执行人：Host 76.76.21.21

Users 命令: /approve 709
Robot 回复: 审核通过 PullRequest #709

Users 命令: /merge 709
Robot 回复: 合并 PullRequest #709
Gitee 回复: User 接受了 Owner/repo 的 Pull Request !709 fix: typo

Users 命令: /deploy micro-server
Robot 回复: 生产发布 micro-server
CDBot 回复:
          [jenkins] micro-server cd
          -------------------------
          任务：#233
          状态：开始
          持续时间：0 分 1 秒
          执行人：Host 76.76.21.21

# 友好地提供帮助
Users 命令: /help
Robot 回复: 当前支持指令列表, 带 * 需要特定人员发起
          /pr - 展示仓库发起中的 PR
          /jenkins <action> <servername> <pr-number> - 在指定 PR 下发起后端测试
          /pass <pr-number> - * 测试通过指定 PR
          /approve <pr-number> - * 审核通过指定 PR
          /merge <pr-number> - * 合并指定 PR
          /test <servername> - 在仅有一个 PR 的状态下发起后端服务测试
          /deploy <servername> - * 发布服务至生产环境
          /help - 显示此帮助内容
```

代码写的很丑陋，没脸往外放了，而且也是企业内部使用，就不开源了（所有变量，十个左右，都配置在环境变量中，尽量没有 Hard Code）。

社区也有不少钉钉机器人的 SDK，阿里没有提供 Go 版本的，但写起来也不复杂，顺手提供自己写的[钉钉群机器人 Go 语言的 SDK](https://github.com/la3rence/dingtalkbot-sdk)，目前就只用来发文本消息。

<div>
  <github user="la3rence" repo="dingtalkbot-sdk"></github>
</div>

最近一次更新，让机器人支持了多个仓库，直接在 `/tag` 最后加一个可选参数 `[repo]`，然后 SDK 的参数做出相应的变动就实现了。

此项实践已作为 ThoughtWorks 员工构建的知识体系 Ledge DevOps 对 ChatOps 这一模式的展示案例：

- [Pattern#ChatOps from Ledge —— DevOps knowledge learning platform](https://devops.phodal.com/pattern#chatops)


DevOps / ChatOps with Dingtalk by GoLang (bot) 钉钉机器人开发应用于运维自动化 Jenkins + WebHook + Git + Pull Request

基于 Go 的 ChatOps 实践


基于 Spring Cloud 使用一致性哈希算法实现分布式 WebSocket. / 基于 RabbitMQ 广播实现分布式 WebSocket.

### WebSocket 协议

参考 [RFC](https://tools.ietf.org/html/rfc6455) 标准规范。

### 思路

核心问题在于具备 WebSocket 服务端的 SpringBoot 或 SpringCloud 等微服务应用是**有状态**的。服务端的内存中存在维持连接的
Session。客户端连接服务器时，只能和集群中的唯一一个服务实例来连接，而且数据传输过程中也直接和此实例通信。

解决方案有很多。

#### 方案一：将状态放到应用之外的存储中，但不可行

这个方案非常类似于 HTTP 协议的 Token 实现（非 JWT），Java 中具体的例子就是 Spring Session 以及 Spring Security 的 Token Store，比如 RedisTokenStore 实现了将
OAuth2 Token 存放到 Redis 的逻辑。此方案的核心前提是可序列化。WebSocket 协议和 HTTP 协议并不同，一个 WebSocket Session 对应于一次 TCP Socket
连接而非数据，新的连接将会基于新的四元组，不可能做到序列化。

#### 方案二：一致性哈希

像微服务注册中心一样，维护一个全局映射关系 —— 当前客户端的 WebSocket
连接是和哪一个实例/节点保持的。每次通信都经过此注册中心或哈希，查询到具体的服务实例，将连接交给它。同样会遇到一些问题，比如：哈希环的实现、如何解决一致性问题（单节点故障的 Session 迁移重连将代价降到最低）、CAP
取舍、实例的区分依据是什么（IP ? 实例
ID？）、可能与注册中心构成强依赖、以及部署环境的变更带来运维上的挑战等难题。这个方案实施有一定的成本和技术限制，可以参考[这篇文章](https://segmentfault.com/a/1190000017307713)的大体思路，理解了核心的哈希环的概念(如下图)，再配合注册中心、服务上下线消息，就能完成基本的实现。我利用
Nacos、Redis、RabbitMQ 基于 Spring Cloud 写了一个通过一致性哈希来实现的全栈项目，前端和后端都已开源 ——
[WebSocket 集群的一致性哈希实践(Spring Cloud 后端) - GitHub](https://github.com/la3rence/websocket-cluster)
, [WebSocket 客户端模拟与服务列表(React 前端) - GitHub](https://github.com/la3rence/websocket-cluster-front),
最近刚刚写好基本的功能，参考 [@ufiredong](https://github.com/ufiredong)
的方式利用 [Java 语言的 Docker SDK](https://github.com/docker-java/docker-java) 实现模拟 WebSocket 实例的上下线。未来还会稍微做细微的优化。

<div>
    <github user="la3rence" repo="websocket-cluster"></github>
</div>

![HashRing: 虚拟节点上线后部分客户端需要迁移节点](/images/websocket-cluster/hashring.png)

另外，Nacos 作为微服务的注册中心是国内比较流行的选择。但有人早就向 Nacos 社区提出了[维护哈希环的议题](https://github.com/alibaba/nacos/issues/2114)；姑且不说此议题是否合理，但
Nacos 的维护人员竟然没有能够理解这样的需求，还是有点令人诧异。

最终效果如下, 上线一个新的服务实例后，客户端会自动根据最新哈希环重新路由到最新节点上，收发消息一切正常：

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

#### 方案三：广播队列

每次连接都需要通知到所有实例，实例各自都判断连接状态在不在自己这里，不在的话直接忽略，在就处理。类似于发布订阅模型，可以通过 MQ（RabbitMQ、Kafka、RocketMQ 等）或 Redis
做到。此方案实现简单，适用于集群规模不大的场景，因为需要所有的节点进行判断或计算。我愿称之为：分布式事件驱动。

以下基于 RabbitMQ 做了简单实现。

##### 简单广播实现 WebSocket 集群

[声明式 API](/blog/declarative-programming) 的好处就体现在这里：短短几行就直接利用了 RabbitMQ 的 Java SDK 创建好交换机和队列以及绑定关系。

```java
package me.lawrenceli.websocket.server.configuration;

import lombok.extern.slf4j.Slf4j;
import org.springframework.amqp.core.AnonymousQueue;
import org.springframework.amqp.core.Binding;
import org.springframework.amqp.core.BindingBuilder;
import org.springframework.amqp.core.FanoutExchange;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Slf4j
@Configuration
public class MqConfig {

    private static final String FANOUT_EXCHANGE = "websocket-exchange";

    @Bean
    public FanoutExchange fanoutExchange() {
        log.info("创建广播交换机 [{}]", FANOUT_EXCHANGE);
        return new FanoutExchange(FANOUT_EXCHANGE);
    }

    @Bean
    public AnonymousQueue queueForWebSocket() {
        log.info("创建用于 WebSocket 的匿名队列");
        return new AnonymousQueue();
    }

    /**
     * @param fanoutExchange    交换机
     * @param queueForWebSocket 队列
     * @return Binding
     */
    @Bean
    public Binding bindingSingle(FanoutExchange fanoutExchange, AnonymousQueue queueForWebSocket) {
        log.info("把匿名队列 [{}] 绑定到广播交换器 [{}]", queueForWebSocket.getName(), fanoutExchange.getName());
        return BindingBuilder.bind(queueForWebSocket).to(fanoutExchange);
    }

}
```

然后是生产者和消费者。生产者将消息发送到队列中进行广播，集群的消费者监听队列，判断此 WebSocket Session 是否在当前消费节点再做进一步处理。

消息生产方，一般是外层接收到消息通信请求，然后调用进行集群内广播：

```java
package me.lawrenceli.websocket.server.configuration;

import lombok.extern.slf4j.Slf4j;
import org.springframework.amqp.core.FanoutExchange;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class FanoutSender {

    @Autowired
    private FanoutExchange fanoutExchange;

    @Autowired
    private RabbitTemplate rabbitTemplate;

    public void send(Object message) {
        log.info("开始发送广播: [{}]", message.toString());
        rabbitTemplate.convertAndSend(fanoutExchange.getName(), "", message);
    }

}
```

消息消费方，多节点共同消费同一消息，区分是否需要自己来处理：

```java
package me.lawrenceli.websocket.server.configuration;

import lombok.extern.slf4j.Slf4j;
import org.springframework.amqp.rabbit.annotation.RabbitListener;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class FanoutReceiver {

    @RabbitListener(queues = "#{queueForWebSocket.name}")
    public void singleReceiver(Object message) {
        log.info("队列接收到了消息: [{}]", message.toString());
        // 判断 WebSocket Session 是否在当前节点
        // 一般维护在一个 ConcurrentHashMap 静态变量中，这里叫 sessionMap
        // message 中有类似 SessionId 的字段
        if (sessionMap.contains(sessionId)) {
            log.info("WebSocket Session 在当前节点");
            // 执行相应的流程
        } else {
            log.info("当前节点无此 WebSocket Session");
            // 什么都不用做，直接忽略
        }
    }

}
```

注意，方案 2、方案 3 都没有解决单节点故障问题，因为从本质上讲，没有实现 WebSocket Session
的全局共享。但是方案二能够依赖哈希环的更新，最大程度上地降低迁移连接的代价，客户端会有重试的机制来针对单节点故障问题做容错。如果规模较大，项目复杂，且客户端连接数多，推荐使用一致性哈希的方案二，当然下面也有其他的社区方案。

### 其他案例

即刻 App 后端基于 Node.js 使用了 [socket.io](http://socket.io) 实现多端实时通信，Joway
的[这篇文章](https://blog.joway.io/posts/socket-io/)交代的一些细节也涉及了分布式部署的问题。

socket.io 官网也提供了[多节点的使用方法](https://socket.io/docs/v3/using-multiple-nodes/index.html)，不外乎 IP Hash 之类的方案。

### Kubernetes 内的 Websocket 集群

如果部署环境基于 Kubernetes 内的 WebSocket
集群，也可以参考[阳明的这篇文章](https://www.qikqiak.com/post/socketio-multiple-nodes-in-kubernetes/)来实践 （利用 Service
的 `sessionAffinity` 会话亲和确保每次将来自特定客户端的连接传递到同一 Pod：使用 `ClientIP` 声明）。


WebSocket 在 Spring Cloud 中如何实践分布式集群：一致性哈希的实现和 Fanout 广播

WebSocket 集群方案


### **Prow** | praʊ |

_noun_. _the pointed front part of a ship; the bow. 船首._

了解 Prow 可以参考这篇知乎专栏：[Kubernetes 原生 CI/CD 系统 Prow 简介](https://zhuanlan.zhihu.com/p/65545774)。

本文重点参考了以下文章，并做了一些问题的修复：

- [Prow Tutorial - KubeSphere‘s Github Repo](https://github.com/kubesphere/prow-tutorial)
- [DevOps 工具链之 Prow](https://www.chenshaowen.com/blog/prow-of-devops-tool-chain.html)

我们并不一定需要使用 Bazel 来构建配置。笔者使用的 Kubernetes 版本为 2020 年发布的 1.19.3。一切的前提是拥有一个 Kubernetes 集群，最好在里面也部署一个 Ingress Controller
用来暴露我们的 WebHook 以及 Prow Deck 前端 Dashboard 服务。

在 K8s 集群中部署 Prow 的具体步骤如下：

首先注册一个 GitHub 账号专门用于作为机器人账号，用此账号前往 [GitHub Developer 页面](https://github.com/settings/tokens)创建一个 Token，权限参考上文，并邀请此账号作为
Collaborators 管理仓库。

随机生成 H-MAC 作为 WebHook 密码安全验证。

```yaml
openssl rand -hex 20 > hmac
```

将他们保存在 `/etc/github/oauth` 和 `/etc/webhook/hmac` 文件下。路径不能错误，因为此处和下面的 Prow manifest 字段匹配。

纳入集群对象：

```bash
kubectl create secret generic hmac-token --from-file=hmac=/etc/webhook/hmac
kubectl create secret generic oauth-token --from-file=oauth=/etc/github/oauth
```

将[以下 Prow 的 manifest](https://gist.github.com/la3rence/79ba7d87cb8a3a44916162d4dece0c66) 做简单修改，注意 Ingress 的域名，namespace 为 `default`：

`gist:la3rence/79ba7d87cb8a3a44916162d4dece0c66`

apply 上述 manifest。过程可能持续几分钟。上面用到的镜像都来自 DockerHub，国内可以直接访问。出现问题尝试打印 Pod 日志或者 describe，用好 Google 和 GitHub 能解决几乎 99% 的技术问题。

```bash
curl -L https://bit.ly/prow -o prow.yaml
vi prow.yaml
kubectl apply -f prow.yaml
```

### **Deck** | dɛk |

_noun._ 甲板

等 Pod 全都 Running 后，项目就成功了一半！现在直接访问 Prow 的 Ingress 地址，可以看到 Prow 的 Deck 前端
Dashboard，类似于：[https://prow.k8s.io/](https://prow.k8s.io/) 。

这时，可以在 GitHub 的项目设置里去添加 WebHook:

1. Payload URL 是你的 Prow Ingress 域名后面直接加 `/hook`
2. Content Type 选择 `application/json`
3. Secrets 是上面随机生成的 HMAC
4. 勾选 `Send me everything`

激活并保存。

接着在集群机器上创建一个 `plugins.yaml` 文件和 `config.yaml` 文件来配置 Prow。

插件的声明：

```yaml
plugins:
  GitHub账号/项目名:
    - size
    - cat
    - dog
    - pony
    - shrug
    - yuks
    - label
    - trigger
    - approve
    - lgtm
    - welcome
    - help
    - assign
    - branchcleaner
    - lifecycle
    - wip
    - heart
    - milestone
    - milestonestatus
    - project
    - stage
    - skip
    - blockade
```

Tide 的配置：

```yaml
prowjob_namespace: "default"
tide:
  merge_method:
    kubeflow/community: squash

  target_url: http://你的域名/tide
  queries:
    - repos:
        - GitHub账号/项目名
      labels:
        - lgtm
        - approved
      missingLabels:
        - do-not-merge
        - do-not-merge/hold
        - do-not-merge/work-in-progress
        - needs-ok-to-test
        - needs-rebase

  context_options:
    from-branch-protection: true
    skip-unknown-contexts: true
    orgs:
      org:
        required-contexts:
          - "check-required-for-all-repos"
        repos:
          repo:
            required-contexts:
              - "check-required-for-all-branches"
            branches:
              branch:
                from-branch-protection: false
                required-contexts:
                  - "required_test"
                optional-contexts:
                  - "optional_test"
```

应用更改：

```bash
kubectl create configmap plugins \
--from-file=plugins.yaml=/root/cluster/prow/plugins.yaml --dry-run -o yaml \
| kubectl replace configmap plugins -f -

kubectl create configmap config \
--from-file=config.yaml=/root/cluster/prow/config.yaml --dry-run -o yaml \
| kubectl replace configmap config -f -
```

可能需要两分钟生效。等一切就绪后，就可以创建 Pull Request 来测试了。效果可以参考 [Kubernetes 的官方仓库](http://github.com/kubernetes/kubernetes)或[我的这个 node
命令行翻译项目](https://github.com/la3rence/Tranclite/pull/5)。

### 使用 Prow

在 GitHub 的 Issue 或 Pull Request 页面下你可以用一个简单的 `/meow` 命令让机器人随机发送一张 🐱 的图片。无需任何刷新，GitHub 页面会自动地更新此页面（后来发现是基于 WebSocket）：

![cat-in-issue](/images/prow/1.png)

我们注意到， Kubernetes 维护人员会使用 `/test` 命令来让集群内的 Pod 执行测试并将结果告诉 GitHub，这就是 ProwJob 实现的了。

ProwJob 主要用于 PR 流程的 CI 测试，而国内网络原因无法使用 Google 的 GCS 服务，ProwJob 中 plank
依赖的 [Pod Utilities](https://github.com/kubernetes/test-infra/blob/master/prow/jobs.md#pod-utilities)，其中定义 GCS Bucket
用于存放构建产物、日志等内容，因此，我们似乎只能自己用自定义的镜像来跑临时 CI 任务了。注意定义 presubmit 字段下的 decorate 为
false，并利用好 [Prow 提供的一些环境变量](https://github.com/kubernetes/test-infra/blob/master/prow/jobs.md#job-environment-variables)。

下面是我的一个简单的 Spring Boot 项目利用 [Maven 镜像（配合阿里云的 Maven Repo）](https://hub.docker.com/r/lawrence2018/aliyun-maven)来做的
presubmits，同样在 config.yaml 中添加：

```yaml
presubmits:
  la3rence/kubernetes-springboot-demo:
    - name: spring
      decorate: false
      always_run: false
      spec:
        containers:
          - image: lawrence2018/maven:3.6-jdk-8
            command: ["/bin/sh", "-c"]
            args:
              - |
                mkdir -p /${REPO_NAME}
                cd /${REPO_NAME}
                git init
                git remote add origin https://github.com/${REPO_OWNER}/${REPO_NAME}.git
                git fetch origin pull/${PULL_NUMBER}/head:pr-${PULL_NUMBER}
                git checkout pr-${PULL_NUMBER}
                mvn test
            resources:
              requests:
                cpu: "2000m"
                memory: "1536Mi"
```

重新配置 config 后并应用更改，在 Pull Request 下评论 `/test all` 或者 `/test spring`
来触发测试。[参考此 PR](https://github.com/la3rence/kubernetes-springboot-demo/pull/4)。

`/test` 后面加 presubmits 的 name 名可触发指定的测试 Pod，all 则测试全部。测试若失败，可使用 `/retest` 来重新测试。

![Prow-in-Pull-Request-Test.png](/images/prow/2.png)

如果测试通过，可使用 `/lgtm` 触发 tide 让机器人合并代码（注意自己不能 `/lgtm`）。

### 自研 Issue/PR Bot

GitHub 大规模使用 WebSocket 来动态修改 Issue 或 PR 页面的 DOM，在视觉上非常令人享受。笔者后来也参考 Prow 用 Go
写了一个简单了 [OpsBot](https://github.com/la3rence/OpsBot) 帮助自己的仓库做一些简单的 PR、Issue 的管理，现已开源，欢迎任何 Issue / PR！

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


Kubernetes 原生 CI/CD 系统 `Prow`。GitHub CI 🤖️ by Kubernetes. @k8s-ci-bot

在 Kubernetes 中部署 Prow


RSS(简易信息聚合): 一系列网络提要格式，用于以标准化格式发布经常更新的作品（博客、新闻、音频和视频）。作者 [Aaron Swartz](http://www.aaronsw.com/) 在 14 岁时设计了它，却在 26 岁自杀。

![Aaron Swartz](/images/long-live-rss/aaronswartz.jpg)

Aaron Swartz 是一位开放互联网原教旨主义的先驱。他的事迹一度影响了我看待世界的方式，他以一种极端的姿态告诉世人如何对抗这个世界。推荐大家看一看十年前上映的《互联网之子》这部纪录片，这是了解 RSS 作者的最佳方式。

这是我自己订阅的一些 RSS 源。

<https://blog.yitianshijie.net/feed/>

<https://byvoid.com/zhs/feed.xml>

<https://martinfowler.com/feed.atom>

<https://sspai.com/feed>

<https://www.solidot.org/index.rss>

<https://www.thetype.com/feed/>

<http://www.aaronsw.com/2002/feeds/pgessays.rss>

2020 年秋，大量 RSS 应用被中区 App Store 下架。

<div>
  <tweet id="1310963891539709952" />
</div>
<div>
  <tweet id="1310553289545658369" />
</div>
<div>
  <tweet id="922363626329133057" />
</div>
<div>
  <tweet id="1311127240713711616" />
</div>

不是所有网站都提供 RSS 支持。好消息是，有一个非常好的站点来让所有人通过 JavaScript 创建 RSS: RSSHub.

你可以访问[RSSHub 官方文档](https://docs.rsshub.app/)来使用。

官方实例部署在[https://rsshub.app](https://rsshub.app/)。

作为 RSSHub 的贡献者之一, 我也乐意分享我自部署的 RSS 实例：

[https://feed.lawrenceli.me](https://feed.lawrenceli.me/)。

我会尽力每天将[我的 RSSHub 代码仓库](https://github.com/la3rence/RSSHub)与[官方仓库](https://github.com/DIYgod/RSSHub)保持同步。

我使用的客户端是 Reeder。另外，出于同步 RSS 源的原因，我自己部署了 FreshRSS 服务，将所有 RSS Feed 保存在一个位置。

![My FreshRSS](/images/long-live-rss/freshrss.png)

你可以试试或上面提到的的任何其他客户端以及任何其他服务端，比如 Feedly、TinyTinyRSS...


RSS 不朽


RSS: A family of Web feed formats used to publish frequently updated works (blog entries, news headlines, audio, and video) in a standardized format. [Aaron Swartz](http://www.aaronsw.com/) helped create it at the age of 14 and committed suicide at 26.

![Aaron Swartz](/images/long-live-rss/aaronswartz.jpg)

Aaron Swartz is a pioneer of open web fundamentalism. His deeds once affected the way I looked at the world. He used an extreme attitude to tell the world how to fight against the world. I recommend you to watch the documentary "The Internet's Own Boy: The Story of Aaron Swartz". This is the best way to understand the authors of RSS.

Here are some feed examples I subscribed for reading:

<https://blog.yitianshijie.net/feed/>

<https://byvoid.com/zhs/feed.xml>

<https://martinfowler.com/feed.atom>

<https://sspai.com/feed>

<https://www.solidot.org/index.rss>

<https://www.thetype.com/feed/>

<http://www.aaronsw.com/2002/feeds/pgessays.rss>

Some apps for RSS were removed from the Chinese App Store in the autumn of 2020.

<div>
  <tweet id="1310963891539709952" />
</div>
<div>
  <tweet id="1310553289545658369" />
</div>
<div>
  <tweet id="922363626329133057" />
</div>
<div>
  <tweet id="1311127240713711616" />
</div>

Not every website supports RSS. But good news is, there's a great web app for everyone to build the RSS feed with JavaScript: RSSHub.

You can visit the [RSSHub doc](https://docs.rsshub.app/) to use it.

The author of RSSHub deployed it on [https://rsshub.app](https://rsshub.app/) .

As a contributor for RSSHub, I'm also glad to share my self-hosted RSSHub for you:

[https://feed.lawrenceli.me](https://feed.lawrenceli.me/) .

I'll try to keep [my repository](https://github.com/la3rence/RSSHub) in sync with [the official RSSHub git repository](https://github.com/DIYgod/RSSHub) every day.

I use the Reeder app for iOS. And also for feed sync up reason I host a FreshRSS service to keep all RSS feeds in one place.

![My FreshRSS](/images/long-live-rss/freshrss.png)

You can also try it or anyother client above and anyother services like Feedly, TinyTinyRSS...


Long Live RSS


## 奇客的资讯，重要的东西 🤖️

这是中国社交网络[饭否上的一个机器人](https://fanfou.com/jayonit)。它是一个基于 [Vercel](https://now.sh) 、mongoDB
的免费数据库、以及 [GitHub Action 提供的声明式定时任务](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#onschedule)一起运行来实现的 Serverless 实践。[作者](https://lawrenceli.me/about)充分利用互联网免费基础设施 ~~(白嫖)~~，让它每隔一段时间（大概 30 分钟）爬取 solidot.org
网站的 [RSS](https://www.solidot.org/index.rss)，比较新旧的数据后，将新的内容通过 [饭否 Node SDK](https://github.com/fanfoujs/fanfou-sdk-node) 发布。

![solidot](/images/solidot-robot/solidot.png)

[源代码](https://github.com/la3rence/SolidotRobot)以 MIT 协议开放，写的很简陋，凑合着能用。

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

你也可以帮我调用[这个 REST API](https://post-solidot-news-to-fanfou.now.sh/api/start) 来帮助触发机器人行动：

```bash
curl -XGET -L https://post-solidot-news-to-fanfou.now.sh/api/start
```

若返回空数组则对应时间段内没有新的内容，反之若抓取到新的内容后，直接返回饭否发布此内容后的 API 响应。

## Todo

- Refactor with ESM


饭否机器人🤖️ Solidot Serverless Robot with MongoDB

Solidot 机器人


命令式编程注重过程，声明式编程注重结果。前者强调代码本身的逻辑，需要开发者重视程序每个阶段的上下文，以一步一步地实现应用功能。后者基于完善的 API / SDK，告诉（声明）程序需要达到的状态（一种状态机），程序会主动、不遗余力地向其驱动一直到达到声明的目标，应用层人员无需在意底层实现。

优雅的 API 往往是声明式的，通常也非常简洁明了。

这里我举一个电风扇和空调的例子：

电风扇：为了实现体表温度的控制，人类利用电动机发明了电风扇，一个命令式风速调节客户端 —— 大部分你需要自己手动地调节电风扇的风向、风速，让身体接受风扇的水平气压梯度力，以让体表流体流动速度上升从而达到吸热的目的。你可能已经间接地知道了它的实现**原理**，尽管这个流程并不复杂。

空调：它是声明式的。你**无需关注**空调自身的实现原理，只需要通过遥控器**声明**它应当达到的温度即可，空调就会驱动自身来实现密闭空间的恒温调节到达期望值 —— 哪怕空间的温度骤变。

虽然栗子并不够恰当，但是用户已经意识到：空调调节起来多简单方便！

软件开发亦如此。

我们其实早已经频繁地和声明式编程打交道了：其实 HTML、CSS、SQL 这些语言自己就是声明式语言；纯函数编程语言也被认为是声明式语言，这非常有趣。另外，前端流行的 React、Vue 都利用了 Virtual DOM 和 diff 算法实现了声明式的 JavaScript 用户界面框架，再也不需要前端开发者去使用 jQuery 或原生写法来操作 DOM。

Java 开发者在开发阶段使用声明式 API 的最典型例子就是运用注解。比如 Spring 提供 `@Autowired` 注解实现 Bean 对象的依赖注入，其实现是基于 Java 语言的反射。Spring 更是提供了大量内置的注解简化了开发人员的开发: `@Transactional` 实现声明式事务, `@Component` , `@Value`, `@Data` ...

首个毕业于 CNCF 的项目 [Kubernetes](https://k8s.io) 中也在充分地让 DevOps 拥抱声明式。它提供了基于 YAML 语法的配置文件（manifest，用以描述容器集群期望的拓扑状态），自动地向配置的声明驱动。云原生应用的一个必要特性就是声明式。

GraphQL 让原本的 REST 更加声明式。这是一个非常适合全栈开发的 HTTP 接口规范，热度最近有在攀升，能否颠覆传统的 REST 不得而知。

Apple 在 WWDC 2019 上发布的 [SwiftUI](https://developer.apple.com/cn/xcode/swiftui/) 和 Google 开源的 [Flutter](https://flutter.cn/docs/get-started/flutter-for/declarative) 一样都是移动端、跨多个操作系统的声明式 UI 框架。

Maven、Gradle、npm、pip、go module 等提供了 Java、JavaScript / TypeScript、Python、GoLang 开发者声明式依赖管理工具，现代的应用开发几乎离不开它们。我还记得第一次手写 Makefile 的痛苦。

GitHub Actions、GitLab、Jenkins Pipeline 提供了基于声明式配置文件（大部分为 YAML）的持续集成流水线，可以让开发人员也能低成本地学习实践 CI/CD。这里 Jenkins Pileline 的实现是基于另一门 JVM 语言 Groovy 的 DSL。

在软件测试领域，BDD (Behavior Driven Development，行为驱动开发) 同样也是声明式。BDD 是为了能让熟悉业务但是不懂编程的用户也能实现业务范畴的自动化测试。 Gherkin 剧本语法面向业务人员提供特定的领域语言来描述软件行为。

开发声明式 API 是很困难的，往往需要开发人员对语言以及框架的拥有深刻认知，并且是一种的利他主义美德:

> 将复杂留给自己，将方便留给别人。

单纯作为用户而言，效率、便利、无副作用是声明式 API 的目的。而作为软件开发者，去意识到这些声明式应用或框架的背后原理往往会更加明白创作者的真实意图，也能更清晰自己所做的声明、或是充分优化应用层代码，而避免陷入[路径依赖与货物崇拜编程](https://lawrenceli.me/blog/path-dependence-and-cargo-cult)的怪圈。

Links:

[https://spring.io/guides/gs/rest-service/](https://spring.io/guides/gs/rest-service/)

[https://www.infoq.cn/article/rest-apis-are-rest-in-peace-apis-long-live-graphql](https://www.infoq.cn/article/rest-apis-are-rest-in-peace-apis-long-live-graphql)

[https://kubernetes.io/zh/docs/tasks/manage-kubernetes-objects/declarative-config/](https://kubernetes.io/zh/docs/tasks/manage-kubernetes-objects/declarative-config/)


Declarative programming - 声明式编程

声明式编程


Kubernetes [中文概述](https://kubernetes.io/zh-cn/docs/concepts/overview/)（是什么以及不是什么）。

实践时建议使用 [kubectl 自动补全](https://kubernetes.io/docs/reference/kubectl/quick-reference/)，极大提升交互效率。

### Pod

Pod 是比容器更高一层次的抽象，同一 Pod 中的所有容器共享

- 同一网络 namespace
- 存储

### Controller

- Deployment
- ReplicaSet
- DaemonSet
- StatefulSet
- Job

### Service

是一个[四层负载均衡器](https://lawrenceli.me/blog/load-balancing)，为 Pod 提供负载均衡。

### MiniKube

国内建议自定义镜像仓库，默认是 [gcr.io](http://gcr.io) ，似乎自带了 PV。

```bash
minikube start --vm-driver=none --image-repository=registry.cn-hangzhou.aliyuncs.com/google_containers --cpus 4 --memory 6144
```

感觉 Docker Desktop 内置的 Kubernetes 有点类似这个 minikube （master 可以直接运行 Pod，也就是单节点集群）。当然了，它们都只能用于开发/测试环境。

### Demo

[用 Spring Boot 创建了一个 HTTP 服务端](https://github.com/la3rence/kubernetes-springboot-demo)，可以尝试用 Kubernetes 部署它。

### 公网服务器集群初始化常用脚本

```sh
cat <<EOF > /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el7-x86_64/
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://mirrors.aliyun.com/kubernetes/yum/doc/yum-key.gpg https://mirrors.aliyun.com/kubernetes/yum/doc/rpm-package-key.gpg
EOF
```

```sh
yum install -y kubeadm-1.19.13-0 kubelet-1.19.13-0 kubectl-1.19.13-0
```

```sh
kubeadm config images pull --image-repository registry.aliyuncs.com/google_containers --kubernetes-version v1.19.3
```

```sh
kubeadm init --image-repository registry.aliyuncs.com/google_containers --kubernetes-version v1.19.13 --apiserver-advertise-address $(hostname -i) --pod-network-cidr=10.96.0.0/16 --service-cidr=10.97.0.0/16
```

```sh
mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config
```

Flannel:

```bash
wget https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml](https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml)
```

```bash
kubectl apply -f kube-flannel.yaml
```

运行 Master 作为 Node:

```bash
kubectl taint node $HOSTNAME node-role.kubernetes.io/master-
```

恢复 Master 不可调度：

```bash
kubectl taint node $HOSTNAME node-role.kubernetes.io/master="":NoSchedule
```

重置：

```bash
kubeadm reset
systemctl stop kubelet
rm -rf /var/lib/cni/
rm -rf /var/lib/etcd/
rm -rf /var/lib/kubelet/
rm -rf /etc/cni/
rm -rf $HOME/.kube
ifconfig cni0 down
ifconfig flannel.1 down
ifconfig docker0 down
ip link delete cni0
ip link delete flannel.1
systemctl restart kubelet
systemctl stop docker
systemctl restart docker
```

Pod 无法访问外网，尝试：

```bash
iptables -P FORWARD ACCEPT
iptables --flush
iptables -tnat --flush

iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X
// POD 无法访问外网络，但是可以互相 ping 或 ping 宿主。CIDR 为 POD CIDR
// 有可能是 SNAT 时出了问题，使用动态 SNAT （即 MASQUERADE） 来配置 nat 表路由规则：
iptables -t nat -I POSTROUTING -s 10.96.0.0/16 -j MASQUERADE
// 再尝试重新运行 core dns 服务
```

[https://github.com/rancher/rancher/issues/6139](https://github.com/rancher/rancher/issues/6139)

[https://github.com/coredns/coredns/issues/2693](https://github.com/coredns/coredns/issues/2693)

网络调试：使用 BusyBox:1.28.3，不建议使用 latest 镜像.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: busybox
  namespace: default
  labels:
    app: busybox
spec:
  selector:
    matchLabels:
      app: busybox
  replicas: 1
  template:
    metadata:
      labels:
        app: busybox
    spec:
      containers:
        - name: busybox
          image: busybox:1.28.3
          command:
            - sleep
            - "3600"
          imagePullPolicy: IfNotPresent
      restartPolicy: Always
```

基于 DNS 的服务发现： Kubernetes Service / Pod 对象资源可以使用集群内部 FQDN 来访问，而不需要在意其扁平空间中的 Cluster IP。
Core DNS 会将 FQDN 动态地指向最新的 Cluster IP。参考 [Pod 与 Service 的 DNS](https://kubernetes.io/zh/docs/concepts/services-networking/dns-pod-service):

```bash
kubectl exec busybox -it -- nslookup kubernetes
```

返回内容：

```bash
Server:    10.97.0.10
Address 1: 10.97.0.10 kube-dns.kube-system.svc.cluster.local

Name:      kubernetes
Address 1: 10.97.0.1 kubernetes.default.svc.cluster.local
```


Kubernetes Notes


爱因斯坦的美国观。

> What first strikes the visitor with amazement is the superiority of this country, in matters of technics and organization. Objects of everyday use are more solid than in Europe, houses infinitely more convenient in arrangement. Everything is designed to save human labour. Labour is expensive, because the country is sparsely inhabited in comparison with its natural resources. The high price of labour was the stimulus which evoked the marvelous development of technical devices and methods of work.

这段话由爱因斯坦在《 [The World As I See It](https://book.douban.com/subject/2058202/) 》中提到。

美国高昂的人力成本促使技术设备、工作方式的惊人发展。现在想想一个案例：中国之所以至今仍有很多挨家挨户抄水电表的人员，不是因为技术上实现不了自动化，而是中国人口太多，社会就业压力大，宁可牺牲效率来换稳定。

站着说话不腰疼的我自己一直奉行一个原则：拒绝机械重复劳作，应当充分发挥机器的优势和人类的主观能动，即将有规则的、确定的流程交给机器去执行，而把富有创造性的工作交给人类。

BLM 运动此起彼伏，许多开源项目在其官网首页顶部加上了醒目的 Slogan，对于美国系统性种族主义此文不作讨论。Kubernetes
官网谈了它的 [社区的价值观](https://git.k8s.io/community/values.md#automation-over-process)，我认为这也是多数开放源码项目社区的价值观：

> We value time spent automating repetitive work more highly than toil.


爱因斯坦的美国观。效率。效率。效率。

The World As I See It


路径依赖原本是经济学中的一个名词，我并不深知其具体领域的定义，但用通俗的话来解释起来非常简单：过去的决策将会限制、缩小未来的可选择性。

笔者首次了解「路径依赖」是源于 BYVoid 的博客文章 —— [在 Google 的这四年](https://byvoid.com/zhs/blog/4-years-at-google-4/)。类比成贪心算法的局限，他提出的解决方案是模拟退火:

> 模拟退火算法的理念是在初期引入随机性，随着迭代次数的增加而减小随机因子，这样最终收敛到全局最优解的机率更大。跟随这个理念来考虑职业的选择，我决定跳出现有的路径，哪怕是这个路径的前方一片光明，现在只是为了体验不同的选择。

再讲一个宗教故事。

二战期间，美军在太平洋的塔纳岛上建了一个临时基地。岛上原住民看到美军的战斗机，以为是「大铁鸟」。美军还会送一些有用的物资给岛上原住民。原住民没见过世面，都以为美军是神。后来，二战结束，美军撤走，还留了一点物资在岛上。岛上居民认为这些物资很神奇，相信这些美国大兵还会送货物过来，纷纷信仰、崇拜起了美军军服和物资（以吸引「大铁鸟」降临）。基于此，原住民发展出了自己的宗教—— 约翰弗鲁姆教。这就是货物崇拜（[Cargo Cult](https://zh.wikipedia.org/wiki/%E8%B2%A8%E7%89%A9%E5%B4%87%E6%8B%9C)）。

货物崇拜在软件工程领域延伸出了货物崇拜软件工程与货物崇拜编程。

货物崇拜软件工程是货物崇拜科学的一个实例。货物崇拜科学是诺奖得主 Richard Feynman 于 1974 年提出的一门伪科学概念。这种类似科学的方法论从道德上就背叛了科学精神。

以下为货物崇拜软件工程的主观实践：

- 盲目模仿成功开发团队的表面现象
- 机械套用软件开发过程却不知其由（即货物崇拜编程）

货物崇拜和路径依赖存在交集。具体表现在开发者的机械式开发。最常见的是：

- jQuery 一把梭

我发现有前端开发者会在使用 Vue/React 等基于 Virtual DOM 的声明式 UI Library 的情况下依旧使用 jQuery 操作 DOM。这是典型的货物崇拜编程实践，因为这样的开发人员完全不理解 Vue/React 是做什么的，因为已经习惯了 $ 的 API，哪管 DOM Virtual 不 Virtual；姑且撇开 Virtual DOM 的性能不说，这样做的开发人员往往也没能够理解[声明式](/blog/declarative-programming) UI 框架的内涵。

上文提到的「模拟退火」是破解路径依赖困境的法则之一。除此之外，笔者认为最适合大多数人的做法是对事物保持强烈的好奇心。正如 Aaron Swartz 所云：

> Be curious. Read widely. Try new things. What people call intelligence just boils down to curiosity.

一些链接：

- [如何「评价老夫写代码就用 jQuery 」[图]](https://www.zhihu.com/question/56085124)

- [维基百科：货物崇拜编程](https://zh.wikipedia.org/wiki/%E8%B4%A7%E7%89%A9%E5%B4%87%E6%8B%9C%E7%BC%96%E7%A8%8B)

- [Quote from Aaron Swartz](https://www.goodreads.com/quotes/709288-be-curious-read-widely-try-new-things-what-people-call)


关于职业规划的思考——软件工程师如何避免陷入路径依赖与货物崇拜编程。

路径依赖与货物崇拜


对于初次了解负载均衡的人来说，可能会被理解成「四次负载均衡」、「七次负载均衡」，这就完全错了。这里要理解的话直接参考英文：layer 4 load-balancing & layer 7 load-balancing. 其实应当理解为工作在 OSI 第四层、第七层的负载均衡。

所以，所谓的层指的是 [OSI 网络模型](https://zh.wikipedia.org/wiki/OSI%E6%A8%A1%E5%9E%8B)中的层次，分别对应于传输层（比如 TCP）和应用层（具体的 Application）。
| Layer | Name | OSI protocols | TCP/IP protocols |
|:---:|:------------:|:---------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------:|
| 7 | Application | FTAM X.400 X.500 DAP ROSE RTSE ACSE CMIP | HTTP HTTPS FTP SMTP |
| 6 | Presentation | ISO/IEC 8823X.226 ISO/IEC 9576-1 X.236 | MIME SSL/TLS XDR |
| 5 | Session | ISO/IEC 8327 X.225ISO/IEC 9548-1 X.235 | Sockets (session establishment in TCP / RTP / PPTP) |
| 4 | Transport | ISO/IEC 8073 TP0 TP1 TP2 TP3 TP4 (X.224)ISO/IEC 8602X.234 | TCP UDP SCTP DCCP |
| 3 | Network | ISO/IEC 8208 X.25(PLP) ISO/IEC 8878 X.223 ISO/IEC 8473-1CLNP X.233 ISO/IEC 10589 IS-IS | IP IPsec ICMP IGMP OSPF RIP |
| 2 | Data link | ISO/IEC 7666 X.25(LAPB) Token Bus X.222 ISO/IEC 8802-2 LLC| PPP SBTV SLIP |
| 1 | Physical | X.25 (X.21bis EIA/TIA-232 EIA/TIA-449 EIA-530G.703) | TCP/IP stack does not care about the physical medium, as long as it provides a way to communicate octets |

因此，基于 OSI 模型，先讲一个三层负载均衡 （即 IP 网络层）的例子 —— DNS 解析，同一个域名可以解析到多个 IP 上，但轮询策略大多数情况下不在自己手上。笔者加入的一家跨国公司内就提供了工作在此层的 Load Balancer，它会根据开发提供的应用健康情况实时动态更新内部网络的 DNS 解析记录，毋庸置疑，公司内部有非常复杂的网络拓扑，包括这样一个工作在局域网中的 DNS 服务器；四层负载均衡其实是在三层基础上加上了端口，也就是通过 IP + Port 的形式进行转发，而七层负载均衡在四层的基础上考虑应用的 URL 或应用层协议的其他字段（比如 HTTP Header）等方式做转发。

由于三、四层负载均衡直接偏底层一些，其代理的效率会比七层的更高，比如单从 TCP 的开销上来看：四层负载均衡时，服务端收到来自客户端的请求，根据负载均衡器的策略，对目标 IP/Port 做修改，转发到对应的后端服务，TCP 三次握手直接一次建立。而七层负载均衡工作在应用层，客户端必须首先与负载均衡器进行一次 TCP 握手，然后负载均衡器再与目标后端服务建立第二次 TCP 握手。相比之下，七层负载均衡的性能就弱了。

一个常见的现象：效率和安全（功能）往往不可兼得。七层负载均衡效率不高，其优势却在于可以植入一些应用上的逻辑，做流量压缩、鉴权、服务迁移、降级、熔断等处理，其可塑性会更好一点，且相对四层可以做一些安全上的设计，因为四层的负载均衡相当于直接间接地暴露了后端服务却难有应用层的调度。四层负载均衡器可以通过硬件实现，比如 F5，常见的软件实现是 lvs、nginx 中的 stream block，[Kubernetes 中的 Service 对象](https://kubernetes.io/zh/docs/concepts/services-networking/service/)。七层负载均衡器一般是一些高性能网关，比如 [OpenResty](https://openresty.org/cn/)，[Kubernetes 中的 Ingress 对象](https://kubernetes.io/zh/docs/concepts/services-networking/ingress/)。

最后我有个小问题，倘若我们使用 DoH (DNS over HTTPS) 技术进行某个 FQDN 的解析，比如 Cloudflare 的 DNS HTTPS API：

```bash
curl -H "accept: application/dns-json" "https://1.1.1.1/dns-query?name=lawrenceli.me"
```

假设此 HTTPS API 的结果会以 Round Robin 的形式返回多个不同的 IP 地址，那么仅基于此 DoH 做 DNS 解析的 Load Balancer 工作在第几层呢？
我的答案仍然是第三层——事实上 DNS 工作在第七层，但是负载均衡器发挥的作用仍然是改变了处在第三层的 IP 地址。


四层负载均衡和七层负载均衡


Next.js 有两种形式的预渲染：**静态生成**和**服务器端渲染**。 区别在于**何时**生成页面的 HTML。

- **静态生成**是在**构建时**生成 HTML 的预渲染方法。 然后，每个请求都会*重用*预渲染的 HTML。
- **服务器端渲染**是在**每个请求**上生成 HTML 的预渲染方法。

重要的是，Next.js 允许您**选择**每个页面使用哪种预渲染表单。 您可以通过对大多数页面使用静态生成并对其他页面使用服务器端渲染来创建「混合」Next.js 应用程序。


Next.js 的两种预渲染形式


Next.js has two forms of pre-rendering: **Static Generation** and **Server-side Rendering**. The difference is in **when** it generates the HTML for a page.

- **Static Generation** is the pre-rendering method that generates the HTML at **build time**. The pre-rendered HTML is then _reused_ on each request.
- **Server-side Rendering** is the pre-rendering method that generates the HTML on **each request**.

Importantly, Next.js lets you **choose** which pre-rendering form to use for each page. You can create a "hybrid" Next.js app by using Static Generation for most pages and using Server-side Rendering for others.


Next.js: Two Forms of Pre-rendering


来自 LeetCode 的经典算法题：翻转二叉树

> 给你一棵二叉树的根节点 root ，翻转这棵二叉树，并返回其根节点。

有如下输入:

```plaintext
     4
   /   \
  2     7
 / \   / \
1   3 6   9
```

期望输出结果是这样:

```plaintext
     4
   /   \
  7     2
 / \   / \
9   6 3   1
```

该问题由此[推文/X](https://twitter.com/mxcl/status/608682016205344768)所启发.

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

以下为 Java 的实现。

```java
/**
 * Definition for a binary tree node.
 * public class TreeNode {
 *     int val;
 *     TreeNode left;
 *     TreeNode right;
 *     TreeNode(int x) { val = x; }
 * }
 */
class Solution {
    public TreeNode invertTree(TreeNode root) {
        if(null != root){
            TreeNode leftChild = root.left;
            root.left = root.right;
            root.right = leftChild;
            root.left = invertTree(root.left);
            root.right = invertTree(root.right);
        }
        return root;
    }
}
```

软件工程和计算机科学有很大的区别。[后来 Max 在 Quara 上回应了这个问题。](https://bit.ly/2HqaTe5)


翻转二叉树


A problem that Homebrew's author complained.

---

Invert a binary tree. Problem from leetcode.

> Given the root of a binary tree, invert the tree, and return its root.

Here's the input:

```plaintext
     4
   /   \
  2     7
 / \   / \
1   3 6   9
```

and the out put looks like:

```plaintext
     4
   /   \
  7     2
 / \   / \
9   6 3   1
```

This problem was inspired by this [tweet](https://twitter.com/mxcl/status/608682016205344768).

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

Here's the solution implemented in Java.

```java
/**
 * Definition for a binary tree node.
 * public class TreeNode {
 *     int val;
 *     TreeNode left;
 *     TreeNode right;
 *     TreeNode(int x) { val = x; }
 * }
 */
class Solution {
    public TreeNode invertTree(TreeNode root) {
        if(null != root){
            TreeNode leftChild = root.left;
            root.left = root.right;
            root.right = leftChild;
            root.left = invertTree(root.left);
            root.right = invertTree(root.right);
        }
        return root;
    }
}
```

There's much different logic behind software engineering with computer science. [Max replied this question about it on quora.com after 2 years.](https://bit.ly/2HqaTe5)


Invert binary tree


维基： [https://zh.wikipedia.org/wiki/没有银弹](https://zh.wikipedia.org/wiki/%E6%B2%A1%E6%9C%89%E9%93%B6%E5%BC%B9)

文献：Brooks, F. P.，"No silver bullet—essence and accidents of software engineering, " in Information Processing 86, H. J. Kugler, ed. Amsterdam: Elsevier Science (North Holland), 1986, pp. 1069-1076.

结论：不会有任何单一的软件工程上的突破（银弹），能够让程序设计的生产力得到一个数量级的提升。

「**人月神话**」

维基：[https://zh.wikipedia.org/wiki/人月神话](https://zh.wikipedia.org/wiki/%E4%BA%BA%E6%9C%88%E7%A5%9E%E8%AF%9D)

豆瓣：[https://book.douban.com/subject/1102259/](https://book.douban.com/subject/1102259/)

结论：人力和时间并不呈现线性关系。以大量人员和较短的时间，并不能缩短软件的开发进度。

公式：

沟通管道数量（n 为一个项目团队中的人数，显然，人数越多，沟通成本越大）：

```plaintext
p = n(n-1)/2
```

Brooks 法则：

> Adding manpower to a late software project makes it later.

组织：

提倡类似外科手术团队的组织。在接受相同的训练、同样都是两年资历的情况下，优秀专业程序员的生产力要比差劲的程序员好上十倍。

系统设计的民主与专制：

整体性：需要专制，设计必须出自于一个人的想法，或是极少数人的一致决定。

评价标准：功能概念复杂度比。功能多不见得是好事。

避免第二系统过度设计。
