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 项目 - 模块依赖与数据流图

Reference on 云淡风轻

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