AI on 云淡风轻

TINC 源码解读第四篇 - 模块依赖与数据流图

Thu, 08 Jan 2026 11:00:00 +0800

本文是 TINC 源码解读系列的第四篇，提供一份快速参考指南，包含完整的模块依赖关系、数据流图、核心数据结构和代码模式。

1. 文件分类一览表

1.1 核心应用程序

文件	行数	职能	关键函数
`tincd.c`	~730	VPN 守护进程主程序	`main()`
`tincctl.c`	~200+	控制工具客户端	`main()`
`fsck.c`	~200+	VPN 一致性检查	`fsck()`
`info.c`	~200+	VPN 信息查询	`info()`

1.2 协议处理模块

文件	职能	处理的消息
`protocol.c`	协议主处理	ID, ACK, ERROR, PING, PONG
`protocol_auth.c`	认证握手	METAKEY, CHALLENGE, CHAL_REPLY
`protocol_edge.c`	拓扑通告	ADD_EDGE, DEL_EDGE
`protocol_key.c`	密钥交换	KEY_CHANGED, REQ_KEY, ANS_KEY
`protocol_subnet.c`	子网通告	ADD_SUBNET, DEL_SUBNET
`protocol_misc.c`	其他消息	STATUS, TERMREQ
`net_packet.c`	数据包转发	PACKET (UDP)

1.3 连接与加密

文件	职能	核心结构
`connection.c`	TCP 连接管理	`connection_t`
`sptps.c`	SPTPS 握手/加密	`sptps_t`
`control.c`	控制接口	`connection_t + control`

1.4 节点与拓扑

文件	职能	核心结构
`node.c`	节点管理	`node_t`
`edge.c`	链路管理	`edge_t`
`subnet.c`	子网管理	`subnet_t`
`graph.c`	拓扑算法 (Dijkstra)	-
`route.c`	路由决策	-
`names.c`	名称↔ID 映射	-

1.5 网络 I/O

文件	职能
`net.c`	主网络处理循环
`net_socket.c`	UDP 套接字 I/O
`net_setup.c`	网络初始化
`net_packet.c`	数据包处理

1.6 设备驱动

文件	平台	说明
`device.h`	通用	设备操作接口
`linux/device.c`	Linux	TUN/TAP 设备
`bsd/device.c`	BSD	tun/tap 设备
`bsd/darwin/tunemu.c`	macOS	tunemu 模拟
`solaris/device.c`	Solaris	TUN 设备
`windows/device.c`	Windows	TAP-win32 设备
`dummy_device.c`	测试	黑洞设备
`raw_socket_device.c`	-	原始套接字
`fd_device.c`	-	文件描述符 I/O
`multicast_device.c`	-	组播
`vde_device.c`	-	VDE 交换机

1.7 密码学

文件	功能
`cipher.c`	对称加密 (AES, ChaCha20 等)
`digest.c`	哈希函数 (SHA256, SHA512 等)
`ecdsa.c`	ECDSA 数字签名
`ecdh.c`	ECDH 密钥交换
`rsa.c`	RSA 签名 (遗留)
`keys.c`	密钥生成与管理
`random.c`	伪随机数生成
`openssl/*.h`	OpenSSL 后端
`gcrypt/*.h`	libgcrypt 后端
`ed25519/`	Ed25519/EdDSA 内置实现
`chacha-poly1305/`	ChaCha20-Poly1305 AEAD 内置实现

1.8 事件与控制

文件	职能
`event.c`	事件循环核心
`event_select.c`	select() 后端
`logger.c`	日志输出
`script.c`	脚本执行 (tinc-up/down)

1.9 配置与工具

文件	职能
`conf.c`	配置文件解析
`conf_net.c`	网络配置字段
`proxy.c`	SOCKS 代理支持
`upnp.c`	UPnP 端口映射
`autoconnect.c`	自动连接管理
`address_cache.c`	地址缓存
`fs.c`	文件系统操作
`pidfile.c`	PID 文件管理
`sandbox.c`	沙箱/安全限制
`ifconfig.c`	网络接口配置
`netutl.c`	网络工具函数

1.10 数据结构

文件	职能
`list.c`	双链表容器
`splay_tree.c`	平衡树容器
`buffer.c`	动态缓冲区
`meta.c`	元数据处理

2. 模块依赖关系

2.1 依赖层级图

Application Layer
|
+-- tincd.c (主程序)
+-- tincctl.c (控制工具)
+-- info.c (信息查询)
+-- fsck.c (一致性检查)
    |
    v
Control & Event Layer
|
+-- event.c (事件循环)
+-- logger.c (日志)
+-- script.c (脚本执行)
+-- control.c (控制接口)
    |
    v
Protocol & Connection Layer
|
+-- connection.c (连接管理)
+-- protocol*.c (协议处理)
+-- sptps.c (加密握手)
    |
    v
Topology & Routing Layer
|
+-- node.c (节点)
+-- edge.c (链路)
+-- subnet.c (子网)
+-- graph.c (Dijkstra)
+-- route.c (路由)
    |
    v
Network I/O Layer
|
+-- net.c (主循环)
+-- net_socket.c (UDP)
+-- net_packet.c (转发)
+-- net_setup.c (初始化)
    |
    v
Device & Platform Layer
|
+-- device.h (抽象接口)
+-- linux/device.c
+-- bsd/device.c
+-- windows/device.c
    |
    v
Cryptography Layer
|
+-- cipher.c (对称)
+-- digest.c (哈希)
+-- ecdsa.c (签名)
+-- ecdh.c (密钥交换)
+-- keys.c (密钥管理)
    |
    v
Utilities & Data Structures
|
+-- buffer.c, list.c, splay_tree.c
+-- conf.c, logger.c, random.c

2.2 模块间调用关系

tincd.c (入口)
  |
  +-- event_loop()
  |   |
  |   +-- accept_connection() -> connection.c
  |   +-- handle_timeout() -> protocol*.c
  |   +-- network_poll()
  |       |
  |       +-- receive_packet() -> net_packet.c
  |       |   |
  |       |   +-- decrypt() -> sptps.c
  |       |   +-- route_packet() -> route.c
  |       |
  |       +-- send_packet() -> net_socket.c
  |           |
  |           +-- encrypt() -> sptps.c
  |
  +-- graph_update()
  |   |
  |   +-- dijkstra() -> graph.c
  |   +-- update_routes() -> route.c
  |
  +-- handle_protocol_message()
      |
      +-- protocol_*.c (各消息处理)
          |
          +-- node_add() -> node.c
          +-- edge_add() -> edge.c
          +-- subnet_add() -> subnet.c

3. 核心数据流图

3.1 连接建立流程

Client Node                         Server Node
    |                                   |
    +-- socket() ----TCP--->  accept()
    |
    +-- send_id()
    |   (PROT_MAJOR, PROT_MINOR)
    |   <--------- recv_id()
    |       (verify version)
    |
    +-- send_metakey()
    |   (cipher, digest, key)
    |   <--------- recv_metakey()
    |       (setup encryption)
    |
    +-- send_challenge()
    |   (hash = HMAC(...))
    |   <--------- recv_challenge()
    |       (compute hash)
    |
    +-- send_chal_reply()
    |   (hash reply)
    |   <--------- recv_chal_reply()
    |       (verify identity)
    |
    +-- send_ack()
    |   <--------- recv_ack()
    |
    v
Connection Established
Exchange Topology (ADD_EDGE, ADD_SUBNET)

3.2 数据包转发流程

VPN Data (IP Packet)
    |
    v
Write to Virtual Device (device.c)
    |
    v
tinc Network Layer (route.c)
    |
    +-- Query subnet owner
    |   (route_ipv4/route_ipv6)
    |
    v
Find Next Hop (graph.c)
    |
    +-- Check if direct or via relay
    |
    v
Encrypt Packet (sptps.c)
    |
    +-- HMAC + symmetric encryption
    |
    v
Choose Transport (UDP or TCP)
    |
    +-- If udp_confirmed and recent:
    |   +-- send_udppacket() (net_socket.c)
    |
    +-- Else:
    |   +-- send_tcppacket() (connection.c)
    |
    v
Network Transmission
    |
    v (Reverse on receiving side)
Receive Packet
    |
    +-- Decrypt (sptps.c)
    +-- Verify HMAC
    +-- Check sequence number
    |
    v
Route Decision (route.c)
    |
    +-- Local delivery?
    |   +-- Write to device
    |   +-- Application reads
    |
    +-- Forward to other node?
    |   +-- Send to next hop
    |
    v
Application Data

3.3 拓扑同步流程

Node A                  Root/Relay                Node B
    |                      |                       |
    +-- ADD_EDGE --------->|-- ADD_EDGE ---------->|
    |   (A, Root)          | (propagate)           |
    |                      |                       |
    |<-- ADD_EDGE ---------|<-- ADD_EDGE ----------+
    |   (B, Root)          | (propagate)           |
    |                      |                       |
    +-- ADD_SUBNET ------->|-- ADD_SUBNET -------->|
    |   (A, 172.16.1.0/24) |                       |
    |                      |                       |
    +-- REQ_KEY ---------->|-- REQ_KEY ----------->|
    |   (A wants B's key)  |                       |
    |                      |<-- ANS_KEY -----------+
    |                      |   (B's key)           |
    |<-- ANS_KEY ----------|                       |
    |   (B's key)          |                       |
    |                      |                       |
    |-- UDP Probe -------------------------------->|
    |   (A->B direct)      |                       |
    |                      |                       |
    |<-- UDP Reply <------------------------------+|
    |   (B->A direct)      |                       |
    |                      |                       |
    v (thereafter: direct UDP communication)

4. 关键数据结构速查

4.1 node_t (节点)

struct node_t {
    char *name;                 // 节点名
    node_id_t id;               // ED25519 公钥
    
    // 状态标志
    node_status_t status;       // 连接状态位
    
    // 网络地址
    sockaddr_t address;         // 节点地址
    sockaddr_t socket_address;  // UDP 地址
    
    // 连接
    struct list_t *connections; // TCP 连接列表
    connection_t *connection;   // 主连接
    
    // 拓扑
    splay_tree_t *subnets;      // 子网树
    splay_tree_t *edges;        // 关联边树
    
    // 路由
    struct node_t *via;         // 路由下一跳
    struct node_t *nexthop;     // 直接下一跳
    uint32_t distance;          // Dijkstra 距离
    
    // UDP 直连相关
    address_cache_t *address_cache; // 地址缓存
    bool udp_confirmed;             // UDP 已确认
    
    // 加密
    cipher_t *cipher;
    digest_t *digest;
    uint16_t outcipher, incipher;
    
    // 更多字段...
};

4.2 edge_t (链路)

struct edge_t {
    struct node_t *from;        // 源节点
    struct node_t *to;          // 目标节点
    
    sockaddr_t address;         // 目标地址
    
    int weight;                 // Dijkstra 权重
    int options;                // 边选项
    
    struct connection_t *connection; // 关联连接
    struct edge_t *reverse;     // 反向边指针
    
    bool active;                // 是否活跃
};

4.3 subnet_t (子网)

struct subnet_t {
    struct node_t *owner;       // 所有者
    
    subnet_type_t type;         // MAC/IPv4/IPv6
    int weight;                 // 优先级权重
    
    time_t expires;             // 过期时间
    
    union {
        subnet_mac_t mac;
        subnet_ipv4_t {
            struct in_addr address;
            int prefixlength;
        } ipv4;
        subnet_ipv6_t {
            struct in6_addr address;
            int prefixlength;
        } ipv6;
    } net;
};

4.4 connection_t (连接)

struct connection_t {
    io_t io;                    // I/O 事件
    
    struct node_t *node;        // 关联节点
    
    // 地址
    sockaddr_t address;         // 远程地址
    sockaddr_t local_address;   // 本地地址
    
    // 缓冲
    buffer_t inbuf, outbuf;     // 输入/输出缓冲
    
    // SPTPS 加密
    sptps_t sptps;              // SPTPS 状态
    
    // 状态
    connection_status_t status; // 连接状态位
    
    // 选项
    uint32_t options;
    int protocol_version;
    
    // 其他
    bool control;               // 是否控制连接
    bool initiate;              // 是否主动连接
};

4.5 sptps_t (SPTPS 加密)

struct sptps_t {
    sptps_state_t state;        // KEX/KEX1/KEX2/OPEN
    
    // 回调
    send_data_t send_data;
    receive_record_t receive_record;
    
    // 密钥交换
    ecdh_t *ecdh;               // ECDH 参数
    
    // 共享密钥
    uint8_t shared_secret[32];
    
    // 会话密钥
    uint8_t key[32];            // 对称密钥
    uint8_t hmac_key[32];       // HMAC 密钥
    
    // 序列号
    uint32_t inseq, outseq;
    
    // 缓冲
    buffer_t inbuf, outbuf;
};

5. 常见代码模式

5.1 创建新节点

node_t *n = new_node();
n->name = xstrdup("node_name");
n->status.visited = false;
n->status.reachable = true;
node_add(n);

5.2 添加子网

subnet_t *subnet = new_subnet();
subnet->owner = node;
subnet->type = SUBNET_IPV4;
subnet->net.ipv4.address = ipv4_address;
subnet->net.ipv4.prefixlength = 24;
subnet_add(node, subnet);

5.3 发送协议消息

send_request(c, "%s %d", "REQUEST_NAME", arg1);

// 例如:
send_request(c, "%s %s %s", "ADD_EDGE", node_a, node_b);
send_request(c, "%s %s %d", "ADD_SUBNET", "192.168.1.0/24", weight);

5.4 注册事件回调

io_t io;
io_add(&io, handle_new_connection, handle, IO_READ);

void handle_new_connection(void *data, int flags) {
    // 处理 I/O 事件
    if(flags & IO_READ) {
        // 有数据可读
    }
}

5.5 路由查询

node_t *via = node;
subnet_t *s = route_ipv4(packet);
if (s) {
    via = s->owner;      // 目标节点
}

// 检查是否直连
if (via->status.direct) {
    send_udppacket(via, packet);
} else {
    send_via_relay(via, packet);
}

5.6 图算法 (Dijkstra)

graph();  // 计算所有最短路径

// 结果存储在每个 node 的:
// - node->via (下一跳)
// - node->distance (距离)
// - node->indirect (是否间接)

// 使用结果
for(node_t *n = node_tree->root; n; n = n->next) {
    printf("Node %s: distance=%d, via=%s\n", 
           n->name, n->distance, n->via->name);
}

6. 构建与运行

6.1 编译

# 基本编译
./configure
make

# 带特定后端
./configure --with-openssl
make

# 发布版本
make install

6.2 启动 VPN 节点

# 初始化新 VPN
sudo tinc -n myvpn init nodename

# 添加子网
sudo tinc -n myvpn add Subnet 172.16.1.0/24

# 启动守护进程
sudo tinc -n myvpn start

# 查看状态
sudo tinc -n myvpn info

6.3 控制工具使用

# 获取节点信息
tinc -n myvpn info

# 查看连接
tinc -n myvpn edges

# 查看子网
tinc -n myvpn subnets

# 监控网络
tinc -n myvpn top

# 启用/禁用节点
tinc -n myvpn enable/disable <nodename>

7. 关键编译标志

标志	说明
`-DHAVE_OPENSSL`	使用 OpenSSL 后端
`-DHAVE_LIBGCRYPT`	使用 libgcrypt 后端
`-DHAVE_LZO`	启用 LZO 压缩
`-DHAVE_LZ4`	启用 LZ4 压缩
`-DLOGGER_DEBUG`	调试日志输出
`-DHAVE_LIBUPNP`	UPnP 支持
`-DHAVE_LIBMINIUPNPC`	miniupnpc 支持

8. 调试技巧

8.1 启用详细日志

# 运行时设置日志级别
tinc -n myvpn -d DEBUG

# 或运行时设置环境变量
DEBUG=2 tincd -n myvpn -d

8.2 数据包捕获

// 在 net_packet.c 中启用包转储
if (debug_level >= DEBUG_TRAFFIC) {
    fprintf(stderr, "Packet from %s: %d bytes\n", 
            source_node->name, packet_len);
}

8.3 追踪连接

# 监视 TCP 连接建立
strace -e trace=socket,connect tincd -n myvpn -d DEBUG

# 监视 UDP 包
tcpdump -i eth0 'udp port 1194'

8.4 性能分析

# 运行性能基准
sptps_speed

# 性能分析
perf record -g tincd -n myvpn -d
perf report

9. 常见问题排查

问题 1: 节点无法连接

诊断步骤:

# 1. 检查配置
tinc -n myvpn info

# 2. 检查网络连通性
ping <remote_ip>

# 3. 检查密钥文件
ls -la ~/.tinc/myvpn/hosts/

# 4. 查看详细日志
tinc -n myvpn -d DEBUG

常见原因:

防火墙阻止 TCP 655 或 UDP 1194
密钥文件缺失或权限错误
配置文件中 Address 字段错误
DNS 解析失败

问题 2: 高延迟

检查项:

查看 Dijkstra 路由是否最优: tinc -n myvpn edges
检查链路权重设置
考虑使用 UDP 直连而非 TCP 中继
检查 MTU 设置是否导致分片

问题 3: 密钥/签名错误

解决方案:

# 重新生成密钥
tinc -n myvpn generate-keys

# 验证密钥对
sptps_keypair

# 测试加密
sptps_test

问题 4: 内存占用持续增长

检查:

是否存在内存泄漏 (valgrind)
是否有断开但未清理的连接
检查事件循环是否正确管理

10. 性能优化点

关键优化

UDP 直连: 避免 TCP 元包开销 (5-10 倍吞吐量提升)
Dijkstra 缓存: 避免频繁重算拓扑
设备选择: TUN (L3) 比 TAP (L2) 更高效
加密算法: ChaCha20 > AES-CBC
子网聚合: 减少 ADD_SUBNET 广播
事件循环: epoll/kqueue > select
地址缓存: 避免重复 DNS 查询

性能指标

指标	TCP 中继	UDP 直连
延迟	100-500ms	10-100ms
吞吐量	50-200 Mbps	200-1000+ Mbps
CPU 占用	中等	低

11. 模块学习路径建议

初学者路径

第一阶段：了解主程序流程

阅读 tincd.c - 理解主程序和事件循环
阅读 main() 函数和初始化流程
理解配置加载、设备初始化、事件循环

第二阶段：理解数据结构 3. 阅读 node.c, edge.c, subnet.c - 核心数据结构 4. 理解节点、边、子网的关系 5. 理解拓扑树的组织方式

第三阶段：掌握网络逻辑 6. 阅读 net.c, route.c - 网络处理和路由 7. 理解数据包的接收和转发流程 8. 理解路由决策和下一跳计算

第四阶段：学习协议实现 9. 阅读 protocol.c - 协议消息处理 10. 理解握手流程和消息类型 11. 理解连接生命周期

进阶路径

第五阶段：深入加密层 12. 阅读 sptps.c - SPTPS 握手和加密 13. 阅读 cipher.c, digest.c - 密码学原语 14. 理解密钥交换和会话建立

第六阶段：掌握拓扑算法 15. 阅读 graph.c - Dijkstra 最短路径 16. 理解拓扑更新和路由重计算 17. 理解环检测和分割处理

第七阶段：系统集成 18. 阅读 device.c - 设备抽象和平台适配 19. 阅读 event.c - 事件循环实现 20. 理解跨平台兼容性

第八阶段：高级特性 21. 学习 UDP 打洞机制 (net_socket.c) 22. 学习 MTU 探测和路径优化 23. 学习性能优化技巧

12. 快速定位代码

按功能查找

“我要修改 TCP 握手流程” → 查看 protocol_auth.c, connection.c

“我要添加新的 UDP 功能” → 查看 net_socket.c, net_packet.c

“我要优化路由算法” → 查看 graph.c, route.c

“我要调整加密参数” → 查看 cipher.c, digest.c, sptps.c

“我要修改拓扑同步” → 查看 protocol_edge.c, protocol_subnet.c, graph.c

“我要支持新平台” → 查看 device.h, bsd/device.c, linux/device.c

按数据结构查找

node_t 相关代码 → node.c, node.h

edge_t 相关代码 → edge.c, edge.h

subnet_t 相关代码 → subnet.c, subnet.h

connection_t 相关代码 → connection.c, connection.h

sptps_t 相关代码 → sptps.c, sptps.h

13. 相关资源

官网: https://www.tinc-vpn.org/
文档: https://www.tinc-vpn.org/documentation-1.1/
源码: https://github.com/gsliepen/tinc
协议规范: PROTOCOL 文件 (项目内)

总结

TINC 的源码组织展现了大型系统软件的设计精髓：

关键特点

清晰的分层架构

应用层、控制层、协议层、网络层、系统层
每层通过定义良好的接口相互通信

灵活的数据结构

节点、边、子网形成拓扑
连接、SPTPS 管理通信状态
事件、缓冲处理异步操作

高效的算法

Dijkstra 最短路径
MRU 地址缓存
UDP 打洞和 MTU 探测

良好的可移植性

设备层抽象支持多平台
密码层支持多后端
平台特定代码隔离

学习建议

从主程序入手 - 理解整体流程
掌握核心数据结构 - 理解系统状态
学习协议实现 - 理解通信机制
深入加密和算法 - 理解安全性
研究平台适配 - 理解可移植性

这个项目是学习系统软件开发的极好范例！

系列预告

第一篇：TINC 协议深度解析
第二篇：TINC 模块架构与代码组织
第三篇：UDP 打洞机制
第四篇：TINC 项目 - 模块依赖与数据流图

TINC 源码解读第三篇 - UDP 打洞

Thu, 08 Jan 2026 10:00:00 +0800

本文是 TINC 源码系列分析的第三篇，重点探讨 TINC 如何在 NAT 环境下建立 P2P 直连。通过 UDP 打洞技术，TINC 能够让位于不同 NAT 后的节点直接通信，大幅提升性能。

1. UDP 打洞概览

问题背景

在互联网上，大多数终端设备都位于 NAT（Network Address Translation）或防火墙后面。这意味着两个内网节点无法直接建立 P2P 连接——它们的内网地址在公网上不可见。传统的解决方案是使用中央服务器中继，但这会增加延迟和服务器成本。

核心概念

UDP 打洞 是一种 NAT 穿透技术，允许两个在 NAT 后面的节点建立直接的 UDP 连接。基本原理是：

两个节点都在 NAT 后
无法直接建立 P2P 连接
通过第三方（根节点）转发连接信息
两个节点同时向对方发送 UDP 包
NAT 记住出站连接，允许回复通过
建立直接的 UDP 通道

优势：

✅ 避免 TCP 中继的开销
✅ 降低延迟
✅ 减少根节点流量
✅ 提高可靠性和吞吐量

2. TINC 中的 UDP 打洞机制

节点状态位

TINC 使用位字段记录节点状态，其中 udp_confirmed 是关键标志位，表示 UDP 连接已双向确认可用：

typedef union node_status_t {
    struct {
        bool validkey: 1;           // 有有效的加密密钥
        bool waitingforkey: 1;      // 等待密钥回复
        bool visited: 1;            // Dijkstra 访问标记
        bool reachable: 1;          // 在拓扑中可达
        bool indirect: 1;           // 不可直接到达
        bool sptps: 1;              // 支持 SPTPS 握手
        bool udp_confirmed: 1;      // ★ UDP 已确认可用
        bool send_locally: 1;       // 从本地网络发送
        bool udppacket: 1;          // 最后收到 UDP 包
        bool validkey_in: 1;        // 已发送有效密钥给对方
        bool has_address: 1;        // 知道对方公网地址
        bool ping_sent: 1;          // 已发送 UDP 探针包
    };
    uint32_t value;
} node_status_t;

关键状态变量

struct node_t {
    // UDP 直连相关
    bool udp_confirmed;             // UDP 连接已确认双向
    address_cache_t *address_cache; // 最近地址缓存
    
    // 打洞探测相关
    bool ping_sent;                 // UDP 探针已发送
    struct timeval udp_ping_sent;   // 探针发送时间
    int udp_ping_rtt;              // 往返时间 (微秒)
    
    // MTU 探测
    int mtuprobes;                  // MTU 探针计数
    uint16_t mtu;                   // 当前 MTU
    uint16_t minmtu;                // 最小 MTU
    uint16_t maxmtu;                // 最大 MTU
    
    // 包大小统计
    uint32_t maxrecentlen;          // 最近最大包长
};

3. UDP 打洞流程

详细步骤

步骤 1: TCP 握手连接

Node A                  Root Server                Node B
  |                        |                          |
  |------ TCP CONNECT ---->|                          |
  |                        |<------ TCP CONNECT ------|
  |                        |                          |

步骤 2: 交换拓扑信息

Node A                  Root Server                Node B
  |                        |                          |
  |- ADD_EDGE A, Root ---->|                          |
  |                        | (Root learns A's addr)   |
  |                        |                          |
  |                        |-- ADD_EDGE B, Root ----->|
  |                        |                          |
  |<- ADD_EDGE B, Root ----|                          |
  |   (A learns B exists)  |                          |

步骤 3: 密钥交换

Node A                  Root Server                Node B
  |                        |                          |
  |-- REQ_KEY A->B ------->|                          |
  | (request B's key)      |                          |
  |                        |---- REQ_KEY A->B ------->|
  |                        |                          |
  |                        |<---- ANS_KEY B->A -------|
  |                        | (B's key)                |
  |<-- ANS_KEY B->A -------|                          |
  | (forwarded by Root)    |                          |

步骤 4: UDP 打洞 (关键阶段)

Node A (LAN: 192.168.1.100:1194)        Node B (LAN: 192.168.2.50:1194)
  |                                       |
  | A knows B's public: 203.0.113.20:5001 | B knows A's public: 203.0.113.10:5000
  |                                       |
  +-- UDP Probe (TYPE=0) ----+            |
  |   NAT A opens hole:      |            |
  |   LAN1194 <-> WAN5000    |            |
  |                          +----------->| Forward to B's LAN
  |                                       | B's NAT opened
  |                          +------ UDP Reply (TYPE=1) --+
  |                          |  NAT B: LAN1194 <-> WAN5001|
  |                          |                            |
  |<-- UDP Reply received <--+                            |
  |    From: 203.0.113.20:5001                            |
  |    NAT A allows reply (hole remains open)             |
  |                                       |
  v (Both sides confirm UDP reachable)
  
  udp_confirmed = true [SUCCESS]
  Both NAT holes established and verified
  Start direct UDP communication

步骤 5: 直接 UDP 通信

Node A                                            Node B
  |                                                |
  |-------- Encrypted VPN packet (UDP) ----------->|
  | (No longer through Root, direct forward)       |
  |                                                |
  |<------- Encrypted VPN packet (UDP) ------------|
  |                                                |
  |--------- High-speed bidirectional flow ------->|

代码流程示意

// 1. 发送 UDP 探针
void send_udp_probe_packet(node_t *n, size_t len) {
    vpn_packet_t packet;
    DATA(packet)[0] = 0;  // 探针请求类型
    
    // 发送到 n 的公网地址
    send_udppacket(n, &packet);
    
    // 标记已发送
    n->status.ping_sent = true;
    gettimeofday(&n->udp_ping_sent, NULL);
}

// 2. 接收探针回复
static void udp_probe_h(node_t *n, vpn_packet_t *packet, length_t len) {
    // 收到对方的探针回复
    
    if(!n->status.udp_confirmed) {
        n->status.udp_confirmed = true;  // ✓ 双向 UDP 已建立
        
        // 缓存这个 UDP 地址
        if(!n->address_cache) {
            n->address_cache = open_address_cache(n);
        }
        add_recent_address(n->address_cache, &n->connection->address);
    }
}

4. 地址缓存机制

缓存结构

为了避免每次都进行 DNS 查询，TINC 维护一个最近地址缓存。缓存采用 MRU（Most Recently Used）策略，保留最近 8 个已验证的 UDP 地址：

#define MAX_CACHED_ADDRESSES 8

typedef struct address_cache_t {
    node_t *node;              // 关联节点
    splay_tree_t *config_tree; // 配置树
    config_t *cfg;             // 当前配置
    
    addrinfo *ai;              // 地址信息
    addrinfo *aip;             // 当前指针
    unsigned int tried;        // 尝试计数
    
    // 最近 8 个已验证的 UDP 地址
    struct {
        unsigned int version;  // 缓存版本
        unsigned int used;     // 已使用数量
        sockaddr_t address[8]; // 地址数组 (最近优先)
    } data;
} address_cache_t;

缓存操作

添加地址：当成功通过 UDP 接收到来自某个地址的包时，将该地址加入缓存
MRU 策略：最近使用的地址移到第 0 位，其他地址向后移动
获取地址：优先尝试缓存的地址，避免 DNS 查询
重置缓存：新连接尝试时清空缓存

5. NAT 类型检测与适应

常见 NAT 类型

NAT 类型	打洞成功率	特点
Full Cone NAT	✅ 95-99%	任何外部地址都能回复
Address-Restricted Cone	✅ 70-90%	只有之前通信过的源 IP 能回复
Port-Restricted Cone	⚠️ 30-60%	只有特定的源 IP:端口能回复
Symmetric NAT	❌ 0-5%	每个目标地址分配不同源端口，无法打洞

TINC 的适应机制

TINC 在协议选项中编码节点的特性，根据选项决定通信策略：

#define OPTION_INDIRECT    0x0001  // 间接连接（已知是 Symmetric NAT）
#define OPTION_TCPONLY     0x0002  // 仅 TCP，不支持 UDP
#define OPTION_PMTU_DISCOVERY 0x0004
#define OPTION_CLAMP_MSS   0x0008

// 根据选项决定使用策略:
if(e->options & OPTION_TCPONLY) {
    // 强制使用 TCP 中继
    use_tcp_relay();
} else if(e->options & OPTION_INDIRECT) {
    // 尝试打洞，但可能需要中继
    attempt_udp_hole_punch();
} else {
    // 尽量使用 UDP 直连
    prefer_udp_direct();
}

6. UDP 数据传输优化

发送策略

TINC 发送包时会检查 UDP 连接状态，优先使用最快的路径：

static void send_udppacket(node_t *n, vpn_packet_t *origpkt) {
    if(n->status.udp_confirmed) {
        // ✓ 已确认 UDP 可用
        
        // 1. 使用缓存的 UDP 地址
        const sockaddr_t *sa = get_recent_address(n->address_cache);
        
        if(!sa) {
            // 缓存无有效地址，降级到 TCP
            goto use_tcp;
        }
        
        // 2. 加密包
        encrypt_packet(n, origpkt);
        
        // 3. 直接通过 UDP 发送
        sendto(udp_socket, pkt, len, 0, sa, salen);
        
    } else {
        // UDP 未确认，使用 TCP 中继
        use_tcp:
        send_tcppacket(n->connection, origpkt);
    }
}

接收处理

static bool receive_udppacket(node_t *n, vpn_packet_t *inpkt) {
    // 收到 UDP 包
    
    // 1. 更新最近地址缓存
    add_recent_address(n->address_cache, &peer_addr);
    
    // 2. 解密
    decrypt_packet(n, inpkt);
    
    // 3. 路由转发
    route_packet(inpkt);
    
    // 4. 如果是首次 UDP 通信
    if(!n->status.udp_confirmed) {
        n->status.udp_confirmed = true;
        logger(LOG_INFO, "UDP direct connection established with %s", n->name);
    }
    
    return true;
}

7. 超时与降级处理

超时配置

// 参数配置
timeout_t udp_probe_timeout;    // 探针超时
#define UDP_PROBE_INTERVAL 3    // 3 秒发送一次
#define UDP_PROBE_TIMEOUT 10    // 10 秒未响应即超时

// 打洞流程时间线
0s   ├─ 发送第 1 个 UDP 探针
     │  status.ping_sent = true
     │
3s   ├─ 发送第 2 个 UDP 探针
     │
6s   ├─ 发送第 3 个 UDP 探针
     │
10s  ├─ 超时检查
     │  if (now - last_udp_reply > 10s)
     │      status.udp_confirmed = false
     │      switch to TCP relay
     │
...  ├─ 继续定期发送 UDP 探针尝试重连

降级逻辑

// TCP/UDP 混合转发 - 智能选择最优路径
void send_packet_to_node(node_t *n, vpn_packet_t *pkt) {
    
    // 优先级 1: UDP 直连（最快）
    if(n->status.udp_confirmed && is_recent_success) {
        return send_udppacket(n, pkt);
    }
    
    // 优先级 2: SPTPS over UDP（新式，安全）
    if(n->status.sptps) {
        return send_sptps_udppacket(n, pkt);
    }
    
    // 优先级 3: TCP 转发（可靠，较慢）
    if(n->connection && n->connection->status.active) {
        return send_tcppacket(n->connection, pkt);
    }
    
    // 优先级 4: 通过其他节点中继（绕行）
    if(n->via && n->via != n) {
        return send_via_relay(n->via, n, pkt);
    }
    
    // 无法送达
    return false;
}

8. MTU 探测与优化

MTU 发现流程

建立 UDP 直连后，TINC 会自动探测最优 MTU 大小，避免包分片导致的性能下降。

1. 初始 MTU = 1500 (以太网标准)

2. 发送递增大小的探针包
   ├─ 1500 字节 ─→ OK ✓
   ├─ 1450 字节 ─→ OK ✓
   ├─ 1400 字节 ─→ OK ✓
   ├─ 1350 字节 ─→ ICMP Fragmented (失败)
   │
   └─ 回退: MTU = 1350 + padding

3. 最终 MTU 确定后
   └─ 所有包都限制在该大小内
   └─ 避免分片，提高性能

代码实现：

void mtu_probe_timeout_handler(void *data) {
    node_t *n = data;
    
    if(n->mtuprobes == -1) {
        // MTU 已确定，不需要探测
        return;
    }
    
    if(n->mtuprobes++ > MAX_PROBES) {
        // 探针已发送足够次数
        try_fix_mtu(n);  // 确定最终 MTU
        return;
    }
    
    // 继续发送 MTU 探针
    size_t len = n->maxmtu - n->mtuprobes * 128;
    send_udp_probe_packet(n, len);
}

9. 协议扩展 (UDP_INFO)

TINC 通过 UDP_INFO 协议消息来交换 UDP 地址信息。这个消息在元协议（Meta Protocol，基于 TCP）中传输。

UDP_INFO 消息格式

格式: UDP_INFO originator_node address_info

流程:
1. Node A → Root: "UDP_INFO myself 203.0.113.10:5000"
   (告诉 Root 我的 UDP 地址)

2. Root → Node B: "UDP_INFO nodeA 203.0.113.10:5000"
   (告诉 B, A 的 UDP 地址)

3. Node B → Root: "UDP_INFO myself 203.0.113.20:5001"

4. Root → Node A: "UDP_INFO nodeB 203.0.113.20:5001"

实现优势

内网节点无法自己检测公网地址，需要第三方帮助
UDP_INFO 机制允许节点告诉其他节点自己的公网 UDP 地址
这是打洞成功的必要条件

10. 实际场景分析

场景 A: 双方都在 Full Cone NAT 后

Node A (10.0.0.5:1194)          Node B (10.0.0.6:1194)
NAT: 203.0.113.10:5000          NAT: 203.0.113.20:5001

时间线:
0ms   A UDP 包 → Root → Root 转发给 B
      NAT A 记录: 内网 1194 ↔ 外网 5000 ↔ 203.0.113.20:5001

5ms   B 收到 A 的探针
      回复 UDP 包 → 203.0.113.10:5000
      NAT B 记录: 内网 1194 ↔ 外网 5001 ↔ 203.0.113.10:5000

10ms  A 收到 B 的回复
      udp_confirmed = true ✓
      后续所有包直接交换，不经过 Root

成功率: ✓ 100% (Full Cone NAT 最容易打洞成功)

场景 B: 一方在 Symmetric NAT 后

Node A (Symmetric NAT)          Node B (Full Cone NAT)

A 的 NAT 行为:
每次发送到不同地址时使用不同的源端口
├─ → 203.0.113.20 from 5000
├─ → 203.0.113.30 from 5001
└─ → 203.0.113.40 from 5002

问题:
Root 看到多个不同的源端口，无法告诉 B 一个确定的 UDP 地址

结果: UDP 打洞失败 ❌
降级: 使用 TCP 中继

11. 性能指标

典型延迟与吞吐量

TCP 中继路径：

延迟：100-500ms（往返）
吞吐量：50-200 Mbps

UDP 直连路径：

延迟：10-100ms（往返，取决于网络）
吞吐量：200-1000+ Mbps（接近原生网络）

吞吐量提升：UDP 直连相比 TCP 中继提升 5-10 倍

成功率统计

NAT 场景	打洞成功率	降级方案
Full Cone NAT	95-99%	TCP 中继
Restricted Cone	70-90%	TCP 中继
Port-Restricted	30-60%	TCP 中继
Symmetric NAT	0-5%	TCP 中继（必须）

12. 调试与监控

查看打洞状态

# 运行时查询
tinc -n myvpn info <node>

# 输出示例:
Node: remotenode
  Address: 203.0.113.20 port 655
  Cipher: aes-256-cbc
  Digest: sha512
  Magic: 12345678
  Status: active validkey udp_confirmed

# udp_confirmed 出现 → UDP 直连已建立 ✓

调试日志

# 启用 UDP 调试
RUST_LOG=debug tincd -n myvpn -d DEBUG

# 关键日志:
[DEBUG] Sending UDP probe to nodeB (203.0.113.20:1194)
[DEBUG] Got UDP probe reply from nodeB
[DEBUG] UDP direct connection confirmed with nodeB
[DEBUG] Caching recent address for nodeB: 203.0.113.20:1194
[DEBUG] MTU for nodeB: 1372 bytes

网络捕获

# 捕获 UDP 直连包
tcpdump -i eth0 -n 'udp port 1194' -w vpn.pcap

# 分析包内容
wireshark vpn.pcap
# 查看: 源/目标 IP:端口、包大小、发送频率

13. 常见问题与解决

问题 1: UDP 打洞失败，始终显示 TCP

诊断：

$ tinc -n myvpn info remotenode | grep -i udp

现象：无 udp_confirmed 标志

原因可能：

节点在 Symmetric NAT 后
防火墙阻止 UDP
ISP 限制 UDP
路由策略问题

解决：

确认两节点都支持 UDP
检查防火墙规则：sudo ufw allow 1194/udp
尝试 UPnP 端口映射（如支持）
确认 UDP_INFO 消息交换成功

问题 2: 间歇性 UDP 中断

现象：UDP 时而工作，时而不工作

原因：

网络波动导致超时
NAT 刷新时间过短
MTU 设置不当导致分片丢失

解决：

降低 UDP 探针超时：udp_probe_timeout = 15
增加打洞频率：udp_probe_interval = 2
调整 MTU：minmtu = 1280

问题 3: MTU 不匹配

现象：大包通过 UDP 时丢失

原因：中间网络 MTU < 节点配置的 MTU

解决：

启用 MTU 自动探测
手动配置：PMTU_SIZE 1280
启用 PMTU 发现：DF 位设置

总结

TINC 的 UDP 打洞机制展示了如何在复杂的 NAT 环境下实现高效的 P2P 通信。关键设计包括：

核心流程：

TCP 握手 + 拓扑同步
    ↓
UDP_INFO 交换公网地址
    ↓
同时发送 UDP 探针（打洞）
    ↓
建立双向 UDP 连接
    ↓
优先使用 UDP 直连
    ↓
失败自动降级到 TCP

关键特性：

✅ 自适应 NAT 类型
✅ 地址缓存优化
✅ 动态 MTU 发现
✅ 失败自动降级
✅ 支持 IPv4 和 IPv6
✅ 低延迟高吞吐量

性能提升：

连接方式	吞吐量
TCP 中继	50-200 Mbps
UDP 直连	200-1000 Mbps
提升倍数	5-10 倍

这种精心设计的适应性系统使 TINC 在各种网络环境下都能提供最优的性能，是现代 VPN 软件的最佳实践。

系列预告

第一篇：TINC 协议深度解析
第二篇：TINC 模块架构与代码组织
第三篇：UDP 打洞机制
第四篇：TINC 项目 - 模块依赖与数据流图

TINC 源码解读第二篇 - 模块架构与代码组织

Thu, 08 Jan 2026 09:00:00 +0800

本文是 TINC 源码解读系列的第二篇，重点分析 TINC 的整体架构和代码组织。TINC 采用清晰的分层架构，将系统分为 8 个层次，从应用层到工具层，每层都有明确的职责。

1. 项目概述

TINC 是一个点对点 (P2P) VPN 守护进程，支持任意数量节点的虚拟专用网络。通过指定 VPN 中几个节点的位置和公钥，TINC 能够自动发现所有其他节点并建立连接。当直接连接不可用时，数据通过中间节点转发。

支持的工作模式：

Router (路由器模式) - 默认，每个节点关联 IPv4/IPv6 子网
Switch (交换机模式) - 虚拟以太网交换机
Hub (集线器模式) - 虚拟以太网集线器

2. 分层架构概览

+---------------------------------------------------------------------+
|                    Application Layer                                |
| +----------+----------+----------+--------+                         |
| | tincd.c  | tincctl  | info.c   | fsck.c |                         |
| | (daemon) | (control)| (query)  |(verify)|                         |
| +----------+----------+----------+--------+                         |
+---------------------------------------------------------------------+
                            |
+---------------------------------------------------------------------+
|                      Control Layer                                  |
| +----------+----------+----------+--------+                         |
| | control  | command  | top.c    | script |                         |
| | (socket) | (handler)| (monitor)|(exec)  |                         |
| +----------+----------+----------+--------+                         |
+---------------------------------------------------------------------+
                            |
+---------------------------------------------------------------------+
|                   Protocol & Comm Layer                             |
| +----------+----------+----------+                                  |
| | protocol | sptps.c  | connec   |                                  |
| | * files  | (crypto) | tion.c   |                                  |
| +----------+----------+----------+                                  |
+---------------------------------------------------------------------+
                            |
+---------------------------------------------------------------------+
|                   Network & Routing Layer                           |
| +----------+----------+----------+--------+                         |
| | net*.c   | route.c  | graph.c  | proxy  |                         |
| | (I/O)    | (table)  | (topo)   |        |                         |
| +----------+----------+----------+--------+                         |
+---------------------------------------------------------------------+
                            |
+---------------------------------------------------------------------+
|                   Data Structure Layer                              |
| +----------+----------+----------+--------+                         |
| | node.c   | edge.c   | subnet.c | names  |                         |
| | +--------+----------+----------+--------+                         |
| | | list   | splay    | hash     |        |                         |
| | | tree   | tree     | table    |        |                         |
| +----------+----------+----------+--------+                         |
+---------------------------------------------------------------------+
                            |
+---------------------------------------------------------------------+
|                  Cryptography Layer                                 |
| +----------+----------+----------+--------+                         |
| | cipher   | digest   | ecdsa    | ecdh   |                         |
| | (sym)    | (hash)   | (sig)    | (kex)  |                         |
| | +--------+----------+----------+--------+                         |
| | | rsa    | ed25519  | OpenSSL  | gcrypt |                         |
| +----------+----------+----------+--------+                         |
+---------------------------------------------------------------------+
                            |
+---------------------------------------------------------------------+
|                   Device & System Layer                             |
| +----------+----------+----------+--------+                         |
| | device.h | *_device | event.c  | conf.c |                         |
| | (intf)   | (impl)   | (loop)   |(config)|                         |
| | +--------+----------+----------+--------+                         |
| | | linux  | bsd      | solaris  | win    |                         |
| +----------+----------+----------+--------+                         |
+---------------------------------------------------------------------+
                            |
+---------------------------------------------------------------------+
|                    Utilities Layer                                  |
| +----------+----------+----------+--------+                         |
| | logger   | utils    | random   | buffer |                         |
| | (log)    | (tools)  | (prng)   | (mem)  |                         |
| | +--------+----------+----------+--------+                         |
| | | fs.c   | address  | autocon  | names  |                         |
| | |        | cache.c  | nect.c   |        |                         |
| +----------+----------+----------+--------+                         |
+---------------------------------------------------------------------+

3. 模块详细说明

3.1 应用层 (Application Layer)

`tincd.c` - 主守护进程

职责: VPN 守护进程的主程序和事件循环
功能:
- 初始化配置和网络
- 启动主事件循环
- 处理信号和优雅关闭
- 管理程序生命周期
依赖: conf.h, event.h, protocol.h

`tincctl.c` - 控制工具

职责: 远程控制 tincd 的命令行工具
功能:
- 连接到 tincd 控制套接字
- 发送/接收命令
- 交互式命令处理
依赖: control.h

`info.c` 和 `fsck.c`

info.c: 显示 VPN 节点信息、查询节点状态
fsck.c: VPN 配置和状态一致性验证

3.2 控制层 (Control Layer)

`control.c` - 控制连接管理

职责: 管理与控制客户端的连接
功能:
- 建立和维护控制连接
- 接收/处理控制命令
- 返回状态信息
关键结构: connection_t (带 control 标志)

`script.c` - 脚本执行

职责: 执行 VPN 生命周期脚本
功能:
- 执行 tinc-up/tinc-down 脚本
- 设置虚拟网络接口
- 执行自定义钩子函数
环境: 通过环境变量传递配置

`event.c` - 事件循环

职责: 异步事件处理引擎
功能:
- I/O 事件（select/epoll/kqueue）
- 超时处理
- 信号处理
回调类型: io_cb_t, timeout_cb_t, signal_cb_t

3.3 协议与通信层 (Protocol & Communication)

`protocol*.c` - 协议处理

文件	职责	处理消息
`protocol.c`	主协议处理器	ID, ACK, ERROR
`protocol_auth.c`	认证	METAKEY, CHALLENGE, CHAL_REPLY
`protocol_edge.c`	边通告	ADD_EDGE, DEL_EDGE
`protocol_key.c`	密钥交换	KEY_CHANGED, REQ_KEY, ANS_KEY
`protocol_subnet.c`	子网通告	ADD_SUBNET, DEL_SUBNET
`protocol_misc.c`	其他	PING, PONG, STATUS
`net_packet.c`	包转发	PACKET

协议版本: PROT_MAJOR=17, PROT_MINOR=7

`sptps.c` - 安全协议握手

职责: 实现 Simple SPTPS 的点对点加密协议
功能:
- 密钥交换 (ECDH)
- 会话建立
- 记录加密/解密
- 前向保密
状态机: SPTPS_KEX → SPTPS_KEX1 → SPTPS_KEX2 → SPTPS_OPEN
密钥派生: 使用 SHA256/SHA512

`connection.c` - 连接管理

职责: 管理与其他节点的 TCP 连接
功能:
- 建立/关闭连接
- 连接状态跟踪
- 连接队列管理
- 元包缓冲 (meta packets)

typedef struct {
  io_t io;                    // I/O event
  struct node_t *node;        // associated node
  buffer_t inbuf, outbuf;     // input/output buffers
  sptps_t sptps;              // SPTPS state
  connection_status_t status; // connection status
} connection_t;

3.4 网络与路由层 (Network & Routing)

`net*.c` - 网络 I/O

文件	职责
`net.c`	主网络处理循环
`net_socket.c`	套接字操作 (UDP)
`net_packet.c`	包处理 (接收/转发)
`net_setup.c`	网络初始化

功能:

UDP 包接收/发送 (fast path)
TCP 连接处理 (slow path)
包加密/解密
包转发

`route.c` - 路由管理

职责: 处理数据包路由决策
工作模式:
- RMODE_ROUTER - 基于子网的路由 (默认)
- RMODE_SWITCH - 以太网交换
- RMODE_HUB - 集线器 (广播)

`graph.c` - 拓扑算法

职责: 计算网络拓扑
算法:
- Dijkstra 最短路径
- Spanning Tree 构建
- 连通性检查
应用:
- 确定最优转发路径
- 检测网络分割
- 计算中继节点

`proxy.c` - 代理支持

职责: 代理协议支持 (SOCKS4/SOCKS5)
功能:
- 通过代理建立连接
- SOCKS 握手处理
- 认证支持

3.5 数据结构层 (Data Structures)

核心数据结构

`node_t` (节点)

node_t
|-- name: 节点名称
|-- id: 节点 ID (ED25519 pub key)
|-- status: 节点状态 flags
|-- address: 节点地址
|-- socket_address: UDP addr
|-- distance: Dijkstra distance
|-- via: routing next hop
|-- nexthop: direct next hop
|-- subnets: owned subnets tree
|-- keys: encrypt keys
+-- connections: TCP conn list

`edge_t` (边/链路)

edge_t
|-- from: source node
|-- to: target node
|-- address: target address
|-- options: edge opts (flags)
|-- weight: path weight
|-- connection: TCP conn
+-- reverse: reverse edge

`subnet_t` (子网)

subnet_t
|-- owner: owner node
|-- type: subnet type
|-- weight: priority weight
|-- expires: expire time
+-- net: subnet data
    |-- mac.address
    |-- ipv4.address/prefix
    +-- ipv6.address/prefix

`connection_t` (连接)

connection_t
|-- io: I/O event handle
|-- node: associated node
|-- address: remote address
|-- inbuf, outbuf: buffers
|-- sptps: SPTPS state
|-- status: connection state
|-- options: connection opts
|-- protocol_version: proto ver
+-- mst: in minimum tree?

容器结构

容器	用途	组织方式
`splay_tree_t`	有序集合 (nodes, subnets, edges)	平衡树
`list_t`	无序列表 (connections, events)	双链表
`hash.h`	快速查找 (name→node mapping)	哈希表

3.6 密码学与安全层 (Cryptography)

对称加密

cipher.c:
- AES, Blowfish, Camellia 等
- ECB, CBC, CFB, OFB, CTR 模式
- 后端: OpenSSL 或 libgcrypt
chacha-poly1305/:
- ChaCha20-Poly1305 AEAD 加密
- 独立实现

哈希与消息摘要

digest.c:
- SHA1, SHA256, SHA512
- MD5 (遗留)
- 后端: OpenSSL 或 libgcrypt
ed25519/sha512.h: ED25519 自带 SHA512

非对称加密与签名

ecdsa.c: ECDSA 签名 (通过 libgcrypt 或 OpenSSL)
ecdh.c: ECDH 密钥交换 (SPTPS 握手用)
rsa.c (遗留): RSA 签名 (传统握手)
ed25519/: EdDSA 实现

后端支持

Cipher/Digest layers
    |
    +-- openssl/ (libssl/libcrypto)
    +-- gcrypt/  (libgcrypto)
    +-- ed25519/ (built-in)

密钥管理

keys.c:
- 生成和加载密钥
- 密钥文件 I/O
- 密钥验证
prf.h: 伪随机函数

3.7 设备与系统层 (Device & System)

虚拟网络设备

device.h: 设备操作接口 (抽象)

typedef struct devops_t {
  setup_t setup;        // initialize
  cleanup_t cleanup;    // clean up
  read_t read;          // read packet
  write_t write;        // write packet
} devops_t;

设备实现:

平台	实现	文件
Linux	TUN/TAP	`linux/device.c`
BSD	tun/tap	`bsd/device.c`
macOS	tunemu	`bsd/darwin/tunemu.c`
Solaris	TUN	`solaris/device.c`
Windows	TAP	`windows/device.c`

其他设备:
- dummy_device.c - 测试用 (黑洞)
- fd_device.c - 文件描述符
- raw_socket_device.c - 原始套接字
- multicast_device.c - 组播
- vde_device.c - VDE 交换机

事件驱动

event.c:
- 事件循环 (select/epoll/kqueue)
- I/O 复用
- 超时和信号处理
event_select.c: select() 后端

配置管理

conf.c:
- 配置文件解析
- 配置树管理
- 配置查询
conf_net.c: 网络配置字段

平台特定代码

bsd/       - BSD 特定 (sandbox, tun)
linux/     - Linux 特定 (设备)
solaris/   - Solaris 特定
windows/   - Windows 特定

3.8 实用工具层 (Utilities)

模块	职责
`logger.c`	日志记录 (DEBUG/INFO/WARNING)
`utils.c`	通用工具函数
`random.c`	伪随机数生成
`buffer.c`	动态缓冲区
`fs.c`	文件系统操作
`dropin.c`	缺失函数替代
`address_cache.c`	节点地址缓存
`autoconnect.c`	自动连接管理
`names.c`	名字↔ID 映射
`netutl.c`	网络工具
`ifconfig.c`	网络接口配置
`pidfile.c`	PID 文件管理
`sandbox.c`	沙箱/安全限制

4. 模块依赖关系

tincd/tincctl (Application)
    |
    v
control + event + logger (Control/Events)
    |
    v
protocol* + sptps + connection (Protocol)
    |
    v
node + edge + subnet + graph + route (Data/Topology)
    |
    v
net* + device + proxy (Network I/O)
    |
    v
cipher + digest + ecdsa + ecdh (Crypto)
    |
    v
buffer + list + splay_tree + hash (Containers)
    |
    v
utils + logger + random + conf (Utilities)

5. 关键工作流

5.1 连接建立流程

1. node.c: create node
    |
    v
2. connection.c: init TCP conn
    |
    v
3. protocol_auth.c: send ID
    |
    v
4. sptps.c: ECDH key exchange
    |
    v
5. protocol_key.c: exchange session key
    |
    v
6. net_packet.c: start forward UDP

5.2 数据包转发流程

1. net_socket.c: receive UDP packet
    |
    v
2. net_packet.c: decrypt packet
    |
    v
3. route.c: routing decision
    |
    v
4. graph.c: compute forward path
    |
    v
5. connection.c / net_socket.c: forward or local

5.3 拓扑更新流程

1. protocol_edge.c: recv ADD_EDGE/DEL_EDGE
    |
    v
2. edge.c: update edge database
    |
    v
3. graph.c: recompute shortest path (Dijkstra)
    |
    v
4. route.c: update forward table

6. 编译配置选项

项目支持多个可选功能，通过编译标志控制：

加密后端: HAVE_OPENSSL / HAVE_LIBGCRYPTO
压缩: HAVE_LZO / HAVE_LZ4
高级特性: HAVE_LIBUPNP, HAVE_LIBMINIUPNPC
平台特定: HAVE_LINUX, HAVE_BSD, HAVE_WINDOWS 等

7. 统计信息

核心代码文件:  60+ files
总代码行数:    15,000+ lines
支持平台:      Linux, BSD, macOS, Solaris, Windows
关键数据结构:  5+ (node, edge, subnet, connection, device)
密码算法:      10+

8. 架构设计优势

模块独立

每个模块职责清晰
最小化模块间耦合
便于测试和维护

易于移植

设备层、密码层可替换
平台特定代码隔离
支持 5+ 个操作系统

可扩展

易于添加新协议
易于添加新加密算法
支持可选特性编译

性能优化

关键路径 (UDP fast path) 独立优化
Dijkstra 缓存避免重复计算
地址缓存防止 DNS 查询风暴

9. 从 TINC 架构到代码实现

快速导航指南

入门代码:

主程序: tincd.c
节点定义: node.h
连接管理: connection.h

协议处理:

协议分发: protocol.c
握手流程: protocol_auth.c

数据转发:

包接收: net_packet.c
路由决策: route.c

拓扑算法:

最短路径: graph.c

总结

TINC 的分层架构展现了大型系统软件的设计哲学：

核心原则

分层设计 - 将系统分为 8 个清晰的层次，每层通过定义良好的接口与其他层通信。

模块化 - 每个模块职责单一，相对独立，易于理解和测试。

可移植性 - 通过设备层、密码层等的抽象，支持多平台和多后端。

高效性 - UDP 直接转发为 fast path，TCP 握手和控制走 slow path，最大化性能。

代码启示

顶层应用 - 通过控制层与底层通信
中层协议 - 实现握手、认证、拓扑交换
下层系统 - 提供跨平台的统一接口
工具层 - 提供通用服务（日志、缓冲、随机数等）

这种精心设计的架构使 TINC 成为一个既可靠又高效的 VPN 解决方案，也是学习大型系统软件架构的极好范例。

系列预告

第一篇：TINC 协议深度解析
第二篇：TINC 模块架构与代码组织
第三篇：UDP 打洞机制
第四篇：TINC 项目 - 模块依赖与数据流图

TINC 源码解读第一篇 - 协议深度解析

Thu, 08 Jan 2026 08:00:00 +0800

本文是 TINC 源码解读系列的第一篇，重点分析 TINC 的协议设计。TINC 采用分层架构，使用 Meta Protocol 处理控制平面，Packet Protocol 处理数据平面，SPTPS 提供额外的加密保证。

1. 协议概览

TINC 使用两个独立的协议层：

Meta Protocol - TCP 连接上的文本协议（连接建立、拓扑交换）
Packet Protocol - UDP 连接上的二进制协议（数据包转发）

协议版本

PROT_MAJOR = 17  // 主版本号（不兼容时变化）
PROT_MINOR = 7   // 次版本号（向后兼容）

2. Meta 协议 - 控制平面

消息类型枚举

Meta Protocol 定义了 20 多种消息类型，按功能分类：

// 认证阶段
ID              // 连接标识
METAKEY         // 元数据密钥交换
CHALLENGE       // 密码挑战
CHAL_REPLY      // 挑战回复
ACK             // 确认

// 连接管理
STATUS          // 状态信息
ERROR           // 错误消息
TERMREQ         // 终止请求

// 保活
PING            // 心跳 Ping
PONG            // 心跳 Pong

// 拓扑交换
ADD_SUBNET      // 添加子网
DEL_SUBNET      // 删除子网
ADD_EDGE        // 添加边/链路
DEL_EDGE        // 删除边/链路

// 密钥交换
KEY_CHANGED     // 密钥已更改
REQ_KEY         // 请求加密密钥
ANS_KEY         // 应答加密密钥

// 数据转发
PACKET          // TCP 转发数据包

// Tinc 1.1+ 扩展
REQ_PUBKEY      // 请求公钥
ANS_PUBKEY      // 应答公钥
SPTPS_PACKET    // SPTPS 加密包
UDP_INFO        // UDP 地址信息
MTU_INFO        // MTU 信息

核心消息格式

ID 消息 - 连接起点

格式: ID name version

示例: 0 mynode 17.7

含义:
├─ 0        - 消息类型标识
├─ mynode   - 节点名称
└─ 17.7     - 协议版本 (MAJOR.MINOR)

METAKEY 消息 - 加密参数协商

格式: METAKEY cipher digest keylength [加密的密钥]

示例: 1 aes-256-cbc sha512 32 [128字节加密数据]

含义:
├─ 1              - 消息类型
├─ aes-256-cbc    - 对称加密算法
├─ sha512         - HMAC 摘要算法
└─ 32             - 密钥长度（字节）

特点:
└─ 加密密钥使用对方的公钥进行 RSA 加密

CHALLENGE 消息 - 身份验证

格式: CHALLENGE <hash>

验证过程:
1. 接收方生成随机 challenge (16 字节)
2. 计算 hash = HMAC-SHA256(challenge, shared_key)
3. 发送 CHALLENGE hash
4. 发起方计算相同的 hash
5. 验证 hash 相等

ADD_EDGE 消息 - 拓扑通告

格式: ADD_EDGE node_from node_to address port weight options

示例: ADD_EDGE nodeA nodeB 192.168.1.100 655 100 0

解析:
├─ ADD_EDGE        - 消息类型
├─ nodeA           - 源节点
├─ nodeB           - 目标节点
├─ 192.168.1.100   - 目标地址（实际网络地址）
├─ 655             - UDP 端口
├─ 100             - 权重（用于 Dijkstra）
└─ 0               - 选项标志

选项标志:
├─ 0x0001: OPTION_INDIRECT   (间接连接)
├─ 0x0002: OPTION_TCPONLY    (仅 TCP)
├─ 0x0004: OPTION_PMTU_DISCOVERY
└─ 0x0008: OPTION_CLAMP_MSS

ADD_SUBNET 消息 - 子网通告

格式: ADD_SUBNET owner_node network/prefixlength

IPv4 示例: ADD_SUBNET node1 192.168.1.0/24
IPv6 示例: ADD_SUBNET node1 2001:db8::/32
MAC  示例: ADD_SUBNET node1 ff:ff:ff:ff:ff:ff

用途:
└─ 通告该节点负责路由的子网地址

REQ_KEY 和 ANS_KEY - 数据加密密钥交换

REQ_KEY 格式: REQ_KEY originator destination
含义: originator 请求与 destination 的通信密钥

ANS_KEY 格式: ANS_KEY from to cipher_id digest_id key mac_length
示例: ANS_KEY nodeB nodeA 1 3 4ae0b0a82d6e0078 16

解析:
├─ nodeB         - 密钥所有者
├─ nodeA         - 请求方
├─ 1             - 对称加密算法 ID
├─ 3             - HMAC 摘要算法 ID
├─ 4ae0...78     - 128 位加密密钥
└─ 16            - MAC 长度

PING 和 PONG - 保活消息

PING 格式: PING [随机数]
PONG 格式: PONG [随机数]

用途:
├─ 检测连接是否仍然活跃
├─ 防止连接因不活动而被关闭
├─ 检测单向连接失败
└─ 通过随机数防止已知明文攻击

3. Meta 协议握手流程

完整的连接建立过程

发起方                      响应方
─────────────────────────────────────

TCP 连接 ─────────────→

                  ← 接受连接

发送 ID ──────────→
                  
                  ✓ 验证版本

                  ← 发送 ID

✓ 验证版本

发送 METAKEY ─────→
(加密的元密钥)

                  ✓ 解密元密钥

                  ← 发送 METAKEY

✓ 解密元密钥

从此以后，所有通信使用
协商的加密密钥加密

发送 CHALLENGE ────→
(hash = HMAC(...))

                  ✓ 验证 hash

                  ← CHAL_REPLY

✓ 双向认证成功

发送 ACK ─────────→

                  ← ACK

✓ 连接完全建立

握手状态机

[TCP Connected]
    ↓
[ID Exchanged]
├─ 校验版本号
├─ 确定协议版本
└─ 准备加密
    ↓
[METAKEY Exchanged]
├─ 选择加密算法
├─ 交换元数据密钥
└─ 开始加密通信
    ↓
[CHALLENGE Issued]
├─ 单向认证
├─ 验证对方公钥
└─ 生成共享密钥
    ↓
[CHAL_REPLY Received]
├─ 双向认证完成
├─ 确认对方身份
└─ 建立信任
    ↓
[ACK Sent/Received]
├─ 连接活跃
├─ 准备数据交换
└─ 拓扑同步
    ↓
[ACTIVE]
├─ 双向 PING/PONG
├─ 转发 ADD_EDGE
├─ 转发 ADD_SUBNET
├─ 转发 REQ_KEY/ANS_KEY
└─ 转发数据包

4. Packet Protocol - 数据平面

UDP 数据包格式

加密前的包结构

Byte:  0-3         4-...           ...      ...+16
      +----------+---------------+--------+--------+
      | seqno    | payload       | padding| MAC    |
      | (32 bit) | (VPN data)    |        |(256bit)|
      +----------+---------------+--------+--------+
      +-----------------------------------+--------+
              Covered by HMAC

加密后的完整 UDP 包

+-------------------------------------------------+
| UDP Header (20 bytes)                           |
| +--- Source IP                                  |
| +--- Dest IP                                    |
| +--- Source Port (1194 or configured)           |
| +--- Dest Port                                  |
+-------------------------------------------------+
| Encrypted Payload (variable length)             |
| +--- Nonce/IV (optional)                        |
| +--- Ciphertext:                                |
| |    +--- seqno (sequence number)               |
| |    +--- VPN data (virtual network packet)     |
| |    +--- HMAC (message authentication code)    |
| +--- Authentication Tag (AEAD encryption)       |
+-------------------------------------------------+

VPN 数据包结构

虚拟网络上传输的是标准 Ethernet Frame：

+----------+----------+----------+---------+-----+
| Dest MAC | Src MAC  | EtherType| Payload | CRC |
| (6 Byte) | (6 Byte) | (2 Byte) |(var len)| (4) |
+----------+----------+----------+---------+-----+

EtherType:
+-- 0x0800: IPv4
+-- 0x86DD: IPv6
+-- 0x0806: ARP

支持的加密算法

对称加密:
├─ ChaCha20-Poly1305  (推荐，AEAD)
├─ AES-256-GCM        (AEAD)
├─ AES-256-CBC        (需要 HMAC)
└─ null cipher        (调试用，无加密)

消息摘要:
├─ SHA512             (推荐)
├─ SHA256
├─ SHA1
└─ MD5 (遗留，不安全)

密钥长度:
├─ 256 bit (标准)
└─ 128 bit (弱密钥，不推荐)

5. SPTPS 协议 - 安全的点对点通信

SPTPS 设计目的

SPTPS（Simple Peer-to-Peer Security）是一个轻量级的加密层，用于在 UDP 上建立直接的加密通道，不需要依赖 Meta Protocol 的握手。

与 Meta Protocol 的区别：

Meta Protocol: 文本协议，TCP，用于控制平面
SPTPS: 二进制协议，UDP，用于数据平面持久化会话

SPTPS 记录类型

#define SPTPS_HANDSHAKE 128   // 密钥交换和认证
#define SPTPS_ALERT 129       // 警告或错误消息
#define SPTPS_CLOSE 130       // 应用程序关闭连接

SPTPS 握手状态

typedef enum sptps_state_t {
    SPTPS_KEX = 1,           // 等待第一个密钥交换记录
    SPTPS_SECONDARY_KEX = 2, // 准备接收二次密钥交换
    SPTPS_SIG = 3,           // 等待签名记录
    SPTPS_ACK = 4,           // 等待确认记录
} sptps_state_t;

SPTPS 密钥交换结构

struct sptps_kex_t {
    uint8_t version;           // 版本号
    uint8_t nonce[32];         // 随机数
    uint8_t pubkey[32];        // 临时 ECDH 公钥 (Curve25519)
}
// 总大小: 65 字节

SPTPS 握手流程

Initiator                   Responder
─────────────────────────────────────

生成临时密钥对
(Curve25519 ECDH)

发送 HANDSHAKE ────────────→
  payload: kex1
  (version, nonce, pubkey)

                           收到 kex1
                           生成临时密钥对
                           计算共享密钥

                           ← 发送 HANDSHAKE
                             payload: kex2

收到 kex2
计算共享密钥

验证: ECDH(A_priv, B_pub)
    == ECDH(B_priv, A_pub) ✓

使用 PRF 派生会话密钥

发送签名记录 ───────────────→
  签署握手数据

                           验证签名

                           ← 发送 ACK 记录

验证 ACK
握手完成 ✓

双向 AEAD 加密通信开始

密钥派生

Shared_Secret = ECDH(my_private_key, peer_public_key)

Session_Keys = PRF-SHA512(
    Shared_Secret,
    label = "SPTPS key expansion" 
          + initiator_pubkey 
          + responder_pubkey
)

派生密钥 (共 64 字节):
├─ Key_A (32 字节): Initiator → Responder
├─ Key_B (32 字节): Responder → Initiator
└─ 每个方向使用不同密钥 (前向保密)

6. 身份验证与安全机制

签名与验证

每个节点都有持久的 ECDSA/EdDSA 密钥对：

公钥位置: hosts 目录 ($TINC_HOME/hosts/nodename)
私钥位置: 配置目录 ($TINC_HOME/rsa_key.priv, ed25519_key.priv)

认证流程:
1. 交换 ID → 校验版本
2. 交换 METAKEY → 协商加密算法
3. 计算 challenge hash
4. 发送 CHALLENGE + CHAL_REPLY
5. 验证签名：数据已被对方的私钥签署
6. 发送 ACK

验证公钥:
├─ 从 hosts 目录读取对方的公钥
├─ 验证签名: Verify(signature, data, peer_pubkey)
├─ 若验证失败，拒绝连接
└─ 若验证成功，建立信任

重放保护

Meta Protocol 重放保护：

├─ past_request_tree 跟踪已处理的请求
├─ 相同请求在一定时间内被忽略
└─ 防止攻击者重复发送拓扑更新

数据包重放保护：

├─ 序列号 (seqno): 递增计数器
├─ 验证 seqno > last_seqno
├─ 丢弃重复包
└─ 使用滑动窗口防止乱序问题

7. 拓扑同步协议

完整的拓扑交换过程

当两个节点建立连接后，会进行完整的拓扑交换：

Node A ──────TCP──────→ Node B

1. 身份验证完成
   (ID, METAKEY, CHALLENGE, ACK)

2. Node A 发送其知道的拓扑:
   
   ADD_EDGE nodeA nodeC 10.0.0.3 655 50 0
   ADD_EDGE nodeA nodeD 10.0.0.4 655 100 0
   ADD_SUBNET nodeA 172.16.1.0/24
   ADD_SUBNET nodeC 172.16.2.0/24

3. Node B 发送其知道的拓扑:
   
   ADD_EDGE nodeB nodeE 10.0.0.5 655 50 0
   ADD_SUBNET nodeB 172.16.4.0/24
   ADD_SUBNET nodeE 172.16.5.0/24

4. 每当拓扑变化时：
   └─ 通过 ADD_EDGE/ADD_SUBNET 发布增量更新

5. 当边或节点失败时：
   └─ 广播 DEL_EDGE/DEL_SUBNET

拓扑维护机制

变化检测:
├─ 新节点加入 → ADD_EDGE + ADD_SUBNET
├─ 节点离开 → DEL_EDGE + DEL_SUBNET
├─ 链路权重变化 → ADD_EDGE (新权重)
└─ 密钥更新 → KEY_CHANGED

广播机制:
├─ 每个连接都转发其收到的拓扑消息
├─ 防环：记录消息源，不回复给源
└─ 定期同步：每个连接建立时交换完整拓扑

8. 协议扩展 (Tinc 1.1+)

新增消息类型

REQ_PUBKEY / ANS_PUBKEY

格式: REQ_PUBKEY from to [timestamp]
      ANS_PUBKEY from to [key_data]

用途:
├─ 请求/应答节点的公钥
├─ 用于拓展的密钥交换
└─ 支持在线密钥更新

UDP_INFO

格式: UDP_INFO originator address:port

用途:
├─ 通告节点可用的 UDP 地址
├─ 支持多地址（IPv4, IPv6）
└─ 加速 UDP 直连建立

MTU_INFO

格式: MTU_INFO node mtu

用途:
├─ 通告路径的最大传输单元
├─ 支持 PMTU 发现
└─ 优化包大小

SPTPS_PACKET

用途:
├─ 使用 SPTPS 加密的 TCP 包
├─ 在 meta 协议上层的加密
└─ 增强安全性

9. 安全性分析

已实现的安全特性

特性	实现	说明
前向保密 (PFS)	✓	ECDH 临时密钥，会话独立
数据完整性	✓	HMAC/AEAD 认证
数据机密性	✓	对称加密 (AES/ChaCha20)
重放保护	✓	序列号 + 滑动窗口
身份认证	✓	ECDSA/EdDSA 签名
密钥交换	✓	ECDH (P-256/Curve25519)
已知明文保护	✓	Ping/Pong 随机值

潜在的风险和对策

风险	严重度	现状
密钥重用	中	支持密钥轮换 (KEY_CHANGED)
时钟偏差	低	支持时钟偏差检测
实现漏洞	高	定期安全审计
算法选择	低	支持现代算法 (ChaCha20)
密钥缓存	中	支持定期过期

10. 连接到完整通信的时间线

时间   事件
──────────────────────────────────────────────
0ms    TCP 连接建立
       ↓
10ms   交换 ID (版本协商)
       ↓
20ms   交换 METAKEY (加密参数)
       ↓
30ms   发送 CHALLENGE (单向认证)
       ↓
40ms   接收 CHAL_REPLY (双向认证)
       ↓
50ms   从此以后所有通信加密
       ↓
60ms   交换 ADD_EDGE (拓扑)
       ↓
100ms  交换 ADD_SUBNET (子网)
       ↓
150ms  定期 PING/PONG (保活)
       ↓
∞      数据转发 & 拓扑维护

11. 协议调试

启用协议日志

# 启用详细的协议调试输出
tincd -n myvpn -d DEBUG

# 典型输出示例:
[DEBUG] Sending ID to node1: "0 mynode 17.7"
[DEBUG] Sending METAKEY to node1: cipher=1 digest=3 maclength=16
[DEBUG] Sending CHALLENGE to node1
[DEBUG] Sending ACK to node1
[DEBUG] Sending ADD_EDGE node1 node2 192.168.1.2 655 100 0
[DEBUG] Sending ADD_SUBNET node2 172.16.2.0/24
[DEBUG] Sending PING to node1
[DEBUG] Received PONG from node1

网络包捕获

# 捕获 Meta Protocol (TCP 655)
tcpdump -i eth0 -n tcp port 655

# 捕获 Packet Protocol (UDP 1194)
tcpdump -i eth0 -n udp port 1194

# 使用 Wireshark 分析
wireshark -i eth0

总结

TINC 协议是一个分层的、设计精良的 VPN 协议体系：

核心设计

Meta Protocol (控制平面)：

TCP 文本协议，用于控制和管理
握手、认证、拓扑交换
可靠但相对低频

Packet Protocol (数据平面)：

UDP 二进制协议，用于数据转发
高效、低延迟
支持快速加密/解密

SPTPS (加密层)：

额外的 UDP 加密层
前向保密和轻量级握手
支持直接 P2P 加密通信

安全特性

✅ 现代密钥交换 (ECDH)
✅ 强力数字签名 (ECDSA/EdDSA)
✅ 前向保密 (PFS)
✅ 重放保护
✅ 完整性认证 (HMAC/AEAD)
✅ 灵活的算法选择

性能考虑

Meta Protocol 低频交互，控制开销小
Packet Protocol 用 UDP，转发延迟低
数据密钥缓存，避免频繁协商
支持直接 P2P（避免中继）

这种精心设计的两层协议架构使 TINC 成为一个既可靠又高效的 VPN 解决方案，是现代 VPN 软件的最佳实践。

系列预告

第一篇：TINC 协议深度解析
第二篇：TINC 模块架构与代码组织
第三篇：UDP 打洞机制
第四篇：TINC 项目 - 模块依赖与数据流图

Write A 2048 Game with AI

Mon, 05 Jan 2026 14:51:13 +0800

2048 Game Development Prompt: Professional Stable Edition

Objective

Create a high-performance, mobile-optimized 2048 game in a single HTML file. The goal is “Industrial-Grade Smoothness”—zero flicker, state persistence, and polished mobile UX.

1. Visual & Layout Architecture

Coordinate System:
- Tiles MUST use position: absolute.
- Movement MUST be handled via transform: translate(x, y) using CSS calc().
- Formula: transform: translate(calc(col * (100% + gap)), calc(row * (100% + gap))).
Zero-Flicker Injection:
- When a new tile is created, its transform coordinates must be calculated and set before it is appended to the DOM to prevent “top-left corner flashing.”
Mobile-First CSS:
- Body: padding-top: 5vh to pull the game down from the notch/status bar.
- Container: touch-action: none and overflow: hidden to disable browser pull-to-refresh and scrolling.
- Layout: Center the game board horizontally.

2. Persistence & State Management

Auto-Save: After every move and new tile generation, serialize the 4x4 grid (tile values) and current score to localStorage.
Session Recovery: On page load, check for saved data. If found, rebuild the grid silently (disable the “appear” animation for recovered tiles) so the player can continue exactly where they left off.
Score Tracking: Maintain “Current Score” and a persistent “Best Score.”

3. Core Logic & Animation Sync

Atomic Move Sequence:
1. Calculate: Map out all tile destinations.
2. Visual Slide: Update transform for all moving tiles (including those marked for deletion).
3. Delayed Cleanup: Remove merged tiles from the DOM only after the 150ms transition ends.
4. Merge Pop: Trigger a 1.15x scale pulse on the new tile AFTER the sliding tiles overlap.
Animation Lock: Use a lock flag to ignore inputs for 200ms during active animations.
Win/Loss Detection:
- Win: Detect value 2048 and show a “You Win” overlay.
- Loss: If the grid is full AND no adjacent tiles (horizontal/vertical) match, show a “Game Over” overlay.

4. Interaction & UX Polish

Play the game below or goto this link:

AI on 云淡风轻

TINC 源码解读 第四篇 - 模块依赖与数据流图

1. 文件分类一览表

1.1 核心应用程序

1.2 协议处理模块

1.3 连接与加密

1.4 节点与拓扑

1.5 网络 I/O

1.6 设备驱动

1.7 密码学

1.8 事件与控制

1.9 配置与工具

1.10 数据结构

2. 模块依赖关系

2.1 依赖层级图

2.2 模块间调用关系

3. 核心数据流图

3.1 连接建立流程

3.2 数据包转发流程

3.3 拓扑同步流程

4. 关键数据结构速查

4.1 node_t (节点)

4.2 edge_t (链路)

4.3 subnet_t (子网)

4.4 connection_t (连接)

4.5 sptps_t (SPTPS 加密)

5. 常见代码模式

5.1 创建新节点

5.2 添加子网

5.3 发送协议消息

5.4 注册事件回调

5.5 路由查询

5.6 图算法 (Dijkstra)

6. 构建与运行

6.1 编译

6.2 启动 VPN 节点

6.3 控制工具使用

7. 关键编译标志

8. 调试技巧

8.1 启用详细日志

8.2 数据包捕获

8.3 追踪连接

8.4 性能分析

9. 常见问题排查

问题 1: 节点无法连接

问题 2: 高延迟

问题 3: 密钥/签名错误

问题 4: 内存占用持续增长

10. 性能优化点

关键优化

性能指标

11. 模块学习路径建议

初学者路径

进阶路径

12. 快速定位代码

按功能查找

按数据结构查找

13. 相关资源

总结

关键特点

学习建议

系列预告

TINC 源码解读 第三篇 - UDP 打洞

1. UDP 打洞概览

问题背景

核心概念

2. TINC 中的 UDP 打洞机制

节点状态位

关键状态变量

3. UDP 打洞流程

详细步骤

步骤 1: TCP 握手连接

步骤 2: 交换拓扑信息

步骤 3: 密钥交换

步骤 4: UDP 打洞 (关键阶段)

步骤 5: 直接 UDP 通信

代码流程示意

4. 地址缓存机制

缓存结构

缓存操作

TINC 源码解读第四篇 - 模块依赖与数据流图

TINC 源码解读第三篇 - UDP 打洞

TINC 源码解读第二篇 - 模块架构与代码组织

`tincd.c` - 主守护进程

`tincctl.c` - 控制工具

`info.c` 和 `fsck.c`

`control.c` - 控制连接管理

`script.c` - 脚本执行

`event.c` - 事件循环

`protocol*.c` - 协议处理

`sptps.c` - 安全协议握手

`connection.c` - 连接管理

`net*.c` - 网络 I/O

`route.c` - 路由管理

`graph.c` - 拓扑算法

`proxy.c` - 代理支持

`node_t` (节点)

`edge_t` (边/链路)

`subnet_t` (子网)

`connection_t` (连接)