给自己搭服务端

接入服务由我们运营，你不用装任何东西也能用。这一页讲的是另一件事：把中转和浏览器入口放到你自己的机器上。

先搞清楚要不要自建

两台机器之间能打通洞的时候，数据是点对点直连的，不经过任何服务器。自建只影响打不通洞的那部分流量，以及浏览器访问的入口。

你的情况	建议
就是家里和公司两台机器互传	不用自建。直接用，打不通洞时走我们的中转
传的量很大，或者中转这一跳太慢	自建 relay，放在离你两端都近的机房
不希望任何流量经过第三方的机器	自建 relay：中转看不到明文，但它确实知道谁在和谁通、转了多少字节
要用浏览器访问自己机器上的页面，且不想让链接经过我们	自建 gateway（需要一个你自己的域名和 443 端口）
整套要在内网/离线环境里跑	relay + gateway + 接入服务都要自己搭，联系我们拿部署方案

两个组件，各干各的

	`relay` 中转	`gateway` 浏览器入口
做什么	替打不通洞的两台机器转发加密流量	把 `https://<token>.你的域名/` 反代到对应的机器
要域名吗	不要	要，还要一张覆盖 `*.子域` 的证书
要什么端口	一个端口的 tcp + udp（默认 4002）	tcp 443，外加 tcp+udp 4003
存数据吗	不存。不持有任何名单，转完就忘	不存。每次都去问「这个 token 是谁」
看得到内容吗	看不到明文，转发的是已经加密的流	它替浏览器终结 HTTPS，所以经它的网页流量它看得到
成本	带宽，双向都算	带宽 + 一个域名

两个都是可选的扩容件，装几台就是多几条路，随时可以停掉，停掉之后流量自动回到默认路径。两台可以装在同一台机器上，互不干扰（各自独立的身份密钥和端口）。

自建 relay

在要当中转的那台机器上用 root 跑，全程在那台机器上。不需要给我们 ssh 权限，也不需要任何凭据 —— 二进制从公开地址取，并对着同时公布的 sha256 校验。

curl -fsSLO https://x.bofile.com/download/install_relay.sh
sudo bash install_relay.sh

可选参数（环境变量）

变量	默认	什么时候要设
`PORT`	`4002`	tcp 和 udp 用同一个号
`ANNOUNCE`	自动探测的公网 IP	机器在 NAT 后面，或者你有域名
`REGION`	无	一个标签（如 `cn-shanghai`），客户端据此优先挑近的中转
`DIR`	`/opt/qfile-relay`	换安装目录

PORT=4002 REGION=cn-shanghai sudo bash install_relay.sh

脚本做不了、必须你做的两件事

放行 tcp/PORT 和 udp/PORT —— 云上的安全组和机器本地防火墙都要，两个都要。QUIC 通常更快，少一条 UDP 规则的症状是「能用，但一直很慢」，很难查。
把脚本最后打印的那行地址发给我们。它长这样 /dns/1.2.3.4/udp/4002/quic-v1/p2p/12D3KooW…，我们把它加进中转清单之后，你的机器才会用到这台。那行是脚本从跑起来的进程里读出来的，别手抄 —— peer id 抄错的报错是「无法预约中转」，指不到原因。

备份 /opt/qfile-relay/qfile_relay.key。它丢了就等于换了一台新机器，清单里的那行会失效，要重新报一次。日常：systemctl status qfile-relay / journalctl -u qfile-relay -f；卸载 systemctl disable --now qfile-relay。

自建 gateway

同样是 root 跑在目标机器上。它要占 443，所以这台机器上不能有别的东西在用 443。

curl -fsSLO https://x.bofile.com/download/install_gateway.sh
sudo bash install_gateway.sh

流程

脚本装好二进制，先把这台机器的 peer id 打印出来，然后开始每 15 秒问一次。
你把那一行 peer id 发给我们 —— 只发这一行。不发证书、不发密钥、不发密码。
我们批准之后，证书通过已经建立的加密连接下发过去，gateway 自己开始服务。

证书不走 URL，也不用人肉传：那条连接两端都由密钥身份认证，我们清楚自己在回答哪台机器，而且只回答批准过的。通配私钥一旦泄漏，就是给它覆盖的每个名字都发了一张新证书，撤都撤不回来 —— 所以它不出现在任何链接、任何聊天窗口里。

用自己的域名

默认 ANNOUNCE 是我们的域名。要用你自己的，需要三样东西同时到位：

DNS：*.你的子域 一条 A 记录指向这台机器，不要开 CDN 代理（CDN 不转发 UDP，会把直连打没）。
证书：必须覆盖 你的子域 和 *.你的子域。泛域名证书只能用 DNS 验证签发。
启动参数：ANNOUNCE=你的子域 sudo bash install_gateway.sh，并把证书放进 /opt/qfile-gateway/certs/。

机器在中国大陆的话，域名必须完成 ICP 备案，否则 443 上的握手会被网络直接重置 —— 症状是 tcp 连得上、证书也对，但 TLS 永远建不起来，而换个已备案的域名指向同一台机器就正常。这一条我们踩过。

验证

唯一要看的一条：/api/info 必须回报接入服务的身份，而不是这台机器自己的。这一行同时证明 TLS 在本机终结、并且这台机器连上了接入服务。

curl -sk -H 'Host: 你的子域' https://127.0.0.1/api/info

不改 DNS，从外面按名字测：

curl -k --resolve 你的子域:443:<这台机器的公网IP> https://你的子域/api/info

超时几乎总是安全组：要放行 tcp/443 和 tcp+udp/4003。卸载：systemctl disable --now qfile-gateway。

不用脚本的话

脚本只是把下面几步串起来。手工做也可以，包括在没有 curl 的机器上先下好再传过去。

# 1. 看清单，记下对应文件的 sha256
curl -s https://x.bofile.com/api/release

# 2. 下载
curl -fsSLO https://x.bofile.com/releases/qfile-relay-linux-amd64

# 3. 校验，一定要做：和清单里那一行完全一致才继续
sha256sum qfile-relay-linux-amd64

# 4. 装成 systemd 服务（-install 把当前这条命令行原样注册成开机自启的单元）
sudo install -m755 qfile-relay-linux-amd64 /opt/qfile-relay/qfile
cd /opt/qfile-relay
sudo ./qfile -mode relay -port 4002 -announce <公网IP> \
  -key /opt/qfile-relay/qfile_relay.key -web https://x.bofile.com -install

服务端二进制

读取 /api/release …

两个脚本都可以重复运行 —— 再跑一次就是原地升级，身份密钥保留，已经报给我们的那行地址不变。

常见问题

自建要给你们 ssh 权限吗？: 不用。脚本在你自己的机器上跑，取的是公开的二进制，唯一要交换的是一行文本：relay 是它的地址，gateway 是它的 peer id。
relay 能看到我传的文件吗？: 看不到明文，它转发的是已经加密的流。但它知道谁在和谁通、转了多少字节 —— 这点元数据是中转这件事本身的代价，自建的意义就是让这点元数据留在你自己手里。
装了自己的 relay，会强制走它吗？: 不会。三条路（中转 / 打洞直连 / 局域网直连）同时建连、各自测速，客户端界面上能看到每条的延迟和吞吐，也可以手动挑。能直连的时候本来就不经过任何中转。
怎么确认我的 relay 真的在被使用？: 客户端的路径面板里会显示当前走的是哪一条、对端地址是什么；服务端 journalctl -u qfile-relay -f 能看到转发量。
升级怎么做？: 把同一个脚本再跑一遍。身份密钥保留，peer id 不变，我们这边的配置不用动。