Module 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 源码解读第二篇 - 模块架构与代码组织

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

Module 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 源码解读 第二篇 - 模块架构与代码组织

1. 项目概述

2. 分层架构概览

3. 模块详细说明

3.1 应用层 (Application Layer)

tincd.c - 主守护进程

tincctl.c - 控制工具

info.c 和 fsck.c

3.2 控制层 (Control Layer)

control.c - 控制连接管理

script.c - 脚本执行

event.c - 事件循环

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

protocol*.c - 协议处理

sptps.c - 安全协议握手

connection.c - 连接管理

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

net*.c - 网络 I/O

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

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` (连接)