SIP003 插件

概述

本文档描述了 Shadowsocks Windows 客户端中的 SIP003 插件系统，该系统允许通过外部程序扩展代理功能。SIP003 规范定义了 Shadowsocks 客户端与插件程序交互的标准方式，这些插件程序可以在加密前修改网络流量。

有关通用代理系统的信息，请参阅代理服务。

插件基础

SIP003 (Shadowsocks 插件协议 03) 是一种标准化的插件接口，允许第三方开发者创建在 Shadowsocks 加密之前转换流量的插件。这些插件可以提供额外的功能，例如流量混淆、协议转换或额外的加密层。

插件作为独立的进程运行，由 Shadowsocks 客户端生成和管理。Shadowsocks 和插件之间的通信通过标准化的环境变量和本地网络连接进行。

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs1-176

插件架构

插件架构遵循代理链模型，其中插件充当 Shadowsocks 客户端和服务器之间的中介。

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs12-46

实现细节

SIP003 插件系统在Sip003Plugin 类中实现，负责插件进程的创建、管理和通信。

类结构

Sip003Plugin: 主类，实现了IDisposable 并管理插件进程的生命周期
主要属性
- LocalEndPoint: 插件监听的本地端点
- ProcessId: 运行中插件进程的 ID

插件进程创建

插件使用静态方法CreateIfConfigured 创建，该方法检查服务器是否配置了插件，并在需要时创建一个新的插件实例

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs12-46 shadowsocks-csharp/Controller/Service/Sip003Plugin.cs80-121

插件通信协议

环境变量

SIP003 协议使用环境变量在 Shadowsocks 和插件进程之间传递配置。

环境变量	描述
`SS_REMOTE_HOST`	远程服务器地址
`SS_REMOTE_PORT`	远程服务器端口
`SS_LOCAL_HOST`	插件监听的本地地址
`SS_LOCAL_PORT`	插件监听的本地端口
`SS_PLUGIN_OPTIONS`	插件特有选项字符串

这些环境变量在启动插件进程时设置，使其能够知道连接和监听的位置。

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs57-76

插件生命周期管理

启动插件

StartIfNeeded 方法负责在插件进程未运行时启动它

检查插件是否已在运行
为插件获取一个空闲的 TCP 端口以供监听
设置环境变量
启动插件进程
将进程添加到 Job 对象以进行生命周期管理

Job 对象确保如果 Shadowsocks 进程意外退出，插件进程也会被终止。

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs80-121

清理

当 Shadowsocks 客户端退出或服务器配置更改时，Dispose 方法会被调用以清理插件资源

如果插件进程仍在运行，则将其终止
等待进程退出
释放进程和 Job 资源

这确保了正确的清理，并防止出现孤立的插件进程。

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs147-174

插件配置

插件在服务器设置中通过三个关键参数进行配置

plugin: 插件可执行文件的路径
plugin_opts: 包含插件特有选项的字符串
plugin_args: 插件的命令行参数

字符串plugin_opts 通过SS_PLUGIN_OPTIONS 环境变量传递给插件，而plugin_args 则直接作为命令行参数传递。

插件参数支持变量扩展，允许使用环境变量和插件特有变量进行动态配置。

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs123-136

实现细节：网络

当插件启用时，Shadowsocks 会改变其网络流量流向

Shadowsocks 不再直接连接到远程服务器，而是连接到插件的本地端点
插件处理流量并将其转发到远程服务器
这形成了一个链：客户端 → Shadowsocks → 插件 → 远程服务器

插件的本地端点会自动选择一个空闲的 TCP 端口，通过使用GetNextFreeTcpPort 方法，该方法会创建一个临时 TCP 监听器来查找可用端口。

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs138-145

错误处理

插件系统包括多种错误处理机制

插件可执行文件的“文件未找到”错误会被专门检测并以用户友好的消息报告
插件进程在 Job 对象中进行管理，以确保清理
即使在插件执行期间发生错误，也能正确释放资源

这确保了插件故障能得到妥善处理，并且不会导致资源泄漏。

来源：shadowsocks-csharp/Controller/Service/Sip003Plugin.cs100-115 shadowsocks-csharp/Controller/Service/Sip003Plugin.cs147-174

插件进程输出

插件系统支持可选地显示插件的控制台输出，这对于调试很有用

当showPluginOutput 设置为true 时，插件的控制台窗口可见
否则，插件在后台静默运行

这由CreateNoWindow 和WindowStyle 属性的ProcessStartInfo 对象控制。