默默的点滴 – 智障儿童欢乐多

Dart AOT 二进制文件的完整性检查：运行时的签名验证与篡改检测

讲座主题：Dart AOT 二进制文件的完整性检查：运行时的签名验证与篡改检测

尊敬的各位开发者，安全专家，大家好。

今天，我们将深入探讨一个在现代软件开发中日益关键且复杂的话题：如何确保 Dart AOT (Ahead-Of-Time) 编译生成的原生二进制文件在运行时未被篡改，以及如何通过数字签名进行有效验证。随着 Dart 在桌面、移动和嵌入式设备领域的普及，其 AOT 编译能力使其能够生成高性能的原生代码。然而，原生代码的便利性也带来了新的安全挑战——这些二进制文件更容易成为攻击者篡改的目标，无论是为了注入恶意代码、绕过授权机制，还是窃取知识产权。

作为一名编程专家，我的目标是为大家提供一个全面、深入且实用的视角，来理解、设计并实现一套针对 Dart AOT 二进制文件的运行时完整性检查机制。我们将从密码学基础出发，逐步构建一套可行的签名与验证架构，并探讨其中的技术细节、挑战与权衡。

第一部分：理解 Dart AOT 与运行时安全威胁

1.1 Dart AOT 二进制文件的特性与安全模型

Dart AOT 编译将 Dart 源代码直接转换为机器码，生成独立的可执行文件（例如在 Linux 上是 ELF 文件，Windows 上是 PE 文件，macOS 上是 Mach-O 文件）。这与传统的解释型语言或即时编译 (JIT) 语言（如 Java 的 JVM 或 Python 解释器）有显著不同。AOT 编译的优势在于启动速度快、运行性能高、内存占用低，且不依赖运行时环境（如 JVM 或 Node.js）。

然而，这种原生特性也意味着：

暴露的机器码： 应用程序的逻辑直接以机器码形式存在，更容易被逆向工程工具（如 IDA Pro, Ghidra）分析。
直接的内存访问： 运行时，操作系统直接加载这些机器码到内存中执行。
篡改的风险： 攻击者可以修改磁盘上的二进制文件，或者在程序加载到内存后，利用调试器或内存注入技术修改其运行时行为。

1.2 运行时完整性检查的必要性

为何需要对 Dart AOT 二进制文件进行运行时完整性检查？主要出于以下几个考虑：

防止恶意注入： 攻击者可能在您的应用程序中植入恶意代码，例如键盘记录器、数据窃取模块或后门，而用户浑然不觉。
保护知识产权： 篡改者可能修改程序的授权逻辑、核心算法或数据处理流程，以绕过许可限制，或窃取商业秘密。
维护系统稳定性与可靠性： 被篡改的程序可能导致系统崩溃、数据损坏，甚至引发更严重的安全漏洞。
合规性要求： 在某些行业（如金融、医疗），软件的完整性是严格的合规性要求。
信任链： 用户需要信任他们运行的软件是来自可信源，并且未被第三方修改。

1.3 核心概念：哈希与数字签名

在深入实现之前，我们必须理解两个基石级的密码学概念：加密哈希函数和数字签名。

加密哈希函数 (Cryptographic Hash Function)：
- 将任意长度的输入（如一个文件、一段文本）转换为固定长度的输出，这个输出被称为哈希值、摘要或指纹。
- 具有以下关键特性：
  - 确定性： 相同输入总是产生相同输出。
  - 雪崩效应： 输入中微小的改动都会导致输出哈希值发生巨大变化。
  - 不可逆性： 无法从哈希值逆向推导出原始输入。
  - 抗碰撞性： 极难找到两个不同的输入产生相同的哈希值（强抗碰撞性）。
- 常用的哈希算法有 SHA-256、SHA-3 等。在完整性检查中，哈希值是文件的“数字指纹”。
数字签名 (Digital Signature)：
- 结合了公钥密码学和哈希函数，用于验证数据的来源和完整性。
- 签名过程：
  1. 发送方（签名者）使用加密哈希函数计算原始数据的哈希值。
  2. 发送方使用其私钥对这个哈希值进行加密（签名）。
  3. 将原始数据、签名和发送方的公钥一起发送。
- 验证过程：
  1. 接收方使用相同的哈希函数计算接收到的原始数据的哈希值。
  2. 接收方使用发送方的公钥解密（验证）接收到的签名，得到一个哈希值。
  3. 比较这两个哈希值。如果它们一致，则说明数据在传输过程中未被篡改，并且确实是由持有对应私钥的发送方签名的。
- 常用的数字签名算法有 RSA、ECDSA 等。

通过数字签名，我们可以确保二进制文件不仅没有被意外损坏（哈希值匹配），而且确实是由我们（作为开发者）签发和认可的（签名验证通过）。

第二部分：构建信任的基石——密码学原理与 Dart 实现

在 Dart 中进行密码学操作，我们通常会借助社区提供的强大库。package:crypto 提供了哈希函数，而 package:pointycastle 或 package:cryptography 则提供了更全面的密码学原语，包括公钥加密和数字签名。

2.1 Dart 中的哈希计算

首先，我们来看如何在 Dart 中计算一个文件的 SHA-256 哈希值。

pubspec.yaml

dependencies:
  crypto: ^3.0.3 # 用于哈希计算

1 2	dependencies: crypto: ^3.0.3 # 用于哈希计算

lib/integrity_checker.dart

import 'dart:io';
import 'dart:convert';
import 'package:crypto/crypto.dart';

/// 负责计算文件哈希值的工具类。
class HashCalculator {
  /// 计算指定文件的 SHA-256 哈希值。
  ///
  /// [filePath]：要计算哈希值的文件路径。
  /// 返回：文件的十六进制 SHA-256 哈希值字符串。
  /// 抛出：[FileSystemException] 如果文件不存在或无法读取。
  static Future<String> calculateFileSha256(String filePath) async {
    final file = File(filePath);
    if (!await file.exists()) {
      throw FileSystemException('File not found', filePath);
    }

    try {
      final input = file.openRead();
      final digest = await sha256.bind(input).first;
      return digest.toString();
    } catch (e) {
      throw FileSystemException('Failed to read file or calculate hash', filePath, e.toString());
    }
  }

  /// 计算指定字节数组的 SHA-256 哈希值。
  ///
  /// [bytes]：要计算哈希值的字节数组。
  /// 返回：字节数组的十六进制 SHA-256 哈希值字符串。
  static String calculateBytesSha256(List<int> bytes) {
    final digest = sha256.convert(bytes);
    return digest.toString();
  }
}

// 示例用法
void main() async {
  // 创建一个临时文件用于测试
  final testFile = File('test_integrity_file.txt');
  await testFile.writeAsString('Hello, Dart AOT integrity check!');

  try {
    final hash = await HashCalculator.calculateFileSha256(testFile.path);
    print('文件 "${testFile.path}" 的 SHA-256 哈希值是: $hash');

    final bytesHash = HashCalculator.calculateBytesSha256(utf8.encode('Hello, Dart AOT integrity check!'));
    print('字节数组 "Hello, Dart AOT integrity check!" 的 SHA-256 哈希值是: $bytesHash');

    // 尝试修改文件，查看哈希值变化
    await testFile.writeAsString('Hello, Dart AOT integrity check! Tampered!');
    final tamperedHash = await HashCalculator.calculateFileSha256(testFile.path);
    print('篡改后文件 "${testFile.path}" 的 SHA-256 哈希值是: $tamperedHash');

    if (hash != tamperedHash) {
      print('哈希值已改变，文件可能已被篡改。');
    }

  } catch (e) {
    print('发生错误: $e');
  } finally {
    await testFile.delete(); // 清理临时文件
  }
}

import 'dart:io';

import 'dart:convert';

import 'package:crypto/crypto.dart';

/// 负责计算文件哈希值的工具类。

class HashCalculator {

/// 计算指定文件的 SHA-256 哈希值。

///

/// [filePath]：要计算哈希值的文件路径。

/// 返回：文件的十六进制 SHA-256 哈希值字符串。

/// 抛出：[FileSystemException] 如果文件不存在或无法读取。

static Future<String> calculateFileSha256(String filePath) async {

final file = File(filePath);

if (!await file.exists()) {

throw FileSystemException('File not found', filePath);

}

try {

final input = file.openRead();

final digest = await sha256.bind(input).first;

return digest.toString();

} catch (e) {

throw FileSystemException('Failed to read file or calculate hash', filePath, e.toString());

}

/// 计算指定字节数组的 SHA-256 哈希值。

///

/// [bytes]：要计算哈希值的字节数组。

/// 返回：字节数组的十六进制 SHA-256 哈希值字符串。

static String calculateBytesSha256(List<int> bytes) {

final digest = sha256.convert(bytes);

return digest.toString();

}

// 示例用法

void main() async {

// 创建一个临时文件用于测试

final testFile = File('test_integrity_file.txt');

await testFile.writeAsString('Hello, Dart AOT integrity check!');

try {

final hash = await HashCalculator.calculateFileSha256(testFile.path);

print('文件 "${testFile.path}" 的 SHA-256 哈希值是: $hash');

final bytesHash = HashCalculator.calculateBytesSha256(utf8.encode('Hello, Dart AOT integrity check!'));

print('字节数组 "Hello, Dart AOT integrity check!" 的 SHA-256 哈希值是: $bytesHash');

// 尝试修改文件，查看哈希值变化

await testFile.writeAsString('Hello, Dart AOT integrity check! Tampered!');

final tamperedHash = await HashCalculator.calculateFileSha256(testFile.path);

print('篡改后文件 "${testFile.path}" 的 SHA-256 哈希值是: $tamperedHash');

if (hash != tamperedHash) {

print('哈希值已改变，文件可能已被篡改。');

}

} catch (e) {

print('发生错误: $e');

} finally {

await testFile.delete(); // 清理临时文件

}

这段代码展示了如何使用 crypto 包计算文件或字节数组的 SHA-256 哈希值。在实际的完整性检查中，我们将用它来计算我们自己 AOT 二进制文件的哈希值。

2.2 Dart 中的数字签名验证 (RSA)

对于数字签名，我们将使用 package:pointycastle，它提供了 RSA、ECDSA 等多种算法的实现。这里我们以 RSA 为例。

pubspec.yaml

dependencies:
  crypto: ^3.0.3
  pointycastle: ^3.7.3 # 用于公钥密码学和数字签名
  asn1lib: ^1.1.0 # 用于解析 PEM 格式的公钥

dependencies:

crypto: ^3.0.3

pointycastle: ^3.7.3 # 用于公钥密码学和数字签名

asn1lib: ^1.1.0 # 用于解析 PEM 格式的公钥

lib/signature_verifier.dart

import 'dart:typed_data';
import 'dart:convert';
import 'package:pointycastle/api.dart';
import 'package:pointycastle/asymmetric/api.dart';
import 'package:pointycastle/asymmetric/rsa.dart';
import 'package:pointycastle/digests/sha256.dart';
import 'package:pointycastle/signers/rsa_signer.dart';
import 'package:asn1lib/asn1lib.dart'; // 用于解析 PEM 公钥

/// 辅助函数：从 PEM 格式字符串加载 RSA 公钥。
/// 这需要解析 PEM 格式，提取 ASN.1 编码的公钥数据。
/// 注意：实际应用中，公钥通常以更简洁的方式嵌入，例如 Base64 编码的模数和指数，
/// 或者直接将 ASN.1 DER 编码的字节嵌入。
RSAPublicKey parseRSAPublicKeyFromPem(String pem) {
  final lines = pem.split('n');
  final base64String = lines
      .where((line) =>
          !line.startsWith('-----BEGIN') && !line.startsWith('-----END'))
      .join('');
  final derBytes = base64.decode(base64String);

  final parser = ASN1Parser(derBytes);
  final topLevel = parser.nextObject() as ASN1Sequence;

  // 根据 RFC 3447 (PKCS#1) 或 X.509 SPKI 结构解析公钥
  // X.509 SPKI 结构通常是 Sequence(Sequence(AlgorithmIdentifier), BitString(RSAPublicKey))
  // RSAPublicKey 是 Sequence(modulus, publicExponent)
  ASN1Sequence publicKeySequence;
  if (topLevel.elements.length == 2 && topLevel.elements[0] is ASN1Sequence && topLevel.elements[1] is ASN1BitString) {
    // X.509 SubjectPublicKeyInfo
    final bitString = topLevel.elements[1] as ASN1BitString;
    final spkiParser = ASN1Parser(bitString.stringValue as Uint8List);
    publicKeySequence = spkiParser.nextObject() as ASN1Sequence;
  } else {
    // PKCS#1 RSAPublicKey
    publicKeySequence = topLevel;
  }

  final modulus = publicKeySequence.elements[0] as ASN1Integer;
  final exponent = publicKeySequence.elements[1] as ASN1Integer;

  return RSAPublicKey(modulus.valueAsBigInt, exponent.valueAsBigInt);
}

/// 负责验证数字签名的工具类。
class SignatureVerifier {
  /// 验证给定数据是否由指定公钥签名。
  ///
  /// [publicKeyPem]：PEM 格式的 RSA 公钥字符串。
  /// [dataHashBytes]：原始数据的 SHA-256 哈希值字节数组。
  /// [signatureBytes]：数字签名字节数组。
  /// 返回：如果签名有效则返回 true，否则返回 false。
  static bool verifySignature(String publicKeyPem, Uint8List dataHashBytes, Uint8List signatureBytes) {
    try {
      final rsaPublicKey = parseRSAPublicKeyFromPem(publicKeyPem);

      final signer = RSASigner(SHA256Digest(), '0609608648016503040201'); // '0609608648016503040201' 是 OID for SHA256withRSA PSS if using PSS
      // 对于 PKCS#1 v1.5 padding，通常不需要指定 OID。
      // 对于 SHA256withRSA，PointyCastle 会根据 Digest 类型自动选择合适的 padding
      // 如果使用 RSASigner(SHA256Digest()) 默认是 PKCS1 v1.5 padding
      // 如果需要 PSS padding，则需要 RSASigner(SHA256Digest(), '0609608648016503040201') 并在初始化参数中指定 PSS
      // 这里我们假设使用 PKCS#1 v1.5 padding，这是最常见的。

      signer.init(false, PublicKeyParameter<RSAPublicKey>(rsaPublicKey)); // false 表示验证模式

      // 验证签名的核心步骤
      final RSASignature rsaSignature = RSASignature(signatureBytes);
      return signer.verifySignature(dataHashBytes, rsaSignature);
    } catch (e) {
      print('签名验证过程中发生错误: $e');
      return false;
    }
  }
}

// 示例用法（需要一个实际的私钥来生成签名）
// 假设你已经通过 openssl 生成了私钥和公钥，并用私钥签名了一个哈希值。
// openssl genrsa -out private_key.pem 2048
// openssl rsa -in private_key.pem -pubout -out public_key.pem
// echo "hello world" | sha256sum | awk '{print $1}' > hash.txt
// openssl dgst -sha256 -sign private_key.pem -out signature.sig hash.txt

void main() async {
  // 替换为你的实际公钥 PEM 字符串
  const String publicKeyPem = '''
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsRk3Q09s+v0M/g0H4n4+
... (你的公钥内容) ...
AQAB
-----END PUBLIC KEY-----
'''; // 这里的公钥是占位符，请替换为实际生成的公钥

  // 假设这是我们应用程序的 SHA-256 哈希值 (32 字节)
  final String appHashHex = 'a8047970d4f6c8273752e22c422849c6762335f6068307c0879e60938ff48a62'; // 示例哈希
  final Uint8List appHashBytes = Uint8List.fromList(List.generate(appHashHex.length ~/ 2, (i) => int.parse(appHashHex.substring(i * 2, i * 2 + 2), radix: 16)));

  // 假设这是通过私钥对 appHashBytes 签名的结果 (通常是 256 字节对于 2048 位 RSA)
  // 这个签名需要通过离线工具生成，并以 Base64 等方式嵌入到 Dart 程序中
  const String signatureBase64 = '...'; // 替换为 Base64 编码的签名，这里是占位符
  final Uint8List signatureBytes = base64.decode(signatureBase64);

  print('开始验证签名...');
  final isValid = SignatureVerifier.verifySignature(publicKeyPem, appHashBytes, signatureBytes);

  if (isValid) {
    print('✅ 签名验证成功！二进制文件完整且来自可信源。');
  } else {
    print('❌ 签名验证失败！二进制文件可能已被篡改或来源不可信。');
  }
}

100

101

102

103

104

105

106

107

108

109

110

import 'dart:typed_data';

import 'dart:convert';

import 'package:pointycastle/api.dart';

import 'package:pointycastle/asymmetric/api.dart';

import 'package:pointycastle/asymmetric/rsa.dart';

import 'package:pointycastle/digests/sha256.dart';

import 'package:pointycastle/signers/rsa_signer.dart';

import 'package:asn1lib/asn1lib.dart'; // 用于解析 PEM 公钥

/// 辅助函数：从 PEM 格式字符串加载 RSA 公钥。

/// 这需要解析 PEM 格式，提取 ASN.1 编码的公钥数据。

/// 注意：实际应用中，公钥通常以更简洁的方式嵌入，例如 Base64 编码的模数和指数，

/// 或者直接将 ASN.1 DER 编码的字节嵌入。

RSAPublicKey parseRSAPublicKeyFromPem(String pem) {

final lines = pem.split('n');

final base64String = lines

.where((line) =>

!line.startsWith('-----BEGIN') && !line.startsWith('-----END'))

.join('');

final derBytes = base64.decode(base64String);

final parser = ASN1Parser(derBytes);

final topLevel = parser.nextObject() as ASN1Sequence;

// 根据 RFC 3447 (PKCS#1) 或 X.509 SPKI 结构解析公钥

// X.509 SPKI 结构通常是 Sequence(Sequence(AlgorithmIdentifier), BitString(RSAPublicKey))

// RSAPublicKey 是 Sequence(modulus, publicExponent)

ASN1Sequence publicKeySequence;

if (topLevel.elements.length == 2 && topLevel.elements[0] is ASN1Sequence && topLevel.elements[1] is ASN1BitString) {

// X.509 SubjectPublicKeyInfo

final bitString = topLevel.elements[1] as ASN1BitString;

final spkiParser = ASN1Parser(bitString.stringValue as Uint8List);

publicKeySequence = spkiParser.nextObject() as ASN1Sequence;

} else {

// PKCS#1 RSAPublicKey

publicKeySequence = topLevel;

}

final modulus = publicKeySequence.elements[0] as ASN1Integer;

final exponent = publicKeySequence.elements[1] as ASN1Integer;

return RSAPublicKey(modulus.valueAsBigInt, exponent.valueAsBigInt);

}

/// 负责验证数字签名的工具类。

class SignatureVerifier {

/// 验证给定数据是否由指定公钥签名。

///

/// [publicKeyPem]：PEM 格式的 RSA 公钥字符串。

/// [dataHashBytes]：原始数据的 SHA-256 哈希值字节数组。

/// [signatureBytes]：数字签名字节数组。

/// 返回：如果签名有效则返回 true，否则返回 false。

static bool verifySignature(String publicKeyPem, Uint8List dataHashBytes, Uint8List signatureBytes) {

try {

final rsaPublicKey = parseRSAPublicKeyFromPem(publicKeyPem);

final signer = RSASigner(SHA256Digest(), '0609608648016503040201'); // '0609608648016503040201' 是 OID for SHA256withRSA PSS if using PSS

// 对于 PKCS#1 v1.5 padding，通常不需要指定 OID。

// 对于 SHA256withRSA，PointyCastle 会根据 Digest 类型自动选择合适的 padding

// 如果使用 RSASigner(SHA256Digest()) 默认是 PKCS1 v1.5 padding

// 如果需要 PSS padding，则需要 RSASigner(SHA256Digest(), '0609608648016503040201') 并在初始化参数中指定 PSS

// 这里我们假设使用 PKCS#1 v1.5 padding，这是最常见的。

signer.init(false, PublicKeyParameter<RSAPublicKey>(rsaPublicKey)); // false 表示验证模式

// 验证签名的核心步骤

final RSASignature rsaSignature = RSASignature(signatureBytes);

return signer.verifySignature(dataHashBytes, rsaSignature);

} catch (e) {

print('签名验证过程中发生错误: $e');

return false;

}

// 示例用法（需要一个实际的私钥来生成签名）

// 假设你已经通过 openssl 生成了私钥和公钥，并用私钥签名了一个哈希值。

// openssl genrsa -out private_key.pem 2048

// openssl rsa -in private_key.pem -pubout -out public_key.pem

// echo "hello world" | sha256sum | awk '{print $1}' > hash.txt

// openssl dgst -sha256 -sign private_key.pem -out signature.sig hash.txt

void main() async {

// 替换为你的实际公钥 PEM 字符串

const String publicKeyPem = '''

-----BEGIN PUBLIC KEY-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsRk3Q09s+v0M/g0H4n4+

... (你的公钥内容) ...

AQAB

-----END PUBLIC KEY-----

'''; // 这里的公钥是占位符，请替换为实际生成的公钥

// 假设这是我们应用程序的 SHA-256 哈希值 (32 字节)

final String appHashHex = 'a8047970d4f6c8273752e22c422849c6762335f6068307c0879e60938ff48a62'; // 示例哈希

final Uint8List appHashBytes = Uint8List.fromList(List.generate(appHashHex.length ~/ 2, (i) => int.parse(appHashHex.substring(i * 2, i * 2 + 2), radix: 16)));

// 假设这是通过私钥对 appHashBytes 签名的结果 (通常是 256 字节对于 2048 位 RSA)

// 这个签名需要通过离线工具生成，并以 Base64 等方式嵌入到 Dart 程序中

const String signatureBase64 = '...'; // 替换为 Base64 编码的签名，这里是占位符

final Uint8List signatureBytes = base64.decode(signatureBase64);

print('开始验证签名...');

final isValid = SignatureVerifier.verifySignature(publicKeyPem, appHashBytes, signatureBytes);

if (isValid) {

print('✅ 签名验证成功！二进制文件完整且来自可信源。');

} else {

print('❌ 签名验证失败！二进制文件可能已被篡改或来源不可信。');

}

关于 parseRSAPublicKeyFromPem 的说明：

PEM 格式是 Base64 编码的 DER (Distinguished Encoding Rules) 数据，通常包含 X.509 SubjectPublicKeyInfo 结构。这个结构本身是一个 ASN.1 Sequence，其中包含了算法标识符和一个 BitString，BitString 的内容又是另一个 ASN.1 Sequence，包含 RSA 的模数 (modulus) 和公指数 (publicExponent)。解析这个结构需要对 ASN.1 编码有一定的了解。package:asn1lib 可以帮助我们解析这些结构。

在实际生产环境中，为了简化，我们可能不会直接嵌入 PEM 字符串，而是只嵌入公钥的模数和公指数的 Base64 编码字符串，或者直接嵌入 DER 编码的字节数组，这样可以避免运行时复杂的 ASN.1 解析。

第三部分：设计运行时完整性检查架构

构建一个健壮的运行时完整性检查机制需要精心设计离线签名阶段和在线验证阶段。

3.1 离线签名阶段（构建/发布时）

这个阶段在应用程序编译和打包后进行，由开发者或 CI/CD 系统执行。

生成密钥对： 开发者生成一对 RSA 或 ECDSA 私钥和公钥。私钥必须严格保密，公钥将随应用程序分发。

# 生成 2048 位 RSA 私钥
openssl genrsa -aes256 -out private_key.pem 2048
# 导出公钥
openssl rsa -in private_key.pem -pubout -out public_key.pem
# 注意：在生产环境，私钥应存储在 HSM (硬件安全模块) 或受严格保护的环境中。

# 生成 2048 位 RSA 私钥

openssl genrsa -aes256 -out private_key.pem 2048

# 导出公钥

openssl rsa -in private_key.pem -pubout -out public_key.pem

# 注意：在生产环境，私钥应存储在 HSM (硬件安全模块) 或受严格保护的环境中。

AOT 编译 Dart 应用程序： 生成最终的原生二进制文件。

dart compile exe bin/main.dart -o my_app

1

dart compile exe bin/main.dart -o my_app
计算二进制文件哈希值： 对编译后的整个 AOT 二进制文件计算 SHA-256 哈希值。

sha256sum my_app > my_app.sha256 # 或者对于 Windows: certutil -hashfile my_app SHA256

1
2

sha256sum my_app > my_app.sha256
# 或者对于 Windows: certutil -hashfile my_app SHA256

关键考虑： 在某些情况下，如果签名或公钥被嵌入到二进制文件自身中，那么在计算哈希时需要排除这些部分，以避免“自举问题”——即嵌入内容改变了文件的哈希，导致验证失败。最简单的策略是将签名和公钥存储在二进制文件的末尾，或者作为单独的资源。如果存储在末尾，需要约定一个偏移量或标记来识别和排除它们。
- 策略一（最简单）： 签名和公钥作为独立的资源文件（不推荐，容易被分离或替换）。
- 策略二（推荐）： 签名和公钥以硬编码字符串（Base64 编码）的形式嵌入到 Dart 源代码中，在编译前。这种情况下，哈希的是包含公钥和签名字符串的 Dart 源代码编译出的二进制文件。这看起来像个循环，但实际上是：先编译出一个不含签名的临时版本，计算其哈希，用私钥签名这个哈希，然后把签名和公钥作为常量嵌入到最终的 Dart 源代码中，再进行最终编译。 这种方法虽然安全，但比较繁琐，且签名值每次变动都需要重新编译。
- 策略三（更灵活）： 签名和公钥以特定格式（如 JSON、自定义二进制格式）附加在二进制文件的末尾。在运行时，程序需要知道如何解析这些附加数据，并在计算哈希时排除它们。这需要对二进制文件格式有一定了解，或者约定一个简单的分隔符。
我们主要关注策略二和三的结合：将公钥和签名以硬编码字符串形式嵌入，但签名是针对不包含签名和公钥本身的二进制文件的哈希。

重新思考策略二的实现：
1. AOT 编译 main.dart 到 my_app_unsigned。
2. 计算 my_app_unsigned 的哈希值 hash_of_unsigned_app。
3. 用私钥签名 hash_of_unsigned_app 得到 signature_value。
4. 将 public_key_pem_string 和 signature_value_base64_string 作为 Dart 常量写入一个新文件，例如 lib/app_integrity_constants.dart。
5. 修改 main.dart 导入 app_integrity_constants.dart。
6. 重新 AOT 编译 main.dart 到 my_app_final。
7. 在运行时，my_app_final 会读取 public_key_pem_string 和 signature_value_base64_string。它会尝试计算当前运行的 my_app_final 的哈希，然后用读取到的公钥和签名去验证。
问题： my_app_final 的哈希会包含 public_key_pem_string 和 signature_value_base64_string，而 signature_value 是基于 my_app_unsigned 计算的。这两者不匹配。

正确的策略（策略三的变种）：将签名和公钥作为外部数据或者以一种可预测的方式附加到二进制文件尾部。

我们选择一种相对简单且通用的方法：将签名和公钥作为硬编码字符串嵌入到 Dart 代码中，但哈希计算的目标是整个二进制文件。这意味着签名所覆盖的内容，也包括了它自身以及公钥。这并非完美，但对于大多数应用场景，它的简单性和有效性可以接受。如果攻击者修改了二进制文件，那么哈希值会改变，签名验证就会失败。如果攻击者同时修改了嵌入的签名或公钥，那么要么哈希值不匹配，要么公钥不对，签名验证依然失败。攻击者唯一能成功的方式是：修改了二进制文件，并用他们自己的私钥重新签名，然后将新的签名和对应的公钥嵌入到程序中。这时，我们需要确保我们的验证逻辑足够健壮，不被轻易替换。

因此，我们采用如下流程：
1. AOT 编译 bin/main.dart 到 my_app。
2. 计算 my_app 的完整哈希 H_app。
3. 使用私钥对 H_app 进行签名，得到 S_app。
4. 将 public_key_pem_string 和 S_app 的 Base64 编码字符串作为 Dart 常量嵌入到 lib/app_integrity_constants.dart。
5. 注意： 这一步需要循环。因为嵌入 public_key_pem_string 和 S_app 会改变 my_app 的内容，从而改变 H_app。理想情况下，我们需要一个固定的位置来存储这些，或者使用一个“两阶段”签名法：
  - a. 编译一个占位符版本。
  - b. 计算占位符版本的哈希。
  - c. 签名哈希。
  - d. 将签名和公钥嵌入到指定位置。
  - e. 重新编译，确保这些嵌入操作不会改变二进制文件的其他部分，或者只改变这些部分，而我们计算哈希时可以排除它们。
更实际的流程：
为了避免复杂的二进制文件解析和循环编译问题，我们采用一个更直接的方法：
1. 最终编译前： 在 Dart 代码中预留好 const String _kEmbeddedPublicKey = '...'; 和 const String _kEmbeddedSignature = '...'; 的位置。
2. 首次编译： 编译一个“占位符”版本，例如 dart compile exe bin/main.dart -o my_app_placeholder。
3. 计算哈希： 计算 my_app_placeholder 的完整 SHA-256 哈希 H_placeholder。
4. 签名： 使用私钥对 H_placeholder 进行签名，得到 S_placeholder。
5. 更新常量： 将你的公钥 PEM 字符串和 S_placeholder 的 Base64 编码填入 _kEmbeddedPublicKey 和 _kEmbeddedSignature。
6. 最终编译： 重新编译一次，得到 my_app_final。注意： 此时 my_app_final 的哈希值已经与 H_placeholder 不同，因为它包含了 _kEmbeddedPublicKey 和 _kEmbeddedSignature。
7. 运行时验证： 在运行时，程序会计算 my_app_final 的哈希 H_runtime。然后尝试用 _kEmbeddedPublicKey 验证 _kEmbeddedSignature 是否是 H_runtime 的签名。
  问题： 这种方法依然存在哈希不匹配的问题，因为签名是针对 my_app_placeholder 的，而不是 my_app_final 的。
解决哈希不匹配的通用方案：将签名和公钥附加到文件末尾。
这需要一个额外的工具来处理。
1. AOT 编译 bin/main.dart 到 my_app_executable。
2. 计算 my_app_executable 的 SHA-256 哈希 H_app。
3. 使用私钥对 H_app 进行签名，得到 S_app。
4. 将 S_app 和 public_key_pem_string 编码成一个结构（例如 JSON 或自定义格式），并将其附加到 my_app_executable 文件的末尾。
  - 例如：my_app_executable + 'START_SIGNATURE_BLOCK' + {signature_data_json} + 'END_SIGNATURE_BLOCK'
5. 在运行时：
  - 程序读取自己 (my_app_executable) 的内容。
  - 找到并解析末尾的签名块。
  - 在计算哈希时，只计算签名块之前的部分。
  - 使用解析出的公钥和签名验证这个哈希。
这种方法要求程序能够精确地识别和排除签名块。这通常通过在签名块前添加一个已知魔术字符串 (magic string) 和签名块的长度来实现。

3.2 运行时验证阶段（应用程序启动时）

这个阶段在应用程序启动时，由应用程序自身执行。

获取自身路径： 应用程序需要知道自己作为可执行文件的路径。
读取自身内容： 应用程序以二进制流的形式读取自己文件的内容。
排除签名块（如果适用）： 如果签名块被附加在文件末尾，应用程序需要计算一个排除这些部分的哈希值。
计算运行时哈希： 对程序文件（或其相关部分）计算 SHA-256 哈希值。
加载公钥与签名： 从嵌入的常量或外部资源中加载公钥和预存的数字签名。
验证签名： 使用公钥验证运行时哈希值与预存签名的匹配性。
处理验证结果：
- 成功： 应用程序正常启动。
- 失败： 应用程序应立即终止、记录错误、提示用户，甚至可以尝试报告（如果安全通道可用）。

3.3 关键挑战与解决方案

自举问题： 应用程序如何验证自身？如果验证逻辑本身被篡改怎么办？
- 解决方案： 将核心验证逻辑放置在二进制文件中难以篡改的区域，或者通过多层、分散的验证点来增加攻击难度。虽然无法100%防止最顶级的攻击者，但可以显著提高攻击门槛。
跨平台兼容性： 获取自身路径、文件 I/O 在不同操作系统上有所不同。
- 解决方案： Dart 的 dart:io 提供了跨平台的文件操作。对于获取可执行文件路径，Platform.executable 通常可用。对于更底层的操作，可能需要使用 dart:ffi 调用操作系统原生 API。
性能开销： 对大型二进制文件进行哈希计算可能耗时，影响启动速度。
- 解决方案：
  - 在开发阶段进行性能测试。
  - 考虑使用更快的哈希算法（如果安全性允许）。
  - 哈希关键代码段而非整个文件（复杂）。
  - 首次启动时进行完整检查，后续启动时可以考虑缓存哈希结果（但缓存本身需要保护）。
攻击者如何绕过： 攻击者可能尝试修改验证逻辑本身、替换嵌入的公钥、或者简单地 Hook exit() 函数。
- 解决方案：
  - 代码混淆： Dart AOT 支持一定程度的混淆，使得逆向工程更困难。
  - 反调试/反篡改技术： 利用 dart:ffi 调用 OS API 检测调试器、检测内存修改等（高级且复杂）。
  - 分散验证点： 在程序的不同模块和生命周期阶段进行多次验证。
  - 安全退出： 在验证失败时，确保程序以一种难以被 Hook 或绕过的方式安全终止。

第四部分：详细实现：从构建到运行

我们将重点实现上述将签名和公钥附加到文件末尾的策略。这需要一个外部工具来执行附加操作，以及 Dart 应用程序内部的解析和验证逻辑。

4.1 预编译与签名流程（外部脚本与工具）

1. 生成密钥对 (如果尚未生成):

   openssl genrsa -out private_key.pem 2048
   openssl rsa -in private_key.pem -pubout -out public_key.pem

1 2	openssl genrsa -out private_key.pem 2048 openssl rsa -in private_key.pem -pubout -out public_key.pem

2. Dart AOT 编译应用程序:
假设你的主 Dart 文件是 bin/main.dart。

   dart compile exe bin/main.dart -o my_app

1	dart compile exe bin/main.dart -o my_app

3. 创建一个 Python 脚本来附加签名和公钥:
这个脚本将执行哈希、签名和附加操作。

sign_and_attach.py

   import hashlib
   import base64
   from cryptography.hazmat.primitives import hashes
   from cryptography.hazmat.primitives.asymmetric import padding
   from cryptography.hazmat.primitives.asymmetric import rsa
   from cryptography.hazmat.primitives import serialization
   import json
   import sys
   import os

   def calculate_sha256(filepath):
       """计算文件的 SHA-256 哈希值."""
       hasher = hashlib.sha256()
       with open(filepath, 'rb') as f:
           while True:
               chunk = f.read(4096)
               if not chunk:
                   break
               hasher.update(chunk)
       return hasher.digest()

   def sign_hash(private_key_path, data_hash):
       """使用 RSA 私钥对哈希值进行签名."""
       with open(private_key_path, "rb") as key_file:
           private_key = serialization.load_pem_private_key(
               key_file.read(),
               password=None, # 如果私钥有密码，这里需要提供
           )

       signature = private_key.sign(
           data_hash,
           padding.PSS(
               mgf=padding.MGF1(hashes.SHA256()),
               salt_length=padding.PSS.MAX_LENGTH
           ),
           hashes.SHA256()
       )
       return signature

   def get_public_key_pem(public_key_path):
       """读取公钥 PEM 字符串."""
       with open(public_key_path, 'r') as f:
           return f.read()

   def attach_signature_block(executable_path, signature_data):
       """将签名数据块附加到可执行文件末尾."""
       # 魔术字符串和长度前缀，以便 Dart 程序能够识别和解析
       magic_start = b'DART_AOT_SIGNATURE_BLOCK_START_V1n'
       magic_end = b'nDART_AOT_SIGNATURE_BLOCK_END_V1n'

       signature_json_bytes = json.dumps(signature_data, indent=2).encode('utf-8')
       signature_block = magic_start + signature_json_bytes + magic_end

       with open(executable_path, 'ab') as f: # 以追加二进制模式打开
           f.write(signature_block)

       print(f"签名块已成功附加到 '{executable_path}'。")
       print(f"签名块大小: {len(signature_block)} 字节。")

   if __name__ == "__main__":
       if len(sys.argv) != 4:
           print("用法: python sign_and_attach.py <executable_path> <private_key_path> <public_key_path>")
           sys.exit(1)

       executable_path = sys.argv[1]
       private_key_path = sys.argv[2]
       public_key_path = sys.argv[3]

       if not os.path.exists(executable_path):
           print(f"错误: 可执行文件 '{executable_path}' 不存在。")
           sys.exit(1)
       if not os.path.exists(private_key_path):
           print(f"错误: 私钥文件 '{private_key_path}' 不存在。")
           sys.exit(1)
       if not os.path.exists(public_key_path):
           print(f"错误: 公钥文件 '{public_key_path}' 不存在。")
           sys.exit(1)

       # 1. 计算原始可执行文件的哈希值 (不含签名块)
       original_hash = calculate_sha256(executable_path)
       print(f"原始可执行文件 '{executable_path}' 的 SHA-256 哈希值: {original_hash.hex()}")

       # 2. 对哈希值进行签名
       signature = sign_hash(private_key_path, original_hash)
       print(f"生成的签名 (Base64): {base64.b64encode(signature).decode('utf-8')}")

       # 3. 获取公钥 PEM 字符串
       public_key_pem = get_public_key_pem(public_key_path)

       # 4. 构建签名数据块
       signature_data = {
           "hash_algorithm": "SHA256",
           "signature_algorithm": "RSA-PSS", # 或 RSA-PKCS1v15
           "original_hash_base64": base64.b64encode(original_hash).decode('utf-8'),
           "signature_base64": base64.b64encode(signature).decode('utf-8'),
           "public_key_pem": public_key_pem,
       }

       # 5. 将签名数据块附加到可执行文件
       attach_signature_block(executable_path, signature_data)

       print("签名和附加过程完成。")

100

101

102

import hashlib

import base64

from cryptography.hazmat.primitives import hashes

from cryptography.hazmat.primitives.asymmetric import padding

from cryptography.hazmat.primitives.asymmetric import rsa

from cryptography.hazmat.primitives import serialization

import json

import sys

import os

def calculate_sha256(filepath):

"""计算文件的 SHA-256 哈希值."""

hasher = hashlib.sha256()

with open(filepath, 'rb') as f:

while True:

chunk = f.read(4096)

if not chunk:

break

hasher.update(chunk)

return hasher.digest()

def sign_hash(private_key_path, data_hash):

"""使用 RSA 私钥对哈希值进行签名."""

with open(private_key_path, "rb") as key_file:

private_key = serialization.load_pem_private_key(

key_file.read(),

password=None, # 如果私钥有密码，这里需要提供

)

signature = private_key.sign(

data_hash,

padding.PSS(

mgf=padding.MGF1(hashes.SHA256()),

salt_length=padding.PSS.MAX_LENGTH

hashes.SHA256()

)

return signature

def get_public_key_pem(public_key_path):

"""读取公钥 PEM 字符串."""

with open(public_key_path, 'r') as f:

return f.read()

def attach_signature_block(executable_path, signature_data):

"""将签名数据块附加到可执行文件末尾."""

# 魔术字符串和长度前缀，以便 Dart 程序能够识别和解析

magic_start = b'DART_AOT_SIGNATURE_BLOCK_START_V1n'

magic_end = b'nDART_AOT_SIGNATURE_BLOCK_END_V1n'

signature_json_bytes = json.dumps(signature_data, indent=2).encode('utf-8')

signature_block = magic_start + signature_json_bytes + magic_end

with open(executable_path, 'ab') as f: # 以追加二进制模式打开

f.write(signature_block)

print(f"签名块已成功附加到 '{executable_path}'。")

print(f"签名块大小: {len(signature_block)} 字节。")

if __name__ == "__main__":

if len(sys.argv) != 4:

print("用法: python sign_and_attach.py <executable_path> <private_key_path> <public_key_path>")

sys.exit(1)

executable_path = sys.argv[1]

private_key_path = sys.argv[2]

public_key_path = sys.argv[3]

if not os.path.exists(executable_path):

print(f"错误: 可执行文件 '{executable_path}' 不存在。")

sys.exit(1)

if not os.path.exists(private_key_path):

print(f"错误: 私钥文件 '{private_key_path}' 不存在。")

sys.exit(1)

if not os.path.exists(public_key_path):

print(f"错误: 公钥文件 '{public_key_path}' 不存在。")

sys.exit(1)

# 1. 计算原始可执行文件的哈希值 (不含签名块)

original_hash = calculate_sha256(executable_path)

print(f"原始可执行文件 '{executable_path}' 的 SHA-256 哈希值: {original_hash.hex()}")

# 2. 对哈希值进行签名

signature = sign_hash(private_key_path, original_hash)

print(f"生成的签名 (Base64): {base64.b64encode(signature).decode('utf-8')}")

# 3. 获取公钥 PEM 字符串

public_key_pem = get_public_key_pem(public_key_path)

# 4. 构建签名数据块

signature_data = {

"hash_algorithm": "SHA256",

"signature_algorithm": "RSA-PSS", # 或 RSA-PKCS1v15

"original_hash_base64": base64.b64encode(original_hash).decode('utf-8'),

"signature_base64": base64.b64encode(signature).decode('utf-8'),

"public_key_pem": public_key_pem,

}

# 5. 将签名数据块附加到可执行文件

attach_signature_block(executable_path, signature_data)

print("签名和附加过程完成。")

运行签名脚本:

 python sign_and_attach.py my_app private_key.pem public_key.pem

1	python sign_and_attach.py my_app private_key.pem public_key.pem

现在 my_app 文件末尾将包含一个 JSON 格式的签名块。

4.2 运行时验证流程（Dart 应用程序内部）

Dart 应用程序需要实现以下功能：

获取自身路径。
以二进制模式读取自身文件内容。
解析文件末尾的签名块： 查找魔术字符串，提取 JSON 数据。
计算“干净”的哈希： 只对签名块之前的文件内容计算哈希。
验证签名。
根据结果采取行动。

lib/integrity_checker.dart (更新)

import 'dart:io';
import 'dart:convert';
import 'dart:typed_data';

import 'package:crypto/crypto.dart';
import 'package:pointycastle/api.dart';
import 'package:pointycastle/asymmetric/api.dart';
import 'package:pointycastle/asymmetric/rsa.dart';
import 'package:pointycastle/digests/sha256.dart';
import 'package:pointycastle/signers/rsa_signer.dart';
import 'package:asn1lib/asn1lib.dart'; // 用于解析 PEM 公钥

/// 定义签名块的魔术字符串，需要与 Python 脚本中的一致。
const String _kSignatureBlockStartMagic = 'DART_AOT_SIGNATURE_BLOCK_START_V1n';
const String _kSignatureBlockEndMagic = 'nDART_AOT_SIGNATURE_BLOCK_END_V1n';

/// 用于存储解析出的签名数据。
class SignatureData {
  final String hashAlgorithm;
  final String signatureAlgorithm;
  final String originalHashBase64;
  final String signatureBase64;
  final String publicKeyPem;

  SignatureData({
    required this.hashAlgorithm,
    required this.signatureAlgorithm,
    required this.originalHashBase64,
    required this.signatureBase64,
    required this.publicKeyPem,
  });

  factory SignatureData.fromJson(Map<String, dynamic> json) {
    return SignatureData(
      hashAlgorithm: json['hash_algorithm'] as String,
      signatureAlgorithm: json['signature_algorithm'] as String,
      originalHashBase64: json['original_hash_base64'] as String,
      signatureBase64: json['signature_base64'] as String,
      publicKeyPem: json['public_key_pem'] as String,
    );
  }
}

/// 辅助函数：从 PEM 格式字符串加载 RSA 公钥。
RSAPublicKey parseRSAPublicKeyFromPem(String pem) {
  final lines = pem.split('n');
  final base64String = lines
      .where((line) =>
          !line.startsWith('-----BEGIN') && !line.startsWith('-----END'))
      .join('');
  final derBytes = base64.decode(base64String);

  final parser = ASN1Parser(derBytes);
  final topLevel = parser.nextObject() as ASN1Sequence;

  ASN1Sequence publicKeySequence;
  if (topLevel.elements.length == 2 && topLevel.elements[0] is ASN1Sequence && topLevel.elements[1] is ASN1BitString) {
    // X.509 SubjectPublicKeyInfo
    final bitString = topLevel.elements[1] as ASN1BitString;
    final spkiParser = ASN1Parser(bitString.stringValue as Uint8List);
    publicKeySequence = spkiParser.nextObject() as ASN1Sequence;
  } else {
    // PKCS#1 RSAPublicKey
    publicKeySequence = topLevel;
  }

  final modulus = publicKeySequence.elements[0] as ASN1Integer;
  final exponent = publicKeySequence.elements[1] as ASN1Integer;

  return RSAPublicKey(modulus.valueAsBigInt, exponent.valueAsBigInt);
}

class AppIntegrityChecker {
  /// 尝试从当前可执行文件末尾解析签名数据块。
  ///
  /// 返回：[SignatureData] 对象，如果解析失败则返回 null。
  static Future<SignatureData?> _parseSignatureBlock(String executablePath) async {
    final file = File(executablePath);
    if (!await file.exists()) {
      print('错误: 可执行文件不存在: $executablePath');
      return null;
    }

    // 读取文件的最后一部分，以查找签名块
    // 假设签名块不会太大，例如不超过 4KB
    const int readBufferSize = 4096;
    final fileLength = await file.length();
    final startOffset = (fileLength - readBufferSize).clamp(0, fileLength).toInt();

    final raf = await file.open(mode: FileMode.read);
    await raf.setPosition(startOffset);
    final buffer = await raf.read(fileLength - startOffset);
    await raf.close();

    final bufferString = utf8.decode(buffer, allowMalformed: true);

    final startIndex = bufferString.indexOf(_kSignatureBlockStartMagic);
    final endIndex = bufferString.indexOf(_kSignatureBlockEndMagic, startIndex != -1 ? startIndex + _kSignatureBlockStartMagic.length : 0);

    if (startIndex == -1 || endIndex == -1) {
      print('警告: 未找到有效的签名块。');
      return null;
    }

    final jsonStartIndex = startIndex + _kSignatureBlockStartMagic.length;
    final jsonString = bufferString.substring(jsonStartIndex, endIndex);

    try {
      final Map<String, dynamic> jsonMap = json.decode(jsonString);
      return SignatureData.fromJson(jsonMap);
    } catch (e) {
      print('错误: 解析签名块JSON失败: $e');
      return null;
    }
  }

  /// 计算可执行文件（排除签名块）的 SHA-256 哈希值。
  ///
  /// [executablePath]：可执行文件路径。
  /// [signatureBlockEndOffset]：签名块结束的字节偏移量，用于确定哈希计算的范围。
  /// 返回：哈希值的字节数组。
  static Future<Uint8List> _calculateExecutableHash(String executablePath, int signatureBlockEndOffset) async {
    final file = File(executablePath);
    if (!await file.exists()) {
      throw FileSystemException('文件不存在', executablePath);
    }

    final input = file.openRead(0, signatureBlockEndOffset); // 只读取签名块之前的部分
    final digest = await sha256.bind(input).first;
    return Uint8List.fromList(digest.bytes);
  }

  /// 执行应用程序的完整性检查。
  ///
  /// 返回：如果完整性验证成功则返回 true，否则返回 false。
  static Future<bool> checkIntegrity() async {
    final executablePath = Platform.executable;
    print('正在检查可执行文件: $executablePath 的完整性...');

    final SignatureData? signatureData = await _parseSignatureBlock(executablePath);
    if (signatureData == null) {
      print('❌ 完整性检查失败: 无法解析签名数据块。');
      return false;
    }

    final fileLength = await File(executablePath).length();
    // 计算签名块的起始和结束位置，相对于文件末尾的偏移
    final endMagicLength = _kSignatureBlockEndMagic.length;
    final startMagicLength = _kSignatureBlockStartMagic.length;

    // 假设签名块的JSON内容长度
    final jsonContentLength = base64.decode(signatureData.signatureBase64).length + base64.decode(signatureData.originalHashBase64).length + signatureData.publicKeyPem.length + 200; // 粗略估计JSON内容的长度，加上一些冗余

    // 签名块的总长度，需要与 Python 脚本保持一致
    // 实际计算时，应该精确计算 json.dumps(signature_data) 的长度，但这里我们无法获得原始 Python 脚本的精确输出
    // 假设我们已经通过某种方式知道精确的签名块长度，或者从签名块中解析出它的长度
    // 简化的方法是：从文件末尾向回搜索 START_MAGIC，然后计算其之前的长度

    final fullFileContent = await File(executablePath).readAsBytes();
    final String fullFileContentString = utf8.decode(fullFileContent, allowMalformed: true);

    final startMagicIndex = fullFileContentString.lastIndexOf(_kSignatureBlockStartMagic);
    if (startMagicIndex == -1) {
        print('❌ 完整性检查失败: 无法在完整文件内容中找到签名块开始标记。');
        return false;
    }

    // 用于计算哈希的文件部分结束偏移量
    final executableContentEndOffset = startMagicIndex;

    // 1. 计算当前可执行文件（排除签名块）的哈希值
    final Uint8List runtimeHashBytes = await _calculateExecutableHash(executablePath, executableContentEndOffset);
    final String runtimeHashHex = runtimeHashBytes.map((byte) => byte.toRadixString(16).padLeft(2, '0')).join();
    print('运行时计算的哈希值: $runtimeHashHex');

    // 2. 从签名数据中提取原始哈希和签名
    final Uint8List expectedOriginalHashBytes = base64.decode(signatureData.originalHashBase64);
    final Uint8List signatureBytes = base64.decode(signatureData.signatureBase64);

    if (runtimeHashBytes.length != expectedOriginalHashBytes.length ||
        !_compareByteLists(runtimeHashBytes, expectedOriginalHashBytes)) {
      print('❌ 完整性检查失败: 运行时哈希值与签名中记录的原始哈希值不匹配。');
      return false;
    }

    // 3. 验证数字签名
    try {
      final rsaPublicKey = parseRSAPublicKeyFromPem(signatureData.publicKeyPem);
      final signer = RSASigner(SHA256Digest(), '0609608648016503040201'); // PSS padding OID
      signer.init(false, PublicKeyParameter<RSAPublicKey>(rsaPublicKey)); // false for verification

      final RSASignature rsaSignature = RSASignature(signatureBytes);
      final bool isValid = signer.verifySignature(runtimeHashBytes, rsaSignature);

      if (isValid) {
        print('✅ 签名验证成功！二进制文件完整且来自可信源。');
        return true;
      } else {
        print('❌ 签名验证失败！二进制文件可能已被篡改或来源不可信。');
        return false;
      }
    } catch (e) {
      print('❌ 签名验证过程中发生错误: $e');
      return false;
    }
  }

  /// 比较两个字节列表是否相同。
  static bool _compareByteLists(Uint8List a, Uint8List b) {
    if (a.length != b.length) return false;
    for (int i = 0; i < a.length; i++) {
      if (a[i] != b[i]) return false;
    }
    return true;
  }
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

import 'dart:io';

import 'dart:convert';

import 'dart:typed_data';

import 'package:crypto/crypto.dart';

import 'package:pointycastle/api.dart';

import 'package:pointycastle/asymmetric/api.dart';

import 'package:pointycastle/asymmetric/rsa.dart';

import 'package:pointycastle/digests/sha256.dart';

import 'package:pointycastle/signers/rsa_signer.dart';

import 'package:asn1lib/asn1lib.dart'; // 用于解析 PEM 公钥

/// 定义签名块的魔术字符串，需要与 Python 脚本中的一致。

const String _kSignatureBlockStartMagic = 'DART_AOT_SIGNATURE_BLOCK_START_V1n';

const String _kSignatureBlockEndMagic = 'nDART_AOT_SIGNATURE_BLOCK_END_V1n';

/// 用于存储解析出的签名数据。

class SignatureData {

final String hashAlgorithm;

final String signatureAlgorithm;

final String originalHashBase64;

final String signatureBase64;

final String publicKeyPem;

SignatureData({

required this.hashAlgorithm,

required this.signatureAlgorithm,

required this.originalHashBase64,

required this.signatureBase64,

required this.publicKeyPem,

});

factory SignatureData.fromJson(Map<String, dynamic> json) {

return SignatureData(

hashAlgorithm: json['hash_algorithm'] as String,

signatureAlgorithm: json['signature_algorithm'] as String,

originalHashBase64: json['original_hash_base64'] as String,

signatureBase64: json['signature_base64'] as String,

publicKeyPem: json['public_key_pem'] as String,

);

}

/// 辅助函数：从 PEM 格式字符串加载 RSA 公钥。

RSAPublicKey parseRSAPublicKeyFromPem(String pem) {

final lines = pem.split('n');

final base64String = lines

.where((line) =>

!line.startsWith('-----BEGIN') && !line.startsWith('-----END'))

.join('');

final derBytes = base64.decode(base64String);

final parser = ASN1Parser(derBytes);

final topLevel = parser.nextObject() as ASN1Sequence;

ASN1Sequence publicKeySequence;

if (topLevel.elements.length == 2 && topLevel.elements[0] is ASN1Sequence && topLevel.elements[1] is ASN1BitString) {

// X.509 SubjectPublicKeyInfo

final bitString = topLevel.elements[1] as ASN1BitString;

final spkiParser = ASN1Parser(bitString.stringValue as Uint8List);

publicKeySequence = spkiParser.nextObject() as ASN1Sequence;

} else {

// PKCS#1 RSAPublicKey

publicKeySequence = topLevel;

}

final modulus = publicKeySequence.elements[0] as ASN1Integer;

final exponent = publicKeySequence.elements[1] as ASN1Integer;

return RSAPublicKey(modulus.valueAsBigInt, exponent.valueAsBigInt);

}

class AppIntegrityChecker {

/// 尝试从当前可执行文件末尾解析签名数据块。

///

/// 返回：[SignatureData] 对象，如果解析失败则返回 null。

static Future<SignatureData?> _parseSignatureBlock(String executablePath) async {

final file = File(executablePath);

if (!await file.exists()) {

print('错误: 可执行文件不存在: $executablePath');

return null;

}

// 读取文件的最后一部分，以查找签名块

// 假设签名块不会太大，例如不超过 4KB

const int readBufferSize = 4096;

final fileLength = await file.length();

final startOffset = (fileLength - readBufferSize).clamp(0, fileLength).toInt();

final raf = await file.open(mode: FileMode.read);

await raf.setPosition(startOffset);

final buffer = await raf.read(fileLength - startOffset);

await raf.close();

final bufferString = utf8.decode(buffer, allowMalformed: true);

final startIndex = bufferString.indexOf(_kSignatureBlockStartMagic);

final endIndex = bufferString.indexOf(_kSignatureBlockEndMagic, startIndex != -1 ? startIndex + _kSignatureBlockStartMagic.length : 0);

if (startIndex == -1 || endIndex == -1) {

print('警告: 未找到有效的签名块。');

return null;

}

final jsonStartIndex = startIndex + _kSignatureBlockStartMagic.length;

final jsonString = bufferString.substring(jsonStartIndex, endIndex);

try {

final Map<String, dynamic> jsonMap = json.decode(jsonString);

return SignatureData.fromJson(jsonMap);

} catch (e) {

print('错误: 解析签名块JSON失败: $e');

return null;

}

/// 计算可执行文件（排除签名块）的 SHA-256 哈希值。

///

/// [executablePath]：可执行文件路径。

/// [signatureBlockEndOffset]：签名块结束的字节偏移量，用于确定哈希计算的范围。

/// 返回：哈希值的字节数组。

static Future<Uint8List> _calculateExecutableHash(String executablePath, int signatureBlockEndOffset) async {

final file = File(executablePath);

if (!await file.exists()) {

throw FileSystemException('文件不存在', executablePath);

}

final input = file.openRead(0, signatureBlockEndOffset); // 只读取签名块之前的部分

final digest = await sha256.bind(input).first;

return Uint8List.fromList(digest.bytes);

}

/// 执行应用程序的完整性检查。

///

/// 返回：如果完整性验证成功则返回 true，否则返回 false。

static Future<bool> checkIntegrity() async {

final executablePath = Platform.executable;

print('正在检查可执行文件: $executablePath 的完整性...');

final SignatureData? signatureData = await _parseSignatureBlock(executablePath);

if (signatureData == null) {

print('❌ 完整性检查失败: 无法解析签名数据块。');

return false;

}

final fileLength = await File(executablePath).length();

// 计算签名块的起始和结束位置，相对于文件末尾的偏移

final endMagicLength = _kSignatureBlockEndMagic.length;

final startMagicLength = _kSignatureBlockStartMagic.length;

// 假设签名块的JSON内容长度

final jsonContentLength = base64.decode(signatureData.signatureBase64).length + base64.decode(signatureData.originalHashBase64).length + signatureData.publicKeyPem.length + 200; // 粗略估计JSON内容的长度，加上一些冗余

// 签名块的总长度，需要与 Python 脚本保持一致

// 实际计算时，应该精确计算 json.dumps(signature_data) 的长度，但这里我们无法获得原始 Python 脚本的精确输出

// 假设我们已经通过某种方式知道精确的签名块长度，或者从签名块中解析出它的长度

// 简化的方法是：从文件末尾向回搜索 START_MAGIC，然后计算其之前的长度

final fullFileContent = await File(executablePath).readAsBytes();

final String fullFileContentString = utf8.decode(fullFileContent, allowMalformed: true);

final startMagicIndex = fullFileContentString.lastIndexOf(_kSignatureBlockStartMagic);

if (startMagicIndex == -1) {

print('❌ 完整性检查失败: 无法在完整文件内容中找到签名块开始标记。');

return false;

}

// 用于计算哈希的文件部分结束偏移量

final executableContentEndOffset = startMagicIndex;

// 1. 计算当前可执行文件（排除签名块）的哈希值

final Uint8List runtimeHashBytes = await _calculateExecutableHash(executablePath, executableContentEndOffset);

final String runtimeHashHex = runtimeHashBytes.map((byte) => byte.toRadixString(16).padLeft(2, '0')).join();

print('运行时计算的哈希值: $runtimeHashHex');

// 2. 从签名数据中提取原始哈希和签名

final Uint8List expectedOriginalHashBytes = base64.decode(signatureData.originalHashBase64);

final Uint8List signatureBytes = base64.decode(signatureData.signatureBase64);

if (runtimeHashBytes.length != expectedOriginalHashBytes.length ||

!_compareByteLists(runtimeHashBytes, expectedOriginalHashBytes)) {

print('❌ 完整性检查失败: 运行时哈希值与签名中记录的原始哈希值不匹配。');

return false;

}

// 3. 验证数字签名

try {

final rsaPublicKey = parseRSAPublicKeyFromPem(signatureData.publicKeyPem);

final signer = RSASigner(SHA256Digest(), '0609608648016503040201'); // PSS padding OID

signer.init(false, PublicKeyParameter<RSAPublicKey>(rsaPublicKey)); // false for verification

final RSASignature rsaSignature = RSASignature(signatureBytes);

final bool isValid = signer.verifySignature(runtimeHashBytes, rsaSignature);

if (isValid) {

print('✅ 签名验证成功！二进制文件完整且来自可信源。');

return true;

} else {

print('❌ 签名验证失败！二进制文件可能已被篡改或来源不可信。');

return false;

}

} catch (e) {

print('❌ 签名验证过程中发生错误: $e');

return false;

}

/// 比较两个字节列表是否相同。

static bool _compareByteLists(Uint8List a, Uint8List b) {

if (a.length != b.length) return false;

for (int i = 0; i < a.length; i++) {

if (a[i] != b[i]) return false;

}

return true;

}

bin/main.dart

import 'package:myapp/integrity_checker.dart'; // 替换为你的库名

void main(List<String> args) async {
  print('应用程序启动...');

  // 执行完整性检查
  final bool integrityOk = await AppIntegrityChecker.checkIntegrity();

  if (!integrityOk) {
    print('应用程序完整性检查失败。正在安全退出。');
    // 在生产环境中，这里应该直接调用 exit(1)，避免任何后续代码执行
    // 或者显示一个错误对话框并强制退出
    exit(1);
  }

  print('应用程序完整性验证通过。继续执行业务逻辑...');
  // 你的应用程序核心逻辑从这里开始
  print('Hello from the trusted Dart AOT app!');
}

import 'package:myapp/integrity_checker.dart'; // 替换为你的库名

void main(List<String> args) async {

print('应用程序启动...');

// 执行完整性检查

final bool integrityOk = await AppIntegrityChecker.checkIntegrity();

if (!integrityOk) {

print('应用程序完整性检查失败。正在安全退出。');

// 在生产环境中，这里应该直接调用 exit(1)，避免任何后续代码执行

// 或者显示一个错误对话框并强制退出

exit(1);

}

print('应用程序完整性验证通过。继续执行业务逻辑...');

// 你的应用程序核心逻辑从这里开始

print('Hello from the trusted Dart AOT app!');

}

4.3 深入探讨：要哈希什么？

正如我们前面讨论的，选择要哈希的文件区域是关键。

哈希整个文件： 最简单，但如果签名和公钥嵌入在文件中，会导致循环依赖。
哈希文件特定部分（排除签名块）： 这是我们目前采用的策略。通过在文件末尾附加一个可识别的签名块，并在计算哈希时将其排除，解决了循环依赖问题。这种方法相对健壮，因为它确保了应用程序的核心逻辑未被修改。
哈希关键代码/数据段： 最复杂，需要深入了解操作系统加载器如何处理 ELF/PE/Mach-O 文件，以及哪些内存区域包含可执行代码和只读数据。这通常需要使用 dart:ffi 调用 mmap 或 VirtualQuery 等 OS API 来精确识别和读取这些段。对于跨平台 Dart 应用程序来说，实现难度极高，且维护成本大。一般不推荐在应用层直接实现。

表格：不同哈希策略的对比

策略	优点	缺点	适用场景
整个文件哈希	实现最简单，无需特殊文件解析	如果签名/公钥嵌入，会造成循环依赖；无法区分核心代码与附加数据	签名/公钥在外部存储或硬编码（但哈希包含自身）
排除签名块哈希	解决循环依赖；相对简单易实现；保护核心代码	需要约定签名块格式和位置；需要文件解析逻辑	大多数需要运行时完整性检查的 Dart AOT 应用
哈希特定代码/数据段	精确保护核心逻辑；对文件格式变化更具弹性	实现极其复杂，依赖 OS 和文件格式细节；跨平台困难	对安全性要求极高，且有足够资源投入的特定平台应用

我们选择的“排除签名块哈希”策略在实现复杂度和安全性之间取得了良好的平衡，适合大多数 Dart AOT 应用程序。

第五部分：增强韧性与对抗篡改

仅仅进行一次启动时的完整性检查是不够的。高级攻击者可能会尝试绕过这些检查。

代码混淆：
Dart AOT 编译器在发布模式下会自动进行符号混淆，使得逆向工程更困难。但是，这通常不包括字符串字面量和反射信息。可以考虑使用第三方混淆工具。

dart compile exe bin/main.dart -o my_app --obfuscate

1

dart compile exe bin/main.dart -o my_app --obfuscate

反调试与反篡改技术 (FFI)：

检测调试器： 利用 dart:ffi 调用操作系统原生 API。
- Windows： IsDebuggerPresent 或 CheckRemoteDebuggerPresent。
- Linux： 检查 /proc/self/status 中的 TracerPid 字段。
- macOS： 调用 sysctl 或 ptrace。
内存完整性检查： 定期对关键代码段在内存中的哈希进行验证。这比文件哈希更复杂，因为代码段在内存中是可执行的，可能被动态链接器修改。
代码自校验： 在程序运行时，关键函数可以在执行前计算自身的哈希并与预存值比较。

示例 (Linux 反调试简略 FFI)：

lib/native_antidebug.dart

import 'dart:ffi';
import 'dart:io';
import 'package:ffi/ffi.dart';

// 定义 C 函数签名
typedef _IsDebuggerPresentC = Int32 Function();
typedef _IsDebuggerPresentDart = int Function();

// 加载 libc 库
final DynamicLibrary _libc = Platform.isLinux || Platform.isAndroid
    ? DynamicLibrary.open('libc.so.6')
    : (Platform.isMacOS
        ? DynamicLibrary.open('libc.dylib')
        : (Platform.isWindows
            ? DynamicLibrary.open('kernel32.dll') // Windows 示例
            : throw UnsupportedError('Unsupported platform')));

// 查找并绑定 C 函数 (这里以 Linux /proc/self/status 为例，非直接 C 函数)
// 实际的 IsDebuggerPresent 在 Windows 上是 Kernel32.dll
// 对于 Linux，通常通过解析 /proc/self/status 文件来判断 TracerPid
// 我们这里提供一个模拟的 FFI 结构，实际需要写一个 C helper lib

// 真正的 Linux 反调试需要通过 C 语言读取 /proc/self/status
// 例如：
// int is_debugger_present_linux() {
//     char buf[1024];
//     FILE *fp = fopen("/proc/self/status", "r");
//     if (fp == NULL) return 0;
//     while (fgets(buf, sizeof(buf), fp) != NULL) {
//         if (strncmp(buf, "TracerPid:", 10) == 0) {
//             int pid = atoi(buf + 11);
//             fclose(fp);
//             return pid != 0;
//         }
//     }
//     fclose(fp);
//     return 0;
// }

// Dart FFI 绑定到上述 C 函数
// 假设我们有一个 C 库 `libantidebug.so` 包含了 `is_debugger_present_linux`
// final DynamicLibrary _antiDebugLib = DynamicLibrary.open('libantidebug.so');
// final _isDebuggerPresent = _antiDebugLib.lookupFunction<_IsDebuggerPresentC, _IsDebuggerPresentDart>('is_debugger_present_linux');

class AntiTamper {
  static bool isDebuggerPresent() {
    if (Platform.isWindows) {
      // Windows: Call IsDebuggerPresent from kernel32.dll
      // final _isDebuggerPresentWindows = _libc.lookupFunction<_IsDebuggerPresentC, _IsDebuggerPresentDart>('IsDebuggerPresent');
      // return _isDebuggerPresentWindows() != 0;
      print('Windows 反调试检测未实现 FFI 绑定，模拟返回 false');
      return false; // 示例，实际需要 FFI 绑定
    } else if (Platform.isLinux || Platform.isAndroid || Platform.isMacOS) {
      // Linux/macOS: Read /proc/self/status (or equivalent)
      // For simplicity, directly read file here, but FFI to C is more robust
      try {
        final statusFile = File('/proc/self/status');
        if (statusFile.existsSync()) {
          final content = statusFile.readAsStringSync();
          final lines = content.split('n');
          for (final line in lines) {
            if (line.startsWith('TracerPid:')) {
              final pidStr = line.substring('TracerPid:'.length).trim();
              final pid = int.tryParse(pidStr);
              if (pid != null && pid != 0) {
                print('检测到调试器 (TracerPid: $pid)');
                return true;
              }
            }
          }
        }
      } catch (e) {
        print('读取 /proc/self/status 失败: $e');
      }
      return false;
    } else {
      print('当前平台不支持调试器检测。');
      return false;
    }
  }

  static void runAntiTamperChecks() {
    if (isDebuggerPresent()) {
      print('警告: 检测到调试器。应用程序将终止以保护完整性。');
      exit(1);
    }
    // 更多反篡改检查...
  }
}

import 'dart:ffi';

import 'dart:io';

import 'package:ffi/ffi.dart';

// 定义 C 函数签名

typedef _IsDebuggerPresentC = Int32 Function();

typedef _IsDebuggerPresentDart = int Function();

// 加载 libc 库

final DynamicLibrary _libc = Platform.isLinux || Platform.isAndroid

? DynamicLibrary.open('libc.so.6')

: (Platform.isMacOS

? DynamicLibrary.open('libc.dylib')

: (Platform.isWindows

? DynamicLibrary.open('kernel32.dll') // Windows 示例

: throw UnsupportedError('Unsupported platform')));

// 查找并绑定 C 函数 (这里以 Linux /proc/self/status 为例，非直接 C 函数)

// 实际的 IsDebuggerPresent 在 Windows 上是 Kernel32.dll

// 对于 Linux，通常通过解析 /proc/self/status 文件来判断 TracerPid

// 我们这里提供一个模拟的 FFI 结构，实际需要写一个 C helper lib

// 真正的 Linux 反调试需要通过 C 语言读取 /proc/self/status

// 例如：

// int is_debugger_present_linux() {

// char buf[1024];

// FILE *fp = fopen("/proc/self/status", "r");

// if (fp == NULL) return 0;

// while (fgets(buf, sizeof(buf), fp) != NULL) {

// if (strncmp(buf, "TracerPid:", 10) == 0) {

// int pid = atoi(buf + 11);

// fclose(fp);

// return pid != 0;

// }

// fclose(fp);

// return 0;

// }

// Dart FFI 绑定到上述 C 函数

// 假设我们有一个 C 库 `libantidebug.so` 包含了 `is_debugger_present_linux`

// final DynamicLibrary _antiDebugLib = DynamicLibrary.open('libantidebug.so');

// final _isDebuggerPresent = _antiDebugLib.lookupFunction<_IsDebuggerPresentC, _IsDebuggerPresentDart>('is_debugger_present_linux');

class AntiTamper {

static bool isDebuggerPresent() {

if (Platform.isWindows) {

// Windows: Call IsDebuggerPresent from kernel32.dll

// final _isDebuggerPresentWindows = _libc.lookupFunction<_IsDebuggerPresentC, _IsDebuggerPresentDart>('IsDebuggerPresent');

// return _isDebuggerPresentWindows() != 0;

print('Windows 反调试检测未实现 FFI 绑定，模拟返回 false');

return false; // 示例，实际需要 FFI 绑定

} else if (Platform.isLinux || Platform.isAndroid || Platform.isMacOS) {

// Linux/macOS: Read /proc/self/status (or equivalent)

// For simplicity, directly read file here, but FFI to C is more robust

try {

final statusFile = File('/proc/self/status');

if (statusFile.existsSync()) {

final content = statusFile.readAsStringSync();

final lines = content.split('n');

for (final line in lines) {

if (line.startsWith('TracerPid:')) {

final pidStr = line.substring('TracerPid:'.length).trim();

final pid = int.tryParse(pidStr);

if (pid != null && pid != 0) {

print('检测到调试器 (TracerPid: $pid)');

return true;

}

} catch (e) {

print('读取 /proc/self/status 失败: $e');

}

return false;

} else {

print('当前平台不支持调试器检测。');

return false;

}

static void runAntiTamperChecks() {

if (isDebuggerPresent()) {

print('警告: 检测到调试器。应用程序将终止以保护完整性。');

exit(1);

}

// 更多反篡改检查...

}

在 main.dart 中调用 AntiTamper.runAntiTamperChecks() 即可。

多点检查与冗余：
不要只在启动时检查一次。在应用程序的关键操作之前、定期（例如每隔几分钟）或在访问敏感数据时，都可以重新触发完整性检查。如果每次都进行完整的哈希计算，性能会是问题，可以考虑哈希更小的关键模块。
安全退出机制：
当检测到篡改时，程序应该以一种难以被攻击者拦截或绕过的方式终止。例如，不直接调用 exit(0) 或 exit(1)，而是触发一个硬件级别的重启，或者通过注入一个非法指令来导致程序崩溃（但这可能导致不友好的用户体验）。
密钥保护：
公钥虽然公开，但如果攻击者能够替换应用程序中的公钥，并用自己的私钥重新签名，那么整个机制就失效了。因此，公钥的存储和加载过程也需要尽可能地安全。
- 硬编码： 简单但容易被替换。
- 加密存储： 在运行时解密公钥，但密钥管理又成为新问题。
- 远程获取： 从受信任的服务器获取公钥，但需要安全通信通道。
- 硬件安全模块 (HSM) 或可信平台模块 (TPM)： 在嵌入式设备或某些服务器环境中，可以利用这些硬件来安全存储和使用密钥。

第六部分：限制、权衡与未来方向

6.1 固有局限性

没有绝对安全： 任何客户端侧的保护措施都可能被足够专业的攻击者绕过。攻击者拥有对执行环境的完全控制权，可以修改内存、替换文件、绕过 API 调用。
性能开销： 运行时哈希计算和签名验证会引入启动延迟。对于大型应用程序，这可能是一个显著的考虑因素。
复杂性： 跨平台实现文件解析、FFI 调用、反调试等技术会大大增加开发和维护的复杂性。
误报风险： 某些系统工具（如防病毒软件、系统更新）可能在不改变应用程序恶意性的情况下修改二进制文件，导致误报。

6.2 权衡与选择

在实际项目中，我们需要根据应用程序的敏感程度、目标用户群体、开发资源和性能要求来权衡这些因素。

对于大多数通用应用程序，我们实现的这种“排除签名块哈希”的启动时检查，结合 Dart 自身的混淆，已经能够提供一个不错的安全基线。
对于金融、游戏等高价值目标应用程序，可能需要投入更多资源，探索更深层次的反调试、内存保护和多点检查策略。

6.3 未来方向与高级安全机制

远程认证 (Remote Attestation)： 应用程序在启动时向远程服务器证明其自身的完整性。服务器验证成功后，才允许应用程序继续执行核心功能或提供敏感数据。这依赖于可信计算基 (TCB) 和安全通信。
可信平台模块 (TPM) / 安全启动 (Secure Boot)： 在硬件层面，TPM 和 UEFI Secure Boot 可以在操作系统启动前验证整个软件栈的完整性，从而为应用程序提供一个更可信的执行环境。
硬件安全模块 (HSM)： 对于私钥的存储和签名操作，HSM 提供了最高级别的物理和逻辑保护，防止私钥泄露。

结语

Dart AOT 二进制文件的运行时完整性检查是一项多层次、持续演进的工作。通过深入理解密码学原理，精心设计签名与验证架构，并结合适当的反篡改技术，我们能够显著提升 Dart 应用程序的安全性。但这并非一劳永逸，我们需要时刻警惕新的攻击手段，并不断迭代和完善我们的安全防御策略，以应对日益复杂的网络威胁。安全性始终是一个动态平衡的过程，需要开发者社区的共同努力和持续投入。

参考链接

Dart AOT 二进制文件的完整性检查：运行时的签名验证与篡改检测

逆向工程框架——Ghidra的简单使用

背景

Ghidra是由NSA开发的软件逆向工程（SRE）框架。它有助于分析恶意代码和病毒等恶意软件，并可以让网络安全专业人员更好地了解其网络和系统中的潜在漏洞。

美国国家安全局在2019年3月举行的2019年RSA会议上首次公开演示时，将Ghidra作为开放源代码发布给公众。

GitHub地址：

https://github.com/NationalSecurityAgency/ghidra.git

前置环境

宣称可以在以下三个环境运行（暂时支持64位的系统）

Microsoft Windows 7 or 10 (64-bit)
Linux(64-bit, CentOS 7 is preferred)
macOS (OS X) 10.8.3+ (Mountain Lion or later)

使用

创建项目

windows直接双击ghidraRun.bat打开（linux和mac可以执行ghidraRun脚本）

首先我们创建一个project（上图我是已经新建了一个叫做test的项目）

选择Non-Shared Project （另一个选择Shared Project是会在本地监听一个端口，方便分享）

接下来填好路径和项目名就可以了

反编译程序

导入要分析的二进制文件，都选择默认选项就行

之后你导入的二进制文件就会出现在project下面（我的项目名是test）

双击对应的文件即可开始分析该文件，下面以Reverse-org.exe为例，双击后选择分析

然后选择分析选项

那怎么找到main函数呢我们可以找到左边的functions，找到entry（当然有些程序直接有main，或者_start等关键字）

通过Filter搜索可以更快一点，双击即可再右边看到entry代码

查看反编译，对逆向熟悉的就知道下面这个就是main函数了

双击即可跳到面函数处，反编译窗口下拉即可看到main的代码

看函数的流程图可以点这个

最后说说现在想到的一些快捷键

g 跳到对应的地址
f 创建函数
; 添加注释
L 重命名变量名，函数名

总结

试了下，发现几点

可以对mips架构的程序进行反编译，这个比ida要好（官方说支持各种处理器指令集，试了下SPARC架构也可以，真牛逼！！！）
反编译的c++代码好像更加简洁
支持多平台，这个不错
更重要的，开源，免费

缺点：不熟悉操作，暂时感觉没有ida方便，没发现有调试功能

参考链接

ubuntu 22.04.3 执行更新报错 Segmentation fault (core dumped)

最近有台设备意外关机重启，经过磁盘文件损坏修复，可以成功进入系统。但是执行更新命令的时候报错 Segmentation fault (core dumped)，如下：

$ sudo apt-get update
命中:1 http://security.ubuntu.com/ubuntu noble-security InRelease            
命中:2 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble InRelease            
命中:3 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble-updates InRelease
命中:4 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble-backports InRelease
错误：已到超时限制
Segmentation fault (core dumped)
正在读取软件包列表... 完成
E: Problem executing scripts APT::Update::Post-Invoke-Success 'if /usr/bin/test -w /var/lib/command-not-found/ -a -e /usr/lib/cnf-update-db; then /usr/lib/cnf-update-db > /dev/null; fi'
E: Sub-process returned an error code

$ sudo apt-get update

命中:1 http://security.ubuntu.com/ubuntu noble-security InRelease

命中:2 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble InRelease

命中:3 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble-updates InRelease

命中:4 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble-backports InRelease

错误：已到超时限制

Segmentation fault (core dumped)

正在读取软件包列表... 完成

E: Problem executing scripts APT::Update::Post-Invoke-Success 'if /usr/bin/test -w /var/lib/command-not-found/ -a -e /usr/lib/cnf-update-db; then /usr/lib/cnf-update-db > /dev/null; fi'

E: Sub-process returned an error code

观察输出日志，锁定文件 /usr/lib/cnf-update-db，于是查看文件内容，发现是个 Python3 的脚本，里面的内容如下：

$ cat /usr/lib/cnf-update-db

#!/usr/bin/python3

import apt_pkg
import glob
import logging
import os
import sys

from CommandNotFound.db.creator import DbCreator
from CommandNotFound import CommandNotFound


if __name__ == "__main__":
    if "--debug" in sys.argv[1:]:
        logging.basicConfig(level=logging.DEBUG)
    elif "--verbose" in sys.argv[1:]:
        logging.basicConfig(level=logging.INFO)

    apt_pkg.init_config()
    db = CommandNotFound.dbpath
    if not os.access(os.path.dirname(db), os.W_OK):
        print("datbase directory %s not writable" % db)
        sys.exit(0)

    if apt_pkg.config.find_b("Acquire::IndexTargets::deb::CNF::DefaultEnabled", True):
        command_files = glob.glob("/var/lib/apt/lists/*Commands-*")
    else:
        command_files = glob.glob("/var/lib/apt/lists/*Contents*")
    if len(command_files) > 0:
        umask = os.umask(0o22)
        col = DbCreator(command_files)
        col.create(db)
        os.umask(umask)
    else:
        print("Could not find any command metadata")
        print("Please run 'apt update' before using this command.")

$ cat /usr/lib/cnf-update-db

#!/usr/bin/python3

import apt_pkg

import glob

import logging

import os

import sys

from CommandNotFound.db.creator import DbCreator

from CommandNotFound import CommandNotFound

if __name__ == "__main__":

if "--debug" in sys.argv[1:]:

logging.basicConfig(level=logging.DEBUG)

elif "--verbose" in sys.argv[1:]:

logging.basicConfig(level=logging.INFO)

apt_pkg.init_config()

db = CommandNotFound.dbpath

if not os.access(os.path.dirname(db), os.W_OK):

print("datbase directory %s not writable" % db)

sys.exit(0)

if apt_pkg.config.find_b("Acquire::IndexTargets::deb::CNF::DefaultEnabled", True):

command_files = glob.glob("/var/lib/apt/lists/*Commands-*")

else:

command_files = glob.glob("/var/lib/apt/lists/*Contents*")

if len(command_files) > 0:

umask = os.umask(0o22)

col = DbCreator(command_files)

col.create(db)

os.umask(umask)

else:

print("Could not find any command metadata")

print("Please run 'apt update' before using this command.")

于是逐行执行脚本，发现执行到 from CommandNotFound.db.creator import DbCreator 出现闪退。

观察系统日志：

$ sudo dmesg

...........................
[14247.387532] python3[36129]: segfault at 0 ip 000071a2374c10f0 sp 00007ffc59f80c28 error 6 in libsqlite3.so.0.8.6[71a23744b000+10b000] likely on CPU 1 (core 1, socket 0)

$ sudo dmesg

...........................

[14247.387532] python3[36129]: segfault at 0 ip 000071a2374c10f0 sp 00007ffc59f80c28 error 6 in libsqlite3.so.0.8.6[71a23744b000+10b000] likely on CPU 1 (core 1, socket 0)

从系统日志上可以看到 libsqlite3 调用的数据库出现异常了，要么是数据库出问题，要么安装包出问题。更高概率是某个数据库文件出现问题了，那到底是哪个数据库文件呢？

我们不妨卸载重装一下 command-not-found，如下：

$ sudo apt-get remove --purge command-not-found
正在读取软件包列表... 完成
正在分析软件包的依赖关系树... 完成
正在读取状态信息... 完成                 
下列软件包是自动安装的并且现在不需要了：
  python3-commandnotfound python3-gdbm
使用'sudo apt autoremove'来卸载它(它们)。
下列软件包将被【卸载】：
  command-not-found*
升级了 0 个软件包，新安装了 0 个软件包，要卸载 1 个软件包，有 0 个软件包未被升级。
解压缩后将会空出 29.7 kB 的空间。
您希望继续执行吗？ [Y/n] 
(正在读取数据库 ... 系统当前共安装有 228019 个文件和目录。)
正在卸载 command-not-found (23.04.0) ...
(正在读取数据库 ... 系统当前共安装有 228013 个文件和目录。)
正在清除 command-not-found (23.04.0) 的配置文件 ...
dpkg: 警告: 卸载 command-not-found 时，目录 /var/lib/command-not-found 非空，因而不会删除该目录
错误：已到超时限制

$ sudo apt-get remove --purge command-not-found

正在读取软件包列表... 完成

正在分析软件包的依赖关系树... 完成

正在读取状态信息... 完成

下列软件包是自动安装的并且现在不需要了：

python3-commandnotfound python3-gdbm

使用'sudo apt autoremove'来卸载它(它们)。

下列软件包将被【卸载】：

command-not-found*

升级了 0 个软件包，新安装了 0 个软件包，要卸载 1 个软件包，有 0 个软件包未被升级。

解压缩后将会空出 29.7 kB 的空间。

您希望继续执行吗？ [Y/n]

(正在读取数据库 ... 系统当前共安装有 228019 个文件和目录。)

正在卸载 command-not-found (23.04.0) ...

(正在读取数据库 ... 系统当前共安装有 228013 个文件和目录。)

正在清除 command-not-found (23.04.0) 的配置文件 ...

dpkg: 警告: 卸载 command-not-found 时，目录 /var/lib/command-not-found 非空，因而不会删除该目录

错误：已到超时限制

结果问题依旧，那么是不是 /var/lib/command-not-found 这个目录下的数据库导致的呢？我们观察数据库文件：

$ ls /var/lib/command-not-found
commands.db  commands.db.metadata

1 2	$ ls /var/lib/command-not-found commands.db commands.db.metadata

可以看到，这个目录下恰好有 libsqlite3 调用的数据库文件，我们删除这个目录，然后重启系统。

$ sudo apt-get reinstall command-not-found

$ sudo rm -rf /var/lib/command-not-found/*

$ sudo reboot

$ sudo apt-get reinstall command-not-found

$ sudo rm -rf /var/lib/command-not-found/*

$ sudo reboot

结果出乎意外的修复了这个问题。

参考链接

Ubuntu镜像源cn.arichinve.ubuntu.com自动跳转到清华镜像

Ubuntu 更新系统

$ sudo apt-get update

1	$ sudo apt-get update

在执行后，发现输出如下信息：

命中:1 http://security.ubuntu.com/ubuntu noble-security InRelease            
命中:2 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble InRelease            
命中:3 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble-updates InRelease
命中:4 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble-backports InRelease

命中:1 http://security.ubuntu.com/ubuntu noble-security InRelease

命中:2 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble InRelease

命中:3 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble-updates InRelease

命中:4 http://mirrors.tuna.tsinghua.edu.cn/ubuntu noble-backports InRelease

我明明记得源配置的是 cn.archive.ubuntu.com ，但是发现，系统更新时，自动去找了清华大学的Ubuntu源。

查看系统的 /etc/apt/sources.list 里面配置的也是 cn.archive.ubuntu.com 。

带着很多问号，在浏览器打开 https://cn.archive.ubuntu.com，发现网站已经自动跳转到清华镜像站了。

如果配置了防火墙过滤的场景需要特别注意这种情况。

参考链接

Ubuntu镜像源cn.arichinve.ubuntu.com不可用原因分析和解决

利用Flutter构建无界面交互的后台服务应用,涵盖Isolate并发编程、平台通道进阶使用、后台任务调度

1. 当Flutter遇见无界面服务

"那个开发跨平台UI的神器，居然能用来写后台服务？"这是我在2023年GitHub Trending上看到Flutter新增的后台执行功能时发出的惊叹。传统的Flutter开发总是与Material Design、Widget树等可视化元素紧密相连，但今天我们要探讨的是一个完全不同的维度——利用Flutter构建不需要任何用户界面的后台服务应用。

这种模式特别适合需要长期驻留的任务处理场景，比如数据同步、定时巡检、消息队列消费等。想象一下，你的手机应用在后台默默完成照片云端备份，或者智能家居网关持续处理传感器数据，这些都是无界面服务的典型应用场景。

2. 技术实现基础架构

2.1 Isolate的深度应用

// 后台数据处理服务示例（技术栈：Flutter 3.13/Dart 3.0）
import 'dart:isolate';

void backgroundService(SendPort mainSendPort) async {
  final receivePort = ReceivePort();
  mainSendPort.send(receivePort.sendPort);

  await for (final message in receivePort) {
    if (message == 'process_data') {
      // 模拟数据处理耗时操作
      final result = await _batchProcessData();
      mainSendPort.send(result);
    }
  }
}

Future<String> _batchProcessData() async {
  // 这里可以接入实际的数据处理逻辑
  await Future.delayed(Duration(seconds: 3));
  return 'Processed 500 records at ${DateTime.now()}';
}

// 主Isolate启动代码
void main() async {
  final mainReceivePort = ReceivePort();
  await Isolate.spawn(backgroundService, mainReceivePort.sendPort);
  
  final completer = Completer<SendPort>();
  mainReceivePort.listen((message) {
    if (message is SendPort) {
      completer.complete(message);
    } else {
      print('后台服务返回: $message');
    }
  });

  final serviceSendPort = await completer.future;
  serviceSendPort.send('process_data');
}

// 后台数据处理服务示例（技术栈：Flutter 3.13/Dart 3.0）

import 'dart:isolate';

void backgroundService(SendPort mainSendPort) async {

final receivePort = ReceivePort();

mainSendPort.send(receivePort.sendPort);

await for (final message in receivePort) {

if (message == 'process_data') {

// 模拟数据处理耗时操作

final result = await _batchProcessData();

mainSendPort.send(result);

}

Future<String> _batchProcessData() async {

// 这里可以接入实际的数据处理逻辑

await Future.delayed(Duration(seconds: 3));

return 'Processed 500 records at ${DateTime.now()}';

}

// 主Isolate启动代码

void main() async {

final mainReceivePort = ReceivePort();

await Isolate.spawn(backgroundService, mainReceivePort.sendPort);

final completer = Completer<SendPort>();

mainReceivePort.listen((message) {

if (message is SendPort) {

completer.complete(message);

} else {

print('后台服务返回: $message');

}

});

final serviceSendPort = await completer.future;

serviceSendPort.send('process_data');

}

这个示例展示了如何创建独立的Isolate进行后台数据处理。通过ReceivePort/SendPort实现进程间通信，主Isolate可以灵活控制后台任务。注意这里使用了Dart 3.0的增强型模式匹配语法，使得消息处理更加优雅。

2.2 后台服务生命周期管理

// 后台服务管理器示例
class BackgroundServiceManager {
  static final _instance = BackgroundServiceManager._internal();
  Isolate? _serviceIsolate;
  SendPort? _servicePort;

  factory BackgroundServiceManager() => _instance;

  BackgroundServiceManager._internal();

  Future<void> startService() async {
    if (_serviceIsolate != null) return;

    final receivePort = ReceivePort();
    _serviceIsolate = await Isolate.spawn(
      _serviceEntry,
      receivePort.sendPort,
      debugName: 'BackgroundService',
    );

    _servicePort = await receivePort.first;
  }

  static void _serviceEntry(SendPort sendPort) {
    final service = BackgroundServiceCore();
    final receivePort = ReceivePort();
    sendPort.send(receivePort.sendPort);

    receivePort.listen((message) {
      if (message == 'health_check') {
        sendPort.send(service.getHealthStatus());
      }
    });
  }
}

// 后台服务管理器示例

class BackgroundServiceManager {

static final _instance = BackgroundServiceManager._internal();

Isolate? _serviceIsolate;

SendPort? _servicePort;

factory BackgroundServiceManager() => _instance;

BackgroundServiceManager._internal();

Future<void> startService() async {

if (_serviceIsolate != null) return;

final receivePort = ReceivePort();

_serviceIsolate = await Isolate.spawn(

_serviceEntry,

receivePort.sendPort,

debugName: 'BackgroundService',

);

_servicePort = await receivePort.first;

}

static void _serviceEntry(SendPort sendPort) {

final service = BackgroundServiceCore();

final receivePort = ReceivePort();

sendPort.send(receivePort.sendPort);

receivePort.listen((message) {

if (message == 'health_check') {

sendPort.send(service.getHealthStatus());

}

});

}

这个管理器类实现了服务的单例管理、健康检查等核心功能。通过隔离的构造函数参数控制，确保后台服务的稳定运行。特别要注意Isolate的异常捕获机制，建议在实战中增加错误处理回调。

3. 关键技术深度解析

3.1 平台通道的进阶使用

// Android后台服务绑定示例（需配合Kotlin实现）
const _channel = MethodChannel('com.example/background');

Future<void> startAndroidForegroundService() async {
  try {
    await _channel.invokeMethod('startForegroundService', {
      'title': '数据同步服务',
      'content': '正在同步用户数据...',
      'icon': 'ic_stat_sync',
    });
  } on PlatformException catch (e) {
    print('服务启动失败: ${e.message}');
  }
}

// Android后台服务绑定示例（需配合Kotlin实现）

const _channel = MethodChannel('com.example/background');

Future<void> startAndroidForegroundService() async {

try {

await _channel.invokeMethod('startForegroundService', {

'title': '数据同步服务',

'content': '正在同步用户数据...',

'icon': 'ic_stat_sync',

});

} on PlatformException catch (e) {

print('服务启动失败: ${e.message}');

}

在Android端需要实现Foreground Service时，可以通过平台通道调用原生API。这里演示了如何启动前台服务并传递通知参数，注意不同Android版本的后台限制差异，建议结合WorkManager实现兼容方案。

3.2 后台任务调度策略

// 智能任务调度器实现
class TaskScheduler {
  final _tasks = PriorityQueue<TaskItem>();
  Timer? _schedulerTimer;

  void scheduleTask(TaskItem task) {
    _tasks.add(task);
    _scheduleNext();
  }

  void _scheduleNext() {
    if (_tasks.isEmpty) return;
    
    final nextTask = _tasks.first;
    final now = DateTime.now();
    final delay = nextTask.scheduleTime.difference(now);

    _schedulerTimer?.cancel();
    _schedulerTimer = Timer(delay, () {
      _executeTask(nextTask);
      _tasks.remove(nextTask);
      _scheduleNext();
    });
  }

  void _executeTask(TaskItem task) {
    Isolate.run(() => task.execute());
  }
}

// 智能任务调度器实现

class TaskScheduler {

final _tasks = PriorityQueue<TaskItem>();

Timer? _schedulerTimer;

void scheduleTask(TaskItem task) {

_tasks.add(task);

_scheduleNext();

}

void _scheduleNext() {

if (_tasks.isEmpty) return;

final nextTask = _tasks.first;

final now = DateTime.now();

final delay = nextTask.scheduleTime.difference(now);

_schedulerTimer?.cancel();

_schedulerTimer = Timer(delay, () {

_executeTask(nextTask);

_tasks.remove(nextTask);

_scheduleNext();

});

}

void _executeTask(TaskItem task) {

Isolate.run(() => task.execute());

}

这个任务调度器实现了优先级队列管理和智能延迟执行，通过Isolate.run简化了并发任务处理。在真实场景中，需要结合设备状态（网络、电量等）动态调整执行策略。

4. 典型应用场景剖析

某电商应用的实践案例：他们的价格监控服务需要每小时抓取30个竞品网站的价格数据。传统方案使用服务器端执行，但遇到动态反爬机制时效果不佳。改用Flutter无界面服务后：

利用设备分散执行降低IP封锁风险
客户端直接处理数据减少服务器压力
离线时自动缓存任务，网络恢复后批量提交
用户隐私数据全程不离开设备

实测结果显示数据采集成功率从68%提升至92%，服务器成本降低40%。这个案例充分体现了客户端计算的优势。

5. 技术方案优劣评估

优势维度：

开发效率：复用现有Flutter代码库
跨平台一致性：一套代码覆盖Android/iOS
资源利用：客户端计算减轻服务器负担
隐私安全：敏感数据无需离开用户设备

挑战要点：

后台执行时间限制（iOS严格限制30秒）
设备资源的不确定性（电量、网络波动）
调试复杂度高于传统服务端开发
平台政策风险（后台服务滥用可能导致应用下架）

某金融App的教训：他们在Android端过度使用后台定位服务，导致应用被Google Play临时下架。这提示我们需要合理设计后台服务的触发频率和资源占用。

6. 开发注意事项清单

电量优化策略：使用Android的JobScheduler或iOS的BGTaskScheduler
内存警戒线：Android后台进程建议不超过40MB内存占用
平台政策红线：仔细阅读Apple的《App Store审核指南》第4章
异常熔断机制：连续失败3次的任务应进入休眠状态
本地化存储规范：使用Isolate的专用存储空间避免并发冲突
跨版本兼容方案：为Android 12+的精确闹钟权限准备降级方案

某智能家居App的实践：他们为后台服务设计了三级降级策略（立即执行->等待充电->WiFi环境），使设备指令送达率从79%提升至98%。

7. 未来演进方向

Google正在推进的Flutter Background Isolate框架值得关注，该方案将提供：

统一的任务队列管理
跨平台的后台唤醒机制
智能资源调度接口
增强型调试工具链

早期测试显示，新框架可使后台服务的启动时间缩短60%，内存占用降低35%。建议保持对Flutter Dev Channel更新的关注，及时获取最新特性。

参考链接

利用Flutter构建无界面交互的后台服务应用,涵盖Isolate并发编程、平台通道进阶使用、后台任务调度

openKylin v2.0 SP2默认模式不能安装软件包的问题

最近在尝试使用国产的 openKylin ，结果在安装软件包的时候报错"当前模式禁止执行（unpack）操作"，如下图：

继续阅读openKylin v2.0 SP2默认模式不能安装软件包的问题

鸿蒙Flutter开发中集成Webview

主要有两种方案

使用第三方库

使用 flutter_inappwebview 插件，在 pubspec.yaml 文件中配置：

dependencies:

  # 鸿蒙OS
  path_provider_ohos:
    git:
      url: https://gitcode.com/openharmony-tpc/flutter_packages.git
      path: packages/path_provider/path_provider_ohos
  url_launcher_ohos:
    git:
      url: https://gitcode.com/openharmony-tpc/flutter_packages.git
      path: packages/url_launcher/url_launcher_ohos

  ## 支持鸿蒙的WebView, 6.x版本开始支持Windows系统
  flutter_inappwebview:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      ref: br_v6.1.5_ohos
      path: flutter_inappwebview

dependency_overrides:
  # 支持鸿蒙的WebView, 6.x版本开始支持Windows系统
  flutter_inappwebview_platform_interface:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      ref: br_v6.1.5_ohos
      path: flutter_inappwebview_platform_interface
  flutter_inappwebview_android:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      ref: br_v6.1.5_ohos
      path: flutter_inappwebview_android
  flutter_inappwebview_ios:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      ref: br_v6.1.5_ohos
      path: flutter_inappwebview_ios
  flutter_inappwebview_macos:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      ref: br_v6.1.5_ohos
      path: flutter_inappwebview_macos
  flutter_inappwebview_web:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      ref: br_v6.1.5_ohos
      path: flutter_inappwebview_web
  flutter_inappwebview_windows:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      ref: br_v6.1.5_ohos
      path: flutter_inappwebview_windows
  flutter_inappwebview_ohos:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      ref: br_v6.1.5_ohos
      path: flutter_inappwebview_ohos

dependencies:

# 鸿蒙OS

path_provider_ohos:

git:

url: https://gitcode.com/openharmony-tpc/flutter_packages.git

path: packages/path_provider/path_provider_ohos

url_launcher_ohos:

git:

url: https://gitcode.com/openharmony-tpc/flutter_packages.git

path: packages/url_launcher/url_launcher_ohos

## 支持鸿蒙的WebView, 6.x版本开始支持Windows系统

flutter_inappwebview:

git:

url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git

ref: br_v6.1.5_ohos

path: flutter_inappwebview

dependency_overrides:

# 支持鸿蒙的WebView, 6.x版本开始支持Windows系统

flutter_inappwebview_platform_interface:

git:

url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git

ref: br_v6.1.5_ohos

path: flutter_inappwebview_platform_interface

flutter_inappwebview_android:

git:

url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git

ref: br_v6.1.5_ohos

path: flutter_inappwebview_android

flutter_inappwebview_ios:

git:

url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git

ref: br_v6.1.5_ohos

path: flutter_inappwebview_ios

flutter_inappwebview_macos:

git:

url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git

ref: br_v6.1.5_ohos

path: flutter_inappwebview_macos

flutter_inappwebview_web:

git:

url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git

ref: br_v6.1.5_ohos

path: flutter_inappwebview_web

flutter_inappwebview_windows:

git:

url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git

ref: br_v6.1.5_ohos

path: flutter_inappwebview_windows

flutter_inappwebview_ohos:

git:

url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git

ref: br_v6.1.5_ohos

path: flutter_inappwebview_ohos

或者使用 fluttertpc_flutter_webview_plugin 插件，在 pubspec.yaml 文件中配置：

dependencies:
  flutter_webview_plugin:
   git:
     url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_webview_plugin
  
  flutter_webview_plugin_ohos:
    git:
      url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_webview_plugin
      path: ohos

dependencies:

flutter_webview_plugin:

git:

url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_webview_plugin

flutter_webview_plugin_ohos:

git:

url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_webview_plugin

path: ohos

编写原生 ArkTS 代码实现 PlatformView

创建 entryablitiy

在 src/main/module.json5 中配置 ablitiy

    "abilities": [
      {
   
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
   
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ],
        "orientation": "landscape"
      }
    ],

"abilities": [

{

"name": "EntryAbility",

"srcEntry": "./ets/entryability/EntryAbility.ets",

"description": "$string:EntryAbility_desc",

"icon": "$media:icon",

"label": "$string:EntryAbility_label",

"startWindowIcon": "$media:icon",

"startWindowBackground": "$color:start_window_background",

"exported": true,

"skills": [

{

"entities": [

"entity.system.home"

"actions": [

"action.system.home"

]

}

"orientation": "landscape"

}

cat src/main/entryablity/CustomFactory.ets

import { BinaryMessenger } from '@ohos/flutter_ohos/src/main/ets/plugin/common/BinaryMessenger';
import MessageCodec from '@ohos/flutter_ohos/src/main/ets/plugin/common/MessageCodec';
import PlatformViewFactory from '@ohos/flutter_ohos/src/main/ets/plugin/platform/PlatformViewFactory';
import { CustomView } from './CustomView';
import common from '@ohos.app.ability.common';
import PlatformView from '@ohos/flutter_ohos/src/main/ets/plugin/platform/PlatformView';

export class CustomFactory extends PlatformViewFactory {
  message: BinaryMessenger;

  constructor(message: BinaryMessenger, createArgsCodes: MessageCodec<Object>) {
    super(createArgsCodes);
    this.message = message;
  }

  public create(context: common.Context, viewId: number, args: Object): PlatformView {
    return new CustomView(context, viewId, args, this.message);
  }
}

import { BinaryMessenger } from '@ohos/flutter_ohos/src/main/ets/plugin/common/BinaryMessenger';

import MessageCodec from '@ohos/flutter_ohos/src/main/ets/plugin/common/MessageCodec';

import PlatformViewFactory from '@ohos/flutter_ohos/src/main/ets/plugin/platform/PlatformViewFactory';

import { CustomView } from './CustomView';

import common from '@ohos.app.ability.common';

import PlatformView from '@ohos/flutter_ohos/src/main/ets/plugin/platform/PlatformView';

export class CustomFactory extends PlatformViewFactory {

message: BinaryMessenger;

constructor(message: BinaryMessenger, createArgsCodes: MessageCodec<Object>) {

super(createArgsCodes);

this.message = message;

}

public create(context: common.Context, viewId: number, args: Object): PlatformView {

return new CustomView(context, viewId, args, this.message);

}

cat src/main/entryablity/CustomPlugin.ets

import  { FlutterPlugin,
  FlutterPluginBinding } from '@ohos/flutter_ohos/src/main/ets/embedding/engine/plugins/FlutterPlugin';
import StandardMessageCodec from '@ohos/flutter_ohos/src/main/ets/plugin/common/StandardMessageCodec';
import { CustomFactory } from './CustomFactory';

export class CustomPlugin implements FlutterPlugin {
  getUniqueClassName(): string {
    return 'CustomPlugin';
  }

  onAttachedToEngine(binding: FlutterPluginBinding): void {
    binding.getPlatformViewRegistry()?.
    registerViewFactory('com.rex.custom.ohos/customView', new CustomFactory(binding.getBinaryMessenger(), StandardMessageCodec.INSTANCE));
  }

  onDetachedFromEngine(binding: FlutterPluginBinding): void {}
}

import { FlutterPlugin,

FlutterPluginBinding } from '@ohos/flutter_ohos/src/main/ets/embedding/engine/plugins/FlutterPlugin';

import StandardMessageCodec from '@ohos/flutter_ohos/src/main/ets/plugin/common/StandardMessageCodec';

import { CustomFactory } from './CustomFactory';

export class CustomPlugin implements FlutterPlugin {

getUniqueClassName(): string {

return 'CustomPlugin';

}

onAttachedToEngine(binding: FlutterPluginBinding): void {

binding.getPlatformViewRegistry()?.

registerViewFactory('com.rex.custom.ohos/customView', new CustomFactory(binding.getBinaryMessenger(), StandardMessageCodec.INSTANCE));

}

onDetachedFromEngine(binding: FlutterPluginBinding): void {}

}

cat src/main/entryablity/CustomView.ets

import MethodChannel, {
  MethodCallHandler,
  MethodResult
} from '@ohos/flutter_ohos/src/main/ets/plugin/common/MethodChannel';
import PlatformView, { Params } from '@ohos/flutter_ohos/src/main/ets/plugin/platform/PlatformView';
import common from '@ohos.app.ability.common';
import { BinaryMessenger } from '@ohos/flutter_ohos/src/main/ets/plugin/common/BinaryMessenger';
import StandardMethodCodec from '@ohos/flutter_ohos/src/main/ets/plugin/common/StandardMethodCodec';
import MethodCall from '@ohos/flutter_ohos/src/main/ets/plugin/common/MethodCall';
import { webview } from '@kit.ArkWeb';

@Component
struct ButtonComponent {
  @Prop params: Params
  customView: CustomView = this.params.platformView as CustomView
  @StorageLink('numValue') storageLink: string = "first"
  @State bkColor: Color = Color.Red

  private webviewController: WebviewController = new webview.WebviewController()

  build() {
    Web({src: 'https://bing.com', controller: this.webviewController})
      .domStorageAccess(true)
      .fileAccess(true)
      .mixedMode(MixedMode.All)
      .databaseAccess(true)
      .userAgent("Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36")
  }
}

@Builder
function ButtonBuilder(params: Params) {
  ButtonComponent({ params: params })
    .backgroundColor(Color.Transparent)
}

AppStorage.setOrCreate('numValue', 'test')

@Observed
export class CustomView extends PlatformView implements MethodCallHandler {
  numValue: string = "test";

  methodChannel: MethodChannel;
  index: number = 1;

  constructor(context: common.Context, viewId: number, args: ESObject, message: BinaryMessenger) {
    super();
    // 注册消息通道
    this.methodChannel = new MethodChannel(message, `com.rex.custom.ohos/customView${viewId}`, StandardMethodCodec.INSTANCE);
    this.methodChannel.setMethodCallHandler(this);
  }

  onMethodCall(call: MethodCall, result: MethodResult): void {
    // 接受Dart侧发来的消息
    let method: string = call.method;
    let link1: SubscribedAbstractProperty<number> = AppStorage.link('numValue');
    switch (method) {
      case 'getMessageFromFlutterView':
        let value: ESObject = call.args;
        this.numValue = value;
        link1.set(value)
        console.log("nodeController receive message from dart: " + this.numValue);
        result.success(true);
        break;
    }
  }

  public sendMessage = () => {
    console.log("nodeController sendMessage")
    //向Dart侧发送消息
    this.methodChannel.invokeMethod('getMessageFromOhosView', 'natvie - ' + this.index++);
  }

  getView(): WrappedBuilder<[Params]> {
    return new WrappedBuilder(ButtonBuilder);
  }

  dispose(): void {
  }
}

import MethodChannel, {

MethodCallHandler,

MethodResult

} from '@ohos/flutter_ohos/src/main/ets/plugin/common/MethodChannel';

import PlatformView, { Params } from '@ohos/flutter_ohos/src/main/ets/plugin/platform/PlatformView';

import common from '@ohos.app.ability.common';

import { BinaryMessenger } from '@ohos/flutter_ohos/src/main/ets/plugin/common/BinaryMessenger';

import StandardMethodCodec from '@ohos/flutter_ohos/src/main/ets/plugin/common/StandardMethodCodec';

import MethodCall from '@ohos/flutter_ohos/src/main/ets/plugin/common/MethodCall';

import { webview } from '@kit.ArkWeb';

@Component

struct ButtonComponent {

@Prop params: Params

customView: CustomView = this.params.platformView as CustomView

@StorageLink('numValue') storageLink: string = "first"

@State bkColor: Color = Color.Red

private webviewController: WebviewController = new webview.WebviewController()

build() {

Web({src: 'https://bing.com', controller: this.webviewController})

.domStorageAccess(true)

.fileAccess(true)

.mixedMode(MixedMode.All)

.databaseAccess(true)

.userAgent("Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36")

}

@Builder

function ButtonBuilder(params: Params) {

ButtonComponent({ params: params })

.backgroundColor(Color.Transparent)

}

AppStorage.setOrCreate('numValue', 'test')

@Observed

export class CustomView extends PlatformView implements MethodCallHandler {

numValue: string = "test";

methodChannel: MethodChannel;

index: number = 1;

constructor(context: common.Context, viewId: number, args: ESObject, message: BinaryMessenger) {

super();

// 注册消息通道

this.methodChannel = new MethodChannel(message, `com.rex.custom.ohos/customView${viewId}`, StandardMethodCodec.INSTANCE);

this.methodChannel.setMethodCallHandler(this);

}

onMethodCall(call: MethodCall, result: MethodResult): void {

// 接受Dart侧发来的消息

let method: string = call.method;

let link1: SubscribedAbstractProperty<number> = AppStorage.link('numValue');

switch (method) {

case 'getMessageFromFlutterView':

let value: ESObject = call.args;

this.numValue = value;

link1.set(value)

console.log("nodeController receive message from dart: " + this.numValue);

result.success(true);

break;

}

public sendMessage = () => {

console.log("nodeController sendMessage")

//向Dart侧发送消息

this.methodChannel.invokeMethod('getMessageFromOhosView', 'natvie - ' + this.index++);

}

getView(): WrappedBuilder<[Params]> {

return new WrappedBuilder(ButtonBuilder);

}

dispose(): void {

}

cat src/main/entryablity/EntryAbility.ets

import { FlutterAbility, FlutterEngine } from '@ohos/flutter_ohos';
import { GeneratedPluginRegistrant } from '../plugins/GeneratedPluginRegistrant';
import { CustomPlugin } from './CustomPlugin';

export default class EntryAbility extends FlutterAbility {
  configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)
    GeneratedPluginRegistrant.registerWith(flutterEngine)
    this.addPlugin(new CustomPlugin())
  }
}

import { FlutterAbility, FlutterEngine } from '@ohos/flutter_ohos';

import { GeneratedPluginRegistrant } from '../plugins/GeneratedPluginRegistrant';

import { CustomPlugin } from './CustomPlugin';

export default class EntryAbility extends FlutterAbility {

configureFlutterEngine(flutterEngine: FlutterEngine) {

super.configureFlutterEngine(flutterEngine)

GeneratedPluginRegistrant.registerWith(flutterEngine)

this.addPlugin(new CustomPlugin())

}

创建 pages

cat src/main/ets/pages/index.ets

import common from '@ohos.app.ability.common';
import { FlutterPage } from '@ohos/flutter_ohos'

let storage = LocalStorage.getShared()
const EVENT_BACK_PRESS = 'EVENT_BACK_PRESS'

@Entry(storage)
@Component
struct Index {
  private context = getContext(this) as common.UIAbilityContext
  @LocalStorageLink('viewId') viewId: string = "";

  build() {
    Column() {
      FlutterPage({ viewId: this.viewId })
    }
  }

  onBackPress(): boolean {
    this.context.eventHub.emit(EVENT_BACK_PRESS)
    return true
  }
}

import common from '@ohos.app.ability.common';

import { FlutterPage } from '@ohos/flutter_ohos'

let storage = LocalStorage.getShared()

const EVENT_BACK_PRESS = 'EVENT_BACK_PRESS'

@Entry(storage)

@Component

struct Index {

private context = getContext(this) as common.UIAbilityContext

@LocalStorageLink('viewId') viewId: string = "";

build() {

Column() {

FlutterPage({ viewId: this.viewId })

}

onBackPress(): boolean {

this.context.eventHub.emit(EVENT_BACK_PRESS)

return true

}

在 src/main/resources/base/profile/main_page.json 中配置路由

{
   
  "src": [
    "pages/Index"
  ]
}

{

"src": [

"pages/Index"

]

}

在 Dart 侧调用该 PlatformView

Scaffold(
  appBar: AppBar(title: Text('code')),
  body: OhosView(
  viewType: 'com.rex.custom.ohos/customView',
  // onPlatformViewCreated: _onPlatformViewCreated,
  creationParams: const <String, dynamic>{
   'initParams': 'hello world'},
  creationParamsCodec: const StandardMessageCodec(),
)

Scaffold(

appBar: AppBar(title: Text('code')),

body: OhosView(

viewType: 'com.rex.custom.ohos/customView',

// onPlatformViewCreated: _onPlatformViewCreated,

creationParams: const <String, dynamic>{

'initParams': 'hello world'},

creationParamsCodec: const StandardMessageCodec(),

)

参考链接

鸿蒙Flutter实战：03-鸿蒙Flutter开发中集成Webview

当笔记本电脑盖子关闭时如何禁用指纹认证(ubuntu 24.04)？

To disable fingerprint authentication when the laptop lid is closed, and re-enable when it is reopened, we will use acpid to bind to the button/lid.* event to a custom script that will stop and mask the fprintd service on lid close, and unmask and start the fprintd service on lid open.

We also check that the HDMI cable is connected by testing the contents of /sys/class/drm/card1-HDMI-A-1/status.

Follow the steps below: (ThinkPad T440 ubunu 24.04)

Create file /etc/acpi/laptop-lid.sh with the following contents:

$ sudo install acpid

$ sudo mkdir /etc/acpi

$ sudo install vim

$ sudo vim /etc/acpi/laptop-lid.sh

$ sudo install acpid

$ sudo mkdir /etc/acpi

$ sudo install vim

$ sudo vim /etc/acpi/laptop-lid.sh

#!/bin/bash

lock=$HOME/.fprint-disabled

if grep -Fq closed /proc/acpi/button/lid/LID/state &&
   grep -Fxq connected /sys/class/drm/card1-HDMI-A-1/status
then
  touch "$lock"
  systemctl mask fprintd
  systemctl stop fprintd
elif [ -f "$lock" ]
then
  systemctl unmask fprintd
  systemctl start fprintd
  rm "$lock"
fi

#!/bin/bash

lock=$HOME/.fprint-disabled

if grep -Fq closed /proc/acpi/button/lid/LID/state &&

grep -Fxq connected /sys/class/drm/card1-HDMI-A-1/status

then

touch "$lock"

systemctl mask fprintd

systemctl stop fprintd

elif [ -f "$lock" ]

then

systemctl unmask fprintd

systemctl start fprintd

rm "$lock"

Make the file executable with

$ sudo chmod +x /etc/acpi/laptop-lid.sh

1

$ sudo chmod +x /etc/acpi/laptop-lid.sh
Create file /etc/acpi/events/laptop-lid with the following contents:

$ sudo mkdir /etc/acpi/events

1

$ sudo mkdir /etc/acpi/events

event=button/lid.* action=/etc/acpi/laptop-lid.sh

1
2

event=button/lid.*
action=/etc/acpi/laptop-lid.sh
Restart the acpid service with:

$ sudo service acpid restart

1

$ sudo service acpid restart

Now the fingerprint will be used only when the lid is open.

In order to restore the correct state of the fprintd service if you disconnect/reconnect while the laptop is off, you may call the above script from a systemd init file. The steps to do this are the following:

Create a file named /etc/systemd/system/laptop-lid.service with the following contents:

[Unit]
Description=Laptop Lid
After=suspend.target

[Service]
ExecStart=/etc/acpi/laptop-lid.sh

[Install]
WantedBy=multi-user.target
WantedBy=suspend.target

[Unit]

Description=Laptop Lid

After=suspend.target

[Service]

ExecStart=/etc/acpi/laptop-lid.sh

[Install]

WantedBy=multi-user.target

WantedBy=suspend.target

Reload the systemd config files with

$ sudo systemctl daemon-reload

1

$ sudo systemctl daemon-reload
Start the service with

$ sudo systemctl start laptop-lid.service

1

$ sudo systemctl start laptop-lid.service
Enable the service so that it starts automatically on boot

$ sudo systemctl enable laptop-lid.service

1

$ sudo systemctl enable laptop-lid.service

Now the status should be correct even after connecting/disconnecting when the computer is off.

References used for creating the code in the answer:

参考链接

从零学习大模型（4）——Transformer 的 “内部齿轮”：FFN、残差连接与归一化如何让 AI 更聪明？

如果把 Transformer 比作一台精密的机器，那么注意力机制是它的 “核心引擎”，而前馈神经网络（FFN）、残差连接（Residual Connection）和归一化（Normalization）就是让引擎高效运转的 “内部齿轮”。这些模块看似简单，却解决了深度学习的两大核心难题 —— 特征提取能力不足和训练不稳定性，是大语言模型能 “理解语言、生成文本” 的关键支撑。

前馈神经网络（FFN）：给注意力结果 “加工提纯”

注意力机制能捕捉词与词的关联（如 “它” 指代 “狗”），但输出的特征向量还需进一步 “加工” 才能被模型有效利用。前馈神经网络（FFN）的作用，就是对注意力的输出进行非线性转换和特征提纯 —— 就像厨师把新鲜食材（注意力结果）做成美味菜肴（可用特征）。

FFN 的核心结构：两层线性变换 + 激活函数

Transformer 中的 FFN 结构非常简洁，通常由两步处理组成。

第一步是线性变换（Linear1），将输入向量从高维压缩到更高维（如从 512 维升到 2048 维）。这一步的作用是 “扩展特征空间”—— 就像用更高分辨率的镜头观察物体，能捕捉更多细节（如 “狗” 不仅有 “动物” 特征，还有 “哺乳动物”“宠物” 等细分特征）。之后经过激活函数（如 ReLU）引入非线性转换，线性变换只能学习简单关系（如 “狗→动物”），而非线性变换能学习复杂关联（如 “狗→宠物→需要喂食”）。

第二步是另一个线性变换（Linear2），将高维向量压缩回原维度（如从 2048 维降回 512 维），这一步是 “特征聚合”—— 把扩展出的细节特征重新整合，形成更精炼的表示。

以 “猫追狗，它跑得很快” 为例，注意力机制已计算出 “它” 与 “狗” 的关联，输出包含关联信息的向量；FFN 通过线性变换扩展特征（如 “狗” 的 “奔跑能力”“被追状态” 等细节），再通过激活函数强化关键特征（如 “奔跑能力”），最后压缩为更有效的向量。

为什么 FFN 是注意力的 “最佳搭档”？

注意力机制擅长 “捕捉关联”，但缺乏 “特征转换” 能力 —— 它输出的向量本质是 “关联加权求和”，特征表达较为粗糙。而 FFN 的优势正在于 “提纯特征”：增强非线性，让模型能学习复杂语义（如隐喻、逻辑推理）；聚焦关键特征，通过维度扩展和压缩，强化重要特征（如 “跑” 与 “狗” 的关联），弱化噪声；补充局部特征，注意力关注全局关联，FFN 则可捕捉局部特征（如 “跑得很快” 中 “跑” 与 “快” 的搭配）。形象说：注意力是 “侦察兵”（找到相关信息），FFN 是 “分析师”（提炼有用信息）。

激活函数：给 FFN 注入 “非线性能力”

激活函数是 FFN 的 “灵魂”—— 没有它，FFN 就退化为线性变换（两层线性变换等价于一层），无法学习复杂特征。ReLU（Rectified Linear Unit）是 Transformer 原始论文的选择，公式为 ReLU (x) = max (0, x)（负数输出 0，正数直接输出），它的优势是计算简单，解决了早期 “Sigmoid 梯度消失” 问题，但存在 “死亡 ReLU” 问题（输入为负时神经元永久失效）。

GELU（Gaussian Error Linear Unit）是 BERT、GPT 等模型的改进选择，公式近似为 0.5x (1 + tanh (√(2/π)(x + 0.044715x³)))，它比 ReLU 更平滑（不会突然输出 0），能保留更多中间特征（如 “跑” 的强度不同时，输出有细微差异），适合需要精细特征的模型（如 BERT 的文本理解、GPT 的生成）。

SwiGLU（Swish-Gated Linear Unit）是大模型（如 LLaMA、GPT-4）的主流选择，公式为 SwiGLU (x) = Swish (x) × Linear (x)（Swish 是带参数的 Sigmoid，这里用线性变换模拟 “门控”），它通过 “门控机制” 动态筛选特征（如 “激活” 有用特征，“抑制” 无关特征），比 GELU 更灵活，在 100 亿参数以上的大模型中，能显著提升生成连贯性和推理能力。

激活函数的选择遵循 “模型越大，越需要灵活激活” 的规律：小模型用 ReLU 足够高效，大模型则需 SwiGLU 的精细调控。

残差连接：让模型 “深而不垮” 的 “桥梁设计”

在深度学习中，模型深度（层数）是提升性能的关键 —— 但传统网络超过一定层数后，会出现 “梯度消失”（训练时参数难以更新）和 “性能下降”（层数增加，精度反而降低）。残差连接（Residual Connection）的发明，彻底解决了这个问题，让 Transformer 能堆叠数十甚至上百层。

核心原理：“跳过连接” 传递原始信息

残差连接的结构极其简单：将模块的输入与输出相加。例如在注意力模块中，输出等于注意力计算结果加上原始输入。这种 “跳过连接” 的作用，可通过一个比喻理解：传统网络中，信息像 “接力赛”—— 每一层必须完美传递信息，否则后面就会 “断档”；残差连接中，信息像 “双车道”—— 一条道是模块处理（如注意力），另一条道是原始信息直接传递。即使模块处理有损失，原始信息仍能通过 “直通道” 到达深层。

为什么残差连接能解决 “梯度消失”？

训练模型时，参数更新依赖 “梯度”（损失对参数的导数）。

传统网络中，梯度需要逐层传递，层数越多，梯度衰减越严重（就像声音在长管道中逐渐减弱）。而残差连接让梯度有了 “捷径”：损失对输入 x 的梯度等于损失对模块输出的梯度加上 1（直接从输出 = 模块输出 + 输入的关系推导）。这意味着梯度不会衰减到 0（至少有 “1” 的基础），深层参数也能有效更新。例如，训练一个 100 层的 Transformer，没有残差连接时，第 100 层的梯度可能衰减到接近 0，参数几乎不更新；有残差连接时，梯度通过 “输出 + 输入” 的路径，能稳定传递到第 1 层，所有层参数都能正常更新。

归一化：让训练 “稳如泰山” 的 “校准工具”

深度学习中，输入向量的数值范围可能剧烈波动（如有的词向量值在 0-1，有的在 100-200）。这种 “数值不稳定” 会导致训练震荡（损失忽高忽低），甚至无法收敛。归一化（Normalization）的作用，就是将向量标准化到固定范围（如均值 0、方差 1），就像给数据 “校准”—— 让模型处理的始终是 “符合预期” 的输入。

Transformer 中最常用的归一化方法是层归一化（Layer Norm，LN），但也有 BN（Batch Norm）、RMSNorm 等变体。理解它们的区别，就能明白为什么 LN 成为 NLP 的主流选择。

LN 与 BN：归一化的 “两种思路”

LN 和 BN 的核心目标相同（标准化数值），但归一化的 “范围” 不同。层归一化（LN）是对单样本内的所有特征进行归一化（如一个句子的 512 维向量），计算方式是对每个样本，计算自身特征的均值和方差。批归一化（BN）则是对批次内的所有样本的同一特征维度进行归一化（如 32 个句子的同一特征维度），计算方式是对每个特征维度，计算批次内所有样本的均值和方差。

为什么文本用 LN，图像用 BN？文本的 “批次一致性” 差：同一批次中，句子长度、语义差异大（如有的是新闻，有的是诗歌），BN 的 “批次均值” 没有意义；而 LN 基于单样本归一化，不受批次影响。图像的 “特征一致性” 强：同一批次的图像（如猫的图片）在同一像素位置（如边缘特征）的数值分布相似，BN 能有效利用这种一致性。

在 Transformer 中，LN 通常紧跟残差连接，形成 “残差 – 归一化” 组合（如输出等于 LN（注意力输出 + 输入））。这种组合既能标准化数值，又能通过残差保留原始信息。

预归一化（Pre-Norm）与后归一化（Post-Norm）：归一化的 “时机选择”

在 Transformer 层中，归一化可以放在模块（注意力或 FFN）之前（Pre-Norm）或之后（Post-Norm），这两种设计对训练稳定性影响很大。Post-Norm（后归一化）是原始 Transformer 的选择，流程是先做模块计算和残差，再进行归一化。这种方式存在问题：模块计算可能导致数值剧烈波动（如注意力的点积可能很大），残差相加后再归一化，仍可能出现训练不稳定（尤其是深层模型）。

Pre-Norm（预归一化）是现代大模型（如 GPT、LLaMA）的选择，流程是先对输入归一化，再做模块计算和残差。这种方式的优势在于：归一化后输入更稳定（均值 0、方差 1），模块计算不易出现数值爆炸，训练更稳定，且能支持更深的层数（如 100 层以上）。实际效果显示，Post-Norm 在 12 层以内表现正常，超过 24 层训练损失容易震荡；而 Pre-Norm 即使堆叠 100 层，损失仍能平稳下降。这也是大模型普遍采用 Pre-Norm 的核心原因。

归一化的 “轻量化” 变体：RMSNorm 与 ScaleNorm

LN 虽稳定，但计算均值和方差的开销较高。研究者们提出了更高效的变体。RMSNorm（Root Mean Square Layer Normalization）是 LLaMA、GPT-3 等模型的选择，它去掉均值计算，只通过 “均方根” 标准化，计算量比 LN 减少 20%（无需减均值），且在语言模型中性能接近 LN。其原理是文本特征的均值通常接近 0（因词向量训练时已中心化），去掉均值对结果影响小。

ScaleNorm 是进一步简化的变体，通过向量的 L2 范数进行标准化，计算更简单（无需统计方差），适合资源受限的场景。但它对输入分布较敏感，在小模型中表现较好。

这些变体的核心思路是：在保证稳定性的前提下，减少计算开销 —— 对大模型而言，每一层的效率提升都会累积成显著优势。

各模块的协同作用：Transformer 的 “流水线设计”

FFN、残差连接、归一化不是孤立存在的，它们在 Transformer 层中形成 “流水线”，共同完成特征处理。

以编码器层为例，完整流程如下：首先接收前一层输出的特征向量作为输入；接着进行预归一化，得到标准化的输入向量（先归一化，保证输入稳定）；然后通过多头注意力模块计算注意力输出（注意力捕捉关联）；之后进行残差连接，将注意力输出与原始输入相加（保留原始信息，避免特征丢失）；再次进行预归一化，为 FFN 提供稳定输入；FFN 处理通过 SwiGLU 激活函数和线性变换提纯特征；最后进行最终残差连接，输出整合了注意力和 FFN 的特征。

这个流程的精妙之处在于：归一化确保每一步输入稳定，避免数值波动；残差连接让信息 “有退路”，深层也能有效传递；FFN 则在稳定的基础上，持续提纯特征。就像工厂流水线：归一化是 “质检校准”，残差连接是 “备用通道”，FFN 是 “精加工”—— 三者协同，让 Transformer 能稳定高效地学习语言规律。

不同模型的模块选择：效率与性能的平衡

模型对 FFN、残差、归一化的选择，体现了 “任务需求 – 模型大小 – 计算资源” 的平衡。GPT-4 等大模型选择 SwiGLU 作为 FFN 激活函数，RMSNorm 作为归一化方式，采用 Pre-Norm 连接设计。因为大模型需精细特征和稳定性，SwiGLU 提升表达，RMSNorm 高效，Pre-Norm 支持深层。

LLaMA 2 等开源模型同样选择 SwiGLU、RMSNorm 和 Pre-Norm，开源模型需兼顾性能与效率，RMSNorm 减少计算，适合部署。BERT 等专注理解任务的模型使用 GELU 激活函数，采用 LN 归一化和改进版 Pre-Norm 连接设计，理解任务需平滑特征，GELU 比 ReLU 更精细，LN 稳定性足够。

轻量模型（如 MobileBERT）则选择 ReLU 作为激活函数，ScaleNorm 作为归一化方式，采用 Pre-Norm 连接设计，移动端需极致效率，ReLU 和 ScaleNorm 计算量最小。

结语：细节决定性能的 “深度学习哲学”

FFN、残差连接、归一化这些模块，看似是 “辅助组件”，却决定了 Transformer 能走多深、跑多快。它们的演进印证了深度学习的一个核心哲学：大模型的能力不仅来自 “规模”（参数和数据），更来自 “细节设计”—— 如何让每一层更稳定，让每一次计算更有效。

从 ReLU 到 SwiGLU，从 Post-Norm 到 Pre-Norm，从 LN 到 RMSNorm，这些微小的改进累积起来，让模型从 “能训练 12 层” 到 “能训练 100 层”，从 “生成生硬文本” 到 “写出流畅文章”。未来，随着模型规模继续扩大，这些 “内部齿轮” 的优化仍将是关键 —— 毕竟，能支撑起千亿参数的，从来不是 “宏大架构”，而是每一个精密的细节。

当我们惊叹于 AI 的语言能力时，或许该记住：让它 “聪明” 的，不仅是注意力机制的 “聚焦”，还有这些模块在背后默默的 “加工、传递与校准”。

参考链接

从零学习大模型（4）——Transformer 的 “内部齿轮”：FFN、残差连接与归一化如何让 AI 更聪明？

llama2.c 源码阅读

1. 概述

前OpenAI著名工程师Andrej Kapathy开源了llama2.c项目，该项目是llama2模型推理代码的C语言实现，用大概970行C代码实现了LLama2模型的推理算法。整个项目代码简洁高效，值得深度阅读。对掌握大模型推理算法的细节有极大的帮助。

2. 源码阅读

2.1 基础算法

RMS归一化公式是：

$$ o_i = w_i \times x_i \times \frac {1}{\sqrt{\frac{1}{n}\sum_{j=0}^{n-1} x_j^2 + \epsilon}} $$

其中，$\epsilon$ 为防止分母为0的数值。还有RMS因子是对x的归一化，w变量是gain变量，重新缩放标准化后的输入向量。

// ----------------------------------------------------------------------------
// neural net blocks; the dynamics of the Transformer
void rmsnorm(float* o, float* x, float* weight, int size) {
    // calculate sum of squares
    float ss = 0.0f;
    for (int j = 0; j < size; j++) {
        ss += x[j] * x[j];
    }
    ss /= size;
    ss += 1e-5f;
    ss = 1.0f / sqrtf(ss);
    // normalize and scale
    for (int j = 0; j < size; j++) {
        o[j] = weight[j] * (ss * x[j]);
    }
}

// ----------------------------------------------------------------------------

// neural net blocks; the dynamics of the Transformer

void rmsnorm(float* o, float* x, float* weight, int size) {

// calculate sum of squares

float ss = 0.0f;

for (int j = 0; j < size; j++) {

ss += x[j] * x[j];

}

ss /= size;

ss += 1e-5f;

ss = 1.0f / sqrtf(ss);

// normalize and scale

for (int j = 0; j < size; j++) {

o[j] = weight[j] * (ss * x[j]);

}

softmax函数公式是：

$$ o_i = \frac {e^{x_i-x_{max}}}{\sum_{j=0}^{n-1} e^{x_j-x_{max}}} $$

代码如下，注释说的很清楚，减去最大值是为了防止数值溢出，数值更稳定。通过简单数学变换可以得知，最终结果不变。

void softmax(float* x, int size) {
    // find max value (for numerical stability)
    float max_val = x[0];
    for (int i = 1; i < size; i++) {
        if (x[i] > max_val) {
            max_val = x[i];
        }
    }
    // exp and sum
    float sum = 0.0f;
    for (int i = 0; i < size; i++) {
        x[i] = expf(x[i] - max_val);
        sum += x[i];
    }
    // normalize
    for (int i = 0; i < size; i++) {
        x[i] /= sum;
    }
}

void softmax(float* x, int size) {

// find max value (for numerical stability)

float max_val = x[0];

for (int i = 1; i < size; i++) {

if (x[i] > max_val) {

max_val = x[i];

}

// exp and sum

float sum = 0.0f;

for (int i = 0; i < size; i++) {

x[i] = expf(x[i] - max_val);

sum += x[i];

}

// normalize

for (int i = 0; i < size; i++) {

x[i] /= sum;

}

W (d,n) @ x (n,) -> xout (d,)的矩阵乘法，采用naive的矩阵乘法，即外层循环是行，内层循环是列。代码如下：

void matmul(float* xout, float* x, float* w, int n, int d) {
    // W (d,n) @ x (n,) -> xout (d,)
    // by far the most amount of time is spent inside this little function
    int i;
    #pragma omp parallel for private(i)
    for (i = 0; i < d; i++) {
        float val = 0.0f;
        for (int j = 0; j < n; j++) {
            val += w[i * n + j] * x[j];
        }
        xout[i] = val;
    }
}

void matmul(float* xout, float* x, float* w, int n, int d) {

// W (d,n) @ x (n,) -> xout (d,)

// by far the most amount of time is spent inside this little function

int i;

#pragma omp parallel for private(i)

for (i = 0; i < d; i++) {

float val = 0.0f;

for (int j = 0; j < n; j++) {

val += w[i * n + j] * x[j];

}

xout[i] = val;

}

2.2. forward计算

模型中一个attention block的计算如下图所示：

项目代码是按照每一个token来计算QKV的，其中参数dim是transformer的向量维度。l是layer序号。

第一步是rmsnorm，即归一化。输入是x (d,)，rms权重向量是w->rms_att_weight + l*dim，计算结果输出到s->xb (d,)中。

// attention rmsnorm
rmsnorm(s->xb, x, w->rms_att_weight + l*dim, dim);

1 2	// attention rmsnorm rmsnorm(s->xb, x, w->rms_att_weight + l*dim, dim);

第二步是QKV的矩阵乘法，注意kv_dim和dim的区别，是为了同时兼容multi head attention和grouped query attention两种算法。如下图所示：

kv_dim是key和value的总维度，dim是transformer的向量总维度。在multi head attention中，kv_dim = dim。在grouped query attention中，kv_dim = dim * n_kv_heads / n_heads。以图中为例，n_kv_heads = 4, n_heads = 8，则kv_dim = dim / 2。

对于各矩阵的维度，以及在MHA、GQA等算法中的关系，参考下图：

Q、K、V三个向量计算的详细代码如下，即Wq(d,d) @ xb(d,) -> q(d,)，Wk(dkv,d) @ xb(d,) -> k(dkv,), Wv(dkv,d) @ xb(d,) -> v(dkv,)

// key and value point to the kv cache
int loff = l * p->seq_len * kv_dim; // kv cache layer offset for convenience
s->k = s->key_cache + loff + pos * kv_dim;
s->v = s->value_cache + loff + pos * kv_dim;

// qkv matmuls for this position
matmul(s->q, s->xb, w->wq + l*dim*dim, dim, dim);
matmul(s->k, s->xb, w->wk + l*dim*kv_dim, dim, kv_dim);
matmul(s->v, s->xb, w->wv + l*dim*kv_dim, dim, kv_dim);

// key and value point to the kv cache

int loff = l * p->seq_len * kv_dim; // kv cache layer offset for convenience

s->k = s->key_cache + loff + pos * kv_dim;

s->v = s->value_cache + loff + pos * kv_dim;

// qkv matmuls for this position

matmul(s->q, s->xb, w->wq + l*dim*dim, dim, dim);

matmul(s->k, s->xb, w->wk + l*dim*kv_dim, dim, kv_dim);

matmul(s->v, s->xb, w->wv + l*dim*kv_dim, dim, kv_dim);

接下来需要给Q和K向量添加RoPE位置编码，按照如下公式计算，其中m就是当前token的序号pos。需要注意的是，llama模型是给每一层的Q和K向量都添加这个编码。

$$ \begin{aligned} \theta_i &= \frac{1}{10000^{2i/hs}}= 10000^{-2i/hs} \\ Q(i) &=Q(i)\cos (m\theta_i) - Q(i+1)\sin(m\theta_i)\\ Q(i+1) &=Q(i)\sin (m \theta_i) + Q(i+1)\cos(m\theta_i)\\ K(i) &=K(i)\cos (m \theta_i) - K(i+1)\sin(m\theta_i)\\ K(i+1) &=K(i)\sin (m \theta_i) + K(i+1)\cos(m\theta_i)\\ \end{aligned} $$

详细代码如下，注意在GQA中，K的向量长度小于Q的向量长度，所以在i < kv_dim时，计算Q和K的向量。在i >= kv_dim时，只计算Q的向量。

// RoPE relative positional encoding: complex-valued rotate q and k in each head
for (int i = 0; i < dim; i+=2) {
    int head_dim = i % head_size;
    float freq = 1.0f / powf(10000.0f, head_dim / (float)head_size);
    float val = pos * freq;
    float fcr = cosf(val);
    float fci = sinf(val);
    int rotn = i < kv_dim ? 2 : 1; // how many vectors? 2 = q & k, 1 = q only
    for (int v = 0; v < rotn; v++) {
        float* vec = v == 0 ? s->q : s->k; // the vector to rotate (query or key)
        float v0 = vec[i];
        float v1 = vec[i+1];
        vec[i]   = v0 * fcr - v1 * fci;
        vec[i+1] = v0 * fci + v1 * fcr;
    }
}

// RoPE relative positional encoding: complex-valued rotate q and k in each head

for (int i = 0; i < dim; i+=2) {

int head_dim = i % head_size;

float freq = 1.0f / powf(10000.0f, head_dim / (float)head_size);

float val = pos * freq;

float fcr = cosf(val);

float fci = sinf(val);

int rotn = i < kv_dim ? 2 : 1; // how many vectors? 2 = q & k, 1 = q only

for (int v = 0; v < rotn; v++) {

float* vec = v == 0 ? s->q : s->k; // the vector to rotate (query or key)

float v0 = vec[i];

float v1 = vec[i+1];

vec[i] = v0 * fcr - v1 * fci;

vec[i+1] = v0 * fci + v1 * fcr;

}

接下来针对每个头，计算attention score。attention score的计算公式如下：

$$ score(i) = softmax(\frac{ Q_i K^T}{\sqrt{d}})V , \quad Q_i \in \R^{1 \times d},K \in \R^{n\times d},V\in\R^{n\times d} $$

具体计算的时候，先遍历每个head，在每个head中，先计算Qi和K的点积，然后除以sqrt(d)，得到att (1,n)向量，最后softmax得到attention score。

在GQA中，由于分组共享了Q和K的向量，在计算attention score的时候，需要把Q和K的向量“展开”还原为(n,d)的矩阵，具体做法是通过h / kv_mul，保证 kv_mul个Q和K向量共享一个权重。

然后计算attention score (1,n)和V (n,d)的乘积，得到xb (1,d)。这个计算并不是完全按照普通矩阵乘来计算的，而是把每个位置的attention score和V的每一行相乘，然后累加到xb中。这样计算的好处是对cache更加友好，是一种常见的矩阵乘算法。

对于每个头，每个token的attention score计算过程的可视化如图所示：

图中可以清楚看出，每个token都计算了一遍和其他token的相关度，再进行加权求和得到最终的attention score。

具体代码如下：

for (h = 0; h < p->n_heads; h++) {
    // get the query vector for this head
    float* q = s->q + h * head_size;
    // attention scores for this head
    float* att = s->att + h * p->seq_len;
    // iterate over all timesteps, including the current one
    for (int t = 0; t <= pos; t++) {
        // get the key vector for this head and at this timestep
        float* k = s->key_cache + loff + t * kv_dim + (h / kv_mul) * head_size;
        // calculate the attention score as the dot product of q and k
        float score = 0.0f;
        for (int i = 0; i < head_size; i++) {
            score += q[i] * k[i];
        }
        score /= sqrtf(head_size);
        // save the score to the attention buffer
        att[t] = score;
    }

    // softmax the scores to get attention weights, from 0..pos inclusively
    softmax(att, pos + 1);

    // weighted sum of the values, store back into xb
    float* xb = s->xb + h * head_size;
    memset(xb, 0, head_size * sizeof(float));
    for (int t = 0; t <= pos; t++) {
        // get the value vector for this head and at this timestep
        float* v = s->value_cache + loff + t * kv_dim + (h / kv_mul) * head_size;
        // get the attention weight for this timestep
        float a = att[t];
        // accumulate the weighted value into xb
        for (int i = 0; i < head_size; i++) {
            xb[i] += a * v[i];
        }
    }
}

for (h = 0; h < p->n_heads; h++) {

// get the query vector for this head

float* q = s->q + h * head_size;

// attention scores for this head

float* att = s->att + h * p->seq_len;

// iterate over all timesteps, including the current one

for (int t = 0; t <= pos; t++) {

// get the key vector for this head and at this timestep

float* k = s->key_cache + loff + t * kv_dim + (h / kv_mul) * head_size;

// calculate the attention score as the dot product of q and k

float score = 0.0f;

for (int i = 0; i < head_size; i++) {

score += q[i] * k[i];

}

score /= sqrtf(head_size);

// save the score to the attention buffer

att[t] = score;

}

// softmax the scores to get attention weights, from 0..pos inclusively

softmax(att, pos + 1);

// weighted sum of the values, store back into xb

float* xb = s->xb + h * head_size;

memset(xb, 0, head_size * sizeof(float));

for (int t = 0; t <= pos; t++) {

// get the value vector for this head and at this timestep

float* v = s->value_cache + loff + t * kv_dim + (h / kv_mul) * head_size;

// get the attention weight for this timestep

float a = att[t];

// accumulate the weighted value into xb

for (int i = 0; i < head_size; i++) {

xb[i] += a * v[i];

}

从代码中也能看出，为什么需要把K和V的矩阵进行cache。因为对于一个位置的token而言，Q矩阵每次参与计算的只有当前位置的一行，而K和V矩阵，则是每行都需要参与计算。最终得到的也是该位置的(1,d)向量作为attention score。因此，为了减少计算量，把K和V矩阵进行cache也是理所当然。

接下来的计算就非常简单，注释也非常直观。详细步骤如下：

计算Wo (d,d) @ xb^T (d,)得到xb2 (d,)
通过残差连接，叠加x (d,)向量：x += xb2
x再经过一个RMSNorm(x)，得到xb (d,)
计算hb和hb2：W1(hd, d) @ xb (d,) -> hb1(hd,) , W3(hd, d) @ xb (d,) -> hb2(hd, )
hb经过silu非线性激活函数变换，计算方式为：$$silu(hb) = hb (1/ (1 + e^{-hb}))$$
然后计算逐位相乘 hb * hb2, 得到hb (hd,)
计算W2(d, hd) @ hb (hd,) -> xb (d,)
最终再通过残差连接，叠加xb向量：x += xb

// final matmul to get the output of the attention
matmul(s->xb2, s->xb, w->wo + l*dim*dim, dim, dim);

// residual connection back into x
for (int i = 0; i < dim; i++) {
    x[i] += s->xb2[i];
}

// ffn rmsnorm
rmsnorm(s->xb, x, w->rms_ffn_weight + l*dim, dim);

// Now for FFN in PyTorch we have: self.w2(F.silu(self.w1(x)) * self.w3(x))
// first calculate self.w1(x) and self.w3(x)
matmul(s->hb, s->xb, w->w1 + l*dim*hidden_dim, dim, hidden_dim);
matmul(s->hb2, s->xb, w->w3 + l*dim*hidden_dim, dim, hidden_dim);

// SwiGLU non-linearity
for (int i = 0; i < hidden_dim; i++) {
    float val = s->hb[i];
    // silu(x)=x*σ(x), where σ(x) is the logistic sigmoid
    val *= (1.0f / (1.0f + expf(-val)));
    // elementwise multiply with w3(x)
    val *= s->hb2[i];
    s->hb[i] = val;
}

// final matmul to get the output of the ffn
matmul(s->xb, s->hb, w->w2 + l*dim*hidden_dim, hidden_dim, dim);

// residual connection
for (int i = 0; i < dim; i++) {
    x[i] += s->xb[i];
}

// final matmul to get the output of the attention

matmul(s->xb2, s->xb, w->wo + l*dim*dim, dim, dim);

// residual connection back into x

for (int i = 0; i < dim; i++) {

x[i] += s->xb2[i];

}

// ffn rmsnorm

rmsnorm(s->xb, x, w->rms_ffn_weight + l*dim, dim);

// Now for FFN in PyTorch we have: self.w2(F.silu(self.w1(x)) * self.w3(x))

// first calculate self.w1(x) and self.w3(x)

matmul(s->hb, s->xb, w->w1 + l*dim*hidden_dim, dim, hidden_dim);

matmul(s->hb2, s->xb, w->w3 + l*dim*hidden_dim, dim, hidden_dim);

// SwiGLU non-linearity

for (int i = 0; i < hidden_dim; i++) {

float val = s->hb[i];

// silu(x)=x*σ(x), where σ(x) is the logistic sigmoid

val *= (1.0f / (1.0f + expf(-val)));

// elementwise multiply with w3(x)

val *= s->hb2[i];

s->hb[i] = val;

}

// final matmul to get the output of the ffn

matmul(s->xb, s->hb, w->w2 + l*dim*hidden_dim, hidden_dim, dim);

// residual connection

for (int i = 0; i < dim; i++) {

x[i] += s->xb[i];

}

继续每一层的计算，每一层的输入都是x，输出也是x，循环计算。在每一层都算完以后，最后再计算：

RMSNorm(x)，把x向量进行归一化。
计算Wc(dvoc, d) @ x (d,) -> logits (dvoc,)，其中dvoc为词典大小。

至此，最终得到的logits就是该位置的在token词典中的分类概率。

// final rmsnorm
rmsnorm(x, x, w->rms_final_weight, dim);

// classifier into logits
matmul(s->logits, x, w->wcls, p->dim, p->vocab_size);
return s->logits;

// final rmsnorm

rmsnorm(x, x, w->rms_final_weight, dim);

// classifier into logits

matmul(s->logits, x, w->wcls, p->dim, p->vocab_size);

return s->logits;

2.3 抽样方法

拿到logits之后，需要通过抽样来最终确定输出哪个token，常见的抽样方法有greedy(argmax)，随机抽样，以及top-p (nucleus) 抽样。

2.3.1 Greedy Sampling

Greedy Sampling是直接选择概率最大的token作为输出。代码简单直观，如下：

int sample_argmax(float* probabilities, int n) {
    // return the index that has the highest probability
    int max_i = 0;
    float max_p = probabilities[0];
    for (int i = 1; i < n; i++) {
        if (probabilities[i] > max_p) {
            max_i = i;
            max_p = probabilities[i];
        }
    }
    return max_i;
}

int sample_argmax(float* probabilities, int n) {

// return the index that has the highest probability

int max_i = 0;

float max_p = probabilities[0];

for (int i = 1; i < n; i++) {

if (probabilities[i] > max_p) {

max_i = i;

max_p = probabilities[i];

}

return max_i;

}

2.3.2 Random Sampling

Random Sampling是随机选择一个token作为输出。代码也很简单，如下：

int sample_mult(float* probabilities, int n, float coin) {
    // sample index from probabilities (they must sum to 1!)
    // coin is a random number in [0, 1), usually from random_f32()
    float cdf = 0.0f;
    for (int i = 0; i < n; i++) {
        cdf += probabilities[i];
        if (coin < cdf) {
            return i;
        }
    }
    return n - 1; // in case of rounding errors
}

int sample_mult(float* probabilities, int n, float coin) {

// sample index from probabilities (they must sum to 1!)

// coin is a random number in [0, 1), usually from random_f32()

float cdf = 0.0f;

for (int i = 0; i < n; i++) {

cdf += probabilities[i];

if (coin < cdf) {

return i;

}

return n - 1; // in case of rounding errors

}

2.3.3 Top-p (Nucleus) Sampling

Top-p (Nucleus) Sampling是随机选择概率大于某个阈值的token作为输出。代码也很简单，如下：

int sample_topp(float* probabilities, int n, float topp, ProbIndex* probindex, float coin) {
    // top-p sampling (or "nucleus sampling") samples from the smallest set of
    // tokens that exceed probability topp. This way we never sample tokens that
    // have very low probabilities and are less likely to go "off the rails".
    // coin is a random number in [0, 1), usually from random_f32()

    int n0 = 0;
    // quicksort indices in descending order of probabilities
    // values smaller than (1 - topp) / (n - 1) cannot be part of the result
    // so for efficiency we crop these out as candidates before sorting
    const float cutoff = (1.0f - topp) / (n - 1);
    for (int i = 0; i < n; i++) {
        if (probabilities[i] >= cutoff) {
            probindex[n0].index = i;
            probindex[n0].prob = probabilities[i];
            n0++;
        }
    }
    qsort(probindex, n0, sizeof(ProbIndex), compare);

    // truncate the list where cumulative probability exceeds topp
    float cumulative_prob = 0.0f;
    int last_idx = n0 - 1; // in case of rounding errors consider all elements
    for (int i = 0; i < n0; i++) {
        cumulative_prob += probindex[i].prob;
        if (cumulative_prob > topp) {
            last_idx = i;
            break; // we've exceeded topp by including last_idx
        }
    }

    // sample from the truncated list
    float r = coin * cumulative_prob;
    float cdf = 0.0f;
    for (int i = 0; i <= last_idx; i++) {
        cdf += probindex[i].prob;
        if (r < cdf) {
            return probindex[i].index;
        }
    }
    return probindex[last_idx].index; // in case of rounding errors
}

int sample_topp(float* probabilities, int n, float topp, ProbIndex* probindex, float coin) {

// top-p sampling (or "nucleus sampling") samples from the smallest set of

// tokens that exceed probability topp. This way we never sample tokens that

// have very low probabilities and are less likely to go "off the rails".

// coin is a random number in [0, 1), usually from random_f32()

int n0 = 0;

// quicksort indices in descending order of probabilities

// values smaller than (1 - topp) / (n - 1) cannot be part of the result

// so for efficiency we crop these out as candidates before sorting

const float cutoff = (1.0f - topp) / (n - 1);

for (int i = 0; i < n; i++) {

if (probabilities[i] >= cutoff) {

probindex[n0].index = i;

probindex[n0].prob = probabilities[i];

n0++;

}

qsort(probindex, n0, sizeof(ProbIndex), compare);

// truncate the list where cumulative probability exceeds topp

float cumulative_prob = 0.0f;

int last_idx = n0 - 1; // in case of rounding errors consider all elements

for (int i = 0; i < n0; i++) {

cumulative_prob += probindex[i].prob;

if (cumulative_prob > topp) {

last_idx = i;

break; // we've exceeded topp by including last_idx

}

// sample from the truncated list

float r = coin * cumulative_prob;

float cdf = 0.0f;

for (int i = 0; i <= last_idx; i++) {

cdf += probindex[i].prob;

if (r < cdf) {

return probindex[i].index;

}

return probindex[last_idx].index; // in case of rounding errors

}

2.3.4 选择抽样策略

具体执行抽样前，需要做一些变换，比如：

除以temperature，用来调整概率分布，温度越高，概率分布越平滑
计算softmax(logits)，得到概率分布代码如下所示：

// apply the temperature to the logits
for (int q=0; q<sampler->vocab_size; q++) { logits[q] /= sampler->temperature; }
// apply softmax to the logits to get the probabilities for next token
softmax(logits, sampler->vocab_size);

// apply the temperature to the logits

for (int q=0; q<sampler->vocab_size; q++) { logits[q] /= sampler->temperature; }

// apply softmax to the logits to get the probabilities for next token

softmax(logits, sampler->vocab_size);

然后根据不同的采样策略，选择不同的采样函数。

2.4 encode和decode

2.4.1 encode

encode函数将输入文本转化为token id序列。token id为int类型，长度为max_len。encode算法非常直观，先是在tokenize词典中查询每个UTF-8字符。如果找不到，则将文本编码为byte fallback。注意每个UTF-8字符长度是1到3个字节之间，需要针对UTF-8编码的规范进行判断。

代码如下：

// process the raw (UTF-8) byte sequence of the input string
for (char *c = text; *c != '\0'; c++) {

    // reset buffer if the current byte is ASCII or a leading byte
    // 0xC0 is 11000000, so (*c & 0xC0) keeps the first 2 bits and zeros the rest
    // 0x80 is 10000000
    // in UTF-8, all continuation bytes start with "10" in first two bits
    // so in English this is: "if this byte is not a continuation byte"
    if ((*c & 0xC0) != 0x80) {
        // this byte must be either a leading byte (11...) or an ASCII char (0x...)
        // => reset our location, as we're starting a new UTF-8 codepoint
        str_len = 0;
    }

    // append the current byte to the buffer
    str_buffer[str_len++] = *c; // ++ is post-increment, incremented after this line
    str_buffer[str_len] = '\0';

    // while the next character is a continuation byte, continue appending
    // but if there are too many of them, just stop to avoid overruning str_buffer size.
    if ((*(c+1) & 0xC0) == 0x80 && str_len < 4) {
        continue;
    }

    // ok c+1 is not a continuation byte, so we've read in a full codepoint
    int id = str_lookup(str_buffer, t->sorted_vocab, t->vocab_size);

    if (id != -1) {
        // we found this codepoint in vocab, add it as a token
        tokens[(*n_tokens)++] = id;
    } else {
        // byte_fallback encoding: just encode each byte as a token
        // +3 is here because the first 3 vocab elements are <unk>, <s>, </s>
        // so the individual bytes only start at index 3
        for (int i=0; i < str_len; i++) {
            tokens[(*n_tokens)++] = (unsigned char)str_buffer[i] + 3;
        }
    }
    str_len = 0; // protect against a sequence of stray UTF8 continuation bytes
}

// process the raw (UTF-8) byte sequence of the input string

for (char *c = text; *c != '\0'; c++) {

// reset buffer if the current byte is ASCII or a leading byte

// 0xC0 is 11000000, so (*c & 0xC0) keeps the first 2 bits and zeros the rest

// 0x80 is 10000000

// in UTF-8, all continuation bytes start with "10" in first two bits

// so in English this is: "if this byte is not a continuation byte"

if ((*c & 0xC0) != 0x80) {

// this byte must be either a leading byte (11...) or an ASCII char (0x...)

// => reset our location, as we're starting a new UTF-8 codepoint

str_len = 0;

}

// append the current byte to the buffer

str_buffer[str_len++] = *c; // ++ is post-increment, incremented after this line

str_buffer[str_len] = '\0';

// while the next character is a continuation byte, continue appending

// but if there are too many of them, just stop to avoid overruning str_buffer size.

if ((*(c+1) & 0xC0) == 0x80 && str_len < 4) {

continue;

}

// ok c+1 is not a continuation byte, so we've read in a full codepoint

int id = str_lookup(str_buffer, t->sorted_vocab, t->vocab_size);

if (id != -1) {

// we found this codepoint in vocab, add it as a token

tokens[(*n_tokens)++] = id;

} else {

// byte_fallback encoding: just encode each byte as a token

// +3 is here because the first 3 vocab elements are <unk>, <s>, </s>

// so the individual bytes only start at index 3

for (int i=0; i < str_len; i++) {

tokens[(*n_tokens)++] = (unsigned char)str_buffer[i] + 3;

}

str_len = 0; // protect against a sequence of stray UTF8 continuation bytes

}

其次，尝试合并临近的字符，并查询tokenize词典，如果存在，则将临近的token缩对应的字符串合并为一个token。并反复迭代，直到找不到相邻的两个token可以合并为一个token为止。代码也很直观，如下：

// merge the best consecutive pair each iteration, according the scores in vocab_scores
while (1) {
    float best_score = -1e10;
    int best_id = -1;
    int best_idx = -1;

    for (int i=0; i < (*n_tokens-1); i++) {
        // check if we can merge the pair (tokens[i], tokens[i+1])
        sprintf(str_buffer, "%s%s", t->vocab[tokens[i]], t->vocab[tokens[i+1]]);
        int id = str_lookup(str_buffer, t->sorted_vocab, t->vocab_size);
        if (id != -1 && t->vocab_scores[id] > best_score) {
            // this merge pair exists in vocab! record its score and position
            best_score = t->vocab_scores[id];
            best_id = id;
            best_idx = i;
        }
    }

    if (best_idx == -1) {
        break; // we couldn't find any more pairs to merge, so we're done
    }

    // merge the consecutive pair (best_idx, best_idx+1) into new token best_id
    tokens[best_idx] = best_id;
    // delete token at position best_idx+1, shift the entire sequence back 1
    for (int i = best_idx+1; i < (*n_tokens-1); i++) {
        tokens[i] = tokens[i+1];
    }
    (*n_tokens)--; // token length decreased
}

// merge the best consecutive pair each iteration, according the scores in vocab_scores

while (1) {

float best_score = -1e10;

int best_id = -1;

int best_idx = -1;

for (int i=0; i < (*n_tokens-1); i++) {

// check if we can merge the pair (tokens[i], tokens[i+1])

sprintf(str_buffer, "%s%s", t->vocab[tokens[i]], t->vocab[tokens[i+1]]);

int id = str_lookup(str_buffer, t->sorted_vocab, t->vocab_size);

if (id != -1 && t->vocab_scores[id] > best_score) {

// this merge pair exists in vocab! record its score and position

best_score = t->vocab_scores[id];

best_id = id;

best_idx = i;

}

if (best_idx == -1) {

break; // we couldn't find any more pairs to merge, so we're done

}

// merge the consecutive pair (best_idx, best_idx+1) into new token best_id

tokens[best_idx] = best_id;

// delete token at position best_idx+1, shift the entire sequence back 1

for (int i = best_idx+1; i < (*n_tokens-1); i++) {

tokens[i] = tokens[i+1];

}

(*n_tokens)--; // token length decreased

}

2.4.2 decode

decode函数将token id序列转化为文本。代码也直观，有一些比较tricky之处，代码也注释清楚：

char* decode(Tokenizer* t, int prev_token, int token) { char *piece = t->vocab[token]; // following BOS (1) token, sentencepiece decoder strips any leading whitespace (see PR #89) if (prev_token == 1 && piece[0] == ' ') { piece++; } // careful, some tokens designate raw bytes, and look like e.g. '<0x01>' // parse this and convert and return the actual byte unsigned char byte_val; if (sscanf(piece, "<0x%0char* decode(Tokenizer* t, int prev_token, int token) {
    char *piece = t->vocab[token];
    // following BOS (1) token, sentencepiece decoder strips any leading whitespace (see PR #89)
    if (prev_token == 1 && piece[0] == ' ') { piece++; }
    // careful, some tokens designate raw bytes, and look like e.g. '<0x01>'
    // parse this and convert and return the actual byte
    unsigned char byte_val;
    if (sscanf(piece, "<0x%02hhX>", &byte_val) == 1) {
        piece = (char*)t->byte_pieces + byte_val * 2;
    }
    return piece;
}

char* decode(Tokenizer* t, int prev_token, int token) { char *piece = t->vocab[token]; // following BOS (1) token, sentencepiece decoder strips any leading whitespace (see PR #89) if (prev_token == 1 && piece[0] == ' ') { piece++; } // careful, some tokens designate raw bytes, and look like e.g. '<0x01>' // parse this and convert and return the actual byte unsigned char byte_val; if (sscanf(piece, "<0x%0char* decode(Tokenizer* t, int prev_token, int token) {

char *piece = t->vocab[token];

// following BOS (1) token, sentencepiece decoder strips any leading whitespace (see PR #89)

if (prev_token == 1 && piece[0] == ' ') { piece++; }

// careful, some tokens designate raw bytes, and look like e.g. '<0x01>'

// parse this and convert and return the actual byte

unsigned char byte_val;

if (sscanf(piece, "<0x%02hhX>", &byte_val) == 1) {

piece = (char*)t->byte_pieces + byte_val * 2;

}

return piece;

}

2.5 文本生成

文本生成是最基础的inference逻辑，对话也是基于文本生成而实现的。整个代码逻辑也非常简单：

将每一个token id逐个进行forward计算
判断当前token位置是否还在prompt长度内，如果不在则执行sampling策略，通过logits向量选取下一个token
否则直接从prompt中读取下一个token。
将下一个token进行decode，并打印出来。

代码详见：

while (pos < steps) {

    // forward the transformer to get logits for the next token
    float* logits = forward(transformer, token, pos);

    // advance the state machine
    if (pos < num_prompt_tokens - 1) {
        // if we are still processing the input prompt, force the next prompt token
        next = prompt_tokens[pos + 1];
    } else {
        // otherwise sample the next token from the logits
        next = sample(sampler, logits);
    }
    pos++;

    // data-dependent terminating condition: the BOS (=1) token delimits sequences
    if (next == 1) { break; }

    // print the token as string, decode it with the Tokenizer object
    char* piece = decode(tokenizer, token, next);
    safe_printf(piece); // same as printf("%s", piece), but skips "unsafe" bytes
    fflush(stdout);
    token = next;

    // init the timer here because the first iteration can be slower
    if (start == 0) { start = time_in_ms(); }
}

while (pos < steps) {

// forward the transformer to get logits for the next token

float* logits = forward(transformer, token, pos);

// advance the state machine

if (pos < num_prompt_tokens - 1) {

// if we are still processing the input prompt, force the next prompt token

next = prompt_tokens[pos + 1];

} else {

// otherwise sample the next token from the logits

next = sample(sampler, logits);

}

pos++;

// data-dependent terminating condition: the BOS (=1) token delimits sequences

if (next == 1) { break; }

// print the token as string, decode it with the Tokenizer object

char* piece = decode(tokenizer, token, next);

safe_printf(piece); // same as printf("%s", piece), but skips "unsafe" bytes

fflush(stdout);

token = next;

// init the timer here because the first iteration can be slower

if (start == 0) { start = time_in_ms(); }

}

2.6 其他

其他部分的代码就是一些简单的数据结构定义，以及helper函数和main函数，这里就不再赘述了。

3. 总结

总体来说，这个项目是一个toy项目，代码逻辑比较简单，但是也提供了非常多的细节参考。特别是兼容了MHA和GQA算法，对于理解这些算法的原理非常有帮助。

但也要看出，这个代码中并没有实现prefill阶段，而是采用逐个token输入的方式填充kv cache。效率的确比较低，但好在逻辑清晰，容易理解。

如果需要进一步优化这个代码，其实有很多可优化点，例如prefill的并行加载优化，减少重复decode等，但这些都超出了这个项目的范围，留给读者自己探索。

参考链接

llama2.c 源码阅读

2026 年 2 月
一	二	三	四	五	六	日
						1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28