q quicktuiv1
iOS 应用iOS → Android 应用Android →

指南 · 远程访问

在任何地方连接你的 QuickTUI 服务端

手机和电脑不在同一个网络时，可以通过 Cloudflare Tunnel、自建 HTTPS 反向代理或路由器端口转发连接电脑上的 QuickTUI 服务端。本指南说明每种方式的要求，以及如何通过它们配对。

先考虑更简单的方式。QuickTUI Relay不需要任何网络设置，在中国大陆也能稳定使用。Tailscale 通过私有网络让手机直接访问电脑，不必开放任何端口；但在中国大陆可能很慢，要获得稳定速度需要自己部署私有 DERP 中转服务器。详见 可以通过公网连接吗？ 下面几种方式适合已经有域名、反向代理或公网 IP 的用户。

开始之前

服务端使用明文 HTTP
QuickTUI 服务端默认监听 0.0.0.0:8022，本身不需要 TLS 证书。配对码、设备认证和全部操作都在端到端加密通道内传输，App 每次连接都会校验电脑的身份指纹。即使地址以 http:// 开头，别人也看不到内容，冒充不了你的电脑。
App 访问哪些路径
App 只需要一个基础地址，形式为 http://主机:端口 或 https://主机[:端口]。App 会通过它请求 /.well-known/quicktui-server-capability，并在 /e2e 建立 WebSocket 连接。
不支持子路径
服务端必须独占一个主机名（或一个端口）。不能挂在 https://example.com/quicktui/ 这样的子路径下，需要把根路径下的所有请求都转发给服务端。
修改地址不需要重新配对
先在局域网内完成配对，然后在 App 中打开这台电脑的编辑服务器页面，把协议、主机和端口改成远程地址即可。App 保留原有配对，并继续校验身份指纹。
通过公开地址配对
想直接通过隧道或反向代理配对时，用 --public-url 把公开地址写入二维码： 
# macOS / Linux
~/.local/bin/quicktui-server pairing qrcode --browser --public-url https://qt.example.com

# Windows（PowerShell）
quicktui-server pairing qrcode --browser --public-url https://qt.example.com
然后按配对设备中的步骤在 App 中扫码。--public-url 同样可以和 --text 一起使用，输出配对文本，在 App 中粘贴代替扫码。
可信代理
服务端会限制同一个来源地址发起握手的数量与频率，防止垃圾连接让你自己连不上。经过隧道或反向代理后，所有连接看起来都来自代理，会共用同一个名额。把 trusted_proxies 设为代理自己的地址后，服务端会从 X-Forwarded-For 读取真实来源地址（见设置可信代理）。只填代理的地址，不要填客户端网段。

Cloudflare Tunnel

Cloudflare Tunnel 由电脑主动连接 Cloudflare，你通过自己域名下的一个网址（HTTPS）访问电脑。不需要公网 IP，也不需要修改路由器。前提是你的域名托管在 Cloudflare。

  1. 登录 Cloudflare，进入 Zero Trust → Networks → Tunnels，创建一个隧道，并按页面提示在电脑上安装并运行 cloudflared。
  2. 在隧道中添加一个 Public Hostname：主机名填 qt.example.com，类型选 HTTP，URL 填 localhost:8022。
  3. 把可信代理设为 127.0.0.1,::1（见设置可信代理）。
  4. 在 App 中使用 https://qt.example.com，不要加 :8022。已经配对过的电脑，把协议设为 HTTPS、主机设为 qt.example.com、端口设为 443。要配对新设备时，用 --public-url https://qt.example.com 生成二维码。

如果你用本地配置文件管理隧道，转发规则如下：

tunnel: <TUNNEL-UUID>
credentials-file: /home/you/.cloudflared/<TUNNEL-UUID>.json
ingress:
  - hostname: qt.example.com
    service: http://127.0.0.1:8022
  - service: http_status:404

Cloudflare Tunnel 默认支持 WebSocket，保留原始 Host 请求头，并发送 X-Forwarded-Proto，满足服务端要求，无需额外设置。

不要为这个网址开启 Cloudflare Access。需要在浏览器中登录的 Access 策略会拦截 App，因为 App 无法完成浏览器登录。

自建 HTTPS 反向代理

如果你已经在用 nginx、Caddy 或其他反向代理，可以把一个主机名指向 QuickTUI 服务端。反向代理可以和服务端在同一台电脑上，也可以在另一台能访问电脑 8022 端口的机器上。

反向代理必须满足：

  1. 用一个单独的主机名（或端口）把所有路径转发给服务端。不支持子路径。
  2. 支持 WebSocket 升级。
  3. 保留原始 Host 请求头。
  4. 发送 X-Forwarded-Proto: https。
  5. 使用 iPhone 信任的证书，例如 Let's Encrypt 免费证书。
  6. 空闲超时不要太短，并关闭响应缓冲。App 每 10 秒发送一次心跳，空闲超时设为 1 小时比较稳妥。

Caddy 会自动申请证书，默认满足以上全部条件：

qt.example.com {
    reverse_proxy 127.0.0.1:8022
}

nginx：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl http2;
    server_name qt.example.com;

    ssl_certificate     /etc/letsencrypt/live/qt.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/qt.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8022;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 1h;
        proxy_send_timeout 1h;
        proxy_buffering off;
    }
}

反向代理在另一台机器上时，把 127.0.0.1:8022 换成你电脑的地址，例如 192.168.1.10:8022，并在 trusted_proxies 中填那台机器的 IP。反向代理不使用 443 端口时，在地址中写上端口，例如 --public-url https://qt.example.com:8443。

App 无法读取服务端能力信息时会显示 HTTP 状态码。404 通常表示路径没有全部转发给服务端；502 通常表示反向代理连不上服务端。

路由器端口转发

如果家里宽带有公网 IP，可以在路由器上把一个外部端口转发到电脑的 8022 端口。

这种方式把服务端直接暴露在互联网上。内容仍然是端到端加密的，别人看不到，也冒充不了你的电脑。但任何人都能发现这里运行着 QuickTUI 服务端及其版本，大量垃圾连接也可能让你自己的设备暂时连不上。能用上面几种方式时，请优先使用它们。

  1. 确认有公网 IP。对比路由器管理页面显示的 WAN 口 IP 与在电脑上运行 curl -4 ifconfig.me 的结果。两者不同，或 WAN 口 IP 在 100.64.0.0/10 范围内，说明处于运营商 CGNAT 之后，端口转发不可用。
  2. 给电脑固定局域网 IP。在路由器的 DHCP 设置中为电脑保留一个地址，例如 192.168.1.10。
  3. 添加转发规则：选一个不常见的外部端口，例如 28022，转发到 192.168.1.10 的 8022 端口，协议 TCP。
  4. 设置动态域名（DDNS）。家庭宽带的公网 IP 经常变化，在路由器中开启 DDNS，得到一个固定域名，例如 home.example.com。
  5. 在 App 中使用：在编辑服务器页面把协议设为 HTTP、主机设为 home.example.com、端口设为 28022。要配对新设备时，使用 --public-url http://home.example.com:28022。

电脑防火墙需要允许 8022 端口入站。有些路由器不支持在家里用公网地址访问家里的设备（不支持 NAT 回环）；如果在外面能连上、在家连不上，可以在家时改用局域网地址，或者绑定 QuickTUI Relay 并使用自动模式。

设置可信代理

使用 Cloudflare Tunnel 或反向代理时需要设置，端口转发不需要。

  1. 用文本编辑器打开配置文件（其他位置见安装位置）： 
    nano ~/.config/quicktui-server-v2/config.toml
  2. 加入一行代理的地址。cloudflared 或同一台电脑上的反向代理填： 
    trusted_proxies = "127.0.0.1,::1"
  3. 保存后重启服务端： 
    ~/.local/bin/quicktui-server service restart

可选：只接受来自代理的连接

默认情况下，服务端也接受来自局域网的连接。如果同一台电脑上的隧道或反向代理是唯一入口，可以让服务端只监听本机：

~/.local/bin/quicktui-server config set --addr 127.0.0.1:8022

这样设置后，局域网内的设备不能再直接连接，App 设置向导中的 SSH 自动安装也无法自动配对。不确定时请保持默认的 0.0.0.0:8022。

相关链接