使用与部署指南

文件传输工具支持多种部署方式，您可以根据自己的需求选择最适合的部署方案。

Docker 部署

方法一：使用 Docker Compose（推荐）

git clone https://github.com/MatrixSeven/file-transfer-go.git
cd file-transfer-go
docker-compose up -d

方法二：直接使用 Docker 镜像

docker run -d -p 8080:8080 --name file-transfer-go matrixseven/file-transfer-go:latest

部署提示

• Docker Compose 方式会自动处理依赖和网络配置
• 服务启动后访问 http://localhost:8080
• 可以通过修改 docker-compose.yml 自定义端口

二进制部署

下载预编译版本

前往 GitHub Releases 页面 下载对应系统的二进制包。

支持的平台：

• Linux (AMD64/ARM64)
• Windows (AMD64)
• macOS (AMD64/ARM64)

启动服务

下载后直接运行可执行文件即可：

# Linux/macOS
chmod +x file-transfer-server-linux-amd64
./file-transfer-server-linux-amd64

# Windows
file-transfer-server-windows-amd64.exe

注意

• 首次运行可能需要防火墙授权
• 默认端口为 8080，可通过参数修改
• 建议在生产环境使用 systemd 等进程管理工具

自行构建

环境要求

• Go 1.21 或更高版本
• Node.js 18 或更高版本
• Git

构建步骤

git clone https://github.com/MatrixSeven/file-transfer-go.git
cd file-transfer-go
./build-fullstack.sh
./dist/file-transfer-go

构建注意

• 确保网络畅通，需要下载 Go 模块和 npm 包
• 首次构建可能需要较长时间
• 构建脚本会自动处理前后端的编译和打包

修改服务端口

以 Linux 为例，将服务绑定到 18080 端口：

./file-transfer-server-linux-amd64 -port 18080

Docker 端口映射

使用 Docker 时修改端口映射：

docker run -d -p 18080:8080 matrixseven/file-transfer-go:latest

端口选择建议

• 避免使用系统保留端口（1-1024）
• 确保选择的端口未被其他服务占用
• 防火墙需要开放对应端口
• 建议使用 8080, 3000, 8000 等常用端口

实验性功能 以下方案理论可行，但未经充分验证，请在测试环境中验证后再用于生产。

内网部署方案

1. 部署内网 DNS 服务

配置内网域名解析，避免直接使用 IP 地址访问

2. 配置 STUN/TURN 服务

部署内网 STUN/TURN 服务器，处理 NAT 穿透

3. 更新服务配置

在应用设置中配置自定义 STUN/TURN 服务器地址

STUN/TURN 服务器推荐

• Coturn：开源 TURN/STUN 服务器
• Janus：WebRTC 网关，包含 STUN/TURN 功能
• 自建方案：基于 Docker 快速部署

配置提示 在应用的设置页面中，可以添加自定义 ICE 服务器：

• STUN 服务器格式：stun:your-server.local:3478
• TURN 服务器格式：turn:your-server.local:3478
• TURN 服务器需要用户名和密码认证

传输方式

| 方式 | 说明 | |------|------| | 点对点传输 | 通过 WebRTC 建立直接连接，数据不经过服务器 | | 中继传输 | 当直连失败时，通过服务器中继数据 |

传输流程

1. 建立信令连接 — 通过 WebSocket 服务器交换连接信息
2. NAT 穿透 — 使用 STUN 服务器检测网络环境，尝试直连
3. 数据传输 — 建立 P2P 连接后直接传输，或通过中继

隐私保护

• 所有文件数据通过点对点传输，服务器不存储任何文件内容
• 房间码具有时效性，连接断开后自动失效
• 支持端到端加密，确保传输安全
• 即使使用中继传输，数据也是加密传输的

交流群组

欢迎加入我们的交流群，获取最新更新、技术支持和经验分享：

• 报告问题和建议
• 获取使用帮助
• 分享部署经验
• 了解新功能动态

其他联系方式

| 渠道 | 说明 | |------|------| | GitHub Issues | 提交 Bug 报告和功能请求 | | 项目主页 | 查看详细的技术文档 |

反馈建议 为了更好地帮助您解决问题，请在反馈时提供：

• 详细的问题描述和复现步骤
• 部署环境信息（Docker/二进制/自构建）
• 浏览器类型和版本
• 网络环境（内网/公网/NAT类型）
• 相关的错误日志或截图

为何房间码不存在

输入取件码后提示"房间不存在"，通常是以下原因：

发送方已关闭房间 — 如果使用的是在线 Demo 站，发送方关闭页面或断开连接后，房间会立即销毁，取件码随之失效。

访问地址不对 — 如果是自行部署，请不要用 localhost 或 127.0.0.1 访问服务。应该使用服务所在的局域网 IP（如 192.168.x.x）或公网 IP。双方必须访问同一个服务地址。

端口被防火墙拦截 — 确认服务端口（默认 8080）已在防火墙中放行，否则其他设备无法连接到服务。

排查步骤：

1. 确认发送方页面仍然打开，房间未过期
2. 确认双方访问的是同一个地址
3. 检查防火墙是否放行了服务端口

为何 P2P 连接失败

P2P 直连需要双方设备能互相"找到"并"打通"网络通道，就像两个人要打电话，必须知道对方的号码且线路畅通。以下情况会导致"打不通"：

运营商网络问题 — 运营商网络通常使用对称 NAT 和防火墙，导致双方设备无法直接互相发现。每次连接分配的端口都不同，几乎无法穿透。这是最常见的原因，建议双方都连接 Wi-Fi 再试。

VPN / 代理 / 加速器 — 这类工具会改变网络路径，干扰直连。传输时建议暂时关闭。

公司 / 学校网络 — 这类网络通常有严格的防火墙，阻止了设备间直接传输所需的通道。

信号不稳定 — 网络延迟过高或频繁断连，也会导致直连建立失败。

不用担心，连接失败后系统会自动切换到中继模式，通过服务器转发数据，不影响正常传输，只是速度可能稍慢。

可以尝试：

1. 双方都切换到同一个 Wi-Fi 网络下再试
2. 暂时关闭 VPN 或代理
3. 确认浏览器没有禁用 WebRTC

复制链接失败

浏览器的复制功能（navigator.clipboard）要求页面必须在 HTTPS 下才能使用。如果你的站点通过 HTTP 访问，复制功能会被浏览器禁用。

解决方法：

1. 确保站点通过 HTTPS 访问（配置反向代理启用 TLS 证书）
2. 在系统浏览器（Safari / Chrome）中打开页面，不要在微信/钉钉内置浏览器中使用
3. 手动长按链接文本复制
4. 使用页面上的取件码，让对方手动输入

无法共享桌面

移动端无法共享桌面

这是移动端浏览器的限制，WebRTC 没有在移动浏览器端实现获取桌面视频流的功能。

解决方案：请使用桌面设备进行屏幕共享。

PC 端无法共享桌面

如果是自行部署，无论是部署在局域网/公网，如果要实现桌面分享，需要必须保证服务访问地址是 TLS 加密，也就是 https 方式访问。

• localhost 地址可以直接分享桌面
• 其他地址需要配置反向代理（如 nginx）启用 HTTPS
• 这是浏览器的安全限制，直接 IP 无法分享桌面

临时解决方案： 如果一定要用 IP+端口 的方式进行桌面分享，可以在浏览器设置中：

1. 打开浏览器设置
2. 搜索 WebRTC 相关设置
3. 开启 Anonymize local IPs exposed by WebRTC
4. 设置为 Enabled 状态

如何自定义中继服务器

当 P2P 直连失败时，如果你有自己的 TURN 中继服务器，可以在应用中配置，让流量通过你的服务器转发，保证传输顺利完成。

配置步骤：

1. 在首页底部点击「中继设置」标签页
2. 点击「添加服务器」
3. 填写你的服务器信息：
   • STUN 服务器：如 stun:your-server.com:3478
   • TURN 服务器：如 turn:your-server.com:3478
   • 用户名和密码：TURN 服务器所需的认证凭据
4. 保存后，当 P2P 连接失败时，系统会自动使用你配置的服务器进行中继

TURN 服务器可以用开源的 Coturn 自行搭建，也可以使用云服务商提供的 TURN 服务。

手机端如何传文件夹

目前不支持。手机浏览器没有提供文件目录相关的 API，无法读取和同步文件夹结构，所以无法支持文件夹传输。

替代方案：

1. 将文件夹压缩成 zip 压缩包，作为单个文件发送
2. 在 PC 端发起文件夹传输，手机端接收单个文件

自部署 WebSocket 异常关闭

自己部署本服务后，如果 WebSocket 连不上，通常是因为前面加了反向代理（如 nginx、Lucky 等），但没有配置 WebSocket 头信息支持。

以 nginx 为例，在代理配置中添加：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;

完整的 nginx location 配置参考：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

其他反向代理工具（如 Lucky、Caddy、宝塔等）也需要开启 WebSocket 支持选项，具体请查看对应工具的文档。

为何显示 5M 上限

这是作者 Demo 站的限制。出现这个提示说明你当前网络 P2P 直连失败，降级到了 WebSocket 中继传输。此时数据会经过作者服务器转发，为了降低服务器压力，Demo 站设置了 5M 的文件大小上限，仅用于效果演示。

如何解决：

1. 自行部署 — 通过源码或 Docker 在自己的服务器上运行，没有文件大小限制
2. 配置自己的中继服务器 — 在「中继设置」中添加你自己的 TURN 服务器，流量走你自己的服务器，不受 Demo 站限制