🌐 vpn代理插件（astrbot_plugin_vpn_proxy） v2.2.0

VPN 节点代理管理插件：管理 VLESS / SS / VMess / Trojan / SOCKS5 / HTTP / WireGuard 节点与订阅， 为 AstrBot 模型 API 请求提供 VPN 加速。谁填代理地址谁走 VPN，不填走正常流量。

✨ 特性

• 7 种协议支持：vless、ss、vmess、trojan、socks5、http、wireguard（手动添加 / 订阅导入 / 面板模板均可）
• 节点延迟测试：面板一键测速（TCP 三次取平均，毫秒显示），快速筛选最快节点
• 订阅管理：粘贴订阅链接自动解析节点，一键更新全部订阅
• 统一代理地址：输出 http://127.0.0.1:10809（HTTP 代理，兼容性最好，不要用 socks 地址）
• 按提供方分流：在模型提供方「高级配置 → 代理地址」填了就走 VPN，不填走直连
• 独立管理界面：深色 Web UI（节点/订阅/服务控制/测速），无需指令
• xray 进程托管：一键启动 / 停止 / 重启，添加节点后自动重启生效

📦 安装

1. 将 astrbot_plugin_vpn_proxy 目录放入 /AstrBot/data/plugins/
2. AstrBot 面板 → 插件管理 → 重载插件（或 POST /api/v1/plugins/astrbot_plugin_vpn_proxy/reload 热重载）
3. 启用插件，在配置页填写 xray_path（默认 /AstrBot/data/openrouter_proxy/xray/xray）

🚀 快速开始（三步）

第 1 步：添加节点

方式A - 订阅导入（推荐）：面板 → 插件页 → 订阅 → 粘贴链接拉取，或指令 #代理 订阅 <URL>

方式B - 手动添加（指令，竖线分隔，key=value 为可选参数）：

#代理 节点添加 vless|美国|1.2.3.4|443|uuid=你的UUID|sni=example.com|pbk=公钥|fp=chrome
#代理 节点添加 ss|香港|1.2.3.4|8388|method=chacha20-ietf-poly1305|password=密码
#代理 节点添加 vmess|日本|5.6.7.8|443|uuid=xxx|network=ws|ws_path=/path|ws_host=xx.com
#代理 节点添加 trojan|新加坡|9.9.9.9|443|password=xxx|sni=example.com
#代理 节点添加 socks|测试S5|1.2.3.4|1080|username=u|password=p
#代理 节点添加 http|测试HP|1.2.3.4|8080|username=u|password=p
#代理 节点添加 wireguard|测试WG|1.2.3.4|51820|public_key=对端公钥|private_key=本机私钥|ip=10.0.0.2/32

方式C - 面板配置：插件配置页 → vpn_servers → 选协议模板（含 vless/ss/vmess/trojan/socks/http/wireguard）添加。

第 2 步：测速并启动

#代理 节点切换 美国     # 设为默认节点（自动重启 xray）
#代理 启动             # 若未自动启动
#代理 状态             # 查看运行状态 / 代理地址

面板上点每行的「测速」按钮即可看延迟（单位 ms，显示「超时」表示连不通）。

第 3 步：在提供方填写代理地址

1. AstrBot 面板 → 模型提供方 → 选择要走 VPN 的提供方
2. 高级配置 → 代理地址 填写：http://127.0.0.1:10809
3. 保存即生效（无需重启）。该提供方的所有 API 请求自动走 VPN 节点

⚠️ 注意：代理地址必须是 http 开头（http://127.0.0.1:10809）， 不要填 socks5://127.0.0.1:10808 —— 部分提供方不认 socks 协议，HTTP 代理兼容性最好。 其他提供方不填代理地址，走正常流量。

🖥 独立管理界面

插件自带独立页面：AstrBot 面板 → 插件 → vpn代理插件 → manage 选项卡。

功能	说明
状态卡	运行状态 / 节点数量 / 代理地址
节点管理	添加（面板模板）/ 删除 / 设为默认 / 测速
订阅管理	添加订阅链接、一键更新全部订阅
服务控制	启动 / 停止 / 重启 xray

后端 API（均需 JWT 认证，挂在 /api/v1/plugins/extensions/astrbot_plugin_vpn_proxy/）： status、nodes、node/add、node/del、node/switch、node/ping（延迟测试）、sub/add、sub/update、control

🎛 配置项说明（插件配置页）

配置项	说明
socks_port	socks5 端口，默认 10808
http_port	http 代理端口，默认 10809（对外统一用这个）
xray_path	xray 可执行文件路径
vpn_servers	节点列表（面板/指令添加自动同步）
subscriptions	订阅链接列表

📖 指令一览（管理员）

指令	说明
#代理 状态	运行状态 / 代理地址 / 当前节点
#代理 启动 / 停止 / 重启	xray 进程管理
#代理 节点	节点列表
#代理 节点添加 <类型>|<备注>|<地址>|<端口>[参数...]	手动添加节点（7 种协议）
#代理 节点删除 <备注/序号>	删除节点
#代理 节点切换 <备注/序号>	设为默认节点
#代理 订阅 <URL>	导入订阅
#代理 订阅	查看已添加订阅
#代理 地址	显示代理地址

别名：#vp / #vpn / #proxy

🔧 节点字段说明

通用：type(协议) remark(备注) address port default(默认节点)

• vless：uuid flow sni public_key(pbk) fingerprint(fp) short_id(sid)
• ss：method(如 chacha20-ietf-poly1305) password
• vmess：uuid alter_id security network(tcp/ws) ws_path ws_host
• trojan：password sni flow
• socks / http：username(可空) password(可空)
• wireguard：public_key(对端公钥) private_key(本机私钥) ip(本机虚拟IP) sni(可空)

⚠️ 订阅 URL 形式支持：vless:// ss:// vmess:// trojan:// socks:///socks5:// http://(带认证) wireguard://。 hysteria2 / tuic 不支持（xray 内核不支持，需要 sing-box，解析时会明确报错提示）。

⚠️ 注意事项

1. AstrBot 重启后 xray 不会自动拉起：若代理失效，用面板服务控制 / #代理 启动 拉起即可。
2. 更新插件代码：用 POST /api/v1/plugins/astrbot_plugin_vpn_proxy/reload 热重载即可，不要重启整个 AstrBot（容器 pid1 不可 kill）。
3. 热重载只刷新代码，不刷新元数据：若改了 metadata.yaml（版本/显示名/图标），需清理 /tmp/astrbot_plugin_vpn_proxy 残留副本后完整重启 AstrBot 才会在插件列表显示。
4. 若换 xray 路径，需在配置页同步修改 xray_path。

🐛 故障排查

• xray 启动失败：查看 data/xray/xray.log
• 节点连不上：面板「测速」看延迟，换节点后重启
• 提供方报错：确认填的是 http://127.0.0.1:10809（http 开头），不是 socks
• hysteria2 节点添加失败：该协议需 sing-box，当前内核不支持，换用 vless/vmess/trojan/ss/socks