柒零的驴舍

STM32 定时器

骑驴的柒零 — Sun, 08 Feb 2026 14:02:00 GMT

@@ Tags: STM32 定时器
@@ Date: 2026-02-08 2202
@@ From: 嵌入式系统设计
@@ Note: ~

概念

定时器的核心就是一个计数器模块，可以进行加一或减一计数。每出现一个计数信号，计数器的值就自动加一或减一。当计数值从0递增到最大值或者从最大值递减到0时，定时器可以向处理器发送中断请求。

计数信号的来源可以选择非周期的外部输入信号或者周期性的内部时钟信号，这两种不同的计数信号决定了定时器的两种基本工作模式：计数模式和定时模式。

在衡量一个定时器的基本性能时，常常使用位宽进行描述，比如8位定时器或者16位定时器。这里的位宽代表了定时器内部的计数器的位数，它决定了定时器的最大计数范围或者最大定时时间。

计数模式
对引脚输入的外部脉冲信号进行计数。
定时模式
对处理器内部的周期性时钟信号进行计数。
定时时钟
在定时模式下，输入定时器的周期性时钟信号称为定时时钟。
计数时间
在定时模式下，定时器内部的计数单元记一次数所花费的时间称为计数时间(或者说两次计数的时间间隔)，该值为定时时钟频率的倒数。

根据定时时钟和计数时间的定义，我们可以得到定时器的定时时间计算公式：

定时时间 = 计数值 × 计数时间
定时时间 = 计数值 / 定时时钟频率

例如，当定时器的定时时钟为1MHz时，计数时间为1s。此时，16位计数器的最大定时时间为65536μs,即65.536ms。

STM32 定时器介绍

STM32的定时器的功能强大，种类也比较多。按照定时器在微控制器内部的位置可以划分为内核定时器和外设定时器两大类。

其中，外设定时器按照功能又可以划分为专用定时器和常规定时器。具体的分类如图8-1所示。

在众多的定时器中，常规定时器的用途最为广泛。按照功能的不同，可以把常规定时
器分为基本定时器、通用定时器和高级定时器三类：

基本定时器
儿乎没有任何对外的输入/输出通道，常用作时间基准（时基），实现基本的定时功能。
通用定时器
具备多路独立的捕获/比较通道，可以完成定时/计数、输入捕获、输出比较等功能，还可以连接其他的传感器接口，如编码器和霍尔传感器。
高级定时器
高级定时器的功能最为强大，除了具备通用定时器的功能外，还增加了重复计数器带死区控制的互补信号输出等功能，可用于电机控制等领域。

以STM32F411芯片为例，片内集成了8个定时器：

注意：STM32微控制器的各个定时器都是完全独立的，所拥有的硬件资源彼此独立，
互不干扰

定时器的定时时钟与定时器所挂接的外设总线时钟APB相关，外设总线的时钟配置如图8-2所示。

无论哪一种定时器，最基本的功能都是定时和计数，在这两个功能的基础上又衍生出其他的功能。在实际的工程应用中，最常用的定时器功能有以下三种：

定时/计数功能：用于产生时间基准以及测量外部脉冲的个数。
输出比较功能：包括PWM输出、电平翻转、单脉冲输出以及强制输出等功能。
输入捕获功能：用于测量输人信号的脉冲宽度。

时钟源

定时器的两种工作模式的区别主要在于时钟源的选择。可以通过设置相关的寄存器，选择对应的时钟源后，该时钟源将作为时基单元的预分频时钟CK_PSC送入时基单元。

时钟源一共有四种选择：

1.内部时钟(CK_INT)

内部时钟CK_INT来自外设总线APB1或APB2提供的定时时钟TIMx_CLK，如图8-2所示的 APBx Timer Clocks。

使用内部时钟作为时钟源时，定时器工作于定时模式，并衍生出输出比较和输入捕获等功能。

2.外部时钟模式1：外部输入引脚TIx(x表示引脚编号1~4，下同)

TIx (Timer Input), 时钟信号来自外部输入引脚TIx，定时器可以在时钟信号的每个上升沿或下降沿计数。

注意：

当使用外部时钟模式1时，时钟信号实际上是由定时器的捕获/比较通道所对应的引脚TIMx_CHn(n表示通道编号1~4，下同)输人。
TIMx_CHn 是物理引脚，而 TIx 是内部路线。

3.外部时钟模式2：外部触发输入ETR

ETR (External Trigger Input), 时钟信号来自外部触发输入引脚TIMx_ETR。定时器可以在时钟信号的每个上升沿或下降沿计数

4.内部触发输入 ITRx

ITRx (Internal Trigger Input), 时钟信号来自芯片内部其他定时器的触发输出，可以实现定时器的同步或级联。例如，使用一个定时器作为另一个定时器的预分频器

时基单元

时基单元是定时器的核心控制单元，负责时钟源的分频、计数和溢出重载等基本功能。它主要由三个模块组成：预分频模块、计数模块和自动重载模块。

时基单元的功能框 如图8-4所示。

预分频时钟CK_PSC是经过时钟源选择后输出的时钟信号。如果使用内部时钟CK_INT作为时钟源，CK_PSC的频率等于定时时钟TIMx_CLK的频率。如果使用外部时钟或者内部触发信号作为时钟源，CK_PSC的频率由外部引脚输入信号或者内部触发信号的频率决定。

CK_CNT是经过预分频模块后，送入计数模块的时钟，这里称为计数时钟

预分频模块

预分频模块由预分频计数器和预分频寄存器TIMx_PSC组成：预分频计数器通过计数的方式对预分频时钟CK_PSC进行分频，而预分频寄存器用于存放预分频系数PSC。

预分频主要用于将 CK_PSC 时钟频率进行预处理，使得可以在 16 位定时器上处理更长时间的定时任务（比如 100MHz 频率上处理 65.536ms 以上时长）。另外一方面可以将频率转换为更容易处理的时长单位，比如间隔时长为 1us。

从图8-5可以看到：当预分频寄存器的内容为3时，预分频计数器从0开始计数，且计数值0会保持一个完整的计数脉冲。因此，实际的计数脉冲个数为4，即最终的预分频系数为：PSC+1。例如，要对内部时钟进行72分频，则预分频系数PSC应设置为71。

预分频时钟CK_PSC经过预分频模块后，得到计数时钟CK_CNT,它的计算公式如下：

$$
CK\_CNT=CK\_PSC / (PSC+1)
$$

计数模块

计数模块由核心计数器和计数器寄存器TIMx_CNT组成：核心计数器用来对预分频模块输出的计数时钟CK_CNT进行二次计数。计数时钟CK_CNT每输人一个脉冲，核心计数器的计数值就自动加一或减一（根据用户设置的不同计数模式来决定是加一还是减一）。计数器寄存器则用来存放核心计数器运行时的计数值，便于用户读取。

自动重载模块

自动重载模块由自动重载寄存器TIMx_ARR构成，用来设置计数器的计数终值或计数初值，决定计数脉冲的多少（计数模式）或定时周期（定时模式）的长短我们将·寄存器的内容记为自动重载值ARR。

计数模式

定时器的计数模块支特三种计数模式：递增计数、递减计数和中心对齐计数，并产生溢出事件，作为定时器的更新中断（定时中断）。

三种模式的主要区别在于：递增时计数器从0到ARR后产生上溢事件，递减时计数器冲ARR到0后产生下溢事件，中心对齐模式先从0到ARR-1后产生上溢事件，再递减到 1 产生下溢事件。

定时时间计算公式

当定时器工作于定时模式时，预分频时钟CK_PSC等于定时时钟TIMx_CLK。定时时间由TIMx_CLK的频率、预分频系数PSC和自动重载值ARR三者决定。

假设PSC=1,ARR=36,采用递增计数模式，计数器寄存器的初值为0。定时器的时序如图8-7所示。

至此我们可以推导出，定时时间的计算公式为:

$$
T=(PSC+1) * (ARR+1) / CK\_PSC
$$

由于计数器寄存器从0开始计数，且计数值0会保持1个完整的计数脉冲。因此，实际的计数脉冲个数为：ARR+1。
公式的 (PSC+1) * (ARR+1) 部分可以简单看做: 触发溢出事件需要多少个 CK_PSC 脉冲数。
需要脉冲数 / 频率就可以求出触发溢出事件总共需要多少秒。

同样的，可以得到定时器溢出频率的计算公式：

$$
f=CK\_PSC / (PSC+1) * (ARR+1)
$$

外部脉冲计数

外部信号的输入有两个途径：

一个是通过外部触发输入引脚 ETR，经过极性选择、分频和滤波以后，再输入到时基单元进行计数(工程常用)。
一个是通过外部输入引脚 TIx，也就是定时器的捕获/比较通道TIMx_CHn，经过滤波和边沿检测后，再输入到时基单元进行计数。

外部脉冲信号的处理流程如图8-8所示。

极性选择用于选择外部脉冲信号的触发极性，可以进行反相和不反相：触发极性不反相表示在脉冲信号的上升沿出现时计数；触发极性反相表示在脉冲信号的下降沿出现时计数。

HAL 库外设模块的编程

对于定时器(TIMER)、串口(UART)和模数转换器(ADC)等功能较为复杂的外设，HAL库设计了一个名为外设句柄的数据类型PPP_HandleTypeDef(PPP表示外设名称)。

#define TIM2 ((TIM_TypeDef *) TIM2_BASE)

typedef struct
{
  uint32_t Prescaler;                         // 预分频系数 PSC, 即 TIMx_PSC 的内容
  uint32_t CounterMode;                       // 计数模式
  uint32_t Period;                            // 自动重装载值 ARR, 即 TIMx_ARR 的内容
  uint32_t ClockDivision;                     // 时钟分频
  uint32_t RepetitionCounter;                 // 重复计数器（仅高级定时器有效）
  uint32_t AutoReloadPreload;                 // 设置自动重载寄存器 TIMx_ARR 的预装载值
} TIM_Base_InitTypeDef;

typedef struct {
    TIM_TypeDef                *Instance;     // 定时器外设实例(寄存器基地址)
    TIM_Base_InitTypeDef       Init;          // 定时器时基初始化参数配置
    HAL_TIM_ActiveChannel      Channel;       // 捕获/比较通道（用于 PWM、输入捕获等）
    DMA_HandleTypeDef          *hdma[7];      // DMA 句柄数组
    HAL_LockTypeDef            Lock;          // 保护锁（防止多任务冲突）
    __IO HAL_TIM_StateTypeDef  State;         // 定时器状态（如 ready, busy, error）
} TIM_HandleTypeDef;

TIM_HandleTypeDef htim2;                      // 定义一个名为 htim2 的句柄
htim2.Instance         = TIM2;                // 指向 TIM2 的硬件地址
htim2.Init.Prescaler   = 71;                  // 预分频器
htim2.Init.Period      = 999;                 // 自动重装载值 (ARR)
htim2.Init.CounterMode = TIM_COUNTERMODE_UP;
                                              // ... 其他初始化
HAL_TIM_Base_Init(&htim2);                    // 调用库函数，把 Init 里的参数写进 Instance 寄存器

定时器有两种启动方式，轮询或中断。对于定时器来说这两种方式的区别在于设置的标志位不同，轮询时由用户自行检查。而中断则设置中断标志，从而触发中断处理程序。

注意：

定时器是一个片内外设，因此定时器在计数或输出PWM时，是完全独立于CPU工作的，完全不影响CPU的指令执行。

轮询方式

// 1. 启动定时器
HAL_TIM_Base_Start(&htim2);

while (1)
{
    // 2. 轮询检查：UIF 标志位是否被置 1（说明计数溢出了）
    if (__HAL_TIM_GET_FLAG(&htim2, TIM_FLAG_UPDATE) != RESET)
    {
        // 3. 清除标志位（如果不清除，下次进来立刻又是 SET）
        __HAL_TIM_CLEAR_FLAG(&htim2, TIM_FLAG_UPDATE);

        // 4. 执行你的逻辑代码
        HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
    }
}

中断方式

中断方式使用 HAL_TIM_Base_Start_IT() 启动定时器, 当溢出事件发生时，会设置中断标志，从而触发中断运行中断处理函数，最后被 HAL_TIM_PeriodElapsedCallback 处理。

注意：

在调用接口函数 HAL_TIM_Base_Init() 初始化时基单元时，会执行一个软件更新语句：TIMx->EGR=TIM_EGR_UG,这个语句将触发更新事件，并置位更新中断标志。

如果采用中断方式启动定时器，一旦使能了更新中断，将立即进入更新中断服务程序。因此用户在使能定时器更新中断之前，必须先执行清除更新中断标志的操作。

定时与计数示例

定时闪烁指示灯

CubeMX 配置

STM32F411RET6 (100MHz)
- Times -> TIM10:
  - Activated -> checked
  - Prescaler -> 9999
  - CounterPeriod -> 9999;
  - CounterMode -> UP
STM32F103C8T6 (72MHz)
- Times -> TIM3:
  - Activated -> checked
  - Prescaler -> 7199
  - CounterPeriod -> 9999;
  - CounterMode -> UP
NVIC 启用 TIM10 或 TIM3 中断

  /* Initialize all configured peripherals */
  MX_GPIO_Init();
  MX_TIM3_Init();

  /* USER CODE BEGIN 2 */
  __HAL_TIM_CLEAR_IT(&htim3, TIM_IT_UPDATE);  // 清除更新中断标志, 避免定时器一启动就进入中断
  HAL_TIM_Base_Start_IT(&htim3);              // 中断方式启动定时器
  /* USER CODE END 2 */

  /* Infinite loop */
  /* USER CODE BEGIN WHILE */
  while (1)
  {
    /* USER CODE END WHILE */

    /* USER CODE BEGIN 3 */
  }
  /* USER CODE END 3 */

增加定时器函数

/* USER CODE BEGIN 4 */
void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim) {
    if (htim->Instance == TIM3) {
        HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);
    }
}
/* USER CODE END 4 */

外部脉冲计数示例

监听键盘事件，每触按下一次键盘，就通过引脚输出一个周期为2ms的脉冲，送入定时器的外部触发输入引脚进行计数，并将计算结果通过串口发送到PC上显示。

STM32F411RET6 (100MHz)
- Times -> TIM2: 外部输入计数设置
  - TriggerSource -> Disbale
  - ClockSource -> ETR2
  - Prescaler -> 0
  - CounterPeriod -> 65535;
  - CounterMode -> UP
  - ClockFilter -> 0
- Connectivity -> USART1: 串口通讯设置
  - Mode -> Asynchronous
  - BaudRate -> 115200
  - Parity -> None
STM32F103C8T6 (72MHz)
- Times -> TIM2: 外部输入计数设置
  - TriggerSource -> Disbale
  - ClockSource -> ETR2
  - Prescaler -> 0
  - CounterPeriod -> 65535;
  - CounterMode -> UP
  - ClockFilter -> 0
- Connectivity -> USART1: 串口通讯设置
  - Mode -> Asynchronous
  - BaudRate -> 115200
  - Parity -> None

实现代码摘要如下, 其中(以STM32F103C8T6为基准, 其他板子引脚有所不同):

PC13 作为LED
PB12 作为按键
PC15 作为脉冲输出
PA0 作为TIM2_ETR

/* USER CODE BEGIN Includes */
#include "stdio.h"
/* USER CODE END Includes */

/* USER CODE BEGIN 0 */
typedef enum {
  KEY_UP = 0,
  KEY_DEBOUNCE,
  KEY_WAIT_RELEASE,
} KEY_STATE;

KEY_STATE        KeyState = KEY_UP;
volatile uint8_t KeyFlag  = 0;
uint8_t          Result   = 0;
/* USER CODE END 0 */

int main(void)
{
  // 省略...

  /* USER CODE BEGIN 2 */
  HAL_TIM_Base_Start_IT(&htim1); // 启动定时器1，用于按键检测
  HAL_TIM_Base_Start(&htim2);    // 启动定时器2，用于外部脉冲计数

  printf(" Timer count function test: \n");
  /* USER CODE END 2 */

  /* USER CODE BEGIN WHILE */
  while (1)
  {
    /* USER CODE END WHILE */
    /* USER CODE BEGIN 3 */
      if (KeyFlag)
      {
        KeyFlag = 0;
        printf(" Button B12 has been target.\n");
        HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);  // 切换 LED 以便观察状态

        // 2ms 脉冲输出
        HAL_GPIO_WritePin(GPIOC, GPIO_PIN_15, GPIO_PIN_SET);
        HAL_Delay(1);
        HAL_GPIO_WritePin(GPIOC, GPIO_PIN_15, GPIO_PIN_RESET);
        HAL_Delay(1);

        Result = __HAL_TIM_GET_COUNTER(&htim2);  // 读取外部脉冲计数值
        printf(" count %d.\n", Result);          // 显示结果
      }
  }
  /* USER CODE END 3 */
}

/* USER CODE BEGIN 4 */
// printf 输出重定向到串口
int fputc(int ch, FILE *f)
{
  HAL_UART_Transmit(&huart1, (uint8_t*)&ch, 1, HAL_MAX_DELAY);
  return ch;
}

// 按键检测
void KeyScan()
{
  switch(KeyState) {
    case KEY_UP:
      if (HAL_GPIO_ReadPin(GPIOB, GPIO_PIN_12) == GPIO_PIN_RESET) {
         KeyState = KEY_DEBOUNCE;
      }
      break;

    case KEY_DEBOUNCE:
      if (HAL_GPIO_ReadPin(GPIOB, GPIO_PIN_12) == GPIO_PIN_RESET) {
         KeyState = KEY_WAIT_RELEASE;
         KeyFlag = 1;
      }
      else {
        KeyState = KEY_UP;
      }
      break;

    case KEY_WAIT_RELEASE:
      if (HAL_GPIO_ReadPin(GPIOB, GPIO_PIN_12) == GPIO_PIN_SET) {
         KeyState = KEY_UP;
      }
      break;
  }
}

// 定时检测按钮状态
void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim)
{
  if(htim->Instance == htim1.Instance)
    KeyScan();
}
/* USER CODE END 4 */

注意:

串口部分的代码，因为使用了 printf 因此要注意勾选 Use MicroLIB 设置, 否则直接运行可能不生效。
外部脉冲计数方面, 相对来说比较简单, 在 CubeMX 中配置好定时器后, 仅需要启动然后读取计数值即可。

PWM 输出

脉冲宽度调制(pulse width modulation,PWM)是一种对模拟信号电平进行数字编码的方法。PWM技术广泛应用于机械、通信、功率控制等领域，如电机的转速控制、灯光的亮度调节、DC-DC转换器以及信号调制等场合。

PWM信号有两个重要的参数：周期和占空比。

周期(Period)
一个完整PWM波形所持续的时间。
占空比(Duty)
- 高电平持续时间(T)与周期(Period)的比值。
- 占空比的计算公式如下：
  $Duty=(T/Period) * 100%$

图8-18 给出了50%、20%和80%三种不同占空比的PWM信号。

如图8-18所示，电压的峰值为 $3.3V$, $T_{on}$ 表示高电平持续时间，$T_{off}$ 表示信号关断时间，虚线表示PWM信号所对应的平均电压。

根据平均电压的计算公式：平均电压=峰值×占空比，我们可以计算出不同占空比的PWM信号所对应的平均电压：

20% 占空比的平均电压为 0.66V;
50% 占空比的平均电压为 1.65V;
80% 占空比的平均电压为 2.64V。

因此，PWM信号能够进行电压调节的基本原理就是不同占空比的PWM信号等效于不同的平均电压。

捕获/比较通道

捕获/比较通道负责输入捕获功能和输出比较功能。每个定时器最多可以拥有4个捕获/比较通道，每个通道都有对应的寄存器进行控制，也有对应的GPIO引脚作为通道的输入和输出接口。

捕获/比较通道的功能框架如图8-19所示。

1.输入捕获单元

用于捕获外部脉冲信号，捕获方式可以设置为上升沿捕获、下降沿捕获和双边沿捕获。发生捕获事件时，将计数器的当前计数值锁存到捕获/比较寄存器中，以供用户读取，同时可以产生捕获中断。输入捕获主要用于信号测量，可以测量信号的周期、频率和占空比等参数，测量所使用的参考时间就是捕获发生时锁存到寄存器中的值（详见:输入捕获功能）。

2.捕获/比较寄存器

捕获/比较寄存器 TIMx_CCR 是捕获/比较通道中最重要的寄存器。

在输入捕获模式下用于存放发生捕获事件时的计数值；
在输出比较模式下用于存放预设的比较值。
该寄存器具备预装载功能，由影子寄存器和预装载寄存器组成，预装载功能可由软件选择开启或关闭。

3.输出比较单元

输出比较单元用于信号输出。定时器通过将预设的比较值与计数器的计数值做匹配比较，从而实现各类输出，如PWM输出、电平翻转、单脉冲输出和强制输出。预设的比较值存放在捕获/比较寄存器TIMx_CCR中。

使用捕获/比较通道时，需要注意以下几点：

输入捕获功能和输出比较功能都是由定时功能衍生而来。因此，定时器工作于定时模式，时钟源为内部时钟CK_INT,时基单元的预分频时钟CK_PSC等于定时器的定时时钟TIMx_CLK。
每个定时器具备1~4个独立的捕获/比较通道，每个通道具有独立的输入捕获单元、捕获/比较寄存器和输出比较单元，但共享同一个时基单元。
每个捕获/比较通道都可以独立设置为捕获通道（用于输入捕获）或者比较通道(用于输出比较)，但是两种功能只能选择其中之一。
每个捕获/比较通道都有对应的通道引脚作为通道的输入/输出接口，如TIMx_CHn(n表示通道号1~4，下同)。这些通道引脚与GPIO引脚复用，用户可以在CubeMX软件的引脚分配图上选择GPIO引脚的功能为通道引脚。

PWM 实现原理

PWM信号输出，需要用到三个寄存器：

TIMx_ARR 自动重载寄存器
TIMx_CCRn 捕获/比较寄存器(n表示通道编号1~4，下同)
TIMx_CNT 计数器寄存器，并通过通道引脚TIMx_CHn输出PWM信号。

整个PWM信号的输出过程如图8-20所示。

启动定时器后，计数器从0开始计数。计数过程中，不断将计数值CNT与捕获/比较值CCR以及自动重载值ARR相比较。

当CNT小于CCR时，输出高电平；
当CNT等于CCR时，输出电平翻转，变为低电平。
当CNT等于ARR时，输出电平再次翻转，变为高电平。并触发重载, 开始下一个周期的输出。

根据PWM信号的输出过程，我们可以知道：自动重载寄存器TIMx_ARR用于控制PWM信号的周期，捕获/比较寄存器TIMx_CCRn用于控制PWM信号的占空比。

综上所述，我们可以得到PWM信号周期及占空比的计算公式：

$T=(PSC+1)*(ARR+1)/TIMx\_CLK$
$Duty=CCR/(ARR+1)* 100%$

假设定时器的定时时钟TIM_CLK为100MHz，要求输出周期为1ms，占空比为47.5%的PWM信号，输出波形如图8-21所示。

要产生这样一个PWM信号，根据公式，我们可以设置:

PSC 预分频系数为99，
ARR 自动重载值为999，从而得到1ms的PWM周期。
CCR 捕获/比较值为475。

定时器的每个通道都具有独立的输入捕获单元、捕获/比较寄存器和输出比较单元，可以分别输出PWM信号。对于同一个定时器而言，由于它的多个通道共享同一个自动重载寄存器，而自动重载寄存器的内容决定了PWM信号的周期。因此，对于同一个定时器的多个通道而言，可以同时输出占空比不同，但周期相同的PWM信号。

输出 PWM 信号示例

输出周期为2s,占空比为50%的PWM信号控制开发板上的指示灯LED。

CubeMX 配置如下:

STM32F103C8T6 (72MHz)
- Times -> TIM2:
  - Mode:
    - ClockSource -> Internal Clock
    - Channel1 -> PWM Generation CH1(PA0引脚)
  - Parameter Settings:
    - Prescaler(预分频系数PSC):7199
    - Counter Mode(计数模式)：Up(递增计数)
    - Counter Period(自动重载值ARR):1999
    - Internal Clock Division(时钟分频)：No Division(不分频)
    - auto-reload preload(预装载功能)：Disable(预装载功能关闭)
    - PWM Generation Channel1(PWM输出通道1)部分进行如下的参数设置：
    - Mode(输出模式)：PWM mode1(输出模式1)
    - Pulse(占空比)：10000(50%占空比)
    - Output compare preload(输出比较预装载功能)：Enable(预装载功能开启)
    - Fast Mode(快速输出模式)：Disable(不使能快速输出模式)
    - CH Polarity(输出极性)：High(输出有效电平为高电平)

注意:

由于 LED 所在的引脚在 PC13, 而该引脚没有定时器比较通道, 因此使用 PA0, 当测试时通过镊子短接 PA0 ~ PC13 即可。

代码如下(在 CubeMX 生成的基础上添加一行代码即可):

/* USER CODE BEGIN 2 */
HAL_TIM_PWM_Start(&htim2, TIM_CHANNEL_1);
/* USER CODE END 2 */

PWM 实现呼吸灯

利用PWM信号控制LED指示灯。设置PWM周期为20ms,占空比从0%开始，步进为10%。递增到100%后，又从0%开始，并重复整个过程。占空比修改的时间间隔为100ms。

配置修改如下:

Prescaler(预分频系数PSC):7199
Counter Period(自动重载值ARR):199

代码如下:

/* USER CODE BEGIN 0 */
uint16_t Duty = 0;    // 占空比
uint16_t Step = 10;   // 步进值
/* USER CODE END 0 */

/* Initialize all configured peripherals */
MX_GPIO_Init();
MX_TIM2_Init();
/* USER CODE BEGIN 2 */
HAL_TIM_PWM_Start(&htim2, TIM_CHANNEL_1);
/* USER CODE END 2 */

/* Infinite loop */
/* USER CODE BEGIN WHILE */
while (1)
{
  /* USER CODE END WHILE */

  /* USER CODE BEGIN 3 */
  for(Duty = 0; Duty <= 200; Duty += Step)
  {
      __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, Duty);
      HAL_Delay(200);
  }
}
/* USER CODE END 3 */

输入捕获功能

输入捕获单元结构

输入捕获功能利用定时器的捕获/比较通道实现，其基本原理是：输入捕获单元不断检测通道上的外部输入信号，当检测到外部信号的有效边沿（上升沿、下降沿或双边沿）时，将计数器寄存器TIMx_CNT的当前值锁存到对应通道的捕获/比较寄存器TIMx_CCRn。

笔记

当检测到外部信号有效时，将计数器中的数值（参考时间），存储到 TIMx_CCRn，并可选的触发中断。当触发了两次捕获之后，我们就可以计算出输入信号的周期、频率、占空比等信息。

输入捕获通道

外部输入信号通过输入捕获通道x对应的引脚TIMx_CHx产生输入信号TIx;

输入滤波器

输入滤波器用于对输入信号的采样滤波，滤波后的信号为TIF。当输入信号存在高频干扰信号时，我们可以通过设置滤波长度，对信号进行多次采样。如果连续N次采样检测都是高电平，则说明这是一个有效的电平信号，从而滤除高频干扰信号。

输入滤波器的工作原理如图8-29所示。从图中可以看到，当输入信号设置为上升沿捕获，滤波长度设置为4时。在捕获到输入信号的上升沿后，输入滤波器将按照采样时钟DTS(采样时钟DTS的频率由内部时钟CK_INT分频获得，分频系数可以是1/2/4)的频率，连续采样4次输入信号。如果都是高电平，才说明这是一次有效的触发信号TIF。如果没有做到连续4次采样都是高电平，则该次触发无效。

预分频器

捕获信号IC1经过预分频器之后，得到最终的捕获信号IC1PS。在最终的捕获信号IC1PS的作用下，将计数器寄存器TIMx_CNT的当前计数值锁存到捕获/比较寄存器TIMx_CCR1,同时可以发出捕获中断申请CC1I(Capture/Compare 1 interrupt)。

注意：捕获信号的输入有两种方式。

直接输入表示通过本通道对应的通道引脚输入捕获信号；
间接输入表示通过其他通道对应的通道引脚输入捕获信号。

例如：

TI1FP1 是捕获通道1的直接输入信号，由捕获通道1对应的通道引脚TIMx_CH1输入。
TI2FP1 是捕获通道1的间接输入信号，由捕获通道2对应的通道引脚TIMx_CH2输入。

信号测量原理

我们假设定时器采用上升沿捕获和递增计数模式，具体的测量过程如下：

启动定时器后，在定时时钟TIMx_CLK的作用下（注意：最终起作用的时钟是经过预分频模块分频后的计数时钟CK_CNT），计数器从0开始递增计数。
假设在 $t_b$ 时刻，被测信号出现了一个上升沿，触发第一次捕获。此时，计数器寄存器TIMx_CNT的内容将锁存到捕获/比较寄存器TIMx_CCRn中，并触发捕获中断。在中断回调中，可以保存 $t_b$ 时刻的捕获值。
在中断处理过程中，定时器的计数模块不会暂停，将继续计数。
假设在 $t_d$ 时刻，被测信号又出现了一个上升沿，触发第二次捕获。再次将TIMx_CNT的内容锁存到TIMx_CCRn中。并在捕获中断回调中，保存 $t_d$ 时刻的捕获值。
将两次捕获值相减，再乘以计数时间，就可以计算出信号的周期。

根据上述信号测量的过程，我们可以总结出信号周期的计算公式：

$T=Diff * (PSC+1)/TIMx\_CLK$

其中 $Diff$ 表示两次捕获值相减后的差值。如果被测信号的周期不大于定时器的一个完整计数周期（从0到ARR）时。假设两次连续的捕获值分别为CCRn_1和CCRn_2,则捕获差值 $Diff$ 可以按照如下方法计算：

当CCRn_1 < CCRn_2: 捕获差值 Diff = CCRn_2 - CCRn_1
当CCRn_1 > CCRn_2: 捕获差值 Diff = (ARR+1 - CCRn_1) + CCRn_2

注意：如果被测信号的周期较长，大于定时器的一个完整计数周期时，就需要考虑计数溢出的问题。这时，我们可以使能定时器的更新中断，在更新中断回调函数中记录溢出次数 m，最终的捕获差值 Diff = m * (ARR+1) - CCRn_1 + CCRn_2。

信号测量示例

利用定时器2的通道1来测量一个外部脉冲信号的周期、频率、高电平脉冲宽度和占空比，外部脉冲信号由另一个引脚产生并输入，并将测量结果通过串口发送到PC上显示。

CubeMX 配置如下:

STM32F103C8T6 (72MHz)
- Times
  - TIM2:
    - Mode:
      - ClockSource -> Internal Clock
      - Channel1 -> Input Capture direct mode(PA0引脚)
    - Parameter Settings:
      - Counter Setting:
        
        Prescaler(预分频系数PSC):0
        
        Counter Mode(计数模式)：Up(递增计数)
        
        Counter Period(自动重载值ARR):65535
        
        Internal Clock Division(时钟分频)：No Division(不分频)
        
        auto-reload preload(预装载功能)：Disable(预装载功能关闭)
      - Input Capture Channel 1:
        
        Polarity Selection(捕获边沿极性选择)：Rising Edge(上升沿)
        
        IC Selection(捕获通道选择)：Direct(直接输入方式)
        
        Prescaler Division Ratio(输人信号分频比)：No division(不分频)
        
        Input Filter(滤波长度)：O(不进行滤波)
  - TIM3:（10kHZ 占空比10%）
    - Prescaler(预分频系数PSC):719
    - Counter Period(自动重载值ARR):9
    - Pulse(占空比)：1

/* USER CODE BEGIN PV */
uint32_t          CapVal[3]   = {0}; // 存放捕获值
uint32_t          CapIndex    = 0;   // 捕获状态指示：0表示没有开始捕获，1表示完成一次捕获，2表示完成两次捕获
volatile uint32_t CapFlag     = 0;   // 捕获完成标志：0表示未完成，1表示完成
uint32_t          Period      = 0;   // 存放信号周期
uint32_t          HighTime    = 0;   // 存放高电平脉冲宽度
/* USER CODE END PV */

/* USER CODE BEGIN 2 */
printf("/*Timer Capture Function*/\n");       // 发送提示信息
HAL_TIM_PWM_Start(&htim3, TIM_CHANNEL_1);     // 启动定时器3通道1输出PwM信号
HAL_Delay(1000);
HAL_TIM_IC_Start_IT(&htim2,TIM_CHANNEL_1);    // 启动定时器2通道1上升沿捕获
/* USER CODE END 2 */

/* Infinite loop */
/* USER CODE BEGIN WHILE */
while (1)
{
  /* USER CODE END WHILE */

  /* USER CODE BEGIN 3 */
  if (CapFlag)                                      // 捕获完成
  {
    if(CapVal[2] >= CapVal[0])                      // 信号在一个周期内
    {
      Period = CapVal[2] - CapVal[0];
    }
    else
    {
      Period = 65535 + 1 - CapVal[0] + CapVal[2];
    }

    printf("Period:%.2fms\n", Period/72000.0);      // 计算信号周期(毫秒), 72MMHz/s=72kHz/ms
    printf("Frequency:%dHz\n", 72000000/Period);    // 计算信号频率, 一秒内计数器触发多少次 / 一个周期的计数值 = 频率

    if(CapVal[1] >= CapVal[0])                      // 信号高电平宽度在同一个计数周期内
    {
      HighTime = CapVal[1] - CapVal[0];
    }
    else                                            // 信号高电平宽度不在同一个计数周期内
    {
      HighTime = 65535 + 1 - CapVal[0] + CapVal[1];
    }

    printf("High %.2fms\n", HighTime/72000.0);      // 计算高电平时间
    printf("Duty:%.1f%%\n", HighTime*100.0/Period); // 计算占空比
    printf("****************************\n");
    CapFlag = 0;                                    // 清除捕获完成标志

    // 启动下一次信号测量
    HAL_Delay(1000);
    HAL_TIM_IC_Start_IT(&htim2, TIM_CHANNEL_1);
  }
}
/* USER CODE END 3 */

捕获中断:

/* USER CODE BEGIN 4 */
void HAL_TIM_IC_CaptureCallback(TIM_HandleTypeDef *htim)
{
  if (htim->Instance == TIM2) // 判断发生捕获中断的定时器
  {
    if (htim->Channel == HAL_TIM_ACTIVE_CHANNEL_1) // 判断发生捕获中断的通道
    {
      switch (CapIndex)
      {
        // 存放第一次上升沿捕获时的捕获值，修改捕获方式为下降沿，并修改捕获指示
        case 0:
        {
          CapVal[0] = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1);
          __HAL_TIM_SET_CAPTUREPOLARITY(htim, TIM_CHANNEL_1,
                                        TIM_INPUTCHANNELPOLARITY_FALLING);
          CapIndex = 1;
          break;
        }

        // 存放第一次下降沿捕获时的捕获值，修改捕获方式为上升沿，并修改捕获指示
        case 1:
        {
          CapVal[1] = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1);
          __HAL_TIM_SET_CAPTUREPOLARITY(htim, TIM_CHANNEL_1,
                                        TIM_INPUTCHANNELPOLARITY_RISING);
          CapIndex = 2;
          break;
        }

        // 存放第二次上升沿捕获时的计数器初值，停止捕获，重置捕获指示，设置捕获完成标志
        case 2:
        {
          CapVal[2] = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1);
          HAL_TIM_IC_Stop_IT(htim, TIM_CHANNEL_1);
          CapIndex = 0;
          CapFlag = 1;
          break;
        }

        // 错误状态
        default:
        {
          Error_Handler();
          break;
        }
      }
    }
  }
}
/* USER CODE END 4 */

捕获过程示意图如下:

笔记

在 STM32F103C8T6 遇到一个有趣的现象, 当输出 PWM 占空比为 10% 的时候, 第一次测量总是比后面的周期大两倍, 后面就正常了。但是占空比设置为 40% 这个现象就消失了。

下面是出现问题的输出:

/*Timer Capture Function*/
CapVal   : 2752,10672,17152
Period   : 0.20ms(14400)
Frequency: 5000Hz
High     : 0.11ms
Duty     : 55.0%
****************************
CapVal   : 21406,22126,28606
Period   : 0.10ms(7200)
Frequency: 10000Hz
High     : 0.01ms
Duty     : 10.0%
****************************
CapVal   : 32534,33254,39734
Period   : 0.10ms(7200)
Frequency: 10000Hz
High     : 0.01ms
Duty     : 10.0%
****************************
/*Timer Capture Function*/      - 重新上电, 现象依旧
CapVal   : 2752,10672,17152
Period   : 0.20ms(14400)
Frequency: 5000Hz
High     : 0.11ms
Duty     : 55.0%
****************************
CapVal   : 21414,22134,28614
Period   : 0.10ms(7200)
Frequency: 10000Hz
High     : 0.01ms
Duty     : 10.0%

分析记录，示意图如下：

   ┌┐┌┐┌┐┌┐┌┐┌┐┌┐┌┐┌┐┌┐
   ┌┐                  ┌┐                  ┌┐
   ││                  ││                  ││
───┘└──────────────────┘└──────────────────┘└───
   | 720 + 6480 = 7200 |

72,000,000Hz / (719 + 1) = 100,000Hz # 计时器分频后的频率
100,000Hz / 10 = 10,000Hz # PWM 每个周期的频率
PWM 每个周期 10 计数点, 每个计数点 720 个时钟点, 一个周期计数点 7200 个时钟点（timer ticks）
PWM 每个周期占空比为 10%, 即高电平 720 个时钟点, 低电平 6480 个时钟点
根据首次测量记录: 2752,10672,17152:
10672 - 2752 = 7920 第一次上升沿到下降沿的计数点大于一个周期的计数点 7200 个时钟点
17152 - 10672 = 6480 下降沿到第二次上升沿的计数点符号正常的低电平 6480 个时钟点
7920 = 6480 + 720 + 720 分析结构大概是这样 ┘└──────────────────┘└
那么可能的原因可能是当成功捕获到第一个上升沿后, 触发了中断, 然后中断中修改为捕获下降沿, 但此时很可能已经到达低电平了，毕竟上升沿只有720个时钟点（10us）, 因此会跳过一个上升沿直到下一个下降沿才会触发。这样也能后解释为什么占空比设置为 40% 这个现象就消失了。
但为什么在第一次之后的测量中这个现象也不会出现了，还没有分析出来。

捕获的流程如下, 这个时间窗口大概可能需要几十到上百个CPU周期, 而高电平只有 (720 timer ticks) 因此错过的概率很高。

- 边缘检测, 捕获到上升沿
- 置位CC1IF
- NVIC触发中断
- ISR中断服务程序
- HAL_TIM_IC_CaptureCallback
- 极性切换

后续优化可以尝试使用两个通道同时检测上升沿与下降沿, 减少极性切换导致的缺陷。

STM32 GPIO

骑驴的柒零 — Wed, 28 Jan 2026 04:38:00 GMT

@@ Tags: STM32 GPIO
@@ Date: 2026-01-28 1238
@@ Note: ~

概念

在STM32中，GPIO 中有两个重要的概念:

端口

定义：STM32 将 GPIO 分成了很多个组, 每一组称为端口。端口可以看做是一个独立的GPIO外设模块。
命名：端口用大写字母表示，如 GPIOA、GPIOB、GPIOC、GPIOD、GPIOH（具体数量取决于芯片型号）。

引脚

定义：引脚是芯片物理上伸出的金属“针脚”，是与外部电路进行电气连接的实际接口。它是端口的具体成员。
命名：由“端口字母 + 引脚编号”组成。例如：
- PA1：表示 GPIOA端口 的 第1号引脚。
- PC13：表示 GPIOC端口 的 第13号引脚。

电路结构

引脚模式

输入模式

1.浮空输入

Floating Input / Input floating
纯粹的数字输入。引脚电平完全由外部电路决定。
内部既不上拉也不下拉。如果外部悬空，引脚电平将是不确定的，极易受电磁干扰影响而翻转。
施密特触发器开启。
典型应用： 连接外部已有确定驱动能力的信号，如另一个MCU的推挽输出、通信总线中主设备驱动的信号线（如UART_RX，当外部有上拉时）。

2.上拉输入

Input pull-up
数字输入，内部通过一个约40kΩ的电阻连接到VDD。
当外部无驱动时，引脚被默认拉至高电平。
需要读取低电平时，外部电路需提供足够的“灌电流”将电平拉低。
典型应用： 按键、开关，一端接地，按下时引脚被拉低。空闲时因上拉而保持高电平。

3.下拉输入

Input pull-down
数字输入，内部通过一个约40kΩ的电阻连接到VSS。
当外部无驱动时，引脚被默认拉至低电平。
需要读取高电平时，外部电路需提供足够的“拉电流”将电平拉高。
典型应用： 按键、开关，一端接VCC，按下时引脚被拉高。空闲时因下拉而保持低电平。

4.模拟输入

Analog Mode
引脚作为ADC（模数转换器） 或DAC（数模转换器） 的通道。
数字功能被完全禁用。施密特触发器关闭，上下拉电阻断开。引脚上的电压被直接送至模拟外设。
功耗最低的输入模式，因为数字输入电路不工作。
典型应用： 连接温度传感器、电位器、麦克风等模拟信号源。

输出模式

1.通用推挽输出

General-purpose output push-pull
最常用的输出模式。MCU可以主动驱动引脚为高电平（通过P-MOS管连接VDD）或低电平（通过N-MOS管连接VSS）。
输出能力强（STM32通常单引脚最大±20mA，具体看数据手册），高低电平由MCU的VDD和VSS决定。
两个MOS管像“推”和“挽”一样交替工作，因此得名。
典型应用： 驱动LED、继电器、蜂鸣器、电平控制等绝大多数需要数字输出的场景。

2.通用开漏输出

General-purpose output open-drain
只能主动拉低（N-MOS管工作），不能主动拉高（P-MOS管被禁用）。高电平状态需要依赖外部上拉电阻连接到正电源。
优点1：电平转换。外部上拉电阻可以接到一个不同于MCU VDD的电压上（如5V），实现与不同电压器件的通信。
优点2：“线与”功能。多个开漏输出的引脚可以直接连在一起，只要有一个拉低，总线即为低；所有都释放，总线才被上拉为高。这是I²C总线的基础。
缺点：驱动高电平时，电流由外部上拉电阻提供，因此上升沿速度较慢（RC充电）。
典型应用： I²C、SMBUS总线，驱动高于MCU电压的器件，需要“线与”逻辑的场景。

3.复用功能推挽输出

Alternate function output push-pull
引脚的控制权交给片上外设（如SPI、USART、TIM等），而非CPU或GPIO寄存器。输出特性与通用推挽完全相同。
例如，配置UART_TX引脚为此模式，数据将由USART外设自动产生并输出。
典型应用： 所有需要由硬件外设驱动的输出功能：SPI_SCK/MOSI、UART_TX、I2S_WS/CK、TIM_PWM输出等。

4.复用功能开漏输出

Alternate function output open-drain
引脚的控制权交给片上外设，输出特性与通用开漏完全相同。
典型应用： 需要开漏特性的硬件外设输出，最经典的就是 I²C 的 SDA 和 SCL 线。I²C外设会自动管理开漏输出和输入检测。

输出速度配置

在配置输出模式（推挽/开漏，通用/复用）时，MODEx位还用于选择输出速度，这对于信号完整性和EMI至关重要。

2 MHz（低速）： 用于低速信号，功耗和噪声低。
10 MHz（中速）： 常用平衡选择。
50 MHz（高速）： 用于高速信号（如SPI、USB），但需注意过冲和振铃。
（新一代STM32有更高速度选项，如Very High）

GPIO 相关寄存器

STM32 的 GPIO 分成了多组端口，端口所含引脚的工作模式通过多个寄存器（端口寄存器组）来进行配置，寄存器中的对应位控制该端口中对应的引脚。

比如 STM32F411 分成了5组端口：GPIOA、GPIOB、GPIOC、GPIOD 和 GPIOH。每组端口由10个32位的寄存器来控制。

注意:

寄存器常量中的 x 代表具体的端口号, 如 GPIOA、GPIOB 等。
寄存器中低位对应低序号引脚, 如 GPIOA_MODER 中 0~1 位对应 PA0, 30~31 位对应 PA15。

GPIOx_MODER（模式寄存器）

控制引脚的工作模式，每个引脚占2位：

00：输入模式（复位值）
01：通用输出模式
10：复用功能模式
11：模拟模式（用于ADC/DAC）

GPIOx_OTYPER（输出类型寄存器）

控制输出类型（每个引脚占1位）：

0：推挽输出（复位值）
1：开漏输出

GPIOx_OSPEEDR（输出速度寄存器）

控制输出驱动速度（每个引脚占2位）：

00：低速（复位值）
01：中速
10：高速
11：超高速（具体频率见芯片手册）

GPIOx_PUPDR（上拉/下拉寄存器）

(Pull-up Pull-down Register) 控制内部上下拉（每个引脚占2位）：

00：无上下拉（复位值）
01：上拉
10：下拉
11：保留

GPIOx_IDR（输入数据寄存器）

读取引脚输入状态（每个引脚占1位, 高16位保留, 只读）：

0：低电平
1：高电平

GPIOx_ODR（输出数据寄存器）

控制引脚输出电平（每个引脚占1位, 高16位保留）：

0：输出低电平
1：输出高电平

GPIOx_BSRR（置位/复位寄存器）

(Bit Set Reset Register) 原子操作设置/清除输出位：

BSy（00-15位）：设置对应引脚为高电平（写1有效，写0无影响）
BRy（16-31位）：设置对应引脚为低电平（写1有效，写0无影响）

注意:

GPIOx_ODR 与 GPIOx_BSRR 的区别在于, 设置某引脚的输出电平, 前者需要 读->改->写 后者可以直接写。

GPIOx_LCKR（配置锁寄存器）

锁定引脚配置，防止意外修改。

GPIOx_AFRL和GPIOx_AFRH（复用功能寄存器）

(Alternate Function Register Low/High) 选择引脚的复用功能（每个引脚占4位），AFRL用于引脚0-7，AFRH用于引脚8-15。

通过寄存器的编程

通过查阅芯片的参考手册可知, GPIO 各端口寄存器的在内存地址空间中的具体地址, 因此我们可以直接通过指针访问这些寄存器。

#define GPIOA_MODER *(volatile unsigned int *)(0x40020000UL)

GPIOA_MODER = 0x00000003;       // 向 GPIOA_MODER 寄存器中写入 0x03 
unsigned int a = GPIOA_MODER;   // 读取GPIOA_MODER寄存器的内容，并存入变量a

另外我们还可以通过预定义的 C 结构体指针访问寄存器, 这种方式要比直接使用地址友好得多。

// stm32f411xe.h
typedef struct
{
  __IO uint32_t MODER;   
  __IO uint32_t OTYPER;  
  __IO uint32_t OSPEEDR; 
  __IO uint32_t PUPDR;   
  __IO uint32_t IDR;     
  __IO uint32_t ODR;     
  __IO uint32_t BSRR;    
  __IO uint32_t LCKR;    
  __IO uint32_t AFRL;    
  __IO uint32_t AFRH;    
} GPIO_TypeDef;

#define GPIOA ((GPIO_TypeDef *)0x40020000UL)

GPIOA->MODER &= ~(3<<(5*2));      // 清除模式寄存器的 bit11:bit10 为 00 
                                  // - 操作的是第5个引脚 (5)
                                  // - 每个引脚占2个bit (*2)
                                  // - 清除2个bit (3 即 0b11)
GPIOA->MODER |=   1<<(5*2);       // 设置 bit11:bit10 = 01, 引脚PA5为推挽输出
GPIOA->BSRR   =   1<<5;           // 设置 bit5 为 1，PA5 输出高电平，开启LD2
GPIOA->BSRR   =   1<(5+16);       // 设置 bit21 为1，PA5 输出低电平，关闭LD2

通过 HAL 库的方式编程

// stm32f4xx_hal_gpio.h
typedef struct
{
  uint32_t Pin;         // 选择需要配置的引脚
  uint32_t Mode;        // 设置所选引脚的工作模式
  uint32_t Pull;        // 使能所选引脚的上拉/下拉电阻
  uint32_t Speed;       // 设置所选引脚的输出速度
  uint32_t Alternate;   // 设置引脚的复用功能
} GPIO_InitTypeDef;

typedef enum
{
  GPIO_PIN_RESET = 0u,  // 引脚低电平
  GPIO_PIN_SET          // 引脚高电平
} GPIO_PinState;

#define GPIO_PIN_0                 ((uint16_t)0x0001)  /* Pin 0 selected    */
                                                       /* ..............    */
#define GPIO_PIN_15                ((uint16_t)0x8000)  /* Pin 15 selected   */
#define GPIO_PIN_All               ((uint16_t)0xFFFF)  /* All pins selected */

#define GPIO_PIN_MASK              0x0000FFFFu /* PIN mask for assert test */

// 配置引脚 PA5和 PA15:推挽输出，无上拉/下拉，输出速度为低速
GPIO_InitTypeDef GPIO_InitStruct = {0};
GPIO_InitStruct.Pin   = GPIO_PIN_5 | GPIO_PIN_15;
GPIO_InitStruct.Mode  = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull  = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

// PA15 引脚设置为低电平
HAL_GPIO_WritePin(GPIOA, GPIO_PIN_15, GPIO_PIN_RESET);

参考

STM32 GPIO 引脚模式

STM32 基础

骑驴的柒零 — Sat, 24 Jan 2026 14:50:00 GMT

@@ Tags: STM32
@@ Date: 2026-01-24 2250
@@ Note: ~

STM32 维基百科

简介

STM32 是意法半导体（STMicroelectronics）公司基于 ARM Cortex-M 内核开发的32位高性能微控制器系列。它是全球最受欢迎、生态最丰富的MCU家族之一。

STM32 微控制器分为多个系列，这些系列都基于相同的32 位ARM处理器内核：Cortex-M0、M0+、M3、M4 M7、M33、M55 或 M85。每个微控制器的内部结构都包含一个或多个 ARM 处理器内核、闪存、静态RAM、调试接口以及各种外设。

2006年10月 ST 获得了ARM Cortex-M3内核的授权。
2007年06月 ST 在北京发布了基于 ARM Cortex-M3 的 STM32 F1 系列芯片。
2026年01月 STM32 自2007年发布以来，出货量超过了 150 亿颗。

部分芯片介绍

TODO 命名

STM32F103C8T6

采用 ARM Cortex-M3 内核，主频72MHz，拥有 64KB Flash（存储程序）和 20KB RAM（运行时内存），性能足以应对多数中小型嵌入式项目。
多达 37个可用GPIO，集成3个USART、2个SPI、2个I2C、1个USB和1个CAN总线，方便连接各类模块。
内置2个12位ADC，可用于采集传感器数据。
多个定时器，支持PWM输出，非常适合控制电机、舵机等。

USB转串口模块：用于串口通信和打印调试信息（很多核心板的USB口仅供电）需要模块和 CH340/CH341驱动。

STM32F411RET6

TODO

其他有意思的型号

STM32C0
- 入门级、性价比之王。主打“32位性能，8位成本”
- 提供8到64引脚的多种封装8引脚是其最小封装(STM32C011F4U6TR)，非常适合引脚要求少的应用。

开发环境

安装 STM32CubeMX
- 安装 MCU 固件包
  - 包括: 文档, 驱动, 中间件, 参考例程
安装 MDK-ARM (Keil MDK)
安装 ST-Link 驱动
- 搜索 STSW-LINK007
- 也可以在 MDK-ARM 安装目录找到: Keil_v5\ARM\STLink\USBDriver
安装串口调试软件
- SSCOM
- XCOM
- SecureCRT

环境设置

STM32CubeMX
- 选择芯片: STM32F103C8T6
- 开启调试: System Core -> sys -> Serial Wire
- 时钟来源: System Core -> rcc -> Crystal/Ceramic Resonato
- 选择时钟: HSI -> PLLCLK-> 72MHz
- 设置引脚
- 生成代码
MDK-ARM
- 打开工程
- 编辑设置: Edit -> Configuration -> Encoding: 设置为 Encode in UTF-8 without signature
- 调试设置: Debug -> Debugger -> ST-Link
- 串口支持: Options for Target -> Target -> 勾选上 “Use MicroLIB”
- 自动运行: Options for Target -> Utilities -> Settings
  - Pack: 取消勾选 “Enable”
  - Flash Download: 勾选上 “Reset and Run”
- 代码优化: Options for Target -> C/C++ (AC6) -> Optimization:
  - -O0 表示不优化, 用于调试
  - -O2 默认优化

辅助代码标记

在 STM32CubeIDE/STM32CubeMX 生成的工程中，/* USER CODE BEGIN xxx */ 和 /* USER CODE END xxx */ 这些注释标记定义了用户代码的安全区域。

当你使用 STM32CubeMX 重新生成代码时：

标记内的用户代码会被保留
标记外的代码可能会被覆盖

下面是常用标记的说明:

/* USER CODE BEGIN Includes */      // Private includes (包含自定义头文件)
/* USER CODE END Includes */

/* USER CODE BEGIN PV */            // Private variables (私有变量声明)
/* USER CODE END PV */

/* USER CODE BEGIN PFP */           // Private function prototypes (私有函数原型声明)
/* USER CODE END PFP */

/* USER CODE BEGIN ET */            // External Types（外部类型定义）
/* USER CODE END ET */

/* USER CODE BEGIN EM */            // Error Macros（错误宏定义）
/* USER CODE END EM */

/* USER CODE BEGIN PTD */           // Private typedef (私有类型定义)
/* USER CODE END PTD */

/* USER CODE BEGIN PD */            // Private define (不带参数的宏定义)
/* USER CODE END PD */

/* USER CODE BEGIN PM */            // Private macro (带参数的宏定义)
/* USER CODE END PM */

时钟配置

内部时钟 LSI HSI
- STM32 MCU 内部自带RC振荡电路，其内部时钟就是RC振荡器产生的。
- 但是RC振荡器精度远低于晶振，且容易受到温度的影响。
外部时钟 LSE HSE
- 一般有两种接法:
- 外部接有源晶振或其他直接时钟输入源：BYPASS Clock Source 模式（旁路时钟源）
- 外部接无源晶振：Crystal/Ceramic Resonator模式（晶体/陶瓷晶振）

VS Code 开发环境

STM32 VS Code扩展

术语

DMA

直接存储器访问方式(DMA), 是在处理器内部建立片内外设和内存之间的数据传输通道，传输过程不需
要处理器参与。

DMA方式由硬件实现，特别适合于批量数据传输的场合。

调试/下载器

用于烧录和调试代码。一般是 ST-Link V2，比DAP-Link对新手更友好。

Linux 挂载群辉硬盘

骑驴的柒零 — Sun, 18 Jan 2026 12:52:00 GMT

@@ Tags: Synology;Btrfs
@@ Date: 2026-01-18
@@ Note:

Linux 系统中挂载 Synology Btrfs 文件系统

zero@ubuntu-2404-x64:/mnt$ lsblk
NAME                            MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
sda                               8:0    0    40G  0 disk
├─sda1                            8:1    0     1M  0 part
├─sda2                            8:2    0     2G  0 part  /boot
└─sda3                            8:3    0    38G  0 part
  └─ubuntu--vg-ubuntu--lv       252:0    0    19G  0 lvm   /
sdb                               8:16   0 465.8G  0 disk  # 这是我的群辉磁盘
├─sdb1                            8:17   0     8G  0 part
│ └─md125                         9:125  0     0B  0 md
├─sdb2                            8:18   0     2G  0 part
│ └─md126                         9:126  0     0B  0 md
└─sdb3                            8:19   0 455.5G  0 part
  └─md127                         9:127  0 455.5G  0 raid1
    ├─vg3-syno_vg_reserved_area 252:1    0    12M  0 lvm
    └─vg3-volume_3              252:2    0   455G  0 lvm

zero@ubuntu-2404-x64:~$ cat /proc/mdstat
Personalities : [raid0] [raid1] [raid6] [raid5] [raid4] [raid10]
md127 : active raid1 sdb3[0]
      477662208 blocks super 1.2 [1/1] [U]

md125 : inactive sdb1[29](S)
      8387584 blocks super 1.2

md126 : inactive sdb2[29](S)
      2096128 blocks super 1.2

unused devices: 


zero@ubuntu-2404-x64:~$ sudo lvs
  LV        VG        Attr       LSize   Pool Origin Data%  Meta%  Move Log Cpy%Sync Convert
  ubuntu-lv ubuntu-vg -wi-ao---- <19.00g


zero@ubuntu-2404-x64:~$ sudo mdadm --detail /dev/md127
/dev/md127:
           Version : 1.2
     Creation Time : Tue Jul  2 22:41:46 2024
        Raid Level : raid1
        Array Size : 477662208 (455.53 GiB 489.13 GB)
     Used Dev Size : 477662208 (455.53 GiB 489.13 GB)
      Raid Devices : 1
     Total Devices : 1
       Persistence : Superblock is persistent

       Update Time : Thu Jan  8 23:56:44 2026
             State : clean, FAILED
    Active Devices : 1
   Working Devices : 1
    Failed Devices : 0
     Spare Devices : 0

Consistency Policy : resync

    Number   Major   Minor   RaidDevice State
       0       8       19        0      active sync   missing

在高版本的内核中直接挂载群晖 Btrfs 卷很可能会失败:

$ sudo mount -t btrfs -o ro /dev/vg3/volume_3 /mnt/syno-btrfs
mount: /mnt/syno-btrfs: can't read superblock on /dev/mapper/vg3-volume_3.
       dmesg(1) may have more information after failed mount system call.

原因是:

Synology在BTRFS文件系统中使用了自定义的标志位（flags）

从Linux 5.4-rc1开始，内核添加了严格的BTRFS根标志检查（commit 259ee7754b67），拒绝挂载含有不支持标志的文件系统。

这个检查被反向移植到Ubuntu LTS版本（包括4.15内核），导致官方Synology恢复指南失效。

解决方案:

使用特定内核版本

Ubuntu Bionic（18.04） + 内核 4.15.0-108
Ubuntu Xenial（16.04） + 内核 4.15.0-107

操作步骤

下载安装 Ubuntu Bionic（18.04）版本, 开始安装服务器版本, 但安装过程总是出现错误, 转而安装了 desktop 版本.

sudo apt install linux-image-4.15.0-108-generic
sudo reboot
重启时，在Grub引导界面（可能需要按 Shift 或 Esc 键唤出）选择 “Advanced options for Ubuntu”，然后找到并启动你刚安装的 4.15 内核
确定物理连接情况: sudo lsblk -f
sudo apt install -y btrfs-progs mdadm lvm2
sudo mdadm --assemble --scan
1. 这一步如果失败, 可能需要先停止现有的md设备
  - 检查md设备 cat /proc/mdstat
  - 再次执行: sudo mdadm --assemble --scan --detail
2. 到了这一步, 在桌面版系统上, 可以通过文件浏览器自动挂载到 /media// 目录下
sudo vgscan --mknodes
sudo vgchange -ay
sudo lvs
sudo mount -o ro,rescue=all /dev/你的磁盘分区 /mnt/recovery
1. 或者用 -o ro,rescue=usebackuproot 选项

安全的移除设备

首先卸载文件系统
- sudo umount /dev/你的磁盘分区
- sudo umount /dev/sdb*
停止LVM逻辑卷, 如果使用LVM逻辑卷
- sudo vgchange -an vg1
停止md设备, 如果使用mdadm
- sudo mdadm --stop /dev/md*
确保没有进程占用设备
- sudo lsof | grep /dev/sdb
- sudo fuser -mv /dev/sdb*
刷新并移除设备
- sudo sync
- sudo blockdev --flushbufs /dev/sdb

或者(推荐)

# 查看设备信息
udisksctl status

# 卸载并弹出（会自动执行所有必要步骤）
udisksctl unmount -b /dev/sdb*
udisksctl power-off -b /dev/sdb

原因分析

群辉断电后, 出现 Btrfs 磁盘可以读取目录, 但不能读取内容。

将磁盘挂载到 Windows 后, 通过 winhex 可以正常打开, 并可以拷贝磁盘数据建立磁盘镜像。
通过 Ubuntu 挂载后, 也是可以访问目录, 但不能拷贝文件(出现io无响应)。
该磁盘作为下载磁盘，断电时可能正在写入数据（少量数据）。

这是 典型的 Btrfs 在异常断电后出现的“逻辑一致性破坏 + 读路径差异”问题:

断电导致“全盘”或全局性问题，而不是仅仅影响正在写入的单个文件，主要是因为 Btrfs是一个“写时复制”（CoW）的、日志式元数据文件系统。
简单来说，一次断电可能同时破坏了用于描述全盘文件布局的“地图”（元数据），以及文件系统记录自己变更的“笔记本”（日志）

解决方案

能识别到卷的基础上, 不挂载文件系统, 执行 btrfs restore

btrfs restore -v [-i -s] /dev/sdX /path/to/backup/

常用参数:

-v
显示正在恢复的文件
-vv
显示 inode、extent、block 级别信息
-i
交互式: 遇到错误时, 询问是否跳过
-s
跳过错误
-x
跳过 xattr / ACL / SELinux label（救命参数）

挂载 ext4

挂载流程基本与 Btrfs 相同, 磁盘结构基本相同, 唯一区别就是卷的文件系统不同。

sdb                               8:16   0 465.8G  0 disk
├─sdb1                            8:17   0     8G  0 part
│ └─md125                         9:125  0     8G  0 raid1
├─sdb2                            8:18   0     2G  0 part
│ └─md126                         9:126  0     2G  0 raid1
└─sdb3                            8:19   0 455.5G  0 part
  └─md127                         9:127  0 455.5G  0 raid1
    ├─vg1-syno_vg_reserved_area 253:0    0    12M  0 lvm
    └─vg1-volume_1              253:1    0   455G  0 lvm   /mnt/g

参考链接

git-crypt 小记

骑驴的柒零 — Wed, 07 Jan 2026 13:04:00 GMT

@@ Tags: git-crypt
@@ Date: 2026-01-07

git-crypt 是一个用于git仓库中文件加密的工具，支持 git 仓库中的文件进行透明的加密和解密。

git-crypt 允许选择某些文件在提交(commit) 时加密，在检出(checkout) 时解密。

git-crypt 也会优雅地降级，因此没有秘钥的开发人员仍然可以克隆并提交到包含加密文件的存储库中。这允许您将秘密资料（如密钥或密码）存储在与代码相同的存储库中，而不需要锁定整个存储库。

安装

git clone https://github.com/AGWA/git-crypt.git
cd git-crypt
make

报错如下:

g++ -Wall -pedantic -Wno-long-long -O2 -std=c++11   -c -o util.o util.cpp
In file included from util.cpp:156:
util-unix.cpp: In member function ‘void temp_fstream::open(std::ios_base::openmode)’:
util-unix.cpp:79:38: 错误：‘mkstemp’ was not declared in this scope; did you mean ‘mkdtemp’?
   79 |         int                     fd = mkstemp(path);
      |                                      ^~~~~~~
      |                                      mkdtemp
util-unix.cpp: In function ‘std::string our_exe_path()’:
util-unix.cpp:135:51: 错误：‘realpath’在此作用域中尚未声明
  135 |                 char*           resolved_path_p = realpath(argv0, nullptr);
      |                                                   ^~~~~~~~
make: *** [<内置>：util.o] 错误 1

参考: https://github.com/AGWA/git-crypt/issues/152

增加 -U__STRICT_ANSI__ 单独编译 util.cpp

g++ -Wall -pedantic -Wno-long-long -O2 -std=c++11 -U__STRICT_ANSI__  -c -o util.o util.cpp
make

# 安装到 /usr/local/bin
make install

# 安装到 /bin
make install PREFIX=

注意: 在 cygwin 下编译并在 windows 下运行时, 存在 bug.

使用

# 配置仓库以使用 git-crypt
# 此时会生成秘钥: .git/git-crypt/key/default
cd repo
git-crypt init

# 通过创建 .gitattributes 文件来指定要加密的文件：
echo "*.key        filter=git-crypt diff=git-crypt" >> .gitattributes
echo "*.pem        filter=git-crypt diff=git-crypt" >> .gitattributes
echo "secretdir/** filter=git-crypt diff=git-crypt" >> .gitattributes

# 使用 GPG 与他人（或自己）共享存储库
git-crypt add-gpg-user 

# 或者，您可以导出对称密钥 (.git/git-crypt/key/default)
# 如果不导出, 则一旦锁住存储库, 则无法解锁(令人深刻的教训😭)
git-crypt export-key /path/to/key

# 克隆包含加密文件的存储库后，使用 GPG 解锁
git-crypt unlock

# 或者使用对称密钥
git-crypt unlock /path/to/key

局限性

git-crypt 依赖于 Git 过滤器，而这些过滤器在设计之初并未考虑加密。

因此，对于需要加密仓库中大部分或全部文件的情况，git-crypt 并非最佳工具。

git-crypt 真正擅长的场景是：你的仓库大部分内容是公开的，但你需要加密少数几个文件（例如名为 *.key 的私钥文件，或包含 API 凭据的文件）。如果需要加密整个仓库，请考虑使用像 git-remote-gcrypt 这样的系统。

卷积神经网络-卷积层

骑驴的柒零 — Wed, 24 Dec 2025 16:54:00 GMT

@@ Tags: 卷积神经网络;卷积层
@@ Date: 12/25/2025, 6:15:47

从数据以及算法层面上对卷积层做一个演示，理解卷积的过程以及反向传播的原理。

首先准备数据

import numpy as np
from termcolor import cprint

# 输入样本、卷积核、卷积层偏置项
sample = np.arange(16).reshape(4, 4)
filter = np.array([[-1, -2, 0], [1, 0, -2], [0, -1, 2]])
biases = np.array([5])

# 预设参数
N, channels = (1, 1)
H, W = sample.shape
FH, FW = filter.shape
padding = 0
stride = 1
out_h = (H + 2 * padding - FH) // stride + 1
out_w = (W + 2 * padding - FW) // stride + 1

cprint(f'sample:\n{sample}\n')
cprint(f'filter:\n{filter}\n', 'magenta')

输出:

sample:
[[ 0  1  2  3]
 [ 4  5  6  7]
 [ 8  9 10 11]
 [12 13 14 15]]

filter:
[[-1 -2  0]
 [ 1  0 -2]
 [ 0 -1  2]]

前向传播(卷积)过程

卷积核在输入图像上滑动，将每次滑动产生卷积窗口的数据拷贝出来，以便后面矩阵乘法计算卷积。

# 滑动步数(输出特征图的每个元素都是一个滑动的卷积窗口) * 卷积窗口
matrix = np.zeros((out_h, out_w,
                   FH, FW), np.int64)

# 在输入数据上滑动, 拷贝每个滑动窗口的数据到矩阵中
for i in range(out_h):
    for j in range(out_w):
        y = i * stride
        x = j * stride
        y_end = y + FH
        x_end = x + FW

        matrix[i, j] = sample[y:y_end, x:x_end]

cprint(f'matrix:\n{matrix}\n', 'green')

输出:

32mmatrix:
[[[[ 0  1  2]
   [ 4  5  6]
   [ 8  9 10]]

  [[ 1  2  3]
   [ 5  6  7]
   [ 9 10 11]]]


 [[[ 4  5  6]
   [ 8  9 10]
   [12 13 14]]

  [[ 5  6  7]
   [ 9 10 11]
   [13 14 15]]]]

将卷积窗口中的像素值与卷积核的权重执行点积，得到输出特征图。

# 将矩阵表示的滑动窗口的数据重塑为行格式, 以便进行矩阵乘法
matrix = matrix.reshape(-1, FH * FW)
cprint(f'matrix:\n{matrix}\n', 'cyan')

# 将卷积核矩阵重塑为列格式
weight = filter.reshape(-1).T
cprint(f'weight:\n{weight}\n', 'magenta')

# 执行矩阵乘法实现卷积
output = np.dot(matrix, weight) + biases
cprint(f'biases:\n{biases}\n', 'green')
cprint(f'output:\n{output}\n', 'green')

# 将输出重塑为特征图的形状
output = output.reshape(-1, out_h, out_w)
cprint(f'output.reshape:\n{output}\n', 'green')

输出:

matrix:
[[ 0  1  2  4  5  6  8  9 10]
 [ 1  2  3  5  6  7  9 10 11]
 [ 4  5  6  8  9 10 12 13 14]
 [ 5  6  7  9 10 11 13 14 15]]

weight:
[-1 -2  0  1  0 -2  0 -1  2]

biases:
[5]

output:
[ 6  3 -6 -9]

output.reshape:
[[[ 6  3]
  [-6 -9]]]

以上就是卷积到输出特征图的过程。为了便于理解，我们忽略了 多样本、多通道的数据维度。

前向传播的数学表达

单通道卷积（基础形式）

设输入 sample 是一个二维矩阵 $X$，卷积核为 $W$，偏置为 $b$。输出特征图 $Y$ 的每一个元素 $y_{i,j}$ 的计算公式为（步幅=1，填充=0）：

$$
y_{i,j} = \sum_{m=0}^{k-1} \sum_{n=0}^{k-1} (x_{i+m, j+n} \cdot w_{m,n}) + b
$$

$x_{i+m, j+n}$：输入图像在卷积窗口内的每一个像素。
$w_{m,n}$：卷积核在 $(m,n)$ 位置的权重。
$k$：卷积核的大小（假设为 $k \times k$）。

多通道卷积（实际工程形式）

在深度学习中，输入通常是三维的 通道x高x宽（$C \times H \times W$），前向传播会涉及多个输入通道的累加。

假设：

输入 $X$ 的维度为 $(C_{in}, H_{in}, W_{in})$
卷积核 $W$ 的维度为 $(C_{out}, C_{in}, k, k)$
输出 $Y$ 的维度为 $(C_{out}, H_{out}, W_{out})$

第 $f$ 个输出特征图（Feature Map）的计算公式为：

$$
Y_f = \sum_{c=1}^{C_{in}} (X_c \star W_{f,c}) + b_f
$$

其中 $\star$ 表示二维卷积操作。这意味着：

每一个输出通道都是所有输入通道与对应卷积核参数卷积后的总和。
$C_{out}$（输出通道数）本质上就是这一层所使用的卷积核（Filters/Kernels）的数量。

或者更详细的公式:

$$
Y[c_{\text{out}}, i, j] = \sum_{c_{\text{in}}=0}^{C_{\text{in}}-1} \sum_{m=0}^{k-1} \sum_{n=0}^{k-1} X[c_{\text{in}}, i+m, j+n] \cdot W[c_{\text{out}}, c_{\text{in}}, m, n] + B[c_{\text{out}}]
$$

im2col、col2im函数

经过上面的步骤，可知卷积算法的过程实际上分为两步：

将输入图片按照卷积窗口展开
将展开的数据矩阵与权重矩阵进行矩阵乘法

因此，提供了 im2col 和 col2im 函数，用于将输入数据进行展开和还原。

im2col函数和col2im函数的实现如下：

def im2col(input_data, filter_h, filter_w, stride=1, pad=0):
    """
    将输入图像转换为列矩阵，以便于后续的矩阵乘法运算。

    参数：
    input_data: 输入数据，形状为(N, C, H, W)
    stride : 卷积步长
    pad : 零填充大小
    return: 转换后的二维矩阵, 形状为(N * out_h * out_w, C * filter_h * filter_w)
    """
    N, C, H, W = input_data.shape
    out_h = (H + 2 * pad - filter_h) // stride + 1
    out_w = (W + 2 * pad - filter_w) // stride + 1

    # 填充 (Padding)
    img = np.pad(input_data, [(0, 0), (0, 0),
                 (pad, pad), (pad, pad)], 'constant')

    # 每一行的大小是: 通道数 * 卷积核高 * 卷积核宽
    # 这里的形状定义只是为了方面下面的拷贝操作, 最后会进行维度重排
    col = np.zeros((N, C, filter_h, filter_w, out_h, out_w))

    for y in range(filter_h):
        y_max = y + stride * out_h
        for x in range(filter_w):
            x_max = x + stride * out_w
            col[:, :, y, x, :, :] = img[:, :, y:y_max:stride, x:x_max:stride]

    # 转置并重塑
    return col.transpose(0, 4, 5, 1, 2, 3).reshape(N * out_h * out_w, -1)


def col2im(col, input_shape, filter_h, filter_w, stride=1, pad=0):
    """
    将列矩阵转换回图像格式，用于反向传播

    参数:
    col: 展开后的列矩阵, 形状为 (N * out_h * out_w, C * filter_h * filter_w)
    input_shape: 原始数据的形状 (N, C, H, W)

    返回: 重建的图像(把col中卷积窗口的值“累加”回来, 因此输出与输入是不同的: col2im(im2col(x)) ≠ x)
    """
    N, C, H, W = input_shape
    out_h = (H + 2 * pad - filter_h) // stride + 1
    out_w = (W + 2 * pad - filter_w) // stride + 1

    # 重塑并转置回原始维度顺序
    col = col.reshape(N, out_h, out_w, C, filter_h,
                      filter_w).transpose(0, 3, 4, 5, 1, 2)

    img = np.zeros((N, C, H + 2 * pad + stride - 1, W + 2 * pad + stride - 1))

    for y in range(filter_h):
        y_max = y + stride * out_h
        for x in range(filter_w):
            x_max = x + stride * out_w
            # 关键：累加重叠部分的梯度
            img[:, :, y:y_max:stride, x:x_max:stride] += col[:, :, y, x, :, :]

    # 切除 padding 部分
    return img[:, :, pad:H + pad, pad:W + pad]

images = sample.reshape(1, 1, H, W)
cprint(f'images:\n{images}\n')

col = im2col(images, FH, FW)
cprint(f'col:\n{col}\n')

img = col2im(col, images.shape, FH, FW)
cprint(f'img:\n{img}\n', 'yellow')

输出:

images:
[[[[ 0  1  2  3]
   [ 4  5  6  7]
   [ 8  9 10 11]
   [12 13 14 15]]]]

col:
[[ 0.  1.  2.  4.  5.  6.  8.  9. 10.]
 [ 1.  2.  3.  5.  6.  7.  9. 10. 11.]
 [ 4.  5.  6.  8.  9. 10. 12. 13. 14.]
 [ 5.  6.  7.  9. 10. 11. 13. 14. 15.]]

img:
[[[[ 0.  2.  4.  3.]
   [ 8. 20. 24. 14.]
   [16. 36. 40. 22.]
   [12. 26. 28. 15.]]]]

观察images到img的结果可以发现:

中间像素被卷积窗口覆盖了多次，在 col2im 中被多次累加了。 而边角像素只被覆盖一次，所以它们是一样的。

因此, 对于边缘非边角元素被累加两次, 中间元素被累加四次。

关于输出的形状, 可能与其他实现存在差异，但不影响逻辑。

再看看完整的RGB图像的数据样本:

cprint(f'RGB三通道图片:\n')
C = 3  # RGB 三通道
img = np.arange(1*C*H*W).reshape(1, C, H, W)
col = im2col(img, FH, FW)
# cprint(f'原始数据:\n{img}\n')
cprint(f'卷积窗口数据:\n{col}\n', 'green')

FN = 2  # 卷积核个数
kernel = np.arange(FN*C*FH*FW).reshape(FN, C, FH, FW)
weight = kernel.reshape(FN, -1).T
# cprint(f'卷积核:\n{kernel}\n', 'red')
# cprint(f'权重值:\n{weight}\n', 'red')
output = np.dot(col, weight)
cprint(f'特征数据:\n{output}\n', 'yellow')

# 转换为特征图
out_h, out_w = (2, 2)  # 特征图大小
output = output.reshape(N, out_h, out_w, -1)
output = output.transpose(0, 3, 1, 2)
cprint(f'特征图:\n{output}\n', 'red')

输出:

RGB三通道图片:

卷积窗口数据:
[[ 0.  1.  2.  4.  5.  6.  8.  9. 10. 16. 17. 18. 20. 21. 22. 24. 25. 26.
  32. 33. 34. 36. 37. 38. 40. 41. 42.]
 [ 1.  2.  3.  5.  6.  7.  9. 10. 11. 17. 18. 19. 21. 22. 23. 25. 26. 27.
  33. 34. 35. 37. 38. 39. 41. 42. 43.]
 [ 4.  5.  6.  8.  9. 10. 12. 13. 14. 20. 21. 22. 24. 25. 26. 28. 29. 30.
  36. 37. 38. 40. 41. 42. 44. 45. 46.]
 [ 5.  6.  7.  9. 10. 11. 13. 14. 15. 21. 22. 23. 25. 26. 27. 29. 30. 31.
  37. 38. 39. 41. 42. 43. 45. 46. 47.]]

特征数据:
[[10197. 25506.]
 [10548. 26586.]
 [11601. 29826.]
 [11952. 30906.]]

特征图:
[[[[10197. 10548.]
   [11601. 11952.]]

  [[25506. 26586.]
   [29826. 30906.]]]]

对比上一个单通道数据, 可以看出 im2col 函数输出的二维数据中, 每一行表示样本在卷积核中滑动时的窗口数据。

如果有多个通道, 则同时包含多个通道的窗口数据。本质上就是为了满足后面的矩阵运算, 因此需要先构建数据。

再看特征数据部分, 每一行是卷积核在当前滑动的卷积窗口中的特征值, 列是不同的卷积核。

通过特征数据变形再重排后, 就可以得到卷积核对应的特征图了。

特征图浓缩了整个输入样本相对于卷积核的特性信息，相当于数据被卷积核筛选出来的结果，因此卷积核又叫过滤器。

卷积层的实现

class ConvolutionalLayer:
    """卷积层实现"""

    def __init__(self, weights, biases, stride=1, padding=0):
        """
        初始化卷积层

        参数:
        weights : 卷积核权重，形状为(输出通道数, 输入通道数, 高度, 宽度)
        biases : 偏置项，形状为(输出通道数,)
        stride : 卷积步长
        padding : 零填充大小
        """
        self.weights = weights
        self.biases = biases
        self.stride = stride
        self.padding = padding

        # 中间变量（用于反向传播）
        self.x = None
        self.col = None
        self.colWeights = None

        # 参数的梯度
        self.dweights = None
        self.dbiases = None

    def forward(self, input_data):
        """
        前向传播

        参数:
        input_data : 输入数据，形状为(样本大小, 通道数, 高度, 宽度)

        返回:
        output : 卷积核对应的特征图，形状为(N, FN, out_h, out_w)
        """
        FN, C, FH, FW = self.weights.shape
        N, C, H, W = input_data.shape

        # 计算输出特征图的大小
        out_h = (H + 2 * self.padding - FH) // self.stride + 1
        out_w = (W + 2 * self.padding - FW) // self.stride + 1

        # 将输入图像转换为行矩阵
        row_matrix = im2col(input_data, FH, FW, self.stride, self.padding)

        # 将权重矩阵重塑为列格式
        column_matrix = self.weights.reshape(FN, -1).T

        # 执行矩阵乘法实现卷积
        output = np.dot(row_matrix, column_matrix) + self.biases

        # 将输出重塑为正确的4维格式
        output = output.reshape(N, out_h, out_w, -1)
        output = output.transpose(0, 3, 1, 2)

        # 保存中间变量用于反向传播
        self.x = input_data
        self.col = row_matrix
        self.colWeights = column_matrix

        return output

    def backward(self, dout):
        """
        反向传播

        参数:
        dout : 输出层的梯度, 形状(N, FN, out_h, out_w)

        返回:
        gradient_input : 输入层的梯度
        """
        FN, C, FH, HW = self.weights.shape

        # 调整梯度输出的形状, 通道调整到最后
        dout = dout.transpose(0, 2, 3, 1).reshape(-1, FN)

        # 计算偏置项的梯度, 每个特征图的梯度求和作为该卷积核的偏置
        self.dbiases = np.sum(dout, axis=0)

        # 计算权重的梯度
        self.dweights = np.dot(self.col.T, dout)
        self.dweights = self.dweights.transpose(1, 0).reshape(FN,
                                                              C,
                                                              FH,
                                                              HW)

        # 计算输入数据的梯度
        dcol = np.dot(dout, self.colWeights.T)
        dx = col2im(dcol,
                    self.x.shape,
                    FH,
                    HW,
                    self.stride,
                    self.padding)
        return dx


# -------------------------------------------------------------------
# 构造输入
x = np.random.randn(2, 3, 5, 5)        # N=2, C=3
w = np.random.randn(4, 3, 3, 3)        # FN=4
b = np.random.randn(4)

conv = ConvolutionalLayer(w, b, stride=1, padding=1)

# 前向传播
out = conv.forward(x)

# 注意输出格式为: (N, FN, out_h, out_w)
# 这表示每个样本的
print("output shape:", out.shape)  # (2, 4, 5, 5)

# 构造上游梯度
dout = np.random.randn(*out.shape)

# backward
dx = conv.backward(dout)
print("dx shape:", dx.shape)
print("dw shape:", conv.dweights.shape)
print("db shape:", conv.dbiases.shape)

输出:

output shape: (2, 4, 5, 5)
dx shape: (2, 3, 5, 5)
dw shape: (4, 3, 3, 3)
db shape: (4,)


def numerical_gradient(conv, x, dout, eps=1e-5):
    grad_w = np.zeros_like(conv.weights)

    it = np.nditer(conv.weights, flags=['multi_index'], op_flags=['readwrite'])
    while not it.finished:
        idx = it.multi_index
        old = conv.weights[idx]

        conv.weights[idx] = old + eps
        out1 = conv.forward(x)
        loss1 = np.sum(out1 * dout)

        conv.weights[idx] = old - eps
        out2 = conv.forward(x)
        loss2 = np.sum(out2 * dout)

        grad_w[idx] = (loss1 - loss2) / (2 * eps)
        conv.weights[idx] = old
        it.iternext()

    return grad_w


# 数值梯度 vs 反向传播
num_dw = numerical_gradient(conv, x, dout)
max_diff = np.max(np.abs(num_dw - conv.dweights))
print("max diff:", max_diff)

输出:

max diff: 2.0845973836003395e-09

反向传播的数学表达

反向传播的主要目标是计算两个梯度：

损失函数对输入的梯度（用于将误差传递给前一层）。
损失函数对卷积核参数的梯度（用于更新当前层的权重）。

在卷积层的前向传播中，输入矩阵 $X \in \mathbb{R}^{C_{\text{in}} \times H_{\text{in}} \times W_{\text{in}}}$ 与卷积核 $W \in \mathbb{R}^{C_{\text{out}} \times C_{\text{in}} \times k_H \times k_W}$ 进行卷积得到输出 特征图 $Y \in \mathbb{R}^{C_{\text{out}} \times H_{\text{out}} \times W_{\text{out}}}$。

在反向传播时，我们已经从下一层拿到了输出梯度（$\frac{\partial L}{\partial Y}$），通常被称为“误差项”或 $\delta$。

$$
\frac{\partial L}{\partial Y} \in \mathbb{R}^{C_{\text{out}} \times H_{\text{out}} \times W_{\text{out}}}
$$

设误差或损失函数为:

$$
L = Loss(Y)
$$

根据 前向传播的公式：

$$
Y = \sum_{c=1}^{C_{in}} (X \star W) + b
$$

分别计算 $\frac{\partial L}{\partial W}$ 、$\frac{\partial L}{\partial X}$ 和 $\frac{\partial L}{\partial b}$。

对权重 $W$ 求导（更新参数）

根据链式法则，对于权重 $W[c_{\text{out}}, c_{\text{in}}, i, j]$：

$$
\frac{\partial L}{\partial W[c_{\text{out}}, c_{\text{in}}, i, j]} = \sum_{m=0}^{H_{\text{out}}-1} \sum_{n=0}^{W_{\text{out}}-1} \frac{\partial L}{\partial Y[c_{\text{out}}, m, n]} \cdot \frac{\partial Y[c_{\text{out}}, m, n]}{\partial W[c_{\text{out}}, c_{\text{in}}, i, j]}
$$

从前向公式可知：

$$
\frac{\partial Y[c_{\text{out}}, m, n]}{\partial W[c_{\text{out}}, c_{\text{in}}, i, j]} = X[c_{\text{in}}, m+i, n+j]
$$

因此：

3.2 向量化形式（互相关运算）

这等价于对每个输出通道 $c_{\text{out}}$ 和输入通道 $c_{\text{in}}$，执行以下互相关运算：

$$
\frac{\partial L}{\partial W[c_{\text{out}}, c_{\text{in}}]} = X[c_{\text{in}}] \star \frac{\partial L}{\partial Y[c_{\text{out}}]}
$$

完整公式：
$$
\boxed{\frac{\partial L}{\partial W} = X \star \frac{\partial L}{\partial Y}}
$$

其中 $\star$ 是互相关运算，维度变化：

$X$: $(C_{\text{in}}, H_{\text{in}}, W_{\text{in}})$
$\frac{\partial L}{\partial Y}$: $(C_{\text{out}}, H_{\text{out}}, W_{\text{out}})$
$\frac{\partial L}{\partial W}$: $(C_{\text{out}}, C_{\text{in}}, k_H, k_W)$

对输入 $X$ 求导（传递误差）

为了让误差继续向前传播，我们需要计算 $\frac{\partial L}{\partial X}$。

对于输入元素 $X[c_{\text{in}}, h_x, w_x]$：

$$
\frac{\partial L}{\partial X[c_{\text{in}}, h_x, w_x]} = \sum_{c_{\text{out}}=0}^{C_{\text{out}}-1} \sum_{h=0}^{H_{\text{out}}-1} \sum_{w=0}^{W_{\text{out}}-1} \frac{\partial L}{\partial Y[c_{\text{out}}, h, w]} \cdot \frac{\partial Y[c_{\text{out}}, h, w]}{\partial X[c_{\text{in}}, h_x, w_x]}
$$

注意：

$h$、$w$ 表示输出特征图的行、列，也可以视为滑动卷积窗口在输入元素内部的偏移量。
$h_x$、$w_x$ 表示输入元素内的实际坐标。
$k_H$、$k_W$ 表示卷积核的宽、高。

从前向公式可知，只有当满足以下条件时，偏导数非零：

$$
\frac{\partial Y[c_{\text{out}}, h, w]}{\partial X[c_{\text{in}}, h_x, w_x]} =
\begin{cases}
W[c_{\text{out}}, c_{\text{in}}, h_x-h, w_x-w] & \text{if } 0 \leq h_x-h < k_H \text{ and } 0 \leq w_x-w < k_W \\
0 & \text{otherwise}
\end{cases}
$$

令 $i = h_x - h$, $j = w_x - w$，则：
$$
\frac{\partial L}{\partial X[c_{\text{in}}, h_x, w_x]} = \sum_{c_{\text{out}}=0}^{C_{\text{out}}-1} \sum_{i=0}^{k_H-1} \sum_{j=0}^{k_W-1} \frac{\partial L}{\partial Y[c_{\text{out}}, h_x-i, w_x-j]} \cdot W[c_{\text{out}}, c_{\text{in}}, i, j]
$$

注意：$i$、$j$ 可以看作是滑动卷积窗口内部元素距离窗口左上角的偏移，因此它们的取值范围是 $[0, K]$。

4.2 向量化形式（全卷积运算）

这等价于一个全卷积（full convolution）运算：
$$
\frac{\partial L}{\partial X[c_{\text{in}}]} = \sum_{c_{\text{out}}=0}^{C_{\text{out}}-1} \text{full_conv}\left( \frac{\partial L}{\partial Y[c_{\text{out}}]}, \text{rot180}(W[c_{\text{out}}, c_{\text{in}}]) \right)
$$

其中 $\text{rot180}(\cdot)$ 表示将矩阵旋转180度（即上下翻转+左右翻转），$\text{full_conv}$ 表示全卷积。

等价形式（使用互相关和填充）：
$$
\boxed{\frac{\partial L}{\partial X} = \text{pad}\left(\frac{\partial L}{\partial Y}\right) \star \text{rot180}(W)}
$$

或者使用转置卷积表示：
$$
\boxed{\frac{\partial L}{\partial X} = \text{transposed_conv}\left(\frac{\partial L}{\partial Y}, W\right)}
$$

维度变化：

$\frac{\partial L}{\partial Y}$: $(C_{\text{out}}, H_{\text{out}}, W_{\text{out}})$
$W$: $(C_{\text{out}}, C_{\text{in}}, k_H, k_W)$
$\frac{\partial L}{\partial X}$: $(C_{\text{in}}, H_{\text{in}}, W_{\text{in}})$

对偏置 $b$ 求导

偏置项的计算最简单。由于一个卷积核通常共享一个偏置，因此偏置的梯度就是对应输出梯度图（Feature Map）中所有元素的总和。

如果前向传播包含偏置：$Y = X \star W + b$，其中 $b \in \mathbb{R}^{C_{\text{out}}}$，则：

$$
\frac{\partial L}{\partial b[c_{\text{out}}]} = \sum_{m=0}^{H_{\text{out}}-1} \sum_{n=0}^{W_{\text{out}}-1} \frac{\partial L}{\partial Y[c_{\text{out}}, m, n]} \cdot \frac{\partial Y[c_{\text{out}}, m, n]}{\partial b[c_{\text{out}}]}
$$

由于 $\frac{\partial Y[c_{\text{out}}, m, n]}{\partial b[c_{\text{out}}]} = 1$：

$$
\boxed{\frac{\partial L}{\partial b[c_{\text{out}}]} = \sum_{m=0}^{H_{\text{out}}-1} \sum_{n=0}^{W_{\text{out}}-1} \frac{\partial L}{\partial Y[c_{\text{out}}, m, n]}}
$$

向量化形式：

$$
\boxed{\frac{\partial L}{\partial b} = \sum_{m,n} \frac{\partial L}{\partial Y[:, m, n]}}
$$

K3s - 轻量级 Kubernetes

骑驴的柒零 — Tue, 04 Nov 2025 13:16:00 GMT

@@ Tags: Kubernetes;K3s
@@ Date: 2025-11-04

K3s 快速开始

K3s 是轻量级的 Kubernetes。K3s 易于安装，仅需要 Kubernetes 内存的一半，所有组件都在一个小于 100 MB 的二进制文件中。

K3s 是一个完全兼容的 Kubernetes 发行版，具有以下增强功能：

打包为单个二进制文件。
使用基于 sqlite3 作为默认存储机制的轻量级存储后端。同时支持使用 etcd3、MySQL 和 Postgres。
封装在简单的启动程序中，可以处理很多复杂的 TLS 和选项。
默认情况下是安全的，对轻量级环境有合理的默认值。
添加了简单但强大的 batteries-included 功能
所有 Kubernetes control plane 组件的操作都封装在单个二进制文件和进程中。因此，K3s 支持自动化和管理复杂的集群操作（例如证书分发等）。
最大程度减轻了外部依赖性，K3s 仅需要现代内核和 cgroup 挂载。K3s 打包了所需的依赖

安装

建议安装需求

仅 Linux
CPU 2 cores(最小 1)
RAM 1 GB(最小 512MB)

安装 Server 节点

curl -sfL https://get.k3s.io | sh -
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

# 查看 node token
sudo cat /var/lib/rancher/k3s/server/node-token

K3s 服务将被配置为在节点重启后或进程崩溃或被杀死时自动重启。
将安装其他实用程序，包括 kubectl、crictl、ctr、k3s-killall.sh 和 k3s-uninstall.sh。
kubeconfig 文件将写入到 /etc/rancher/k3s/k3s.yaml，由 K3s 安装的 kubectl 将自动使用该文件。

安装 Agent 节点并将它们添加到集群

curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -

K3S_URL 参数会导致安装程序将 K3s 配置为 Agent 而不是 Server。K3s Agent 将注册到在 URL 上监听的 K3s Server。K3S_TOKEN 使用的值存储在 Server 节点上的 /var/lib/rancher/k3s/server/node-token 中。

备注

每台主机必须具有唯一的主机名。如果你的计算机没有唯一的主机名，请传递 K3S_NODE_NAME 环境变量，并为每个节点提供一个有效且唯一的主机名。

# 查看服务的日志
sudo journalctl -u k3s -n 100 --no-pager
sudo journalctl -u k3s-agent -n 100 --no-pager


# 拉取镜像
sudo k3s ctr image pull docker.io/rancher/mirrored-pause:3.6

管理集群

# Server 节点执行
# 拷贝 k3s.yaml 到用户目录, 并修改权限
sudo cp /etc/rancher/k3s/k3s.yaml ~/
sudo chown $USER:$USER ~/k3s.yaml

# 远程管理机器执行
# 将 kk3s.yaml 拷贝到本地 ~/.kube/config
mkidr ~\.kube
scp user@server_ip:~/k3s.yaml ~\.kube\config
# 修改 config 文件的server字段到节点地址, 如下所示：
nano ~\.kube\config

# kubeconfig 配置文件
# 来自: /etc/rancher/k3s/k3s.yaml
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: # CA 证书（Base64编码
    LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJkekNDQVIyZ0F3SUJBZ0lCQURBS0JnZ3Foa2pPUFFRREFqQWpNU0V3SHdZRFZRUUREQmhyTTNNdGMyVnk
    ....
    NFUlRJRklDQVRFLS0tLS0K
    server: https://192.168.3.225:6443  # API Server 端点
  name: default                         # 集群名称
contexts:
- context:
    cluster: default
    user: default
  name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default               # 用户名称
  user:
    client-certificate-data:  # 客户端证书数据
    LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJrRENDQVRlZ0F3SUJBZ0lJWjYxeldWcHVhSVl3Q2dZSUtvWkl6ajBFQXdJd0l6RWhNQjhHQTFVRUF3d1k
    ....
    V09UUzQ0WXcySXZERzFVN3BWdW95Zm5rdWd4UFd6V29DS0t3QT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
    client-key-data:          # 客户端密钥数据
    LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSU9UeHVicGVIcXYvd3J1VzNxU25KUVhrbXQwK3JGR1F3T3ZKMm1wRFZRR3FvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFSWFLakNNNzFOK3UyNDRKcGZYSGY4Wm9Bekw4Q1RwaVV0Z1QxUk5hMmpxRzk1MTdSTDg2ZwpINjE1T3htc2tWQ3JrRmVzUi9rT0dIQW1zTTZNbXM1ZTNRPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=

server 节点生成　/etc/rancher/k3s/k3s.yaml 的主要目的:

让管理员能够在 Server 节点本机上使用 kubectl 管理整个 K3s 集群

集群管理员身份凭证:　这个 k3s.yaml 包含了最高权限的认证凭证

作为其他管理配置的基准

此时可以使用 kubectl 命令来管理集群。

# 测试集群连接
kubectl cluster-info

# 查看节点
kubectl get nodes

# 查看所有 pods
kubectl get pods -A
kubectl get pods -A -o wide

# 查询所有的 ingress
kubectl get ingress -A

# 查看所有服务的状态
kubectl get svc -A -o wide

# 查看所有 namespace=kube-system 的pods详细信息
kubectl describe pod -n kube-system

# 查看 pods traefik-c98fdf6fb-629q2 的状态 (tail)
kubectl logs traefik-c98fdf6fb-629q2 -n kube-system -f

# 查看所有节点的状态
kubectl top node

# 删除单个失败的 Pod
kubectl delete pod 

# 删除所有失败的 Pod
kubectl delete pods --field-selector=status.phase=Failed

# 删除所有状态不是 Running 的 Pod（谨慎使用）
kubectl delete pods --field-selector=status.phase!=Running

# 查看所有 configmap(配置数据)
kubectl.exe get configmap -A

# 查看所有 configmap 的内容
kubectl.exe get configmap traefik-conf -n kube-system -o yaml

# 通过重启 Pod, 可以清理日志
kubectl rollout restart deployment/traefik -n kube-system

# 删除 Pod 迫使其重建（如果是 Deployment 管理的）
kubectl delete pod traefik-c98fdf6fb-629q2 -n kube-system

# 查看节点, 标签
kubectl get nodes --show-labels

# 设置节点标签
kubectl label nodes  node-type=worker

# 添加标准的 worker 角色
kubectl label node  node-role.kubernetes.io/worker=true

POD 状态

ContainerCreating
容器创建中
Running
正在运行
Completed
已完成
ErrImagePull
镜像拉取失败, 镜像仓库异常
ImagePullBackOff
镜像拉取失败, 可能是镜像不存在, 镜像仓库异常
CrashLoopBackOff
容器启动后崩溃
CreateContainerConfigBackOff
创建容器配置失败, 例如，引用了不存在的 Secret 或 ConfigMap。
Error
容器启动失败
Terminating
终止状态, 可能节点失联

配置

server 配置文件位于 /etc/rancher/k3s/config.yaml, 字段内容参考官方文档;

也支持多个配置文件。

默认情况下，配置文件/etc/rancher/k3s/config.yaml按/etc/rancher/k3s/config.yaml.d/*.yaml字母顺序读取。

服务角色管理

启动 K3s 服务器--cluster-init将运行所有控制平面组件，包括 API 服务器、控制器管理器、调度器和 etcd。可以禁用特定组件，以便将控制平面和 etcd 角色拆分到不同的节点上。

比如创建专用etcd节点:

curl -fL https://get.k3s.io | sh -s - server --cluster-init --disable-apiserver --disable-controller-manager --disable-scheduler

集群数据存储

K3s 支持以下数据存储选项：

嵌入式SQLite
- SQLite 无法在多服务器集群中使用
- 是默认数据存储，当没有其他数据存储配置且磁盘上不存在嵌入式 etcd 数据库文件时，将使用 SQLite。
- 位于: /var/lib/rancher/k3s/server/db/
嵌入式 etcd
有关在多台服务器上使用嵌入式 etcd 的更多信息，请参阅高可用性嵌入式 etcd文档。如果 K3s 配置为初始化新的 etcd 集群、加入现有 etcd 集群，或者在启动期间磁盘上存在 etcd 数据库文件，则会自动选择嵌入式 etcd。

备份恢复

除了备份数据存储本身之外，您还必须备份服务器令牌文件/var/lib/rancher/k3s/server/token。如果在恢复时未使用相同的令牌值，则快照将无法使用，因为该令牌用于加密数据存储中的机密数据。

手动导入镜像

镜像可以被手动导入, 通过运行 ctr -n k8s.io image pull 命令来拉取镜像(嵌入的注册表)，或者通过使用 ctr -n k8s.io import 或 ctr -n k8s.io load 命令加载镜像归档文件。注意，k8s.io命名空间必须指定，以便在ctr中管理镜像时，kubelet可以识别这些镜像。

集群架构

K3s Architecture

K3s 集群架构大概分为两种:

单服务器架构，内置数据库
高可用性, 多服务器架构, 嵌入式 etcd 数据存储, 节点通常建议使用奇数个（如3个、5个），这是由底层etcd的Raft共识算法决定的，可以有效避免“脑裂”问题。

参考

嵌入式注册表镜像

K3s 内置了Spegel，这是一个无状态的分布式 OCI 镜像仓库，允许 Kubernetes 集群中的节点之间进行容器镜像的对等共享。该分布式镜像仓库默认处于禁用状态。

启动时，K3s 会检查该文件是否/etc/rancher/k3s/registries.yaml存在。如果存在，则会在生成 containerd 配置时使用此文件中的注册表配置。

如果您想使用私有注册表作为公共注册表（例如 docker.io）的镜像，则需要registries.yaml在每个要使用该镜像的节点上进行配置。
如果您的私有镜像仓库需要身份验证、使用自定义 TLS 证书或不使用 TLS，则需要 registries.yaml 在每个拉取镜像的节点上进行配置。

registries.yaml 文件的格式如下：

mirrors:
  :
    endpoint:
      - https:///v2
configs:
  :
    auth:
      username: 
      password: 
      token: 
    tls:
      ca_file: 
      cert_file: 
      key_file: 
      insecure_skip_verify:

示例(国内镜像)：

mirrors:
  docker.io:
    endpoint:
      - "https://docker.1ms.run/"
      - "https://docker.xuanyuan.me/"

mirrors:
  "docker.io":
    endpoint:
      - "https://registry-1.docker.io"

重启后应用, 然后可以查看日志检查是否成功应用

sudo systemctl restart k3s
sudo systemctl restart k3s-agent
sudo systemctl status k3s-agent

与 containerd 配置

k3s 默认使用containerd，需要修改containerd的配置文件，才能让Pod的镜像使用镜像加速器。

K3s会自动生成containerd的配置文件/var/lib/rancher/k3s/agent/etc/containerd/config.toml,不要直接修改这个文件，k3s重启后修改会丢失。

$ sudo cat /var/lib/rancher/k3s/agent/etc/containerd/config.toml
# File generated by k3s. DO NOT EDIT. Use config.toml.tmpl instead.
version = 3
root = "/var/lib/rancher/k3s/agent/containerd"
state = "/run/k3s/containerd"
# ...
[plugins.'io.containerd.cri.v1.images'.registry]
  config_path = "/var/lib/rancher/k3s/agent/etc/containerd/certs.d"

$ sudo cat /var/lib/rancher/k3s/agent/etc/containerd/certs.d/docker.io/hosts.toml
# File generated by k3s. DO NOT EDIT.
server = "https://registry-1.docker.io/v2"
capabilities = ["pull", "resolve", "push"]

[host]

[host."https://docker.1ms.run/v2"]
  capabilities = ["pull", "resolve"]

[host."https://docker.xuanyuan.me/v2"]
  capabilities = ["pull", "resolve"]

OCI 镜像仓库

OCI 镜像仓库是一个用于存储和分发符合 OCI（开放容器倡议）规范的容器镜像及其他制品的系统。其核心目标是实现标准化，确保镜像在不同的容器运行时（如 Docker、Podman、containerd、CRI-O）和客户端（如 Helm、Nerdctl、oras）之间能够自由分发和运行，避免兼容性问题。

etcd

etcd是一个强一致性的分布式键值存储系统，它为分布式系统或集群中需要访问的数据提供了一种可靠的存储方式。它能够优雅地处理网络分区期间的领导者选举，并且即使在领导者节点上发生故障，也能容忍机器故障。

脑裂问题

在分布式系统中，脑裂指的是：原本应该协同工作的一个集群，由于网络故障被分割成两个或多个无法通信的子集群，每个子集群都认为自己是“唯一存活”的部分，并继续对外提供服务，从而导致数据不一致和系统混乱。

crictl

crictl 是 Kubernetes 节点上的容器运行时命令行工具，主要用于与 CRI（Container Runtime Interface）兼容的容器运行时进行交互。

命令行语法与docker 命令行语法相似，但有些命令可能不同。

# 查看 Pod 列表
sudo crictl pods

# 查看容器列表
sudo crictl ps

# 查看镜像列表
sudo crictl images

# 查看容器状态
sudo crictl inspect 

# 查看 Pod 状态
sudo crictl inspectp

ctr

ctr 是 containerd 的命令行工具，用于与 containerd 进行交互。

# 查看镜像列表
sudo ctr images list

# 拉取镜像
sudo ctr images pull docker.io/library/nginx:latest

# 删除镜像
sudo ctr images rm docker.io/library/nginx:latest

# 查看容器列表
sudo ctr containers list

# 查看任务列表（运行的容器）
sudo ctr tasks list

# 在容器中执行命令
sudo ctr tasks exec --exec-id $RANDOM -t  /bin/sh

# 查看命名空间
sudo ctr namespaces list

Kubernetes 简述

骑驴的柒零 — Mon, 03 Nov 2025 16:28:00 GMT

@@ Tags: Kubernetes;k8s
@@ Date: 2025-11-04 1428
@@ Note:

Kubernetes（常简称为 K8s）是一个开源的容器编排平台，用于自动化部署、扩展和管理容器化应用程序。

概念

Kubernetes 要解决的问题

在容器技术（如 Docker）普及之前，应用的部署和运维面临诸多挑战：

环境不一致：开发、测试、生产环境差异导致“在我这儿是好的”问题。
部署繁琐：手动部署应用，流程复杂且容易出错。
资源利用率低：每个物理机或虚拟机通常只运行一个应用，资源浪费严重。
扩缩容困难：流量高峰时，手动增加服务器实例速度慢，成本高。
故障恢复慢：应用或机器宕机后，需要人工介入恢复，停机时间长。

容器技术（如 Docker）解决了第一个问题，它通过镜像保证了环境的一致性。但后四个问题依然存在：

你有成百上千个容器，如何调度它们到合适的机器上？
如何保证容器数量始终满足用户需求？
容器之间如何发现和通信？
如何平滑地更新应用而不中断服务？

Kubernetes 就是为了解决这些容器编排和管理问题而生的。

Kubernetes 的核心架构

Kubernetes 采用经典的主从架构，分为控制平面 和工作节点。

1. 控制平面

控制平面是 Kubernetes 的“大脑”，负责管理整个集群的所有决策。它包含以下几个核心组件：

API Server
- 整个系统的唯一入口。所有用户、客户端和其他组件的请求都必须通过 API Server。
- 它提供了 RESTful API，是前端界面（如 kubectl）与集群交互的桥梁。
etcd
- 一个高可用的键值对数据库。
- Kubernetes 所有集群数据（如节点信息、Pod 状态、配置信息等）都持久化存储在 etcd 中。
- 它是 Kubernetes 的“唯一信源”。
Scheduler
调度器。它负责监视新创建的、还未被调度到节点上的 Pod，并根据资源需求、策略等因素，选择一个最合适的 Node 来运行它。
Controller Manager
控制器管理器。它运行着各种控制器，这些控制器就像是集群的“自动修复系统”，不断地观察集群的状态，确保其与期望的状态一致。例如
- 节点控制器：负责监测节点故障。
- 副本控制器：确保 Pod 的副本数量始终符合用户定义的数量。

2. 工作节点

工作节点是真正运行容器化应用的地方。每个节点上运行着：

Kubelet
节点上的“代理”，它负责与控制平面通信，管理本节点上 Pod 的生命周期，例如创建、启动、停止容器，并定期向 API Server 报告节点和 Pod 的状态。
Kube Proxy
网络代理，它通过在节点上维护网络规则，实现了 Kubernetes Service 的概念，负责负载均衡和将流量转发到正确的 Pod。
容器运行时
负责运行容器的软件，比如 Docker、containerd 或 CRI-O。Kubelet 通过容器运行时接口与它们交互来启动和停止容器。

核心概念与对象

要理解 Kubernetes 如何工作，必须先掌握以下几个核心对象（在 K8s 中，你通过创建这些对象来定义你的应用）：

Pod:
- Kubernetes 中最小的可部署和管理单元。
- 一个 Pod 包含一个或多个容器（通常是紧密相关的容器，例如应用容器和日志收集 sidecar 容器）。
- 这些容器共享网络命名空间、存储卷和其他资源。
- Pod 是短暂的，会被频繁地创建和销毁。
Deployment：
- 用于定义 Pod 的期望状态（例如，需要运行 3 个副本的 Nginx Pod）。
- 它提供了声明式的更新机制。当你更新 Pod 模板时（例如，使用新的镜像版本），Deployment 会以可控的方式（滚动更新）创建新的 Pod，并逐步替换旧的 Pod，实现零停机部署。
- 它是管理无状态应用的首选对象。
Service：
- 因为 Pod 是短暂的，它们的 IP 地址会变化，所以不能直接依赖 Pod IP 来访问服务。
- Service 提供了一个稳定的网络端点（一个固定的 IP 地址和 DNS 名称），为一组功能相同的 Pod（通常由 Deployment 管理）提供负载均衡。
- 无论后端的 Pod 如何创建、销毁或迁移，客户端都可以通过 Service 的固定地址访问到它们。
Namespace：
- 在物理集群内部创建的虚拟集群，用于实现资源隔离和多租户管理。
- 可以将资源（如 Pod、Service）划分到不同的命名空间中，方便管理和权限控制。default、kube-system 是内置的命名空间。
Volume：
- Pod 中的容器是短暂的，其文件系统也是临时的。当容器重启时，数据会丢失。
- Volume 提供了持久化存储的能力，允许容器中的数据在重启后依然存在。Kubernetes 支持多种存储系统（如 NFS、云提供商盘等）。
ConfigMap & Secret：
- ConfigMap 用于将非机密的配置数据（如配置文件、环境变量）与容器镜像解耦。
- Secret 用于存储敏感信息（如密码、OAuth 令牌、ssh 密钥），并以更安全的方式传递给 Pod。

使用 .yaml 格式的文件表示 Kubernetes 对象

Kubernetes 对象

Kubernetes 对象是持久化的实体。 Kubernetes 使用这些实体去表示整个集群的状态。具体而言，它们描述了如下信息：

哪些容器化应用正在运行（以及在哪些节点上运行）
可以被应用使用的资源
关于应用运行时行为的策略，比如重启策略、升级策略以及容错策略

几乎每个 Kubernetes 对象包含两个嵌套的对象字段，它们负责管理对象的配置：

对象 spec（规约）
- 在创建对象时设置的内容，描述你希望对象所具有的特征：期望状态（Desired State）。
对象 status（状态）
- 描述了对象的当前状态（Current State），它是由 Kubernetes 系统和组件设置并更新的。

描述 Kubernetes 对象

通常会通过清单（Manifest）文件来描述 Kubernetes 对象, 比如对象的基本信息、spec。然后使用 kubectl 创建对象。

该清单文件，有一些必须的字段：

apiVersion - 创建该对象所使用的 Kubernetes API 的版本
kind - 想要创建的对象的类别
metadata - 帮助唯一标识对象的一些数据，包括一个 name 字符串、UID 和可选的 namespace
spec - 你所期望的该对象的状态

例如创建一个 Pod 的清单文件：

# pods/simple-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

可以运行这个命令创建: kubectl apply -f https://k8s.io/examples/pods/simple-pod.yaml

再比如下面的清单文件(一个包含 Redis 和多个 ComfyUI Worker 的示例应用):

# comfyui-with-redis.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: comfyui-worker
  labels:
    app: comfyui-worker
spec:
  replicas: 3  # 启动3个Worker副本
  selector:
    matchLabels:
      app: comfyui-worker
  template:    # 定义Pod模板
    metadata:
      labels:
        app: comfyui-worker
    spec:
      containers:
      - name: worker
        image: your-comfyui-image:latest  # 请替换为你的镜像
        env:
        - name: REDIS_URL
          value: "redis://redis-service:6379"
        - name: QUEUE_NAME
          value: "comfyui_tasks"
---
apiVersion: v1
kind: Service
metadata:
  name: comfyui-service
spec:
  selector:
    app: comfyui-worker
  ports:
  - port: 8188
    targetPort: 8188
---
# 部署Redis
apiVersion: apps/v1
kind: Deployment
metadata:
  name: redis
spec:
  replicas: 1
  selector:
    matchLabels:
      app: redis
  template:
    metadata:
      labels:
        app: redis
    spec:
      containers:
      - name: redis
        image: redis:7-alpine
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"
---
apiVersion: v1
kind: Service
metadata:
  name: redis-service
spec:
  selector:
    app: redis
  ports:
  - port: 6379
    targetPort: 6379

配置清单的字段参考:

API 对象

"Kubernetes 对象" 和 "API 对象" 基本上指的是同一组东西，但它们的侧重点略有不同。

Kubernetes 对象 = API 对象

它们是从不同角度对同一实体的称呼：

"Kubernetes 对象"：强调这些对象在 Kubernetes 系统中的作用和功能
"API 对象"：强调这些对象通过 Kubernetes API 进行创建、读取、更新和删除 的访问方式

YAML >> API >> API 对象

flowchart TD
    A[用户编写 YAML 文件] --> B[YAML 文件描述了“期望状态”]
    B --> C{kubectl apply 触发 API 调用}
    
    C -- 用户动作 --> D[POST/PUT 请求
送达 API Server]
    
    subgraph K [Kubernetes 内部]
        D --> E[API Server
处理请求]
        E --> F[Persistent Storage
保存为 API 对象]
        F --> G[控制器
监听并协调现实状态]
    end
    
    G --> H[集群状态
与 YAML 描述一致]

YAML 描述了用户期望的状态, 它内部的字段与 k8s 的 HTTP RESTful API 接口的参数可以看做是一一对应的(在apply 时被转化为JSON HTTP 请求体交给 API Server)。
API Server 接收到用户请求后，形成一个 API 对象(创建或更新)，并保存到持久存储中(etcd)。这个API 对象是资源在 k8s 系统内部持久化后的实例和表现形式，它是集群“期望状态”的真实来源。

参考

Minikube

Minikube

minikube 是本地 Kubernetes，专注于让 Kubernetes 的学习和开发变得容易。

kubectl 命令行工具

kubectl 命令行工具

kubectl (“Kubernetes Control”) 是使用 Kubernetes API 与 Kubernetes 集群的控制平面进行通信的命令行工具。

kubectl 工作原理

kubectl 本身并不直接管理容器，它只是一个客户端工具。它的工作流程是：

读取你的 kubeconfig 配置文件（通常在 ~/.kube/config），获取要访问的集群地址和认证信息。
将你的命令转换为一个 API 请求。
将这个请求发送给 Kubernetes API Server。
API Server 接收到请求后，会根据请求的类型与集群的当前状态进行处理，并更新 etcd 数据库。
其他的 Kubernetes 控制平面组件（如 Scheduler, Controller Manager）会监视这些变化，并采取行动来使集群的实际状态与期望状态一致（例如，在节点上创建 Pod）。

单位

$ kubectl.exe top pod
NAME                        CPU(cores)   MEMORY(bytes)
echo-app-74f6cd4946-6qn8m   1m           19Mi
echo-app-74f6cd4946-h7ndx   1m           19Mi
echo-app-74f6cd4946-hwljm   1m           19Mi
echo-app-74f6cd4946-s5hxr   1m           19Mi

1m = 1 millicore（毫核）也就是 0.001 CPU 核心。

Kubernetes 当中：

1000m = 1 CPU 核（也就是宿主机的一个逻辑核心）
500m = 0.5 核心
1m = 0.001 核心

19Mi = 19 Mebibytes（MiB）= 19 × 1024 × 1024 bytes

在计算机领域，“MB” 其实既可能是 1000×1000，也可能是 1024×1024，但严格定义上它应该是十进制（1000），而二进制的“1024”应该写成 MiB。

1998 年之后，国际标准组织（IEC）正式规定：

名称	缩写	进制	字节
KB	Kilobyte	10 进制	1 KB = 1,000 bytes
MB	Megabyte	10 进制	1 MB = 1,000,000 bytes
KiB	Kibibyte	2 进制	1 KiB = 1,024 bytes
MiB	Mebibyte	2 进制	1 MiB = 1,024×1,024 = 1,048,576 bytes

人工神经网络

骑驴的柒零 — Mon, 14 Apr 2025 16:00:00 GMT

神经网络（Neural Network）是机器学习的一个分支，是一种模仿生物神经元结构的计算模型，也称为人工神经网络 (ANN)。

神经网络旨在从训练数据中学习模式和关系，不断调整和改进，并运用所学做出预测或决策。神经网络能够从复杂数据中提取有意义的信息来解决问题，与传统算法有着明显的不同。

基本结构

神经元: 是神经网络的基本单元，由输入、激活函数和输出组成。
输入层：接收原始数据（如图像像素、文本向量等）。
隐藏层：进行特征提取和转换（可能有多层，深度神经网络即由此得名）。
输出层：生成预测结果（如分类概率、回归值等）。

隐藏层与输出层由一个或多个神经元组成，这些神经元也被称为层的节点。

神经元

其中的符号含义为：

$a1$ ~ $an$ 为神经元的输入，一般是一个向量的各个分量
$w1$ ~ $wn$ 为神经元各个突触的权重值(weight)
$b$ 为神经元的偏置(bias)
$f$ 为激活函数，也称为传递函数，通常为非线性函数，本文中采用 $sigmoid$。
$t$ 为神经元输出

可见，一个神经元的功能是求得输入向量与权向量的内积后，经一个非线性传递函数得到一个标量结果。

前向传播

前向传播是神经网络的核心计算过程，其目的是通过网络的权重和激活函数，将输入信号传递到输出层，得到预测结果。

我们通过最简单的前馈神经网络(Feedforward Network)，来展示前向传播的过程。

神经网络的示意图如下:

图 1-1: Feedforward Network

其中的符号含义为：

$x_i$：输入层第i个节点的输入信号, 即样本的第i个特征值。
$w_j$：各层的节点突触的权重值。
$b_k$：各层的节点的偏置。
$h_i$：隐藏层第i个节点的输出信号。
$y$：输出层的输出信号。

层的特征

输入层的节点数取决于输入数据的维度(即特征)的数量。
输入层数据的形状是(样本数, 特征数)，可以输入一批样本，如果输入单个样本则为(1, 特征数)。
每一层权重的形状是(上一层节点数, 该层节点数)。
每一层偏置的形状是(1, 该层节点数)。
每一层输出的形状是(该层输入数据的行数【即样本数】, 该层节点数)。

数学表达

每个网络层（隐藏层和输出层），都可以视为一个拟合的函数，那么对于多层（深度）神经网络而言，它的数学本质，就等同于一个多层的复合函数：它实现了从向量 $x$ 到向量 $y$ 的映射（如公式所示）

$$
y = h_3(h_2(h_1(x)))
$$

图 1-1 中神经网络的输入为 $x_1, x_2$ 输出的预测值为 $y$, 与实际值 $Y$ 的误差设为 $E$（也就是 损失函数）, 则所有公式表示如下:

$$
\begin{aligned}
h_1 &= sigmoid(x_1 · w_1 + x_2 · w_2 + b_1) \\
h_2 &= sigmoid(x_1 · w_3 + x_2 · w_4 + b_2) \\
y &= sigmoid(h_1 · w_5 + h_2 · w_6 + b_3) \\
E &= \frac{1}{2}(y-Y)^2
\end{aligned}
$$

注意：

损失函数这里采用的是均方误差，而这里的 $\frac{1}{2}$ 是为了方便计算梯度而简化的，因为后面要乘以 $2$。

数据与计算过程

在实际的计算中，数据一般以矩阵的形式出现，这里演示前向传播时, 数据的运算过程以及中间结果的结构。

# 输入层数据, 形状 (3 样本数, 2 特征数)
X=[[x1, x2],  # 样本1 特征向量
   [x1, x2],  # 样本2 ...
   [x1, x2]]  # 样本3

# 隐藏层权重, 形状 (2 上一层节点数, 2 隐藏层节点数)
#   h1, h2
Hw=[[w1, w3],
    [w2, w4]]

# 计算隐藏层的输入数据(输入向量与隐藏层权重的点积)
# Hi=np.dot(X, Hw)
Hi=[[x1·w1 + x2·w2, x1·w3 + x2·w4], # 样本1
    [x1·w1 + x2·w2, x1·w3 + x2·w4], # ...
    [x1·w1 + x2·w2, x1·w3 + x2·w4]]

# 隐藏层偏置, 形状 (1, 2 隐藏层节点数)
Hb=[[b1, b2]]

# 计算隐藏层的输出数据(隐藏层输入数据与隐藏层偏置的加和后再通过激活函数处理)
# Ho=sigmoid(Hi+Hb)
Ho=[[h1=sigmoid(x1·w1 + x2·w2 + b1), h2=sigmoid(x1·w3 + x2·w4 + b2)], # 样本1
    [h1=sigmoid(x1·w1 + x2·w2 + b1), h2=sigmoid(x1·w3 + x2·w4 + b2)], # ...
    [h1=sigmoid(x1·w1 + x2·w2 + b1), h2=sigmoid(x1·w3 + x2·w4 + b2)]]

# 化简后以 h1, h2 代替
Ho=[[h1, h2],
    [h1, h2],
    [h1, h2]]

# 输出层权重, 形状 (2 上一层节点数, 1 输出层节点数)
Ow=[[w5],
    [w6]]

# 输出层偏置, 形状 (1, 1 输出层节点数)
Ob=[[b3]]

# 计算输出层输出值, 也就是神经网络的预测值
# Oo=np.dot(Ho, Ow) + Ob
Oo=[[sigmoid(h1·w5 + h2·w6 + b3)], # 样本1
    [sigmoid(h1·w5 + h2·w6 + b3)], # 样本2
    [sigmoid(h1·w5 + h2·w6 + b3)]] # 样本3
y=Oo

观察以上数据可以得出:

输入数据与中间数据中，每一行都表示一个样本，而列则表示该样本的某一个特征的信息。
网络各个层的权重与偏置数据中，每一列表示的是该层节点的数据, 而行则与上一层的节点一一对应(这特性是由于矩阵乘法的性质决定)。

反向传播

为了训练神经网络, 我们使用反向传播（Backpropagation）算法, 从输出到输入反向计算并更新每一层的权重和偏置, 从而让神经网络的输出值与实际值的误差最小化。

我们首先需要计算误差 $E$ 关于每一个权重与偏置的梯度（偏导数），即该权重或偏置对误差的贡献度。

然后再根据梯度下降法（Batch Gradient Descent）来更新。

1. 计算与更新权重 $w_5$

1.1 $w_5$ 对 $E$ 的贡献, 表示为 $\frac{\partial E}{\partial w_5}$。

1.2 为了方便后面的计算, 我们将公式中的 $sigmoid$ 函数的输入提取出来:

$$
\begin{aligned}
c &= h_1 · w_5 + h_2 · w_6 + b_3 \\
y &= sigmoid(c) \\
E &= \frac{1}{2}(y-Y)^2
\end{aligned}
$$

1.3 根据导数的链式法则, 可以得到:

$$
\frac{\partial E}{\partial w_5} = \frac{\partial E}{\partial y} \cdot \frac{\partial y}{\partial c} \cdot \frac{\partial c}{\partial w_5}
$$

1.4 分别计算各项：

$$
\begin{aligned}
\frac{\partial E}{\partial y} &= y-Y \\
\frac{\partial y}{\partial c} &= \text{sigmoid_derivative}(c) \\
\frac{\partial c}{\partial w_5} &= h_1 \\
\end{aligned}
$$

1.5 得到:

$$
\frac{\partial E}{\partial w_5} = (y-Y) \cdot \text{sigmoid_derivative}(c) \cdot h_1
$$

由于 $h_1$、$c$、$y$ 都在前向传播计算过程中计算过, 因此我们可以直接使用从而计算出结果。

1.6 更新权重:

$$
w_5 = w_5 - η \cdot \frac{\partial E}{\partial w_5}
$$

其中 $η$ 表示学习率，也称为步长或学习速率，这里取 $0.1$。

2. 计算与更新权重 $w_1$

2.1 同理, 误差贡献表示为: $\frac{\partial E}{\partial w_1}$

2.2 提取:

$$
\begin{aligned}
a &= x_1 · w_1 + x_2 · w_2 + b_1 \\
h_1 &= sigmoid(a) \\
c &= h_1 · w_5 + h_2 · w_6 + b_3 \\
y &= sigmoid(c) \\
E &= \frac{1}{2}(y-Y)^2
\end{aligned}
$$

2.3 链式法则代入:

$$
\frac{\partial E}{\partial w_1} = \frac{\partial E}{\partial y} \cdot \frac{\partial y}{\partial c} \cdot \frac{\partial c}{\partial h_1} \cdot \frac{\partial h_1}{\partial a} \cdot \frac{\partial a}{\partial w_1}
$$

2.4 分别计算:

$$
\begin{aligned}
\frac{\partial E}{\partial y} &= y-Y \\
\frac{\partial y}{\partial c} &= \text{sigmoid_derivative}(c) \\
\frac{\partial c}{\partial h_1} &= w_5 \\
\frac{\partial h_1}{\partial a} &= \text{sigmoid_derivative}(a) \\
\frac{\partial a}{\partial w_1} &= x_1 \\
\end{aligned}
$$

2.5 得到:

$$
\frac{\partial E}{\partial w_1} = (y-Y) \cdot \text{sigmoid_derivative}(c) \cdot w_5 \cdot \text{sigmoid_derivative}(a) \cdot x_1
$$

2.6 更新权重:

$$
w_1 = w_1 - η \cdot \frac{\partial E}{\partial w_1}
$$

3. 计算与更新偏置 $b_1$

3.1 同理, 误差贡献表示为: $\frac{\partial E}{\partial b_1}$

3.2 提取:

$$
\begin{aligned}
a &= x_1 · w_1 + x_2 · w_2 + b_1 \\
h_1 &= sigmoid(a) \\
c &= h_1 · w_5 + h_2 · w_6 + b_3 \\
y &= sigmoid(c) \\
E &= \frac{1}{2}(y-Y)^2
\end{aligned}
$$

3.3 链式法则代入:

$$
\frac{\partial E}{\partial b_1} = \frac{\partial E}{\partial y} \cdot \frac{\partial y}{\partial c} \cdot \frac{\partial c}{\partial h_1} \cdot \frac{\partial h_1}{\partial a} \cdot \frac{\partial a}{\partial b_1}
$$

3.4 分别计算:

3.5 得到:

$$
\frac{\partial E}{\partial b_1} = (y-Y) \cdot \text{sigmoid_derivative}(c) \cdot w_5 \cdot \text{sigmoid_derivative}(a)
$$

3.6 更新权重:

$$
b_1 = b_1 - η \cdot \frac{\partial E}{\partial b_1}
$$

Python 实现

为了简化矩阵的计算, 这里我们使用了numpy 模块, numpy 是一个开源的Python库, 广泛用于科学计算。

首先定义一个神经网络类, 主要包含两个函数, 一个是前向传播函数, 一个是反向传播函数。

import numpy as np

# 定义激活函数及其导数
def sigmoid(x):
    return 1 / (1 + np.exp(-x))

def sigmoid_derivative(x):
    return x * (1 - x)

# 定义神经网络类
class FeedNeuralNetwork:
    def __init__(self, input_size, hidden_size, output_size):
        # 初始化权重和偏置
        self.weights1 = np.random.randn(input_size, hidden_size)   # 输入层到隐藏层的权重
        self.bias1 = np.zeros((1, hidden_size))                    # 隐藏层的偏置
        self.weights2 = np.random.randn(hidden_size, output_size)  # 隐藏层到输出层的权重
        self.bias2 = np.zeros((1, output_size))                    # 输出层的偏置

    def forward(self, X):
        # 前向传播
        self.hidden_input = np.dot(X, self.weights1) + self.bias1  # 隐藏层输入
        self.hidden_output = sigmoid(self.hidden_input)            # 隐藏层输出
        self.final_input = np.dot(self.hidden_output, self.weights2) + self.bias2  # 输出层输入
        self.final_output = sigmoid(self.final_input)              # 输出层输出
        return self.final_output

    def backward(self, X, Y, learning_rate):
        # 反向传播
        m = X.shape[0]  # 样本数量

        # 输出层误差
        output_error = self.final_output - Y  # 误差函数: 求的是每个样本的误差 #(∂E/∂y)
        output_delta = output_error * sigmoid_derivative(self.final_output) #(∂E/∂y * ∂y/∂c)

        # 隐藏层误差
        hidden_error = np.dot(output_delta, self.weights2.T)                 #(∂E/∂y * ∂y/∂c * ∂c/∂h_1)
        hidden_delta = hidden_error * sigmoid_derivative(self.hidden_output) #(∂E/∂y * ∂y/∂c * ∂c/∂h_1 * ∂h_1/∂a)

        # 更新权重和偏置 
        # self.hidden_output.T 表示隐藏层输出, 也就是: h_1, h_2, 又分别等于 ∂c/∂w_5, ∂c/∂w_6 (见反向传播公式)
        # 因此这里相当于:
        #  - ∂E/∂w_5 = ∂E/∂y * ∂y/∂c * ∂c/∂w_5
        #  - ∂E/∂w_6 = ∂E/∂y * ∂y/∂c * ∂c/∂w_6
        # 关于转置的原因:
        #  - hidden_output 的形状为 (样本数, 2)
        #    - 第一列表示 h_1
        #    - 第二列表示 h_2
        #  - output_delta  的形状为 (样本数, 1)
        #  - 转置一方面, 可以使两个矩阵符合矩阵乘法的要求, 另一方面是, 可以同时更新 weights2 中的权重 (w_5, w_6)
        # 关于最后除以样本数(/m)的原因:
        #  - 执行矩阵乘法后, 结果矩阵的形状为 (2, 1), 也就是说这批样本的误差之和, 因此需要除以样本数才能得到权重的更新量
        # 
        self.weights2 -= learning_rate * np.dot(self.hidden_output.T, output_delta) / m
        self.bias2 -= learning_rate * np.sum(output_delta, axis=0, keepdims=True) / m

        self.weights1 -= learning_rate * np.dot(X.T, hidden_delta) / m
        self.bias1 -= learning_rate * np.sum(hidden_delta, axis=0, keepdims=True) / m

    def train(self, X, Y, epochs, learning_rate, verbose=False):
        losses = []
        for epoch in range(epochs):
            output = self.forward(X)
            self.backward(X, Y, learning_rate)

            # 打印损失
            if epoch % 100 == 0:
                loss = np.mean(np.square(Y - output))
                if verbose and epoch % 1000 == 0:
                    print(f"Epoch {epoch}, Loss: {loss}")
                losses.append(loss)

        return losses

随机生成一组二分标签，作为训练数据，来训练并测试:

# 生成一些简单的训练数据, 100个样本，每个样本有2个特征
X = np.random.randn(100, 2)
Y = (X[:, 0] + X[:, 1] > 0).astype(int).reshape(-1, 1)
T = np.array([[0.5, 0.5], [-0.5, -0.5], [0.1, -0.3], [-0.2, 0.4]])

# 定义包含2个节点的隐藏层的神经网络
nn = FeedNeuralNetwork(input_size = 2, hidden_size = 2, output_size = 1)

# 训练神经网络
nn.train(X, Y, epochs=10000, learning_rate=0.1, verbose=True)

# 测试神经网络
predictions = nn.forward(T)
print("Predictions for test data:\n", predictions)

Epoch 0, Loss: 0.2832618264020293
Epoch 1000, Loss: 0.19258215420098243
Epoch 2000, Loss: 0.0962378267167891
Epoch 3000, Loss: 0.061623524890982315
Epoch 4000, Loss: 0.04722564099421363
Epoch 5000, Loss: 0.03931114517521166
Epoch 6000, Loss: 0.034210231243449074
Epoch 7000, Loss: 0.03059331500272531
Epoch 8000, Loss: 0.027863796066633327
Epoch 9000, Loss: 0.025712263913194387
Predictions for test data:
 [[0.97895248]
 [0.03954089]
 [0.22193466]
 [0.76031685]]

测试不同隐藏层节点数量之间的差异，主要从训练损失曲线和预测结果两个方面进行比较。

import matplotlib.pyplot as plt

# 生成一些简单的训练数据, 100个样本，每个样本有2个特征
np.random.seed(42) 
X = np.random.randn(100, 2)
Y = (X[:, 0] + X[:, 1] > 0).astype(int).reshape(-1, 1)
T = np.concatenate((np.array([[0.5, 0.5], [-0.5, -0.5]]), np.random.randn(28, 2)), axis=0)

# 训练数据排序, 避免画图时画错序
T = T[np.argsort(T.sum(axis=1))]

# colors = ["blue", "green", "orange", "red", "purple", "brown", "pink", "gray"]
colors = ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf']
epochs = 10000
sequence = [2, 4, 8, 16, 32]

plt.figure(figsize=(12, 5))
plt.subplot(1, 2, 1) 

predictions = []
for i, size in enumerate(sequence):
    nn = FeedNeuralNetwork(2, size, 1)
    losses = nn.train(X, Y, epochs, learning_rate=0.1)
    x_axis = np.arange(0, epochs, 100)
    plt.plot(x_axis, losses, label=f'Hidden size = {size}', color=colors[i])
    predictions.append(nn.forward(T).flatten())


# 左侧：训练损失曲线
plt.title('Different Hidden Layer Sizes')
plt.xlabel('Epoch')
plt.ylabel('Loss (MSE)')
plt.legend()
plt.grid(True)

# # 右侧：预测结果对比
plt.subplot(1, 2, 2)

x_values = T.sum(axis=1)
for i, t in enumerate(predictions):
    plt.scatter(x_values, t, c=colors[i], marker='o', label=f'Hidden size = {sequence[i]}')
    plt.plot(x_values, t, colors[i])

plt.title('Different Hidden Layer Test')
plt.xlabel('Sample-feature (X[i,0] + X[i,1])')
plt.ylabel('Predicted Values')
plt.legend()
plt.grid(True)
plt.tight_layout()
plt.show()

参考

导数

骑驴的柒零 — Tue, 25 Feb 2025 13:59:00 GMT

@@ Tags: 数学;导数
@@ Date: 2025-02-25

导数（Derivative）是微积分学中的一个概念，函数在某一点的导数是指这个函数在这一点附近的变化率（即函数在这一点的切线斜率），导数的本质是通过极限的概念对函数进行局部的线性逼近。

函数 $f$ 对变量 $x$ 的导数表示 $f$ 随 $x$ 的变化率。换句话说，导数描述了函数 $f$ 在点 $x$ 处的瞬时变化率。形式上，导数记作 $\frac{df}{dx}$，表示当 $x$ 变化一个微小量时， $f$ 变化的量。

定义

当函数 $f(x)$ 的自变量 $x$ 在点 $x_0$ 上产生一个增量 $h$ 时，函数输出值的增量与自变量增量 $h$ 的比值在 $h$ 趋于 $0$ 时的极限如果存在，即为 $f(x)$ 在 $x_0$ 处的导数，记作 $f'(x_0)$。

设函数 $f(x)$ 在点 $x_0$ 的某邻域有定义，若极限

$$
f'(x_0) = \lim_{h \to 0} \frac{f(x_0 + h) - f(x_0)}{h}
$$

存在，则称 $f(x)$ 在 $x_0$ 处可导，$f'(x_0)$ 即为 $f(x)$ 在 $x_0$ 点的导数。

导数 $f'(x_0)$ 表示函数 $f(x)$ 在 $x_0$ 处的切线斜率，这也是导数的几何意义。

笔记

在 $x_0$ 处可理解为当 $x=x_0$ 的时候。

邻域是集合中的概念，表示点 $x_0$ 附近的一段区域（不包含点 $x_0$）。

$x$ 变化时函数 $1+𝑥sin(𝑥^2)$（蓝色曲线）的切线变化。函数的导数值就是切线的斜率，绿色代表其值为正，红色代表其值为负，黑色代表值为零。

记法 & 公式

导数的记法有多种形式，具体取决于上下文和使用习惯。

1. 莱布尼茨记法（Leibniz Notation）

这是最常见的导数记法，用 $\frac{dy}{dx}$ 表示 $y$ 对 $x$ 的导数。

公式：
$$
\frac{dy}{dx} = \lim_{\Delta x \to 0} \frac{\Delta y}{\Delta x}
$$

或

$$
\frac{d}{dx} f(x)
$$

其中：
- $\Delta y = f(x + \Delta x) - f(x)$ 是函数值的变化量。
- $\Delta x$ 是自变量的变化量。
示例：
如果 $y = x^2$，则：
$$
\frac{dy}{dx} = 2x
$$

2. 拉格朗日记法（Lagrange Notation）

用 $f'(x)$ 表示函数 $f(x)$ 的导数。

公式：
$$
f'(x) = \lim_{h \to 0} \frac{f(x + h) - f(x)}{h}
$$
示例：
如果 $f(x) = \sin(x)$，则：
$$
f'(x) = \cos(x)
$$

3. 牛顿记法（Newton Notation）

用 $\dot{y}$ 表示 $y$ 对时间 $t$ 的导数，常见于物理学中。

公式：
$$
\dot{y} = \frac{dy}{dt}
$$
示例：
如果 $y = t^3$，则：
$$
\dot{y} = 3t^2
$$

导数的几何意义

导数的几何意义是函数图像在某一点处的切线斜率。

如果导数为正，函数在该点处是递增的。
如果导数为负，函数在该点处是递减的。
如果导数为零，函数在该点处可能是极值点（最大值或最小值）。

导数的物理意义

在物理学中，导数可以表示速度、加速度等变化率。

例如，位移对时间的导数是速度，速度对时间的导数是加速度。

单侧导数

左导数 $f'_-(x)$
右导数 $f'_+(x)$

TODO 图

$f(x)$ 在 $x_0$ 处可导 $<=>$ 左右导数都存在且相等。

求导

求导是计算函数导数的过程，即找出函数在各点处的切线斜率。

求导方法

基本求导公式：
- $\frac{d}{dx} (c) = 0$ （$c$ 为常数）
- $\frac{d}{dx} (x) = 1$
- $\frac{d}{dx} (x^n) = n x^{n-1}$ （$n$ 为实数）
- $\frac{d}{dx} (e^x) = e^x$
- $\frac{d}{dx} (e^{-x}) = -e^{-x}$
- $\frac{d}{dx} (a^x) = a^x \times ln(a)$
- $\frac{d}{dx} (\ln x) = \frac{1}{x}$
求导法则：
- 加法法则
  $$\frac{d}{dx} [f(x) + g(x)] = f'(x) + g'(x)$$
- 乘法法则
  $$\frac{d}{dx} [f(x) \cdot g(x)] = f'(x) g(x) + f(x) g'(x)$$
- 链式法则
  $$\frac{d}{dx} [f(g(x))] = f'(g(x)) \cdot g'(x)$$

例1: 求函数 $f(x)=x^2$ 的导数

使用幂函数的导数公式

幂函数的导数公式为：

$$
\frac{d}{dx}(x^n) = n \cdot x^{n-1}
$$

对于 $f(x) = x^2$，幂指数 $n = 2$，因此：

$$
\frac{d}{dx}(x^2) = 2 \cdot x^{2-1} = 2x
$$

使用公式代入推导

写出导数的定义：
$$
\frac{dy}{dx} = \lim_{h \to 0} \frac{f(x + h) - f(x)}{h}
$$
代入 $f(x) = x^2$：
$$
\frac{dy}{dx} = \lim_{h \to 0} \frac{(x + h)^2 - x^2}{h}
$$
代入利用完全平方和公式展开：
$$
\frac{dy}{dx} = \lim_{h \to 0} \frac{x^2 + 2xh + h^2 - x^2}{h}
$$
简化分子：
$$
\frac{dy}{dx} = \lim_{h \to 0} \frac{2xh + h^2}{h}
$$
约分 $h$：
$$
\frac{dy}{dx} = \lim_{h \to 0} (2x + h)
$$
取极限 $h \to 0$：
$$
\frac{dy}{dx} = 2x + 0 = 2x
$$

例2: 求函数 $f(x)=\frac{1}{x}$ 的导数

代入函数表达式
$$ f'(x) = \lim_{h \to 0} \frac{\frac{1}{x + h} - \frac{1}{x}}{h} $$
将分子部分通分：
$$ \frac{1}{x + h} - \frac{1}{x} = \frac{x - (x + h)}{x(x + h)} = \frac{-h}{x(x + h)} $$
将通分结果代入导数表达式：
$$ f'(x) = \lim_{h \to 0} \frac{\frac{-h}{x(x + h)}}{h} = \lim_{h \to 0} \frac{-h}{x(x + h)h} $$
约简 $h$：
$$ f'(x) = \lim_{h \to 0} \frac{-1}{x(x + h)} $$
求极限，当 $h \to 0$时，$x + h \to x$，因此：
$$ f'(x) = \frac{-1}{x^2} = -x^{-2} $$

例3: 求函数 $f(x)=e^{-1}$ 的导数

函数 $f(x) = e^{-x}$ 是一个复合函数，其中：

外层函数是指数函数：$g=e^{h}$。
内层函数是线性函数：$h=-x$。

使用链式法则代入：

$$
\begin{aligned}
\frac{d}{dx} \left( g(h(x)) \right) &= g'(h(x)) \cdot h'(x) \\
\frac{d}{dx} e^{-x} &= g'(h(x)) \cdot h'(x)\\
\frac{d}{dx} e^{-x} &= e^{-x} \cdot -1 = -e^{-x} \\
\end{aligned}
$$

外层指数函数的导数：$g'(h) = \frac{d}{dh} e^h = e^h$
内层线性函数的导数：$h'(x) = \frac{d}{dx} (-x) = -1$

例4: 求Sigmoid函数 $f(x) = \frac{1}{1 + e^{-x}}$ 的导数

首先，将 Sigmoid 函数写成指数形式：

$$
f(x) = (1 + e^{-x})^{-1}
$$

使用链式法则：

$$
f'(x) = \frac{d}{dx} \left( (1 + e^{-x})^{-1} \right)
$$

链式法则的公式为：
$$
\frac{d}{dx} \left( g(h(x)) \right) = g'(h(x)) \cdot h'(x)
$$

在这里：

$g(u) = u^{-1}$，其导数为 $g'(u) = -u^{-2}$；
$h(x) = 1 + e^{-x}$，其导数为 $h'(x) = -e^{-x}$。

因此：
$$
f'(x) = g'(h(x)) \cdot h'(x) = -\left(1 + e^{-x}\right)^{-2} \cdot (-e^{-x})
$$

将导数表达式化简：

$$
f'(x) = \frac{e^{-x}}{(1 + e^{-x})^2}
$$

用 Sigmoid 函数表示, 注意到 $f(x) = \frac{1}{1 + e^{-x}}$，因此可以将导数表示为：

$$
f'(x) = f(x) \cdot (1 - f(x))
$$

推导过程：
$$
f'(x) = \frac{e^{-x}}{(1 + e^{-x})^2} = \frac{1}{1 + e^{-x}} \cdot \frac{e^{-x}}{1 + e^{-x}} = f(x) \cdot \left(1 - \frac{1}{1 + e^{-x}}\right) = f(x) \cdot (1 - f(x))
$$

离散数据的导数计算

假设摩托车在行驶过程中记录下的时间与速度的关系:

速度：y: [10, 12, 15, 80, 85, 90]
时间：x: [1 2 3 4 5 6 ]
函数关系：$y = f(x)$

根据连续导数定义公式:

$$
f'(x_0) = \lim_{h \to 0} \frac{f(x_0 + h) - f(x_0)}{h}
$$

对于离散数据来说，不能取 $h \rightarrow 0$，只能取有限小的 $\Delta x$（常取为数据点之间的固定间距 $h$, 在这里也就是 $h=1$）。

代入可得:

$$
f'(x_k) \approx \frac{f(x_k + h) - f(x_k)}{h}
$$

前向差分公式

上面这种公式，也叫前向差分公式

$$
f'(x_k) \approx \frac{f_{k+1} - f_k}{h}
$$

因为 $h=1$, 则简化为:

$$
f'(x_k) \approx f_{k+1} - f_k
$$

即：[2, 3, 65, 5, 5, N/A(没有下一个数据点)]

后向差分公式

$$
f'(x_k) \approx \frac{f_k - f_{k-1}}{h}
$$

或者

$$
f'(x_k) \approx f_k - f_{k-1}
$$

即：[N/A(没有上一个数据点), 2, 3, 65, 5, 5]

中心差分公式

还有更高精度的中间差分公式(取 $x$ 左右两边点的斜率)，具体的推导式需要泰勒级数 (Taylor Series)

$$
f'(x_k) \approx \frac{f_{k+1} - f_{k-1}}{2h}
$$

通常结合其他差分模式一起计算:

[2(左边界，通常用前向差分), 2.5, 34, 35, 5, 5(右边界，通常用后向差分)]

参考

文件名规范引发的 iTunes 备份还原错误及解决方案

骑驴的柒零 — Mon, 24 Feb 2025 14:54:00 GMT

@@ Tags: iTunes;备份;还原;错误修复
@@ Date: 2025-02-24

用户还原之前的iTunes备份时, 出现如下错误:



	DLMessageProcessMessage
	
		ErrorCode
		2
		ErrorDescription
		_restoreRegularFiles:size: rename error: No such file or directory (2) at path "/private/var/mobile/.backup.i/var/mobile/Containers/Data/Application/9B671B4F-ED81-43E1-BD67-258DA97116B9/Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force/01 Champions Of The Force.mp3" (MBErrorDomain/2)
		MessageName
		Response

用户的环境如下:

备份: iPhone 13 Pro Max(iPhone14,3) - iOS 15.4
目标: iPhone 13 Pro Max(iPhone14,3) - iOS 18.3 and 18.3.1
系统: Windows 11 Pro x64, 10.0.26100
iTunes 版本: iTunesMobileDevice.dll(1190.100.1.2)

分析错误原因

经检查 Manifest.db 文件，发现清单数据库中并未存在报错项目的上级目录:

错误项目信息:
- domain: AppDomain-org.videolan.vlc-ios
- relativePath: Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force/01 Champions Of The Force.mp3
- fileId: ddab7b0a154cbc9b934b80331ced23dd820ffd0f
不存在的上级项目:
- domain: AppDomain-org.videolan.vlc-ios
- relativePath: Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force
- fileId: 5da63f6ebaf0b256a7a1a654daaeadec91fdd920
但存在类似的上级项目:
- fileId: b8ae2d19ce590a182d23561dded5dc34f053e42e
- domain: AppDomain-org.videolan.vlc-ios
- relativePath: Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force

fid_ddab7b0a = 'Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force/01 Champions Of The Force.mp3'
fid_b8ae2d19 = 'Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force'

left = fid_ddab7b0a[:len(fid_b8ae2d19) + 1]
right = fid_b8ae2d19
print('Left       : ', left)
print('Right      : ', right)
print('Compare    : ', left == right)
print('LeftEncode : ', left.encode('utf-8'))
print('RightEncode: ', right.encode('utf-8'))

index = left.index('è')
leftChar = left[index:index+2]
rightChar = right[index]
leftBytes = leftChar.encode('utf-16-be')
rightBytes= rightChar.encode('utf-16-be')
print('leftChar   :  {}={: <16}, hex({})'.format(leftChar, str(leftBytes), leftBytes.hex(' ')))
print('rightChar  :  {}={: <16}, hex({})'.format(rightChar, str(rightBytes), rightBytes.hex(' ')))

输出:

Left       :  Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force
Right      :  Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force
Compare    :  False
LeftEncode :  b'Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogye\xcc\x80ampions of the Force'
RightEncode:  b'Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogy\xc3\xa8ampions of the Force'
leftChar   :  è=b'\x00e\x03\x00', hex(00 65 03 00)
rightChar  :  è=b'\x00\xe8'     , hex(00 e8)

关键在于 Trilogye\xcc\x80ampions 与 Trilogy\xc3\xa8ampions, 前者 e\xcc\x80 后者 \xc3\xa8(在UTF-8 编码下)。

这其实是一个Unicode 中的字素分解的现象，前者是该字符在 Unicode Normalization 是采用 NFD 规范下产生的编码 è，后者是在 NFC 规范下产生的编码 è;

NFC（Normalization Form Canonical Composition）又称完全组合

NFC 规范，将字符组合为标准的组合形式。

NFC 规范，也是大多数平台的文件系统采用的归一化规范，如：Windows 和大多数 Linux 发行版。

示例: 신(신)

NFD（Normalization Form Canonical Decomposition）又称完全分解

NFD 规范，它将字符分解为基本字符和组合字符。

NFD 规范，是 macOS、iOS 的 HFS+ 文件系统采用的归一化规范[2] [3]。

示例: 신(신)

可以看到在完全分解下 `e 字符被拆解成了两个字符: e 和 ̀

根据以上信息，可以推论这大概是 iOS 15.4 的一个Bug，在备份时，将两个包含 è 路径采用了两个不同的 Unicode Normalization 规范来编码。从而导致在iOS 18.3.1 还原时，两个字符被解码成两个不同的路径，导致还原失败。

修复问题

在尝试修复问题之前，我们先对清单中的所有数据进行一些分析，判断问题规模，并查找具体原因。

import sqlite3
import hashlib

class ManifestDB:
    def __init__(self,):
        self.file = None
        self.conn = None
        self.cursor = None
        
    def open(self, file):
        self.file = file
        self.conn = sqlite3.connect(file)
        self.cursor = self.conn.cursor()

    def close(self):
        self.conn.close()

    @staticmethod
    def fileId(domain, relativePath):
        return hashlib.sha1(f"{domain}-{relativePath}".encode('utf-8')).hexdigest()
    
    def exists(self, fileID):
        self.cursor.execute("SELECT COUNT(*) FROM Files WHERE fileID = ?", (fileID,))
        return self.cursor.fetchone()[0] > 0

    def files(self):
        self.cursor.execute("SELECT fileID, domain, relativePath, flags, file FROM Files")
        return self.cursor.fetchall()

import unicodedata
import plistlib

def NormalizationForm(string):
    nfc = unicodedata.normalize('NFC', string)
    nfd = unicodedata.normalize('NFD', string)
    if nfc == nfd:
        return 'Plain'
    elif string == nfc:
        return 'NFC'
    elif string == nfd:
        return 'NFD'

    nfkc = unicodedata.normalize('NFKC', string)
    nfkd = unicodedata.normalize('NFKD', string)
    if string == nfkc:
        return 'NFKC'
    elif string == nfkd:
        return 'NFKD'
    else:
        return 'Unknown'

def GetRelativePath(plist):
    root = plist['$top']['root']
    indx = plist['$objects'][root]['RelativePath']
    return plist['$objects'][indx]

def SetRelativePath(plist, relativePath):
    root = plist['$top']['root']
    indx = plist['$objects'][root]['RelativePath']
    plist['$objects'][indx] = relativePath

import os
from termcolor import cprint

print('Checking for potential errors...')

db = ManifestDB()
db.open(r'Manifest_15.4.db')
items = db.files()
items = { f[0] : f for f in items}

print('- Item count:', len(items))

count = {}
for index, key in enumerate(items):
    fileID, domain, relativePath, flags, file = items[key]
    
    form = NormalizationForm(relativePath)
    count[form] = count.get(form, 0) + 1
    
    plistBlob = plistlib.loads(file)
    plistPath = GetRelativePath(plistBlob)
    
    if fileID != db.fileId(domain, relativePath):
        cprint(f'- Detected target item ID mismatch Origin: {fileID}', 'red')
        cprint(f'  * fileID: {fileID}=sha1({ f"{domain}-{relativePath}".encode() })', 'yellow')
        cprint(f'  - domain: {domain}')
        cprint(f'  - relativePath: {relativePath}')
        
    if plistPath != relativePath:
        cprint(f'- Detected target item path mismatch Origin: {fileID}', 'red')
        cprint(f'  - domain: {domain}')
        cprint(f'  - relativePath(UTF-8): {relativePath.encode()}')
        cprint(f'  * plistPath   (UTF-8): {plistPath.encode()}', 'yellow')

    pdir = os.path.dirname(relativePath) 
    if pdir:
        pid = db.fileId(domain, pdir)
        if pid not in items:
            cprint(f'- Detected parent directory of target item does not exist: {fileID}', 'red')
            cprint(f'  - domain: {domain}')
            cprint(f'  - relativePath: {relativePath}')
            cprint(f'  * ParentItem: {pid}=sha1({ f"{domain}-{pdir}".encode() })', 'yellow')
    
    if index % 5000 == 0:
        print(f'- {index:0<5} / {len(items)} ...')

print('Check completed, relativePath normalization form statistics:')
for form in count:
    print(f'- {form: <5}: {count[form]}')

输出:

Checking for potential errors...
- Item count: 100717
- 00000 / 100717 ...
- 50000 / 100717 ...
- 10000 / 100717 ...
- 15000 / 100717 ...
- 20000 / 100717 ...
- 25000 / 100717 ...
- Detected target item ID mismatch Origin: 84f50bb8bc96c5741ab156130ba4de8b4901c1c1
  * fileID: 84f50bb8bc96c5741ab156130ba4de8b4901c1c1=sha1(b'AppDomain-org.videolan.vlc-ios-Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/36 The Hand of Thrawn Duology -\xd3\xb0ecter of the Past')
  - domain: AppDomain-org.videolan.vlc-ios
  - relativePath: Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/36 The Hand of Thrawn Duology -Ӱecter of the Past
- Detected target item ID mismatch Origin: b8ae2d19ce590a182d23561dded5dc34f053e42e
  * fileID: b8ae2d19ce590a182d23561dded5dc34f053e42e=sha1(b'AppDomain-org.videolan.vlc-ios-Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogy\xc3\xa8ampions of the Force')
  - domain: AppDomain-org.videolan.vlc-ios
  - relativePath: Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force
- 30000 / 100717 ...
- 35000 / 100717 ...
- 40000 / 100717 ...
- 45000 / 100717 ...
- 50000 / 100717 ...
- 55000 / 100717 ...
- 60000 / 100717 ...
- 65000 / 100717 ...
- 70000 / 100717 ...
- 75000 / 100717 ...
- 80000 / 100717 ...
- 85000 / 100717 ...
- 90000 / 100717 ...
- 95000 / 100717 ...
- 100000 / 100717 ...
Check completed, relativePath normalization form statistics:
- Plain: 100701
- NFC  : 2
- NFD  : 14

经过以上脚本检查发现，其实上级项目是存在的，因为其中包含非 ASCII 字符，因此字符 è 是以 UTF-8编码来计算的 SHA1 值。但是在这里上级项目的 fileID 与 relativePath 对不上，应该是在备份时计算 fileID 与存储 relativePath 的编码规范发生了变化导致的问题。

可以看到出错的项目的文件路径使用的规范是 NFD （完全分解），而上级项目的 fileID 也是使用的 NFD 计算的，但是 relativePath 却是 NFC （完全组合），所以会导致文件路径不匹配。

那么确定了问题的原因，我们只需要将 fileID 不匹配的 relativePath 转换为 NFD 编码规范即可。

import shutil

shutil.copy2(r'Manifest_15.4.db', r'Manifest.db.fixed')

db = ManifestDB()
db.open(r'Manifest.db.fixed')

for fileID, domain, relativePath, flags, file in db.files():
    if fileID != db.fileId(domain, relativePath):
        cprint(f'- Process: {fileID}', 'yellow')

        relativePathNFD = unicodedata.normalize('NFD', relativePath)
        plistBlob = plistlib.loads(file)
        SetRelativePath(plistBlob, relativePathNFD)
        plistBlobNFD = plistlib.dumps(plistBlob, fmt=plistlib.FMT_BINARY)
        
        if fileID == db.fileId(domain, relativePathNFD):
            cprint(f'  - NFD: {relativePathNFD}', 'green')
            cprint(f'  - FIX: ', 'green')
            cprint(f'    * From(UTF-8): {relativePath.encode()}', 'green')
            cprint(f'    * To  (UTF-8): {relativePathNFD.encode()}', 'green')

            db.cursor.execute("UPDATE Files SET relativePath = ?, file = ? WHERE fileID = ?", (relativePathNFD, plistBlobNFD, fileID))

db.conn.commit()
db.close()
print('Finished!')

输出:

- Process: 84f50bb8bc96c5741ab156130ba4de8b4901c1c1
  - NFD: Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/36 The Hand of Thrawn Duology -Ӱecter of the Past
  - FIX:
    * From(UTF-8): b'Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/36 The Hand of Thrawn Duology -\xd3\xb0ecter of the Past'
    * To  (UTF-8): b'Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/36 The Hand of Thrawn Duology -\xd0\xa3\xcc\x88ecter of the Past'
- Process: b8ae2d19ce590a182d23561dded5dc34f053e42e
  - NFD: Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogyèampions of the Force
  - FIX:
    * From(UTF-8): b'Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogy\xc3\xa8ampions of the Force'
    * To  (UTF-8): b'Documents/Audio books/Starwars/4 New Republic Era (5 to 25 ABY)/22 The Jedi Academy Trilogye\xcc\x80ampions of the Force'
Finished!

将 Manifest.db.fixed 文件提交给用户替换到原备份的 Manifest.db 文件后，成功解决了问题。

复利公式与自然对数 e

骑驴的柒零 — Sat, 22 Feb 2025 13:22:00 GMT

@@ Tags: 复利;自然对数e
@@ Date: 2025-02-22

自然对数 $e$ 与复利公式的关系可以从复利计算中推导出来。以下是详细的阐述：

1. 单利

单利计算公式:

$$
A = P \left(1 + r\right)
$$

其中：

$A$ 是最终金额
$P$ 是本金
$r$ 是利率

也就是说 1000元以年利率 50% 存一年，一年后本金利息则为：$1000 \times (1 + 0.5) = 1500$ 元。

如果我们把年利率拆分成月利率，再把 1000元分两次存，每次存半年：

上半年:

$$
1025 = 1000 \times (1 + \frac{0.5}{2})
$$

下半年:

$$
1562.5 = 1025 \times (1 + \frac{0.5}{2})
$$

同样的年利率在分两次存取后，比存一年多了 62.5 元。

另外可以发现：如果我们拆的次数越多，则最终金额也就越大，而这就是复利。

2. 复利

复利是指在计算利息时，将本金和已产生的利息一起作为下一期的本金。复利公式为：

$$
A = P \left(1 + \frac{r}{n}\right)^{nt}
$$

其中：

$n$ 是计息次数
$t$ 是时间 (年)

3. 连续复利

当计息次数 $n$ 趋近于无穷大时，复利计算变为连续复利。此时，公式变为：

$$
A = P \cdot e^{rt}
$$

其中 $e$ 是自然对数的底，约等于 2.71828。

4. 推导过程

$$
P \left(1 + \frac{r}{n}\right)^{nt} = P \cdot e^{rt}
$$

4.1 推导自然对数 e

设 $P = 1$、$r = 1$、$t = 1$，则复利公式简化为：

$$
A = \left(1 + \frac{1}{n}\right)^n
$$

当 $n$ 趋近于无穷大时，$A$ 的极限即为 $e$：

$$
e = \lim_{n \to \infty} \left(1 + \frac{1}{n}\right)^n
$$

4.2 推导连续复利公式

设 $P = 1$，且当 $n$ 趋近于无穷大时，公式表示如下:

$$
\lim_{n \to \infty} \left(1 + \frac{r}{n}\right)^{nt}
$$

为了简化计算，我们引入一个新的变量 $\frac{1}{m}$ 来替换 $\frac{r}{n}$，并且当 $n \to \infty$ 时，$m \to \infty$，此时 $m$、$n$ 的关系为：

$$
\frac{1}{m} = \frac{r}{n} = \frac{r}{m \cdot r}
$$

因此，代入后复利公式可以改写为：

$$
\lim_{m \to \infty} \left(1 + \frac{1}{m}\right)^{mrt} = \left(\lim_{m \to \infty} \left(1 + \frac{1}{m}\right)^{m}\right)^{rt} = e^{rt}
$$

聚类 k-means

骑驴的柒零 — Fri, 21 Feb 2025 13:47:22 GMT

K-means (K平均聚类) 是一种常用的无监督学习算法，主要用于聚类分析。其目标是将数据集划分为 K 个簇，使得每个数据点归属于最近的簇中心，且簇内数据点尽可能相似，簇间差异尽可能大。

特点：

简单易用，广泛应用于图像分割、市场细分、文档聚类等领域。。
需预先设定 K 值，选择不当可能影响结果。
对初始中心敏感，可能陷入局部最优。
对噪声和异常值敏感。

K-means 算法步骤：

初始化 K 个中心点（ centroids ）。
将每个数据点分配到最近的中心点所属簇中。
更新每个簇的中心点，使其成为其所有数据点的平均值。
重复步骤 2 和步骤 3，直到簇中心不再移动或达到最大迭代次数。

实例

首先，我们生成一些随机数据，然后使用 KMeans 算法对它们进行聚类，并使用 matplotlib 绘制出聚类结果。

import cv2
import numpy as np
import matplotlib.pyplot as plt

# 设置随机数种子
np.random.seed(None)

# 生成 100 个二维数据点，范围在 [0, 50]
data = np.random.randint(0, 50, (100, 2)).astype(np.float32)

# 定义 K 值（簇的数量）
K = 3

# 定义 K-means 的停止条件, 两个标识符 通过 + 来组合, 类似于 |
#  - TERM_CRITERIA_MAX_ITER: 最大迭代次数条件，达到指定次数时停止迭代
#  - TERM_CRITERIA_EPS: 精度条件，簇中心的移动幅度小于阈值（精度）时停止迭代
criteria = (cv2.TERM_CRITERIA_MAX_ITER + cv2.TERM_CRITERIA_EPS, 10, 1.0)

# 运行 K-means 算法
#   - attempts: 重复算法次数, 返回紧凑性最好的一次结果
#   - flags: 初始中心的选择方法, 这里采用随机选择
#   - 返回值: 
#     - compactness: 表示结果的紧凑性, 即所有数据点到其所属簇中心的距离的平方和
#     - labels: 表示每个数据点所属的标签(簇)的索引, 形状为 (N, 1): [ [lebel_id], [lebel_id], ... ]
#     - centers: 表示每个簇的中心
# 参考: https://docs.opencv.org/4.11.0/d5/d38/group__core__cluster.html#ga9a34dc06c6ec9460e90860f15bcd2f88
compactness, labels, centers = cv2.kmeans(data, K, None, criteria, attempts=10, flags=cv2.KMEANS_RANDOM_CENTERS)

# 将数据点按标签分离, 使用 NumPy 的布尔索引操作
cluster1 = data[labels.ravel() == 0]
cluster2 = data[labels.ravel() == 1]
cluster3 = data[labels.ravel() == 2]

# 使用 Matplotlib 可视化结果
# 展示原始数据点
plt.figure(figsize=(10, 5))
plt.subplot(1, 2, 1)  # 1 行 2 列，第 1 个子图
plt.scatter(data[:, 0], data[:, 1], c='blue', label='Data Points') # data[:, 0] 所有点的 X 坐标集, NumPy 多维切片语法
plt.ylabel('Y')
plt.title('Original Data Points')
plt.legend()

# 展示聚类结果
plt.subplot(1, 2, 2)  # 1 行 2 列，第 2 个子图 
plt.scatter(cluster1[:, 0], cluster1[:, 1], c='blue', label='Cluster 1')
plt.scatter(cluster2[:, 0], cluster2[:, 1], c='green', label='Cluster 2')
plt.scatter(cluster3[:, 0], cluster3[:, 1], c='red', label='Cluster 3')
plt.scatter(centers[:, 0], centers[:, 1], s=200, c='black', marker='*', label='Centers')
plt.xlabel('X')
plt.ylabel('Y')
plt.title('K-means Clustering with OpenCV')
plt.legend()
plt.show()

从结果图中可以看到，所有点都都被聚成了 3 个簇，以颜色区分。

K 的取值与聚类效果

K 的取值以及中心的的初始化方式，对聚类效果影响很大。我们可以通过下面的案例观察不同的 K 值与紧凑性（WCSS - Within Cluster Sum of Squares）的关系。

import cv2
import numpy as np
import matplotlib.pyplot as plt

np.random.seed(None)

# 生成 4 个簇的数据
data = np.concatenate([
    np.random.normal(loc=center, scale=2, size=(25, 2))
    for center in [[0, 0], [10, 10], [0, 10], [10, 0]]
]).astype(np.float32)

# 定义 K 值范围
K_values = range(1, 11)
compactness_values = []

# 定义 K-means 的停止条件
criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 10, 1.0)

# 对每个 K 值运行 K-means
for K in K_values:
    # 运行 K-means
    compactness, labels, centers = cv2.kmeans(data, K, None, criteria, 10, cv2.KMEANS_RANDOM_CENTERS)
    compactness_values.append(compactness)  # 记录紧凑性

# 展示原始数据点
plt.figure(figsize=(12, 5))
plt.subplot(1, 2, 1)  # 1 行 2 列，第 1 个子图
plt.scatter(data[:, 0], data[:, 1], c='blue', label='Data Points') # data[:, 0] 所有点的 X 坐标集, NumPy 多维切片语法
plt.xlabel('X')
plt.ylabel('Y')
plt.title('Original Data Points')
plt.legend()

# 绘制 K 值与紧凑性的关系图
plt.subplot(1, 2, 2)
plt.plot(K_values, compactness_values, marker='o', linestyle='-', color='b')
plt.xlabel('K (Number of Clusters)')
plt.ylabel('WCSS (Compactness)')
plt.title('K vs WCSS (OpenCV)')
plt.xticks(K_values)
plt.grid(True)
plt.show()

通过上面的曲线图，我们可以看出当 K 值越大，紧凑性（WCSS）的度量值越低，曲线整体上像是一个胳膊肘的形状。而当 K 值达到某个值时（曲线的肘点），折线的下降趋势开始显著降低，这个位置就是 K 的最佳值，因此这种方法也称为肘点法（Elbow method）。

参考

常见距离算法

骑驴的柒零 — Wed, 19 Feb 2025 16:00:00 GMT

距离算法用于衡量数据点之间的相似性或差异性，根据数据特性的不同，可以采用不同的度量方法。

一般而言，定义一个函数 $\text{dist}(x, y)$，若它是一个“距离度量”(distance measure)，则需要满足以下基本性质：

非负性: $\text{dist}(x_i, x_j) \geq 0$；
同一性: $\text{dist}(x_i, x_j) = 0$ 当且仅当 $x_i = x_j$；
对称性: $\text{dist}(x_i, x_j) = \text{dist}(x_j, x_i)$；
三角不等式: $\text{dist}(x_i, x_j) \leq \text{dist}(x_i, x_k) + \text{dist}(x_k, x_j)$。

常见的有以下几种：

1. 欧氏距离 (Euclidean Distance)

定义: 两点在欧几里得空间中的直线距离。
公式: 对于点 $P = (p_1, p_2, \dots, p_n)$ 和 $Q = (q_1, q_2, \dots, q_n)$，欧氏距离为：
$$
d(P, Q) = \sqrt{\sum_{i=1}^n (p_i - q_i)^2}
$$
应用: 适用于连续数据，如KNN、K-Means等。

2. 曼哈顿距离 (Manhattan Distance)

定义: 两点在标准坐标系上的绝对轴距总和。
公式:
$$
d(P, Q) = \sum_{i=1}^n |p_i - q_i|
$$
应用: 适用于网格状路径，如城市街区距离。

3. 切比雪夫距离 (Chebyshev Distance)

定义: 两点在各坐标轴上的最大差值。
公式:
$$
d(P, Q) = \max_i |p_i - q_i|
$$
应用: 适用于需要衡量最大差异的场景，如棋盘上的移动。

4. 闵可夫斯基距离 (Minkowski Distance)

定义: 欧氏距离和曼哈顿距离的推广，通过参数 $p$ 控制距离类型。
公式:
$$
d(P, Q) = \left( \sum_{i=1}^n |p_i - q_i|^p \right)^{1/p}
$$
应用: 通过调整 $p$ 值适应不同场景。
特点：
- p=1: 闵可夫斯基距离等同于曼哈顿距离。
- p=2: 闵可夫斯基距离等同于欧氏距离。
  
  $$
  d(P, Q) = \left( \sum_{i=1}^n |p_i - q_i|^2 \right)^{1/2}
  $$
  
  进一步简化为：
  $$
  d(P, Q) = \sqrt{\sum_{i=1}^n (p_i - q_i)^2}
  $$
- p→∞: 闵可夫斯基距离趋近于切比雪夫距离。

5. 汉明距离 (Hamming Distance)

定义: 两个等长字符串在相同位置上不同字符的数量。
公式:
$$
d(P, Q) = \sum_{i=1}^n \delta(p_i, q_i), \quad \delta(p_i, q_i) =
\begin{cases}
0 & \text{如果 } p_i = q_i \
1 & \text{如果 } p_i \neq q_i
\end{cases}
$$
应用: 用于编码理论、信息检索等。

6. 余弦相似度 (Cosine Similarity)

定义: 通过计算两个向量的夹角余弦值来衡量相似性。
公式:
$$
\text{cosine}(P, Q) = \frac{P \cdot Q}{|P| |Q|}
$$
应用: 适用于文本分析、推荐系统等。

7. 杰卡德距离 (Jaccard Distance)

定义: 衡量两个集合的差异，基于交集与并集的比例。
公式:
$$
d(P, Q) = 1 - \frac{|P \cap Q|}{|P \cup Q|}
$$
应用: 用于集合相似性比较，如文档相似性。

8. 马氏距离 (Mahalanobis Distance)

定义: 考虑数据分布的距离度量，适用于多维数据。
公式:
$$
d(P, Q) = \sqrt{(P - Q)^T S^{-1} (P - Q)}
$$
其中 $S$ 是协方差矩阵。
应用: 适用于需要考虑数据相关性的场景。

这些距离算法各有特点，选择时应根据具体问题和数据特性进行权衡。

行列式 - 同乘后加到另一行后，行列式不变

骑驴的柒零 — Tue, 17 Dec 2024 17:54:00 GMT

@@ Tags: 行列式
@@ Date: 2024-12-18 0154

证明行列式的某行的各元素同乘以一个数然后加到另一行上，行列式不变，我们可以按照以下步骤进行：

第一步，设原行列式为

$D = \left| \begin{array}{cccc}
a_{11} & a_{12} & \cdots & a_{1n} \\
a_{21} & a_{22} & \cdots & a_{2n} \\
\vdots & \vdots & \ddots & \vdots \\
a_{i1} & a_{i2} & \cdots & a_{in} \\
a_{j1} & a_{j2} & \cdots & a_{jn} \\
\vdots & \vdots & \ddots & \vdots \\
a_{n1} & a_{n2} & \cdots & a_{nn} \\
\end{array} \right|$

其中，$i \neq j$。

第二步，根据题目要求，我们将第$i$行的各元素同乘以一个数$k$然后加到第$j$行上，得到新的行列式：

$D' = \left| \begin{array}{cccc}
a_{11} & a_{12} & \cdots & a_{1n} \\
a_{21} & a_{22} & \cdots & a_{2n} \\
\vdots & \vdots & \ddots & \vdots \\
a_{i1} & a_{i2} & \cdots & a_{in} \\
a_{j1} + ka_{i1} & a_{j2} + ka_{i2} & \cdots & a_{jn} + ka_{in} \\
\vdots & \vdots & \ddots & \vdots \\
a_{n1} & a_{n2} & \cdots & a_{nn} \\
\end{array} \right|$

第三步，根据行列式的性质 —— 行列式的某一行（列）的元素都是两数之和，则D'等于下列两个行列式之和，得到：

$D' = \left( \left| \begin{array}{cccc}
a_{11} & a_{12} & \cdots & a_{1n} \\
a_{21} & a_{22} & \cdots & a_{2n} \\
\vdots & \vdots & \ddots & \vdots \\
a_{i1} & a_{i2} & \cdots & a_{in} \\
a_{j1} & a_{j2} & \cdots & a_{jn} \\
\vdots & \vdots & \ddots & \vdots \\
a_{n1} & a_{n2} & \cdots & a_{nn} \\
\end{array} \right| +
\left| \begin{array}{cccc}
a_{11} & a_{12} & \cdots & a_{1n} \\
a_{21} & a_{22} & \cdots & a_{2n} \\
\vdots & \vdots & \ddots & \vdots \\
a_{i1} & a_{i2} & \cdots & a_{in} \\
ka_{i1} & ka_{i2} & \cdots & ka_{in} \\
\vdots & \vdots & \ddots & \vdots \\
a_{n1} & a_{n2} & \cdots & a_{nn} \\
\end{array} \right| \right)$

第四步，第二个行列式的第$j$行是第$i$行的$k$倍，根据行列式的性质 —— 行列式中如果有两行（列）元素成比例，则此行列式等于零。因此，我们得到：

$D' = D + 0 = D$

这就证明了行列式的某行的各元素同乘以一个数然后加到另一行上，行列式不变。