Zorven 文档

安装

Zorven 客户端是一个单独的二进制文件（zorven）。安装脚本会下载它，将你的令牌和服务器地址写入系统配置，并启动后台服务。

Linux 和 macOS

脚本会安装到 /usr/local/bin/zorven，由于要创建系统服务，需要 root 权限。从控制台获取令牌（参见快速入门），并通过参数传入：

如果省略令牌，脚本会提示你输入。如需在运行前先阅读脚本：

Windows

以管理员身份打开 PowerShell。脚本会安装到 C:\Program Files\Zorven 下，并启动 Windows 服务：

如需先检查脚本，请将 irm https://zorven.app/install.ps1 的输出保存为文件后阅读。

桌面应用

Windows 图形化安装程序：Zorven-Setup-windows-amd64.exe。详情及其他平台请参见下载页面。

手动下载

如果不想使用脚本，可以直接下载二进制文件，赋予可执行权限，并放到 PATH 中的某个目录。

当前版本列在 /bin/manifest.json 中。客户端可以自行更新；传入 --no-auto-update 可关闭此功能。

快速入门

1. 注册并创建令牌 打开控制台，创建一个客户端并复制它的客户端令牌（以 zrv_live_ 开头）。令牌是设备身份凭据，请妥善保密。
2. 保存令牌
   $zorven authtoken zrv_live_...

   复制
3. 发布本地端口
   $zorven http 3000

   复制
   输出中的 https://<name>--slug.zorven.app 地址会立即生效，并带有有效的 TLS 证书。WebSocket、HTTP/2 和 SSE 均可使用。客户端会打印一个状态框，包含 Status: Online、Public URL: https://<name>--slug.zorven.app 和 Local target: http://localhost:3000。客户端会根据系统语言使用土耳其语、英语或日语；可通过 zorven settings 更改。
4. 需要一次性隧道？
   $zorven ephemeral 3000 --ttl 30m

   复制
   时间到后隧道会自动删除。启动时会打印 Temporary tunnel: it will be removed automatically after 30m0s.

CLI 命令

以下是客户端的实际命令。对其中任何一个运行 zorven <command> --help 即可查看帮助。

zorven http <port> and zorven <port>

将本地 HTTP 服务暴露到互联网。简写形式 zorven 8080 效果相同。

远程终端和屏幕共享在 CLI 和服务模式下默认关闭；在 Windows 桌面应用中默认开启。若要在使用 CLI 时通过控制台访问它们，请在本设备上显式启用（0.2.2 及更高版本）：

控制台终端：客户端会上报本机已安装的 shell，你在打开新标签页时可从中选择（bash、zsh、fish、sh、PowerShell 7、Windows PowerShell、cmd、WSL）。每个客户端最多可打开 8 个标签页，支持搜索、字号调整和选中即复制。zsh 和 bash 会以 Zorven 配置启动（提示符、自动建议、语法高亮）；使用 --terminal-plain-zsh / --terminal-plain-bash 可获得纯净 shell。shell 运行在服务器端：离开页面或刷新后，标签页会重新连接到同一个 shell 并重放最近的输出。连接断开后，shell 会等待 30 分钟；关闭标签页则会结束它。只有打开会话的人才能重新连接该会话。

zorven ephemeral <port>

开启一条到期自动删除的临时隧道，适用于演示、Webhook 测试和 PR 预览。--ttl 必须在 1 分钟到 24 小时之间（默认 2h）。别名：temp、tmp。

zorven authtoken <token>

将客户端令牌保存到本地配置。令牌必须以 zrv_live_ 开头，否则命令会失败。别名：token。

status, update, version

显示客户端版本、配置文件、服务器地址、已保存的令牌（已掩码）以及后台服务的状态（版本行自 0.2.2 起提供）。

如有新版本，则下载并应用（客户端会重启）。

打印客户端和协议版本以及操作系统和架构。提交支持请求时请附上此输出。

zorven config

--system 参数会将设置写入系统级配置（用于服务模式），需要管理员/root 权限。参见配置。

zorven connect Team+

加入 Zorven Network 并开启本地 SOCKS5 代理（默认 127.0.0.1:1080）。你的应用可以通过名称访问从不暴露到互联网的私有资源（例如 db.internal:5432）。此命令需要的是 API 令牌，而不是客户端令牌（控制台中的 API 密钥，至少具备 tunnels:read 权限范围）。该令牌必须属于某个服务账号，并且必须存在授予该服务账号访问权限的资源策略（REST API：POST /resource-policies，grant.service_account_ids）；没有策略时，连接无法访问任何资源。

然后在你的应用中将 127.0.0.1:1080 用作 SOCKS5 代理。以 SSH 为例：

在网关（站点到站点）模式下，你可以将代理暴露给局域网；此模式必须指定允许的客户端地址范围：

zorven forward <host>

将本地端口绑定到 SNI 模式的原始 TCP 隧道（访客端）。例如，加入游戏服务器：

然后让你的应用指向 127.0.0.1:25565。使用 --listen 可监听其他地址。此命令仅支持 TCP；UDP 请使用控制台中的保留端口模式。

zorven deploy and zorven apps Zorven Apps

使用 Zorven Apps，你的应用容器通过 Docker 运行在你自己的机器上（即运行 Zorven 客户端的节点），流量经由现有隧道转发。该节点需要安装 Docker，并且必须使用 --enable-deploy 启动客户端（出于安全考虑默认关闭）。这些命令需要 API 令牌而不是客户端令牌（zrv_api_...；查看需要 apps:read，修改需要 apps:write，CI 部署需要 apps:deploy）：传入 --api-token 或设置 ZORVEN_API_TOKEN。

zorven deploy init 会写入一个带注释的 zorven.yaml 模板；使用 --git 可从代码仓库构建，使用 --env 设置环境变量（{{secret:name}} 会从密钥保险库读取）。默认策略为蓝绿部署：不健康的新版本不会接收任何流量。管理命令：zorven apps ls、status、logs -f、restart、stop、start、rm、rollback 和 deployments。在 CI 中，zorven deploy --app site --image-tag v1.4.2 --wait 只需要 apps:deploy 权限范围。

zorven share, access and net

你可以通过 WireGuard 端到端地共享本地端口，且仅限你指定的人员、群组或设备；服务器无法看到内容，也不需要管理员权限。共享在命令运行期间有效（--persist 可使其永久生效）：

接收方格式：ali@company.com、user:<id>、group:everyone、group:role:admin、device:<name>；使用 --udp 共享 UDP，使用 --expires 24h 限制有效期。zorven share ls 和 rm 用于管理共享。在接收方，设备的客户端令牌即可（无需 API 令牌，所有套餐均可使用）；如果 Zorven 客户端正在运行，它会打开访问：

zorven net up 启用完整网络层（虚拟网卡、路由和 *.zorven.internal DNS；需要管理员权限），zorven net down 将其关闭，zorven net status 列出节点和共享。使用 --no-net 可完全关闭 Zorven Net，使用 --no-tun 则仅关闭完整网络层。

zorven mcp

将 Zorven 作为 MCP（Model Context Protocol）服务器运行，使 Claude、Cursor 等 AI 助手能够把你的设备、隧道、域名、请求日志和指标当作工具使用。它需要 API 访问权限（Pro 及以上）；工具列表依据令牌的权限范围生成，只有具备 tunnels:delete / hostnames:delete 权限范围时才会出现删除类工具。

使用 --http 127.0.0.1:8765 可改用本地 HTTP，而不是 stdio。

zorven settings

打开交互式设置界面（方向键、Enter、Esc）；简称为 set 和 ayarlar。使用 zorven completion 可获得 shell 自动补全。界面语言为土耳其语、英语或日语。

常用参数

适用于 zorven、zorven http 和 zorven ephemeral（0.2.2 及更高版本；更早的版本只在 zorven [port] 上接受这些参数）：

服务模式

在服务模式下，客户端无需登录会话即可在后台运行，并随开机启动（Windows 服务或 systemd）。安装脚本已经完成了这些设置；如需手动配置，请使用管理员/root 权限：

服务读取的是系统配置，而不是你的用户设置，因此请使用 --system（或 service install --token）来写入令牌和服务器地址。仅执行 zorven authtoken 不会配置服务；请使用 sudo zorven service install --token zrv_live_...。

配置

客户端使用两个配置文件：每个用户一份的 config.json（位于用户配置目录下的 zorven 文件夹中），以及供服务模式使用的系统级文件（Linux/macOS：/etc/zorven/config.json，Windows：%ProgramData%\zorven\config.json）。运行 zorven config show 可查看实际生效的值。

同样支持环境变量：

如果未设置服务器，则使用默认的 zorven.app:443。如果你运行自己的服务器，请用 zorven config set-server 设置其地址。

控制台概念

你可以在 panel.zorven.app 管理一切。下面介绍主要概念以及各自适用的套餐；当前限额请参见价格。

组织和项目

每个账号都属于一个组织。将隧道、客户端和域名归入项目，即可让预发布、生产和客户环境相互分离。项目数量取决于套餐（Free 2、Hobby 3、Pro 10、Team 50）。

隧道

一个客户端（设备）可以开启一条或多条隧道。隧道类型：HTTP/HTTPS、原始 TCP（数据库、SSH）、SNI 模式 TCP 以及 UDP（游戏服务器）。HTTP 隧道支持基于路径的路由、流量策略以及控制台中的请求检查器（查看请求头和请求体，一键重放）。你可以用密码（Basic Auth）或 Google/GitHub 访客登录来保护隧道。你可以重新发送已捕获的请求（重放），并对比两次响应（重放对比）。请求检查器不会记录因身份验证、策略或 IP 规则而被提前拒绝的请求（401、策略、IP）。同时也提供 Node 和 Python SDK。

域名

每条隧道都会获得一个免费的租户地址（name--slug.zorven.app，其中 slug 是你的组织简称），并自动启用 HTTPS。在控制台的域名下，你还可以申领全局短名称，例如 name.zorven.app（先到先得）：Pro 1 个、Team 3 个、Enterprise 10 个；Pro+。如果套餐降级，超出配额的短名称和自定义域名不会被删除，而是被暂停（关闭访问）；升级后会按创建时间从早到晚重新开启。包含 zorven 或 rpshell 的名称无法注册。在控制台中添加你自己的域名（例如 api.yourcompany.com），并创建它所显示的 DNS 记录（所有权验证和 CNAME）；之后 Zorven 会自动签发并续期证书。自定义域名自 Hobby+ 起提供。

证书：平台的 *.zorven.app 通配符证书通过 DNS 验证（acme.sh）在服务器之外获取，并从文件加载；自定义域名的证书由 Let's Encrypt 自动签发（HTTP-01 和 TLS-ALPN-01）。对于 DNS 验证尚未完成的自定义域名，TLS 握手会被拒绝。

团队

通过电子邮件邀请成员加入你的组织。角色有 owner、admin 和 member。团队页面适用于 Pro+ 套餐，成员数量上限取决于套餐（Pro 3、Team 5）。登录支持双重验证（2FA）；Enterprise 还支持通过你自己的身份提供商进行 SSO（OIDC/SAML）并带有群组映射。

策略与密钥保险库

策略引擎 Pro+ 让你无需编写代码，即可在控制台中定义规则：速率限制、拒绝、重定向、请求头注入（set_header）、强制 mTLS（require_mTLS）、WAF（waf）以及Webhook 签名验证（verify_webhook）。WAF 通过 OWASP-lite 规则拦截 SQL 注入、XSS、路径遍历、命令注入和扫描器 User-Agent，你还可以添加自定义正则规则。它检查路径、查询字符串、User-Agent、Referer 和 Cookie（不检查请求体）；命中规则时返回 403。verify_webhook 可验证 GitHub、Stripe、GitLab、Shopify 和 Slack 的签名（容差 5 分钟，请求体最大 1 MB）；无效签名会以 401 拒绝。密钥保险库 Pro+ 加密存储你的密钥；{{secret:name}} 仅在 verify_webhook 的 secret_ref 字段中被解析。

请求处理顺序：免费套餐的首次访问提示页在策略引擎之前运行，而每条隧道的请求限速器在策略之后运行。负载均衡 Team+：支持轮询、加权、最少连接和延迟策略，并提供 HTTP 和 TCP 健康检查。

隧道安全

在隧道的“安全”标签页（API：GET/PUT /api/v1/tunnels/{id}/security）中，你可以为 HTTP 隧道配置以下防护：

• WAF：off、log（仅观察；所有套餐）和 block（403；Pro+）。它会扫描 SQL 注入、XSS、路径遍历、命令注入、log4shell、扫描器 User-Agent，以及 /.git、/.env 等路径；规则或类别可单独关闭。
• 地理规则 Pro+：按国家允许或封锁；适用于 HTTP 以及原始 TCP/UDP 隧道。国家数据来自 DB-IP Lite Country（IP Geolocation by DB-IP）。
• 机器人防护：向可疑访客显示一个简短的工作量证明验证页面（所有套餐）。“始终显示”模式和按 IP 的速率限制属于 Pro+。你可以排除 API 和 Webhook 路径；通过验证的访客在设定时间内不会再次被检查。经过验证的搜索引擎机器人（Googlebot、Bingbot）默认放行。
• 受信任 IP（所有套餐）：列出的地址不受速率限制、机器人检查和 WAF 约束。IP 白名单、访客登录、策略规则和强制 mTLS 仍然对它们生效。过宽的范围（IPv4 宽于 /8，或 IPv6 宽于 /32）会被拒绝。

被拦截或被观察到的请求会出现在控制台的“请求”页面中，原因标记为 waf:、geo:、bot: 和 rate:。

Zorven CAPTCHA

一个用于保护你自己表单（注册、登录、联系、评论）免受机器人侵扰的验证组件：不使用 Cookie，不追踪访客，也没有图片拼图；所有套餐均可使用。在控制台的 CAPTCHA 页面创建站点（公开的 zcs_... 站点密钥，以及保留在你服务器上的 zcsec_... 密钥）。将脚本和组件添加到你的页面，然后在你的服务器上通过 POST /api/v1/captcha/siteverify 验证表单中的 zorven-captcha-response 值：

示例：<script src="https://zorven.app/captcha/v1/api.js" async defer></script>，并在表单内加入 <div class="zorven-captcha" data-sitekey="zcs_..."></div>.

日志接收端

你可以将请求日志批量发送到 Webhook 或 syslog 目标 Team+。Webhook 投递失败时，会以指数退避方式最多重试 5 次。如果目标配置了 whsec_... 签名密钥（创建时只显示一次），每个请求都会带有 X-Zorven-Signature（HMAC-SHA256）请求头，以及用于去重的 X-Zorven-Delivery 请求头；你可以通过 API 轮换该密钥（rotate-secret）。

套餐权限

超出配额时不会切断连接，而是限速：Free 1、Hobby 5、Pro 10、Team 25、Enterprise 100 Mbps。Pro 含 7 天免费试用。日志保留期按套餐执行（Free 1、Hobby 3、Pro 7、Team 30、Enterprise 90 天；每小时运行一次清理任务）；审计日志保留 365 天。在 Team 套餐中，你可以在控制台的“配额与套餐”中申请额外设备（每台每月 $0.50）和额外流量（每 GB $0.10）；获批后，你的限额会相应提高。

访客登录页面

当 HTTP 隧道设置了访问策略（Basic Auth 或 Google / GitHub）时，访客看到的是 Zorven 风格的登录页面，而不是浏览器的密码弹窗。该页面支持土耳其语和英语、浅色和深色主题以及移动端。

• 用户名和密码：会话有效期为 12 小时。修改密码会使现有会话失效。每个 IP 每 10 分钟最多允许 10 次失败尝试。curl 和 API 客户端仍可通过 Authorization: Basic 请求头访问。
• 使用 Google / GitHub 继续：仅显示该隧道允许的提供商；允许邮箱列表同样生效，访客可以切换账号。
• 统计：每次尝试（方式、提供商、身份、是否成功、原因、IP、user agent）都会被记录，但密码绝不会被记录。记录按你套餐的日志保留期保存。GET /api/v1/tunnels/{id}/access-events 返回列表，GET /api/v1/tunnels/{id}/access-events/summary?window=24h|7d|30d 返回汇总（analytics:read 权限范围）。相同的统计也会显示在控制台的隧道页面上。

Web 门（TCP/UDP）Pro+

对于原始 TCP/UDP 隧道（含 SNI），访客在网页上登录后，只有其自己的 IP 地址才被允许访问隧道端口。没有授权的连接会被静默丢弃。

1. 首先为隧道设置登录方式：用户名和密码，或 Google / GitHub（访问策略）。
2. 启用门并选择授权时长：3600（1 小时）、43200（12 小时）、86400（24 小时）或 604800（7 天）。
3. 将门的 URL 分享给访客：door--<label>.zorven.app。登录后，其 IP 在时间到期前都可以访问该端口；他们也可以自行关闭门。

被拦截的尝试会计入访问统计。如果套餐降到 Pro 以下，门会自动关闭。IPv6 与 IPv4 地址之间不做匹配。

在邮件应用中使用

你可以通过 IMAP 和 SMTP 在邮件应用中使用平台邮箱（org-name@mail.zorven.app）。在控制台的邮件部分，使用“在邮件应用中使用”为每个邮箱创建应用专用密码；该密码只显示一次，并可随时撤销。

• Gmail 应用（Android / iOS）：添加账号，选择“其他”或“个人（IMAP）”，并填入上述设置。
• Outlook 和 Thunderbird：已提供 autoconfig / autodiscover 端点；只输入邮箱地址可能就足够了。
• Apple Mail：从控制台下载配置描述文件并安装。
• 向外部收件人发送邮件遵循与网页邮箱相同的套餐规则（Enterprise）；平台内部地址始终可以投递。
• 不提供 POP3，仅支持 IMAP。Gmail 网站通过 POP3 添加外部账号，因此无法在 gmail.com 上添加此账号；请使用 Gmail 应用。

API 与令牌

你在控制台中所做的一切，也都可以通过 REST API 完成。API 访问适用于 Pro+ 套餐。在控制台的 API 密钥部分创建 API 令牌，选择其权限范围和有效期，并在 Authorization 请求头中发送它：

请勿混淆两种令牌：zrv_live_ 是客户端（设备）令牌，配合 zorven authtoken 使用；zrv_api_ 是 API 令牌，用于 REST API 和 zorven connect。全部端点和权限范围请参见 API 参考。

帮助

常见问题请查看常见问题，服务运行状况请查看状态页面，其他事项请联系我们。客户端和服务器均为开源核心（AGPLv3）：GitHub。