安装

没有安装程序，没有运行库依赖。一个可执行文件，放哪儿都能跑，删掉就干净了。

先选对文件

你的系统	下载哪个
Windows 10 / 11（64 位）	`qfile-wails-windows-amd64.exe` —— 带窗口，日常用这个
Windows，要看日志 / 做成开机服务	`qfile-windows-amd64.exe` —— 控制台版
Mac（M1/M2/M3/M4 等 Apple 芯片）	`qfile-darwin-arm64`
Mac（2020 年前的 Intel 机型）	`qfile-darwin-amd64`
Linux（普通 x86 服务器/台式机）	`qfile-linux-amd64`
Linux（ARM，树莓派、云上的 ARM 实例）	`qfile-linux-arm64`

分不清 Mac 是哪种芯片：左上角 → 关于本机，写着「芯片 Apple M…」就是 Apple 芯片，写着「处理器 Intel…」就是 Intel。

读取 /api/release …

表格里的 sha256 是给校验用的，怎么核对见每个系统那一节的最后一步。不校验也能用，但那意味着你信任的是这条网络链路，而不是这个文件。

Windows

下载 qfile-wails-windows-amd64.exe，放到一个你自己的目录，比如 D:\qfile\。别放在「下载」文件夹里——那里的东西迟早被清理掉。
双击运行。第一次会弹「Windows 已保护你的电脑」，那是因为这个程序没有买代码签名证书。点「更多信息」→「仍要运行」。
它会自己打开浏览器界面。第一次问你这台电脑当共享端还是连接端（区别见首页）。

放行防火墙

第一次运行时 Windows 会弹「是否允许此应用通过防火墙」，专用网络和公用网络都勾上。只勾专用网络的话，换到别的网络（酒店、公司访客 Wi-Fi）就只能走中转，慢很多。

开机自动运行（可选）

用控制台版更合适。Win+R 输入 shell:startup，把 qfile-windows-amd64.exe 的快捷方式放进去，在快捷方式属性的「目标」后面加上参数：

D:\qfile\qfile-windows-amd64.exe -mode listener

校验（可选）

certutil -hashfile qfile-wails-windows-amd64.exe SHA256

输出和上面表格里那一行一致就对了。

卸载

删掉这个 exe。配置在 %AppData%\qfile\，一起删掉就彻底干净了（里面有这台机器的身份密钥，删了等于换了一台新机器，对方要重新授权）。

macOS

Mac 版是命令行程序，没有 .app 图标 —— 界面在浏览器里。三条命令装完。

下载并给执行权限（Apple 芯片用 arm64，Intel 用 amd64）：

curl -fsSLO https://x.bofile.com/releases/qfile-darwin-arm64
chmod +x qfile-darwin-arm64

解除隔离标记。从网上下载的、没有苹果签名的程序会被 Gatekeeper 拦下，报「无法打开，因为无法验证开发者」。这条命令去掉那个标记：
```
xattr -dr com.apple.quarantine ./qfile-darwin-arm64
```
运行，然后打开它打印出来的那个本机地址：
```
./qfile-darwin-arm64
```

不想敲第 2 条命令的话，也可以在访达里按住 Control 点这个文件 → 打开，在弹窗里再点一次「打开」，效果一样。之后再运行就不问了。

校验（可选）

shasum -a 256 qfile-darwin-arm64

后台常驻（可选）

要让它开机就跑、关掉终端也不退出，用 launchd：~/Library/LaunchAgents/ 下放一个 plist，ProgramArguments 写上二进制的绝对路径和 -mode listener，然后 launchctl load。临时用的话 nohup ./qfile-darwin-arm64 -mode listener & 就够。

卸载

删掉二进制，再删 ~/Library/Application Support/qfile/。

Linux

下载并给执行权限（uname -m 是 x86_64 就用 amd64，aarch64 用 arm64）：

curl -fsSLO https://x.bofile.com/releases/qfile-linux-amd64
chmod +x qfile-linux-amd64

校验，对着清单里的那一行：

sha256sum qfile-linux-amd64
curl -s https://x.bofile.com/api/release | grep -A2 '"qfile-linux-amd64"'

运行。有桌面的机器上它会自己开浏览器；没有桌面的看下面一节。
```
./qfile-linux-amd64
```

没有桌面的服务器

管理界面默认只开在回环地址上。最稳妥的用法是 ssh 隧道 —— 端口不用对外开放，权限也不用额外配：

# 在服务器上
./qfile-linux-amd64 -mode listener -dirroot /srv/share

# 在你自己的电脑上，另开一个终端
ssh -N -L 34116:127.0.0.1:34116 你的用户名@服务器地址
# 然后浏览器打开 http://127.0.0.1:34116

确实需要把界面直接开到公网时，必须带密码，否则程序拒绝启动：

QFILE_ADMINPASS='你的密码' ./qfile-linux-amd64 -mode listener -adminaddr 0.0.0.0:34116

那个端口能授予远程桌面和代理权限，没有密码不是「弱一点的配置」，是谁扫到端口谁就能开这台机器。密码写在环境变量里而不是命令行参数里，因为命令行会出现在 ps 里，同机器上任何用户都看得到。

装成系统服务

程序自带注册：把你要的参数写全，最后加 -install，它会把这一整条命令注册成 systemd 单元并设为开机自启。

sudo install -m755 qfile-linux-amd64 /opt/qfile/qfile
cd /opt/qfile
sudo ./qfile -mode listener -dirroot /srv/share -install

systemctl status qfile-listener
journalctl -u qfile-listener -f

卸载

sudo systemctl disable --now qfile-listener   # 装过服务才需要
rm -rf ~/.config/qfile                        # 身份密钥和配置

升级

界面里有更新按钮，点一下自己下载、校验、替换、重启，身份密钥和授权都保留。手工升级就是把新文件盖掉旧文件 —— 唯一要注意的是正在运行的程序先退出（Windows 上占用文件会直接报拒绝访问）。

配置和身份密钥不在程序目录里，所以换文件不会丢授权：Windows 在 %AppData%\qfile\，macOS 在 ~/Library/Application Support/qfile/，Linux 在 ~/.config/qfile/。备份这个目录 = 备份这台机器的身份。

装不上时先看这几条

Windows 报「已保护你的电脑」/ 杀软报毒: 没有代码签名证书的程序都会这样。点「更多信息 → 仍要运行」；杀软误报的话把这个文件加进白名单。用上面的 sha256 核对一下，能确认你拿到的和我们发布的是同一个文件。
Mac 说「无法打开，因为无法验证开发者」: Gatekeeper 的隔离标记。跑 xattr -dr com.apple.quarantine ./qfile-darwin-arm64，或者右键（Control+点击）→ 打开。
Mac 说 bad CPU type 或 cannot execute binary file: 下错架构了。Apple 芯片要 qfile-darwin-arm64，Intel 要 qfile-darwin-amd64。
Linux 上 Permission denied: 忘了 chmod +x。如果加了还不行，可能是文件在挂了 noexec 的分区上（常见于 /tmp），换个目录。
能连上，但速度一直很慢: 多半是走了中转没走直连。防火墙要放行 UDP，不只是 TCP —— 少一条 UDP 规则的典型症状就是「能用但慢」。