Mint Lab

KVM虚拟化入门： Debian系统上用物理 DVD 安装 KVM 虚拟机攻略

Tue, 19 May 2026 00:00:00 GMT

环境：Dell PowerEdge R730 / Debian 13 / KVM+libvirt / 纯 SSH 终端（无图形界面）

目标：从服务器物理光驱安装 Fedora 44 和 Arch Linux 虚拟机

参考文章： Linux KVM 虚拟化实战：基于 Debian 系统的完整指南

1. 前置条件

1.1 硬件虚拟化支持检查

KVM 依赖 CPU 的硬件虚拟化扩展，需确保 CPU 支持并启用该功能：

检查 CPU 支持： 执行以下命令，若输出包含 vmx（Intel）或 svm（AMD），则支持虚拟化：

grep -E --color=auto 'vmx|svm' /proc/cpuinfo

若无输出，可能是 CPU 不支持，或需在 BIOS/UEFI 中启用（常见选项：Intel Virtualization Technology 或 AMD SVM）。

验证内核模块加载： 若硬件支持，KVM 内核模块会自动加载（或按需加载）：

lsmod | grep kvm
# 输出示例（Intel）：
# kvm_intel             311296  0
# kvm                   942080  1 kvm_intel

1.2 Debian 系统要求

系统版本：推荐 Debian 11（Bullseye）或 12（Bookworm，最新稳定版），内核版本 ≥ 5.10（KVM 功能更完善）。
资源建议：
- CPU：至少 2 核心（推荐 4 核心以上，支持多线程）。
- 内存：至少 4GB（每台虚拟机建议分配 2GB+，根据需求调整）。
- 存储：至少 20GB 空闲空间（推荐 SSD 以提升虚拟机磁盘性能）。

2. 在 Debian 上安装 KVM

2.1 安装核心组件

Debian 官方仓库提供 KVM 相关包，直接通过 apt 安装：

# 更新软件源
sudo apt update

# 安装 KVM 核心组件、管理工具及网络支持
sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager virtinst

组件说明：

组件	说明
`qemu-kvm`	提供硬件模拟功能，是 KVM 的用户态组件
`libvirt-daemon-system`	libvirt 守护进程（管理虚拟机的核心服务）
`libvirt-clients`	libvirt 命令行工具（如 `virsh`）
`bridge-utils`	网络桥接配置工具
`virt-manager`	图形化虚拟机管理工具（可选，适合桌面环境）
`virtinst`	命令行虚拟机创建工具（如 `virt-install`）

2.2 配置用户权限

默认情况下，仅 root 用户可管理 KVM 虚拟机。为避免直接使用 root，需将普通用户添加到 kvm 和 libvirt 组（前者控制设备访问，后者控制 libvirt 服务）：

# 将当前用户加入 kvm 和 libvirt 组
sudo usermod -aG kvm $USER
sudo usermod -aG libvirt $USER

# 重新登录使权限生效（或执行 `newgrp kvm; newgrp libvirt` 临时生效）

2.3 验证安装

检查 libvirt 服务状态：

sudo systemctl status libvirtd
# 预期输出：Active: active (running)

验证 KVM 模块加载：

sudo virsh capabilities | grep -A 10 "cpu"
# 输出应包含 CPU 特性（如 vmx/svm），表明 KVM 可用

列出默认网络：

virsh net-list --all
# 预期输出：默认 NAT 网络 "default" 处于活跃状态

3. 环境检查

动手前先确认 KVM 服务正常：

# CPU 虚拟化支持
grep -E "(vmx|svm)" /proc/cpuinfo | head -1

# KVM 模块
lsmod | grep kvm

# 设备节点
ls -la /dev/kvm

# libvirtd 状态
systemctl status libvirtd

# 用户组（当前用户需在 libvirt 组）
groups

4. 光驱设备定位

插入 DVD 后，用以下命令定位设备：

lsblk -o NAME,TYPE,SIZE,MODEL,LABEL | grep -E "(sr|cdrom)"

输出示例：

sr0    rom    3.6G HL-DT-ST DVD-ROM DTA0N   Fedora-S-dvd-x86_64-44

结论：设备文件是 /dev/sr0，符号链接 /dev/cdrom → sr0，光盘是 Fedora 44 安装 DVD。

确认设备信息：

cat /proc/sys/dev/cdrom/info
# drive name: sr0
# Can read DVD: 1

验证光盘内容：

sudo mount /dev/sr0 /mnt -o ro
ls /mnt/
# boot  EFI  Fedora-Legal-README.txt  images  LICENSE  media.repo  Packages  repodata
sudo umount /mnt

5. 失败的尝试与排错

以下是我踩过的三个坑，帮你绕过。

尝试一：`--cdrom` 直接启动

sudo virt-install \
  --name fedora-vm \
  --ram 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/fedora-vm.qcow2,size=30 \
  --cdrom /dev/sr0 \
  --os-variant fedora-unknown \
  --network network=default \
  --graphics none \
  --console pty,target_type=serial

结果：VM 启动后一片空白，无法看到安装界面。

原因：Fedora 安装器（Anaconda）默认使用图形界面。--graphics none 禁用了图形输出后，串口控制台没有显示任何内容。WARNING 提示：

CDROM 介质默认情况下不输出信息到文本控制台

尝试二：`--location` + `inst.text`

升级方案——用 --location 从光盘加载内核，加 inst.text 强制文本模式：

sudo mount /dev/sr0 /mnt -o ro

sudo virt-install \
  --name fedora-vm \
  --ram 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/fedora-vm.qcow2,size=30 \
  --location /mnt \
  --os-variant fedora-unknown \
  --network network=default \
  --graphics none \
  --extra-args "inst.text console=ttyS0,115200" \
  --console pty,target_type=serial

结果：内核启动成功，dracut 加载 initrd，但随后进入超时循环：

[ 170.526] dracut-initqueue[1091]: Warning: dracut-initqueue: timeout
[ 170.546] dracut-initqueue[1091]: Warning: It seems that the boot has failed.
[ 170.552] dracut-initqueue[1091]: Warning: missing inst.stage2 or inst.repo
                                       boot parameters on the kernel cmdline.
[ 170.555] dracut-initqueue[1091]: Warning: Please verify that you have
                                       specified inst.stage2 or inst.repo.

原因分析：

--location /mnt 只会从光盘加载 vmlinuz（内核） 和 initrd.img 两个文件，然后启动安装环境。但安装环境启动后，它不知道从哪里获取剩余的安装数据（RPM 软件包仓库），因为光盘并没有作为块设备传给虚拟机——只传了挂载点里的两个引导文件。

Anaconda 需要 inst.stage2 或 inst.repo 参数来告知第二阶段安装源的位置。没有这个参数，dracut-initqueue 就在循环等待 /dev/root 出现，最终超时。

尝试三：混合使用 `--cdrom` + `--extra-args`

天真地想用 --cdrom 传光盘设备，同时用 --extra-args 传文本模式参数：

sudo virt-install \
  --name fedora-vm \
  --cdrom /dev/sr0 \
  --graphics none \
  --extra-args "inst.text console=ttyS0,115200" \
  ...

结果：直接报错 ❌

ERROR  Kernel arguments are only supported with location or kernel installs.

原因：virt-install 规定——内核参数 --extra-args 只能与 --location（PXE/URL/本地目录）搭配使用，不能和 --cdrom（模拟光驱启动）混用。因为 --cdrom 模式下 libvirt 直接让 BIOS/UEFI 从光盘引导，不经过 libvirt 的内核注入流程。

6. 终极方案

综合以上教训，正确的方案是双管齐下：

--location /mnt 负责引导 + --disk /dev/sr0,device=cdrom 传光盘设备 + inst.repo=cdrom 指定安装源

# 1. 挂载 DVD
sudo mount /dev/sr0 /mnt -o ro

# 2. 清理之前的试错残留（如有）
sudo virsh destroy fedora-vm 2>/dev/null
sudo virsh undefine fedora-vm --remove-all-storage 2>/dev/null

# 3. 终极命令
sudo virt-install \
  --name fedora-vm \
  --ram 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/fedora-vm.qcow2,size=30 \
  --disk /dev/sr0,device=cdrom,readonly=on \
  --location /mnt \
  --os-variant fedora-unknown \
  --network network=default \
  --graphics none \
  --extra-args "inst.text console=ttyS0,115200 inst.repo=cdrom" \
  --console pty,target_type=serial

参数详解

参数	作用	为什么需要
`--disk /dev/sr0,device=cdrom,readonly=on`	把物理光驱以 CDROM 设备传给 VM	Anaconda 需要直接访问光盘上的 RPM 仓库
`--location /mnt`	从挂载的光盘中提取 vmlinuz + initrd	用于启动安装环境（允许传 `--extra-args`）
`--graphics none`	禁用图形输出	服务器没有图形界面
`--extra-args "inst.text ..."`	强制文本模式安装	跳过 Anaconda 的图形/RDP 提示
`--extra-args "... inst.repo=cdrom"`	指定安装源为光盘	关键参数——解决 `dracut-initqueue timeout`
`--extra-args "console=ttyS0,115200"`	串口终端输出	安装信息输出到 `virsh console`
`--console pty,target_type=serial`	安装后自动连接串口	无需手动 `virsh console`

执行流程图

物理光驱 /dev/sr0
        │
        ├──► 挂载到 /mnt
        │       │
        │       └──► --location /mnt ──► 提取 vmlinuz + initrd ──► 启动安装内核
        │                                       │
        │                                       ├──► inst.text ──► 文本模式安装
        │                                       │
        │                                       └──► inst.repo=cdrom ──► 从光盘读取 RPM
        │
        └──► --disk /dev/sr0,device=cdrom ──► VM 内出现 /dev/sr0 ──► Anaconda 挂载读取

7. Fedora 文本安装流程

安装启动后，Anaconda 会提示选择模式：

1) Use graphical mode via Remote Desktop Protocol
2) Use text mode

输入 2，然后输入 c 确认

然后按数字键选择配置项：

输入	配置项	说明
`1`	Language	已默认简体中文
`2`	Timezone	已默认 Asia/Shanghai
`3`	Install Source	应自动识别为 Local media
`4`	Software	选择 Fedora Server Edition
`5`	Disk	选择自动分区方案
`7`	Root Password	必须设置
`8`	User	创建管理员用户
`b`	Begin	开始安装

完成后系统会重启进入新系统。

8. 安装后管理

连接到虚拟机

# 方式 1：串口控制台
sudo virsh console fedora-vm
# 退出：按 Ctrl + ]

# 方式 2：SSH（推荐，安装好 guest-agent 后）
sudo virsh domifaddr fedora-vm   # 查看 IP
ssh mint@<vm-ip>

在 VM 内安装 Guest Agent

sudo dnf install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

日常管理速查

# VM 生命周期
sudo virsh list --all           # 查看所有 VM
sudo virsh start fedora-vm      # 启动
sudo virsh shutdown fedora-vm   # 正常关机
sudo virsh destroy fedora-vm    # 强制关机
sudo virsh autostart fedora-vm  # 开机自启

# 修改硬件
sudo virsh edit fedora-vm       # 编辑全部配置
sudo virsh setvcpus fedora-vm 4 --config
sudo virsh setmaxmem fedora-vm 4096 --config

# 快照
sudo virsh snapshot-create-as fedora-vm --name clean-install
sudo virsh snapshot-revert fedora-vm clean-install

# 网络
sudo virsh net-dhcp-leases default   # 查看 VM 的 IP

# 克隆
sudo virt-clone --original fedora-vm --name fedora-vm2 \
  --file /var/lib/libvirt/images/fedora-vm2.qcow2

# 删除
sudo virsh destroy fedora-vm
sudo virsh undefine fedora-vm --remove-all-storage

9. 网络配置：让外部设备访问虚拟机

安装完成后，你会发现一个尴尬的问题：virsh console 可以连上 VM，但从笔记本 SSH 过去却 100% packet loss。

9.1 为什么默认网络外部无法访问

KVM 默认使用 NAT 虚拟网络（virbr0，网段 192.168.122.0/24）。它的工作原理：

┌─────────────────────────────────────────────────────┐
│                    宿主机 (R730)                      │
│                                                     │
│   物理网卡 eno1            虚拟网桥 virbr0            │
│   192.168.43.101  ──NAT──►  192.168.122.1            │
│       │                         │                    │
│       │                         ├── VM: .225         │
│       │                         ├── VM: .xxx         │
│       │                         └── ...              │
│       │                                              │
└───────┼──────────────────────────────────────────────┘
        │
   ┌────┴────┐
   │ 路由器   │
   │ 192.168.43.1
   └────┬────┘
        │
   ┌────┴────┐
   │ 你的笔记本 │
   │ 192.168.43.x
   └─────────┘

关键问题：

笔记本发给 192.168.122.225 的包到达路由器后，路由器查路由表：192.168.122.0/24 在哪？不知道，丢弃。
只有宿主机自己知道这个子网（virbr0 在宿主机内部）。
这就是 ping 不通、ssh 不了的根因。

9.2 三种暴露方案对比

方案	难度	VM IP	适用场景
桥接网络	⭐⭐	独立 IP，和宿主机同网段	VM 长期运行，需要对外提供服务
SSH 隧道	⭐	无需暴露 VM IP	临时访问，无需改网络
端口转发	⭐⭐	无需暴露 VM IP	只暴露特定端口（如 Web、SSH）

下文重点讲解桥接网络（推荐方案）的完整原理与配置。

9.3 桥接网络原理

桥接的本质：让虚拟机"冒充"一台真机直接接入物理交换机。

配置前（NAT）                          配置后（桥接 br0）
┌──────────┐                           ┌──────────────────────┐
│ 宿主机     │                          │      宿主机           │
│ eno1      │                          │                      │
│ .101      │                          │  eno1 ──┐            │
│           │                          │  (无IP)  │           │
│ virbr0 NAT│                          │         br0          │
│ ├─ VM .225│                          │       .101 (宿主机)   │
│           │                          │       .250 (VM)      │
└──────────┘                           └─────────┬────────────┘
                                                 │
VM 对外不可见                                 ┌────┴────┐
                                            │ 路由器   │
                                            └────┬────┘
                                                 │
                                            ┌────┴────┐
                                            │ 笔记本   │
                                            └─────────┘
                                      ssh mint@192.168.43.250 ✅

数据流向变化：

阶段	NAT 模式	桥接模式
VM 发包	→ `virbr0` → 宿主机 NAT → `eno1` → 物理网络	→ `br0` → `eno1` → 物理网络（直达）
外部回包	路由器发给宿主机 .101，宿主机再做 NAT 转回 VM	路由器直接发给 VM 的 IP
性能	多一层 NAT 转换	零拷贝，接近物理网卡性能

9.4 宿主机桥接配置

⚠️ 警告：以下操作会导致 SSH 短暂断开（约 5~10 秒），因为主网卡的 IP 要迁移到桥接口上。

第一步：查看当前网络布局

# 查看默认路由和主网卡
ip route show default
# default via 192.168.43.1 dev eno1 ...
#                       ↑主网卡名

# 查看当前连接
nmcli con show --active
# NAME         UUID    TYPE      DEVICE
# Wired-1      xxxx    ethernet  eno1
# ...

第二步：创建网桥（用 NetworkManager）

# 1. 创建桥接接口 br0
sudo nmcli con add type bridge ifname br0

# 2. 把主网卡 eno1 作为 br0 的从属
sudo nmcli con add type bridge-slave ifname eno1 master br0

# 原理：nmcli 在 /etc/NetworkManager/system-connections/ 下创建两个配置文件：
#   - br0.nmconnection        → 桥接设备定义
#   - br0-slave-eno1.nmconnection → eno1 从属关系
# NetworkManager 重启后自动生效，持久化无需额外操作。

此时发生了什么：

执行前:
  eno1 ── IP 192.168.43.101 ── 默认网关 192.168.43.1

执行中（nmcli con up br0）:
  1. eno1 被加入 br0（变为从属，IP 被剥离）
  2. br0 发起 DHCP 请求，获取 IP  ← SSH 断开发生在这里
  3. 默认路由从 eno1 转移到 br0

执行后:
  eno1 ── 无 IP（master: br0）
  br0  ── IP 192.168.43.xxx（新 DHCP 分配的 IP）

注意：新 IP 可能和原来不同！本次实操中，eno1 原来的 IP 是 192.168.43.69，桥接后 br0 拿到的是 192.168.43.101。如果你有 DHCP 保留 / 静态 IP 需求，应预先设置。

第三步：验证桥接

# 确认 br0 已创建并获取 IP
ip addr show br0 | grep inet
# inet 192.168.43.101/24 ...

# 确认 eno1 已从属到 br0
ip link show eno1
# ... master br0 ...

# 确认默认路由走 br0
ip route show default
# default via 192.168.43.1 dev br0 ...

# 确认 NetworkManager 连接状态
nmcli con show --active | grep br0

9.5 创建 libvirt 桥接网络

宿主机网络桥 OK 了，但 libvirt 还不知道这个桥的存在。需要为 libvirt 定义网络：

# 编写 libvirt 网络定义 XML
cat > /tmp/bridge-net.xml << 'EOF'
<network>
  <name>host-bridge</name>          <!-- libvirt 内的网络名称 -->
  <forward mode="bridge"/>          <!-- 桥接模式：二层转发 -->
  <bridge name="br0"/>              <!-- 绑定到宿主机 br0 网桥 -->
</network>
EOF

# 定义（注册到 libvirt）
sudo virsh net-define /tmp/bridge-net.xml

# 启动
sudo virsh net-start host-bridge

# 设为开机自启
sudo virsh net-autostart host-bridge

# 确认
sudo virsh net-list --all

XML 参数详解：

元素	含义
`<forward mode="bridge"/>`	二层桥接模式。和 NAT 模式 (`mode='nat'`) 不同，不做 IP 转换，VM 数据帧直接透传到 `br0`
`<bridge name="br0"/>`	指定宿主机上已有的 Linux bridge 设备名

<forward mode="bridge"/> vs <forward mode="nat"/>：前者工作在数据链路层（二层），后者工作在网络层（三层）。桥接模式下的 VM 和宿主机在同一个广播域中。

9.6 将虚拟机接入桥接网络

热切换（VM 运行时在线切换）

# 1. 查看当前接口
sudo virsh domiflist fedora-vm
# 接口     类型      源          MAC
# vnet4    network   default    52:54:00:cf:37:f1

# 2. 断开默认 NAT 接口（--mac 用于精确定位要删除的接口）
sudo virsh detach-interface fedora-vm network --mac 52:54:00:cf:37:f1

# 3. 接入桥接网络
sudo virsh attach-interface fedora-vm bridge br0 \
  --model virtio \   # 准虚拟化网卡（最佳性能）
  --config \         # 持久化到 XML 配置
  --live             # 立即生效（--config 只存配置，--live 才在线生效；两者同时用=永久在线切换）

--live vs --config：

--live：立即生效，但重启后丢失

--config：写入 XML，下次启动才生效

两者共用 = 立即生效且持久化

在 VM 内刷新 DHCP

网卡切换后，VM 需要重新获取 IP：

# 进入 VM 控制台
sudo virsh console fedora-vm

# 在 VM 内执行
sudo dhclient enp1s0
# 或
sudo nmcli con down enp1s0 && sudo nmcli con up enp1s0

验证

# 宿主机上查看 VM 的网络接口
sudo virsh domiflist fedora-vm
# 接口     类型     源    型号      MAC
# vnet5    bridge   br0   virtio   52:54:00:54:7e:bc
#                       ↑ 已改为 br0

9.7 查看虚拟机 IP 的多种方式

这是日常管理中最常用的操作，按推荐度排列：

方式一：`virsh domifaddr`（推荐，最全面）

# 通过 Guest Agent 查询（需 VM 内安装 qemu-guest-agent）
sudo virsh domifaddr fedora-vm --source agent
# 名称      MAC 地址            协议    地址
# lo        00:00:00:00:00:00   ipv4    127.0.0.1/8
# enp1s0    52:54:00:54:7e:bc   ipv4    192.168.43.250/24

# 通过 libvirt DHCP 租约查询（仅 NAT 网络有效）
sudo virsh domifaddr fedora-vm --source lease

--source 参数的含义：

来源	适用网络	原理
`agent`	所有网络	查询 VM 内的 qemu-guest-agent，返回真实 IP。最准确。
`lease`	仅 NAT	查询 libvirt 的 dnsmasq DHCP 租约表。桥接模式下不由 libvirt 管理 DHCP，故查不到。
`arp`	所有网络	查看宿主机的 ARP 表（同方式三）。

方式二：`virsh net-dhcp-leases`（仅 NAT 网络）

sudo virsh net-dhcp-leases default
# 到期时间               MAC 地址             协议  IP 地址               主机名
# 2026-05-19 03:40:42   52:54:00:cf:37:f1   ipv4  192.168.122.225/24   -

仅适用于 default NAT 网络。桥接到 br0 后，DHCP 由路由器负责，libvirt 不知道租约信息。

方式三：宿主机的 ARP 表

ip neigh show dev br0
# 192.168.43.250 lladdr 52:54:00:54:7e:bc REACHABLE

# 或用 arp 命令
arp -n -i br0
# Address          HWtype  HWaddress           Flags  Iface
# 192.168.43.250   ether   52:54:00:54:7e:bc   C      br0

原理：宿主机和 VM 在同一个二层域（br0），宿主机通信时自然会缓存 VM 的 MAC-IP 映射。

方式四：路由器后台

直接登录路由器管理页面（如 192.168.43.1），在 DHCP 客户端列表中找到 VM（可根据主机名 fedora-vm 或 MAC 地址识别）。

方式五：登入 VM 内部查看

sudo virsh console fedora-vm
# 登录后执行
ip addr show enp1s0
# 或
hostname -I

IP 查看速查表

场景	推荐命令
日常快速查 IP	`sudo virsh domifaddr fedora-vm --source agent`
NAT 网络查 IP	`sudo virsh net-dhcp-leases default`
桥接网络查 IP	`ip neigh show dev br0`
Guest Agent 未装	`sudo virsh console fedora-vm` 进去看

9.8 SSH 隧道方案（备选）

如果不想改网络，可以用宿主机做跳板：

# 笔记本上执行（一次性）
ssh -J mint@<R730的IP> mint@192.168.122.225

配置 ~/.ssh/config 后更简单：

Host r730
    HostName <R730的IP>
    User mint

Host fedora-vm
    HostName 192.168.122.225
    User mint
    ProxyJump r730

然后直接 ssh fedora-vm。

原理：SSH 客户端先连 R730，在 R730 上开启一个端口转发通道，再通过该通道连接 VM。192.168.122.225 对笔记本仍然不可达，但 R730 可达——它充当了代理角色。

9.9 端口转发方案（备选）

只暴露特定端口，用 iptables 做 DNAT：

# 在 R730 上执行：把 R730:2222 转发到 VM:22
sudo iptables -t nat -A PREROUTING -p tcp --dport 2222 \
  -j DNAT --to-destination 192.168.122.225:22
sudo iptables -A FORWARD -p tcp -d 192.168.122.225 --dport 22 -j ACCEPT
sudo iptables -t nat -A POSTROUTING -j MASQUERADE

# 持久化（Debian）
sudo apt install iptables-persistent
sudo netfilter-persistent save

笔记本连接：ssh -p 2222 mint@192.168.43.101

数据流路径：

笔记本 → R730:2222 → iptables DNAT → VM:22

适用：只需暴露 Web（80/443）或 SSH 等少数端口。不适用多端口或 UDP 密集型服务。

10. Fedora 安装小结

Fedora 安装的核心在于同时使用 --location（提取内核）和 --disk device=cdrom（传光盘设备）。三个关键参数缺一不可：

参数	作用
`--disk /dev/sr0`	把物理光驱作为块设备传给 VM
`--location /mnt`	提取 vmlinuz + initrd 引导
`inst.repo=cdrom`	告诉 Anaconda 从光盘读取 RPM

详细公式见文末第 13 节"全文总结"。

11. Arch Linux 安装实战

说明：在上述 Fedora 安装完成后，笔者又用同样的物理光驱安装了 Arch Linux（2026.05.01 版 ISO），踩了完全不同的坑。本节记录整个过程。

11.1 Arch Linux 的光驱引导

Arch Linux 的 ISO 结构与 Fedora 完全不同——它没有 virt-install --location 能识别的安装树。--location 检查 /mnt 后直接报错：

ERROR  验证安装位置出错：在 URL '/mnt' 上找不到可安装的发行版

失败原因

Fedora 光盘内有标准的 images/pxeboot/vmlinuz + initrd.img 布局，--location 能自动发现。Arch 的内核和 initrd 则藏在更深的路径下：

/mnt/arch/boot/x86_64/vmlinuz-linux
/mnt/arch/boot/x86_64/initramfs-linux.img

必须先探查光盘布局：

sudo mount /dev/sr0 /mnt -o ro
ls -laR /mnt/arch/boot/
# 输出：
# /mnt/arch/boot/x86_64/vmlinuz-linux
# /mnt/arch/boot/x86_64/initramfs-linux.img

同时查看引导器配置，获取必需的内核参数：

cat /mnt/loader/entries/01-archiso-linux.conf
# title    Arch Linux install medium (x86_64, UEFI)
# linux    /arch/boot/x86_64/vmlinuz-linux
# initrd   /arch/boot/x86_64/initramfs-linux.img
# options  archisobasedir=arch archisosearchuuid=2026-05-01-06-05-08-00

关键参数 archisobasedir=arch 和 archisosearchuuid=<UUID> 是 Arch ISO 引导时必须的。没有它们，initramfs 找不到光盘上的根文件系统。

11.2 正确的启动命令

Arch 需要用 --boot 显式指定内核和 initrd 路径，不能依赖 --location：

# 1. 挂载 DVD
sudo mount /dev/sr0 /mnt -o ro

# 2. 清理残留
sudo virsh destroy arch-vm 2>/dev/null
sudo virsh undefine arch-vm --remove-all-storage 2>/dev/null

# 3. 启动安装
sudo virt-install \
  --name arch-vm \
  --ram 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/arch-vm.qcow2,size=30 \
  --disk /dev/sr0,device=cdrom,readonly=on \
  --boot kernel=/mnt/arch/boot/x86_64/vmlinuz-linux,\
         initrd=/mnt/arch/boot/x86_64/initramfs-linux.img,\
         kernel_args="console=ttyS0,115200 archisobasedir=arch archisosearchuuid=2026-05-01-06-05-08-00" \
  --os-variant archlinux \
  --network network=default \
  --graphics none \
  --console pty,target_type=serial

参数对比：Fedora vs Arch

参数	Fedora (Anaconda)	Arch Linux (archiso)
引导方式	`--location /mnt`	`--boot kernel=...,initrd=...,kernel_args=...`
内核参数	`inst.text inst.repo=cdrom`	`archisobasedir=arch archisosearchuuid=<UUID>`
安装源	自动搜索光盘上的 RPM 仓库	archiso 会自动挂载 `/dev/sr0` 到 `/run/archiso/bootmnt`
安装程序	Anaconda（图形/文本向导）	纯命令行（手动 `pacstrap`）

成功启动后，Arch Live 环境会直接进入 root shell：

Arch Linux 7.0.3-arch1-1 (ttyS0)
archiso login: root （无密码直接登录）

11.3 镜像源加速

默认镜像源在国内只有几百 B/s，安装前务必切换到国内镜像：

echo "Server = https://mirrors.ustc.edu.cn/archlinux/\$repo/os/\$arch" > /etc/pacman.d/mirrorlist
echo "Server = https://mirrors.tuna.tsinghua.edu.cn/archlinux/\$repo/os/\$arch" >> /etc/pacman.d/mirrorlist
echo "Server = https://mirrors.aliyun.com/archlinux/\$repo/os/\$arch" >> /etc/pacman.d/mirrorlist

# 开启并行下载
sed -i 's/^#ParallelDownloads/ParallelDownloads/' /etc/pacman.conf
pacman -Syy

效果：下载速度从 12 KiB/s → 3 MiB/s，提升约 250 倍。

11.4 分区与 Btrfs 文件系统

由于 zfs-dkms 已从 Arch 官方仓库移除，且第三方 archzfs 源在国内不可用，改用 Btrfs——它和 ZFS 一样支持 CoW（写时复制）、快照、透明压缩等特性，且原生内置于内核。

# 查看磁盘
lsblk
# vda  30G  ← 唯一磁盘

# MBR 分区（BIOS 模式）
parted /dev/vda mklabel msdos
parted /dev/vda mkpart primary ext4 1MiB 513MiB    # /boot
parted /dev/vda set 1 boot on
parted /dev/vda mkpart primary 513MiB 100%           # btrfs

# 格式化
mkfs.ext4 /dev/vda1                                 # boot 分区
mkfs.btrfs -f /dev/vda2                             # btrfs 根分区

# 创建 btrfs 子卷（方便快照管理）
mount /dev/vda2 /mnt
btrfs subvolume create /mnt/@                       # 根子卷
btrfs subvolume create /mnt/@home                   # home 子卷
umount /mnt

# 挂载
mount -o compress=zstd,subvol=@ /dev/vda2 /mnt
mkdir -p /mnt/{boot,home}
mount -o compress=zstd,subvol=@home /dev/vda2 /mnt/home
mount /dev/vda1 /mnt/boot

分区布局：

分区	大小	文件系统	挂载点
`/dev/vda1`	512 MiB	ext4	`/boot`
`/dev/vda2`	29.5 GiB	btrfs (子卷 @)	`/`
同上	—	btrfs (子卷 @home)	`/home`

11.5 安装基础系统

安装 linux-zen 内核以支持 drm_panic 功能（内核崩溃时显示 QR 码），同时安装中文字体：

pacstrap /mnt base base-devel \
  linux-zen linux-zen-headers \
  linux-firmware btrfs-progs \
  grub networkmanager \
  vim sudo git \
  noto-fonts-cjk

为什么选 linux-zen：主线内核的 drm_panic 功能需要 CONFIG_DRM_PANIC=y 编译选项。Zen 内核开箱即支持，且针对桌面/服务器混合负载做了优化。

11.6 系统配置

# 1. fstab
genfstab -U /mnt >> /mnt/etc/fstab

# 2. chroot
arch-chroot /mnt

# 3. 时区与本地化
ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
hwclock --systohc
echo 'en_US.UTF-8 UTF-8' > /etc/locale.gen
echo 'zh_CN.UTF-8 UTF-8' >> /etc/locale.gen
locale-gen
echo 'LANG=en_US.UTF-8' > /etc/locale.conf
echo 'arch-vm' > /etc/hostname

# 4. 设置密码
echo 'root:arch123' | chpasswd
useradd -m -G wheel -s /bin/bash mint
echo 'mint:mint123' | chpasswd
echo '%wheel ALL=(ALL:ALL) ALL' >> /etc/sudoers.d/wheel

# 5. 复制镜像源配置（新系统也用国内源）
cp /etc/pacman.d/mirrorlist /etc/pacman.conf .

11.7 initramfs 与 GRUB

# 在 mkinitcpio 中添加 btrfs hook
sed -i 's/^HOOKS=.*/HOOKS=(base udev autodetect modconf block btrfs filesystems keyboard fsck)/' /etc/mkinitcpio.conf
mkinitcpio -P

# 安装 GRUB（BIOS 模式）
grub-install --target=i386-pc /dev/vda

# 配置串口输出 + drm_panic
sed -i 's|^GRUB_CMDLINE_LINUX_DEFAULT="|GRUB_CMDLINE_LINUX_DEFAULT="console=ttyS0,115200 drm.panic_register=1 |' /etc/default/grub
sed -i 's|^GRUB_TERMINAL_INPUT=|GRUB_TERMINAL_INPUT=console serial|' /etc/default/grub
sed -i 's|^#GRUB_TERMINAL_OUTPUT=|GRUB_TERMINAL_OUTPUT=console serial|' /etc/default/grub
echo 'GRUB_SERIAL_COMMAND="serial --speed=115200 --unit=0 --word=8 --parity=no --stop=1"' >> /etc/default/grub
grub-mkconfig -o /boot/grub/grub.cfg

# 启用 NetworkManager
systemctl enable NetworkManager

# 退出 chroot，卸载，关机
exit
umount -R /mnt
poweroff

11.8 安装后清理

VM 关机后，从 libvirt XML 中移除 DVD 内核引导配置，改为纯磁盘启动：

# 导出现有 XML，删除 kernel/initrd/cmdline 行
sudo virsh dumpxml arch-vm > /tmp/arch-vm.xml
sed -i '/<kernel>.*vmlinuz-linux<\/kernel>/d' /tmp/arch-vm.xml
sed -i '/<initrd>.*initramfs-linux.img<\/initrd>/d' /tmp/arch-vm.xml
sed -i '/<cmdline>.*archisobasedir.*<\/cmdline>/d' /tmp/arch-vm.xml

# 重新定义并启动
sudo virsh define /tmp/arch-vm.xml
sudo virsh start arch-vm

用户密码：root / arch123，mint / mint123

12. VNC 图形控制台配置

虽然服务器无图形界面，但为 VM 配置 VNC 后，可以从笔记本用 VNC 客户端直连查看 VM 画面（GRUB 菜单、tty 等）。对于 virt-manager 远程管理也必不可少。

12.1 原理

libvirt 的 <graphics> 元素告诉 QEMU 启动一个内置的 VNC 服务器。<video> 元素定义虚拟显卡型号。两者配合后，VM 就有了图形输出通道。

笔记本 VNC 客户端 ──TCP 5901──► QEMU (libvirt) ──► VM 虚拟显卡

12.2 为已有 VM 添加 VNC

注意：操作需要 destroy → define → start，VM 会短暂中断（约 10 秒）。

# 1. 导出 VM 的 XML
sudo virsh dumpxml <vm-name> | sudo tee /tmp/<vm-name>-vnc.xml > /dev/null

# 2. 在 <devices> 起始标签后插入 graphics + video
sudo sed -i 's|<devices>|<devices>\n    <graphics type="vnc" port="-1" autoport="yes" listen="0.0.0.0">\n      <listen type="address" address="0.0.0.0"/>\n    </graphics>\n    <video>\n      <model type="virtio" heads="1" primary="yes"/>\n    </video>|' /tmp/<vm-name>-vnc.xml

# 3. 销毁 → 重新定义 → 启动
sudo virsh destroy <vm-name>
sudo virsh define /tmp/<vm-name>-vnc.xml
sudo virsh start <vm-name>

# 4. 查看分配的 VNC 端口
sudo virsh vncdisplay <vm-name>
# 输出示例：:1  →  端口 5901

<graphics> 参数说明：

属性	值	含义
`type`	`vnc`	使用 VNC 协议
`port`	`-1`	自动分配端口
`autoport`	`yes`	自动选择可用端口
`listen`	`0.0.0.0`	监听所有网络接口

<video> 参数说明：

属性	值	含义
`type`	`virtio`	准虚拟化显卡（性能最佳）
`heads`	`1`	单显示器
`primary`	`yes`	主显示设备

12.3 实际执行结果

笔者两台 VM 配置后的端口分配：

虚拟机	VNC 端口	连接地址
`arch-vm`	`:1`	`192.168.43.101:5901`
`fedora-vm`	`:2`	`192.168.43.101:5902`

12.4 从笔记本连接

VNC 客户端直连（最直接）：

# Linux 笔记本
vncviewer 192.168.43.101:5901

# Windows/Mac 可用 TigerVNC、RealVNC 等客户端

virt-manager 远程连接（在笔记本上安装 virt-manager）：

# 笔记本终端执行（X11 转发）
ssh -X mint@192.168.43.101 virt-manager

这会打开图形化的虚拟机管理窗口，可以查看所有 VM 的状态和画面。

13. 总结

核心教训

Fedora/Anaconda 的图形安装器与无图形服务器不兼容，必须用 inst.text 强制文本模式
--cdrom 模式下不能传 --extra-args，必须改用 --location 方式引导
--location 只传引导文件，不传光盘设备，必须同时用 --disk /dev/sr0,device=cdrom 把光盘作为块设备传给 VM
inst.repo=cdrom 是解决 dracut-initqueue timeout 的关键参数
Arch Linux 不能用 --location，必须用 --boot 显式指定内核路径和 archisobasedir 参数
Arch 官方仓库已移除 zfs-dkms，国内 archzfs 镜像不可用，改用 Btrfs（子卷 + zstd 压缩）是更务实的选择
drm_panic QR 码内核崩溃诊断 需要 linux-zen 内核 + drm.panic_register=1 内核参数
VNC 图形控制台 通过修改 libvirt XML 添加 <graphics> + <video> 实现，不依赖宿主机图形环境

通用公式

Fedora/RHEL/CentOS/Rocky 系列（Anaconda 安装器）：

sudo mount /dev/sr0 /mnt -o ro

sudo virt-install \
  --name <vm-name> \
  --ram <内存> --vcpus <CPU数> \
  --disk path=<磁盘路径>,size=<大小> \
  --disk /dev/sr0,device=cdrom,readonly=on \
  --location /mnt \
  --os-variant <发行版> \
  --network network=default \
  --graphics none \
  --extra-args "inst.text console=ttyS0,115200 inst.repo=cdrom" \
  --console pty,target_type=serial

Arch Linux 系列（archiso，用 --boot 显式指定内核）：

sudo mount /dev/sr0 /mnt -o ro
# 先获取 UUID: cat /mnt/boot/*.uuid

sudo virt-install \
  --name <vm-name> \
  --ram <内存> --vcpus <CPU数> \
  --disk path=<磁盘路径>,size=<大小> \
  --disk /dev/sr0,device=cdrom,readonly=on \
  --boot kernel=/mnt/arch/boot/x86_64/vmlinuz-linux,\
         initrd=/mnt/arch/boot/x86_64/initramfs-linux.img,\
         kernel_args="console=ttyS0,115200 archisobasedir=arch archisosearchuuid=<UUID>" \
  --os-variant archlinux \
  --network network=default \
  --graphics none \
  --console pty,target_type=serial

本文记录于 2026 年 5 月 19 日，环境 Debian 13 + libvirt 11.3.0 + QEMU 10.0.8

折腾家里云：入手一台戴尔R730服务器，设置IDRAC直通并配置ssh隧道

Sun, 17 May 2026 00:00:00 GMT

学校批了一间办公室，不要电费，空调随便开。哎呀，路过科技市场，脚一滑，不知道怎么的就上2楼了，不知道怎么了就配了台服务器回来。本文主要讲解R730服务器的一些特点，以及设置IDRAC直通，和利用已有云服务器配置ssh隧道的过程。

待机功耗56瓦，风扇确实安静，白天根本听不出来

服务器配置

组件	规格 / 备注	价格（元）
戴尔 R730 3.5英寸 8盘位准系统	含 H730 阵列卡、提升卡、8个硬盘架（装满）	750
CPU	单路 Intel Xeon E5-2696v4	280
内存	16GB DDR4 ECC 一根	320
硬盘	512GB 机械硬盘（赠送）	0
合计		1350

我是直接在科技市场线下买的，价格可能偏贵，如果在淘宝可能会更便宜。

设置为默认命令行启动

:::note 我的服务器安装的主系统是Debian 13 (Trixie), 桌面环境是Xfce，通过以下设置可使系统默认以纯命令行启动，并且可以自由启动和退出图形化界面。 :::

通过 systemd 的 multi-user.target (纯命令行) 和 graphical.target (带桌面环境) 来控制默认启动模式。

sudo systemctl set-default multi-user.target

运行以下命令确认设置成功，若输出为 multi-user.target 即成功：

systemctl get-default

手动启动和退出桌面环境

使用 startx 命令启动桌面环境，如果提示未找到命令，需先安装 xinit 包。

startx

如需退出桌面环境，直接在桌面环境中点击注销即可，注意注销后桌面环境中未保存的工作将会丢失。

idrac 配置为直通模式

:::note

戴尔服务器有一个独立于主系统的管理系统idrac，默认是独立的网络，在主系统内访问不到idrac，这样设计的好处是可以在服务器出现故障，或是主系统未启动时依然可以访问idrac，还可以远程重装系统。

我没有多的设备对idrac进行独立穿透了，所以我选择将idrac设置为直通模式，通过主系统访问并转发到云服务器，但这样会使idrac的访问必须依赖主系统的运行。

:::

重启服务器
在bios启动显示以下界面时根据左上角的提示按F2进入System Setup

选择并进入 iDRAC Settings 菜单

找到并进入 Communications Permissions (通信权限)

在 OS to iDRAC Pass-through设置项，选择 USB NIC 模式
在下方的OS IP中输入自定义的ip，这里设置为169.254.0.1，后面要用

保存退出并继续引导，启动主系统。

测试端口是否开放

nc -zv 169.254.0.1 443

# 参考输出
# Connection to 169.254.0.1 443 port [tcp/https] succeeded!

给R730配置一个连接到云服务器的ssh密钥

这一段相信大家都会做，不然怎么连上服务器，难道真用桌面吗(x)

ssh-keygen -t rsa -b 4096 -C "在公钥中的描述文字"

将xxx.pub文件的内容追加到云服务器的~/.ssh/authorized_keys，如果云服务器设置了允许密码登录(不推荐)，则还可以这样上传(会提示输入密码)：

ssh-copy-id user@hostname

配置 ssh 隧道

:::note

需要一个带有固定公网ip的云服务器作为中转，R730先通过ssh连接到云服务器，将自己本地的ssh端口转发到云服务器的本地回环端口上(远程转发)，远程登录时先使用ssh登录云服务器作为跳板，再将云服务器端口转发到本地(本地转发)，通过本地ssh连接R730。

:::

ssh 转发格式

`-L` 本地转发 (Local)


ssh -L [绑定地址:]本地端口:目标主机:目标端口  user@ssh服务器

绑定地址（可选）：默认 127.0.0.1，表示只允许本机连接该本地端口。若写 0.0.0.0 或 * 则允许其他机器连接（需谨慎）。
本地端口：在客户端机器上监听的端口。
目标主机:目标端口：最终要访问的服务地址，这个地址是从SSH 服务端的角度解析的（即服务端去连接它）。

`-R` 远程转发 (Remote)


ssh -R [绑定地址:]远程端口:目标主机:目标端口  user@ssh服务器

绑定地址（可选）：默认 127.0.0.1，表示只在 SSH 服务端本地监听该远程端口。若想允许其他机器访问服务端的这个端口，通常需要服务端配置 GatewayPorts yes，或显式指定 0.0.0.0。
远程端口：在 SSH 服务端机器上监听的端口。
目标主机:目标端口：最终要访问的服务地址，这个地址是从SSH 客户端（本地）的角度解析的（即客户端去连接它）。

安装并配置autossh

为了连接稳定，使用autossh包代替ssh，拥有自动保活控制。


 sudo apt update 
 sudo apt install autossh

新建以下systemd服务文件在/etc/systemd/system/autossh-tunnel.service，

//file: /etc/systemd/system/autossh-tunnel.service

[Unit]
Description=AutoSSH reverse tunnel for R730
After=network.target

[Service]
User=<执行服务的本机用户>
Environment="AUTOSSH_GATETIME=0"
ExecStart=/usr/bin/autossh -M 0 -N -o "ServerAliveInterval 60" -o "ServerAliveCountMax 3"  -o "ExitOnForwardFailure yes" \
          -R 7322:localhost:7322 \    # ssh端口
          -R 7320:169.254.0.1:443 \   # idrac网页控制端口
          -R 5900:169.254.0.1:5900 \  # vnc 端口
          -R 5901:169.254.0.1:5901 \  # vnc ws控制端口
          <云服务器登录用户>@<云服务器ip>:<云服务器ssh端口>
Restart=always
RestartSec=60

[Install]
WantedBy=multi-user.target

写入文件后保存退出并启动服务设置开机自启。


sudo systemctl daemon-reload                      # 重载服务文件
sudo systemctl enable autossh-tunnel.service      # 设置开机自启
sudo systemctl start autossh-tunnel.service       # 启动服务
sudo systemctl status autossh-tunnel.service      # 查看服务状态

参数解释

/usr/bin/autossh autossh 的可执行文件路径。该工具会在 SSH 连接断开时自动重连。
-M 0 设置监控端口为 0，即禁用 autossh 自带的连接检测机制（原本它会通过一个额外端口发送测试数据）。当使用 -M 0 时，autossh 完全依赖 SSH 自身的保活选项来判断连接是否存活。
-N 告诉 SSH 不执行远程命令（不分配 shell）。通常用于纯端口转发场景，只建立隧道而不登录到远程主机。
-o "ServerAliveInterval 60" 设置 SSH 的 ServerAliveInterval 选项：每隔 60 秒向服务器发送一个保活消息（空包），用于检测连接是否仍在工作。
-o "ServerAliveCountMax 3" 设置 SSH 的 ServerAliveCountMax 选项：最多连续 3 次收不到保活消息的响应（即最长 60×3=180 秒无响应），就认为连接已断开，主动关闭连接。
-o "ExitOnForwardFailure yes" （非常重要） 设置 SSH 的 ExitOnForwardFailure 选项：如果端口转发失败（例如本地或远程端口被占用、无法绑定等），SSH 立即退出并报错，等待下一次重连。

:::note

如果R730 ssh连接意外断开(如断网)，在云服务器ssh处短时间不会断连，需要等待约180秒自动清理，这会导致远端端口暂时无法被释放，R730重新连接ssh时虽然连接成功，但是建立端口转发会失败，如果加入"ExitOnForwardFailure yes这个选项，则会让autossh检测到端口转发失败后自动重试。

:::

云服务器ssh配置

通过sudo vim /etc/ssh/sshd_config修改云服务器sshd配置文件，新加入一行。

//file: /etc/ssh/sshd_config

# 在绑定时删除已有的套接字文件，避免端口已占用报错
StreamLocalBindUnlink yes

本机ssh_config配置

//file: ~/.ssh/config

Host cloud
    HostName <云服务器公网ip>
    User <云服务器登录用户>
    Port <云服务器ssh端口>
    IdentityFile /home/mint/.ssh/id_rsa           # 要使用的密钥的本地路径
    LocalForward 7322 localhost:7322
    LocalForward 7320 localhost:7320
    LocalForward 5900 localhost:5900
    LocalForward 5901 localhost:5901
Host R730
    HostName localhost
    Port 7322
    User <R730登录用户>
    ProxyJump cloud
    IdentityFile /home/mint/.ssh/R730_linux_LAPTOP # 要使用的密钥的本地路径

下次使用登录可直接使用：

ssh R730

使用Server Box作为移动端监控

一个非常好用且高颜值的移动端监控软件：

::github{repo="lollipopkit/flutter_server_box"}

先连接云服务器，在连接R730时在下方配置跳板服务器为连接好的云服务器，主机直接填localhost即可：

配置IDRAC远程连接

:::note idrac的远程访问界面有Host检查，必须为本机地址才会放行，远程连接会显示400错误码。需要先登录idrac然后设置禁止Host检查。 :::

登录到R730中，使用ssh连接IDRAC系统：

# 默认用户名是 root，密码是你为 iDRAC 网页界面设置的登录密码, 默认是calvin
ssh root@169.254.0.1

关闭Host检查：

racadm set idrac.webserver.HostHeaderCheck 0

重启web服务：

racadm racreset soft

然后稍等重启完成后，新建一个终端使用ssh cloud建立端口转发，然后打开浏览器访问https://localhost:7320，注意是https，可能会提示不安全的连接，这是IDRAC内部的证书导致的不影响访问。

检查VNC配置

请确认IDRAC许可必须为Enterprise才可以使用VNC，登录，默认用户名root，密码calvin

检查VNC服务器设置是否打开，控制端口设置为5901

在虚拟控制台选项中设置远程端口为5900，插件类型为HTML5

点击启动虚拟控制台即可

博客前端性能大优化：首图快一点，再快一点

Tue, 12 May 2026 00:00:00 GMT

起因是看月度总结那篇文章时发现，直接打开文章链接居然加载不出评论区，排查问题途中顺手做了个全站性能调优。Lighthouse 评分从 34 一路拉到桌面端 95、移动端 76。

起因：评论区加载不出来

写完 2026年4月总结之后，把链接发给了朋友，他说页面打不开评论区。我点开试了一下——从首页点进去正常，但是直接复制链接到新标签页打开，评论区空荡荡，控制台没有任何请求。

神了，Swup 页面切换就正常，直接 SSR 渲染就不行。

排查：set:html + 模板字面量踩坑

F12 看了半天，发现评论区有个巨大的内联脚本（快一千行），用了 Astro 的 set:html 语法把整段 JS 当字符串塞进去：

// ❌ 旧写法
<script is:inline type="module" set:html={
  `(function() {
    const articleKey = ${JSON.stringify(article)};
    // ...
  })();
`}>

这个写法我以前翻过一次车：Astro 的 set:html 里嵌套 JS 模板字面量 ${} 会破坏解析器。跟项目里正常的 CommentForm.astro 对比，它用的是 define:vars。

最后干脆放弃变量注入，直接让脚本从 DOM 的 data-article 属性读取参数，彻底绕开 Astro 的模板魔法：

// ✅ 最终方案：从 DOM 读取，零依赖
var section = document.querySelector('section[data-comment-section-id]');
var articleKey = section.dataset.article;

照着改了，还是不行。继续往深了挖 —— 日志显示脚本确实跑起来了，卡在了 loadMarkdownIt() 里面。

真凶：CDN 脚本加载竞态

comment-utils.js 里的 loadMarkdownIt() 通过动态创建 <script> 标签从 CDN 加载 markdown-it 和 highlight.js：

U.loadMarkdownIt = () => {
  if (window.__md) return Promise.resolve(window.__md);
  // 动态创建 script 标签加载 CDN
  // 等两个脚本都 onload 了才 resolve Promise
};

问题来了：Swup 预加载（prefetch）时已经把 CDN 标签塞进 <head> 了，但 onload 还没触发。直接打开新标签页时，标签已存在，window.__md 却没定义，Promise 永远不 resolve，评论区卡死。

根本原因是这个函数的 else 分支缺失 —— 它只处理了"没有标签就创建"的情况，没有处理"标签已存在但未 onload"的情况。

graph LR
    A[页面加载] --> B{CDN标签已存在?}
    B -->|Swup导航| C[window.__md已缓存]
    C --> D[✅ 直接返回]
    B -->|直接打开| E[标签存在但未onload]
    E --> F[❌ Promise卡死]

修复：超时 + fallback

给 loadMarkdownIt() 加了三个容错机制：

10 秒超时兜底 —— CDN 加载不上也 resolve，评论正常显示（只是没有语法高亮）
else 分支补全 —— 标签已存在则直接检查 window.markdownit 并 resolve
resolved 防重入 —— 防止 onload/onerror/超时多次 resolve

var timeoutId = setTimeout(function() {
  if (resolved) return;
  resolved = true;
  resolve(null); // 降级，继续加载评论
}, 10000);

// 补全的分支：标签已存在但 __md 未定义
if (window.markdownit) {
  tryInit(); tryInit(); // 两次触发 loaded >= 2
} else {
  resolved = true; resolve(null);
}

顺手把 CommentSection 改为懒加载 —— IntersectionObserver 在评论区距视口 400px 时才开始请求数据。文章正文渲染完全不受影响了。

Lighthouse 来了个下马威

评论修好之后跑了一次 Lighthouse 看看整体情况。这一跑不要紧...

优化前：

指标	数值	评级
Performance	34	🔴
FCP	1,633ms	🟢
LCP	4,043ms	🔴
TBT	1,356ms	🔴
Total Size	4,148KB	🔴

主线程长任务排行：

729ms  ← AliyunCaptcha.js  (验证码 SDK)
354ms  ← Layout 内联脚本 bundle
297ms  ← AliyunCaptcha.js 再次
218ms  ← feilin006 (验证码字体渲染)
217ms  ← feilin006 再次
203ms  ← feilin006 再次
197ms  ← cx.031 (验证码动态脚本)

阿里云验证码相关长任务合计 1,760ms，占整个 TBT 的 130%。

逐个击破

1. 图片过大 → sharp 缩放

Lighthouse 报告了 "Properly size images" 警告，预计能省 2,567KB。

罪魁祸首是文章封面图：原图 5760×3240，实际在卡片上只需要 405×228。Astro 内置了 Image 组件，但 ImageWrapper 没传 width，等于原画质输出。

// ❌ 旧：没传宽高，原画质
<Image src={img} />

// ✅ 新：指定宽度 + 2x 视网膜
<Image src={img} width={1600} />  // 800px 显示 × 2x 密度

各场景的尺寸设定：

场景	宽度	说明
文章封面	1600	内容区 800px × 2
卡片封面	400	侧栏 ~200px × 2
头像	192	96px × 2
Banner	2400	全宽 1200px × 2

astro.config.mjs 开启 sharp 图片处理：

image: {
  service: { entrypoint: "astro/assets/services/sharp" },
}

写了一个 rehype 插件，给 markdown 里的 <img> 自动加上 loading="lazy" decoding="async"：

// rehype-image-lazy.mjs
export default function rehypeImageLazy() {
  return (tree) => {
    visit(tree, "element", (node) => {
      if (node.tagName !== "img") return;
      node.properties.loading = node.properties.loading || "lazy";
      node.properties.decoding = node.properties.decoding || "async";
    });
  };
}

2. 封面图 LCP 优化

对于首屏封面图，加上最高优先级：

<ImageWrapper
  loading="eager"
  decoding="sync"
  fetchpriority="high"
  width={1600}
/>

浏览器在发现图片 URL 第一时间就全速下载，LCP 从 4,043ms 压到了 1,452ms。

3. 验证码 SDK 阻塞主线程 → 懒加载

验证码 1.7 秒阻塞是最大痛点。之前 CommentForm.astro 页面一加载就初始化：

setTimeout(initCaptcha, 50);

改成 IntersectionObserver，不滚到评论区就不加载：

var captchaObserver = new IntersectionObserver(function(entries) {
  if (entries[0].isIntersecting) {
    captchaObserver.disconnect();
    initCaptcha(); // 现在才开始下载 AliyunCaptcha.js
  }
}, { rootMargin: '500px' });
captchaObserver.observe(form);

4. KaTeX CSS 按需加载

Layout.astro 全局引入了 KaTeX CSS（约 60KB），实际上只有少数文章（比如 markdown 语法测试那篇）用到数学公式。把它移到了 Markdown.astro —— 只有文章页才加载。

// Layout.astro  ❌ 移除
// import "katex/dist/katex.css";

// Markdown.astro  ✅ 仅文章页
import "katex/dist/katex.css";

5. 说说页面也修了

修复过程中顺手发现说说页（/moments/）有同样的问题。moments.js 也是 IIFE 入口就拿了 var U = window.__commentUtils，而 comment-utils.js 在 <slot /> 之后同步加载，但 moments.js 通过动态插入 script 标签加载，时序不确定。

最简单的方案是保证 comment-utils.js 的加载顺序在所有其它脚本之前 —— 保持同步 <script is:inline src="/comment-utils.js"> 不变。虽然 Lighthouse 会报一个小警告，但实际只有 5KB，在生产环境 HTTP/2 下影响几乎为零。

6. 不删的 CSS

还有一部分 178KB "Unused CSS" —— @tailwindcss/typography 的 prose 变体、expressive-code 代码块样式、photoswipe 灯箱、overlayscrollbars 滚动条。这些都是给特定内容类型准备的（代码块、移动端图片缩放），不能随便删，也没有懒加载 CSS 的简单方案，保留了。

HTTP/2 加速：阿里云 ESA

我的博客托管在阿里云 ESA（全站加速），开启了 HTTP/2。

ESA 控制台 → 站点 → 边缘规则 → 添加规则：

规则名称：启用 HTTP/2
目标类型：所有请求
执行动作：HTTP/2

HTTP/2 相比 HTTP/1.1 的核心优势：

多路复用 —— 一个连接并行传输所有资源，不再需要"CSS Sprites"和域名分片
头部压缩 (HPACK) —— Cookie 等头部信息只传差异部分
对静态资源多的博客来说，HTTP/2 的多路复用优势非常明显

静态资源缓存

顺手把 _astro/ 目录的缓存拉到 365 天：

规则：URL 路径 通配符 */_astro/*
执行：缓存 TTL = 31536000s

Astro 构建的静态文件带内容哈希（如 C6BFPrR2_1wNbLv.webp），内容变了哈希就变，放心缓存。

最终效果

部署后跑了两轮 Lighthouse：

指标	优化前	优化后 (桌面)	优化后 (移动)
Performance	34	95	76
FCP	1,633ms	582ms	2,229ms
LCP	4,043ms	1,452ms	5,604ms
TBT	1,356ms	0ms	0ms
Total KB	4,148KB	797KB	←
Speed Index	7,720ms	1,109ms	2,829ms

TBT 归零是最爽的，验证码懒加载把主线程 1.7 秒的阻塞全消掉了。

为什么移动端 76

Lighthouse 的移动端模拟用 4 倍 CPU 降速 + Slow 4G (1.6Mbps)，相当于 2015 年的低端安卓。对一篇 20+ 张插图的长文来说，76 分非常健康。同类内容型博客（Medium、Dev.to）一般也就 60-80 分。

桌面 95 分说明代码本身已经充分优化。

小结

首图快才是真的快。压缩图片大小谁都会，关键是调节加载顺序。封面图高优先级全速下载，正文插图懒加载不抢带宽，评论区脚本等人滚到了再初始化。

一个很反直觉的经验：改 defer 的确能在 Lighthouse 上好看几分，但在生产环境里这点收益远小于它带来的维护成本。comment-utils.js 直接同步加载只有 5KB，HTTP/2 多路复用下几乎没有感知延迟，但加上 defer 后所有引用它的脚本都要改成惰性访问，反而引入了新的边界条件和 bug。性能优化还是要以用户体验为准，不要为了评分而优化。

以后再写新文章，这些优化会自动生效 —— ImageWrapper 会输出合理尺寸的图片，rehype 插件给插图加 lazy loading，评论区在滚动到附近时才请求。一劳永逸，好耶！

普源DHO804软件升级：谁不想拥有带示波器功能的安卓平板呢？

Mon, 11 May 2026 00:00:00 GMT

本文讲解了如何通过无线网桥给DHO804连上WIFI，用adb进行软件升级到924，并且允许恢复到原来的状态，不影响保修，升级后支持250M带宽，自带root权限，可安装桌面和应用，自定义全面屏手势，然后下载云游戏，原神启动（x）

购买

DHO804有4个通道，70MHz带宽，1.25G采样率，25M存储深度，PD供电功耗约36W。

通过咸鱼经销商购买，价格为1800元整，是全新原盒未开封，可以凭序列号官网质保，比旗舰店便宜约400块，而且顺丰包邮，还是非常划算的。

实验室终于有一台带校准证书的仪器了😭

这外壳设计我真喜欢，还有ui和万能旋钮，用起来非常舒服，设置界面的一些参数可以通过万能旋钮来调节，真正做到了触摸和实体按键相配合。

升级

我是通过29块找咸鱼帮我远程升级的，折磨了卖家一下午（

他还怪好嘞，远程操控完之后，也没删文件，把他的工具和升级固件都留给我了，看一遍就学会了😋

我会把升级固件和adb软件放到后文中供大家自行下载。

准备工作：为示波器联网

DHO804背面有一个有线网口，不支持WIFI连接，如果你有路由器的话，可以通过一条网线直接为它联网，然后跳过这一节。

下文主要讲解怎么为DHO804连接WIFI，我在学校外面租的房，没有办宽带，只能开个热点联网了。

首先需要购买一个无线网桥，某宝参考价格180元（我超，贵死了，可以选择不带12v电源适配器的款，这样会便宜一些。

网桥有一个12v dc供电插口，会接出一根网线和一根USB供电线，直接将网线插入示波器网口，将USB线插入示波器前面板的USB接口就可以供电了。

参考卖家给的说明书，先连接网桥自己的WIFI，配置好网络信息，保存重启之后就可以自动连接你配置的WIFI，并将其转换为有线网啦。

在辅助功能中看到CONNECTED字样即为联网成功，记录一下示波器的IP地址，后面adb连接会用到。

使用adb远程连接到示波器

以下是必要的资源（用于将804升级到924）

adb调试软件(exe)+924固件

首先确保你的电脑和示波器在同一局域网下，可以通过ping验证网络连通性。

ping <示波器的IP地址>

确认网络连通后，输入以下命令进行连接（注意端口是 55555）

adb connect <示波器的IP地址>:55555

然后输入 adb devices，看到 device 状态即为成功。

备份你自己的固件和校准数据

示波器破解前的第一件事，就是备份原始 vendor.bin 这包含了示波器的固件以及独一无二的校准数据。备份后如果需要售后则可以用备份的文件来还原。

adb pull /rigol/data/vendor.bin vendor_old.bin

执行后，vendor.bin文件就会被复制到当前工作目录，命名为vendor_old.bin，请妥善保管。

刷入924的vendor.bin，然后重启示波器，运行一下自校准功能。

adb push <资源包中vendor.bin文件的路径> /rigol/data/

检查示波器设置中的版本，显示924即为成功，如果你只是想升级示波器，到这里就完全结束了，还想自定义安装软件的请看下文。

安装自定义软件

注意到DHO804的安卓版本非常老（Android 7.1 / SDK 25），可能会出现一些应用安装不上的情况，请优先考虑是否是系统版本过低。

以下是非必要资源（我自己自定义安装的一些软件）

火狐浏览器 Firefox 68 APK

文件浏览器 Solid_Explorer_v2.8.37_b200274-arm6.apk

全面屏手势 me.hisn.mygesture_6.41p.apk

启动器桌面 Olauncher-L-v6.3.15.apk

bilibili iBiliPlayer-bili.apk

网易云游戏 official_com.netease.android.cloudgame-2.8.24-2520-netease_new-1029.apk

键盘 Simple Keyboard_6.3_APKPure.apk

可以使用以下命令来安装应用

adb install <本地apk路径>

解决键盘问题：安装Simple Keyboard

adb install <下载好的Simple Keyboard本地apk路径>

# 设置 Simple Keyboard 为默认输入法
adb shell ime enable rkr.simplekeyboard.inputmethod/.latin.LatinIME
adb shell ime set rkr.simplekeyboard.inputmethod/.latin.LatinIME

# 确保输入法已被启用（应该会返回你刚装的输入法）
adb shell ime list -s

解决导航问题：mygesture

adb install <下载好的mygesture本地apk路径>

# 通过 ADB 授权无障碍服务
adb shell settings put secure enabled_accessibility_services com.whiz.quickgest/com.whiz.quickgest.GestureService
adb shell settings put secure accessibility_enabled 1

# 启动手势应用
adb shell monkey -p com.omarea.gesture -c android.intent.category.LAUNCHER 1

安装桌面启动器：Olauncher-L

adb install <下载好的Olauncher-L本地apk路径>

# 安装成功后，先启动一次新桌面
adb shell monkey -p app.olauncher -c android.intent.category.LAUNCHER 1

# 设置为默认桌面
adb shell pm set-home-activity app.olauncher

后续的bilibili,云游戏可自行安装，直接使用adb install <apk路径>即可

dho804示波器仪器包推荐（

我发现随便买的这个收纳包异常的合适，还是硬壳的。某宝参考价90元。

2026年4月总结：忙忙忙忙，参加各种比赛，技术栈增长飞快的一个月

Thu, 07 May 2026 00:00:00 GMT

几乎无休的一个月，因为打比赛，在一个月内学了前端后端嵌入式还有3D建模，非常充实的一个月，小挑战杯，计算机设计大赛都进省赛了，还购置了新设备，好耶！本篇几乎全是关于计设比赛的碎碎念，不涉及任何技术上的细节，是三月下和整个四月经历的回忆，篇幅较长

另外博客因为这篇文章更新了图片标题和横向排版的功能，这篇博客让我受益匪浅：对Fuwari进行一些小的改动（二）改

关于计算机设计大赛的经历

起初：思考比赛的意义

一开始是一个同年级的朋友问我有计算机设计大赛要不要参加，我想可算有一个注重技术的比赛了，而且我当时从来没有使用过git的协作功能，就想加入他们队伍协作做一点东西(毕竟才大一，也只学了C语言，我就当放松了，顺带学习github协作。

我说那随意了，反正大一啥都不会能做出点啥呢，你们想选题吧，谁曾想，选题选了一个毫米波雷达检测老人跌倒的项目, 还说有边缘计算什么东西的，我都惊了。

真的震撼我一整年，现在的大学生都怎么了？如果这是创业大赛，你吹一吹也就算了，这tm是计算机设计竞赛，简直是ai连接大脑，豆包代替思考，怎么能这么敢想，c语言还没学明白呢，太好高骛远了。

唉，其实我一直在想，比赛真的是为了得奖吗，难道不是提供了一个大家一起组队协作，锻炼技术与经验的一个平台吗？之前参加了小挑战杯，其实真的有些失望了，创业大赛变成了PPT吹牛大赛。现在计算机设计大赛也是这样吗，ai生成一个高大上的选题和高深的技术组合，网上下载一些视频和开源项目，拼接、编造成自己的成果，那这样的比赛获奖了又有什么意义呢？

后来我就放弃了和他们组队，没有别的意思，对事不对人，只是大家打比赛的目标不同罢了，我不愿意一个多月只是费劲巴拉的当搬运工，还学不到东西。

我认为打比赛得什么奖不重要，重要的是你学会了什么，最后留下来了什么。借鉴技术不是拿别人的技术拍个演示视频，技术的应用不会比技术研发简单。

机缘巧合：获得一个志同道合的队友

后面我就在想，我小挑的技术部分一个人完成压力太大了，既然计设是一个技术性比赛，能不能用小挑的项目去参加计设，拉一些真正搞技术的人来帮我分担压力，也能让多一些人拿奖。

然后我就在一堂水课上看到坐我斜前方的哥们在拿电脑写代码，我去C++，还会用md看文档，这波会自己学也是领先90%的大学生了，后面我们就认识了，青蝶半染 -- 哇全能键盘手（双关

我俩的比赛目标非常一致，就是学东西，接下来进度简直飞快，git、前端、Vue框架说学就学。很快我们就进入协作开发环节了--他负责前端，我负责后端和嵌入式，一天十几个commit，每天都pr，太燃了（

嵌入式学习：在未知的探索中收获喜悦

我们做的是一个智慧养鸟系统，物联网赛道，需要用到硬件上传图像和传感器数据，并且主动接收一些指令如上粮，开灯等，这套系统是我们完全从零开发的，技术细节可以参考：分类：Lark云雀物联网全栈

选型是ESP32，我也借此机会学习ESP32的开发，在这之前都是用arduino库去写，我想试一试ESP-IDF官方的开发库，另外学习FreeRTOS，提前装好了环境，参考：vscode esp-idf开发环境安装及arduino移植

当时离提交校赛只有不到三周了，状态还只是刚买好模块装好环境，基本是上课查文档，下课搞开发，晚上去想明天的方向和计划，有过焦虑和迷茫，每天都是走一步看一步，一个一个功能的学。熬到凌晨三四点，大半夜的看着自己实现的功能傻笑。

就这样，几乎每天都有新进展，从移植摄像头驱动，设计网络请求回调函数，设计ws传输和命令，到分片接收响应，这些全是我自己亲手写出来的，零ai coding，我只在晚上和ai讨论各种实现的可行性。

信心打击：实地考察征求鸟厂意见

在交稿的前两天，我们紧赶慢赶才完成了系统的功能设计，尤其是必要的远程日志ota功能。说是设备，其实目前只有摄像头和温湿度传感器这两个，去实地部署测试了，去的原因一是我们参加的是物联网创业赛道，需要切实可行的创业相关调研；二是我也想问问能不能真的帮上什么忙。

老板其实是非常不看好的，指着挂在墙上的4G摄像头说，这东西才两百块，还不用联网，你们的能做什么？就是摄像功能也没有它画质好。我为了这次实地部署能够顺利，考虑了很多种情况，鸟厂有可能没有电源，没有WIFI，于是我带上了自己的插排和路由器(移动热点)，还好准备做得足，最后硬说想要试试才放上。

唉，是啊，我也在想到底怎么才能帮上忙，但是在半个月内这是我能做出最最好的状态了，技术方面几乎是都是最好的架构。

我回家看着床头缺少的插板，电脑想要传文件发现连路由器都没了😭。我一直在想是不是一开始就做的太仓促了，没有调研好要做什么，但是所谓的自动喂水喂食，现成的物理结构完全就能实现，自动上粮和铲💩我们可能还设计不来那种机械结构

那天晚上也和朋友聊了很多，网抑云到好晚，你说这比赛打得没意义叭，对我个人来说学了超级超级多，从数据库到嵌入式，还发了四篇博客，有意义叭，我又觉得没帮上实际的忙。

最后我们决定先通过校赛，从"对现实有用"为基础进行设计，从老板提出的缺少批量上粮的系统开始设计，因为学校不给报销，我们打算如果可能的话，在省赛时做出自动上粮的3D结构模型。

藏龙卧虎！稳稳拿下校赛答辩

接下来就是校赛答辩了，因为过于顺利，没拍什么照片，看了现场很多都是大二大三的学长学姐，交流一下发现我们的项目技术还是非常有竞争力的。

计设校赛老师都非常善，还是相当尊重技术的，说是一个队8分钟路演时间，实际上没有计时器，你不管讲多久都不会打断。而且不要求脱稿，ppt直接拿电脑上去念。

我们演示系统的时候老师都直接围上来看，说上一个做物联网的接的是华为云平台，你们这是全链路自己搓的啊，我看这大一的也是藏龙卧虎啊。

打的是物联网赛道，团队没一个是物联网专业的，全靠自学和热爱走到现在（哭。后面答辩环节老师也是什么都没问，基本都是在指导我们省赛怎么打，该怎么扩展交互和传感器。最后也是稳稳进入省赛。

柳暗花明：挣扎着学习3D建模

为了扩展更多功能，我们设计了喂食称重功能和批量喂食的螺旋管道，这些结构部分找不到完全合适的，只得自己建模打印。还好找好哥们借了一台A1 mini，开始学习建模。

从SU开始折腾，破面一直补不上，有时候真的想过自己是否真的不适合学习，仅仅是一个简单的三通管就折腾到三五点后半夜。

后来换到了Rhino，从管道，曲面，螺纹一点点建模，又熬了三天把上粮结构设计出来了，也算3D建模入门了叭，我菜死了。

中途因为鸟粮的谷子在塑料管里转的摩擦是在实在是太大了，输送距离越长越明显，我就看着电机功率一点一点往上涨，到出料口电机直接不动了，把管子剪短了也没用，最后换了一个3v20转的电机，调到12v跑，强而有力，甚至能把卡住的谷子磨碎。

省赛这次我们新加了一个ESP32C3芯片用来外挂新加的传感器，包括光强，紫外线，重量，TVOC，CO2，颗粒物和电压电流这些，带上买的电机和各种耗材，测试的时候还烧了俩ESP32，马上快没钱打比赛了(哭了

突发意外：为准备演示视频组装成品

队友非常靠谱，我俩作息异常的一致，凌晨还在对接传输格式，省赛改进的部分我把前端和后端开发都交给他了，我全部时间都在研究结构和嵌入式，，软硬件都准备完毕，可以拼在一起拍演示视频了。

推算工期没有想到这两个主控，八九个传感器，还有电机，灯和风扇的接线难度，太复杂了。当时软硬件测试完成只剩不到24个小时就要提交到省赛了，我准备用这一坨先简单拍一个演示视频兜底，然后赶快理线，通宵给设备建模个壳子。

没想到遇到不可抗力了，电烙铁突然在手里爆炸了。拆开看了看，也没有发现什么短路问题，这个黄花电烙铁大概陪了我6年，购买记录都找不到了，比我的电脑还要老。中间烙铁头也换过不下六七个了，大到铜接地带，小到0402贴片都焊过，还压过热熔螺母，切过塑料盒，以及烫过我自己（x），真的算是陪我走过了整个电子入门阶段，离别的好突然😭

我知道我该换电烙铁了，一直没有契机，主要是觉得现在这个也够用，但也没必要这样搞我叭（

唉，还是命重要，提前拍的演示视频也可以凑合，是该休息一下了，等新的烙铁到了再做，到答辩现场再展示完整的也不急。

小结：虽然累，但是值得

这段难得的经历真的让我学会了很多，一次次地面对未知与挫折，关关难过关关过，问题解决之后有那种打游戏难有的开心。有过熬到五点的日子，也有一觉睡到下午五点补觉的日子。还有和我一起打比赛的队友，尤其是学姐们，帮我分担了好多文档类的工作，感谢你们一路相伴。以后我会试着将我的经历更多地分享出来。

后记：计设省赛的最终结果

5月17号等我好消息喵，无论结果如何，这些难忘的经历，已经是我最好的收获了。

博客后端并发优化实录：从 SQLite 48 req/s 到 PostgreSQL 323 req/s

Sun, 19 Apr 2026 00:00:00 GMT

狛荷屋主站后端基于 FastAPI + SQLAlchemy 构建，之前的项目使用 SQLite 作为数据库、单 Worker 运行。主站评论功能引入递归 CTE 查询，考虑到后期的可扩展性, 构建时选用了PostgreSQL。本文记录了从 SQLite 迁移到 PostgreSQL，并发优化的完整过程。

起点：SQLite + 单 Worker

最初的架构非常简单：

数据库：SQLite（文件型数据库）
运行方式：uvicorn main:app，单 Worker 单进程
压测结果：

wrk -t2 -c32 -d10s
Requests/sec: 48

SQLite 在并发写入时有全局锁，且不支持异步连接池，成为最大瓶颈。

第一步：迁移到 PostgreSQL

将数据库从 SQLite 替换为 PostgreSQL，使用 asyncpg 驱动 + SQLAlchemy 异步引擎：

engine = create_async_engine(
    "postgresql+psycopg://user:pass@localhost:5432/blog",
    pool_size=10,
    max_overflow=20,
    pool_timeout=30,
    pool_pre_ping=True,
)

迁移后，单 Worker 压测：

wrk -t2 -c32 -d10s
Requests/sec: ~255

提升约 5.3 倍。PostgreSQL 原生支持并发连接和异步查询，递归 CTE 的执行效率也远优于 SQLite。

第二步：部署 Gunicorn 多 Worker

生产环境使用 Gunicorn 启动 4 个 Uvicorn Worker：

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

4 个 Worker = 4 个独立 Python 进程，每个进程有自己的事件循环，可以充分利用多核 CPU。

第三步：发现高并发瓶颈

部署后用 wrk 进行压力测试，发现问题：

wrk -t4 -c2048 -d10s
  Latency     1.49s   302.09ms   2.00s
  Socket errors: timeout 481
Requests/sec: 285.63

低并发时响应约 10ms，高并发时飙升到 200ms+，还出现大量超时。于是开始排查。

瓶颈分析

瓶颈一：日志线程池串行化（最致命）

原始的日志函数：

log_executor = ThreadPoolExecutor(max_workers=1)  # 只有 1 个线程！

async def async_log(logger_obj, level, message):
    def _log():
        getattr(logger_obj, level)(message)
    loop = asyncio.get_event_loop()
    await loop.run_in_executor(log_executor, _log)  # await = 等日志写完

每个请求在中间件中调用 2 次 await async_log。await 意味着协程会挂起并排队等待日志写完。线程池只有 1 个线程时，2048 个请求的日志调用排成长队，所有协程都卡在 await 上。

这是延迟飙升的最主要原因。

瓶颈二：数据库连接池不足

pool_size=10, max_overflow=20  # 最多 30 个并发 DB 连接

当 2048 个请求同时到达，大量请求在等待连接池释放，pool_timeout=30 导致超时前长时间挂起。

瓶颈三：请求日志中间件开销

中间件对每个请求都执行：

读取并解析请求 body
序列化完整 headers + body 为 JSON
2 次阻塞式日志写入

高并发下叠加效果显著。

优化措施

优化一：日志改为 Fire-and-Forget

核心思路：日志提交到线程池后不等待完成，请求立即继续处理。

log_executor = ThreadPoolExecutor(max_workers=4)  # 1 → 4

def async_log(logger_obj, level, message):
    def _log():
        getattr(logger_obj, level)(message)
    try:
        loop = asyncio.get_running_loop()
        loop.run_in_executor(log_executor, _log)  # 不 await！
    except RuntimeError:
        _log()

关键区别：

之前：await run_in_executor → 协程挂起等日志写完 → 高并发下排队
之后：run_in_executor 不 await → 日志任务扔进线程池，请求立刻返回

优化二：增大数据库连接池

engine = create_async_engine(
    DATABASE_URL,
    pool_size=20,       # 10 → 20
    max_overflow=40,    # 20 → 40
    pool_timeout=10,    # 30 → 10，避免长时间挂起
    pool_pre_ping=True,
)

4 个 Worker 进程各自有连接池，总计可用 $4 \times (20 + 40) = 240$ 个数据库连接。

优化三：中间件日志不阻塞

所有 await async_log(...) 改为 async_log(...)，中间件中的日志写入不再阻塞请求处理。

优化结果

本地测试（单 Worker）

并发数	优化前延迟	优化后延迟	吞吐量
16	-	62ms	255 req/s
32	-	125ms	255 req/s
100	-	406ms	250 req/s

吞吐量稳定在 ~255 req/s，延迟随并发线性增长符合 Little's Law：

$$Latency = \frac{Concurrency}{Throughput}$$

生产环境（4 Workers）

并发数	延迟	吞吐量	超时
16	96ms	159 req/s	0
32	103ms	296 req/s	0
100	296ms	323 req/s	2
256	804ms	278 req/s	84

其中生产环境的延迟包含约 34ms 的网络 RTT（客户端 → CDN → 服务器），实际服务器处理时间约 $96 - 34 \approx 62ms$。

性能提升总结

阶段	吞吐量	延迟（32并发）
SQLite + 单 Worker	48 req/s	-
PostgreSQL + 单 Worker	255 req/s	125ms
PostgreSQL + 4 Workers + 优化	323 req/s	103ms（含网络）

SQLite → PostgreSQL + 全部优化后，吞吐量提升约 6.7 倍。

为什么吞吐没有 4x？

4 个 Worker 理论上应该有 4 倍吞吐，但实际只提升了约 27%。原因是：

瓶颈已经从 Python 转移到了 PostgreSQL。 4 个 Worker 共享同一个数据库实例，评论查询使用递归 CTE，数据库 CPU 成为新的天花板。进一步优化需要在 DB 层下功夫（缓存、物化视图等）。

关于合理的压测方式

在排查过程中还踩了一个坑：一开始用 2048 并发压测单 Worker，看到大量超时就以为有问题——其实这完全在预期范围内。

合理的压测并发量应匹配 Worker 数量：

Worker 数	合理并发	压力上限
1	16-32	100
4	32-100	500

超过处理能力的并发只会产生排队，不会暴露真实性能问题。

总结

这次优化最大的收获是：性能瓶颈往往不在你以为的地方。 直觉上会以为"数据库慢"、"Python 慢"，但实际上最致命的瓶颈是一个 max_workers=1 的日志线程池配合 await——一行 await 就让所有高并发请求排成了单行队列。

对于博客这种读多写少的场景，当前性能已经完全足够。如果后续需要进一步提升，方向是在 DB 层做缓存（Redis 或内存 TTL 缓存），可以将评论查询延迟从 ~60ms 降到 <5ms。

重新学习SQL: 完成博客系统的 SQL递归CTE 评论查询设计

Wed, 15 Apr 2026 00:00:00 GMT

一直想给自己的博客添加一个评论功能, 真正写起来才发现评论树的层级嵌套查询并不好做, 在业务层做需要发起多次数据库查询, 而在SQL中使用递归CTE可以很好的解决这一点, 本文主要注重于SQL语句的设计, 真得学了叭

参考

Bilibili视频: SQL语言之 CTE(Common Table Expression)公用表达式

实际需求

实际评论是可以回复盖楼的, 这就意味着在评论内还有评论, 要实现一个评论树的结构

用户A: 文章不错! (#1)
├─ 贴主: 谢谢(#2)
│   ├─ 用户A: 不客气（#3）
│   │   └─ 用户B: 膜（#4）
│   └─ 用户C: 这文章怎么写的? (#5)
└─ 用户C: 你写得也不差(#6)
用户D: 膜膜(#7)

期望返回结构

前端构建需要根据评论的深度层级(depth)来调整缩进, 最好有父级id(parent_id)让我知道是回复了谁, 通过评论路径(path)我就可以摘出整个评论回复链

id	user_id	parent_id	content	depth	path
1	A	NULL	文章不错!	1	1
2	贴主	1	谢谢	2	1 -> 2
3	A	2	不客气	3	1 -> 2 -> 3
4	B	3	膜	4	1 -> 2 -> 3 -> 4
5	C	2	这文章怎么写的?	3	1 -> 2 -> 5
6	C	1	你写得也不差	2	1 -> 6
7	D	NULL	膜膜	1	7

CTE入门

为什么要使用CTE?

来看下面这个例子, 查询所有换过部门的员工, 思路是在 job_history 部门更换记录表中获取员工编号, 然后通过编号筛选换过部门的员工。此处的(select distinct empno from job_history)就是一个子表达式, 如果这个子查询再复杂些, 或者需要在别的地方复用, 则需要再写一遍, 大大提高了代码的复杂度

select * from employees where empno in (select distinct empno from job_history);

什么是CTE?

CTE全称Common Table Expression, 是一个命名的临时结果集,它存在于单个语句的范围内,并且可以在该语句中多次引用，而且CTE还可以相互引用。

并且CTE是在所有主流数据库中都通用的表达式(很多数据库都拥有自己的方言, 那这个是不是可以算作数据库中的普通话x)

CTE的基本语法如下：

WITH cte_name (column list) AS query

SELECT * FROM cte_name;

其中cte_name是cte临时表名, (column list)是cte表中的列名, query部分应该用( )包含整个查询语句,

让我们改造一下上文的SQL语句, 查询所有换过部门的员工, 使用CTE实现:

WITH emp_with_history AS (
    SELECT DISTINCT empno
    FROM job_history
)
SELECT *
FROM employees
WHERE empno IN (SELECT empno FROM emp_with_history);

你会发现原来的子查询被前置了, 先查询作为临时结果集, 后面的查询再从结果集中二次筛选. 虽然看起来比原式稍复杂, 但是有更好的扩展性, 你可以进行多个子查询, 全部都存成CTE, 然后在后文的查询中自由组合使用, 可读性更好.

CTE递归初识

CTE像是一个函数, 所得到的结果可以反复复用, 甚至可以自己使用自己, 即为"函数递归", CTE中的递归需要将WITH变成WITH RECURSIVE, 来看一个例子

WITH RECURSIVE cte_table(n) AS (
    SELECT 1

    UNION ALL

    SELECT n+1 FROM cte_table WHERE n < 10
)

SELECT * FROM cte_table;

输出是一个包含n列的表，有10行，值1到10

整个语句用UNION ALL分成两部分, 上半部分只执行一次, 我们暂且称它为锚点查询, 下半部分会对每个锚点数据反复执行, 直到WHERE中的条件不再符合, 最后将每个子查询和对应原始数据拼接在一起形成最终的结果表.

回到例子中, 上半部分SELECT 1直接与cte_table(n)中的n列对应, 代表直接将一个1放入n列, 下半部分对锚点数据1执行, 将n列的数据+1, 并和锚点数据1拼接在一起, 直到n列不小于10

| n   |
| --- |
| 1   |
| 2   |
| 3   |
| 4   |
| 5   |
| 6   |
| 7   |
| 8   |
| 9   |
| 10  |

更进一步? 递归CTE生成斐波那契数

试一试生成斐波那契数的前10项

WITH RECURSIVE fib(n, fib_n, next_fib) AS (
    -- 初始值：第1项为0，第2项为1
    SELECT 1, 0, 1
    UNION ALL
    -- 递归：下一项 = 当前项 + 前一项
    SELECT n + 1, next_fib, fib_n + next_fib
    FROM fib
    WHERE n < 10   -- 生成前10项
)
SELECT n   AS 序号,
       fib_n AS 斐波那契数
FROM fib;

| 序号 | 斐波那契数 |
| ---- | ---------- |
| 1    | 0          |
| 2    | 1          |
| 3    | 1          |
| 4    | 2          |
| 5    | 3          |
| 6    | 5          |
| 7    | 8          |
| 8    | 13         |
| 9    | 21         |
| 10   | 34         |

好了, 你已经掌握了CTE的精髓--递归

简化版: 测试核心功能

id	user_id	parent_id	content	time
1	123	NULL	文章不错!	2026-04-15T08:00
2	121	1	谢谢	2026-04-15T08:12

在数据库中, 评论数据是按照上述格式存储的

WITH RECURSIVE comment_tree(com_id, user_id, content, depth, path) AS (
    SELECT c.id, c.user_id, c.content, 1, c.id from comments AS c
    WHERE c.parent_id IS NULL

    UNION ALL
    SELECT c.id, c.user_id, c.content, ct.depth+1, concat(ct.path, ' -> ', c.id)
    FROM comments AS c
    JOIN comment_tree AS ct ON ct.com_id = c.parent_id
)
SELECT * FROM comment_tree
ORDER BY path;

该sql返回的内容和上文期望结果相同

在sql中, 使用from comments AS c给comments表起了一个别名c, 接下来需要访问cte表和评论表, 就用表名.列名来区分, 每次计算子节点时都ct.depth+1, 通过concat(ct.path, ' -> ', c.id)拼接出类似于1 -> 2 -> 3的回复链, 后续通过ORDER BY path;自动实现按照评论回复顺序排序

下半部分的JOIN comment_tree AS ct ON ct.com_id = c.parent_id其实就是连接条件, 等价于FROM comments c, comment_tree ct WHERE ct.com_id = c.parent_id, 但是JOIN更加可读

-- 使用 JOIN
SELECT ...
FROM comments c
JOIN comment_tree ct ON ct.com_id = c.parent_id

-- 使用 WHERE
SELECT ...
FROM comments c, comment_tree ct
WHERE ct.com_id = c.parent_id

实际生产环境设计

在实际博客系统中, 不只是获取用户id, 还需要根据user_id, 在users表中查询对应的用户信息并加入评论返回中, 还需要支持置顶评论, 根评论按最新排序, 子评论按时间先后排序, 评论分页功能

并且简化版的sql中还存在一个漏洞, 直接使用path字符串进行排序, 当评论id达到两位数时, 按照符逐个比较排序会发生10排在2前面, 因为先比较的是"10"中的第一个字符"1"与"2"

数据库表示例

comments 表

id	parent_id	root_id	article	user_id	content	time	pinned
1	NULL	1	/abc	101	Root A (pinned)	2024-01-01 10:00:00	1
2	1	1	/abc	102	Child A1	2024-01-01 10:05:00	0
3	1	1	/abc	103	Child A2	2024-01-01 10:10:00	0
4	NULL	4	/abc	104	Root B	2024-01-02 09:00:00	0
5	4	4	/abc	101	Child B1	2024-01-02 09:15:00	0
6	2	1	/abc	105	Grandchild A1-1	2024-01-01 10:20:00	0

users 表

id	username	avatar	home_page	role	email
101	alice	a.jpg	alice.com	user	a@x.com
102	bob	b.jpg	bob.com	user	b@x.com
103	charlie	c.jpg	charlie.com	user	c@x.com
104	dave	d.jpg	dave.com	user	d@x.com
105	eve	e.jpg	eve.com	user	e@x.com

查询SQL

WITH RECURSIVE comment_tree AS (
  SELECT id, id AS com_id, article, user_id, content, browser, os, parent_id, root_id, time, pinned,
         1 AS depth,
         lpad(id::text, 10, '0') AS path,
         time AS root_time
  FROM comments
  WHERE {root_filter}

  UNION ALL

  SELECT c.id, c.id AS com_id, c.article, c.user_id, c.content, c.browser, c.os,
         c.parent_id, c.root_id, c.time, c.pinned,
         ct.depth + 1 AS depth,
         concat(ct.path, ' -> ', lpad(c.id::text, 10, '0')) AS path,
         ct.root_time
  FROM comments AS c
  JOIN comment_tree AS ct ON ct.com_id = c.parent_id
  WHERE c.article = :article
)
SELECT ct.id, ct.article, ct.user_id, ct.content, ct.browser, ct.os,
       ct.parent_id, ct.root_id, ct.time, ct.depth, ct.path, ct.pinned,
       u.username, u.avater, u.home_page, u.role, u.email
FROM comment_tree ct
LEFT JOIN users u ON ct.user_id = u.id
ORDER BY ct.pinned DESC, ct.root_time DESC, ct.path ASC
OFFSET :skip LIMIT :limit

该SQL相较于简化版有着以下明显改进

类别	简化版	最终版
根节点过滤	`WHERE c.parent_id IS NULL`<br>（固定取所有根评论）	`WHERE {root_filter}`（占位符，可动态指定根节点，<br>比如 `root_id = 某值` 或 `parent_id IS NULL AND article = :article）`
文章过滤	无	WHERE 子句中添加了 `c.article = :article`<br>确保子评论与根评论属于同一篇文章
路径构建	`concat(ct.path, ' -> ', c.id)`<br>路径如 1 -> 2 -> 3	用 `lpad(..., 10, '0')` 将 ID 补零成固定宽度（如 0000000001）<br>保证按字符串排序时能按数字顺序排列（避免 10 排在 2 前面）
排序与分页	无	置顶评论（pinned）优先<br>然后按根评论时间倒序<br>同根下的评论按 path 字典序（即树的深度优先顺序）<br>支持分页（OFFSET / LIMIT）

最终查询结果

（{root_filter} = parent_id IS NULL AND article = :article，article=/abc，skip=0，limit=100，排序 pinned DESC, root_time DESC, path ASC）

id	article	user_id	content	parent_id	root_id	time	depth	path	pinned	username	avatar	home_page	role	email
1	/abc	101	Root A (pinned)	NULL	1	2024-01-01 10:00:00	1	0000000001	1	alice	a.jpg	alice.com	user	a@x.com
2	/abc	102	Child A1	1	1	2024-01-01 10:05:00	2	0000000001 -> 0000000002	0	bob	b.jpg	bob.com	user	b@x.com
6	/abc	105	Grandchild A1-1	2	1	2024-01-01 10:20:00	3	0000000001 -> 0000000002 -> 0000000006	0	eve	e.jpg	eve.com	user	e@x.com
3	/abc	103	Child A2	1	1	2024-01-01 10:10:00	2	0000000001 -> 0000000003	0	charlie	c.jpg	charlie.com	user	c@x.com
4	/abc	104	Root B	NULL	4	2024-01-02 09:00:00	1	0000000004	0	dave	d.jpg	dave.com	user	d@x.com
5	/abc	101	Child B1	4	4	2024-01-02 09:15:00	2	0000000004 -> 0000000005	0	alice	a.jpg	alice.com	user	a@x.com

FastAPI单worker后端并发优化: 从持续瘫痪到高并发保持服务

Fri, 10 Apr 2026 00:00:00 GMT

突发奇想给自己的后端压测一下, 没想到30并发就会卡死超时, 重启也未恢复, 本文介绍了完整的排查流程和优化方案, 实现了在3000并发下有超过1/3的请求得到服务, 超出能力的请求全部拒绝, 仅有3个超时.

问题

今天下午压测后端了<br> 咱的后端连30并发都扛不住<br> 那很坏了<br> 测试了512并发，两分钟就能让我们后端瘫痪半小时<br>

使用了systemctl --user restart fastapi.service, systemctl --user stop fastapi.service和systemctl --user start fastapi.service都不能解决问题, 虽然成功重启, 但是服务访问仍然超时

排查

查看数据库连接池

SQLite在创建连接时会先进入连接池, 如果连接池已满, 则后续的连接请求会被阻塞, 直到有连接被释放或默认15秒超时后报错退出

但我们未显式设置连接池数量, 默认为128, 对于我们30并发就阻塞卡死的情况, 显然不合理, 并且我们SQLite是WAL模式, 写不阻塞读, 所以排除数据库的问题

TCP连接池满?

我们使用ss -tan state close-wait -H | wc -l命令查询了系统未关闭的TCP连接数量,

mint@MintServer-WH:~$ ss -tan state close-wait -H | wc -l
468

结果非常惊人, 有接近500个连接未被关闭, 这非常符合我们刚刚进行的512并发测试, 并且重启服务这些连接也未被关闭.

反复刷新可以发现这些连接在缓慢减少, 说明后端正在缓慢处理这些堆积的请求, 可是这些请求对应的客户端早都超时退出了, 服务器正在做无用功.

大约半小时过去了, 我们还在寻找解决方案时, 后端服务突然恢复了, 重新查看发现未关闭的连接数果然下降到了1, 这也证实了我们的想法

修复思路

清除大量未关闭的连接

从网上查到了这行命令lsof -i:<端口号>, 可以查询正在使用端口的进程和状态, 运行显示

mint@MintServer-WH:~$ lsof -i:8080
COMMAND      PID USER   FD   TYPE   DEVICE SIZE/OFF NODE NAME
nginx    3967538 mint   13u  IPv4 50128379      0t0  TCP localhost:47238->localhost:http-alt (ESTABLISHED)
gunicorn 4062077 mint    3u  IPv4 48464702      0t0  TCP localhost:http-alt (LISTEN)
gunicorn 4062083 mint    3u  IPv4 48464702      0t0  TCP localhost:http-alt (LISTEN)
gunicorn 4062083 mint   28u  IPv4 50129369      0t0  TCP localhost:http-alt->localhost:47238 (ESTABLISHED)

ttp-alt 是 /etc/services 中定义的 8080 端口的服务别名，实际就是端口 8080。

我们是一个典型的 Nginx 反向代理 → Gunicorn 应用服务器的本地回环通信架构：

Gunicorn 在 127.0.0.1:8080 上监听 HTTP 请求（两个 LISTEN 是因为 master + worker 共享同一个监听套接字）。
Nginx 作为客户端主动向 localhost:8080 发起连接（从自己的临时端口 47238 连过去），用来转发外部 Web 请求。
输出中的 ESTABLISHED 连接正是 Nginx 与 Gunicorn 之间当前活跃的一条请求通道。

之前使用systemctl --user restart fastapi.service属于优雅关闭, 保留了进程的TCP连接池, 以便重启后能够继续处理未完成的请求, 这就是我们重启也无效的原因 -- 大量的请求还未被关闭, 服务上线后依然在按顺序处理这些过时的请求, 新的请求只能在后面排队, 等排到新请求也超时了.

使用kill -9 <进程PID>强制关闭进程, 这里注意要关闭Gunicorn的主进程, 根据上图也就是4062077, 强制关闭后重新检查未关闭连接数量

mint@MintServer-WH:~$ ss -tan state close-wait -H | wc -l
1

恢复正常, 使用systemctl --user start fastapi.service启动服务, 后端服务正常运行!

优化单线程逻辑

之前的操作只是从瘫痪中临时恢复, 如果再来一次高并发, 依然会陷入相同的境地, 我可不想每次都上来杀进程:(

解决方案是在FastAPI http中间件里添加信号量, 试了试asyncio但是我好像不太会用(, 所以就自己写了一个

该设计限制了单worker的最大处理数, 在多worker时依然有效, 因为不同worker内存独立, gunicorn会将负载均衡分配到每一个worker上

# 请求限制信号量实现
class RequestLimiter:
    def __init__(self, max_concurrent: int):
        self._max = max_concurrent
        self._current = 0
        self._lock = asyncio.Lock()

    async def acquire(self) -> bool:
        async with self._lock:
            if self._current >= self._max:
                return False
            self._current += 1
            return True

    async def release(self) -> None:
        async with self._lock:
            if self._current > 0:
                self._current -= 1

request_limiter = RequestLimiter(5)

@app.middleware("http")
async def log_requests(request: Request, call_next):
    if not await request_limiter.acquire():
        return JSONResponse({"detail": "server busy"}, status_code=503)
    try:
        # 处理请求
        response = await call_next(request)    # T1. 先处理业务, 获取响应
        return response                        # T2. 由于在try块中, python会先记住要返回的值
    finally:
        await request_limiter.release()        # T3. finally执行, 释放信号量
                                               # T4. 函数真正返回

ESA访问频次限制

在阿里云ESA访问频次限制中, 限制了同一ip在10秒内请求超过60次即触发拦截, 返回403

来感受恶意()

最终效果

1024并发-ESA防护

3000并发-无ESA防护 1273+1724=2997

3000并发情况下，有超过1/3的请求完成服务，1724个拒绝，仅有3个超时, 完美解决!

谁说单线程不能打，单线程能服务1000多个请求，改成32线程，并发上3万（x）

多worker优化

保持上述设计的同时可以在nginx限制全局并发

# Nginx 配置示例
http {
    # 定义一个共享内存区域，用于存储连接数状态
    limit_conn_zone $binary_remote_addr zone=perip:10m;
    limit_conn_zone $server_name zone=perserver:10m;

    server {
        location / {
            # 每个IP的并发连接数限制
            limit_conn perip 10;
            # 所有IP对当前虚拟主机的总并发连接数限制
            limit_conn perserver 50;

            # 当请求超过限制时，返回503状态码
            limit_conn_status 503;

            proxy_pass http://backend;
        }
    }
}

我的第一个边缘计算项目：用阿里云 ESA 搭建设备视监面板

Wed, 08 Apr 2026 00:00:00 GMT

前言

第一次接触边缘计算，用阿里云 ESA 的边缘函数 + EdgeKV 做了一个设备监控面板。没有服务器，没有数据库，一个 JS 文件就是全部后端。这篇文章记录整个技术方案的实现细节。

网站在这里: Mint Now--视监面板欢迎来玩!

什么是边缘函数

传统的后端服务跑在一台固定的服务器上，用户的请求需要绕到那台机器再返回。边缘函数不同——代码被部署到全球各地的 CDN 节点上，用户的请求由离他最近的节点直接处理，响应速度天然就快。

阿里云 ESA（Edge Security Acceleration）提供的边缘函数基于标准的 Web Worker API，写法和 Cloudflare Workers 类似：

export default {
  async fetch(request, env, ctx) {
    return handleRequest(request);
  }
};

整个 monitor.js 就是一个标准的 fetch handler。接收 Request 对象，返回 Response 对象，中间没有 Express、没有 Koa，连 Node.js 的 http 模块都不存在——这是一个纯粹的 Serverless 环境。

路由分发也是手写的 if/else：

async function handleRequest(request) {
  const url = new URL(request.url);
  const path = url.pathname;

  if (path === "/api/monitor/report" && request.method === "POST") {
    return handleReport(request);
  }
  if (path === "/api/monitor/devices" && request.method === "GET") {
    return handleGetDevices();
  }
  // ...更多路由
  return errorResponse("Not Found", 404);
}

没有框架抽象，逻辑一目了然。

EdgeKV：边缘节点上的键值存储

边缘函数是无状态的，每次请求之间不共享内存。要持久化数据，ESA 提供了 EdgeKV——一个分布式键值存储，和边缘函数跑在同一层网络上，读写延迟极低。

使用方式很直接：

const kv = new EdgeKV({ namespace: "monitor-kv" });

// 写
await kv.put("device:my-pc", JSON.stringify(deviceData));

// 读
const value = await kv.get("device:my-pc");

// 删
await kv.delete("device:my-pc");

在这个项目里，KV 存储承担了所有的数据职责：

Key 模式	用途
`device:<id>`	单个设备的完整状态
`device:list`	所有设备 ID 的数组
`device:list:data`	所有设备数据的缓存快照
`uptime:<id>:<date>`	按天聚合的设备在线时长（分钟）
`viewer:<id>`	单个观看者的会话数据
`viewer:list`	所有观看者 ID 的数组
`viewer:list:data`	所有观看者数据的缓存快照

你会注意到 device:list:data 和 viewer:list:data 这两个"缓存列表"。这是被 EdgeKV 的调用次数限制逼出来的设计——如果每个设备存一条 KV，获取设备列表时要逐个 kv.get()，5 台设备就是 5 次 KV 调用，超了配额直接报错。所以在设备上报时，顺手把整个设备列表冗余地写一份到 device:list:data，读列表时一次 kv.get() 全部拿回来。

没有 TTL？手动管理过期

这是踩的最大的坑。很多 KV 存储（比如 Cloudflare KV）支持设置 TTL，key 到期自动删除。但 ESA 的 EdgeKV 没有原生的 TTL 支持。如果你写入一条数据，不主动删，它就永远在那里。

对于设备数据这种 7 天过期的场景，不可能靠定时任务去扫——边缘函数没有 cron，只有请求来了才会执行。

最终方案是 包装层模拟 TTL。写入时，把实际数据和过期时间戳包在一起：

function makeExpirablePayload(value, ttlSeconds) {
  return JSON.stringify({
    value,
    expireAt: Date.now() + ttlSeconds * 1000,
  });
}

KV 里存的不是裸数据，而是 { value: <实际数据>, expireAt: <过期时间戳> } 这样的信封。

读取时，通过配套的 getExpirableValue 函数拆信封：

async function getExpirableValue(kv, key, { deleteIfExpired = true } = {}) {
  const raw = await kv.get(key);
  if (raw === undefined || raw === null) return null;

  try {
    const parsed = JSON.parse(raw);
    if (parsed && typeof parsed.expireAt === "number"
        && Object.prototype.hasOwnProperty.call(parsed, "value")) {
      if (Date.now() > parsed.expireAt) {
        // 过期了，顺手删掉
        if (deleteIfExpired) {
          kv.delete(key).catch(() => {});
        }
        return null;
      }
      return parsed.value;
    }
  } catch (e) {
    // 不是包装格式，返回原始值
  }
  return raw;
}

关键在于 deleteIfExpired——读到过期数据时，顺手异步删除。这是一种"惰性清理"策略：不专门花时间扫过期数据，而是在正常业务读取时发现过期就清。代价是过期后到下一次被读到之间，数据仍然占着空间；好处是零额外开销。

在拉取设备列表和观看者列表时也做了同样的处理：

for (const device of devices) {
  if (device._expireAt && now > device._expireAt) {
    await removeDeviceFromLists(kv, device.id).catch(() => {});
    continue; // 跳过过期设备
  }
  // ...正常处理
}

每次读列表都是一次"顺便清扫"。

实时观看者计数

这是整个项目里最有意思的部分。需求很简单：页面上显示"当前有 N 人正在观看"。

心跳机制

浏览器端每隔 30 秒发一次心跳：

POST /api/monitor/viewers
{ "id": "viewer-abc123", "page": "home" }

边缘函数收到后，写入一条带 35 秒 TTL 的观看者数据：

const viewerData = {
  id: body.id,
  page: body.page || "",
  source: body.source || "",
  lastSeen: now,
  _expireAt: now + CONFIG.VIEWER_TTL_SECONDS * 1000, // 35秒后过期
};

TTL 设为 35 秒（比心跳间隔 30 秒多 5 秒容错）。如果用户关闭页面、断网、切走，心跳停止，35 秒后这条数据自动被视为过期。

查询时过滤

拉取观看人数时，从缓存列表里读出所有观看者，过滤掉已过期的：

for (const viewer of viewers) {
  if (viewer._expireAt && now > viewer._expireAt) {
    continue; // 跳过过期的观看者
  }
  validViewers.push(viewer);
  if (!page || viewer.page === page) {
    activeViewers.push(viewer);
  }
}

如果发现有过期条目被清除了，顺手把清理后的列表写回 KV，保持缓存干净：

if (validViewers.length !== viewers.length) {
  await kv.put(CONFIG.KV_VIEWER_DATA_LIST_KEY, JSON.stringify(validViewers));
}

同时在心跳写入时也会清理过期条目，避免缓存列表无限膨胀影响实时性：

async function updateViewerDataList(kv, viewerData) {
  let viewerList = listJson ? JSON.parse(listJson) : [];
  // 清理已过期的观看者，保证实时性
  const now = Date.now();
  viewerList = viewerList.filter(
    (item) => !(item._expireAt && now > item._expireAt)
  );
  // 然后更新当前观看者...
}

按页面过滤

支持查询特定页面的观看人数：

GET /api/monitor/viewers?page=home

返回结构：

{
  "success": true,
  "data": {
    "count": 3,
    "viewers": [...]
  }
}

整个方案没有 WebSocket，没有长连接，纯粹靠轮询心跳 + 短 TTL 模拟出了实时效果。在 Serverless 环境下这是最务实的方案——你没有长驻进程来维持 WebSocket 连接。

设备状态的三态判定

设备也是靠心跳判断在线状态的，但需要比观看者更细的粒度。定义了三种状态：

const CONFIG = {
  OFFLINE_THRESHOLD: 30 * 60 * 1000, // 30分钟无心跳 = 离线
  AWAY_THRESHOLD:    10 * 60 * 1000, // 10分钟无心跳 = 离开
};

function determineStatus(lastSeen) {
  const diff = Date.now() - lastSeen;
  if (diff > CONFIG.OFFLINE_THRESHOLD) return "offline";
  if (diff > CONFIG.AWAY_THRESHOLD)    return "away";
  return "online";
}

online：10 分钟内有心跳
away：10~30 分钟无心跳（可能睡眠或暂时离开）
offline：超过 30 分钟无心跳

状态不是存死的，而是每次查询时根据 lastSeen 实时计算。这样即使没有新的上报，查询接口也能反映最新状态。

上报客户端

配套写了一个 Python 客户端 report_client.py，跑在被监控的设备上，支持自动采集系统信息：

python report_client.py --id my-pc --interval 60

它会每 60 秒采集一次 CPU、内存、磁盘、电量等信息，通过 psutil 获取，然后 POST 到边缘函数。还能自动检测前台运行的应用窗口（Linux 下通过 xdotool），方便在面板上展示"这台机器正在干什么"。

Serverless 的优势

做完这个项目，对 Serverless 的体感比之前清晰很多：

零运维。没有服务器要管，不用装 Nginx，不用配 systemd，不用半夜爬起来重启进程。代码推上去就跑。

按需付费。没有请求就不产生费用。对于个人项目这种流量极低的场景，成本几乎为零。传统方案怎么也得一台 VPS，哪怕空跑也按月收费。

天然全球加速。代码部署在 CDN 边缘节点上，不管用户从哪里访问，响应都是就近的。不需要额外买 CDN、配回源、调缓存策略。

自动扩缩。突然来了 1000 个并发？平台自动处理。不需要提前预估容量、配负载均衡。

当然也有代价：

调试困难。没有本地运行环境（本项目靠 mock 的 EdgeKV 做本地测试）
存储限制。EdgeKV 只是简单的键值对，复杂查询做不了
没有原生 TTL。这篇文章花了大量篇幅讲手动过期管理，就是因为平台不提供
冷启动。虽然边缘函数的冷启动比传统 FaaS 快得多，但偶尔还是能感知到

小结

一个 731 行的 JS 文件，一个 Python 上报脚本，零服务器，实现了：

多设备状态监控（在线/离开/离线三态）
实时观看者计数（心跳 + 短 TTL 过期）
7 天在线时长统计
设备前台应用检测
完整的 CRUD API

作为第一次接触边缘函数的项目，整体体验是积极的。最大的收获不是代码本身，而是理解了在"没有服务器"的限制下，如何用最朴素的方式（轮询、包装 TTL、冗余缓存）解决实际问题。

在 Linux Mint 上折腾 DRM Panic：从企鹅到二维码的完整调试记录

Tue, 07 Apr 2026 00:00:00 GMT

:::note[前言]

在b站上刷到 Linux 内核在2024年增加了一个有趣的功能：DRM Panic。当内核发生Kernel Panic时，会出现一个类似于windows的蓝屏界面(划掉, 紫屏。我在物理机上尝试了最终还是没看到二维码, 搞半天原来要重新编译内核(晕

于是，我开启了一段长达数小时的调试之旅。本文将完整记录整个过程——从触发内核恐慌、解决各种卡死问题，到最终发现“二维码缺失”的根本原因。希望能给同样好奇的朋友一些参考。

我的设备：

RedmiBook 14 II，
CPU Intel i7-1065G7（Ice Lake）
双显卡 Intel + NVIDIA MX350
系统 Linux Mint 22.2 Zara
内核 6.14.0-29-generic

:::

一、初次尝试：直接触发，只有卡死

按照网上的教程，最简单触发内核恐慌的命令是：

echo c | sudo tee /proc/sysrq-trigger

结果屏幕直接卡死在最后一帧，没有任何新画面，键盘无响应，只能长按电源键强制重启。查看日志确认内核确实 panic 了，但画面没出来。

原因分析

· 默认内核启动参数中有 quiet splash，隐藏了大部分输出。 · 图形界面（Cinnamon）的 Xorg 服务器持有 DRM master 锁，内核恐慌时无法抢占显示输出。

二、初现曙光：切换到 tty 文本控制台

我尝试按 Ctrl+Alt+F3 切换到纯文本 tty，登录后再次触发崩溃。这次屏幕上终于出现了黑底白字的内核恐慌调用栈——但依然没有企鹅和二维码。

这说明：传统文本模式可以工作，但 DRM Panic 的图形界面没有激活。

检查内核配置

grep -E "CONFIG_DRM_PANIC" /boot/config-$(uname -r)

输出显示：

CONFIG_DRM_PANIC=y
CONFIG_DRM_PANIC_FOREGROUND_COLOR=0xffffff
CONFIG_DRM_PANIC_BACKGROUND_COLOR=0x5e2750
CONFIG_DRM_PANIC_SCREEN="user"
# CONFIG_DRM_PANIC_SCREEN_QR_CODE is not set

好消息：内核已编译 DRM_PANIC 支持。坏消息：当前模式是 user（只显示文本），二维码功能被禁用。

三、尝试强制启用图形化 Panic

1. 修改 GRUB 内核参数

编辑 /etc/default/grub，添加：

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash drm.panic=1 drm.panic_force=1 vt.handoff=0"

运行 sudo update-grub 并重启。检查 /proc/cmdline 确认参数已生效。

2. 问题依旧：图形界面下仍然卡死

即使在桌面环境直接触发，依然卡在最后一帧。于是我尝试禁用 NVIDIA 显卡（使用 prime-select intel 并黑名单 nvidia 模块），结果依旧。

3. 添加 nomodeset 后“成功”了？

在 GRUB 参数中加入 nomodeset（禁用内核模式设置）后，触发崩溃时终于出现了紫色的文本 panic 界面，顶部有 ASCII 企鹅字符！但是——没有二维码。

这正是文章开头那张截图的效果。

四、定位二维码缺失的真相

检查运行时控制接口

cat /sys/module/drm/parameters/panic_screen
# 输出：user

尝试在线切换为二维码模式：

echo -n qr_code | sudo tee /sys/module/drm/parameters/panic_screen
# 报错：Invalid argument

这说明内核根本不认识 qr_code 这个值。

终极检查：内核编译选项

grep "CONFIG_DRM_PANIC_SCREEN" /boot/config-$(uname -r)

输出：

CONFIG_DRM_PANIC_SCREEN="user"
# CONFIG_DRM_PANIC_SCREEN_QR_CODE is not set

真相大白：我的 Linux Mint 内核在编译时只开启了文本模式，二维码功能对应的 CONFIG_DRM_PANIC_SCREEN_QR_CODE 被明确关闭了。因此无论怎么配置，都不可能显示二维码。

五、为什么会这样？发行版内核策略

· 二维码功能依赖 Rust 编写的底层库，编译时需要完整的 Rust 工具链。 · Ubuntu/Debian 系（包括 Mint）为了稳定和减少依赖，默认不开启该选项。 · 而 Arch Linux、Fedora 等激进发行版则默认启用了二维码。

六、硬件兼容性问题补充

在排查过程中，我发现即使不加 nomodeset，DRM Panic 也无法在图形界面下正常工作。查阅内核邮件列表发现，该功能的开发者 Jocelyn Falempe 曾报告：

“I still have an issue with Alderlake, and it doesn't work when in gnome desktop.”

我的 Ice Lake 平台与 Alderlake 架构相近，同样受到影响。这说明除了内核配置，部分 Intel 显卡在图形界面下的抢占问题也是未解决的 bug。

七、最终结论与建议

1. 为什么我没看到二维码？

直接原因：当前内核编译时未启用 CONFIG_DRM_PANIC_SCREEN_QR_CODE。
根本原因：Linux Mint 发行版内核策略保守，未包含该功能。

2. 为什么连紫色企鹅界面都看不到（不加 nomodeset）？

硬件/驱动兼容性问题，Intel Ice Lake + i915 驱动在图形界面下无法被 DRM Panic 抢占。

3. 如何完整体验 DRM Panic？

最简单：使用虚拟机安装 Fedora 40+ 或 Arch Linux，直接触发。
物理机：要么更换发行版，要么自己重新编译内核（开启 CONFIG_DRM_PANIC_SCREEN_QR_CODE=y），并接受可能存在的抢占问题。

4. 给同样折腾的朋友的建议

先检查 /proc/cmdline 确认参数生效。
用 lsmod | grep nvidia 排除双显卡干扰。
查看内核 config 确认 CONFIG_DRM_PANIC_SCREEN_QR_CODE 是否开启。
如果只是为了截图，虚拟机是最省心的途径。

八、彩蛋：开发者自己的话

“我仍然在 Alderlake 平台上遇到问题，在 GNOME 桌面下它无法工作。” —— Jocelyn Falempe

连功能开发者都在某些 Intel 笔记本上搞不定，我的 RedmiBook 失败也就不那么意外了。这证明问题不是我的配置错误，而是功能本身在部分硬件上尚不完善。

为什么说Rust是编程界的原神.jpg

后记

虽然最终没有在物理机上看到完整的二维码，但整个调试过程让我对 Linux 内核参数、DRM 子系统、GRUB 配置以及内核编译选项有了更深的理解。而且，至少我成功看到了那只紫色的 ASCII 企鹅——也算是不虚此行。

后后记：在ArchLinux虚拟机上看到二维码

初识Latex: 从安装到撰写比赛计划书

Fri, 03 Apr 2026 00:00:00 GMT

最近打了商业精英挑战赛, 需要经常写计划书协作, 那么问题来了, linux写word并不太方便, libreoffice还是太拉了, 并且每次协作都需要重新排格式, 涉及到的公式还非常难排, 本文介绍了基于linux系统latex的安装和在计划书撰写方面的尝试

参考文章

我的设备:

系统 Linux Mint 22.2 Zara
内核 6.14.0-29-generic

安装

本文主要针对Linux系统安装TeX Live作介绍, 其他系统可查看上方参考文章

"首先我推荐在 Linux 平台安装 TeX Live（Mac 不在本文的讨论之列）。出于各种原因，Linux 下程序的编译速度可以达到 Windows 下的数倍。根据我的经验，对于 LaTeX 项目，Linux 可以获得至少 5 倍的编译加速。"

下载安装镜像

到某个国内的 CTAN 镜像站下载最新版的 TeX Live 镜像，比如清华大学开源软件镜像站。

目前最新的 TeX Live 版本为 2026，该文件夹下包含 3 个 .iso 文件，这 3 个文件仅有文件名不同，内容完全相同，你可以任选一个下载。该文件夹下还包含有 md5 摘要文件，你也可以下载下来以备校验。

iso可以放在任意位置, 后文将使用挂载镜像的安装方式, 默认安装到/usr/local/texlive/2026

校验安装镜像

这一步是可选的，主要是检查下载过程中镜像有没有出现损坏，以及镜像是否被第三方篡改过。实际上现在的网络条件很好了，一般不会出问题的。如果从正规的镜像站下载，也不必担心篡改的问题。

在 Shell（如 bash）中切换到镜像所在的文件夹，然后执行

md5sum texlive2026.iso

md5 计算需要完整读取整个镜像文件，因此计算会持续一段时间，取决于你机器的运算速度和硬盘读取速度，请耐心等待。

你应该可以得到 TeX Live 2026 镜像文件的 md5 值 f5872cb2dec838670f91ed5c62493553。

挂载安装镜像

进入 Shell 并执行

sudo mkdir /mnt/texlive
sudo mount 你的镜像存放路径/texlive2026.iso /mnt/texlive

运行安装程序

sudo /mnt/texlive/install-tl

你应该能够看到如下内容：

======================> TeX Live installation procedure <=====================
 
======>   Letters/digits in <angle brackets> indicate   <=======
======>   menu items for actions or customizations      <=======
= help>   https://tug.org/texlive/doc/install-tl.html   <=======
 
 Detected platform: GNU/Linux on x86_64
 
 <B> set binary platforms: 1 out of 15
 
 <S> set installation scheme: scheme-full
 
 <C> set installation collections:
     40 collections out of 41, disk space required: 8779 MB (free: 970330 MB)
 
 <D> set directories:
   TEXDIR (the main TeX directory):
     /usr/local/texlive/2025
   TEXMFLOCAL (directory for site-wide local files):
     /usr/local/texlive/texmf-local
   TEXMFSYSVAR (directory for variable and automatically generated data):
     /usr/local/texlive/2025/texmf-var
   TEXMFSYSCONFIG (directory for local config):
     /usr/local/texlive/2025/texmf-config
   TEXMFVAR (personal directory for variable and automatically generated data):
     ~/.texlive2025/texmf-var
   TEXMFCONFIG (personal directory for local config):
     ~/.texlive2025/texmf-config
   TEXMFHOME (directory for user-specific files):
     ~/texmf
 
 <O> options:
   [ ] use letter size instead of A4 by default
   [X] allow execution of restricted list of programs via \write18
   [X] create all format files
   [X] install macro/font doc tree
   [X] install macro/font source tree
   [ ] create symlinks to standard directories
   [X] after install, set CTAN as source for package updates
 
 <V> set up for portable installation
 
Actions:
 <I> start installation to hard disk
 <P> save installation profile to 'texlive.profile' and exit
 <Q> quit
 
Enter command:

调整安装配置

这一节是可选的。实际上 TeX Live 中有许多组件是很少用的，为了节省磁盘空间，我们精简一些组件。如果你的硬盘足够大，不在乎空间占用，可以直接进入下一步。

这一节参考了 TeX Live宏包集合和自定义安装

TeX Live 的打包策略为体系（scheme）——集合（collection）——软件包/宏包三层。其中可定制安装的是集合层次。TeX Live 2025 包括了 41 个集合。针对这些集合的解释可以参考上面的链接，这里就不赘述了。

Linux 的安装路径不建议改，否则之后出问题查文档可能会雪上加霜。Windows 随意，但路径不能带有非 ASCII 字符，而且不要太深，否则容易出问题。

在安装程序中输入 C 并回车，进入安装组件定制页面。

===============================================================================
Select collections:
 
 a [X] Essential programs and files      w [X] Italian                         
 b [X] BibTeX additional styles          x [X] Japanese                        
 c [X] TeX auxiliary programs            y [X] Korean                          
 d [X] ConTeXt and packages              z [X] Other languages                 
 e [X] Additional fonts                  A [X] Polish                          
 f [X] Recommended fonts                 B [X] Portuguese                      
 g [X] Graphics and font utilities       C [X] Spanish                         
 h [X] Additional formats                D [X] LaTeX fundamental packages      
 i [X] Games typesetting                 E [X] LaTeX additional packages       
 j [X] Humanities packages               F [X] LaTeX recommended packages      
 k [X] Arabic                            G [X] LuaTeX packages                 
 l [X] Chinese                           H [X] MetaPost and Metafont packages  
 m [X] Chinese/Japanese/Korean (base)    I [X] Music packages                  
 n [X] Cyrillic                          J [X] Graphics, pictures, diagrams    
 o [X] Czech/Slovak                      K [X] Plain (La)TeX packages          
 p [X] US and UK English                 L [X] PSTricks                        
 s [X] Other European languages          M [X] Publisher styles, theses, etc.  
 t [X] French                            N [ ] Windows-only support programs   
 u [X] German                            O [X] XeTeX and packages              
 v [X] Greek                            
 P [X] Mathematics, natural sciences, computer science packages
 S [X] TeXworks editor; TL includes only the Windows binary
 
Actions: (disk space required: 8315 MB)
 <-> deselect all
 <+> select all
 <R> return to main menu
 <Q> quit
 
Enter letter(s) to (de)select collection(s):

输入集合对应的字母可以选中/取消选中。支持批量输入。可以不装的组件有：

d [ ] ConTeXt and packages
e [ ] Additional fonts		// 各种字体，空间大头
g [ ] Graphics and font utilities
i [ ] Games typesetting		// 排版游戏用的
j [ ] Humanities packages	// 人文科学类宏包，按需安装即可
E [ ] LaTeX additional packages		// 空间大头
H [ ] MetaPost and Metafont packages
I [ ] Music packages	// 排版乐谱用的
K [ ] Plain (La)TeX packages
L [ ] PSTricks		// 老旧技术
M [ ] Publisher styles, theses, etc.	// 各种学术、毕业论文模板，需要学术写作可以装一下
N [ ] Windows-only support programs		// linux不支持，默认取消勾选
S [ ] TeXworks editor; TL includes only the Windows binary

各种语言集合上面省略了，根据需要选择即可。如果不需要外语支持，语言类集合中仅选择 Chinese 和 Chinese/Japanese/Korean (base)、US and UK English 即可。

注意，如果需要中文支持，那么 Chinese 和 Chinese/Japanese/Korean (base)（这三种语言的首字母形成了有名的缩写：CJK）都是必不可少的。同理 Japanese 和 Korean 集合也都依赖 CJK base。

TeXworks 是一个简单的 LaTeX 编辑器，我们将会使用 VSCode 来编辑 LaTeX ，因此这个组件可以不装。另外只有 Windows 平台提供有编译好的二进制文件，Linux 平台估计要手动编译。

即使有些宏包在上面精简了，后期仍然可以使用 tlmgr 工具来单独安装它们。因此不用太担心。

我把可以不装的包的序号写在下面，可以直接复制粘贴然后回车：

deghijkstuvwxyznoABCEHIKLMNS

我这里经过一番精简后，原本需要的 8779 MB 空间精简到了 2713 MB。

这样精简之后，编译有些模板时可能会报错说找不到宏包。此时可以使用tlmgr 从 CTAN 单独安装它们。

确认无误后，输入 R 并回车，回到主界面。

使用

参考链接：

官方文档: 一份(不太)简短的 LaTeX 2ε 介绍.pdf（推荐，非常详细）
本站镜像: 一份(不太)简短的 LaTeX 2ε 介绍.pdf（网络不佳时可用）

从一个最小骨架开始

任何 LaTeX 文档都由两部分组成：导言区（preamble，\documentclass 到 \begin{document} 之间）和正文区（body，\begin{document} 到 \end{document} 之间）。导言区负责全局设置、加载宏包；正文区负责实际内容。

最精简的文档长这样——已经可以编译了：

\documentclass[oneside]{ctexart}
\title{Hello, \LaTeX!}
\author{Mint}
\date{\today}

\begin{document}
\maketitle
Hello, \LaTeX{}! 这是我的第一篇 \LaTeX{} 文档。
\end{document}

这里选择了 ctexart 文档类（CTeX 提供的 article 中文适配版），选项 oneside 表示单面打印——如果写计划书、课程报告，单面就够用；写论文需要双面打印时换成 twoside。

导言区：加载你需要的宏包

LaTeX 的核心理念是"按需加载"——用到什么功能，就 \usepackage 引入对应的宏包。以下是我在计划书撰写中最常用的几个：

宏包	用途	一句话说明
`zhlipsum`	生成中文占位文字	写草稿时填充内容看排版效果
`graphicx`	插入图片	支持 png/jpg/pdf，`\includegraphics`
`booktabs`	学术风格三线表	提供 `\toprule` `\midrule` `\bottomrule`
`caption`	自定义图表标题	控制标题与内容的间距
`fancyhdr`	自定义页眉页脚	比默认页面风格灵活得多
`hyperref`	超链接与 PDF 书签	目录、引用自动变成可点击链接

\usepackage{zhlipsum}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{caption}
\usepackage{fancyhdr}
\usepackage[bookmarksnumbered=true, colorlinks=true, linkcolor=black]{hyperref}

% 单栏文档（默认就是单栏，显式声明更清晰）
\onecolumn

% 表格标题与上方内容的间距
\captionsetup[table]{skip=10pt}

小提示：hyperref 通常放在导言区最后加载，避免与其他宏包冲突。colorlinks=true 让链接有颜色但不加框；linkcolor=black 让目录和交叉引用的链接变成黑色，打印友好。

页眉页脚：用 fancyhdr 自定义

默认的 LaTeX 页眉只有章节名和页码，用 fancyhdr 可以自由定制。下面定义了一个 myfancy 页面风格——页眉左中右分别显示章节名、文章标题、小节名，页脚居中显示页码：

\fancypagestyle{myfancy}{%
    \pagestyle{fancy}
    \lhead{\leftmark}        % 页眉左：当前章节（section）名
    \chead{\thetitle}        % 页眉中：文章标题
    \rhead{\rightmark}       % 页眉右：当前小节（subsection）名
    \lfoot{}                 % 页脚左：留空
    \cfoot{\thepage}         % 页脚中：页码
    \rfoot{}                 % 页脚右：留空
}

\leftmark 和 \rightmark 是 LaTeX 自动维护的标记——章节标题会自动填入。但是 \chead{\thetitle} 需要我们自己定义 \thetitle 变量，详见下文"标题页"一节。

fancyhdr 对页眉高度有要求。如果编译时警告"headheight is too small"，加上这两行即可：

\setlength{\headheight}{12.64723pt}
\addtolength{\topmargin}{-0.64723pt}

正式文档通常让标题页和目录页不显示页眉，所以在导言区最后把默认页面风格设为 empty：

\pagestyle{empty}

等到正文开始再切换到 \pagestyle{myfancy}。

正文区：从标题页到致谢

下面按顺序讲解正文区的每一个部分。

1. 标题页

\begin{document}
\makeatletter
\let\thetitle\@title   % 把内部变量 \@title 的值保存到自定义命令 \thetitle
\makeatother

\maketitle

\@title 是 LaTeX 内部存储标题的变量，正常情况不能在导言区外直接访问。\makeatletter / \makeatother 之间的代码可以"借用"内部命令，把标题值捕获到 \thetitle，供后续页眉使用。

\maketitle 生成标题区域，包含标题、作者、日期。

2. 摘要与目录（前导页）

正式文档的前几页通常用罗马数字页码，与正文的阿拉伯数字页码区分：

\section*{摘要}
\pagenumbering{Roman}
\addcontentsline{toc}{section}{摘要}
Hello, \LaTeX{}! 这是我的第一篇 \LaTeX{} 文档。

\zhlipsum[1-3]    % 占位文字，写正式内容时删掉

\newpage
\thispagestyle{empty}
\tableofcontents    % 生成目录
\listoffigures      % 生成插图清单（可选）
\listoftables       % 生成表格清单（可选）

命令	说明
`\section*{摘要}`	带 `*` 的章节不会自动编号，也不会进入目录
`\addcontentsline{toc}{section}{摘要}`	手动把"摘要"加入目录
`\pagenumbering{Roman}`	页码切换为罗马数字
`\tableofcontents`	自动从章节标题生成目录
`\thispagestyle{empty}`	当前页（目录页）不显示页眉页脚

提示：\zhlipsum[1-3] 生成第 1~3 段中文占位文字，方便预览排版效果。写正式内容时删掉即可。

3. 进入正文

\cleardoublepage          % 确保正文从奇数页开始
\pagestyle{myfancy}       % 切换到自定义页眉页脚
\setcounter{page}{1}      % 页码重置为 1
\pagenumbering{arabic}    % 切换为阿拉伯数字

\cleardoublepage 对于双面打印很重要——它保证新的一章始终从右页（奇数页）开始。如果只写电子版文档，用 \newpage 也可以。

4. 章节层级

LaTeX 的章节命令从高到低依次为：

\section{一级标题}
  \subsection{二级标题}
    \subsubsection{三级标题}

编号自动递增，目录也自动更新。写计划书时，一般用 \section 划分大板块（市场分析、财务预测等），\subsection 细分具体内容。

5. 插入图片

\begin{figure}[htbp]
    \centering
    \includegraphics[width=0.8\textwidth]{img/ba.png}
    \caption{示例图片}\label{fig:example}
\end{figure}

如图~\ref{fig:example}所示，这是一个示例图片。

逐行解释：

代码	说明
`\begin{figure}[htbp]`	浮动体环境，`[htbp]` 控制图片放置优先级：here→top→bottom→单独一页
`\centering`	图片居中
`\includegraphics[width=0.8\textwidth]{...}`	插入图片，宽度为页面文字宽度的 80%，高度等比例缩放
`\caption{...}`	图片标题，自动编号
`\label{fig:example}`	给图片贴标签，供交叉引用
`\ref{fig:example}`	引用标签，编译后自动替换为对应编号
`~`	不可断行空格，防止"如图"和"1"分处两行

浮动体是 LaTeX 的一大特色——图片和表格不会死板地卡在代码位置，而是浮动到排版最优的地方。用 [htbp] 可以调整浮动偏好；如果坚持"图片就要在这里"，可以用 [H]（需加载 float 宏包）。

6. 插入表格

\begin{table}[htbp]
    \centering
    \caption{示例表格}\label{tab:example}
    \begin{tabular}{ccc}
        \toprule
        列1 & 列2 & 列3 \\
        \midrule
        数据1 & 数据2 & 数据3 \\
        \bottomrule
    \end{tabular}
\end{table}

代码	说明
`\begin{tabular}{ccc}`	三列均居中（c=center），换成 `l` 左对齐、`r` 右对齐
`\toprule`	表格顶部粗线（booktabs 宏包提供）
`\midrule`	表头与数据之间的细线
`\bottomrule`	表格底部粗线
`&`	列分隔符
`\\`	行分隔符

三线表是学术写作的标准格式，简洁干净。booktabs 宏包提供的就是这种风格，比 LaTeX 默认的 \hline 好看得多。

交叉引用表格的语法与图片完全一致：\label{tab:xxx} 贴标签，\ref{tab:xxx} 引用。建议用前缀区分类型——fig: 表示图，tab: 表示表，eq: 表示公式。

7. 致谢

\newpage
\thispagestyle{empty}
\section*{致谢}
\addcontentsline{toc}{section}{致谢}
感谢所有支持我的人！

\end{document}

和摘要一样，\section* 确保不自动编号，\addcontentsline 手动加入目录。

完整模板

把以上所有片段组合起来，就是一份可以直接编译的计划书模板：

\documentclass[oneside]{ctexart}
\title{Hello, \LaTeX!}
\author{Mint}
\date{\today}

\usepackage{zhlipsum}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{caption}
\usepackage{fancyhdr}
\usepackage[bookmarksnumbered=true, colorlinks=true, linkcolor=black]{hyperref}

\onecolumn
\captionsetup[table]{skip=10pt}

\fancypagestyle{myfancy}{%
    \pagestyle{fancy}
    \lhead{\leftmark}
    \chead{\thetitle}
    \rhead{\rightmark}
    \lfoot{}
    \cfoot{\thepage}
    \rfoot{}
}
\setlength{\headheight}{12.64723pt}
\addtolength{\topmargin}{-0.64723pt}
\pagestyle{empty}

\begin{document}
\makeatletter
\let\thetitle\@title
\makeatother

\maketitle

\section*{摘要}
\pagenumbering{Roman}
\addcontentsline{toc}{section}{摘要}
Hello, \LaTeX{}! 这是我的第一篇 \LaTeX{} 文档。

\zhlipsum[1-3]

\newpage
\thispagestyle{empty}
\tableofcontents
\listoffigures
\listoftables

\cleardoublepage
\pagestyle{myfancy}
\setcounter{page}{1}
\pagenumbering{arabic}

\section{第一章}
\subsection{概述}
\subsubsection{如何xxx}

\begin{figure}[htbp]
    \centering
    \includegraphics[width=0.8\textwidth]{img/ba.png}
    \caption{示例图片}\label{fig:example}
\end{figure}

如图~\ref{fig:example}所示，这是一个示例图片。

\zhlipsum[1-4]

\subsubsection{然后xxx}
\zhlipsum[1-4]

\begin{table}[htbp]
    \centering
    \caption{示例表格}\label{tab:example}
    \begin{tabular}{ccc}
        \toprule
        列1 & 列2 & 列3 \\
        \midrule
        数据1 & 数据2 & 数据3 \\
        \bottomrule
    \end{tabular}
\end{table}
如表~\ref{tab:example}所示，这是一个示例表格。

\zhlipsum[1-8]

\newpage
\thispagestyle{empty}
\section*{致谢}
\addcontentsline{toc}{section}{致谢}
感谢所有支持我的人！

\end{document}

使用提示：复制模板后，把 \zhlipsum[...] 替换成你的实际内容，调整图片路径，修改章节标题——一份格式规范的计划书就出来了。后续协作时，团队成员只需要关注正文内容，格式由 LaTeX 自动搞定，再也不用反复手动排版了。

ESP32 并发 TLS 握手导致间歇性连接失败的排查与优化

Sun, 29 Mar 2026 00:00:00 GMT

环境: ESP-IDF v5.5 / ESP32 (4MB PSRAM) / mbedTLS
现象: HTTPS POST 传感器数据时随机出现 PK verify failed with error 0x4290，但同一请求有时成功有时失败
根因: 多任务并发 TLS 握手争抢内部 SRAM，RSA 签名验证因内存不足而失败
修复: HTTP 连接持久化复用 + 请求重试

一、问题现象

设备运行期间，传感器数据每 60 秒上报一次，日志中周期性出现以下错误：

E esp-x509-crt-bundle: PK verify failed with error 0x4290
E esp-x509-crt-bundle: Certificate matched but signature verification failed
E esp-x509-crt-bundle: Failed to verify certificate
E esp-tls-mbedtls: mbedtls_ssl_handshake returned -0x3000
E esp-tls: Failed to open new connection
E HTTP_CLIENT: Connection failed, sock < 0

奇怪的是，同一个接口、同样的数据、同一台服务器——上一分钟还成功返回 200，下一分钟就 TLS 握手失败。跟服务器证书本身没有关系（证书有效期内，其他时段正常）。

二、系统架构与并发模型

设备上同时运行着多个需要 HTTPS 的任务：

┌─────────────────────┐     ┌──────────────────────┐     ┌──────────────────┐
│  remote_log (rlog)  │     │ sensor_data_transmit │     │   websocket_task │
│  每 ~1s POST 日志    │     │  每 60s POST 传感器   │     │   持久 WSS 连接   │
│  独立 HTTP client   │     │  全局 HTTP client     │     │                  │
└────────┬────────────┘     └────────┬─────────────┘     └──────────────────┘
         │                           │
         ▼                           ▼
   ┌───────────┐              ┌───────────┐
   │ TLS 握手   │              │ TLS 握手  │
   │ (mbedTLS) │              │ (mbedTLS) │
   └─────┬─────┘              └─────┬─────┘
         │                          │
         ▼                          ▼
   ┌────────────────────────────────────────┐
   │        ESP32 内部 SRAM (~307 KB)        │
   │     空闲仅 35~70 KB (11%~22%)           │
   └────────────────────────────────────────┘

关键数据来自健康监控日志：

[内存] 堆=3318188/4501391B(73%) 最低=3279536B
       内部=35691/307087B(11%) | PSRAM=3285836/4194304B(78%)

虽然总堆空间（含 PSRAM）还剩 73%，但内部 SRAM 只剩 11%（~35KB）。而 mbedTLS 的密钥运算必须使用内部 SRAM（不能用 PSRAM），一次 TLS 握手的 RSA 签名验证临时需要 20~40KB 内部 SRAM。

三、根因分析

3.1 旧代码：每次 flush 都新建 TLS 连接

修改前的 remote_log_http_post() 实现：

// ❌ 旧代码：每次调用都 init → TLS握手 → perform → close → cleanup
static esp_err_t remote_log_http_post(const char *data, int len)
{
    esp_http_client_config_t cfg = {
        .url = s_upload_url,
        .method = HTTP_METHOD_POST,
        .crt_bundle_attach = esp_crt_bundle_attach,
        .keep_alive_enable = true,   // 虽然开了 keep-alive，但...
    };

    // 每次都创建新 client
    esp_http_client_handle_t client = esp_http_client_init(&cfg);
    
    esp_http_client_set_header(client, "Content-Type", "text/plain");
    esp_http_client_set_header(client, "Authorization", s_secret);
    esp_http_client_set_post_field(client, data, len);
    
    // perform 内部会做完整 TLS 握手（TCP → TLS → HTTP）
    esp_err_t err = esp_http_client_perform(client);

    // 用完直接销毁
    esp_http_client_close(client);
    esp_http_client_cleanup(client);  // ← 连接和 TLS 上下文全部释放
    return err;
}

问题：虽然配置了 keep_alive_enable = true，但每次调用结束都 cleanup 销毁了 client 对象，下次调用只能重新创建、重新握手。keep_alive 形同虚设。

由于 flush 任务每秒运行一次，这意味着每秒都会进行一次完整的 TLS 握手。

3.2 时间线碰撞

时间轴 ──────────────────────────────────────►

rlog:   [TLS握手][TLS握手][TLS握手]...[TLS握手][TLS握手]...
               每 ~1-2 秒一次             ↑
                                         │ 恰好重叠
sensor:                                  │
         ────────── 60s ────────── [TLS握手] ← 失败!

每分钟总有一次传感器 POST 的 TLS 握手和 rlog 的握手时间重叠。两个并发握手同时向内部 SRAM 申请临时缓冲区：

资源	需求
一次 TLS 握手 RSA 验签	~20-40 KB
内部 SRAM 空闲	~35-70 KB
两次并发握手总需求	~40-80 KB

当内部 SRAM 处于低位（35KB）时，两个并发握手总需求超过可用空间，后发起的那个就会在 RSA 签名验证阶段因 malloc 失败而报错 0x4290。

3.3 为什么"有时成功有时失败"?

这是概率性的，取决于两个条件：

时间是否重叠：rlog 每 ~1s 一次握手，sensor 每 60s 一次。两者碰撞概率大约 30-50%（取决于握手耗时 ~0.5-1s）
内部 SRAM 当时的空闲量：其他任务（WiFi、WebSocket、Camera）的内存占用是波动的，空闲量在 35-70KB 间浮动

两个条件同时满足（重叠 + 内存低位）时失败，否则成功。

四、修复方案

4.1 核心修复：HTTP 连接持久化复用

// ✅ 新代码：持久化 client，复用 TLS 连接
static esp_http_client_handle_t s_persistent_client = NULL;

static esp_http_client_handle_t rlog_get_client(void)
{
    if (s_persistent_client != NULL) {
        return s_persistent_client;  // 直接返回已有 client
    }

    // 仅首次（或重建时）创建
    esp_http_client_config_t cfg = {
        .url = s_upload_url,
        .method = HTTP_METHOD_POST,
        .timeout_ms = RLOG_HTTP_TIMEOUT_MS,
        .crt_bundle_attach = esp_crt_bundle_attach,
        .buffer_size = 1024,
        .keep_alive_enable = true,
    };

    s_persistent_client = esp_http_client_init(&cfg);
    if (s_persistent_client != NULL) {
        esp_http_client_set_header(s_persistent_client, "Content-Type", "text/plain");
        esp_http_client_set_header(s_persistent_client, "Authorization", s_secret);
    }
    return s_persistent_client;
}

static esp_err_t remote_log_http_post(const char *data, int len)
{
    esp_http_client_handle_t client = rlog_get_client();
    if (client == NULL) return ESP_FAIL;

    esp_http_client_set_post_field(client, data, len);

    // perform 在 keep-alive 连接上直接发 HTTP 请求，无需 TLS 握手
    esp_err_t err = esp_http_client_perform(client);

    if (err != ESP_OK) {
        // 连接断开时销毁，下次调用会自动重建
        ESP_LOGW(TAG, "持久连接失败, 将重建: %s", esp_err_to_name(err));
        rlog_destroy_client();
    }
    // 注意：成功时不 close/cleanup，连接保持
    return err;
}

4.2 关键区别对比

维度	旧代码（每次新建）	新代码（持久复用）
client 生命周期	每次 flush 创建并销毁	首次创建，长期持有
TLS 握手频率	每秒 1 次	仅首次 + 断线重连
内部 SRAM 峰值	每秒出现 20-40KB 尖峰	稳态仅 ~5KB（TLS 上下文）
与 sensor 任务碰撞概率	~30-50%	≈0%（几乎无握手）
`Certificate validated` 日志	每 2 秒一条（刷屏）	仅启动时 1 条
网络开销	每次 TCP+TLS 三次握手	HTTP keep-alive 复用

4.3 `esp_http_client_perform` 的内部行为

理解这个修复的关键在于 esp_http_client_perform() 的内部逻辑：

esp_http_client_perform(client)
    │
    ├── 连接未建立？
    │   ├── DNS 解析
    │   ├── TCP connect (三次握手)
    │   ├── TLS handshake ← 内存密集操作!
    │   │   ├── ClientHello → ServerHello
    │   │   ├── 服务器证书验证 (x509 bundle)
    │   │   ├── RSA/ECDSA 签名验证 ← 需要 20-40KB 内部 SRAM
    │   │   └── 密钥交换 → Finished
    │   └── 连接就绪
    │
    ├── 连接已建立且 keep-alive？
    │   └── 直接跳到 HTTP 请求 ← 零额外内存开销!
    │
    ├── 发送 HTTP 请求
    ├── 接收 HTTP 响应
    └── 返回结果

旧代码每次都走左边分支（完整握手），新代码只有首次走左边，后续全部走右边（直接发请求）。

4.4 辅助修复：传感器 POST 增加重试

即使持久化连接大幅降低了碰撞概率，极端情况下仍可能遇到（比如持久连接断线重建时恰好碰上 sensor POST）。因此增加重试兜底：

#define SENSOR_POST_MAX_RETRY   3
#define SENSOR_POST_RETRY_MS    3000  // 重试间隔 3 秒

// 带重试的 HTTPS POST
int ret_code = ESP_FAIL;
for (int attempt = 0; attempt < SENSOR_POST_MAX_RETRY; attempt++) {
    ret_code = WifiSecurityRequest("https://lark.mintlab.top",
                                   "/api/sensors", 443,
                                   WS_CLINENT_METHOD_POST, post_data, NULL);
    if (ret_code == ESP_OK) break;
    
    ESP_LOGW(TAG, "传感器上报失败 (%d/%d), %dms 后重试...",
             attempt + 1, SENSOR_POST_MAX_RETRY, SENSOR_POST_RETRY_MS);
    vTaskDelay(pdMS_TO_TICKS(SENSOR_POST_RETRY_MS));
}

3 秒的重试间隔不是随意选的——它足够让另一个 TLS 握手完成并释放内部 SRAM。

五、实测验证

部署修复后的固件 (v0.7.1)，通过 OTA 升级并观察日志。

5.1 启动阶段：仍有碰撞，但重试兜住了

OTA 重启后，前 5 秒内 OTA 检查、rlog 首次 flush、sensor 首次 POST 三个任务几乎同时发起 TLS 握手：

(5050) ota:     Checking for firmware update    → TLS 握手
(5070) sensor:  POST /api/sensors               → TLS 握手
(5070) rlog:    首次 flush                       → TLS 握手（持久 client 首次创建）

sensor 的前两次握手失败（0x4290 和 0x7F00），第三次重试成功——此时 OTA 和 rlog 已完成握手释放了内部 SRAM：

(5240)  task: 传感器上报失败 (1/3), 3000ms 后重试...
(8320)  task: 传感器上报失败 (2/3), 3000ms 后重试...
(12190) http_client: POST .../api/sensors -> 200  ✅ 第三次成功

重试机制达到预期效果。

为进一步消除启动碰撞，在 sensor 任务入口增加 5 秒延迟，错开与 OTA/rlog 的首次握手窗口：

void sensor_data_transmit_task(void *pvParameter)
{
    // 启动后延迟 5 秒，错开 OTA/rlog 首次 TLS 握手的内存高峰
    vTaskDelay(pdMS_TO_TICKS(5000));
    // ...
}

5.2 稳态运行：问题彻底消除

启动阶段过后，对比效果显著：

指标	修复前 (v0.7.0)	修复后 (v0.7.1)
`Certificate validated` 频率	每 ~2 秒一条（刷屏）	启动后消失
sensor POST 成功率	~60-70%（每分钟偶发失败）	100%（稳态零重试）
rlog `consec_fail`	偶发 1+	稳定 0
rlog stats 间隔	~20 秒（退避中）	~10 秒（正常，无退避）

关键证据——稳态下 Certificate validated 日志完全消失，证明 rlog 持久连接复用生效，不再每秒做 TLS 握手：

00:29:28  remote_log: [stats] sent=6746 B, consec_fail=0
00:29:38  remote_log: [stats] sent=6879 B, consec_fail=0   ← +133B, 无握手
00:29:48  remote_log: [stats] sent=7012 B, consec_fail=0   ← +133B, 无握手
00:30:22  http_client: POST .../api/sensors -> 200          ← 一次成功，无重试

5.3 实际数据对比

TLS 握手次数：

修复前: ~1次/秒 × 3600秒/小时 = 3600 次/小时
修复后: 1次/启动 + 偶发重建 ≈ 1-5 次/小时
减少: 99.9%

内部 SRAM（来自 sys_mon 实测）：

修复前: 内部=35691/307087B (11%)  ← TLS 握手后的谷值
修复后: 内部=38731/307079B (12%)  ← 稳态值，无尖峰波动

稳态下内部 SRAM 不再出现周期性尖峰，彻底消除了并发碰撞的条件。

六、经验总结

6.1 `keep_alive_enable = true` 不是万能的

ESP-IDF 的 keep_alive_enable 只是在 HTTP 层面告诉服务器"不要关闭连接"，但如果你在客户端代码里每次都 cleanup 销毁了 client 对象，keep-alive 就毫无意义——对象都没了，哪来的连接可以复用？

正确用法: 创建一次 client，多次调用 perform，只在不再需要时 cleanup。

6.2 ESP32 的"两种内存"陷阱

ESP32 有 PSRAM 时总堆空间看起来很大（4.5MB），但 mbedTLS 加密运算只能用内部 SRAM（~307KB），而系统本身（WiFi、freeRTOS、任务栈等）已占用大部分。实际可用于 TLS 握手的空间非常紧张。

esp_get_free_heap_size() 返回的数字包含 PSRAM，容易给人"内存充裕"的错觉。排查 TLS 问题时要看 heap_caps_get_free_size(MALLOC_CAP_INTERNAL)。

6.3 间歇性 TLS 失败的排查思路

当 TLS 握手"有时成功有时失败"时：

不是证书问题——证书问题是 100% 失败，不会间歇
不是网络问题——网络问题表现为超时，不是签名验证失败
大概率是内存问题——特别是 PK verify failed，说明 RSA 运算分配不到足够内存
检查并发——找出所有同时做 TLS 的任务，计算峰值内存需求

6.4 连接复用是嵌入式 HTTPS 的最佳实践

在资源受限的嵌入式设备上，每个 TLS 连接的建立成本很高：

成本维度	数值
时间	1-3 秒（含 TCP + TLS 握手）
内部 SRAM 峰值	20-40 KB
CPU	RSA-2048 验签约 0.5-1 秒

对于周期性请求同一服务器的场景，连接复用应该是默认选择，而不是每次新建。

SQLite 性能优化实战：从 70ms 到 1ms 的日志写入之旅

Sat, 28 Mar 2026 00:00:00 GMT

背景

Lark 是一个 ESP32 物联网监控平台，嵌入式端通过 HTTP POST 每秒批量上报 ESP_LOG 日志到 FastAPI 后端，存入 SQLite。

在优化前，日志上报接口的处理时间波动很大：

POST /api/logs - 200 OK - 处理时间: 74.46ms
POST /api/logs - 200 OK - 处理时间: 28.54ms
POST /api/logs - 200 OK - 处理时间: 17.43ms
POST /api/logs - 200 OK - 处理时间: 71.78ms
POST /api/logs - 200 OK - 处理时间: 78.86ms

平均约 40ms，峰值接近 80ms。对于一个简单的日志写入操作来说，这个速度显然不正常。

一、SQLite Journal Mode 详解

SQLite 通过 日志(Journal) 机制保证事务的原子性——要么完全提交，要么完全回滚。journal_mode 控制的就是这个日志的工作方式。

1.1 DELETE 模式（默认）

PRAGMA journal_mode = DELETE;

这是 SQLite 的默认模式，工作流程：

写入事务开始
  ├─ 1. 创建 rollback journal 文件（.db-journal）
  ├─ 2. 将要修改的原始页拷贝到 journal 文件
  ├─ 3. fsync journal 文件 → 确保落盘
  ├─ 4. 修改数据库文件中的页
  ├─ 5. fsync 数据库文件 → 确保落盘
  └─ 6. 删除 journal 文件  → 事务完成标志

关键痛点：每次 commit 需要 2 次 fsync（步骤 3 和 5）。fsync 是告诉操作系统"把内存缓冲区的数据真正写入物理磁盘"，这是整个流程中最慢的操作。在 HDD 上一次 fsync 约 10-30ms，SSD 上约 1-10ms。

读写互斥：写事务持有排他锁期间，所有读操作被阻塞。

1.2 WAL 模式（Write-Ahead Logging）

PRAGMA journal_mode = WAL;

WAL 彻底反转了写入逻辑：

                      ┌──────────────┐
                      │  数据库文件    │  ← 只读（checkpoint 时才写入）
                      │  .db         │
                      └──────────────┘
                             ▲
                             │ checkpoint（批量回写）
                             │
┌──────────────┐      ┌──────────────┐
│  共享内存索引  │ ←──→ │  WAL 日志文件  │ ← 所有写入先到这里
│  .db-shm     │      │  .db-wal     │
└──────────────┘      └──────────────┘

WAL 的写入流程：

写入事务开始
  ├─ 1. 将修改后的页 追加(append) 到 WAL 文件末尾
  ├─ 2. fsync WAL 文件（取决于 synchronous 设置）
  └─ 3. 完成 ← 没有第二次 fsync，没有删除操作

核心优势：

特性	DELETE	WAL
写入操作	拷贝原始页 → 修改 → 删除 journal	追加新页到 WAL 尾部
fsync 次数	2 次	0~1 次
读写并发	写阻塞读	读写互不阻塞
文件操作	每次创建/删除 journal	追加写入（顺序 I/O）

为什么 WAL 更快？

顺序写入 vs 随机写入：WAL 只做 append，磁盘顺序 I/O 比随机 I/O 快 10-100 倍
单次 fsync vs 两次：减少一半的磁盘同步等待
无文件创建/删除：省去了 journal 文件的 create/unlink 系统调用

WAL 的 Checkpoint 机制：

WAL 文件不会无限增长。当 WAL 达到 wal_autocheckpoint（默认 1000 页 ≈ 4MB）时，SQLite 自动将 WAL 中的修改回写到数据库主文件。这个过程叫 checkpoint，通常在读操作时顺带完成，不影响写入性能。

1.3 其他模式（简要）

模式	特点
TRUNCATE	类似 DELETE，但截断 journal 而非删除（省一次 unlink 系统调用）
PERSIST	journal 文件创建后不删除，header 置零表示无效（省 create + unlink）
MEMORY	journal 存在内存中，断电即丢（不安全，仅测试用）
OFF	不创建 journal（无事务保护，极端场景才用）

对于服务端应用，WAL 是绝大多数场景的最优选择。

二、Synchronous 级别详解

synchronous 控制 SQLite 调用 fsync 的频率，直接影响"数据安全性 vs 写入速度"的权衡。

PRAGMA synchronous = FULL | NORMAL | OFF;

各级别对比

FULL（默认值 = 2）

每次 commit:
  → fsync journal/WAL 文件  ✓
  → fsync 数据库文件         ✓

最安全：即使操作系统崩溃或突然断电，数据库也不会损坏，不会丢失已提交的事务。代价是每次写入都要等磁盘完成物理写入。

NORMAL（值 = 1）

每次 commit:
  → fsync WAL 文件          ✓（关键时刻才做）
  → fsync 数据库文件         ✗（交给 OS 决定何时刷盘）

在 WAL 模式下的安全性分析：

进程崩溃（segfault / kill）：不丢数据 ✓ —— OS 缓冲区会自动刷盘
操作系统崩溃（内核 panic）：可能丢失最后一个事务 —— OS 缓冲区中未刷盘的数据丢失
断电：可能丢失最后一个事务 —— 同上
数据库损坏：不会 ✓ —— WAL 的校验和机制保护完整性

💡 关键理解：NORMAL 在 WAL 模式下，丢的只是"最后一个未刷盘的事务"，数据库完整性始终有保障。对于 IoT 日志场景，丢失一条日志完全可接受。

OFF（值 = 0）

每次 commit:
  → fsync journal/WAL 文件  ✗
  → fsync 数据库文件         ✗

最快但最危险：完全不调用 fsync，任何非正常关机都可能导致数据库损坏。生产环境不推荐。

直觉理解

       安全性                     速度
 ◄─────────────────────────────────────────►
 OFF          NORMAL              FULL
 │             │                    │
 不 fsync      关键时刻 fsync       每次都 fsync
 断电可损坏    断电丢最后1个事务     绝对不丢
 ~0.1ms       ~1ms                 ~10-70ms

三、ORM 层优化：bulk_insert_mappings

SQLAlchemy 的标准 add_all() 会为每个对象维护 identity map（身份映射），跟踪对象状态变化。这对日志这种"写入后不再修改"的场景是纯浪费。

# 优化前：add_all — 创建 ORM 对象 + identity map 跟踪
entries = []
for item in parsed:
    entries.append(M_DeviceLog(
        device_id=device_id,
        timestamp=timestamp,
        level=item["level"],
        ...
    ))
db.add_all(entries)  # 每个对象进入 Session 跟踪
db.commit()

# 优化后：bulk_insert_mappings — 直接插入字典，跳过 ORM 跟踪
mappings = [
    {
        "device_id": device_id,
        "timestamp": timestamp,
        "level": item["level"],
        ...
    }
    for item in parsed
]
db.bulk_insert_mappings(M_DeviceLog, mappings)  # 直接生成 INSERT 语句
db.commit()

bulk_insert_mappings 跳过了：

对象实例化（不创建 Python ORM 对象）
Identity map 注册（不跟踪对象状态）
属性事件触发（不触发 attribute event）

对于批量插入场景，性能提升约 2-5 倍。

四、实际优化效果

项目配置

# Db.py — SQLAlchemy 引擎配置
from sqlalchemy import create_engine, event

engine = create_engine(
    "sqlite:///../database/lark.db",
    connect_args={"check_same_thread": False}
)

@event.listens_for(engine, "connect")
def _set_sqlite_pragma(dbapi_conn, connection_record):
    cursor = dbapi_conn.cursor()
    cursor.execute("PRAGMA journal_mode=WAL")
    cursor.execute("PRAGMA synchronous=NORMAL")
    cursor.close()

基准测试结果

测试环境：Linux, SQLite 3.x, SSD

单条日志写入（50 次取样）：

指标	优化前 (DELETE + FULL)	优化后 (WAL + NORMAL)
最小值	~17ms	0.15ms
平均值	~40ms	0.95ms
最大值	~79ms	18.93ms（首次冷启动）

6 条日志批量写入（50 次取样）：

指标	优化后 (WAL + NORMAL + bulk_insert)
最小值	0.21ms
平均值	0.27ms
最大值	0.52ms

平均写入延迟从 40ms 降至不到 1ms，提升约 40 倍。

数据库文件变化

优化前:
  lark.db           360K    ← 数据库主文件
  lark.db-journal   (临时)  ← 每次写入创建/删除

优化后:
  lark.db           360K    ← 数据库主文件（checkpoint 时更新）
  lark.db-shm        32K    ← 共享内存索引（WAL 读取加速）
  lark.db-wal       4.0M    ← WAL 日志（自动 checkpoint 回收）

五、适用场景总结

场景	推荐配置	理由
IoT 日志 / 传感器数据	WAL + NORMAL	高频写入，偶尔丢一条可接受
用户账号 / 配置数据	WAL + FULL	低频写入，数据不能丢
金融交易 / 订单	WAL + FULL（或用 PostgreSQL）	必须绝对安全
临时缓存 / 测试	WAL + OFF 或 MEMORY	速度优先，数据不重要

六、注意事项

WAL 模式是持久的：设置一次后写入数据库文件头，下次打开自动生效。但 synchronous 需要每次连接时设置。
网络文件系统不兼容：WAL 依赖共享内存（mmap），NFS/SMB 上不能用 WAL 模式。
WAL 文件增长：高频写入时 .db-wal 可能增长，但 wal_autocheckpoint（默认 1000 页 ≈ 4MB）会自动回收。
备份注意：备份 SQLite 数据库时，必须同时复制 .db、.db-shm、.db-wal 三个文件，或使用 VACUUM INTO 命令。
只读场景无收益：WAL 主要优化写入性能，纯读场景两种模式差异不大。

Lark 项目的完整优化还包括日志解析改造：将 ESP32 批量文本拆分为单条存储，自动解析日志等级(E/W/I/D/V)、组件标签(tag)、设备 tick，支持按等级/标签/时间范围检索。这属于业务层改造，不在本文讨论范围。

ESP32 日志远程传输系统：从设计到实现

Sat, 28 Mar 2026 00:00:00 GMT

基于 ESP-IDF v5.x + FreeRTOS，运行于 ESP32 平台。

一、核心需求

在动手写代码之前，先明确这个系统必须满足的四个硬约束：

约束	说明
零侵入	不修改业务代码中的任何 `ESP_LOGx` 调用，对现有代码完全透明
不阻塞	日志上传绝不能影响主业务（摄像头帧传输、传感器采集）
不丢关键日志	WiFi 连接前的启动日志（最有诊断价值）也要尽量捕获
网络容错	断网、超时时优雅降级，不崩溃、不阻塞、不狂刷请求

最终实现的架构一句话概括：vprintf 钩子拦截所有日志 → 写入 16KB 环形缓冲区 → 独立任务每秒通过 HTTP POST 批量上传。

下面从方案选型开始，逐步展开每个设计决策背后的思考。

二、方案演进：从 WebSocket 到 HTTP POST

2.1 初始方案：WebSocket 传输

最初的设计是新开一个独立的 WebSocket 连接专门传输日志：

ESP_LOGx ──► vprintf 钩子
               ├── 串口输出
               └── 环形缓冲区
                      │
                flush 任务 (每 1s)
                      │
                独立 WS 连接 ──► /api/stream/device/log

为什么必须「独立」WS，而不是复用现有连接？

项目中已有一个 WS 连接用于传输摄像头视频帧，buffer_size = 64KB，发送使用 portMAX_DELAY（无限阻塞等待缓冲区可用）。如果日志和视频帧共用同一连接：

视频帧很大，占满发送缓冲区时，日志发送被阻塞——违反「不阻塞」约束
日志写入反过来也会抢占缓冲区，干扰帧率

所以即便用 WS，也必须是独立连接。但分析到这一步之后，WS 方案本身的问题也浮出水面了：

问题	说明
内存开销	多一个 WS client 常驻内存 ~10KB RAM，ESP32 本就紧张
重连逻辑	断线后需要处理重连、状态恢复，代码复杂度上升
优势浪费	WS 的长连接优势在高频通信（>10次/秒）时才明显，1 秒 1 次完全用不上
后端复杂度	需要维护 WS 会话状态，不方便水平扩展

2.2 最终方案：HTTP POST 传输

1 秒 1 次的频率，HTTP POST 完全足够。两种方案的正面对比：

维度	WebSocket	HTTP POST
连接模型	1 次握手，长连接常驻	keep-alive 复用，或按需新建
后端复杂度	需要 WS 会话管理	无状态，天然负载均衡
容错	需要断线重连状态机	每次请求独立，失败重试即可
ESP32 内存	~10KB 常驻	按需分配，用完即释放
代码复用	需额外 WS client 封装	项目已有 HTTP POST 基础设施

最后一点尤其关键：项目中已经封装了 WifiSecurityRequest() 用于传感器数据 POST 上传。日志上传可以复用完全相同的后端模式——一个普通的 REST API。

不过这里有个线程安全的坑：WifiSecurityRequest() 内部使用一个全局单例 WifiSecurityClient 句柄，传感器任务已经在用它。如果日志 flush 任务也调用它，两个 FreeRTOS 任务并发访问同一个 esp_http_client_handle_t，必然崩溃。所以日志模块必须创建自己独立的 esp_http_client。

最终架构确定如下：

ESP_LOGx ──► vprintf 钩子 (阶段一: WiFi 之前安装)
               ├── vprintf() → 串口照常输出
               └── 环形缓冲区 16KB (非阻塞写入, 满则丢弃新日志)
                      │
                flush 任务 (阶段二: 网络就绪后启动, 每 1s)
                      │
                独立 esp_http_client ──► POST /api/logs
                      (线程安全, 不与全局 HTTP client 冲突)

三、两阶段初始化：不漏掉 WiFi 前的日志

3.1 矛盾：日志最有价值的时候，网络还没通

设备上电后的启动流程是这样的：

NVS init → WiFi 连接 → SNTP 时间同步 → OTA 检测 → WS 连接 → 业务运行

WiFi 连接阶段产生的日志（扫描、认证、DHCP）往往是排查网络问题的关键信息。但此时网络还没通，根本无法上传。如果等网络就绪后再安装日志钩子，这些最有价值的启动日志就全丢了。

3.2 解法：先攒着，等能发了一口气刷出去

把初始化拆成两个阶段：

阶段	时机	做什么
`remote_log_early_init()`	NVS 之后、WiFi 之前	创建 16KB 环形缓冲区 + 安装 vprintf 钩子
`remote_log_start()`	主 WS 连接成功之后	启动 flush 任务，开始 HTTP POST 上传

从阶段一开始，所有 ESP_LOGx 输出就会同时写入缓冲区。WiFi 连接、SNTP、OTA 检测期间产生的日志全部在缓冲区里攒着。等阶段二启动后，flush 任务第一个周期就把积攒的日志一口气发出去。

在 app_main() 中的实际调用位置：

// NVS 初始化 + 读取 secret ...

// ── 阶段一：WiFi 之前 ──
remote_log_early_init();    // 钩子就绪，日志开始积攒

WifistaInit("SSID", "password");
while (!Wifi_isConnected) { vTaskDelay(500 / portTICK_PERIOD_MS); }
obtain_time();              // SNTP
// OTA 检测 ...
WifiSecurityClientInit();
WebsocketStart(...);
while (!WebsocketIsConnected()) { vTaskDelay(500 / portTICK_PERIOD_MS); }

// ── 阶段二：网络就绪 ──
remote_log_start("https://example.com", "/api/logs", 443, secret);
// 积攒的启动日志在下一秒自动刷出

3.3 缓冲区大小怎么定？

启动阶段日志量估算：

阶段	大约行数	大约字节
WiFi driver init + scan + connect + DHCP	20-30 行	2-4 KB
SNTP 时间同步	5 行	500 B
OTA 状态检测	5 行	500 B
TLS client init + WS 握手	10 行	1-2 KB
合计	~50 行	~5-7 KB

选择 16KB 缓冲区，安全余量超过 50%。即使极端情况溢出，溢出策略是丢弃新日志、保留旧日志——最早的启动日志（最有价值）一定不会丢。

一旦 flush 任务启动并成功 POST，缓冲区空间被释放，后续日志就正常流转了。丢弃只可能发生在启动阶段的极端情况下。

四、环形缓冲区：整个系统的心脏

环形缓冲区（Ring Buffer）是生产者-消费者模型的经典解法。在这个系统里，它承担着一个关键角色：解耦日志产生的速度和日志上传的速度。

4.1 为什么不直接发？

假设没有缓冲区，vprintf 钩子里直接调 HTTP POST 会怎样？

ESP_LOGI 在任意任务、任意上下文中被调用
HTTP POST 涉及 TLS 加密、TCP 发送，耗时 50-500ms
调用 ESP_LOGI 的业务任务被阻塞数百毫秒
摄像头帧率暴跌，传感器读取超时，看门狗触发重启

日志系统绝对不能阻塞产生日志的那个任务。 缓冲区的意义就在于：写入是瞬时的（微秒级），发送是异步的（另一个任务慢慢来）。

4.2 FreeRTOS RingBuffer 的工作原理

ESP-IDF 提供了 freertos/ringbuf.h，我们使用 RINGBUF_TYPE_BYTEBUF 类型（字节流缓冲区）。可以把它想象成一个首尾相连的数组：

        写指针 (head)
           ↓
┌──────────────────────────────────┐
│ ████████░░░░░░░░░░░░░░███████████│
└──────────────────────────────────┘
                                ↑
                           读指针 (tail)

█ = 已写入待读取的数据
░ = 空闲空间

写入 (xRingbufferSend)：从 head 开始写，写完 head 前进。如果追上了 tail（满了），根据超时参数决定等待还是失败返回。
读取 (xRingbufferReceiveUpTo)：从 tail 开始读，读完 tail 前进，释放空间给写入。
环形：head 到达数组末尾时自动绕回到开头，所以叫「环形」。

关键特性：

BYTEBUF 类型：数据按字节流连续存储，没有 per-item 的 header 开销，空间利用率最高
线程安全：内部使用信号量保护，多任务并发读写是安全的
0-tick 超时：写入指定超时为 0 ticks 时，写不进去立即返回 pdFALSE，绝不阻塞

4.3 写入端：vprintf 钩子中的非阻塞写入

每当任意任务调用 ESP_LOGx，钩子函数被触发，将格式化后的日志文本以 0-tick 超时写入缓冲区：

// 格式化日志文本
char line_buf[256];
int len = vsnprintf(line_buf, sizeof(line_buf), fmt, args);

// 0-tick 写入：写不进去就丢，绝不阻塞
BaseType_t ok = xRingbufferSend(s_ringbuf, line_buf, len, 0);
if (ok == pdTRUE) {
    s_total_bytes_buffered += len;
} else {
    s_total_bytes_dropped += len;  // 统计丢弃量
    s_drop_count++;
}

这里的 0 是超时 ticks 数。如果缓冲区满了，xRingbufferSend 立即返回 pdFALSE，不会等待哪怕一个 tick。日志被丢弃，但调用 ESP_LOGI 的业务任务完全无感——这就是「不阻塞」的保证。

4.4 读取端：flush 任务的批量收割

flush 任务每秒执行一次，从缓冲区中批量读取数据，拼成一个大块一次性 POST 出去：

char flush_buf[4096];
int total_len = 0;

// 批量读取，最多读满 4KB
while (total_len < 4095) {
    size_t remain = 4095 - total_len;
    void *item = xRingbufferReceiveUpTo(s_ringbuf, &item_size, 0, remain);
    if (item == NULL) break;
    memcpy(flush_buf + total_len, item, item_size);
    total_len += item_size;
    vRingbufferReturnItem(s_ringbuf, item);  // 归还空间
}

// 批量 POST
if (total_len > 0) {
    remote_log_http_post(flush_buf, total_len);
}

注意 xRingbufferReceiveUpTo 的语义：一次最多读取 remain 字节，但可能返回的比请求的少（取决于缓冲区中连续可用的数据量）。所以用 while 循环多次读取，拼成一个大块一次性发出——减少 HTTP 请求次数，降低 TLS 握手开销。

读取完成后调用 vRingbufferReturnItem() 归还空间，写入端才能继续写入新数据。

4.5 为什么「满了丢新的」而不是「覆盖旧的」？

FreeRTOS RingBuffer 的 BYTEBUF 类型在满的时候不会自动覆盖旧数据，而是让新写入失败。这恰好符合我们的需求：

启动阶段：钩子已安装但网络未通，日志只进不出，缓冲区逐渐填满
如果覆盖旧的：最先产生的 WiFi init 日志被后面的日志挤掉——恰恰丢了最有价值的部分
如果丢弃新的：WiFi init 日志稳稳保留，被丢弃的是网络就绪前最后几条——价值相对较低

一旦 flush 任务启动并成功 POST，缓冲区空间被释放，后续日志就正常流转了。丢弃只发生在启动阶段的极端情况下。

五、vprintf 钩子：零侵入的秘密武器

5.1 ESP-IDF 的日志拦截机制

ESP-IDF 的 ESP_LOGx 宏最终都会调用一个 vprintf 风格的函数来输出格式化文本。ESP-IDF 提供了一个 API 来替换这个输出函数：

vprintf_like_t esp_log_set_vprintf(vprintf_like_t func);

调用它可以替换日志系统内部的输出函数，返回值是被替换掉的旧函数。这就是我们的入口——安装一个自定义的 vprintf，在里面同时做两件事：

static int remote_log_vprintf(const char *fmt, va_list args)
{
    // 1. 调用原始 vprintf → 串口照常输出
    va_list args_copy;
    va_copy(args_copy, args);
    int ret = s_original_vprintf(fmt, args_copy);
    va_end(args_copy);

    // 2. 格式化后写入环形缓冲区 → 等待上传
    char line_buf[256];
    int len = vsnprintf(line_buf, sizeof(line_buf), fmt, args);
    xRingbufferSend(s_ringbuf, line_buf, len, 0);

    return ret;
}

整个项目中没有任何一行 ESP_LOGx 需要修改——钩子在底层透明地拦截了所有输出。

5.2 va_list 的陷阱：必须 va_copy

注意代码中的 va_copy。va_list 在 C 标准中是一个不透明类型，一次 vprintf / vsnprintf 调用可能会消耗（推进）它的内部状态。如果不 copy 就直接传给两个函数，第二个函数拿到的是被第一个函数「消耗过」的 va_list——未定义行为，轻则日志乱码，重则栈损坏崩溃。

正确做法：先 va_copy 出一份副本给串口输出，原始的 args 留给缓冲区写入（或者反过来，顺序不重要，关键是不能让两个函数共用同一个 va_list）。

5.3 防递归：钩子里绝对不能调 ESP_LOGx

这是最容易踩的坑。如果钩子函数内部调用了 ESP_LOGI：

ESP_LOGI → remote_log_vprintf → ESP_LOGI → remote_log_vprintf → ...

无限递归，栈溢出，设备当场重启。

解法是用一个 _Thread_local 标志位做递归守卫：

static _Thread_local bool s_in_hook = false;

static int remote_log_vprintf(const char *fmt, va_list args)
{
    // 先执行原始串口输出（这一步始终执行，确保串口日志不丢）
    int ret = s_original_vprintf(fmt, args_copy);

    // 递归守卫：正在钩子内则跳过缓冲区写入
    if (s_in_hook) return ret;
    s_in_hook = true;
    // ... 写入缓冲区 ...
    s_in_hook = false;
    return ret;
}

为什么用 _Thread_local 而不是普通 static bool？ 因为 FreeRTOS 中多个任务可能同时调用 ESP_LOGx。如果用全局 static，任务 A 设置了标志，任务 B 的日志也会被误跳过。_Thread_local 让每个任务拥有独立的标志，互不干扰。

flush 任务里的 ESP_LOGI（统计日志）安全吗？ 安全。flush 任务在读完缓冲区之后才调用 ESP_LOGI，触发的钩子会把统计日志写入缓冲区，但不会递归——因为 ESP_LOGI → 钩子 → 写缓冲区 这条路径不涉及再次调用 ESP_LOGI。这条统计日志会在下一轮 flush 时被发出去。

六、网络容错：超时、失败与指数退避

网络不是永远可靠的。设备运行在现场，WiFi 可能中断、服务器可能重启、TLS 握手可能超时。日志系统必须在这些情况下优雅降级，而不是崩溃或狂刷请求。

6.1 HTTP POST 的独立 client

每次 flush 都创建独立的 esp_http_client，请求完成后立即关闭释放：

static esp_err_t remote_log_http_post(const char *data, int len)
{
    esp_http_client_config_t cfg = {
        .url            = s_upload_url,
        .method         = HTTP_METHOD_POST,
        .timeout_ms     = 5000,                    // 5 秒超时
        .crt_bundle_attach = esp_crt_bundle_attach, // TLS 证书
        .keep_alive_enable = true,                  // TCP keep-alive 复用
    };

    esp_http_client_handle_t client = esp_http_client_init(&cfg);
    esp_http_client_set_header(client, "Content-Type", "text/plain");
    esp_http_client_set_header(client, "Authorization", s_secret);
    esp_http_client_set_post_field(client, data, len);

    esp_err_t err = esp_http_client_perform(client);

    if (err == ESP_OK) {
        int status = esp_http_client_get_status_code(client);
        if (status != 200 && status != 201 && status != 204) {
            err = ESP_FAIL;  // HTTP 层面的失败
        }
    }

    esp_http_client_close(client);
    esp_http_client_cleanup(client);
    return err;
}

关键设计点：

5 秒超时：timeout_ms = 5000，避免网络异常时无限等待。如果服务器 5 秒内没有响应，请求失败，flush 任务继续下一轮
keep-alive：开启 TCP keep-alive，底层连接可以被复用，减少每次 POST 的 TCP 握手 + TLS 握手开销
独立句柄：不与全局 WifiSecurityClient 共享，两个任务互不影响

6.2 发送失败时的数据回写

如果 HTTP POST 失败了，已经从缓冲区读出来的数据怎么办？直接丢弃太可惜。我们尝试将数据写回缓冲区，等下一轮重试：

esp_err_t err = remote_log_http_post(flush_buf, total_len);
if (err == ESP_OK) {
    s_total_bytes_sent += total_len;
    s_consecutive_fail = 0;          // 重置连续失败计数
} else {
    s_total_bytes_send_fail += total_len;
    s_consecutive_fail++;
    // 写回缓冲区，下次重试（0-tick，满则丢弃）
    xRingbufferSend(s_ringbuf, flush_buf, total_len, 0);
}

写回也是 0-tick 非阻塞的——如果此时新日志已经把缓冲区填满了，回写失败，这批数据就丢弃。这是可接受的降级：优先保证系统不阻塞。

6.3 指数退避：别在网络故障时狂刷 HTTP

如果服务器挂了，每秒一次 POST 就变成了每秒一次无意义的 TLS 握手 + 超时等待，白白消耗 CPU 和网络资源。解法是指数退避（Exponential Backoff）：

uint32_t delay_ms = RLOG_FLUSH_INTERVAL_MS;  // 基础 1 秒
if (s_consecutive_fail > 0) {
    // 连续失败次数越多，等待越久：1s → 2s → 4s → 8s → 16s → 封顶 30s
    delay_ms = RLOG_FLUSH_INTERVAL_MS * (1u << (s_consecutive_fail > 4 ? 4 : s_consecutive_fail));
    if (delay_ms > RLOG_MAX_BACKOFF_MS) delay_ms = RLOG_MAX_BACKOFF_MS;
}
vTaskDelay(pdMS_TO_TICKS(delay_ms));

退避曲线：

连续失败次数	等待间隔
0	1 秒（正常）
1	2 秒
2	4 秒
3	8 秒
4	16 秒
5+	30 秒（封顶）

一旦某次 POST 成功，s_consecutive_fail 立即归零，间隔恢复到 1 秒。这样：

短暂的网络波动（1-2 次失败）：几秒后自动恢复
持续的网络断连：请求频率降到每 30 秒一次，不浪费资源
网络恢复后：第一次成功即回到正常频率

七、运行时诊断：定期统计

系统稳定运行后，怎么知道它健不健康？flush 任务每 10 轮（约 10 秒）打印一次诊断统计：

ESP_LOGI(TAG, "[stats] flushed=%d B, pending=%u/%u bytes (%.0f%%), "
              "sent=%u B, drop=%u B (%u times), send_fail=%u B, consec_fail=%u",
         total_len,
         pre_flush_used + total_len, RLOG_RINGBUF_SIZE,
         (float)(pre_flush_used + total_len) / RLOG_RINGBUF_SIZE * 100.0f,
         s_total_bytes_sent,
         s_total_bytes_dropped, s_drop_count,
         s_total_bytes_send_fail,
         s_consecutive_fail);

各指标含义：

指标	含义	健康基准
`flushed`	本轮读出的字节数	正常运行时 200-1000 B
`pending`	flush 前缓冲区已用量	正常 <10%，启动阶段可达 30-40%
`sent`	累计成功发送字节数	持续增长
`drop`	累计被丢弃字节数	正常运行时应为 0
`send_fail`	累计发送失败字节数	偶发可接受，持续增长需排查网络
`consec_fail`	当前连续失败次数	0 为健康，>3 说明网络持续异常

这条统计日志本身也会被钩子捕获、写入缓冲区、在下一轮 flush 时上传——形成一个优雅的自监控闭环。它不会触发递归问题，因为 ESP_LOGI → 钩子 → 写缓冲区 这条路径不涉及再次调用 ESP_LOGI。

八、优雅关闭：remote_log_deinit

当设备需要停止远程日志（例如进入深度休眠前）时，关闭顺序很重要：

void remote_log_deinit(void)
{
    // 1. 先恢复原始 vprintf（停止拦截新日志）
    if (s_original_vprintf) {
        esp_log_set_vprintf(s_original_vprintf);
        s_original_vprintf = NULL;
    }
    s_hook_installed = false;

    // 2. 停止 flush 任务（等待当前轮次完成）
    s_upload_started = false;
    if (s_flush_task_handle) {
        vTaskDelay(pdMS_TO_TICKS(RLOG_FLUSH_INTERVAL_MS + 500));
        s_flush_task_handle = NULL;
    }

    // 3. 释放缓冲区
    if (s_ringbuf) {
        vRingbufferDelete(s_ringbuf);
        s_ringbuf = NULL;
    }
}

顺序不能反：如果先删缓冲区，钩子还在拦截日志，写入一个已释放的缓冲区——野指针访问，立即崩溃。

九、设计要点总结

设计原则	具体体现
生产-消费解耦	环形缓冲区隔离日志产生速度和上传速度
两阶段初始化	先攒后发，不丢启动日志
零侵入	vprintf 钩子透明拦截，业务代码无需修改
绝不阻塞	写缓冲区 0-tick 超时，满了就丢
线程安全	独立 HTTP client + `_Thread_local` 递归守卫
网络容错	失败回写 + 指数退避，优雅降级
自监控	定期统计日志自我上报
资源友好	16KB 缓冲区 + 按需创建 HTTP client，内存可控

整个模块约 200 行 C 代码，对外暴露 4 个 API（early_init / start / is_connected / deinit），即插即用。对于任何需要远程查看设备日志的 ESP32 项目，这套方案都可以直接移植。

基于 ESP-IDF v5.x + FreeRTOS，运行于 ESP32 平台。

基于 asyncio.Future 实现 WebSocket 请求-响应模式：异步获取 IoT 设备版本号

Thu, 26 Mar 2026 00:00:00 GMT

1. 问题背景

项目中后端通过 WebSocket 长连接与 ESP32-CAM 设备通信，前端通过 HTTP/WebSocket 与后端交互。已有的设备控制指令（重启、OTA）都是"发射后不管"（fire-and-forget）——发完指令就返回，无需等待设备的具体响应内容：

# 重启：发完即返回 "ok"
await device.websocket.send_json(CMD_RESTART)
return CommonOut(msg="Restart command sent.", data={"key": "restart", "values": "ok"})

但获取版本号不同，它是一个 请求-响应（Request-Response） 模式：

HTTP 客户端 ──GET /devices/1/version──► 后端 ──ws.send──► ESP32
                                         ▲                    │
                                         │    ws.receive      │
HTTP 客户端 ◄──返回版本号────────────── 后端 ◄─────────────────┘

后端必须等待设备回复后，才能把版本号返回给前端。

2. 为什么不能用简单方案？

方案一：在 HTTP 处理函数中直接 `receive()`？

# ❌ 错误方案
async def get_device_version(id):
    await device.websocket.send_json(CMD_VERSION)
    response = await device.websocket.receive_json()  # 阻塞等待
    return response

问题：WebSocket 连接上的 receive() 只能有一个消费者。设备的消息循环（Stream.py）已经在持续 await websocket.receive() 了。如果 HTTP 处理函数也去 receive()：

两个协程竞争同一个 WebSocket 的读取权 → 未定义行为
设备可能先发一帧视频流二进制数据，HTTP 侧收到的不是版本号响应 → 消息错乱
消息循环那边丢失了这条消息 → 其他功能被破坏

方案二：轮询共享变量？

# ❌ 低效方案
device.latest_version = None
await device.websocket.send_json(CMD_VERSION)
for _ in range(50):
    if device.latest_version is not None:
        return device.latest_version
    await asyncio.sleep(0.1)
return "timeout"

问题：

轮询间隔固定，要么浪费 CPU 要么响应慢
多个请求同时查版本号时，无法区分响应归属
需要额外的锁/清理逻辑，实现丑陋且脆弱

方案三：回调函数？

回调函数是异步编程中最经典的模式——"事情做完了叫我"。我们先看看如果硬用回调会怎样：

# ⚠️ 尝试用回调实现
class Esp32:
    def __init__(self):
        self.callbacks = {}  # key -> callback function

    def register_callback(self, key: str, callback):
        """注册：等收到这个 key 的响应时，调用 callback"""
        self.callbacks[key] = callback

# 消息循环中触发回调
async def _on_device_text(device, raw):
    json_data = json.loads(raw)
    key = json_data.get("key")
    if key in device.callbacks:
        device.callbacks.pop(key)(json_data)  # 调用回调
        return
    # ...正常转发...

看起来还不错？现在问题来了——HTTP 处理函数怎么写：

# ❌ 回调的死胡同
@router.get("/{id}/version")
async def get_device_version(id):
    result = None

    def on_version(data):
        nonlocal result
        result = data   # 回调把结果写入 result

    device.register_callback("version", on_version)
    await device.websocket.send_json(CMD_VERSION)

    # 但是...现在 result 还是 None！
    # 回调还没被调用（设备还没响应）
    # 而 HTTP 函数必须现在就 return 一个值
    return CommonOut(data=result)  # ← None，错误！

核心矛盾：

时间线：
  T0  HTTP handler: 注册回调, 发送指令
  T1  HTTP handler: 函数执行到末尾, 必须 return  ← 此时设备还没响应！
  T2  WS 消息循环: 收到设备响应, 触发回调
  T3  回调执行: result = data  ← 但 HTTP 响应早就在 T1 返回了，来不及了

回调函数能在"将来某个时刻"处理数据，但 HTTP 处理函数需要在当前执行流中返回结果。回调和 HTTP handler 的生命周期是割裂的。

那加个 await asyncio.sleep() 等等？那就退化成方案二的轮询了。

真正的解法：我们需要一种方式让 HTTP handler 挂起（暂停执行），直到回调被触发后再继续。这恰好就是 asyncio.Future 做的事——它把回调模式和 await 挂起机制粘合在一起：

# ✅ 回调 + Future = 最终方案
async def get_device_version(id):
    future = loop.create_future()                       # 创建占位符
    device.register_callback("version", future.set_result)  # 回调 = 填充 Future
    await device.websocket.send_json(CMD_VERSION)
    result = await future   # 挂起，直到回调执行 set_result()
    return CommonOut(data=result)

future.set_result 本身就是一个函数引用——它就是那个"回调"。只不过我们不直接用回调返回数据，而是用它来 填充 Future。HTTP handler 那边 await future 就能在回调执行后被唤醒继续执行。

这正是我们最终方案的本质——把回调的"通知"能力和 Future 的"等待"能力结合起来。

3. 最终方案：`asyncio.Future` 桥接两个协程

3.1 核心思想

asyncio.Future 是 asyncio 中最底层的可等待对象。它本质上是一个 "还没有结果的占位符"：

创建时：pending 状态（空盒子）
set_result(value)：filled 状态（盒子里放了东西）
await future：如果还是空的就挂起等待；如果已经有值就立即返回

利用这个特性，我们可以在协程 A 中创建 Future 并等待，在协程 B 中填入结果：

协程A (HTTP handler)          共享的 Future           协程B (WS 消息循环)
    │                              │                       │
    ├─ create future ────────────► │                       │
    ├─ send command to device      │                       │
    ├─ await future (挂起) ◄───── pending                  │
    │                              │     收到设备响应 ────── │
    │                              │ ◄── set_result(data)   │
    ├─ await 返回, 拿到 data ◄── filled                    │
    └─ return response             │                       │

3.2 实现代码

Esp32 类中的两个方法

class Esp32:
    def __init__(self, device):
        # ...
        self.pending_responses: dict[str, asyncio.Future] = {}
        #    key: 指令的 key 字段 (如 "version")
        #    value: 等待该响应的 Future

    async def send_and_wait(self, command: dict, key: str, timeout: float = 5.0) -> dict | None:
        """发送指令并等待设备返回匹配 key 的响应。超时返回 None。"""
        loop = asyncio.get_event_loop()
        future = loop.create_future()          # ① 创建空 Future
        self.pending_responses[key] = future   # ② 注册，供消息循环查找
        try:
            await self.websocket.send_json(command)  # ③ 发送指令
            return await asyncio.wait_for(future, timeout=timeout)  # ④ 挂起等待
        except asyncio.TimeoutError:
            return None                        # ⑤ 超时 → 返回 None
        finally:
            self.pending_responses.pop(key, None)  # ⑥ 清理

    def resolve_pending(self, key: str, data: dict) -> bool:
        """由消息循环调用：尝试匹配并填充一个挂起的 Future。"""
        future = self.pending_responses.get(key)
        if future and not future.done():
            future.set_result(data)   # 唤醒 send_and_wait 中的 await
            return True
        return False

消息循环中的拦截逻辑

# Stream.py
async def _on_device_text(device: Device.Esp32, raw: str) -> None:
    json_data = json.loads(raw)

    # 优先检查：是否有 HTTP 请求在等这条响应？
    resp_key = json_data.get("key")
    if resp_key and device.resolve_pending(resp_key, json_data):
        return  # 已消费，不转发给前端观看者

    # 常规流程：状态处理 + 转发给订阅者
    await _handle_device_status_response(device, json_data)
    await _forward_text(device, json_data)

HTTP 接口

@router.get("/{id}/version", summary="查询设备固件版本")
async def get_device_version(id, db):
    # ...校验省略...
    device = esp32IdDict.get(id)

    result = await device.send_and_wait(CMD_VERSION, "version", timeout=5.0)
    if result is None:
        return JSONResponse(status_code=504, ...)  # 超时

    return CommonOut(data={"key": "version", "values": result.get("values", "")})

3.3 逐步执行流程

以 GET /devices/1/version 为例：

时间	事件循环调度	动作
T0	HTTP handler	创建 `Future`，存入 `pending_responses["version"]`
T1	HTTP handler	`send_json(CMD_VERSION)` → 指令发往 ESP32
T2	HTTP handler	`await wait_for(future, 5.0)` → 挂起，让出控制权
T3	WS 消息循环	`await websocket.receive()` → 收到设备响应
T4	WS 消息循环	`resolve_pending("version", data)` → `future.set_result(data)`
T5	HTTP handler	被唤醒，`await` 返回 `data`
T6	HTTP handler	包装成 JSON 返回给前端

如果 T3 在 T2 之后 5 秒仍未发生 → TimeoutError → 返回 504。

4. 与回调函数的深度类比

4.1 什么是回调函数

回调的思想很简单："我现在没法处理，但你帮我做完后，调用我给你的这个函数"。

生活类比：你去餐厅点餐，前台给你一个取餐呼叫器。你不用站在柜台前等，呼叫器响了你再去取。这里"呼叫器响了"就是回调被触发的时刻。

# 最朴素的回调模式
def 点餐(菜名, 做好了之后):
    厨房.开始做(菜名)
    厨房.做好时调用(做好了之后)  # 注册回调

def 吃饭(菜):
    print(f"开吃: {菜}")

点餐("红烧肉", 吃饭)   # 传入回调函数
# 这里程序继续往下跑，不会等在这里

4.2 用回调实现设备版本查询——完整示例

为了更好理解 Future 解决了什么问题，我们先用纯回调硬写一遍：

# ========= 纯回调实现（在 FastAPI 中行不通的版本）=========

# 1. 设备对象维护回调注册表
class Esp32:
    def __init__(self):
        self.callbacks: dict[str, callable] = {}

    def on_response(self, key, callback):
        self.callbacks[key] = callback

# 2. 消息循环：收到消息后查找并触发回调
async def _on_device_text(device, raw):
    json_data = json.loads(raw)
    key = json_data.get("key")
    cb = device.callbacks.pop(key, None)
    if cb:
        cb(json_data)  # 触发回调！
        return
    # ...正常转发...

# 3. HTTP 接口中使用
@router.get("/{id}/version")
async def get_device_version(id):
    device = esp32IdDict[id]

    # 问题在这里 ↓
    received = {}
    def my_callback(data):
        received["result"] = data   # 回调把数据存到外部字典

    device.on_response("version", my_callback)
    await device.websocket.send_json(CMD_VERSION)

    # ❌ 此刻 received 是空的！因为设备还没响应
    # ❌ 但 HTTP 函数必须返回值
    return received.get("result")  # → None

画成时序图看得更清楚：

HTTP handler 执行流         回调函数           WS 消息循环
     │                        │                    │
  T0 ├── on_response(cb) ────►│                    │
  T1 ├── send_json(CMD) ──────┼───────────────────►│
  T2 ├── return received ──►  │                    │  ← HTTP 响应已发出（None）!
     │   （函数结束了）          │                    │
  T3 │                        │    receive(data) ──┤
  T4 │  （已经不存在了）   ◄── cb(data)             │  ← 回调终于执行了
     │                        │                    │     但 HTTP 响应已经返回了

根本矛盾：回调是"事后"执行的，但 HTTP handler 的 return 是"当下"就要的。这两个时间点对不上。

4.3 回调在 Node.js/Express 中为什么能用？

你可能会问：JavaScript 的 Express 框架不就是用回调的吗？

// Node.js Express — 回调是可以的
app.get('/version', (req, res) => {
    device.send({ key: 'version' });
    device.once('message:version', (data) => {
        res.json(data);   // ← 在回调里发送 HTTP 响应
    });
    // 注意：这里没有 return 响应内容
    // Express 不要求函数返回值，它靠 res.json() 来发响应
});

区别在于 Express 的 HTTP 响应是通过 res.send()/res.json() 主动发送的，不依赖函数返回值。所以回调里可以随时调 res.json()。

但 FastAPI 的路由处理函数必须通过 return 返回响应。函数 return 了就结束了，你在回调里没法 "return 到一个已经结束的函数"。

# FastAPI：响应 = 函数返回值
@router.get("/version")
async def handler():
    return CommonOut(data=...)  # ← 只能在这里决定返回什么

# Express：响应 = 手动调用 res
app.get('/version', (req, res) => {
    // 可以在任何时候、任何回调里调用 res.json()
    setTimeout(() => res.json({...}), 1000);
});

4.4 Future = 回调的"时空传送门"

asyncio.Future 解决了这个时间差问题。它的作用就像一个信封：

HTTP handler 创建一个空信封（Future），然后在信封前等着（await future）—— 此时函数 没有 return，它挂起了
回调往信封里塞了数据（set_result(data)）
HTTP handler 拆开信封拿到数据，继续执行到 return

# 回调                              Future
# ────                              ──────

def on_version(data):               future = loop.create_future()
    # data 在这里，但没法                
    # 传回 HTTP handler              pending["version"] = future
    ???                              await ws.send_json(CMD_VERSION)
                                     
                                     data = await future  # 暂停在这里
                                     # ↑ 等价于：注册了一个回调说
                                     # "有人 set_result 时唤醒我"

# 消息循环触发回调：                    # 消息循环填充 Future：
cb(json_data)                        future.set_result(json_data)
# ↓                                  # ↓
# 回调执行了，但 HTTP handler          # await 被唤醒，data 有值了
# 已经 return 了                      # HTTP handler 继续执行到 return

await future 做了两件事：

暂停当前函数（不是 return，是 suspend，函数还活着）
等 set_result() 后恢复执行

这就把回调的"通知能力"和 HTTP handler 的"需要 return 值"完美衔接了。

4.5 对照表：回调 vs Future vs Promise

维度	回调函数	asyncio.Future	JS Promise
注册"事后操作"	传入回调函数	`pending[key] = future`	`.then(callback)`
触发"事后操作"	直接调用 `cb(data)`	`future.set_result(data)`	`resolve(data)`
等待结果	没有原生支持	`await future`	`await promise`
错误传递	手动传 `err` 参数	`future.set_exception(e)` + try/except	`reject(e)` + `.catch()`
超时控制	手动 `setTimeout` + 清理	`asyncio.wait_for(future, timeout)`	`Promise.race([p, timeout])`
多个结果汇聚	嵌套回调（回调地狱）	`asyncio.gather(f1, f2)`	`Promise.all([p1, p2])`
能否挂起调用方	❌ 不能	✅ `await` 挂起	✅ `await` 挂起
本质	"做完了叫我"	"给我一个承诺，我等它兑现"	"给我一个承诺，我等它兑现"

4.6 一句话总结关系

回调:    "嘿，做完了调用这个函数"    → 通知能力 ✓，挂起等待 ✗
Future:  "嘿，做完了往这个盒子里放结果，我在盒子前 await 着"  → 通知能力 ✓，挂起等待 ✓

asyncio.Future 不是替代了回调，而是包装了回调。 set_result() 就是回调被触发的那个动作，只不过触发后的效果不是"跑一个函数"，而是 "唤醒一个正在 await 的协程"。

底层实现上，await future 其实就是向事件循环注册了一个回调："当这个 future 完成时，恢复执行我这个协程"。async/await 只是把这个注册过程藏在了语法糖背后，让你写出来的代码 看起来像同步的，跑起来是异步的。

如果你了解 JavaScript 的 Promise，asyncio.Future 就是 Python 中的等价物。set_result() 对应 resolve()，await future 对应 await promise。历史上 Python 也是受 JS Promise 启发才在 asyncio 中引入了 Future + async/await 语法。

5. 为什么必须使用异步方案？

回到我们的场景——FastAPI + 单线程事件循环 + WebSocket 长连接：

5.1 WebSocket 消息流是独占的

设备的 WebSocket 连接上跑着一个持续的消息循环：

while True:
    data = await websocket.receive()  # 独占读取
    if "text" in data:
        await _on_device_text(device, data["text"])
    if "bytes" in data:
        await _on_device_bytes(device, websocket, data["bytes"])

你不可能从另一个协程去 receive() 同一个 WebSocket——这会导致竞态条件。所以响应 只能从消息循环里获取，然后通过某种机制传给等待方。

5.2 HTTP 处理函数需要"等"

FastAPI 的路由处理函数必须返回一个值。对于版本号查询，你不能"先返回再补数据"——HTTP 是请求-响应模型。所以处理函数 必须挂起等待，直到拿到结果或超时。

5.3 不能阻塞事件循环

如果用 time.sleep() 或忙等待来"等"，整个事件循环都会冻结——所有其他请求、所有 WebSocket 通信全部停摆。必须用 await 让出控制权，让事件循环在等待期间继续处理其他任务。

asyncio.Future + await 完美满足这三个约束：

不触碰 WebSocket 的读取权 ✓
让 HTTP 处理函数挂起等待 ✓
不阻塞事件循环 ✓

6. 扩展思考

6.1 并发安全

如果两个前端同时查同一设备的版本号怎么办？当前实现中 pending_responses 用 key 作为字典键，后注册的会覆盖先注册的 Future。

如需支持并发，可以改为用唯一请求 ID：

import uuid

async def send_and_wait(self, command, key, timeout=5.0):
    request_id = f"{key}:{uuid.uuid4().hex[:8]}"
    command["_req_id"] = request_id  # 需要设备原样返回此字段
    future = loop.create_future()
    self.pending_responses[request_id] = future
    # ...

但对于嵌入式设备场景（ESP32 资源有限，协议简单），当前按 key 匹配的方案已经够用。

6.2 方案适用范围

这个模式适用于任何需要"通过一个共享通道发送请求、从同一通道接收响应"的场景：

IoT 设备控制（本文场景）
消息队列的 RPC 模式（通过 MQ 发请求、等回复）
多路复用的 TCP 连接上的请求-响应匹配

核心思路始终是：创建 Future → 注册到共享字典 → 发送请求 → 等待 Future → 另一端填充结果。

基于 FastAPI + asyncio + WebSocket + ESP32-CAM 的实际项目经验整理。

嵌入式 WebSocket 命令处理的扁平化设计：映射表 + 分发表实战

Thu, 26 Mar 2026 00:00:00 GMT

1. 问题：嵌套地狱

一个典型的 WebSocket 文本帧协议长这样：

{
  "code": 0,
  "item": "camera",
  "key": "frame_size",
  "values": "FRAMESIZE_VGA"
}

code：0 查询，1 设定
item：模块名（status / camera / device）
key：参数名
values：参数值

最朴素的实现方式是：

if (code == 0) {
    if (strcmp(item, "status") == 0) {
        if (strcmp(key, "status") == 0) { /* ... */ }
    } else if (strcmp(item, "camera") == 0) {
        if (strcmp(key, "frame_size") == 0) { /* ... */ }
        else if (strcmp(key, "jpeg_quality") == 0) { /* ... */ }
        // ...
    }
} else if (code == 1) {
    // 再来一遍……
}

三层嵌套，每增加一个 item 或 key 就要在两处（查询/设定）各加一段。 模块一多，这个函数轻松突破 300 行，可读性和可维护性直线下降。

2. 解法概览：两级扁平化

整体思路是将「嵌套分支」拆成两级独立的 表驱动（Table-Driven） 结构：

层级	职责	数据结构
映射表	枚举值 ↔ 字符串的双向转换	`FrameSizeEntry_t[]`
分发表	`item` → 对应的查询/设定处理函数	`ItemDispatch_t[]`

入口函数 ws_text_handler 只做三件事：解析 JSON → 查分发表 → 调用处理函数，不含任何业务逻辑。

┌─────────────────────┐
│  ws_text_handler()  │  入口：JSON 解析 + 字段校验
└────────┬────────────┘
         │ 遍历 dispatch_table[]
         ▼
┌────────────────────────────────────────┐
│  dispatch_table[i].query / .set        │  按 code 选择查询或设定
│  ┌──────────┬──────────┬────────────┐  │
│  │ status   │ camera   │ device     │  │  每个 item 一行
│  └──────────┴──────────┴────────────┘  │
└────────┬───────────────────────────────┘
         │ 在具体 handler 中按 key 处理
         ▼
   query_camera() / set_camera() / ...

3. 映射表：枚举 ↔ 字符串的零成本转换

嵌入式开发中经常需要在「人类可读的字符串」和「C 枚举值」之间转换。传统做法是写一大堆 switch-case，每增加一个枚举值就要改两处（to_str 和 from_str）。

定义

typedef struct {
    const char    *name;
    framesize_t    fs;
} FrameSizeEntry_t;

static const FrameSizeEntry_t fs_table[] = {
    { "FRAMESIZE_128X128", FRAMESIZE_128X128 },
    { "FRAMESIZE_240X240", FRAMESIZE_240X240 },
    { "FRAMESIZE_VGA",     FRAMESIZE_VGA     },
    { "FRAMESIZE_SVGA",    FRAMESIZE_SVGA    },
    { "FRAMESIZE_HD",      FRAMESIZE_HD      },
    { "FRAMESIZE_FHD",     FRAMESIZE_FHD     },
};

正反查找

// 枚举 → 字符串
static const char *framesize_to_str(framesize_t fs) {
    for (size_t i = 0; i < FS_TABLE_SIZE; i++)
        if (fs_table[i].fs == fs) return fs_table[i].name;
    return "unknown";
}

// 字符串 → 枚举
static framesize_t str_to_framesize(const char *str) {
    for (size_t i = 0; i < FS_TABLE_SIZE; i++)
        if (strcasecmp(str, fs_table[i].name) == 0) return fs_table[i].fs;
    return FRAMESIZE_INVALID;
}

优势：

单一数据源：新增分辨率只需在 fs_table[] 加一行，正反查找自动生效。
编译期可见：表是 const 数组，存储在 .rodata，不占 RAM。
大小写容错：查找使用 strcasecmp，协议鲁棒性更好。

4. 分发表：item × code 的扁平路由

这是整个设计的核心。我们定义一个统一的处理函数签名，然后用结构体数组把 item 名称和对应的查询、设定函数关联起来。

处理函数签名

typedef void (*query_handler_t)(const char *key, cJSON *values_item);

所有查询和设定 handler 都遵守同一签名（入参为 key 和 values），确保可以用函数指针统一调用。

分发表定义

typedef struct {
    const char      *item;     // 模块名称
    query_handler_t  query;    // code == 0 时调用
    query_handler_t  set;      // code == 1 时调用
} ItemDispatch_t;

static const ItemDispatch_t dispatch_table[] = {
    { "status", query_status, (query_handler_t)set_status },
    { "camera", query_camera, (query_handler_t)set_camera },
    { "device", query_device, NULL },  // device 的 set 需要特殊处理
};

入口函数中的调度逻辑

// 1. 遍历分发表，O(n) 查找 item
const ItemDispatch_t *entry = NULL;
for (size_t i = 0; i < DISPATCH_TABLE_SIZE; i++) {
    if (strcasecmp(item, dispatch_table[i].item) == 0) {
        entry = &dispatch_table[i];
        break;
    }
}

// 2. 未找到 → 统一错误响应
if (!entry) {
    ws_reply(0, "不支持的item", key, "");
    cJSON_Delete(json);
    return;
}

// 3. 按 code 分发
if (code == 0) {
    entry->query(key, values_item);
} else if (code == 1) {
    // device 模块的 set 需要额外传入 json（支持重启前释放资源）
    if (strcasecmp(item, "device") == 0) {
        if (set_device(key, values_item, json)) return;
    } else if (entry->set) {
        entry->set(key, values_item);
    }
}

入口函数体只有约 50 行，且不含任何具体业务分支。 所有业务逻辑都下沉到各个 handler 中。

5. 业务 Handler 内部：key 级别的平铺

每个 handler 内部再按 key 做一层 if-else，但此时每个函数只关心自己模块的字段，职责单一：

static void query_camera(const char *key, cJSON *values_item) {
    sensor_t *s = esp_camera_sensor_get();
    if (!s) { ws_reply(0, "相机未初始化", key, ""); return; }

    char vbuf[32];
    if (strcasecmp(key, "frame_size") == 0) {
        ws_reply(1, "OK.", key, framesize_to_str(s->status.framesize));
    } else if (strcasecmp(key, "jpeg_quality") == 0) {
        snprintf(vbuf, sizeof(vbuf), "%d", s->status.quality);
        ws_reply(1, "OK.", key, vbuf);
    } else {
        ws_reply(0, "未知的camera键", key, "");
    }
}

每个 handler 不超过 30 行，context 清晰
错误处理统一走 ws_reply 返回标准格式

6. 统一响应：ws_reply

所有对外输出都通过一个函数完成，保证协议格式一致：

static void ws_reply(int ok, const char *msg, const char *key, const char *values) {
    char buf[256];
    snprintf(buf, sizeof(buf),
             "{\"code\":%d,\"msg\":\"%s\",\"key\":\"%s\",\"values\":\"%s\"}",
             ok ? 1 : 0, msg, key ? key : "", values ? values : "");
    WebsocketSendText(buf, strlen(buf));
}

这带来的好处：

修改响应格式只改一处
不会出现某个分支忘了返回 code 字段的问题
调用处代码极其简洁

7. 特殊分支的优雅处理

并非所有模块都能完美套入统一签名。device 模块的 restart 指令需要在重启前手动释放 JSON 对象，函数签名多了一个 cJSON *json 参数。

处理方式是在分发表中将 device.set 设为 NULL，在入口函数中做一次显式判断：

if (strcasecmp(item, "device") == 0) {
    if (set_device(key, values_item, json))
        return;  // json 已在 set_device 内部释放（重启场景）
}

set_device 返回 bool 来告知调用方是否已接管 json 的生命周期——这是一个最小特例化的策略：不为了追求完美统一而引入复杂的抽象，而是在必要时用最小的代码量处理例外。

8. 扩展性分析

新增一个 item 模块（如 `sensor`）

只需 3 步：

编写 query_sensor() 和 set_sensor() 两个函数

在分发表加一行：

{ "sensor", query_sensor, (query_handler_t)set_sensor },

完成。入口函数 零改动。

新增一个 key（如给 camera 加 `brightness`）

只需在 query_camera / set_camera 中各加一个 else if 分支。其他模块和入口函数完全不受影响。

新增一个枚举映射（如 `FRAMESIZE_QVGA`）

在 fs_table[] 加一行即可，to_str 和 from_str 自动适配。

9. 设计要点总结

设计原则	具体体现
表驱动替代分支	映射表消除 switch-case，分发表消除 if-else 嵌套
单一职责	入口函数只做路由，业务逻辑下沉到各 handler
统一接口	所有 handler 遵循 `(key, values_item)` 签名
统一出口	`ws_reply()` 保证响应格式一致
最小特例化	仅 `device.set` 做特殊处理，不过度抽象
编译期安全	映射表和分发表均为 `const`，存 `.rodata` 段
零外部依赖	仅依赖 cJSON + ESP-IDF 标准 API

10. 适用场景

这套模式适用于任何「协议字段 → 处理函数」的映射场景：

MQTT 主题路由
HTTP REST 端点分发
串口 AT 指令解析
BLE 特征值读写回调

核心思想不变：用数据（表）代替控制流（分支），用函数指针代替内联逻辑。 代码量可能差不多，但可读性和可维护性天差地别。

基于 ESP-IDF v5.x + cJSON，运行于 ESP32 平台。

linux systemd 服务管理器的使用

Tue, 17 Mar 2026 00:00:00 GMT

参考了以下文章, 写得超好!

简要命令

重载 systemd 配置

重载所有 unit 文件（常用）

sudo systemctl daemon-reload

启动服务并设置开机启动

sudo systemctl start myapp.service
sudo systemctl enable myapp.service

查看服务状态与日志

sudo systemctl status myapp
sudo journalctl -fu myapp

列出所有服务

systemctl list-units --type=service

systemd 用户模式 (好用!)

简单说，systemd 不只是给 root 用的。每个登录用户都可以跑自己的 systemd --user 实例，用来管理用户级别的后台服务和定时任务——不需要 sudo。

用户单元文件放在以下目录：

目录	用途
`~/.config/systemd/user/`	用户自定义的服务(推荐!)
`~/.local/share/systemd/user/`	用户安装的服务
`/usr/lib/systemd/user/`	系统提供的用户服务模板

所有操作都带 --user 参数，和系统级的 systemctl 用法几乎一样：

systemctl --user start my-app       # 启动
systemctl --user stop my-app        # 停止
systemctl --user restart my-app     # 重启
systemctl --user status my-app      # 查看状态
systemctl --user enable my-app      # 开机自启
systemctl --user daemon-reload      # 重新加载配置

有一个前提：必须启用 linger，否则用户注销后所有用户服务都会被杀掉：

sudo loginctl enable-linger $USER
loginctl show-user $USER | grep Linger   # 确认输出 Linger=yes

systemd文件配置示例

以这个博客的fastapi服务文件为例

//file: /home/mint/.config/systemd/user/blog_backend.service

[Unit]
Description=Blog Fastapi Service
After=network.target
 
[Service]
WorkingDirectory=/home/mint/web/blog_backend/app
Environment="PATH=/home/mint/web/blog_backend/.venv/bin:/usr/local/bin:/usr/bin"
Environment="FASTAPI_DEPLOY=DEPLOY"           # 用于区分测试和部署环境
Environment="SMTP_USER=******"                # 以下均是通过环境变量引入敏感数据
Environment="SMTP_PASSWORD=******"
Environment="SECRET_KEY=******"
Environment="DB_USER=******"
Environment="DB_PASSWORD=******"
Environment="DB_NAME=******"
Environment="DB_HOST=******"
Environment="DB_SCHEMA=******"
ExecStart=/home/mint/web/blog_backend/.venv/bin/gunicorn \
          -w 4 \
          -k uvicorn.workers.UvicornWorker \
          --bind localhost:8051 \
          --log-file=- \
          main:app
StandardOutput=journal                        # 将控制台输出重定向到journal
Restart=always                                # 自动重启
RestartSec=10  
LimitNOFILE=4096  
 
[Install]
WantedBy=default.target

后记

还有定时器功能等等, 还没用上, 可先参考上方列出来的文章

vscode esp-idf开发环境安装及arduino移植

Sun, 08 Mar 2026 00:00:00 GMT

:::note 之所以写这篇博客, 是因为乐鑫做的实在是太垃圾了.

手动安装VScode插件识别不到, 默认安装版本太高arduino不适配, Vscode启动安装管理器安装居然要在vscode上按一下回车确认我的github用户名???

我瞪了半天安装管理器, 没发现vsc命令窗口上有个超小的输入框确认, 没确认就不开始下载, 等了半天自己居然崩溃了?!

我tm整整装了四遍, 等进度条的时候写下了这篇博客 :::

esp-idf环境安装

:::note 手动安装或使用source export.sh会导致idf插件无法识别虚拟环境

两种方案原生无法共存, 所以哪个都行, 后文有解决方案. :::

方案A: 通过VSCode插件安装(通过官方管理器)

参考安装 ESP-IDF 和相关工具

如果你不使用VSCode插件, 参考在 Linux 上安装 ESP-IDF 及工具链直接下载管理器安装

vscode安装扩展ESP-IDF, 然后跟随欢迎页面提示安装,.

或者在vsc命令面板输入ESP-IDF: Open ESP-IDF Install Manager安装.

:::important 正如我开头提到的, 确认完下载后, 答应我一定要看VScode顶上的命令框好吗, 没确认就不开始下载, 我哭死 :::

方案B: 手动安装

参考Linux 和 macOS 平台工具链的标准设置（已过时）

以下是基于Ubuntu 和 Debian的安装方案

1.安装依赖(已安装的会自动跳过)

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

2. 从Github克隆esp-idf

::github{repo="espressif/esp-idf"}

mkdir -p ~/esp
cd ~/esp
git clone -b v5.1.4 --single-branch --recursive https://github.com/espressif/esp-idf.git

:::important --recursive必须要加, 因为这会下载所有的子仓库

-b v5.1.4必须要加, 截止2026.3 esp-idf已经更新到v6.1, 但arduino组件仅支持v5.x版本的esp-idf :::

3. 安装所需芯片的工具包

cd ~/esp/esp-idf
./install.sh all  # 安装所有芯片

./install.sh esp32,esp32s2 # 安装指定的几个芯片

:::note 工具包默认安装到~/.espressif定制安装目录参见前文

Linux 和 macOS 平台工具链的标准设置（已过时） :::

4. 环境配置

vim ~/.bashrc

在.bashrc中加入以下内容, 保存后别忘了source ~./bashrc使配置生效


export IDF_PATH="$HOME/esp/esp-idf/:$PATH"
# 设置一个别名, 
alias get_idf='. $IDF_PATH/export.sh'

请在需要运行 ESP-IDF 的终端窗口运行以下命令：

. $HOME/esp/esp-idf/export.sh

或者直接运行

get_idf

看到下图即说明安装成功

vscode ESP-IDF插件编译和 idf.py手动编译兼容

以v5.5.3版本为例

首先, 你一定执行过./install.sh和$HOME/esp/esp-idf/export.sh,出现了上图的界面, 证明idf.py已经可以使用.
但是ESP-IDF插件的编译虚拟环境没有使用export.sh, 而是使用了source $HOME/.espressif/tools/activate_idf_v5.5.3.sh, 其内部设置的虚拟环境和export.sh的虚拟环境冲突, 如果设置了export.sh, 则vsc插件的环境就会消失
所以我们要做的是将activate_idf_v5.5.3.sh内的虚拟环境改为export.sh中的虚拟环境
export.sh中的虚拟环境位置在$HOME/.espressif/python_env/idf5.5_py3.12_env

//file: /home/mint/.espressif/tools/activate_idf_v5.5.3.sh
l-files activate_idf_v5.5.3.sh 'activate_idf_v5.5.3 (副本).sh'
9c9
+ IDF_PYTHON_ENV_PATH:/home/mint/.espressif/python_env/idf5.5_py3.12_env
- IDF_PYTHON_ENV_PATH:/home/mint/.espressif/tools/python/v5.5.3/venv
97c97
+     export PATH="/home/mint/.espressif/tools/cmake/3.30.2/bin:/home/mint/.espressif/tools/esp-clang/esp-19.1.2_20250312/esp-clang/bin:/home/mint/.espressif/tools/esp-rom-elfs/20241011/:/home/mint/.espressif/tools/esp32ulp-elf/2.38_20240113/esp32ulp-elf/bin:/home/mint/.espressif/tools/esp32ulp-elf/2.38_20240113/esp32ulp-elf/esp32ulp-elf/bin:/home/mint/.espressif/tools/ninja/1.12.1/:/home/mint/.espressif/tools/openocd-esp32/v0.12.0-esp32-20251215/openocd-esp32/bin:/home/mint/.espressif/tools/riscv32-esp-elf-gdb/16.3_20250913/riscv32-esp-elf-gdb/bin:/home/mint/.espressif/tools/riscv32-esp-elf/esp-14.2.0_20251107/riscv32-esp-elf/bin:/home/mint/.espressif/tools/riscv32-esp-elf/esp-14.2.0_20251107/riscv32-esp-elf/riscv32-esp-elf/bin:/home/mint/.espressif/tools/xtensa-esp-elf-gdb/16.3_20250913/xtensa-esp-elf-gdb/bin:/home/mint/.espressif/tools/xtensa-esp-elf/esp-14.2.0_20251107/xtensa-esp-elf/bin:/home/mint/.espressif/tools/xtensa-esp-elf/esp-14.2.0_20251107/xtensa-esp-elf/xtensa-esp-elf/bin:/home/mint/.espressif/python_env/idf5.5_py3.12_env:/home/mint/.espressif/v5.5.3/esp-idf/components/esptool_py/esptool:$PATH"
-     export PATH="/home/mint/.espressif/tools/cmake/3.30.2/bin:/home/mint/.espressif/tools/esp-clang/esp-19.1.2_20250312/esp-clang/bin:/home/mint/.espressif/tools/esp-rom-elfs/20241011/:/home/mint/.espressif/tools/esp32ulp-elf/2.38_20240113/esp32ulp-elf/bin:/home/mint/.espressif/tools/esp32ulp-elf/2.38_20240113/esp32ulp-elf/esp32ulp-elf/bin:/home/mint/.espressif/tools/ninja/1.12.1/:/home/mint/.espressif/tools/openocd-esp32/v0.12.0-esp32-20251215/openocd-esp32/bin:/home/mint/.espressif/tools/riscv32-esp-elf-gdb/16.3_20250913/riscv32-esp-elf-gdb/bin:/home/mint/.espressif/tools/riscv32-esp-elf/esp-14.2.0_20251107/riscv32-esp-elf/bin:/home/mint/.espressif/tools/riscv32-esp-elf/esp-14.2.0_20251107/riscv32-esp-elf/riscv32-esp-elf/bin:/home/mint/.espressif/tools/xtensa-esp-elf-gdb/16.3_20250913/xtensa-esp-elf-gdb/bin:/home/mint/.espressif/tools/xtensa-esp-elf/esp-14.2.0_20251107/xtensa-esp-elf/bin:/home/mint/.espressif/tools/xtensa-esp-elf/esp-14.2.0_20251107/xtensa-esp-elf/xtensa-esp-elf/bin:/home/mint/.espressif/tools/python/v5.5.3/venv/bin:$PATH"
103c103
+     venv_path="/home/mint/.espressif/python_env/idf5.5_py3.12_env"
-     venv_path="$1"
138c138
+ alias idf.py="/home/mint/.espressif/v5.5.3/esp-idf/tools/idf.py"
- alias idf.py="/home/mint/.espressif/tools/python/v5.5.3/venv/bin/python /home/mint/.espressif/v5.5.3/esp-idf/tools/idf.py"
140c140
+ alias esptool.py="/home/mint/.espressif/v5.5.3/esp-idf/components/esptool_py/esptool/esptool.py"
- alias esptool.py="/home/mint/.espressif/tools/python/v5.5.3/venv/bin/python /home/mint/.espressif/v5.5.3/esp-idf/components/esptool_py/esptool/esptool.py"
142c142
+ alias espefuse.py="/home/mint/.espressif/v5.5.3/esp-idf/components/esptool_py/esptool/espefuse.py"
- alias espefuse.py="/home/mint/.espressif/tools/python/v5.5.3/venv/bin/python /home/mint/.espressif/v5.5.3/esp-idf/components/esptool_py/esptool/espefuse.py"
144c144
+ alias espsecure.py="/home/mint/.espressif/v5.5.3/esp-idf/components/esptool_py/esptool/espsecure.py"
- alias espsecure.py="/home/mint/.espressif/tools/python/v5.5.3/venv/bin/python /home/mint/.espressif/v5.5.3/esp-idf/components/esptool_py/esptool/espsecure.py"
146c146
+ alias otatool.py="/home/mint/.espressif/v5.5.3/esp-idf/components/app_update/otatool.py"
- alias otatool.py="/home/mint/.espressif/tools/python/v5.5.3/venv/bin/python /home/mint/.espressif/v5.5.3/esp-idf/components/app_update/otatool.py"
148c148
+ alias parttool.py="/home/mint/.espressif/v5.5.3/esp-idf/components/partition_table/parttool.py"
- alias parttool.py="/home/mint/.espressif/tools/python/v5.5.3/venv/bin/python /home/mint/.espressif/v5.5.3/esp-idf/components/partition_table/parttool.py"
156c156
+ venv_default="/home/mint/.espressif/python_env/idf5.5_py3.12_env"
- venv_default="/home/mint/.espressif/tools/python/v5.5.3/venv"

arduino组件添加

参考Arduino as an ESP-IDF component

要使用 IDF 组件管理器将 Arduino 组件添加到项目中，请在项目目录中运行以下命令：

idf.py add-dependency "espressif/arduino-esp32^3.3.7"

或者，可以使用 Arduino 组件从模板创建一个新项目：

idf.py create-project-from-example "espressif/arduino-esp32^3.3.7:hello_world"

配置

根据以下两个选项之一，在 idf.py menuconfig 中设置相应的设置。

前往该部分Arduino Configuration --->

功能使用说明app_main()- 关闭Autostart Arduino setup and loop on boot

使用方法setup()和loop()功能 - 打开Autostart Arduino setup and loop on boot

由于 Arduino 库使用了 C++ 特性，您需要将一些文件扩展名从 .c .c++替换为 .c++ .cpp：

在主文件夹中，将文件main.c重命名为main.cpp。

在主文件夹中打开CMakeLists.txt文件，并按照以下说明将main.c更改为main.cpp 。

方案一：使用 Arduino 的 setup() 和 loop() 函数

你的 main.cpp 文件应该像其他草图文件一样格式化。别忘了包含Arduino.h.

//file: main.cpp
#include "Arduino.h"

void setup(){
  Serial.begin(115200);
  while(!Serial){
    ; // wait for serial port to connect
  }
}

void loop(){
    Serial.println("loop");
    delay(1000);
}

选项 2. 使用 ESP-IDF appmain()

你需要在 main.cpp 中实现app_main()并调用initArduino();它。

请注意，在这种情况下不会调用 setup() 和 loop() 函数。此外，这app_main()是一个单次执行的普通函数，因此如果您需要像 Arduino 那样的无限循环，请将其放在其他地方。

//file: main.cpp
#include "Arduino.h"

extern "C" void app_main()
{
  initArduino();

  // Arduino-like setup()
  Serial.begin(115200);
  while(!Serial){
    ; // wait for serial port to connect
  }

  // Arduino-like loop()
  while(true){
    Serial.println("loop");
  }

  // WARNING: if program reaches end of function app_main() the MCU will restart.
}

最终结果

stc8g makefile和用量分析脚本

Sat, 03 Jan 2026 00:00:00 GMT

makefile


#!/usr/bin/make -f
# Makefile for SDCC project with automatic library discovery
CC = sdcc
CFLAGS = --model-medium --opt-code-size

# 定义库名称（只需要在这里添加）
LIBRARIES = User System

# 单片机型号
MCU = STC8G1K08A
# 串口设备
SERIAL_PORT = /dev/ttyUSB0

# 生成包含目录路径
INCLUDES = $(foreach lib, $(LIBRARIES), -I $(lib)/Inc)

# 查找所有源文件
SRCS = $(foreach lib, $(LIBRARIES), $(wildcard $(lib)/Src/*.c))
# 获取所有.c文件的基本名称（用于检查重名）
BASENAMES = $(foreach src, $(SRCS), $(notdir $(src)))

# 检查是否有重复的源文件名
DUPLICATES = $(filter $(words $(BASENAMES)),$(words $(sort $(BASENAMES))))
ifneq ($(DUPLICATES),$(words $(BASENAMES)))
    $(warning 警告: 发现重复的源文件名！)
    $(warning 重复文件: $(foreach base,$(sort $(foreach b,$(BASENAMES),$(if $(filter 2,$(words $(filter $(b),$(BASENAMES)))),$(b)))),$(base)))
endif

# 生成对象文件列表（保持目录结构）
OBJS = $(patsubst %.c,%.rel,$(SRCS))

# 项目名称
TARGET = pwm

# 构建目录
BUILD_DIR = build

# 将对象文件放在build目录中
OBJS_BUILD = $(patsubst %.rel,$(BUILD_DIR)/%.rel,$(OBJS))

# 默认目标：构建并生成报告
all: check_libs $(BUILD_DIR) $(BUILD_DIR)/report
	@echo "构建完成: $(BUILD_DIR)/$(TARGET).hex"

# 检查库目录是否存在
check_libs:
	@for lib in $(LIBRARIES); do \
		if [ ! -d "$$lib/Inc" ] || [ ! -d "$$lib/Src" ]; then \
			echo "错误: 库 $$lib 结构不正确！需要 $$lib/Inc 和 $$lib/Src 目录"; \
			exit 1; \
		fi; \
	done

# 创建构建目录
$(BUILD_DIR):
	@mkdir -p $(BUILD_DIR)

# 编译规则：所有.c文件 -> build/目录下的.rel文件
$(BUILD_DIR)/%.rel: %.c
	@echo "编译: $<"
	@mkdir -p $(dir $@)
	@$(CC) -c $(CFLAGS) $(INCLUDES) $< -o $@ 2>&1 | head -20

# 链接
$(BUILD_DIR)/$(TARGET).ihx: $(OBJS_BUILD)
	@echo "链接: $(words $(OBJS_BUILD)) 个对象文件..."
	@cd $(BUILD_DIR) && $(CC) $(CFLAGS) $(patsubst $(BUILD_DIR)/%,%,$(OBJS_BUILD)) -o $(TARGET).ihx

# 生成HEX
$(BUILD_DIR)/$(TARGET).hex: $(BUILD_DIR)/$(TARGET).ihx
	@echo "生成HEX文件..."
	@cd $(BUILD_DIR) && packihx $(TARGET).ihx > $(TARGET).hex

+ # report: 调用外部脚本解析 map 并打印报告
+ $(BUILD_DIR)/report: $(BUILD_DIR)/$(TARGET).hex
+	@echo "生成资源使用报告..."
+	@sh scripts/map_report.sh $(BUILD_DIR)/$(TARGET).map || true

# 下载到单片机
flash: $(BUILD_DIR)/$(TARGET).hex
	@echo "下载到 $(MCU) via $(SERIAL_PORT)..."
	stcgal -p $(SERIAL_PORT) -t 22168 -o program_eeprom_split=12288 -a $(BUILD_DIR)/$(TARGET).hex

# 编译但不链接（调试用）
compile: $(OBJS_BUILD)
	@echo "编译完成，生成 $(words $(OBJS_BUILD)) 个.rel文件"

# 显示项目信息
info:
	@echo "========================================"
	@echo "项目: $(TARGET)"
	@echo "编译器: $(CC)"
	@echo "库列表: $(LIBRARIES)"
	@echo "包含目录: $(INCLUDES)"
	@echo "源文件 ($(words $(SRCS)) 个):"
	@for src in $(sort $(SRCS)); do echo "  $$src"; done
	@echo "对象文件 ($(words $(OBJS_BUILD)) 个):"
	@for obj in $(sort $(OBJS_BUILD)); do echo "  $$obj"; done
	@echo "构建目录: $(BUILD_DIR)"
	@echo "========================================"

# 清理
clean:
	@echo "清理构建文件..."
	@rm -rf $(BUILD_DIR)
	@rm -f *.ihx *.hex *.rel *.lk *.map *.mem *.rst *.asm *.lst *.sym *.cdb

# 帮助信息
help:
	@echo "可用命令:"
	@echo "  make           - 构建整个项目"
	@echo "  make clean     - 清理所有生成文件"
	@echo "  make flash     - 下载到单片机"
	@echo "  make info      - 显示项目信息"
	@echo "  make compile   - 只编译不链接"
	@echo "  make help      - 显示此帮助信息"

.PHONY: all clean flash info help check_libs compile tidy

资源分析脚本


#!/bin/sh
# Enhanced map report for SDCC projects
# Usage: map_report.sh <map-file> [ROM_TOTAL_BYTES] [RAM_TOTAL_BYTES]
# If ROM_TOTAL_BYTES / RAM_TOTAL_BYTES are not provided, script tries to
#  - read a companion .mem file (same base name) for ROM total
#  - otherwise falls back to defaults: ROM=8k+4k (12288), RAM=1k+256 (1280)

MAPFILE="$1"
ROM_OVERRIDE="$2"
RAM_OVERRIDE="$3"

if [ -z "$MAPFILE" ] || [ ! -f "$MAPFILE" ]; then
    echo "map 报告: 未提供 map 文件 或 文件不存在: $MAPFILE"
    exit 0
fi

hex2dec() {
    [ -z "$1" ] && echo 0 && return
    # accept 0x... or bare hex (without 0x)
    case "$1" in
        0x*|0X*) printf "%d" "$1" ;;
        *) printf "%d" "0x$1" ;;
    esac
}

# Try to extract code/const/idata/pdata/xdata sizes from map file.
# We look for sections by name and take the "Size" column where possible.
CSEG_START_HEX=$(awk '/^[[:space:]]*CSEG[[:space:]]+[0-9A-Fa-f]/ {print $2; exit}' "$MAPFILE" | sed 's/0x//g')
CSEG_HEX=$(awk '/^[[:space:]]*CSEG[[:space:]]+[0-9A-Fa-f]/ {print $3; exit}' "$MAPFILE" | sed 's/0x//g')
CONST_HEX=$(awk '/^[[:space:]]*CONST[[:space:]]+[0-9A-Fa-f]/ {print $3; exit}' "$MAPFILE" | sed 's/0x//g')
DSEG_HEX=$(awk '/^[[:space:]]*DSEG[[:space:]]+[0-9A-Fa-f]/ {print $3; exit}' "$MAPFILE" | sed 's/0x//g')
PSEG_HEX=$(awk '/^[[:space:]]*PSEG[[:space:]]+[0-9A-Fa-f]/ {print $3; exit}' "$MAPFILE" | sed 's/0x//g')
XSEG_HEX=$(awk '/^[[:space:]]*XSEG[[:space:]]+[0-9A-Fa-f]/ {print $3; exit}' "$MAPFILE" | sed 's/0x//g')

CSEG=$(hex2dec "$CSEG_HEX")
CONST=$(hex2dec "$CONST_HEX")
DSEG=$(hex2dec "$DSEG_HEX")
PSEG=$(hex2dec "$PSEG_HEX")
XSEG=$(hex2dec "$XSEG_HEX")

USED_ROM=$((CSEG + CONST))
USED_RAM=$((DSEG + PSEG + XSEG))

# compute CSEG end for module delta calc
CSEG_START=$(hex2dec "$CSEG_START_HEX")
CSEG_END=$((CSEG_START + CSEG))

# Determine total ROM (flash) size: prefer override arg, then companion .mem file, then default
DEFAULT_ROM=$((8*1024 + 4*1024))
DEFAULT_RAM=$((1*1024 + 256))

ROM_TOTAL=""
if [ -n "$ROM_OVERRIDE" ]; then
    ROM_TOTAL="$ROM_OVERRIDE"
else
    MEMFILE="${MAPFILE%.map}.mem"
    if [ -f "$MEMFILE" ]; then
        # Look for line like: ROM/EPROM/FLASH  0x0000   0x1e73    7796    65536
        ROM_TOTAL=$(awk '/ROM\/EPROM\/FLASH/ {print $(NF-1); exit}' "$MEMFILE")
    fi
fi
if [ -z "$ROM_TOTAL" ]; then
    ROM_TOTAL=$DEFAULT_ROM
fi

RAM_TOTAL=""
if [ -n "$RAM_OVERRIDE" ]; then
    RAM_TOTAL="$RAM_OVERRIDE"
else
    # try to read some RAM hints from .mem (not always present)
    MEMFILE="${MAPFILE%.map}.mem"
    if [ -f "$MEMFILE" ]; then
        # try to find a line like: PAGED EXT. RAM   0x0001   0x00ba     186      256
        RAM_TOTAL=$(awk '/PAGED EXT. RAM|EXTERNAL RAM|Internal RAM layout:/ {line=NR} END{ if (line) { for(i=1;i<=NR;i++){} } }' "$MEMFILE")
        # above attempt is conservative; we won't rely on it — fallback to default if empty
        RAM_TOTAL=""
    fi
fi
if [ -z "$RAM_TOTAL" ]; then
    RAM_TOTAL=$DEFAULT_RAM
fi

# Print summary with percentages
percent() {
    # percent <used> <total>
    awk "BEGIN{ if ($2==0) printf \"N/A\"; else printf \"%.1f\", ($1/$2)*100 }"
}

echo "Map 报告: $MAPFILE"
echo "----------------------------------------"
echo "ROM 总量: $ROM_TOTAL bytes"
echo "ROM 已用: $USED_ROM bytes (code=$CSEG const=$CONST)"
echo "ROM 使用率: $(percent $USED_ROM $ROM_TOTAL)%"
echo ""
echo "RAM 总量: $RAM_TOTAL bytes"
echo "RAM 已用: $USED_RAM bytes (idata=$DSEG pdata=$PSEG xdata=$XSEG)"
echo "RAM 使用率: $(percent $USED_RAM $RAM_TOTAL)%"
echo "----------------------------------------"


# Top modules by C: entries (module name after C:)
# We'll convert the hex sizes to decimal using shell helper then aggregate with awk.
TMPFILE="/tmp/map_report.$$"
rm -f "$TMPFILE"
# Build a sorted list of symbol addresses and their module
awk '/^ *C:/ { addr=$2; sym=$3; mod=$NF; if (addr!="" && sym!="") print addr, sym, mod }' "$MAPFILE" | sed 's/\.rel//; s/\.o//; s/\.obj//' | \
while read HEX SYM MOD; do
    [ -z "$HEX" -o -z "$SYM" ] && continue
    DEC=$(hex2dec "$HEX")
    printf "%d %s %s\n" "$DEC" "$SYM" "$MOD" >> "$TMPFILE"
done

if [ -f "$TMPFILE" ]; then
    SORTED="/tmp/map_report_sorted.$$"
    sort -n "$TMPFILE" > "$SORTED"

    # compute deltas between consecutive symbols and attribute delta to the symbol (function)
    # SORTED format: <addr> <symbol> <module>
    SYMBOL_SIZES="/tmp/map_report_sym_sizes.$$"
    awk -v cseg_end="$CSEG_END" '
    { addr[NR]=$1; sym[NR]=$2; mod[NR]=$3 }
    END {
        for(i=1;i<=NR;i++) {
            if (i<NR) delta = addr[i+1]-addr[i]; else delta = cseg_end - addr[i];
            if (delta<0) delta=0;
            printf "%d %s %s\n", delta, sym[i], mod[i];
        }
    }' "$SORTED" > "$SYMBOL_SIZES"

    echo "Top 20 函数（按占用字节）:"
    # Print header with tabs, then nicely aligned rows: Rank, Bytes, Function, Module
    printf "%-4s\t%8s\t%-30s\t%s\n" "#" "Bytes" "Function" "Module"
    sort -nr "$SYMBOL_SIZES" | head -n 20 | awk 'BEGIN{rank=0} {rank++; printf "%-4d\t%8d\t%-30s\t%s\n", rank, $1, $2, $3}'

    rm -f "$SYMBOL_SIZES"

    rm -f "$TMPFILE" "$SORTED"
fi

exit 0

汇编代码初始化数组

Tue, 30 Dec 2025 00:00:00 GMT

初始化数组（存储在RAM中）

方法1：使用DS在RAM中预留空间

ORG 30H            ; 从30H开始分配RAM变量

; 未初始化的数组（预留空间）
BUFFER:      DS    16      ; 预留16字节的缓冲区
TEMP_ARRAY:  DS    8       ; 预留8字节的温度数组
RESULTS:     DS    32      ; 预留32字节的结果数组

; 混合定义
DATA_AREA:
VAR1:        DS    1       ; 单个字节变量
ARRAY1:      DS    10      ; 10字节数组
VAR2:        DS    1       ; 另一个变量

方法2：运行时初始化数组

; 初始化RAM数组的函数
INIT_ARRAYS:
    ; 初始化BUFFER数组为0
    MOV R0, #BUFFER       ; 数组起始地址
    MOV R2, #16           ; 数组长度
    CLR A                 ; A = 0
INIT_LOOP1:
    MOV @R0, A            ; 清零数组元素
    INC R0
    DJNZ R2, INIT_LOOP1
    
    ; 初始化TEMP_ARRAY为特定值
    MOV R0, #TEMP_ARRAY
    MOV @R0, #20          ; TEMP_ARRAY[0] = 20
    INC R0
    MOV @R0, #25          ; TEMP_ARRAY[1] = 25
    INC R0
    MOV @R0, #30          ; TEMP_ARRAY[2] = 30
    ; ... 继续初始化
    
    RET

访问常数变量和数组

1. 访问ROM中的常数（使用MOVC）

; 读取SINE_TABLE中的第3个元素
READ_SINE_VALUE:
    MOV DPTR, #SINE_TABLE   ; 设置表基址
    MOV A, #2               ; 索引2（第3个元素）
    MOVC A, @A+DPTR         ; A = SINE_TABLE[2] = 25
    RET

; 读取字符串中的字符
READ_MESSAGE_CHAR:
    MOV DPTR, #MESSAGE      ; 字符串地址
    MOV R2, #0              ; 字符索引
READ_LOOP:
    MOV A, R2               ; 索引到A
    MOVC A, @A+DPTR         ; 读取字符
    JZ END_OF_STRING        ; 如果是0，字符串结束
    ; 处理字符...
    INC R2                  ; 下一个字符
    SJMP READ_LOOP
END_OF_STRING:
    RET

2. 访问RAM中的数组

; 通过索引访问数组元素
ACCESS_ARRAY_ELEMENT:
    ; 参数：R7 = 数组索引
    ; 返回：A = 数组元素
    
    MOV A, R7              ; 索引到A
    ADD A, #BUFFER         ; 计算实际地址
    MOV R0, A              ; R0指向数组元素
    MOV A, @R0             ; 读取数组元素
    RET

; 遍历数组（求数组元素之和）
SUM_ARRAY:
    MOV R0, #BUFFER        ; 数组起始地址
    MOV R2, #16            ; 数组长度
    CLR A                  ; 累加器清零
    CLR B                  ; 进位清零
SUM_LOOP:
    ADD A, @R0             ; 累加数组元素
    JNC NO_CARRY
    INC B                  ; 处理进位
NO_CARRY:
    INC R0                 ; 下一个元素
    DJNZ R2, SUM_LOOP
    
    ; 结果：A=低8位，B=高8位（进位）
    RET

3. 多维数组访问

; 二维数组（3x4矩阵）
MATRIX_ROWS   EQU    3
MATRIX_COLS   EQU    4
MATRIX_SIZE   EQU    MATRIX_ROWS * MATRIX_COLS

MATRIX: DS MATRIX_SIZE     ; 3x4矩阵

; 访问MATRIX[row][col]
; 参数：R6 = 行号(0-2), R7 = 列号(0-3)
; 返回：A = MATRIX[row][col]
ACCESS_MATRIX:
    MOV A, R6              ; 行号
    MOV B, #MATRIX_COLS    ; 每行4列
    MUL AB                 ; A = 行号 * 4
    ADD A, R7              ; + 列号
    ADD A, #MATRIX         ; + 矩阵基址
    MOV R0, A              ; R0指向矩阵元素
    MOV A, @R0             ; 读取元素
    RET

结构体类型的数据组织

1. 定义数据结构

; 定义学生记录结构
STUDENT_SIZE EQU 4
STUDENT_AGE   EQU 0     ; 偏移0：年龄
STUDENT_GRADE EQU 1     ; 偏移1：成绩
STUDENT_ID_H  EQU 2     ; 偏移2：ID高字节
STUDENT_ID_L  EQU 3     ; 偏移3：ID低字节

; 学生数组（3个学生）
STUDENTS: DS STUDENT_SIZE * 3

; 常量学生数据（ROM中的模板）
STUDENT_TEMPLATE:
    DB 18, 85, 0, 1      ; 学生1：18岁，成绩85，ID=0001
    DB 19, 90, 0, 2      ; 学生2：19岁，成绩90，ID=0002
    DB 20, 78, 0, 3      ; 学生3：20岁，成绩78，ID=0003

2. 访问结构体数组

; 获取第n个学生的成绩
; 参数：R7 = 学生索引(0-2)
; 返回：A = 成绩
GET_STUDENT_GRADE:
    MOV A, R7              ; 学生索引
    MOV B, #STUDENT_SIZE   ; 每个学生大小
    MUL AB                 ; A = 索引 * 4
    ADD A, #STUDENTS       ; + 基址
    ADD A, #STUDENT_GRADE  ; + 成绩偏移
    MOV R0, A              ; R0指向成绩字段
    MOV A, @R0             ; 读取成绩
    RET

; 初始化学生数组
INIT_STUDENTS:
    MOV DPTR, #STUDENT_TEMPLATE
    MOV R0, #STUDENTS      ; RAM目标地址
    MOV R2, #3             ; 3个学生
INIT_STU_LOOP1:
    MOV R3, #STUDENT_SIZE  ; 每个学生4字节
INIT_STU_LOOP2:
    CLR A
    MOVC A, @A+DPTR        ; 从ROM读取
    MOV @R0, A             ; 写入RAM
    INC DPTR
    INC R0
    DJNZ R3, INIT_STU_LOOP2
    DJNZ R2, INIT_STU_LOOP1
    RET

高级技巧：使用宏和标号

1. 定义带类型的数组访问宏

; 定义数组访问宏
ARRAY_GET MACRO ARRAY_NAME, INDEX, DEST
    MOV A, INDEX
    ADD A, #ARRAY_NAME
    MOV R0, A
    MOV DEST, @R0
    ENDM

ARRAY_SET MACRO ARRAY_NAME, INDEX, SRC
    MOV A, INDEX
    ADD A, #ARRAY_NAME
    MOV R0, A
    MOV @R0, SRC
    ENDM

; 使用宏
    MOV R1, #2            ; 索引2
    ARRAY_GET BUFFER, R1, A    ; A = BUFFER[2]
    
    MOV R1, #3
    MOV R2, #0FFH
    ARRAY_SET BUFFER, R1, R2   ; BUFFER[3] = 0FFH

2. 使用标号计算数组大小

; 自动计算数组大小
CONST_ARRAY_START:
    DB 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
CONST_ARRAY_END:

CONST_ARRAY_SIZE EQU CONST_ARRAY_END - CONST_ARRAY_START

; 编译时会计算：CONST_ARRAY_SIZE = 10

完整示例程序

; 定义常数
ORG 1000H
PI:          DB    22, 7          ; π ≈ 22/7
DAYS_IN_MONTH:
    DB 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31

; 定义RAM变量
ORG 30H
TEMPERATURES: DS   24      ; 24小时温度数据
DAILY_MAX:    DS   1       ; 日最高温度
DAILY_MIN:    DS   1       ; 日最低温度

; 主程序
ORG 0000H
    MOV SP, #60H
    
    ; 初始化温度数组为20°C
    CALL INIT_TEMP_ARRAY
    
    ; 读取下午2点的温度（索引14）
    MOV R7, #14
    CALL GET_TEMPERATURE   ; A = TEMPERATURES[14]
    
    ; 查找最高温度
    CALL FIND_MAX_TEMP     ; A = 最高温度
    MOV DAILY_MAX, A
    
    ; 使用常数表：获取7月的天数
    MOV DPTR, #DAYS_IN_MONTH
    MOV A, #6              ; 7月是第7个月，索引6
    MOVC A, @A+DPTR        ; A = 31
    
    SJMP $

; 初始化温度数组
INIT_TEMP_ARRAY:
    MOV R0, #TEMPERATURES
    MOV R2, #24
    MOV R3, #20            ; 初始温度20°C
INIT_TEMP_LOOP:
    MOV @R0, R3
    INC R0
    DJNZ R2, INIT_TEMP_LOOP
    RET

; 获取温度值
GET_TEMPERATURE:      ; R7 = 小时(0-23)
    MOV A, R7
    ADD A, #TEMPERATURES
    MOV R0, A
    MOV A, @R0
    RET

; 查找最高温度
FIND_MAX_TEMP:
    MOV R0, #TEMPERATURES
    MOV R2, #24
    CLR A                ; A = 0（当前最大值）
FIND_MAX_LOOP:
    MOV B, @R0
    CJNE A, B, COMPARE
COMPARE:
    JNC NOT_HIGHER       ; 如果A >= B，跳过
    MOV A, B             ; 更新最大值
NOT_HIGHER:
    INC R0
    DJNZ R2, FIND_MAX_LOOP
    RET

重要提示：

ROM常数：使用DB/DW定义，用MOVC指令访问
RAM数组：使用DS预留空间，运行时初始化
地址计算：访问数组元素时，基址+偏移量计算地址
索引边界：始终检查数组索引是否越界
性能考虑：频繁访问的数组放在直接寻址区域（00H-7FH）

自建服务器搭建git远程仓库

Tue, 25 Nov 2025 00:00:00 GMT

服务器操作

sudo yum install git

# 创建git用户
sudo adduser git

添加远程访问者的ssh密钥

在本地~/.ssh/id_rsa.pub中复制自己的ssh公钥到服务器/home/git/.ssh/authorized_keys中

# 本地执行，复制输出的密钥
cat ~/.ssh/id_rsa.pub

# 服务器执行，将复制来的密钥添加到文件中，一个密钥一行
vim /home/git/.ssh/authorized_keys

# 也可以自行生成一个新的密钥
ssh-keygen -t rsa -b 4096 -C "助记词(一般是邮箱)"

# 将新生成的密钥加入ssh钥匙串
ssh-add "~/.ssh/id_rsa(新生成的私钥路径)"

创建git仓库

在~/ /home/git家目录下执行

mkdir gitrepo

# 创建一个裸仓库(没有工作区，只用于文件共享)
git init --bare myrepo.git

本地操作

A. 从新仓库开始(克隆)

git clone git@xxx.com:/home/git/gitrepo/myrepo.git

B. 为已有仓库添加新的远程仓库

# 添加远程仓库
git remote add my_origin git@xxx.com:/home/git/gitrepo/myrepo.git

# 显示所有远程仓库配置
git remote -v

# 展示远程仓库状态
git remote show my_origin

# 推送到远程仓库，好耶！
git push my_origin

Linux系统备份方案

Fri, 21 Nov 2025 00:00:00 GMT

Linux系统备份方案

备份策略概述

架构：两地三介质
冗余级别：HDD RAID1
数据分类：
- 系统核心文件：6份备份
- 用户文档：3份备份
备份类型
- 完整压缩：clonezilla
- 增量：timeshift
- 反向增量：rdiff-backup

备份计划表

备份内容	介质	备份方式	周期	覆盖周期
系统镜像	HDD	完整压缩	每月	3个月
系统镜像	网盘	完整压缩	每月	6个月
系统镜像	BD	完整压缩	每月	无限
系统快照	HDD	增量	每天	14天
系统快照	BD	完整	每周	无限
系统快照	网盘	完整	每周	4周
用户文档	HDD	反向增量	每天	60天
用户文档	Server	反向增量	每天	60天
用户文档	DVD	完整	每周	无限

恢复测试计划

周期：每3个月（在所有新的备份工作完成后）

测试项目

系统完整镜像恢复测试
- 将新的系统完整镜像恢复到另一台电脑
- 测试是否启动成功
系统快照回退测试
- 从HDD和BD分别随机选择一个系统快照版本
- 使用live系统进入，将系统回退到此快照版本
- 测试是否启动成功
介质读取测试
- 随机抽选一张BD和一张DVD
- 测试读取是否成功
- 验证文件内容是否正确

sdcc汇编伪指令

Fri, 21 Nov 2025 00:00:00 GMT

汇编助记符中的符号含义

符号	含义	说明
Rn	工作寄存器 R0~R7	n 可取 0~7，表示当前寄存器组中的寄存器
Ri	间接寻址寄存器 R0 或 R1	i 可取 0 或 1，用于间接寻址
@Ri	以 Ri 中的值为地址，访问该地址的数据	间接寻址方式，Ri 中存放的是内存地址
#data	立即数	直接跟在指令后的常数，如 `#30H`
direct	直接地址	8位内部 RAM 地址或 SFR 地址，如 `30H` 或 `P1`

SDCC伪指令详细说明及示例

一、段定义伪指令（.area）

1. 基本格式

.area 段名 (属性1,属性2,...) [重定位类型]

2. 常用段类型

; 代码段（程序存储器）
.area CSEG (CODE)       ; 常规代码段
.area HOME (CODE)       ; 起始段（0x0000-0x00FF）
.area GSINIT (CODE)     ; 全局变量初始化代码
.area GSFINAL (CODE)    ; 初始化后的代码

; 数据段
.area DSEG (DATA)       ; 内部可直接寻址数据（0x30-0x7F）
.area ISEG (DATA)       ; 内部间接寻址数据（0x80-0xFF）
.area OSEG (DATA)       ; 覆盖数据段
.area XSEG (XDATA)      ; 外部数据存储器
.area ESEG (EDATA)      ; 扩展数据存储器（STC8G特有）

; 其他
.area RSEG (ABS)        ; 绝对定位段
.area ASEG (ABS)        ; 绝对段（已过时）
.area BSEG (BIT)        ; 位寻址区（0x20-0x2F）

3. 段属性

CODE - 程序代码
DATA - 内部RAM数据
XDATA - 外部RAM数据
EDATA - 扩展RAM数据（STC8G）
ABS - 绝对地址
BSS - 未初始化数据
BIT - 位数据
OVR - 可覆盖段
REL - 可重定位段
CON - 常量段

4. 示例

; 定义绝对地址中断向量表
.area VEC (ABS)
.org 0x0000
    ljmp   _main          ; 复位向量
.org 0x0003
    ljmp   _ext0_isr      ; 外部中断0
.org 0x000B
    ljmp   _timer0_isr    ; 定时器0中断

; 代码段
.area CSEG (CODE)
_main:
    mov    SP, #0x80      ; 设置堆栈指针

; 内部数据段
.area DSEG (DATA)
counter:
    .byte 0x00           ; 单字节变量
buffer:
    .ds   16             ; 16字节缓冲区

; 外部数据段
.area XSEG (XDATA)
large_buffer:
    .ds   1024           ; 1KB外部缓冲区

; 位寻址区
.area BSEG (BIT)
flag1:   .dbits 1        ; 定义1个位
flags:   .dbits 8        ; 定义8个位（1字节）

二、数据定义伪指令

1. 字节数据

; 定义字节（8位）
.byte value1, value2, ...    ; 定义字节序列
.db   value1, value2, ...    ; 同.byte

; 示例
data1:  .byte 0x12           ; 单个字节
table:  .byte 0, 1, 2, 3, 4  ; 数组
str:    .byte 'H','e','l','l','o',0  ; 字符串

2. 字数据

; 定义字（16位）
.word value1, value2, ...    ; 定义字序列（小端序）
.dw   value1, value2, ...    ; 同.word

; 示例
vectors: .word 0x0000, 0x1000, 0x2000  ; 地址表
const:   .dw   0x1234, 0x5678          ; 16位常量

3. 双字数据

; 定义双字（32位）
.long value1, value2, ...    ; 32位数据
.dl   value1, value2, ...    ; 同.long

; 示例
long_val: .long 0x12345678   ; 32位值
float_val: .long 0x4048F5C3  ; 浮点数（3.14的IEEE754表示）

4. 浮点数

; 定义浮点数
.float value1, value2, ...   ; 单精度浮点数

; 示例
pi:     .float 3.1415926
temp:   .float 25.5

5. 字符串

; ASCII字符串
.ascii "string"              ; 无结束符
.asciz "string"             ; 以\0结尾

; 示例
msg1:   .ascii "Error"       ; 长度5
msg2:   .asciz "Hello"       ; 长度6（含\0）

6. 保留空间

.ds size                     ; 保留size字节空间
.blkb size                   ; 同.ds（块）

; 示例
buffer: .ds 100              ; 100字节缓冲区
stack:  .blkb 32             ; 32字节堆栈空间

7. 位数据

; 位定义（仅用于BSEG段）
.dbits size                  ; 定义size个位

; 示例
.area BSEG (BIT)
flags:  .dbits 8             ; 8个标志位
status: .dbits 1             ; 单状态位

三、符号定义伪指令

1. 常量定义

; 等值定义
.equ symbol, value           ; 定义符号常量
.set  symbol, value          ; 同.equ（可重复定义）
=      symbol = value        ; 另一种形式

; 示例
.equ BUFFER_SIZE, 256        ; 定义常量
.set  COUNTER_MAX, 1000
TIMEOUT = 5000               ; 使用等号

2. 全局符号声明

.globl symbol                ; 声明全局符号
.global symbol               ; 同.globl
.gblel symbol                ; 声明全局外部符号

; 示例
.globl _main                 ; C主函数
.globl _isr_timer0           ; 中断服务函数

3. 外部符号声明

.extern symbol               ; 声明外部符号
.external symbol             ; 同.extern

; 示例
.extern _printf              ; 外部C函数
.extern buffer               ; 外部变量

四、条件汇编伪指令

1. 基本条件

; 条件块
.if condition                ; 开始条件
.else                        ; 否则分支
.endif                       ; 结束条件

; 示例
.if DEBUG == 1
    mov   A, #0x55           ; 调试代码
.else
    mov   A, #0xAA           ; 发布代码
.endif

2. 符号条件

; 符号检查
.ifdef symbol                ; 如果符号已定义
.ifndef symbol               ; 如果符号未定义

; 示例
.ifdef USE_UART
    call  uart_init          ; 如果定义了USE_UART
.endif

.ifndef OPTIMIZE
    nop                      ; 如果没有优化
.endif

3. 比较条件

; 比较表达式
.ifeq expression             ; 如果等于
.ifne expression             ; 如果不等于
.ifgt expression             ; 如果大于
.ifge expression             ; 如果大于等于
.iflt expression             ; 如果小于
.ifle expression             ; 如果小于等于

; 示例
.ifeq VERSION-2
    ljmp  legacy_code        ; VERSION==2时
.else
    ljmp  new_code           ; 其他情况
.endif

五、宏定义与使用

1. 基本宏定义

; 宏定义
.macro macroname [param1, param2, ...]  ; 定义宏
    ; 宏体
.endm                                   ; 结束宏

; 示例：延时宏
.macro DELAY cycles
    mov   R7, #(\cycles & 0xFF)         ; 使用参数
    djnz  R7, $
.endm

; 使用宏
DELAY 100     ; 扩展为：mov R7, #100; djnz R7, $
DELAY 255     ; 扩展为：mov R7, #255; djnz R7, $

2. 带参数的宏

; 带多个参数的宏
.macro MOV16 src, dst
    mov   A, \src            ; 参数前加反斜杠
    mov   \dst, A
    mov   A, \src+1
    mov   \dst+1, A
.endm

; 使用
MOV16 #0x1234, R6    ; 将16位值传送到R6:R7

3. 局部标签宏

; 带局部标签的宏
.macro DELAY_MS ms
    mov   R5, #\ms
1$:                         ; 局部标签（数字+$）
    mov   R6, #200
2$:
    mov   R7, #250
    djnz  R7, $
    djnz  R6, 2$
    djnz  R5, 1$
.endm

4. 条件宏

; 条件判断宏
.macro BIT_SET reg, bit
    .if \bit < 8
        setb \reg.\bit      ; 使用位操作符
    .else
        .error "Bit out of range"
    .endif
.endm

; 使用
BIT_SET P1, 0        ; setb P1.0
BIT_SET ACC, 3       ; setb ACC.3

5. 嵌套宏

; 宏嵌套
.macro PUSH_REG reg
    push  \reg
.endm

.macro PUSH_REGS regs
    .irp reg, \regs        ; 迭代参数列表
        PUSH_REG \reg
    .endm
.endm

; 使用
PUSH_REGS ACC, B, PSW    ; 压栈多个寄存器

6. 宏函数示例

; 计算平方的宏函数
.macro SQUARE x, result
    mov   A, #\x
    mov   B, A
    mul   AB
    mov   \result, A       ; 低8位
    mov   \result+1, B     ; 高8位
.endm

; 使用
SQUARE 5, square_result

; 带返回值的宏
.macro ADD16 a, b
    mov   A, \a
    add   A, \b
    mov   R0, A
    mov   A, \a+1
    addc  A, \b+1
    mov   R1, A
    ; 结果在R0:R1中
.endm

六、包含文件与模块化

1. 包含文件

.include "filename.inc"    ; 包含汇编文件
.include <stddef.h>       ; 包含C头文件（需要-i指定路径）

; 示例
.include "stc8g.h"
.include "macros.inc"
.include "config.inc"

2. 模块化组织

; 主文件 main.asm
.module main
.globl _main

.include "uart.inc"
.include "timer.inc"

_main:
    call  uart_init
    call  timer_init
    ; ...

; 子模块 uart.inc
.module uart
.globl uart_init, uart_send

uart_init:
    ; ...
    ret

uart_send:
    ; ...
    ret

七、地址控制伪指令

1. 地址定位

.org address               ; 设置当前位置
.radix base                ; 设置数字基数（2,8,10,16）

; 示例
.radix 16                  ; 设置为16进制
.org   1000H               ; 从1000H开始
    .byte 1,2,3,4
.org   2000H               ; 跳转到2000H
    .word 1234H

2. 对齐

.even                      ; 对齐到偶数地址
.odd                       ; 对齐到奇数地址
.align power               ; 对齐到2^power边界

; 示例
.align 4                   ; 对齐到16字节边界
data: .ds 10

.even                      ; 确保下面代码在偶地址
code: mov A, #0

八、列表控制伪指令

1. 列表文件控制

.list                      ; 开启列表
.nolist                    ; 关闭列表
.lst                       ; 生成列表文件
.nolst                     ; 不生成列表文件

; 示例
.nolist                    ; 不列出包含文件内容
.include "macros.inc"
.list                      ; 恢复列表

2. 其他控制

.title "标题"              ; 设置标题
.sbttl "子标题"            ; 设置子标题
.page                      ; 分页
.width columns             ; 设置列宽

九、标签的 : 和 :: 区别

1. 单冒号 :（局部标签）

; 局部标签（默认）
label1:                    ; 局部标签，文件内可见
    nop

; 示例
loop:                      ; 局部循环标签
    djnz R7, loop          ; 可访问
    
func1:
    call subfunc
    ret
    
subfunc:                   ; 另一个局部标签
    nop
    ret

2. 双冒号 ::（全局标签）

; 全局标签
label2::                   ; 全局标签，外部可访问

; 示例
.globl _main               ; 需要配合.globl声明
_main::                    ; C入口函数（全局）
    mov SP, #0x80

; 中断服务函数（全局）
_ext0_isr::
    push PSW
    ; ... 中断处理
    pop PSW
    reti

; 在另一个文件中可这样引用
.extern _main              ; 声明外部全局符号
.extern _ext0_isr

3. 标签作用域规则

; 文件: module1.asm
.local_label:              ; 仅本文件可见
    nop
    
global_label::             ; 全局可见（自动.globl）
    nop

.globl exported_label      ; 需要显式声明
exported_label:            ; 全局可见（需.globl）
    nop

; 文件: module2.asm
.extern global_label       ; 引用全局标签
.extern exported_label

call global_label          ; 可调用
call exported_label        ; 可调用
; call local_label        ; 错误！不可访问

4. 数字标签（局部）

; 数字标签（自动局部）
1:                         ; 数字标签，可重复定义
    nop
    jb   P1.0, 1b          ; 向后跳转到最近的1:
    
2:                         ; 另一个数字标签
    nop
    jnb  P1.1, 2f          ; 向前跳转到下一个2:

; 示例：循环中使用
    mov  R7, #10
1$:                        ; 带$的数字标签（推荐）
    djnz R7, 1$            ; 向后跳转

; 嵌套循环
    mov  R6, #5
2$:
    mov  R7, #10
1$:
    djnz R7, 1$
    djnz R6, 2$

十、完整示例

; ============================================
; STC8G 汇编程序示例
; ============================================

; 包含头文件
.include "stc8g.inc"

; 常量定义
.equ BUFFER_SIZE,  256
.equ LED_PIN,      P1_0
.equ BUTTON_PIN,   P3_2
.set  TIMEOUT,     1000

; 宏定义
.macro DELAY_US us
    .if \us > 0
        mov  R7, #((\us * 2) & 0xFF)
    1$: djnz R7, 1$
    .endif
.endm

.macro LED_ON
    setb LED_PIN
.endm

.macro LED_OFF
    clr  LED_PIN
.endm

.macro TOGGLE_LED
    cpl  LED_PIN
.endm

; 位定义
.area BSEG (BIT)
button_flag:   .dbits 1    ; 按键标志
tx_busy:       .dbits 1    ; 发送忙标志
rx_ready:      .dbits 1    ; 接收就绪标志

; 数据段
.area DSEG (DATA)
counter:      .byte 0
buffer:       .ds   BUFFER_SIZE
tx_index:     .byte 0
rx_index:     .byte 0

; 绝对地址段（中断向量）
.area VEC (ABS)
.org 0x0000
    ljmp   _main           ; 复位向量

.org 0x0003
    ljmp   ext0_isr        ; INT0中断

.org 0x000B
    ljmp   timer0_isr      ; Timer0中断

.org 0x0023
    ljmp   uart_isr        ; UART中断

; 代码段
.area CSEG (CODE)

; ============================================
; 主程序
; ============================================
.globl _main
_main::
    ; 初始化堆栈
    mov   SP, #0x80
    
    ; 初始化端口
    mov   P1M0, #0x01      ; P1.0推挽输出
    mov   P1M1, #0x00
    
    ; 初始化定时器
    call  timer0_init
    
    ; 初始化串口
    call  uart_init
    
    ; 使能中断
    setb  EA
    setb  EX0              ; 使能INT0
    setb  ET0              ; 使能Timer0
    setb  ES               ; 使能串口中断
    
    ; 主循环
main_loop:
    ; 检查按键
    jnb   button_flag, no_button
    clr   button_flag
    
    ; 按键处理
    TOGGLE_LED
    call  send_message
    
no_button:
    ; 检查接收数据
    jnb   rx_ready, main_loop
    clr   rx_ready
    
    ; 处理接收数据
    call  process_data
    
    sjmp  main_loop

; ============================================
; 延时函数（毫秒）
; 使用宏实现
; ============================================
.macro DELAY_MS ms
    push  ACC
    push  PSW
    mov   A, #\ms
    call  delay_ms_func
    pop   PSW
    pop   ACC
.endm

; 实际的延时函数
delay_ms_func:
    mov   R6, A
1$: mov   R7, #200
2$: mov   R8, #250
3$: djnz  R8, 3$
    djnz  R7, 2$
    djnz  R6, 1$
    ret

; ============================================
; 中断服务函数
; ============================================
ext0_isr::
    push  PSW
    push  ACC
    
    ; 防抖延时
    DELAY_US 100
    
    ; 设置按键标志
    setb  button_flag
    
    pop   ACC
    pop   PSW
    reti

timer0_isr::
    push  PSW
    push  ACC
    
    ; 定时器处理
    inc   counter
    
    ; 1秒闪烁
    mov   A, counter
    anl   A, #0x80
    jz    timer_done
    TOGGLE_LED
    
timer_done:
    pop   ACC
    pop   PSW
    reti

uart_isr::
    push  PSW
    push  ACC
    
    ; 串口中断处理
    jnb   RI, uart_tx_check
    clr   RI
    
    ; 接收数据
    mov   A, SBUF
    call  store_rx_data
    
uart_tx_check:
    jnb   TI, uart_done
    clr   TI
    setb  tx_busy          ; 发送完成
    
uart_done:
    pop   ACC
    pop   PSW
    reti

; ============================================
; 子函数
; ============================================
; 初始化定时器0
timer0_init::
    mov   TMOD, #0x01      ; 定时器0模式1
    mov   TH0, #0xFC       ; 1ms定时
    mov   TL0, #0x66
    setb  TR0              ; 启动定时器
    ret

; 初始化串口
uart_init::
    mov   SCON, #0x50      ; 模式1，允许接收
    mov   PCON, #0x80      ; 波特率加倍
    mov   TH1, #0xFD       ; 9600 bps @11.0592MHz
    mov   TL1, #0xFD
    setb  TR1              ; 启动定时器1
    ret

; 存储接收数据
store_rx_data:
    push  PSW
    mov   PSW, #0x10       ; 使用第2组寄存器
    
    mov   R0, rx_index
    mov   @R0, A           ; 存储数据
    inc   rx_index
    
    ; 设置接收就绪标志
    setb  rx_ready
    
    pop   PSW
    ret

; 发送消息
send_message::
    mov   DPTR, #welcome_msg
    call  send_string
    ret

; 发送字符串
send_string:
    push  ACC
1$: clr   A
    movc  A, @A+DPTR
    jz    send_done
    call  send_char
    inc   DPTR
    sjmp  1$
send_done:
    pop   ACC
    ret

; 发送单个字符
send_char:
    jnb   tx_busy, $       ; 等待发送完成
    clr   tx_busy
    mov   SBUF, A
    ret

; 处理数据
process_data::
    ; 处理接收缓冲区数据
    ret

; ============================================
; 常量数据
; ============================================
welcome_msg:
    .asciz "STC8G Ready!\r\n"

; ============================================
; 程序结束
; ============================================
    .end

十一、编译与链接

1. 编译命令

# 编译汇编文件
sdcc -c -mmcs51 --model-small example.asm

# 编译C文件（含内联汇编）
sdcc -c -mmcs51 --model-small main.c

# 链接目标文件
sdcc -mmcs51 --model-small example.rel main.rel

# 生成Intel HEX文件
packihx example.ihx > example.hex

2. Makefile示例

TARGET = example
SRCS = main.asm uart.asm timer.asm
OBJS = $(SRCS:.asm=.rel)

CC = sdcc
CFLAGS = -mmcs51 --model-small --opt-code-size

all: $(TARGET).hex

$(TARGET).hex: $(OBJS)
	$(CC) $(CFLAGS) $(OBJS) -o $(TARGET).ihx
	packihx $(TARGET).ihx > $(TARGET).hex

%.rel: %.asm
	$(CC) -c $(CFLAGS) $<

clean:
	rm -f *.rel *.asm *.lst *.sym *.ihx *.hex *.map

十二、注意事项

大小写敏感：SDCC汇编器是大小写敏感的
下划线规则：C函数在汇编中前加下划线（如 _main）
参数传递：通过寄存器R5-R7传递参数
返回值：8位在A中，16位在DPL/DPH中
内存模型：使用 --model-small、--model-medium、--model-large 指定
优化选项：使用 --opt-code-size 或 --opt-code-speed
调试信息：使用 --debug 生成调试信息

rdiff-backup 反向增量备份

Thu, 20 Nov 2025 00:00:00 GMT

📋 rdiff-backup 2.x 新版语法结构

基本语法格式

rdiff-backup [全局选项...] <动作> [子选项...] [路径...]

🔧 常用动作详解

备份 (backup)

命令	说明	示例
`rdiff-backup backup <源目录> <目标目录>`	基本备份	`rdiff-backup backup /home/user /backup`
`--exclude <模式>`	排除文件/目录	`--exclude "/home/user/tmp"`
`--include <模式>`	包含文件/目录	`--include "/home/user/important"`
`--print-statistics`	显示备份统计	`backup --print-statistics`
`--compression`	启用压缩(默认)	`backup --compression`
`--no-compression`	禁用压缩	`backup --no-compression`

完整备份示例：

rdiff-backup --api-version 201 backup \
    --exclude "/home/mint/Documents/xwechat_files" \
    --print-statistics \
    "/home/mint/Documents" \
    "/media/mint/H/Documents_backup"

列出备份点 (list increments)

命令	说明	示例
`rdiff-backup list increments <备份目录>`	列出所有备份点	`list increments /backup`
`--size`	显示备份点大小	`list increments --size /backup`
`--no-size`	不显示大小(默认)	`list increments --no-size /backup`
`--parsable-output`	机器可读格式	`list increments --parsable-output /backup`

使用示例：

# 列出所有备份点
rdiff-backup --api-version 201 list increments "/media/mint/H/Documents_backup"

# 显示备份点大小
rdiff-backup --api-version 201 list increments --size "/media/mint/H/Documents_backup"

恢复文件 (restore)

命令	说明	示例
`rdiff-backup restore --at <时间> <源目录> <目标目录>`	恢复到指定时间	`restore --at 3D /backup /restore`
`--at now`	最新状态	`restore --at now /backup /restore`
`--at 3D`	3天前	`restore --at 3D /backup /restore`
`--at 2W`	2周前	`restore --at 2W /backup /restore`
`--at 1M`	1个月前	`restore --at 1M /backup /restore`
`--at 2024-11-20T10:00:00`	精确时间	`restore --at "2024-11-20T10:00:00" /backup /restore`
`--at 5B`	第5个备份点	`restore --at 5B /backup /restore`

恢复示例：

# 恢复到3天前的状态
rdiff-backup --api-version 201 restore \
    --at 3D \
    "/media/mint/H/Documents_backup" \
    "/home/mint/Documents_restored"

# 恢复到特定日期
rdiff-backup --api-version 201 restore \
    --at "2024-11-20T10:00:00" \
    "/media/mint/H/Documents_backup" \
    "/home/mint/Documents_old"

查看文件列表 (list files)

命令	说明	示例
`rdiff-backup list files --at <时间> <备份目录>`	查看特定时间点的文件	`list files --at 1D /backup`
`list files --changed-since <时间> <备份目录>`	查看自某时间后变化的文件	`list files --changed-since 2D /backup`

使用示例：

# 查看3天前的文件列表
rdiff-backup --api-version 201 list files \
    --at 3D \
    "/media/mint/H/Documents_backup"

# 查看最近2天内变化的文件
rdiff-backup --api-version 201 list files \
    --changed-since 2D \
    "/media/mint/H/Documents_backup"

清理旧备份 (remove increments)

命令	说明	示例
`rdiff-backup remove increments --older-than <时间> <备份目录>`	删除旧备份点	`remove increments --older-than 30D /backup`
`--force`	强制删除多个会话	`remove increments --older-than 30D --force /backup`
`--size`	显示删除的备份大小	`remove increments --older-than 30D --size /backup`

清理示例：

# 删除30天前的备份点
rdiff-backup --api-version 201 remove increments \
    --older-than 30D \
    "/media/mint/H/Documents_backup"

# 强制删除60天前的所有备份点
rdiff-backup --api-version 201 remove increments \
    --older-than 60D \
    --force \
    "/media/mint/H/Documents_backup"

⚙️ 重要全局选项

选项	说明	示例
`--api-version 201`	使用新版API	`--api-version 201`
`--force`	强制操作(如覆盖目录)	`--force`
`--verbosity <0-9>`	设置详细级别	`--verbosity 5`
`--terminal-verbosity <0-9>`	终端输出详细级别	`--terminal-verbosity 3`
`--null-separator`	使用null分隔符	`--null-separator`

📁 文件选择选项

排除/包含模式

选项	说明	示例
`--exclude <模式>`	排除匹配的文件	`--exclude "*.tmp"`
`--include <模式>`	包含匹配的文件	`--include "*.doc"`
`--exclude-filelist <文件>`	从文件读取排除列表	`--exclude-filelist excludes.txt`
`--include-filelist <文件>`	从文件读取包含列表	`--include-filelist includes.txt`

特殊文件处理

选项	说明	示例
`--include-special-files`	包含设备文件等特殊文件	`--include-special-files`
`--exclude-special-files`	排除特殊文件	`--exclude-special-files`
`--max-file-size <大小>`	限制备份文件最大尺寸	`--max-file-size 1G`

🕒 时间格式说明

格式	说明	示例
`now`	当前时间	`--at now`
`3D`	3天前	`--at 3D`
`2W`	2周前	`--at 2W`
`1M`	1个月前	`--at 1M`
`5B`	第5个备份点	`--at 5B`
`2024-11-20T10:00:00`	精确时间	`--at "2024-11-20T10:00:00"`
`1234567890`	时间戳	`--at 1234567890`

🛠️ 实用脚本模板

完整备份脚本

#!/bin/bash
# complete_backup.sh

BACKUP_DIR="/media/mint/H/Documents_backup"
SOURCE_DIR="/home/mint/Documents"

echo "开始备份: $(date)"

# 执行备份
rdiff-backup --api-version 201 \
    backup \
    --exclude "/home/mint/Documents/xwechat_files" \
    --exclude "**/cache" \
    --exclude "**/tmp" \
    --print-statistics \
    "$SOURCE_DIR" "$BACKUP_DIR"

if [ $? -eq 0 ]; then
    echo "备份成功完成"
    
    # 显示备份点信息
    echo "=== 备份点列表 ==="
    rdiff-backup --api-version 201 list increments "$BACKUP_DIR"
    
    echo "=== 备份点大小 ==="
    rdiff-backup --api-version 201 list increments --size "$BACKUP_DIR"
    
    # 清理60天前的备份
    rdiff-backup --api-version 201 remove increments \
        --older-than 60D \
        "$BACKUP_DIR"
else
    echo "备份失败!"
    exit 1
fi

echo "备份结束: $(date)"

恢复脚本

#!/bin/bash
# restore_backup.sh

BACKUP_DIR="/media/mint/H/Documents_backup"

echo "可用的备份点:"
rdiff-backup --api-version 201 list increments "$BACKUP_DIR"

read -p "输入要恢复的时间点 (如 3D, 1W, 或时间戳): " restore_time

RESTORE_DIR="/home/mint/Documents_restored_$(date +%Y%m%d_%H%M%S)"

echo "正在恢复到: $RESTORE_DIR"
rdiff-backup --api-version 201 restore \
    --at "$restore_time" \
    "$BACKUP_DIR" "$RESTORE_DIR"

echo "恢复完成到: $RESTORE_DIR"

🔍 故障排除

常见问题解决

问题	解决方案
"invalid choice" 错误	确保选项在动作之前，动作在路径之前
备份目录不存在	使用 `--force` 初始化新仓库
权限错误	确保对源目录有读权限，目标目录有写权限
符号链接问题	使用物理路径而非符号链接路径

验证备份完整性

# 验证备份仓库
rdiff-backup --api-version 201 verify "/media/mint/H/Documents_backup"

# 比较当前目录与备份
rdiff-backup --api-version 201 compare \
    --at 1D \
    "/home/mint/Documents" \
    "/media/mint/H/Documents_backup"

这些命令基于 rdiff-backup 2.x 的新语法，避免了弃用警告，并提供了完整的备份、恢复和管理功能。

LinuxDir2html文件目录树创建方法

Wed, 19 Nov 2025 00:00:00 GMT

LinuxDir2html Github项目地址： ::github{repo="homeisfar/LinuxDir2HTML"}

用法

该程序需要两个必需参数：要建立索引的目录和不带扩展名的输出文件名。例如：

linuxdir2html ~/Pictures output

将索引内容/home/username/Pictures保存到output.html当前工作目录中。

额外选项

有五个可选标志：

-hidden 包含隐藏文件和目录。
-links 使 HTML 链接直接指向文件。
-symlink 跟踪符号链接。此标志很危险（可能导致循环引用）。
-silent 抑制输出。适用于脚本编写。仍会打印错误信息。
-verbose 额外的终端输出。不影响结果。

只有在确定需要时才应启用符号链接标志。

应用户要求，v1.4.0 版本新增了堆叠--startswith和--child参数功能[注意：自 v1.6.1 版本起，这些功能已被视为弃用，未来版本将移除。]。例如：

linuxdir2html --startswith 'dev' --child 'Pictures' ~ ~/output

将从用户主目录中选择以“dev”开头的目录以及名为“Pictures”的目录。此--startswith过滤器仅影响根搜索目录，所有子目录和文件都将被索引。隐藏标志可与 startswith 标志一起使用。

在linux下刻录光盘

Sat, 15 Nov 2025 00:00:00 GMT

Linux 下光盘刻录

制作iso镜像文件

# 基本参数
genisoimage -V "<盘名称>" -J -R -udf -allow-limited-size -o "<输出iso文件位置>" <要打包的目录>

# 基本示例
genisoimage -V "BD-1-2025-11-11" -J -R -udf -allow-limited-size -o "~/iso/BD-1-2025-11-11.iso" ~/Documents

参数	意义说明
-V	"BD-1-2025-11-11" 设置光盘卷标，在系统中显示为光盘名称
-J	生成 Joliet 目录记录，支持Windows长文件名
-R	使用 Rock Ridge 协议，保留Unix/Linux文件权限和符号链接
-udf	启用 UDF 文件系统，支持大于4GB的文件和更好的兼容性
-allow-limited-size	允许创建超过ISO 9660标准限制的镜像
-o "~/iso/BD-1-2025-11-11.iso"	指定输出ISO文件的路径和名称
~/Documents	要打包的源目录路径

🎯 其他常用可选参数

文件系统相关

参数	说明
-joliet-long	允许Joliet文件名达到103字符（默认64）
-ucs-level 3	使用UCS级别3，支持更多Unicode字符
-iso-level 4	使用ISO 9660版本4，支持更多特性
-no-iso-translate	禁止字符转换，保持原文件名

优化和性能

参数	说明
-sort	按文件名排序文件在光盘上的位置
-r	按反向顺序排序
-cache-inodes	缓存inode信息（Linux系统）
-no-cache-inodes	不缓存inode信息（其他系统）

文件过滤和排除

参数	说明
-exclude-list file.txt	从指定文件读取要排除的文件列表
-exclude "*.tmp"	排除所有.tmp文件
-path-list file.txt	只包含列表中的文件和目录

引导和特殊用途

参数	说明
-b boot.img	指定引导镜像文件
-c boot.catalog	指定引导目录文件
-no-emul-boot	非模拟模式启动
-boot-load-size 4	设置引导扇区加载大小
-hide file.txt	在ISO 9660中隐藏文件
-hide-joliet file.txt	在Joliet中隐藏文件

💡 实用命令示例

完整的推荐命令

genisoimage -V "BACKUP_2025" -J -joliet-long -R -udf -iso-level 4 \
  -allow-limited-size -cache-inodes -o "/backup/backup.iso" \
  -exclude "*.tmp" -exclude "*.log" /usr/total_backup

创建可启动备份

genisoimage -V "RESCUE_DISK" -J -R -udf -b boot/grub/stage2_eltorito \
  -no-emul-boot -boot-load-size 4 -boot-info-table \
  -allow-limited-size -o "/backup/rescue.iso" /rescue_files

带文件过滤的备份

# 创建排除列表文件
echo "*.tmp" > exclude-list.txt
echo "*.log" >> exclude-list.txt
echo "temp/" >> exclude-list.txt

genisoimage -V "CLEAN_BACKUP" -J -R -udf -allow-limited-size \
  -exclude-list exclude-list.txt -o "/backup/clean.iso" /usr/total_backup

启动刻录

growisofs -dvd-compat -speed=<速度> -Z <光驱位置>="<iso文件位置>"

growisofs -dvd-compat -speed=2 -Z /dev/sr0="~/iso/BD-1-2025-11-11.iso"

参数	说明	示例
基本操作
-Z	开始刻录到空白光盘	-Z /dev/sr0=file.iso
-M	追加刻录（多会话）	-M /dev/sr0=file2.iso
-dvd-compat	封闭光盘提高兼容性	-dvd-compat
速度控制
-speed=N	设置刻录速度	-speed=2
-s	模拟刻录（测试）	-s
缓存设置
-use-the-force-luke=bufsize:SIZE	设置缓冲区大小	bufsize:32m
-overburn	允许超刻（超过标称容量）	-overburn
光盘管理
-dvd-compat	完成后封闭光盘	-dvd-compat
-dao	使用 Disk-At-Once 模式	-dao
-sa	使用 Session-At-Once 模式	-sa
文件系统
-udf	使用 UDF 文件系统	-udf
-iso-level	设置 ISO 级别	-iso-level 3
-joliet	启用 Joliet 扩展	-joliet
-rock	启用 Rock Ridge 扩展	-rock
调试信息
-v	详细输出	-v
-dry-run	干运行（不实际刻录）	-dry-run
特殊选项
-use-the-force-luke=notray	不弹出光盘托盘	notray
-use-the-force-luke=tty	强制 TTY 输出	tty
-use-the-force-luke=4gms	使用 4GB 边界对齐	4gms

验证光盘

文件完整性验证

cmp -n $(stat -c%s image.iso) image.iso /dev/sr0

参数	含义
-n $(stat -c%s image.iso)	限制比较的字节数为原始 ISO 文件的大小
image.iso	原始 ISO 镜像文件
/dev/sr0	刻录后的光盘设备

工作原理：

stat -c%s image.iso 获取原始 ISO 文件的确切字节大小
cmp 读取光盘上前 N 个字节（N=ISO文件大小）与原始文件逐字节比较
如果完全一致，命令不输出任何内容（返回码 0）
如果发现差异，会报告第一个不匹配的位置

文件校验

步骤1：计算原始文件哈希

# 计算MD5（快速）
md5sum BD-1-2025-11-11.iso

步骤2：验证光盘内容

# 获取ISO文件大小
iso_size=$(stat -c%s "BD-1-2025-11-11.iso")

# 验证MD5
dd if=/dev/sr0 bs=1M 2>/dev/null | head -c $iso_size | md5sum

步骤3：自动化验证脚本

#!/bin/bash
ISO_FILE="BD-1-2025-11-11.iso"
CD_DEVICE="/dev/sr0"

echo "计算原始文件MD5..."
original_md5=$(md5sum "$ISO_FILE" | awk '{print $1}')

echo "计算光盘内容MD5..."
iso_size=$(stat -c%s "$ISO_FILE")
cd_md5=$(dd if="$CD_DEVICE" bs=1M 2>/dev/null | head -c $iso_size | md5sum | awk '{print $1}')

if [ "$original_md5" = "$cd_md5" ]; then
    echo "✅ MD5验证成功：光盘刻录完整"
else
    echo "❌ MD5验证失败：文件不匹配"
    echo "原始文件: $original_md5"
    echo "光盘内容: $cd_md5"
fi

参数	说明	示例
基本操作
(无参数)	计算文件MD5值	md5sum file.iso
-b	二进制模式读取文件	md5sum -b file.iso
-t	文本模式读取文件（默认）	md5sum -t file.txt
验证模式
-c	从文件检查MD5值	md5sum -c checksum.md5
--status	静默模式，只返回状态码	md5sum -c --status checksum.md5
输出控制
--tag	输出BSD风格格式	md5sum --tag file.iso
-z	用NUL分隔输出行	md5sum -z *.iso

💡 实际应用示例

创建MD5校验文件

# 为多个文件创建校验文件
md5sum *.iso > checksum.md5

# 检查内容
cat checksum.md5
# 输出：
# d41d8cd98f00b204e9800998ecf8427e  file1.iso
# e4d909c290d0fb1ca068ffaddf22cbd0  file2.iso

批量验证文件

# 验证checksum.md5中所有的文件
md5sum -c checksum.md5

# 输出：
# file1.iso: 确定
# file2.iso: 确定

网络下载验证

# 下载文件和他的MD5校验文件
wget http://example.com/file.iso
wget http://example.com/file.iso.md5

# 验证下载的文件
md5sum -c file.iso.md5

linux备份命令

Tue, 11 Nov 2025 00:00:00 GMT

linux备份命令

rsync 同步

常用命令形式

本地同步：

rsync -av /path/to/source/ /path/to/destination/

从本地同步到远程：

rsync -avz /local/path/ username@remote_host:/remote/path/

从远程同步到本地：

rsync -avz username@remote_host:/remote/path/ /local/path/

选项	全称	说明
-a	--archive	归档模式，保留所有文件属性（相当于 -rlptgoD）
-v	--verbose	显示详细传输信息
-z	--compress	传输时压缩数据
-r	--recursive	递归复制目录
-l	--links	保留符号链接
-p	--perms	保留文件权限
-t	--times	保留文件修改时间
-g	--group	保留文件所属组
-o	--owner	保留文件所有者
-D	--devices	保留设备文件（仅限超级用户）
-h	--human-readable	以人类可读格式输出数字
--progress	显示传输进度
--delete	删除目标中源没有的文件
--exclude=PATTERN	排除匹配 PATTERN 的文件
--include=PATTERN	包含匹配 PATTERN 的文件
-n	测试模式，不实际执行

本地备份

sudo rsync -avzh --log-file=/usr/doc_backup/rsync.log /home/mint/Documents /usr/doc_backup/

python pip虚拟环境构建和使用

Sat, 08 Nov 2025 00:00:00 GMT

python pip虚拟环境构建和使用

pip虚拟环境

sudo apt install python3-venv

# 创建新的虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .env/bin/activate

# 执行相关安装
pip install ...
pip3 install ...

# 退出虚拟环境
deactivate

Django运行没有端口权限解决

sudo -E ../.env/bin/python3 manage.py runserver localhost:80

Django 使用小记

Wed, 05 Nov 2025 00:00:00 GMT

Django 使用小记

命令行使用

# 新建工程文件
django-admin startproject <projectName>

调试

# 启动调试服务
manage.py runserver localhost:80

# Linux下缺少端口权限，使用该命令
sudo -E ../.env/bin/python3 manage.py runserver localhost:80

url路由

分级解析

在工程目录urls.py

rom django.urls import include, path
from sales import views

urlpatterns = [
    path('admin/', admin.site.urls),
    path('sales/', include("sales.urls")),
]

在sales/urls.py

from django.urls import path
from sales.views import listorders

urlpatterns = [
    path('orders/', listorders),
]

FMO外壳安装说明（电池版）

Tue, 04 Nov 2025 00:00:00 GMT

购买无电池普通版本的台友请看这里：

外壳安装仅需拆掉FMO原装透明亚克力前后保护板，然后参考步骤4、5、6、13进行安装即可。附带螺丝有4短4长一共8颗螺丝短螺丝用于固定前面板，长螺丝用于固定后盖。

祝各位台友玩的愉快 73！

:::note[提示] 本页面只是提供其外壳使用说明的展示服务，最终解释权归BI6LDD所有

使用说明的PDF版本点此下载：fmo外壳安装图解.pdf :::

:::caution[安装注意] FMO原装的塑料螺柱非常非常脆弱！请拆卸和安装时候务必非常小心！所有螺丝拧上后请稍稍用力拧紧即可，大力拧紧螺丝会造成螺丝滑丝无法安装和使用！ :::

Mint Lab

KVM虚拟化入门： Debian系统上用物理 DVD 安装 KVM 虚拟机攻略

1. 前置条件

1.1 硬件虚拟化支持检查

1.2 Debian 系统要求

2. 在 Debian 上安装 KVM

2.1 安装核心组件

2.2 配置用户权限

2.3 验证安装

3. 环境检查

4. 光驱设备定位

5. 失败的尝试与排错

尝试一：--cdrom 直接启动

尝试二：--location + inst.text

尝试三：混合使用 --cdrom + --extra-args

6. 终极方案

参数详解

执行流程图

7. Fedora 文本安装流程

8. 安装后管理

连接到虚拟机

在 VM 内安装 Guest Agent

日常管理速查

9. 网络配置：让外部设备访问虚拟机

9.1 为什么默认网络外部无法访问

9.2 三种暴露方案对比

9.3 桥接网络原理

9.4 宿主机桥接配置

第一步：查看当前网络布局

第二步：创建网桥（用 NetworkManager）

第三步：验证桥接

9.5 创建 libvirt 桥接网络

9.6 将虚拟机接入桥接网络

热切换（VM 运行时在线切换）

在 VM 内刷新 DHCP

验证

9.7 查看虚拟机 IP 的多种方式

方式一：virsh domifaddr（推荐，最全面）

方式二：virsh net-dhcp-leases（仅 NAT 网络）

方式三：宿主机的 ARP 表

方式四：路由器后台

方式五：登入 VM 内部查看

IP 查看速查表

9.8 SSH 隧道方案（备选）

9.9 端口转发方案（备选）

10. Fedora 安装小结

11. Arch Linux 安装实战

11.1 Arch Linux 的光驱引导

失败原因

11.2 正确的启动命令

11.3 镜像源加速

11.4 分区与 Btrfs 文件系统

11.5 安装基础系统

11.6 系统配置

11.7 initramfs 与 GRUB

11.8 安装后清理

12. VNC 图形控制台配置

12.1 原理

12.2 为已有 VM 添加 VNC

12.3 实际执行结果

12.4 从笔记本连接

13. 总结

核心教训

通用公式

折腾家里云： 入手一台戴尔R730服务器，设置IDRAC直通并配置ssh隧道

服务器配置

设置为默认命令行启动

手动启动和退出桌面环境

idrac 配置为直通模式

给R730配置一个连接到云服务器的ssh密钥

配置 ssh 隧道

ssh 转发格式

-L 本地转发 (Local)

-R 远程转发 (Remote)

安装并配置autossh

参数解释

云服务器ssh配置

本机ssh_config配置

使用Server Box作为移动端监控

配置IDRAC远程连接

尝试一：`--cdrom` 直接启动

尝试二：`--location` + `inst.text`

尝试三：混合使用 `--cdrom` + `--extra-args`

方式一：`virsh domifaddr`（推荐，最全面）

方式二：`virsh net-dhcp-leases`（仅 NAT 网络）

折腾家里云：入手一台戴尔R730服务器，设置IDRAC直通并配置ssh隧道

`-L` 本地转发 (Local)

`-R` 远程转发 (Remote)

博客前端性能大优化：首图快一点，再快一点

普源DHO804软件升级：谁不想拥有带示波器功能的安卓平板呢？

2026年4月总结：忙忙忙忙，参加各种比赛，技术栈增长飞快的一个月