ifly

ifly 是一个给本机程序提供固定本地代理入口的双入口链式代理。

它默认提供两个本地入口：

• HTTP：127.0.0.1:8341
• SOCKS5：127.0.0.1:8342

也支持把这两个入口配置成同一个端口，让一个端口同时接受 HTTP 和 SOCKS5。

适合这类场景：

• 你想让某个本机程序始终走一个固定、可控、只影响它自身的代理入口
• 你平时会开 Surge / Clash / Stash / sing-box 等本地代理客户端，但不想把远端节点直接塞进客户端里
• 你希望本地代理客户端可用时走完整链路，不可用时还能自动回退继续工作

安装

npm install -g @aisymbiote/ifly

当前 npm 包首发支持：

• macOS
• Apple Silicon（darwin-arm64）

安装后默认配置文件路径：

~/ifly/config.yaml

如果安装脚本没有自动生成配置模板，可以手动执行：

ifly init

快速开始

1）准备配置

默认配置文件：

~/ifly/config.yaml

你至少需要配置好 local_proxies 或 remote_proxies 中的至少一项。

• 只配 local_proxies：ifly 会走 inbounds -> local_proxies -> target
• 只配 remote_proxies：ifly 会走 inbounds -> remote_proxies -> target
• 两者都配：优先走 inbounds -> local_proxies -> remote_proxies -> target

如果上游代理不需要认证，把模板里的认证字段改成：

username: ""
password: ""

如果你平时会开 Surge / Clash / Stash / sing-box，也建议把它们的本地监听端口填进 local_proxies。

如果你想只暴露一个本地入口，也可以把 inbounds 里的 http-in.port 和 socks-in.port 都设成同一个值，比如都设成 8341。

模板示例见：

examples/config.example.yaml

最小配置可以参考这三种：

1. 只用本地代理客户端：

inbounds:
  - name: http-in
    protocol: http
    host: 127.0.0.1
    port: 8341

  - name: socks-in
    protocol: socks5
    host: 127.0.0.1
    port: 8342

local_proxies:
  - name: local-http
    protocol: http
    host: 127.0.0.1
    port: 6152
    priority: 0

2. 只用远端专用代理：

inbounds:
  - name: http-in
    protocol: http
    host: 127.0.0.1
    port: 8341

remote_proxies:
  - name: remote-http
    protocol: http
    host: 1.2.3.4
    port: 50100
    username: ""
    password: ""
    priority: 0

3. 本地代理客户端 + 远端专用代理：

inbounds:
  - name: http-in
    protocol: http
    host: 127.0.0.1
    port: 8341

local_proxies:
  - name: local-http
    protocol: http
    host: 127.0.0.1
    port: 6152
    priority: 0

remote_proxies:
  - name: remote-http
    protocol: http
    host: 1.2.3.4
    port: 50100
    username: ""
    password: ""
    priority: 0

2）前台运行

ifly dev

如果你已经有一份配置文件，想导入为默认配置再运行：

ifly dev \
  -config /path/to/config.yaml

3）验证是否可用

HTTP：

curl -x 'http://127.0.0.1:8341' \
  'https://checkip.amazonaws.com'

SOCKS5：

curl -x 'socks5h://127.0.0.1:8342' \
  'https://checkip.amazonaws.com'

常用命令

初始化默认配置：

ifly init

导入一份配置到默认位置：

ifly init \
  -config /path/to/config.yaml

前台运行：

ifly dev

安装成 macOS 用户级常驻服务：

ifly install \
  -config /path/to/config.yaml

查看状态：

ifly status

实时查看事件日志：

ifly log

重启常驻服务：

ifly restart

卸载常驻服务：

ifly uninstall

文件位置

默认配置：

~/ifly/config.yaml

LaunchAgent plist：

~/Library/LaunchAgents/com.ifly.plist

日志：

~/ifly/logs/ifly.log
~/ifly/logs/ifly.err.log

运行状态与事件订阅：

~/ifly/state/status.json
~/ifly/state/events.sock

常见提示

• init -config PATH 和 dev -config PATH 都会把那份配置导入到默认配置路径，不是临时切换配置文件。
• ifly 启动时只做配置语法/结构校验；像 your-port 这种不是合法端口号的值仍然会失败。
• 测试 SOCKS5 时建议用 socks5h://，让域名通过 SOCKS5 传递，而不是由 curl 在本地先解析。
• 对 localhost、127.0.0.1 和明确的私网/链路本地 IP 目标，ifly 会自动直连，不再送进远端代理链。

更多文档

• 想看链路选择、健康检查、fallback 回切、状态语义等技术细节： TECHNICAL_SUMMARY.md
• 想看演进历史： DEVELOPMENT_HISTORY.md
• 想看原始设计/方案材料： 双入口代理链自动选择方案.md
• 想看项目动机背景： ifly.md