LinkNest

LinkNest 是一个可运行的多端文件传输原型，提供服务端、Web UI、CLI、Windows 桌面端、Android 移动端和 Docker 部署方式。你可以把它部署到自己的服务器上，然后通过浏览器、CLI、Windows GUI 或 Android GUI 登录同一个账号、绑定设备、上传文件、下载文件、删除文件、查看任务状态，以及在不再需要时注销账号并清理自己的数据。

V2 在保留 V1 云端分片上传、断点续传和下载能力的基础上，新增“P2P 直传优先，V1 云端链路兜底”的传输路径。CLI 是协议验证入口；Web UI 展示 P2P 能力和传输诊断；Windows / Android GUI 复用共享 client service，不单独实现传输协议。

我能用它做什么

• 在自己的服务器上部署一个可访问的文件传输服务
• 用浏览器登录账号，查看在线设备、文件和任务
• 用 CLI 把当前电脑绑定成一个设备并保持在线
• 用 CLI 启动本机 P2P 接收服务，并向同账号在线设备发起 transfer send
• 在 Windows 桌面端里完成登录、绑定设备、文件管理和上传任务查看
• 在 Android 移动端里完成登录、绑定设备、文件管理和上传任务查看
• 上传大文件、断点续传、补传缺失分片
• 在其他设备上查看文件、下载文件和删除文件
• 注销测试账号或不再使用的账号，清理对应的设备、文件和上传记录

作为部署者怎么启动服务

本地直接运行

1. 设置服务端密钥：

export LINKNEST_JWT_SECRET='replace-with-local-secret'

2. 启动服务端：

go run ./server/cmd/linknest-server --config ./deploy/config.example.yaml

3. 检查服务是否启动成功：

curl http://127.0.0.1:8080/healthz

如果返回 {"status":"ok"}，说明服务已经可用。

用 Docker Compose 部署

1. 设置服务端密钥：

export LINKNEST_JWT_SECRET='replace-with-server-secret'

2. 启动服务：

docker compose up -d --build

3. 检查状态：

docker compose ps
curl http://127.0.0.1:8080/healthz

作为服务器管理员，你至少会用到这些入口

• 登录页：http://<server>:8080/login
• 设备页：http://<server>:8080/devices
• 文件页：http://<server>:8080/files
• 任务页：http://<server>:8080/tasks
• 健康检查：http://<server>:8080/healthz

如果你部署时做了反向代理或端口映射，比如把公网 80 转发到容器 8080，把上面的 :8080 替换成你的实际访问地址即可。

作为普通用户怎么登录和使用 Web UI

1. 打开登录页：

http://<server>:8080/login

2. 使用同一个账号注册或登录。

3. 登录后按页面使用：

• Devices：查看当前账号下的在线设备、P2P 能力、监听端口和候选地址类型，离线设备会自动隐藏
• Files：上传文件、查看文件列表、下载文件、删除文件，也可以选择一个在线目标设备发起 V2 P2P 优先传输；浏览器直连失败时会回退到云端分片链路
• Tasks：查看 V1 上传任务和 V2 P2P/cloud 传输任务、路径、失败原因和回退状态
• 页面右上角的 注销账号：输入当前密码后删除该账号及其设备、文件和上传记录

手机怎么用

• 手机当前通过浏览器访问同一个账号即可使用
• 当前是 Web 使用方式，不是原生 App
• 手机可以登录、查看在线设备、查看文件、上传下载
• 当前“正式设备绑定”主要由 CLI 客户端完成，手机浏览器更适合作为 Web 用户入口

作为 Windows 用户怎么使用桌面端

直接使用 release 里的可执行文件

1. 下载 GitHub Release 里的 Windows 压缩包。
2. 解压后运行 linknest-desktop.exe。
3. 在账号页先保存服务器地址，再登录或注册。
4. 在设备页绑定当前设备，并按需启动在线心跳。
5. 在设备页可以启动/停止 P2P 服务；在文件页的 P2P 目标设备 下拉框中选择在线设备后，可以发起 P2P 优先传输。
6. 在文件页上传、下载和删除文件，在上传任务页查看 V1 上传任务和 V2 传输任务状态。

自己编译 Windows 桌面端

需要：

• Go
• CGO_ENABLED=1
• 可用的 Windows C 编译器，例如 MSYS2 UCRT64 的 gcc / g++

编译命令：

mkdir -p ./bin
go build -o ./bin/linknest-desktop.exe ./client/desktop/cmd/linknest-desktop

作为 Android 用户怎么使用移动端

Android GUI 使用底部页签和手机单列布局。账号页使用短标签竖向表单，长 URL、ID、路径和文件名会自动换行或缩短展示，状态信息显示在内容顶部，避免挤占底部页签和中间列表区域。设备页可以启动/停止 P2P 服务，文件页提供独立的 P2P 目标设备 选择控件并发起 P2P 优先传输，任务页展示 V1 上传任务和 V2 传输任务。Android 端下载文件会优先保存到系统公共 Downloads 目录，系统拒绝写入时才回退到应用沙箱 Documents 目录。

自己构建 Android 安装包

需要：

• Go
• Android SDK
• fyne 打包工具

推荐命令：

cd ./client/mobile/cmd/linknest-mobile
fyne package -os android -app-id top.ledouya.linknest.mobile -name LinkNestMobile

如果要在 WSL/Linux 环境一次性构建 Windows GUI zip 和 Android APK，可以使用本仓库的脚本：

GO_BIN=/home/ledouya/.local/lib/go/bin/go \
FYNE_BIN=/home/ledouya/go/bin/fyne \
ANDROID_HOME=/home/ledouya/.local/android-sdk \
PATH=/home/ledouya/.local/mingw-w64/usr/bin:$PATH \
./scripts/build-gui-artifacts.sh

脚本会输出到 dist/gui-artifacts/，并打印每个产物的 SHA-256。Windows GUI 需要 Linux 侧 mingw-w64 交叉编译器；Android APK 需要 Android SDK、build-tools、platforms 和 NDK。

iPhone / iPad 能不能做

• 可以共用同一套 Fyne / Go 移动端代码
• 但最终 iOS 构建、签名和上架必须在 macOS + Xcode 环境完成
• 所以当前这一步先落 Android，后续如果你有 macOS 环境，再补 iOS 打包链路

作为 CLI 用户怎么绑定设备和保持在线

新用户

go run ./client/cmd/linknest setup --register --username demo --email demo@example.com --password password

这条命令会一次性完成：

• 注册账号
• 登录账号
• 初始化当前设备
• 把当前设备注册到服务器

已有账号用户

go run ./client/cmd/linknest setup --username demo --password password

这条命令会一次性完成：

• 登录账号
• 初始化当前设备
• 把当前设备注册到服务器

保持设备在线

go run ./client/cmd/linknest online

这会持续发送设备心跳，让当前设备在设备页里显示为在线。

如果要让当前设备可接收 V2 P2P 直传，启动 P2P 接收服务：

go run ./client/cmd/linknest p2p serve

查看本机 P2P 配置：

go run ./client/cmd/linknest p2p status

查看在线设备：

go run ./client/cmd/linknest device list

设备列表默认只显示在线设备。DHCP 场景下历史离线设备会继续保留在服务端记录中，但不会出现在 CLI、Web UI、Windows 桌面端或 Android 移动端的设备列表里。

向同账号在线设备发起 V2 传输：

go run ./client/cmd/linknest transfer send ./demo.zip --to <device_id>

查看 V2 传输任务：

go run ./client/cmd/linknest transfer list
go run ./client/cmd/linknest transfer detail <transfer_id>

如果 P2P 探测、连接或 hash 校验失败，默认自动回退到 V1 云端分片上传链路。也可以手动请求回退：

go run ./client/cmd/linknest transfer fallback <transfer_id>

怎么上传、下载、删除文件、查看任务和注销账号

通过 Web UI

1. 进入文件页：http://<server>:8080/files
2. 选择文件后上传
3. 在任务页：http://<server>:8080/tasks 查看进度
4. 在文件页中下载目标文件
5. 在文件页中点击目标文件右侧的删除按钮，可以从服务器移除该文件
6. 如果不再需要当前账号，可以点击页面右上角的 注销账号，输入当前密码后清理该账号的数据

通过 CLI

上传文件：

go run ./client/cmd/linknest file upload ./demo.zip

查看文件列表：

go run ./client/cmd/linknest file list

下载文件：

go run ./client/cmd/linknest file download <file_id> --output ./downloaded-demo.zip

删除文件：

go run ./client/cmd/linknest file delete <file_id>

查看任务列表：

go run ./client/cmd/linknest task list

继续未完成任务：

go run ./client/cmd/linknest task resume <upload_id>

注销当前账号：

go run ./client/cmd/linknest auth delete --password <当前密码>

执行后会：

• 删除当前账号下的设备记录
• 删除当前账号下的文件和上传任务
• 清理服务器上的用户文件存储目录和分片目录
• 清空本地 CLI 保存的登录 token

常见访问入口

• 登录页：/login
• 设备页：/devices
• 文件页：/files
• 任务页：/tasks
• 健康检查：/healthz

默认路径

• 本地数据库：./data/linknest.db
• 本地文件存储：./data/storage
• 本地分片目录：./data/chunks
• Docker 数据库：/var/lib/linknest/linknest.db
• Docker 文件存储：/var/lib/linknest/storage
• Docker 分片目录：/var/lib/linknest/chunks

补充文档入口

• client/：CLI 客户端代码和模块说明
• client/desktop/：Windows 桌面端代码和构建说明
• client/mobile/：Android 移动端代码和构建说明
• server/：服务端代码、迁移脚本和 Web 资源
• deploy/：本地和 Docker 配置模板
• docs/api.md：API 说明
• docs/dev-plan.md：开发计划

各级目录下也都带有 README.md，用于说明该目录的职责、结构和文件用途。