萌约 MoeYork

Javacard 不完全指北

2026-05-25T13:54:00.000Z

Javacard 不完全指北

本文旨在在尽量不出错的情况下简单介绍 Javacard 相关资讯

笔者第一次了解到 Javacard 的存在是在 tuna 的一次金枪鱼之夜分享中

智能卡相关

以下信息不仅适用于 Javacard，通常也适用于其他智能卡

智能卡芯片也有其他封装形式和电气连接方式 (如常见的 ST33 等芯片)

机械尺寸

正常 Javacard 的尺寸与银行卡相同（毕竟是同一个标准），该尺寸为 ISO/IEC 7810 中的 ID‑1 规格；卡片上的芯片触点排列和定义同样由该标准确定

在通常情况下，Javacard 的芯片仅位于芯片触点下方，NFC 通信天线嵌在卡片塑料层中，可以透过高亮度的光源观察

也有尺寸为全尺寸 SIM (1FF) 的 Javacard 售卖

通信协议

物理层

接触式通信通过与卡片上的芯片触点接触来建立连接，通信协议在 ISO/IEC 7816-3 中规定，为异步半双工同步传输协议

非接触式通信通过与卡片上的线圈电磁感应耦合来获得能量和建立连接，通信协议在 ISO/IEC 14443 中规定，工作在 13.56 MHz ISM 频段，标准中规定了两种通信机制 Type A 和 Type B，具有不同的调制、编码和防冲突方式

磁条不参与与芯片的通信，根据矫顽力不同有高抗和低抗等分类，按磁条的磁轨数有双轨、三轨等，不同磁轨的编码方式在ISO/IEC 7811中定义。

通常同时具有接触式和非接触式接口的卡片被称为 “双界面”，额外印刷的磁条也可能被作为一个“界面”，与其他两种的组合被称为 “双界面”或“三界面”

传输层

接触式通信采用两种传输协议：

T=0 (面向字节的半双工传输协议)
T=1 (面向块的半双工异步传输协议)

非接触式采用一种传输协议：

T=CL (非接触式传输协议 Transmission = ContactLess)

传输层负责在卡片上电、初始化完成后打包上层的应用通信数据并交由物理层传输

应用层

应用层采用统一格式的 APDU (Application Protocol Data Unit) 指令进行通信，该格式在 ISO/IEC 7816-4 中描述

C-APDU

终端向智能卡发送的格式为 COMMAND APDU (C-APDU)

===================================================================
|                      COMMAND APDU (C-APDU)                      |
|                         终端 ----> 智能卡                       |
===================================================================
|   CLA   |   INS   |   P1   |   P2   ||  Lc  |   Data   |   Le   |
| (1 Byte)| (1 Byte)| (1 Byte)|(1 Byte)|| (Var)|  (Var)   | (Var)  |
--------------------------------------  ---------------------------
| <---------- Header (必选) --------->|| <----- Body (可选) ----->|
===================================================================

Header 指令头必选

CLA (Class): 指令类别。用来区分应用类型或安全级别 (如 00 表示标准的 ISO 7816 指令，80 常常用于各家卡商的自定义指令)
INS (Instruction): 指令码。告诉卡片要做什么 (如 A4 表示 SELECT 选择应用，B0 表示 READ BINARY 读取数据)。
P1 / P2 (Parameter 1 & 2): 指令参数。提供指令所需的具体参数，通常用作文件偏移量、安全标志或配置选项

Body 可选

Lc (Length of Command Data): 指示后面 Data 字段的字节长度。
Data: 终端实际发送给卡片的载荷数据
Le (Length of Expected Data): 终端期望卡片返回的数据最大长度 (如果填 00，通常表示期望返回最大可用长度，最高 256 字节；扩展 APDU 可达 65536 字节)

R-APDU

卡片处理完指令后，会返回一个响应

=========================================
|         RESPONSE APDU (R-APDU)        |
|             智能卡 ----> 终端         |
=========================================
|        Data        ||   SW1  |   SW2  |
|       (Var)        ||(1 Byte)|(1 Byte)|
---------------------  ------------------
| <--- Body (可选) --->||<-Trailer(必选)->|
=========================================

Data (可选): 卡片返回的实际业务数据。它的长度由 C-APDU 中的 Le 以及卡片内部逻辑共同决定
SW1 / SW2 (Status Word 1 & 2，必选): 状态字。用于指示指令执行的结果

通过状态字可以知道命令的执行情况

SW1	SW2	状态说明 (Description)
`90`	`00`	成功 (Success)
`61`	`XX`	有额外数据待读取 (XX bytes remaining)
`62`	`83`	文件已失效 (File invalidated)
`63`	`00`	认证失败 (Authentication failed)
`63`	`CX`	认证失败，剩余重试次数为 X
`65`	`81`	内存故障 (Memory failure)
`67`	`00`	Lc 长度错误 (Wrong length)
`68`	`81`	不支持的逻辑通道
`68`	`82`	不支持的安全报文格式
`69`	`82`	安全状态不满足 / 未授权 (Security condition not satisfied)
`69`	`83`	认证方法被锁定 (Method blocked)
`69`	`85`	使用条件不满足 (Conditions not satisfied)
`6A`	`80`	数据域 (Data) 参数不正确
`6A`	`81`	不支持该功能 (Function not supported)
`6A`	`82`	未找到文件或应用 (File/Applet not found)
`6A`	`83`	未找到记录 (Record not found)
`6A`	`86`	P1/P2 参数不正确
`6C`	`XX`	Le 长度错误，实际应为 XX 字节
`6D`	`00`	不支持的 INS / 无效指令码
`6E`	`00`	不支持的 CLA / 无效指令类
`6F`	`00`	未知内部错误 (Unknown error)

读卡器相关

通常免驱动的智能卡读卡器为 USB CCID 设备，PC/SC 为事实 API 标准

接触式和未接触式需要不同的读卡器类型，也有同时支持两种接口的读卡器售卖。

安卓手机自带的 NFC 功能允许应用通过非接触式接口向智能卡发送和接收 APDU，可以安装 NXP TagInfo / NFC Tools 等读取卡片信息。也可以通过 HCE 功能模拟智能卡接收和响应外部读卡器发送的 APDU

Canokey 和 Yubikey 声明自己为 USB CCID 设备，以允许操作系统读取其中的 “智能卡” 实现相关功能

GlobalPlatform 相关

如果你需要了解如何管理 Javacard：进行如安装或删除 applet 等操作，或者对 Javacard 的生命周期、ISD 等感兴趣请直接阅读 CardSpecification_v2.3.1，这份文档内详细说明了卡片生命周期以及应用 (applet)、模块和安全域 (发卡方安全域 ISD、补充安全域 SSD) 和安全通道 (SCP02、SCP03) 、密钥等概念和对应的 APDU

GlobalPlatform (GP) 是一个跨行业的国际标准化组织，GlobalPlatform 制定的标准定义了如何在安全环境中安全地加载、安装、更新和删除应用程序，以及如何进行密钥管理和身份认证。不同生产厂家的 Javacard 卡通常均遵守特定版本的 GlobalPlatform 规范

如果你不了解你正在对卡进行的操作，至少以下操作是危险的，误操作或多次失败尝试可能会导致卡片变砖、锁定或不可用
更改卡片的生命周期状态 (单向不可逆+影响可用管理功能)
使用软件提供的默认密钥或猜测的密钥进行安全通道认证 (可能导致锁定)
替换、添加、删除密钥或添加新的安全通道 (错误的配置或组合可能导致失去管理权)
在不可靠的连接状态下写入卡片 (断连可能导致卡片变砖)

以下软件提供 GlobalPlatform 规范下的卡片管理功能

GlobalPlatformPro 非常经典简洁的 CLI 工具
PyApduTool 随 JCIDE 安装，虽然很旧但是图形界面很好用

Applet 相关

你可以自己编写或使用开源的 Applet 项目，编译得到 .cap 文件并将其加载到 Javacard 上

不同的Applet通常具有不同的AID，以在选择应用时加以区分

这部分信息可能过时，你可以参考以下链接：
javacard-curated-list 一份非常详细的 applet 列表
一位安了很多 Applet 的博主的文章

卡片载入应用后，通常需要特定的应用来配套使用，你可以参考 CanoKey 帮助文档和网络上使用 Yubikey、Canokey 的相关博客以及下列项目中的说明文档来了解相关应用的配置和使用方法

PIV: makinako/OpenFIPS201

2026年4月仍在更新
正在进行FIPS认证

GPG: github-af/SmartPGP

2025年9月仍在更新
OpenPGP 3.4
使用 requestObjectDeletion

FIDO2: BryanJacobs/FIDO2Applet

2026年4月仍在更新
完整覆盖 FIDO2 CTAP2.1 标准
需要 Javacard 3.0.5+
需要较多空间

GIDS: vletoux/GidsApplet

2023年停更
需要 Java Card 2.2.1+
初始化工具

BIP39: keycard-tech/status-keycard

不会用

NDEF: OpenJavaCard/openjavacard-ndef

还没用

MRTD (机读旅行证件): https://github.com/E3V3A/JMRTD/tree/master/passportapplet

除此之外还有HOTP/TOTP、EMV 和 SIM 等可通过 Applet 实现的功能

如何购买 Javacard

不构成购买建议

你可以在淘宝上搜索特定的 Javacard 产品型号来购买。对于 NXP 生产的 Javacard，其初始化文档为保密资料，通常需要卖家帮助完成卡片初始化操作 (卡片通信参数: ATR、历史字符等；卡片通信配置: APDU缓冲区大小、逻辑通道数、VHBR、SCP通道配置；卡片功能配置: RSA最大长度等) 或直接购买未初始化的卡片、使用卖家提供的出厂密钥自行初始化 (需要 NXP 私有 APDU 命令)

目前推荐 NXP 的 J3R 系列，比较新，而且可以买到：

NXP J3R110 / J3R180
NXP J3R150 / J3R200

其可用容量约为J3R后面的三位数字(单位: KB)，购买时需要注意 EMV / SecID 版本的区别 (是否支持 ECC)，以及接口是否为你需要的 (接触式 / 双界面 / 纯非接)，还有最重要的卡片密钥

如果你对卡片购买、初始化命令感兴趣，欢迎邮件交流讨论

WSL 2 分离式 home 挂载

2025-11-13T15:33:31.000Z

最近清理WSL2发行版的磁盘，发现大部分空间都被/home占用，所以决定用独立的vhdx磁盘作为/home挂载到发行版里

关于 WSL 2 架构

WSL 2 架构可以参考wsl.dev，微软于25年5月19开源了 WSL 2 大部分组件。

WSL 2 内核运行在一个使用[HCS API](Host Compute System Overview | Microsoft Learn)创建的隐藏虚拟机里，各发行版实际上是通过namespace隔离的容器。在内核启动后，WSL 进入其预制的WSLg System Distro中，加载各已安装发行版的磁盘，并将其挂载到各发行版的mount namespace中（这里写死了是ext4，所以应该是没法去改根目录文件系统的）。

PS：所有发行版共用同一个network namespace

可以通过下面的命令进入system distro：

1	wsl --system

还可以以root权限进入：

1	wsl --debug-shell

关于 VHD/VHDX

还得是 VHDX

VHD/VHDX有三个很有用的特性：

动态VHD: 支持空间调整
稀疏VHD: 支持自动回收空间
父子VHD: 类似overlayfs

常用的管理命令：

# 设置动态VHD大小
Resize-VHD

# 压缩动态VHDX空间
Optimize-VHD

关于挂载

WSL2 所有发行版共享同一个内核，通过wsl --mount --vhd --bare 挂载的磁盘同时对所有发行版可见
Linux 从 2.4 开始就支持把一个文件系统挂在多个挂载点上，或者在一个挂载点上挂多个文件系统
mount --bind可以挂载一个目录到另一个目录（与挂载点不同，可以是非空目录，且同样可以被挂载多次）

关于稀疏 VHD (SparseVHD)

稀疏VHD实际上是NTFS的稀疏文件，它需要通过特殊的ioctl设置，通过特殊API写入全0数据时可以回收磁盘空间。但是被WSL加了警告

操作过程

分离`/home`到 VHDX

这里笔者选择了 btrfs，创建了一个空白vhdx，作为/dev/sdxx临时挂载在/mnt/home：

# 创建子卷结构
sudo mount /dev/sdxx /mnt/home
sudo btrfs subvolume create /mnt/home/@home
sudo btrfs subvolume create /mnt/home/@.snapshots
sudo umount /mnt/home

# 复制已有的/home
sudo mount -t btrfs -o subvol=/@home /dev/sdxx /mnt/home
sudo rsync -aXS /home/ /mnt/home
sudo umount /mnt/home

# 挂载到/home
sudo mv /home /home_old
sudo mount --mkdir -t btrfs -o subvol=/@home /dev/sdxx /home

自动挂载配置

在上面配置完后其实就已经可用了，但是WSL再次冷启动时之前挂载的VHDX并不会自动挂载，挂载上了磁盘也需要手动挂载/home，所以还需要进行自动挂载的配置。这里利用了WSL 2内置的systemd进行自动挂载：

在发行版/etc/wsl.conf中进行以下配置：

1 2	[automount] mountFsTab=false # 因为在加载发行版时还没有挂载vhdx，所以需要推迟到systemd引导过程中

创建/usr/lib/systemd/system/wsl-automount.service：

其中VHDX路径为"C:\\Users\\UserName\\AppData\\Local\\wsl-home\\home.vhdx"

[Unit]
Description=WSL2 Auto Mount
After=systemd-binfmt.service systemd-udevd.service
Requires=systemd-binfmt.service
Before=home.mount
DefaultDependencies=no

[Service]
Type=oneshot
ExecStart=/bin/sh -c '/mnt/c/Windows/System32/wsl.exe --mount --vhd --bare "C:\\Users\\UserName\\AppData\\Local\\wsl-home\\home.vhdx" || true'
StandardOutput=null
StandardError=null
RemainAfterExit=yes
TimeoutStopSec=5

[Install]
WantedBy=basic.target

创建/usr/lib/systemd/system/home.mount

使用lsblk -f查看磁盘UUID

[Unit]
Description=Mount VHD Filesystem
After=wsl-automount.service
Requires=wsl-automount.service
Before=shutdown.target
Conflicts=shutdown.target
DefaultDependencies=no

[Mount]
What=UUID=a936001a-3044-4285-8a4a-8be821931f08
Where=/home
Type=btrfs
Options=compress=zstd,noatime,subvol=/@home

[Install]
WantedBy=basic.target

创建'/usr/lib/systemd/system/\x2esnapshots.mount'：

快照目录，记得创建/.snapshots

[Unit]
Description=Mount VHD Filesystem @.snapshots
After=wsl-automount.service
Requires=wsl-automount.service
Before=shutdown.target
Conflicts=shutdown.target
DefaultDependencies=no

[Mount]
What=UUID=a936001a-3044-4285-8a4a-8be821931f08
Where=/.snapshots
Type=btrfs
Options=compress=zstd,noatime,subvol=/@.snapshots

[Install]
WantedBy=basic.target

可以wsl --shutdown后等待8s，重启wsl检查效果

OpenWRT 配置教程

2025-07-14T18:57:00.000Z

写在前面

笔者最近为一台设备刷写了最新的 OpenWRT 24.10.1（虽然没过几天 24.10.2 版本已出 Orz）。为了让这台路由器符合笔者的需求，笔者研究了负载均衡、无线 mesh 组网和 IPv6 等配置。然而现有的简中互联网并没有详细的配置教程或说明文档，很多配置只知其然不知其所以然，甚至以讹传讹，让人迷惑甚至误解。笔者在现有资料的基础上对部分国内网络环境下的常见需求进行了探索和分析，给出了设置项位置和相关设置说明，力求简明准确。虽然笔者写到最后仍是一知半解，但还是记录下来，希望能给读者和未来的自己节省一些时间。

配置细节

自定义构建

通过在线构建可以保证安装的软件包是最新的，避免在 overlayfs 上重复安装浪费存储空间

启用 dnsmasq-full
启用 kmod-tcp-bbr
启用 wpad-mbedtls 为 802.11s 做准备，这个就是完整版的 hostapd / wpad，按加密套件不同分为openssl / wolfssl / bedtls 三个版本
安装 luci-i18n-upnp-zh-cn 添加 upnp 管理
安装 luci-i18n-wol-zh-cn 添加 WOL 支持
安装 block-mount 为 luci 添加系统 / 挂载点选项

IPv6 网络配置

允许扩展前缀分配: 网络 / 接口 / 接口选项卡 wan6 端口 编辑 / 常规设置 打开 扩展前缀 （端口协议应为DHCPv6 客户端）
IPv6 中继相关配置 网络 / 接口 / 接口选项卡 选择端口 编辑 / DHCP 服务器
IPv6 前缀相关配置: 网络 / 接口 / 接口选项卡 选择端口 编辑 / 高级设置
开启MSS钳制: 网络 / 防火墙 / 常规设置选项卡 / 区域 选择防火墙区域（WAN区域） 编辑 / 常规设置 打开 MSS 钳制

IPv6 地址分配

IPv6地址由网络前缀+接口标识组成，有以下几种类型：

类型	名称	前缀标识
单播地址	全球单播地址 GUA	2000::/3
	唯一本地地址 ULA	fc00::/7
	站点本地地址 SLA	fec0::/10
	链路本地地址 LLA	fe80::/10
特殊地址	环回地址	::1/128
特殊地址	未指定地址	::/128
组播地址		ff00::/8

IPv6 地址分配有两种方式：

有状态：由 DHCPv6 服务器分配
无状态：由 SLAAC 过程设备自行分配

两种方式可同时存在，注意安卓设备只支持 SLAAC，SLAAC 过程使用 NDP（邻居发现协议）的 RS / RA 消息；NDP 还有类似 ARP 的功能，使用 NS / NA 消息

实际分配时，路由器通过 RA（路由器通告）消息应答设备的 RS （路由器请求）消息，下发配置和 SLAAC 前缀。RA 消息是定期发送的，但主机发送 RS 消息后，可立即得到响应：

A标志（Autonomous Address Configuration，每个前缀独立配置）
- A=1：客户端可在该前缀范围内进行 SLAAC，获取 IPv6 地址和 DNS 等参数
- A=0：客户端不应当在该前缀范围内进行 SLAAC
M标志（Managed Address Configuration）：
- M=1：客户端可使用 DHCPv6 获取 IPv6 地址和 DNS 等参数
- M=0：判断O标志
O标志（Other Configuration，仅当M=0时有效）：
- O=1：当有A=1（全部 A=0 没有 IP 地址）时，客户端可通过 DHCPv6 获取 DNS 等参数
- O=0：不通过 DHCPv6 获取 DNS 等参数

要注意单个 IPv6 地址与子网的区别，获取到一个 IPv6 地址≠获取了一条路由：

假设 2001:1:2:3:a:b:c:d/64 是一个 IPv6 地址，IPv6 地址本身不包含前缀信息，但在网络配置中，前缀长度（如 /64）类似子网掩码，用于决定该地址所属的子网范围。网络接口使用前缀（2001:1:2:3）判断一个 IPv6 地址是否与自己同属一个子网（即在本地链路上）。网络接口在没有明确路由的情况下，只能在本地链路上通信。在内核根据路由表判断某个报文应从接口 B 发出时，首先要通过 NDP 在本地链路上确定目的 IPv6 地址对应的 MAC 地址，然后在链路层向该 MAC 地址转发 IPv6 报文

路由转发操作在同一个路由器的不同接口之间进行，由 Linux 内核遵循路由表进行转发。例如路由器有两个接口A、B，IPv6 地址分别为 2001:1:a::1/48 和 2001:1:b::1/48，其网络前缀不同，分属两个不同的子网，且假设具有一条路由（将2001:1:b:6789::/64转发到2001:1:b:6789::1）。

当接口 A 收到目的 IPv6 地址为 2001:1:b:abcd::1 的 IPv6 报文时，Linux 内核判断应由接口 B 发出，在接口 B 的本地链路上执行 NDP 查找 2001:1:b:abcd::1 对应的 MAC 地址，成功后在其本地链路上向 2001:1:b:abcd::1 发送 IPv6 报文。
而当接口A 收到目的 IPv6 地址为 2001:1:b:6789::1234 的 IPv6 报文时，Linux 内核根据路由表向 2001:1:b:6789::1 转发该报文，2001:1:b:6789::1 位于接口 B，因此在接口 B 的本地链路上执行 NDP 查找 2001:1:b:6789::1 对应的 MAC 地址，成功后在其本地链路上向 2001:1:b:6789::1 发送 IPv6 报文

在该例子下的一个 IPv6 地址分配过程示例（IPv6 地址中的/64代表其前缀长度为 /64）：

新设备 C 生成链路本地地址
新设备 C 连接到路由器接口 B，发送 RS 消息，获取 RA 通告为 M=1，O=1，一条可用前缀（2001:1:b:0，A=1，前缀长度64），一个可用 DNS 2001:1:b::1，源 MAC 地址 aa:bb:cc:dd:ee:ff，MTU=1500
设备通过 SLAAC 为自己分配 IPv6 地址 2001:1:b:6666:8888::abcd/64 和 2001:1:b:6666:8888::cdef/64，网关 IPv6 地址为 fe80:xxxx（链路本地地址）
设备通过 DHCPv6 （IA_NA）获得地址 2001:1:b:6666::abcd/128
设备通过 DHCPv6-PD（IA_PD）申请到子网前缀 2001:1:b:6789::/64，路由器添加新的路由条目（将2001:1:b:6789::/64 转发到 2001:1:b:6666:::abcd）

DHCPv6-PD

DHCPv6 前缀代理（PD，Prefix Delegation）允许下一级路由器通过 DHCPv6 协议获得可自行分配的子网前缀，以下内容参考IPV6 DHCPv6-PD 前缀子网简单拆解

所有全球单播地址（公网 IPv6 地址）中网络前缀最长只能是64bit，不能再划分，因此路由器 wan 口至少会占一个 /64 子网
SLAAC只能使用64位网络前缀

SLAAC、有状态 DHCPv6 、无状态 DHCPv6 和 DHCPv6-PD 可同时存在，但是只有 DHCPv6-PD 可以申请到新的子网路由。在获取到 PD 前缀后，路由器可以将其下发给 LAN 口使用，这样局域网中的设备也可以有全球单播地址。

DHCPv6-PD 示例：

上级 LAN 口

- fdba:c244:5433::1/60

本级 WAN 口

- fdba:c244:5433:4::/62（DHCPv6-PD）
- fdba:c244:5433:0:::d26/128（DHCPv6）
- fdba:c244:5433:0:2276:93ff:fe57:647d/64（SLAAC）

本级 LAN 口

- fdba:c244:5433:4::1/62

下级 WAN 口

- fdba:c244:5433:6::/63（DHCPv6-PD）
- fdba:c244:5433:4::3cf/128（DHCPv6）
- fdba:c244:5433:4:cc4f:c2ff:fe67:7fa8/64（SLAAC）

子网划分情况

fdba:c244:5433::1/60（上级 LAN 口子网）
  fdba:c244:5433:0::/62
    fdba:c244:5433:0::/64（本级 WAN 口子网）
    fdba:c244:5433:1::/64
    fdba:c244:5433:2::/64
    fdba:c244:5433:3::/64
  fdba:c244:5433:4::/62（本级获取的 PD 前缀 && 本级 LAN 口子网）
   fdba:c244:5433:4::/63
    fdba:c244:5433:4::/64（下级 WAN 口子网）
    fdba:c244:5433:5::/64
   fdba:c244:5433:6::/63（下级获取的 PD 前缀 && 下级 LAN 口子网）
  fdba:c244:5433:8::/62
  fdba:c244:5433:c::/62

RFC 7278

但很糟糕的是，在笔者的校园网环境下 SLAAC 和 DHCPv6-PD 获得的 IPv6 地址前缀相同（均为/64）

在进行前缀委派时，上游路由器（例如通过PD拿到2001:1:a::1/48）可以通过剔除与下游路由器通信的/64子网，把剩下的部分分派给各下游路由器，但是在地址前缀长度到64位时，将没有可供下游分配的前缀。如果强行为路由器的LAN使用该前缀，将有两条相同的路由分别指向LAN和WAN。打开扩展前缀选项将会把WAN口转为/128路由，并将剩余的/64地址池交给下游分配。

来自RFC 6603：DHCPv6 前缀委派（DHCPv6-PD）{RFC 3633} 存在第 12.1 节所述的明确限制：委派给请求路由器（本级）的前缀不能被委派路由器（上一级）使用。该限制意味着委派路由器将拥有两条（不可聚合的）指向客户的路由：一条用于请求路由器与委派路由器间的链路，另一条用于请求路由器背后的客户站点。

来自RFC 3633：the requesting router MUST NOT assign any delegated prefixes or subnets from the delegated prefix(es) to the link through which it received the DHCP message from the delegating router 请求路由器不得将任何从委派前缀（或其子网）中分配的前缀，用于分配给它通过同一链路（即从委派路由器接收 DHCP 消息的那条链路）的接口

来自RFC 6603：The OPTION_PD_EXCLUDE option allows prefix delegation where a requesting router is delegated a prefix (e.g., /56) and the delegating router uses one prefix (e.g., /64) on the link through which it exchanges DHCPv6 messages with the requesting router with a prefix out of the same delegated prefix set. OPTION_PD_EXCLUDE 选项允许在前缀委派中进行如下情况：请求路由器被委派一个前缀（例如 /56），而委派路由器在与其交换 DHCPv6 消息的链路上（即 WAN 链路）使用同一委派前缀集合中的某个前缀（例如 /64）

来自RFC 6603：The delegating router includes the prefix in the OPTION_PD_EXCLUDE option that is excluded from the delegated prefix set. The requesting router MUST NOT assign the excluded prefix to any of its downstream interfaces. 委托路由器在 OPTION_PD_EXCLUDE 选项中包含需要排除的前缀，该前缀将从所分配的前缀集合中被剔除。请求路由器不得将所排除的前缀分配给任何下游接口

当然这个问题直接打开扩展前缀选项就可以解决（RFC 7278）

实现局域网获取全球单播地址

对于有 PD 的情况，路由器会自动将可用的 PD 前缀分配给 lan 使用

对于没有 PD 的情况，要实现局域网获取全球单播地址，就需要将局域网设备暴露到上层网络中

启用 RA 中继，为局域网内设备转发上层网络 RA 消息
启用 DHCPv6 中继，为局域网内设备转发上层网络 DHCPv6 消息
启用 NDP 中继，向上层网络转发局域网设备 IPv6地址与 mac 对应关系

这种方法在上层网络看来，会有多个 IPv6 地址（/64 前缀）对应到同一个 MAC 地址（路由器 wan 口），因此在某些网络下不可行。在一个 MAC 地址只能对应一个 IPv6 地址（/64 前缀）的情况下，只能通过 NAT6 为局域网分配地址

更新：之前提到限制MAC的情况，这里看到另一种上游错误配置导致丢包的情况 https://blog.icpz.dev/articles/notes/odhcpd-relay-mode-discuss/#%E6%A1%88%E4%BE%8B%E8%AF%B4%E6%98%8E

更新：还有一种情况适合 NAT66，那就是运营商的 PD 前缀有效期很短，失效后会导致子网设备 IPv6 地址失效

更新：NAT66 在 24.10.2 上的配置已经十分简单：
https://openwrt.org/docs/guide-user/network/ipv6/ipv6_extras
https://openwrt.org/docs/guide-user/network/ipv6/ipv6.nat6

DNS 不过滤 IPv6 AAAA 记录
在上游防火墙区域启用 IPv6 伪装功能+MSS钳制
在上游接口禁用 IPv6 源地址过滤 uci set network.wan6.sourcefilter=”0”
注意性能问题 https://github.com/openwrt/openwrt/issues/15623 该问题在 24.10.0-rc1 中修复
ULA 地址优先级比 IPv4 低，要默认使用 IPv6需要更改 ULA 地址 https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml

桥接配置

操作要考虑清楚，否则可能连不上路由器

修改路由器局域网 IP 网段（桥接不需要）: 网络 / 接口 / 接口选项卡 lan 端口 编辑 / 常规设置 IPv4 地址改为需要的路由器自身IP，配合下面的子网掩码生效
在局域网上禁用 DHCP 服务器: 网络 / 接口 / 接口选项卡 lan 端口 编辑 / DHCP 服务器 / 常规设置 打开 忽略此端口
将路由器自身 IP 改为 DHCP 获取: 网络 / 接口 / 接口选项卡 lan 端口 编辑 / 常规设置 协议选择 DHCP 客户端
不应当简单关闭 wan 口的 IP 动态伪装（即 NAT 功能），会造成往返非对称路由: 网络 / 防火墙 / 常规设置选项卡 / 区域 wan区域 编辑 / 常规设置 打开 IP 动态伪装

802.11s 配置

这是关于真正的 mesh 的配置，定义参考官网教程

WiFi可用频段受国家代码限制（不符合系统日志里会报错），可配置为CN: 网络 / 无线 选择网络 编辑 / 设备配置 / 常规设置 国家代码选择 CN
不同 mesh 节点同页面位置模式信道通道宽度应一致
启用 802.11s 模式: 网络 / 无线 选择网络 编辑 / 接口配置 / 常规设置 选择 802.11s
加入 lan 网络: 同页面位置网络选择 lan（会自动被桥接，非桥接网络如 wan，原设备可能会被替换掉）

802.11s 为二层网络，如果配置好以后没有关掉其他节点 lan 网络的 DHCP 服务器，新加入其他节点的设备 DHCP 请求会被抢答

除此之外还可以通过 WDS 来实现无线桥接，一方设置为接入点 AP（WDS），另一方设置为客户端（WDS）即可实现二层桥接

当然 ad-hoc 也是一种组网方式，但是笔者不懂

DSA 架构下的 VLAN 配置

位置: 网络 / 接口 / 设备选项卡 选择交换机设备（br-lan）配置 / 网桥 VLAN 过滤

DSA 架构可以让 Linux 在 CPU 侧区分流量来自具体哪个交换机端口，因此在 DSA 架构下 CPU 侧与交换机连接的物理端口已经按交换机端口拆分虚拟端口

# refer: https://docs.kernel.org/networking/dsa/dsa.html

        +----------------------------------+
        |        +------------------------+|
        |        |         br-lan         ||
        |        +--|^-------|^-------|^--+|
        |+-----+ +--v|--+ +--v|--+ +--v|--+|
        || wan | | lan1 | | lan2 | | lan3 ||
        |+-----+-+------+-+------+-+------+|
        |             DSA驱动程序           | 软件
        +----------------------------------+
                         |^
        添加特定交换机标识 || 识别特定交换机标识
                         v|
        +-------------+------+-------------+
        |             | eth0 |             |
        |             +------+             |
        |         网络接口驱动程序           | 软件
--------+----------------------------------+------------
        |          CPU侧网络接口            | 硬件
        +----------------------------------+
                         |^
        识别特定交换机标识 || 添加特定交换机标识
                         v|
        +-------------+------+-------------+
        |             | eth0 |             |
        |             +------+             |
        |               交换机              |
        |+-----+ +------+ +------+ +------+|
        || wan | | lan1 <=> lan2 <=> lan3 || # br-lan 控制桥接 lan1 lan2 lan3
        ++-----+-+------+-+------+-+------++

在 DSA 架构下配置 VLAN 时，首先要理清以下几点：

下述物理端口 / 交换机上的xxx端口指物理交换机上的真实网络接口（在上图中硬件部分）
下述虚拟接口 / Linux 下的xxx接口指在 Linux 下可见（或 Luci 中展示）的交换机端口（在上图中软件部分）

对于虚拟接口

Linux 下的 eth0 是真实的 CPU 侧与交换机通信的接口，该接口由 DSA 驱动收发带有特定交换机标识（用于区分来源，不是 VLAN tag）的二层数据，不应该直接访问。
所有 Linux 下可见的交换机接口（wan、lan1..3）都不是交换机上的真实端口，而是对交换机（按来源端口区分后）发往 CPU 数据抽象出的虚拟接口，区分工作由 DSA 驱动通过解析特定交换机标识完成。
Linux 下没有交换机上 eth0 物理端口对应的虚拟接口

对于转发策略

所有 Linux 下可见的虚拟接口（br-lan，wan，lan1..3）都隐式的包含主机端（就是流量可被转发至 CPU 侧）。简单理解的话，br-lan + wan就相当于上文提到的交换机上 eth0 物理端口对应的虚拟接口，毕竟概念上这些虚拟接口就是对应的物理接口转发到 CPU 侧的抽象（可以理解为相当于eth0-from-wan，eth0-from-br-lan）
所有没有被桥接的 Linux 下可见的虚拟接口对应的物理端口均只转发至 Linux 下的接口（即对应的虚拟接口）。如果同一台交换机上的物理端口对应的虚拟接口没有通过 Linux 下的桥接设备连接，即使它们在同一台交换机上，也不会相互转发
Linux 下的桥接设备唯一的控制哪些Linux 下的接口对应的物理端口在二层互通。如果桥接的物理端口在同一台交换机上，会自动开启硬件offload，流量不经过 Linux 中转。而没有在同一个物理交换机上的端口被桥接将通过 Linux 中转进行交换

理清上述几条以后，就可以解释实际的接口配置：

笔者的路由器工作在 DSA 架构下，在 br-lan 中没有 eth0：没有 eth0 是因为 Linux 下的 eth0 是带有特定交换机标识（用于区分来源，不是 VLAN tag）的原始网络接口，在套了 DSA 驱动之后变成了 Linux 下的 wan、lan1..3 接口，只需要关注这些虚拟接口即可。
笔者的路由器默认没有启用 VLAN：在 Linux 下 br-lan 仅桥接了 lan1..4，没有将它们与 wan 桥接，两者已经隔离开了

在了解 DSA 架构下的 Linux 下的虚拟接口的特性后，就可以关注 VLAN 相关的特性：

所有 Linux 下可见的接口都丢弃带有 VLAN tag 的报文，要处理从某端口发来的带有 VLAN tag 的报文，要套一层 802.1q 设备，这个新设备将收到的带有指定 VLAN tag 的报文转为普通报文，并将发出报文加上指定 VLAN tag
交换机内部所有报文都带 VLAN tag

然后就可以了解 OpenWRT 的 VLAN 配置项的含义：

开启 VLAN 过滤时，硬件必须被编程为拒绝 VLAN ID 未在已编程允许的 VLAN ID 映射/规则范围内的 802.1Q 帧。若交换机端口未配置 PVID（默认 VLAN），则必须同时拒绝未标记帧。关闭过滤时，交换机必须接受任何 VLAN ID 的 802.1Q 帧且允许未标记帧。

开启 VLAN 过滤：在桥接设备上启用 VLAN 功能，让交换机按配置的 VLAN 设置进行工作
已标记: 带对应的 VLAN ID 的流量可原样流入流出该端口。流入流量没有 VLAN 的将打上该端口对应的 PVID
未标记: 带对应的 VLAN ID 的流量可流入流出该端口。流出该端口的流量（注意是对应 VLAN ID）将被剥离 VLAN ID。流入流量没有 VLAN 的将打上该端口对应的 PVID
主 VLAN：即该VLAN ID 是该端口的 PVID，一个端口最多设一个 PVID。
禁用: 该 VLAN 下禁止流入流出
local：是否为该 VLAN ID 创建对应的 802.1q 设备。没有设备的话不会被转发到 CPU 侧

还有一点需要注意的边际情况，你可以点击连接查看详细的例子：

一个端口有两个或以上未标记时才需要设置 PVID，没有设置的话默认为 VID 较小的
一个端口没有未标记时，流入的无 VLAN 流量将被丢弃。除非该端口设置了 PVID
不同 VLAN 如果设置了 local，路由器将根据防火墙设置在三层上不同防火墙区域间转发

SG105 Pro MTU VLAN / 端口 VLAN / 802.11q VLAN 是三种不同的 VLAN 模式

还有链路聚合相关 kmod-bonding、proto-bonding，笔者不太了解

MultiWAN 配置

安装 luci-i18n-mwan3-zh-cn iptables-nft ip6tables-nft

后面两个用于兼容高版本 OpenWRT 使用的nftable 注意默认配置会使网络不可用

无线配置

高版本 OpenWRT 下可以为同一个 SSID 设置多个密码，并导向不同 VLAN

参考 https://forum.openwrt.org/t/individual-per-passphrase-per-mac-wifi-vlans-using-wpa-psk-file-no-radius-required/161696 有非常详细的讨论和介绍

为 Hexo Next 主题集成 Cusdis 评论组件

2025-06-26T18:57:00.000Z

因为本站为纯静态站点，为了让博客能评论，找了一个可以托管的评论服务 Cusdis

Next 主题默认不提供 Cusdis 的集成，所以简单搓了一个

配置修改

新建评论模板

添加了中文语言（没写自适应倒是）
参考 issue 修正了容器高度

在 source/_data/post-body-end.swig 中：

{% if theme.cusdis.enable %}
    <hr />
    <h3>评论h3>
    <div id="cusdis_thread"
      data-host="{{ theme.cusdis.host }}"
      data-app-id="{{ theme.cusdis.app_id }}"
      data-page-id="{{ page.path }}"
      data-page-url="{{ page.permalink }}"
      data-page-title="{{ page.title }}"
      style="display: flex; height: 24em;"
    >div>
    <script async defer src="https://cusdis.com/js/widget/lang/zh-cn.js">script>
    <script async defer src="https://cusdis.com/js/cusdis.es.js">script>
{% endif %}

配置 Next 主题

cusdis 这部分对应评论模板中的内容

在 _config.next.yml 中：

custom_file_path:
  postBodyEnd: source/_data/post-body-end.swig
cusdis:
  enable: true
  host: # 你的 cusdis 实例地址
  app_id: # 你的 app_id

某光猫提权过程

2024-07-06T08:00:00.000Z

今天研究家里的光猫（KD-YUN-811G），发现默认开了 telnet，用户名 telnetadmin, 密码 telnetadmin。结果登陆上去发现是个假 shell，里面什么命令都没有，也没有 sh 命令。

折腾一顿发现 http 界面可以开 ftp 服务器，登陆进 ftp 可以访问到光猫文件系统。

下载下来 /etc/telnetd, 拖进 ida 反编译找到登陆逻辑：

// start -> _ftext:
    /* read arguments */
    /* cmsMsg_initWithFlags */
    /* cmsMdm_initWithAcc */
    /* initLoggingFromConfig */
    /* make_new_session */ {
        cmsCli_printWelcomeBanner();
        if (!cmsCli_Telnetauthenticate(NetworkAccessMode_igd, 600)) {
            cmsCli_run(msgHandle, 600);
        }
    }

这些函数都在 libcms_cli.so 中，这里重点关注 cmsCli_run: 参考网上的源码可知处理输入的逻辑在 processInput 中:

// processInput
    if (input[0]) {
        if ( cli_processCliCmd(input) != 1 && cli_processHiddenCmd(input) != 1 )
            log_log(3, "processInput", 393, "unrecognized command %s", v3);
        /* XXXXXX */
    }

再看看 cli_processHiddenCmd:

// cli_processHiddenCmd
    if ( strncasecmp(input, "muma@door", strlen(input)) ) {
      prctl_runCommandInShellBlocking(input);
    }

输入 muma@door，发现其实是 busybox，这样就可以正常使用命令了:

ADOC 实现分析

2024-01-16T08:23:00.000Z

本文基于仓库 FEAT_7.11
base(FEAT_7.11): 5fbcc8c54d4a8704405b568d53faf23cd0722eeb
base(rocksdb): 5fbcc8c54d4a8704405b568d53faf23cd0722eeb

tools/db_bench_tool.cc

// 相关选项
// @db_bench_tool.cc:783
DEFINE_bool(DOTA_enabled, false, "Whether trigger the DOTA framework");
DEFINE_bool(FEA_enable, false, "Trigger FEAT tuner's FEA component");
DEFINE_bool(TEA_enable, false, "Trigger FEAT tuner's TEA component");
DEFINE_int32(SILK_bandwidth_limitation, 200, "MBPS of disk limitation");
DEFINE_bool(SILK_triggered, false, "Whether the SILK tuner is triggered");
DEFINE_double(idle_rate, 1.25,
              "TEA will decide this as the idle rate of the threads");
DEFINE_double(FEA_gap_threshold, 1.5,
              "The negative feedback loop's threshold");
DEFINE_double(TEA_slow_flush, 0.5, "The negative feedback loop's threshold");
DEFINE_double(DOTA_tuning_gap, 1.0, "Tuning gap of the DOTA agent, in secs ");
DEFINE_int64(random_fill_average, 150,
             "average inputs rate of background write operations");
DEFINE_bool(detailed_running_stats, false,
            "Whether record more detailed information in report agent");

// 设置相关 flag 后, 初始化局部变量 reporter_agent 为自定义的实现
// rocksdb::Benchmark::RunBenchmark
//     @db_bench_tool.cc:3854
std::unique_ptr reporter_agent;
if (FLAGS_report_interval_seconds > 0) {
    if ( FLAGS_DOTA_enabled || FLAGS_TEA_enable ||
        FLAGS_FEA_enable) {
    // need to use another Report Agent
    if (FLAGS_DOTA_tuning_gap == 0) {
        reporter_agent.reset(new ReporterAgentWithTuning(
            reinterpret_cast(db_.db), FLAGS_env, FLAGS_report_file,
            FLAGS_report_interval_seconds, FLAGS_report_interval_seconds));
    } else {
        reporter_agent.reset(new ReporterAgentWithTuning(
            reinterpret_cast(db_.db), FLAGS_env, FLAGS_report_file,
            FLAGS_report_interval_seconds, FLAGS_DOTA_tuning_gap));
    }
    auto tuner_agent =
        reinterpret_cast(reporter_agent.get());
    tuner_agent->UseFEATTuner(FLAGS_TEA_enable, FLAGS_FEA_enable);
    tuner_agent->GetTuner()->set_idle_ratio(FLAGS_idle_rate);
    tuner_agent->GetTuner()->set_gap_threshold(FLAGS_FEA_gap_threshold);
    tuner_agent->GetTuner()->set_slow_flush_threshold(FLAGS_TEA_slow_flush);
    } else if (FLAGS_detailed_running_stats) {
    reporter_agent.reset(new ReporterWithMoreDetails(
        reinterpret_cast(db_.db), FLAGS_env, FLAGS_report_file,
        FLAGS_report_interval_seconds));
    } else if (FLAGS_SILK_triggered) {
    reporter_agent.reset(new ReporterAgentWithSILK(
        reinterpret_cast(db_.db), FLAGS_env, FLAGS_report_file,
        FLAGS_report_interval_seconds, FLAGS_value_size,
        FLAGS_SILK_bandwidth_limitation));
    } else { /* 注: 这里是原始的 ReporterAgent */
    reporter_agent.reset(new ReporterAgent(FLAGS_env, FLAGS_report_file,
                                            FLAGS_report_interval_seconds));
    }
}

utilities/DOTA/report_agent.cc

启动路径

作者将 ReporterAgent 的定义从 tools/db_bench_tool.cc 移动到了 include/rocksdb/utilities/report_agent.h 中

该实现在 ReporterAgent 构造函数中, 启动了一个新的线程, 主要逻辑为周期性的执行 DetectAndTuning 函数

// rocksdb::ReporterAgent::ReporterAgent
//     @report_agent.h:67
reporting_thread_ = port::Thread([&]() { SleepAndReport(); });

// @report_agent.h:92
void SleepAndReport() {
    ...
    while (true) {
        // sleep report_interval_secs_
        ...
        DetectAndTuning(secs_elapsed);
        ...
    }
}

其中 ReporterAgent::DetectAndTuning 为虚函数, 该类本身将其实现为空函数; 该函数在 ReporterAgent 的三个子类中被 override, 主要逻辑在 ReporterAgentWithTuning::DetectAndTuning 中

// @report_agent.cc:40
void ReporterAgentWithTuning::DetectAndTuning(int secs_elapsed) {
  if (secs_elapsed % tuning_gap_secs_ == 0) {
    DetectChangesPoints(secs_elapsed);
    //    this->running_db_->immutable_db_options().job_stats->clear();
    last_metrics_collect_secs = secs_elapsed;
  }
  if (tuning_points.empty() ||
      tuning_points.front().change_timing < secs_elapsed) {
    return;
  } else {
    PopChangePoints(secs_elapsed);
  }
}

// @report_agent.cc:182
void ReporterWithMoreDetails::DetectAndTuning(int secs_elapsed) {
  //  report_file_->Append(",");
  //  ReportLine(secs_elapsed, total_ops_done_);
  secs_elapsed++;
}

// 没有 ReporterAgentWithSILK::DetectAndTuning

作者在仓库 README 中提到:
The SILK implementation in this repo is a placeholder, since we failed to reproduce the read performance as mentioned in its paper.

调节过程

在 DetectChangesPoints 和 PopChangePoints 中, 该实现通过 tuner->DetectTuningOperations 函数动态获得新的 rocksdb 的配置选项 change_points; 然后通过 ApplyChangePointsInstantly 更新数据库和列族设置选项

// @report_agent.cc:31
void ReporterAgentWithTuning::DetectChangesPoints(int sec_elapsed) {
  std::vector change_points;
  if (applying_changes) {
    return;
  }
  tuner->DetectTuningOperations(sec_elapsed, &change_points);
  ApplyChangePointsInstantly(&change_points);
}

// @report_agent.cc:169
void ReporterAgentWithTuning::PopChangePoints(int secs_elapsed) {
  std::vector valid_point;
  for (auto it = tuning_points.begin(); it != tuning_points.end(); it++) {
    if (it->change_timing <= secs_elapsed) {
      if (running_db_ != nullptr) {
        valid_point.push_back(*it);
      }
      tuning_points.erase(it--);
    }
  }
  ApplyChangePointsInstantly(&valid_point);
}

utilities/DOTA/DOTA_tuner.cc

本文件实现了两个 Tuner: FEAT_Tuner 和 DOTA_Tuner, 需要注意 FEAT_Tuner 是 DOTA_Tuner 的子类, override 了 DetectTuningOperations

新的设置列表生成 (`std::vector`)

新的设置参数计算操作主要在 DetectTuningOperations 中, DOTA_Tuner 在打分和获取统计信息后调用 AdjustmentTuning 获得新的设置列表

// @DOTA_tuner.cc:12
void DOTA_Tuner::DetectTuningOperations(
    int secs_elapsed, std::vector *change_list_ptr) {
  current_sec = secs_elapsed;
  //  UpdateSystemStats();
  SystemScores current_score = ScoreTheSystem();
  UpdateMaxScore(current_score);
  scores.push_back(current_score);
  gradients.push_back(current_score - scores.front());

  auto thread_stat = LocateThreadStates(current_score);
  auto batch_stat = LocateBatchStates(current_score);

  AdjustmentTuning(change_list_ptr, current_score, thread_stat, batch_stat);
  // decide the operation based on the best behavior and last behavior
  // update the histories
  last_thread_states = thread_stat;
  last_batch_stat = batch_stat;
  tuning_rounds++;
}

// @DOTA_tuner.cc:195
void DOTA_Tuner::AdjustmentTuning(std::vector *change_list,
                                  SystemScores &score,
                                  ThreadStallLevels thread_levels,
                                  BatchSizeStallLevels batch_levels) {
  // tune for thread number
  /* 注: 这里得到状态 */
  auto tuning_op = VoteForOP(score, thread_levels, batch_levels);
  // tune for memtable
  /* 注: 这里根据状态(tuning_op)更新数据库设置列表(change_list) */
  FillUpChangeList(change_list, tuning_op);
}

FEAT_Tuner 计算状态 (TuningOP) 的方式与 DOTA_Tuner 不同:

void FEAT_Tuner::DetectTuningOperations(int /*secs_elapsed*/,
                                        std::vector *change_list) {
  //   first, we tune only when the flushing speed is slower than before
  auto current_score = this->ScoreTheSystem();
  if (current_score.flush_speed_avg == 0) return ;
  scores.push_back(current_score);
  if (scores.size() == 1) {
    return;
  }
  this->UpdateMaxScore(current_score);
  if (scores.size() >= (size_t)this->score_array_len) {
    // remove the first record
    scores.pop_front();
  }
  CalculateAvgScore();

  current_score_ = current_score;

  if (current_score_.flush_speed_avg >0 ){
   TuningOP result{kKeep, kKeep};
   if (TEA_enable) {
      result = TuneByTEA();
   }
    if (FEA_enable) {
      TuningOP fea_result = TuneByFEA();
      result.BatchOp = fea_result.BatchOp;
    }
    FillUpChangeList(change_list, result);

  }
}

设置参数细节

FillUpChangeList 会根据计算好的状态更新参数, 然后通过 SetBatchSize SetThreadNum 追加到 std::vector *change_list 中

// @DOTA_tuner.cc:251
inline void DOTA_Tuner::SetBatchSize(std::vector *change_list,
                                     uint64_t target_value) {
  ChangePoint memtable_size_cp;
  ChangePoint L1_total_size;
  ChangePoint sst_size_cp;
  //  ChangePoint write_buffer_number;

  sst_size_cp.opt = sst_size;
  L1_total_size.opt = total_l1_size;
  // adjust the memtable size
  memtable_size_cp.db_width = false;
  memtable_size_cp.opt = memtable_size;

  target_value = std::max(target_value, min_memtable_size);
  target_value = std::min(target_value, max_memtable_size);

  // SST sizes should be controlled to be the same as memtable size
  memtable_size_cp.value = std::to_string(target_value);
  sst_size_cp.value = std::to_string(target_value);

  // calculate the total size of L1
  uint64_t l1_size = current_opt.level0_file_num_compaction_trigger *
                     current_opt.min_write_buffer_number_to_merge *
                     target_value;

  L1_total_size.value = std::to_string(l1_size);
  sst_size_cp.db_width = false;
  L1_total_size.db_width = false;

  //  change_list->push_back(write_buffer_number);
  change_list->push_back(memtable_size_cp);
  change_list->push_back(L1_total_size);
  change_list->push_back(sst_size_cp);
}

// @DOTA_tuner.cc:240
inline void DOTA_Tuner::SetThreadNum(std::vector *change_list,
                                     int target_value) {
  ChangePoint thread_num_cp;
  thread_num_cp.opt = max_bg_jobs;
  thread_num_cp.db_width = true;
  target_value = std::max(target_value, min_thread);
  target_value = std::min(target_value, max_thread);
  thread_num_cp.value = std::to_string(target_value);
  change_list->push_back(thread_num_cp);
}

RocksDB 内部结构浅析

2024-01-10T14:39:31.000Z

本文基于 RocksDB v6.8.1 版本

键值的内部编码

RocksDB 内部将用户提供的键值对称为 user_key, 并在内部将其编码为 internal_key. 编码过程发生在 MemTable::Add 中, internal_key 的编码过程大致如下:

uint32_t key_size = static_cast<uint32_t>(key.size());
uint32_t val_size = static_cast<uint32_t>(value.size());
uint32_t internal_key_size = key_size + 8;

uint64_t packed = PackSequenceAndType(SequenceNumber s, ValueType type);

// internal_key 结构示意
Varint32(internal_key_size) + key + Fixed64(packed) + Varint32(val_size) + value;

其将序列号(SequenceNumber s)和键值类型(ValueType type) 编码为一个8字节整数, 并添加到 internal_key 内部.

因此 internal_key 的整体排布如下:

1 2	\|user_key\|timestamp\|seqno\|type\| \|<-------internal_key-------->\|

Memtable 提供的比较器 Memtable::KeyComparator comparator_ 在进行比较时, 只使用 InternalKeyComparator comparator 比较 key + Fixed64(packed) 这部分, 其中 key 部分 InternalKeyComparator 使用用户指定的 Comparator user_comparator_ 进行比较.

值得注意的是 RocksDB 支持 User-defined-Timestamp 功能, 这个功能允许用户为键值对插入一个可指定长度的时间戳, 并可指定一个 Timestamp-aware 的 Comparator. 时间戳部分在进入 MemTable::Add 时是已经编码在 key 中的尾部的, 其比较过程直接由 Comparator::Compare 处理.

键值的内部类型

键值类型 ValueType 定义在 db/dbformat.h 中, 其主要类型如下:

enum ValueType : unsigned char {
    kTypeDeletion = 0x0,
    kTypeValue = 0x1,
    kTypeMerge = 0x2,
    ...
    kTypeSingleDeletion = 0x7,
    ...
    kTypeRangeDeletion = 0xF,  // meta block
    ...
    kTypeBlobIndex = 0x11,     // Blob DB only
    ...
};

其中kTypeDeletion, kTypeValue, kTypeMerge, kTypeBlobIndex 及 kTypeSingleDeletion 为 “值类型”

// Checks whether a type is an inline value type
// (i.e. a type used in memtable skiplist and sst file datablock).
inline bool IsValueType(ValueType t) {
  return t <= kTypeMerge || t == kTypeSingleDeletion || t == kTypeBlobIndex;
}

具体实现中, RocksDB 将 ValueType 的数据与 kTypeRangeDeletion 的数据分开存储, 这些类型被合称为 “扩展值类型”

// Checks whether a type is from user operation
// kTypeRangeDeletion is in meta block so this API is separated from above
inline bool IsExtendedValueType(ValueType t) {
  return IsValueType(t) || t == kTypeRangeDeletion;
}

kTypeMerge, kTypeSingleDeletion 及 kTypeRangeDeletion 类型分别对应 RocksDB 提供的 Merge 和 Single-Delete 以及 DeleteRange 操作, 此处不再赘述.

键值的存储过程

WAL

这部分还没仔细看, 鸽了.

MemTable

键值对通过 MemTable::Add 添加到 Memtable 中, 在编码为 internal_key 后, Memtable 根据值的类型对其进行存储.

Memtable 默认的存储结构为跳表(SkipListRep : MemTableRep), RocksDB 支持的所有存储结构均继承了 MemTableRep (memtable representation). 完整的 MemTableRep 需实现内存分配(Allocate), 插入(Insert), 读取(Get) 以及迭代器(GetIterator) 等操作, Memtable 通过这些操作来实现最终的键值插入和查找功能.

在 MemTable::Add 中, 值类型(IsValueType() == true) 放置在 MemTableRep table_ 中, kTypeRangeDeletion 类型放置在 MemTableRep range_del_table_ 中. 值得注意的一点是 range_del_table_ 总是 SkipListRep.

在满足条件后, DBImpl::SwitchMemtable 将被调用, 将 Memtable 变为 Immutable memtable. 具体过程就是通过 MemTableList::Add 将 Memtable 放入 MemTableList cfd->imm(), 在 MemTableList::Add 中还会调用 Memtable::MarkImmutable 通知 Memtable.

Flush & Compaction

Flush 过程主要在 FlushJob::WriteLevel0Table 中, 笔者认为其与 Compaction 过程的最大不同只是其构建 SST 的数据来源不同.

在 Flush 过程中, 所有待 Flush 的 Memtable 的迭代器((Memtable m)->NewIterator) 将通过 NewMergingIterator 被组合为一个 ScopedArenaIterator; 并和所有的 (Memtable m)->NewRangeTombstoneIterator 一起传递给 BuildTable, 进行最终的 SST 创建过程.

Compaction 过程主要在 CompactionJob::ProcessKeyValueCompaction 中.

SST 构建

BlockBasedTable 是 RocksDB 默认的 SST 实现. 它由 Block 和 Footer 组成, 其文件布局如下:


[data block 1]
[data block 2]
...
[data block N]
[meta block 1: filter block]
[meta block 2: index block]
[meta block 3: compression dictionary block]
[meta block 4: range deletion block]
[meta block 5: stats block]
...
[meta block K: future extended block]
[metaindex block]
[Footer] (fixed size; starts at file_size - sizeof(Footer))

其中 [Footer] 中存放了 metaindex block 和 index block 的 BlockHandle; [metaindex block] 则按 (块名称, BlockHandle) 存储了元信息块 (meta block) 的偏移, 例如 range deletion block 的 key 为 std::string kRangeDelBlock = "rocksdb.range_del";

[Footer] 内容:

legacy footer format:
    metaindex handle
    index handle
     
        // make the total size 2 * BlockHandle::kMaxEncodedLength
    table_magic_number (8 bytes)
new footer format:
    checksum type (char, 1 byte)
    metaindex handle
    index handle
    
        // make the total size 2 * BlockHandle::kMaxEncodedLength + 1
    footer version (4 bytes)
    table_magic_number (8 bytes)

BlockHandles 用于描述块的偏移量和大小

1 2	offset: varint64 size: varint64

值得注意的是每个 Block (除 [Footer] 外的所以类型的均相同), 都设计为用于存储键值数据, 其大概结构如下:

<完整KV 1>
<去除相同前缀KV 2>
<去除相同前缀KV 3>
...
<完整KV k>
<去除相同前缀KV k+1>
...
<重启点 1>
<重启点 2>
...
 // block footer

其中通过 PackIndexTypeAndNumRestarts 编码, 记录了索引类型及重启点个数.

Block 通过 BlockBuilder 进行创建, 通过 BlockBuilder::Add 方法可写入一个键值对; 在写入完成后通过 BlockBuilder::Finish 写入重启点信息和 block footer 完成单个块的构建过程.

在存储和读取时, SST 会以 Block 为单位进行读取和写入. 创建 SST 时, 在使用 BlockBasedTableBuilder::Add 按顺加入全部键值对后, 调用 BlockBasedTableBuilder::Finish 将按文件布局顺序写入各元信息块和[Footer], 完成整个 SST 的构建过程.

写入顺序:

1. [meta block: filter]
2. [meta block: index]
     index_blocks.meta_blocks ( <-- metaindex_block )
     index_blocks.index_block_contents ( <-- Footer )
3. [meta block: compression dictionary]
4. [meta block: range deletion tombstone]
5. [meta block: properties]
6. [metaindex block]
7. [Footer]

萌约 MoeYork

Javacard 不完全指北

Javacard 不完全指北

智能卡相关

机械尺寸

通信协议

物理层

传输层

应用层

C-APDU

R-APDU

读卡器相关

GlobalPlatform 相关

Applet 相关

如何购买 Javacard

WSL 2 分离式 home 挂载

关于 WSL 2 架构

关于 VHD/VHDX

关于挂载

关于稀疏 VHD (SparseVHD)

操作过程

分离/home到 VHDX

自动挂载配置

OpenWRT 配置教程

写在前面

配置细节

自定义构建

IPv6 网络配置

IPv6 地址分配

DHCPv6-PD

RFC 7278

实现局域网获取全球单播地址

桥接配置

802.11s 配置

DSA 架构下的 VLAN 配置

对于虚拟接口

对于转发策略

MultiWAN 配置

无线配置

为 Hexo Next 主题集成 Cusdis 评论组件

配置修改

新建评论模板

配置 Next 主题

某光猫提权过程

ADOC 实现分析

tools/db_bench_tool.cc

utilities/DOTA/report_agent.cc

启动路径

调节过程

utilities/DOTA/DOTA_tuner.cc

新的设置列表生成 (std::vector)

设置参数细节

RocksDB 内部结构浅析

键值的内部编码

键值的内部类型

键值的存储过程

WAL

MemTable

Flush & Compaction

SST 构建

分离`/home`到 VHDX

新的设置列表生成 (`std::vector`)