ii

面向临时跨设备文件流动、局域网共享和轻量网络联调的跨平台 CLI 工具箱。

简体中文 · English

ii 以临时跨设备文件流动为核心，并提供局域网共享、临时访问和网络联调能力。它不是云盘、长期 NAS 或生产级代理平台。

核心传输使用 ii send / ii recv：无需预先部署服务器，优先走局域网或公网 P2P 直连；无法直连时才使用 Iroh 默认的 n0 relay。接收方只需拿到 ticket。

• 发送文件、目录、多文件和管道数据；接收支持断点续传、同 MD5 跳过和冲突覆盖。
• 支持发送端校验和、单文件 metadata 保留、符号链接策略、FIFO 队列和目录监视。
• 需要中转时，可使用通用 S3、Cloudflare R2、Azure Blob、WebDAV、FTP 或 SFTP，并可在接收后删除对象。

• 用 ii web 分享目录、下载或接收浏览器上传；ii http 提供只读目录，ii drop 提供只上传收集箱，ii paste 分享短文本。
• 用 ii dav 把目录作为 WebDAV 网络磁盘提供，用 ii ftp 提供 FTP/FTPS 兼容服务。
• 用 ii webrtc 在同一局域网的浏览器之间直传文件和文本；ii discover 可发现同网段正在运行的 ii 服务。

• 用 ii tunnel 通过 Iroh 暴露本机 TCP 服务；需要固定中继时可运行 ii relay。
• 用 ii socks5、ii proxy 和 ii pac 提供代理接入和代理规则分发。
• 用 ii tcp、ii udp 转发到固定目标，适合短期联调和端口映射。

• ii ping、ii port、ii health 分别用于 TCP 延迟、端口和服务健康检查。
• ii speed 测量真实局域网吞吐，ii wake 发送 Wake-on-LAN 魔术包。
• ii test 分阶段测试 SOCKS5、HTTP 或 HTTPS 代理的端口连接、目标访问和延迟。

Linux x86_64 和 Apple Silicon macOS：

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/zengyufei/ii/master/install.sh | bash

默认安装到 ~/.local/bin/ii；设置 II_INSTALL_DIR 可指定安装目录。Windows x64 请从 GitHub Releases 下载。所有发布资产和校验和也可在 Releases 获取。

发送端：

ii send .\video.mp4

ii 会输出一段 ticket：

ii ticket:
ii1k7v...x9a

on the other computer:
ii recv ii1k7v...x9a

接收端：

ii recv ii1k7v...x9a

发送端和接收端的实际样子：

# 文件
ii send .\report.pdf

# 目录；接收为 <输出目录>\my-folder
ii send .\my-folder

# 多个文件或目录；接收为 <输出目录>\ii
ii send .\report.pdf .\images .\notes.txt

# 指定多文件集合的根目录名
ii send .\report.pdf .\images --name release

多文件会打包为一个 tar 流，旧版接收端仍按目录 tar 接收。多个输入项的顶层名称不能重复。

# 管道输入需要指定接收文件名
tar czf - .\project | ii send --name project.tar.gz

# 只发送匹配文件；exclude 优先于 include
ii send .\project --include "**/*.rs" --exclude "target/**"

# 所有接收端共享 8 MiB/s 总发送带宽
ii send .\video.mp4 --rate 8MiB

--include 和 --exclude 可重复使用，匹配输入目录内以 / 分隔的相对路径；它们不适用于 --web。--rate 接受 bytes/s、KiB、MiB、GiB，也限制网页下载和各中转后端的发送流量。

# 持续提供同一 ticket
ii send .\my-folder -t

# 复制接收命令或写入文件
ii send .\video.mp4 -c
ii send .\video.mp4 -o recv.txt

# 面向自动化的 JSON Lines
ii send .\video.mp4 --json

# 输出实际发送字节的校验和
ii send .\video.mp4 --checksum sha256

# 单文件保留 mtime、权限和只读属性
ii send .\video.mp4 --preserve-metadata

普通 ii send 在首次成功发送后退出。-t 最多同时服务 16 个接收端，另有最多 1000 个 FIFO 排队连接；并发接收共享发送端带宽，满队列时稍后重试。--json 时 stdout 只输出 JSON Lines。

--checksum md5|sha256 只在本地计算并输出实际发送字节，不写入 ticket，也不自动和接收端比较。--preserve-metadata 只适用于单个常规文件，会使用现有 tar 载荷，因此不支持 stdin、--web、断点续传和 MD5 秒传。

ii queue .\a.zip .\b.zip
ii queue .\report.pdf --after 10s
ii queue .\folder --every 1h
ii watch .\incoming --interval 2s --stabilize 2s

queue 和 watch 只在当前进程内排队，不持久化；它们接受 --rate、后端、relay、--local、--no-relay、--checksum、--preserve-metadata 和 --symlinks，不接受 -t、-c、-o、--web 或 --json。--quic-port <1..65535> 可固定 P2P 的 Iroh UDP 端口。

--profile <name> 选择后端配置；S3、R2 和 Azure ticket 只包含对象 URL，接收端无需本机配置。-p 将 WebDAV、FTP 或 SFTP 凭据写入 ticket，ticket 未加密，只能交给可信接收方；-d 在接收成功后尝试删除中转对象。SMB/NFS 已挂载目录可直接作为本地发送路径，不提供原生中转。配置和协议限制见 ii.md、ftp.md、sftp.md。

# 指定保存目录
ii recv ii1k7v...x9a -o D:\Downloads

# 输出到标准输出
ii recv ii1k7v...x9a --stdout > project.tar.gz

# 面向自动化的 JSON Lines
ii recv ii1k7v...x9a --json

断网或传到一半失败后，重新执行同一条 ii recv 就会继续接收；如果目标文件已经完整且内容相同，会直接跳过；如果同名但内容不同，会覆盖。ii send 和 ii recv 都会显示传输进度、速率和完成耗时；ii recv --trace 输出建连阶段、最终直连或 relay 路径和 RTT。--stdout 不能与 --json 同用。

--checksum md5|sha256 在接收完成后计算实际文件或目录 tar 流；不能与 --stdout 同用。--quic-port 只适用于 P2P ticket。

# 为一个文件或目录提供下载页
ii send .\video.mp4 --web

# 浏览目录；加 --upload 后允许上传独立文件
ii web .\shared --upload --path .\uploads

# 用系统文件管理器挂载目录；默认可读写
ii dav .\shared
ii dav .\shared --read-only
ii dav .\shared --port 8443 --username alice --password secret --tls --domain dav.example.com --cert D:\certs\fullchain.pem --key D:\certs\privkey.pem

ii send --web 为单个文件或目录提供下载页。默认第一个完整 /download 响应写完后立即退出；加 -t 才持续服务到 Ctrl+C，并发下载时第一个完成会直接结束进程。访问下载页、上传和失败下载不会退出。ii web 显示 nginx 风格目录列表，省略目录时服务当前目录；--upload 才开放多文件上传，默认写入启动目录的 ./ii/，--path <dir> 可改为指定目录。网页上传按 1 MiB 分块写入，断网或刷新后重新选择同一文件会自动继续。ii dav 直接读写所服务目录，不使用网页上传目录。

ii dav --username <username> --password <password> 启用 HTTP Basic Auth，两个参数必须同时提供。--password 会出现在 shell 历史和进程列表中，只适合你明确接受这一风险的场景。--tls 开启 HTTPS；未提供 --cert 与 --key 时生成仅当前进程有效的自签证书，客户端必须手动信任。公网请使用受信任 PEM 证书，或让 HTTPS 反向代理终止 TLS 并将 ii dav 绑定到 127.0.0.1。未启用 --tls 时，Basic Auth 凭据会以明文传输。

--port 8080 固定端口，--bind :: 只监听 IPv6；裸 --token 生成路径令牌，--token <value> 使用指定令牌。路径 token 不是账号鉴权。

ii web --once 只在第一次完整的普通文件 GET 200 后退出；HEAD、Range、目录页、404 和上传不会消耗这次机会，且不能和 --upload 同用。

# 共享当前目录，默认监听 0.0.0.0:21
ii ftp

# 指定目录、账号密码、总带宽和连接上限
ii ftp .\shared --port 2121 --username alice --password secret --rate 8MiB --max 20

# 显式开启主动和被动模式；PASV 返回指定地址和端口范围
ii ftp .\shared --passive-host 192.168.1.20 --passive-ports 49152-49200

# 关闭单项操作权限
ii ftp .\shared --upload false --delete false --rename false

# 显式 FTPS：控制和数据通道均强制 TLS；未给证书时生成临时自签证书
ii ftp .\shared --tls
ii ftp .\shared --tls --cert D:\certs\fullchain.pem --key D:\certs\privkey.pem

# 隐式 FTPS：连接后立即 TLS 握手；未指定端口时使用 990
ii ftp .\shared --tls --implicit

ii ftp 共享当前目录或一个已有目录。默认匿名登录、最大 100 个控制连接、不限速，允许上传、下载、删除、改名和新建目录。默认仅主动模式，不监听被动数据端口；提供 --passive-ports [start-end] 后主动和被动模式同时可用，未给范围使用 49152-65535，--passive-host 只能与它同用。--rate 限制全部上传和下载连接共享的总带宽；--delete false 同时禁用文件和目录删除，--download false 只禁用 RETR，目录浏览和元数据查询仍可用。0.0.0.0 仅是监听地址，终端会输出主 LAN IPv4 FTP 地址和 other: 网卡地址。

--tls 开启并强制 FTPS：默认是显式模式，客户端在明文 FTP 欢迎语后发送 AUTH TLS，默认端口仍为 21。不提供 --cert 与 --key 时，服务只为当前进程生成自签证书，客户端需要自行接受该证书；已有 PEM 证书链和私钥时必须成对提供。--implicit 只能和 --tls 一起使用，客户端连接后立即进行 TLS 握手，未指定 --port 时使用 990。单独指定 --port 990 不会切换到隐式模式。-k 不是 FTP 服务端参数。

# 只读目录站；支持浏览、Range、媒体播放和下载
ii http .\public

# 文字剪贴板；无参数时从 stdin 读取，raw 返回纯文本
ii paste "meeting code: 123456" --ttl 30m
Get-Content .\note.txt -Raw | ii paste --token

# 纯上传收集箱；默认写到启动目录的 .\ii\
ii drop .\incoming

# 为现有 HTTP/SOCKS5 代理托管 PAC 文件
ii pac --proxy socks5://192.168.1.10:1080

# 局域网吞吐测试服务端和客户端
ii speed serve --port 9000
ii speed http://192.168.1.10:9000/ --duration 15s

ii http 没有上传和写入接口；ii drop 只有多文件上传和断点续传，不列目录也不提供下载，指定目录直接作为上传目录。ii paste 根页可复制内容，raw 返回 text/plain，--ttl 到期自动关闭。ii pac 根 URL 返回 PAC 文件，内网、回环、.local 和无点主机名走 DIRECT，其他目标走指定代理。它们都支持 --port、--bind、--token [value]，终端输出二维码、LAN URL 和 other:；也会被 ii discover 发现。

# 列出同一 LAN 中的 ii send -t、web/dav 和轻量 HTTP 服务
ii discover

# 输出 JSON Lines
ii discover --json

发现等待三秒，只在本地网络内工作；公告会暴露 ticket 或 token URL，不是访问控制。

ii webrtc

ii webrtc 打开网页后可在两台浏览器之间传文件和文本。它同样支持 --port、--bind 和 --token。限制见 webrtc.md。

# A：让持有 ticket 的设备访问 A 可连接的服务
ii tunnel -s 127.0.0.1:22

# B：使用 A 输出的 ticket
ii tunnel -c ii1k7v...x9a

B 默认监听 127.0.0.1:8080，端口被占用时自动递增；--listen 0.0.0.0:8022 才会暴露给 B 的局域网。流量经 Iroh 端到端加密，ticket 持有者可访问目标直到 A 停止服务。完整用法见 ii.md。

ii socks5
ii socks5 --port 1080 --username alice --password secret

ii socks5 是独立的普通网络代理，默认监听 0.0.0.0 的随机端口并打印实际地址。支持 SOCKS5 CONNECT、UDP ASSOCIATE、BIND、IPv4、IPv6 和域名目标；不经过 Iroh、ticket 或 relay。CONNECT 的域名目标会在同一个 30 秒总时限内并发尝试代理端 DNS 返回的全部地址。提供 --username 与 --password 时启用 SOCKS5 用户名密码认证，两个参数必须成对出现。为避免公网半开连接耗尽资源，默认最多 100 个活动连接，10 秒内必须完成握手，CONNECT 隧道连续 5 分钟无数据会关闭；任一方向关闭后，另一方向最多 5 秒收尾，避免半关闭连接长期占用资源。达到 --max 时，新的 TCP 连接留在监听队列中等待容量释放，而不会被应用层立即关闭。

SOCKS5 流量和 RFC 1929 用户名密码认证均为明文，认证只限制访问，不提供加密。裸 SOCKS5 暴露到公网可能被扫描或被网络路径干扰，不能保证绕过协议识别或干扰；需要加密公网代理时，使用现有 ii proxy --tls、VPN 或 SSH 隧道。

普通传文件不需要自建 relay。需要固定中继入口时：

# HTTP relay
ii relay --port 8443
ii send .\video.mp4 --relay http://服务器公网IP:8443

# 临时自签 HTTPS relay
ii relay --tls --port 8443
ii send .\video.mp4 --relay https://服务器公网IP:8443 -k

# 使用已有 PEM 证书
ii relay --tls --domain relay.example.com --port 8443 --cert D:\certs\fullchain.pem --key D:\certs\privkey.pem
ii send .\video.mp4 --relay https://relay.example.com:8443

省略 --port 时随机监听。终端打印实际可用的 IPv4 URL；0.0.0.0 只用于监听，云服务器公网 IP 可能需要从控制台取得。-k 仅用于自签 HTTPS；指定 HTTP 或 HTTPS relay 后，传输强制经过该 relay。重复指定 --relay 时，ii send 探测各显式 relay 的可达性和延迟，选取最快可达节点；不影响默认 n0 relay。完整 TLS、NAT 与安全边界见 ii.md。

# 查看接收路径和耗时
ii recv ii1k7v...x9a --trace

# 检查本机网络、端口、权限和版本
ii doctor
ii doctor --nat
ii version

ii doctor --nat 会运行一次短生命周期 UDP/NAT/relay 探测，输出实际 UDP socket、IPv4/IPv6、NAT 映射、首选 relay 和 relay 在线结果；Iroh 未公开 hairpin 探测时会明确标记为不可用。

# HTTP/HTTPS 正向代理；可选 Basic 认证
ii proxy --port 8080
ii proxy --username alice --password secret
ii proxy --port 8443 --tls --domain proxy.example.com
ii proxy --port 8443 --tls --cert .\fullchain.pem --key .\privkey.pem

# 将本地 TCP/UDP 端口转发到固定目标
ii tcp db.internal:5432 --port 15432
ii udp game.internal:27015 --port 27015

# TCP connect 探测、端口检查、持续健康检查
ii ping api.example.com:443 --count 4
ii port api.example.com 80 443 8443
ii health https://api.example.com/health --interval 10s

# 发送 Wake-on-LAN 魔术包
ii wake aa:bb:cc:dd:ee:ff --broadcast 192.168.1.255

ii proxy 支持 HTTP/1.0、HTTP/1.1 absolute-form 请求与 CONNECT。--tls 只加密客户端到代理的连接，HTTPS 目标仍通过 CONNECT 隧道转发，代理不解密目标 TLS。未提供证书时生成仅当前进程有效的自签证书；提供 --cert 与 --key 时加载 PEM 证书链和私钥。--domain 用于证书 DNS 名称和输出 URL；-k 不适用于 ii proxy。ii tcp 和 ii udp 是固定目标转发器；UDP 按客户端地址维护上游会话，空闲五分钟清理。ii ping 是 TCP connect 延迟探测，不发送 ICMP；ii port 并发检查 TCP 端口；ii health 对 HTTP(S) 仅将 2xx/3xx 视为健康，或检查裸 host:port 的 TCP 连通性。

ii test https://google.com --socks5 127.0.0.1:10808
ii test https://google.com --http 127.0.0.1:8080
ii test https://google.com --https proxy.example.com:8443

ii test 会依次测试代理端口、通过代理访问目标 URL，以及代理连接延迟；失败项仍会继续执行，任一项失败时退出码非零。--https 表示 TLS 包裹的 HTTP 代理并严格校验证书；--username 与 --password 可为 SOCKS5 或 HTTP/HTTPS 代理提供认证。

完整命令、配置和故障排查见 ii.md。

CHANGELOG.md · CHANGELOG.en.md

版本以 GitHub Release 和 Git tag 为准。

MIT License，见 LICENSE。