max1874/ferry
max1874/ferry has 46 GitHub stars and 2 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 22:37 UTC. Last push 2026-11-02.
实测星标增长
- 24小时
- 0
- 7天
- 正在收集历史
- 15天
- 正在收集历史
- 1个月
- 正在收集历史
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Self-hosted clipboard and file ferry for devices on one private network: a single Go server with a built-in web app, so any browser is a client. Native iOS and Android apps are optional.
自托管README.zh-Hans.md
原文
动图录自 max1874.com/ferry,那里可以亲手试。
让你的 agent 帮你部署
把下面这段话复制给能够在目标电脑上执行命令的 agent,就可以让它带你完成 Docker 部署。安装软件或获取系统权限时,可能需要你授权。
请在这台电脑上用 Docker 部署 Ferry,让同一私有网络里的手机和其他电脑都能使用。请实际执行部署,不要只给操作说明。
先阅读 https://github.com/max1874/ferry/blob/main/README.zh-Hans.md 并查看 https://github.com/max1874/ferry/releases/latest,使用最新稳定版本的 Docker Compose 部署包及其对应的已发布镜像。
检查操作系统、CPU 架构、Docker Engine 和 Compose v2,以及是否已有 Ferry 部署。缺少依赖时,说明需要安装什么并征得我的同意。保留已有部署、配置和数据;升级前先备份。
新部署使用独立目录,保留部署包的目录结构,配置持久化存储和合适的私有局域网 IP,检查端口可用后拉取并启动 Ferry。如果有多个可能的网络,请问我设备使用哪一个。只在可信私有网络内提供服务,不要暴露到公网或关闭防火墙。
检查容器状态、日志和所选局域网地址的 HTTP 访问,解决部署错误。最后告诉我安装版本、部署目录、浏览器访问地址,以及停止、启动、升级和备份的命令。然后引导我进入 Devices → Connect another device,扫码接入并完成一次文字和文件传输。区分你已完成的验证和仍需我的手机或确认的步骤,不要把本机检查成功说成跨设备传输成功。
想自己执行命令?请看快速开始。
Ferry 是什么?
Ferry 是一个自托管的剪贴板与文件摆渡工具,服务于同一个可信私有网络里的设备。它长得像聊天:你发出的所有内容都落在一条时间线上,每台已接入的设备都能看到,所以把一个链接从手机挪到电脑,就是一次粘贴加一次复制,不用再给自己发邮件。
一个 Go 进程同时提供 Web 应用和 API,把消息和设备身份存进 SQLite,把上传的文件字节放在本地 blob 目录。任何内容都不会离开你运行它的网络,也不需要注册账号。
为什么不直接给自己发消息?
因为来回一趟就是成本。在聊天软件里给自己发消息,会把你的剪贴板内容发到别人的服务器上,会压缩你的截图,还要求每台设备都登录账号。AirDrop 要求两台设备都醒着、解锁、在同一个房间,而且没有可以往回翻的历史。
| 方面 | Ferry 的做法 |
|---|---|
| 内容存在哪 | 你自己运行的一个进程,在你自己的硬件上 |
| 账号 | 没有;设备凭可选的共享密码加入,拿到一个可撤销的 token |
| 历史 | 一条持久的时间线,而不是传完就消失的一次传输 |
| 文件 | 按上传原样存储和提供,最大 64 MB,不重新编码 |
| 剪贴板 | 只由你自己的粘贴快捷键和复制控件读写 |
| 网络 | 默认只监听 loopback;局域网地址和监听所有网卡都要显式开启;从不绑定主机名或公网地址 |
设备只需要一个浏览器
手机、平板和电脑在浏览器里打开 Ferry 的地址就能加入,不用在上面安装任何东西。Web 应用可以发送文字、链接、照片和文件,一点就能复制消息,能预览图片、下载文件。
iOS 和 Android 原生 App 是可选的。GitHub Release 附带 Android APK;iOS 单独分发。见原生 App。
快速开始
你需要一台常开的电脑,装有 Docker 和 Docker Compose v2,系统是 64 位 x86(amd64)或 ARM(arm64)。不需要克隆本仓库,也不需要安装 Go。
从最新版本下载 Compose 文件并进入目录:
curl -fLO https://github.com/max1874/ferry/releases/download/v1.0.5/ferry-1.0.5-docker-compose.tar.gz tar -xzf ferry-1.0.5-docker-compose.tar.gz cd ferry下载包里有
compose.yaml、.env.example和用于备份的scripts/ferry-data.sh,请保持这个目录结构。它不是程序本身:Ferry 启动时,Compose 会拉取公开镜像ghcr.io/max1874/ferry:1.0.5。创建配置文件:
cp .env.example .env查到这台电脑的局域网 IP。 它通常以
192.168.、10.或172.16.–172.31.开头。系统 命令 macOS ipconfig getifaddr en0(Wi-Fi)或ipconfig getifaddr en1Linux hostname -IWindows ipconfig,看“IPv4 地址”把它写进
.env。 把FERRY_HOST_IP=127.0.0.1改成你的地址,例如:FERRY_HOST_IP=192.168.1.20保留
127.0.0.1的话,只有这台电脑自己能访问 Ferry。启动 Ferry:
docker compose up -d docker compose logs ferry日志会写出要打开的地址,例如
open Ferry at http://192.168.1.20:42817 from devices on the same private network。在这台电脑的浏览器里打开这个地址。第一台设备会直接加入。
第一次在两台设备间传送
- 在电脑上,点空时间线上的 Connect another device,或者打开 Devices。Ferry 会显示它的地址和一个二维码。
- 在手机上,连到同一个 Wi-Fi 或私有网络,然后用相机扫码,或者在浏览器里输入这个地址。
- 手机会直接加入。如果你设置过访问密码,它会先要求输入密码。
- 在手机上粘贴一段文字并发送。它会出现在电脑上;点消息上的 Copy。
- 在电脑上发送一张照片或一个文件。手机上图片直接预览,其他文件可以下载。
任何已加入的浏览器都可以在 Devices → Access password 里开启共享密码。它只拦截新设备;已加入的设备在被撤销前一直保持加入。
在消息上选择 Recall 并确认,会从服务器和已更新的设备移除该内容。任意已加入设备都能撤回任意消息,不限时间;已有副本、下载和备份不在撤回范围内。
升级与备份
要实时同步撤回,请先升级服务端,再更新原生客户端。旧客户端可能保留已加载的消息,直到刷新或重新连接。
每次升级前先备份。在部署目录里运行:
scripts/ferry-data.sh backup ../ferry-backup-$(date +%F).tar.gz
然后只修改 .env 里 FERRY_IMAGE 末尾的版本号,拉取镜像并重建容器:
docker compose pull
docker compose up -d
docker compose logs --tail=100 ferry
恢复时,指定要恢复的归档,以及一个新的、保存当前数据的安全备份:
scripts/ferry-data.sh restore ../ferry-backup-2026-09-14.tar.gz ../before-restore.tar.gz
这个工具会短暂停止正在运行的 Ferry,让 SQLite 和 blob 一起归档;归档里如果有 Ferry 数据之外的东西,它会拒绝。恢复时先写好安全备份再替换数据卷,并且只有在恢复成功、且操作前 Ferry 本来在运行时才重启它。请把备份拷到服务器以外的地方;备份里有消息、文件、设备 token 的 hash 和密码校验值。
把现有的源码部署切换到镜像
如果你之前用 git clone 和 docker compose up --build 部署 Ferry,请在同一个目录里升级,这样 Compose 会继续使用同一个数据卷:
scripts/ferry-data.sh backup ../ferry-backup-before-upgrade.tar.gz
git pull --ff-only
docker compose pull
docker compose up -d
docker compose logs --tail=100 ferry
如果你的 .env 里 COMPOSE_FILE 包含 compose.build.yaml,请先从这一行里去掉它(保留 override 文件),否则 Compose 会继续构建源码,而不是使用镜像。消息、文件、设备身份和密码都会保留。如果想继续从源码构建,见从源码构建镜像。
其他部署方式
只在这台电脑上试用
跳过快速开始的第 3、4 步。这时 Ferry 监听 http://127.0.0.1:42817,只有这台电脑能打开;Devices 页面会提示你先改用局域网地址,才会显示二维码。
配置项
| 配置 | 默认值 | 含义 |
|---|---|---|
FERRY_IMAGE |
ghcr.io/max1874/ferry:1.0.5 |
运行的镜像和版本 |
FERRY_HOST_IP |
127.0.0.1 |
Docker 把端口发布到宿主机的哪个地址;必须是 loopback 或私有地址 |
FERRY_PORT |
42817 |
宿主机和容器里使用的端口 |
FERRY_TRUSTED_ORIGIN |
空 | 你自己的 TLS 反向代理的 origin |
FERRY_LISTEN_HOST |
容器自己的 IP | Ferry 在容器里监听的地址 |
默认的监听方式要求容器恰好只有一个 IP 地址,否则启动失败。设置 FERRY_LISTEN_HOST=0.0.0.0(或 ::)可以监听容器的所有网卡,比如容器加入了第二个 Docker 网络时。在普通的 bridge 容器里,0.0.0.0 仍然只能通过发布在 FERRY_HOST_IP 上的端口被外部访问。使用 network_mode: host 时,容器的网卡就是宿主机的网卡,防火墙放行的所有宿主机网卡都能访问 Ferry。
放在你已有的反向代理后面
如果要通过私有域名、用你自己的 TLS 代理访问 Ferry(比如在 VPN 里),要设置 Ferry 应该接受的那一个浏览器 origin。代理必须转发原始的 Host 头,Caddy 默认就会这样做。Host 或 Origin 指向其他域名的请求仍会被拒绝。代理到 Ferry 这一跳是明文 HTTP,所以要让它留在 loopback 或私有网络里。reverse_proxy 后面填什么,取决于代理跑在哪里。
代理装在宿主机上,或者代理容器使用 network_mode: host。 在 .env 里设置 FERRY_TRUSTED_ORIGIN=https://ferry.example.com,保留 FERRY_HOST_IP=127.0.0.1,连到发布的端口:
ferry.example.com {
reverse_proxy 127.0.0.1:42817
}
代理跑在自己的 bridge 容器里。 这时代理容器里的 127.0.0.1 指向代理自己,所以要把 Ferry 接入代理所在的 Docker 网络,并用服务名访问。Ferry 这时有两个 IP 地址,所以要在 .env 里同时设置 FERRY_TRUSTED_ORIGIN=https://ferry.example.com 和 FERRY_LISTEN_HOST=0.0.0.0,并在 compose.yaml 旁边新建 compose.override.yaml。只有在没有指定任何文件时,Compose 才会自动加载它;使用 COMPOSE_FILE 或 -f 时,要把它放在最后,例如 COMPOSE_FILE=compose.yaml:compose.build.yaml:compose.override.yaml,否则容器会丢掉代理网络。这种部署方式还没有端到端实测过;如果遇到问题,请开 issue。
services:
ferry:
networks: [default, proxy]
networks:
proxy:
external: true
name: caddy_default # 代理所在的网络名,用 `docker network ls` 查看
ferry.example.com {
reverse_proxy ferry:42817
}
从源码构建镜像
在本仓库的克隆里,compose.build.yaml 会构建当前检出的源码,而不是拉取已发布的镜像。服务、数据卷和配置都保持不变。要让每条命令(包括备份脚本)都使用它,在 .env 里加上 COMPOSE_FILE=compose.yaml:compose.build.yaml(Windows 上用 ; 分隔),然后运行 docker compose up --build -d。一次性的等价写法是:
docker compose -f compose.yaml -f compose.build.yaml up --build -d
一旦指定了文件,Compose 就不会再自动加载 compose.override.yaml。如果你用了它,比如上文的代理网络,也要把它写上:
docker compose -f compose.yaml -f compose.build.yaml -f compose.override.yaml up --build -d
不用 Docker,直接从源码运行
要求:Go 1.26.3 或更新版本。
go run ./cmd/ferry -listen 127.0.0.1:42817
go run ./cmd/ferry -lan -listen 192.168.1.20:42817 # 局域网可访问
go run ./cmd/ferry -lan -listen 0.0.0.0:42817 # 所有网卡;Ferry 会在日志里警告
go run ./cmd/ferry -listen 127.0.0.1:42817 -trusted-origin https://ferry.example.com
本地状态写到被 git 忽略的 ./ferry-data 目录;用 -data-dir 可以换一个位置。
排错
| 症状 | 可能原因与解决办法 |
|---|---|
| 手机打不开地址 | 日志里写着 on this computer only:把 .env 里的 FERRY_HOST_IP 改成服务器的局域网 IP,再运行 docker compose up -d。否则检查手机是否在同一个网络里,而不是开了客户端隔离的访客 Wi-Fi 或移动网络,以及服务器防火墙是否放行了这个端口。 |
| Devices 页面不显示二维码 | 页面是通过 localhost 或 127.0.0.1 打开的。改用服务器的局域网 IP 打开 Ferry,再从那里扫码。 |
代理返回 421 Misdirected Request,错误码 invalid_host |
没有设置 FERRY_TRUSTED_ORIGIN,或者它和浏览器里的地址不完全一致,或者代理改写了 Host。 |
容器退出并提示 expected exactly one container IP address |
容器接入了不止一个 Docker 网络。在 .env 里设置 FERRY_LISTEN_HOST=0.0.0.0。 |
published-host must be a loopback or private/link-local IP address |
FERRY_HOST_IP 是公网地址或主机名。改用服务器的私有 IP。 |
bind: address already in use 或 port is already allocated |
端口 42817 被其他程序占用。在 .env 里换一个 FERRY_PORT,并打开新的地址。 |
docker compose pull 失败 |
denied 或 unauthorized:运行 docker logout ghcr.io 清掉过期凭据,镜像是公开的。no matching manifest:服务器不是 amd64 或 arm64,比如 32 位的 Raspberry Pi OS,请在那里从源码构建。超时:检查服务器能否访问互联网,或代理设置。 |
原生 App
Web 应用可在所有设备上使用。可选的原生 App 连接同一个 Server;使用撤回前请先升级服务端。
| App | 当前状态 |
|---|---|
| iOS | 面向 iOS 26 的原生 SwiftUI MVP;FerryDrop 已在 App Store 上架。支持撤回和新时间线的 1.0.1 (2) 目前提供给已有内部 TestFlight 测试员 |
| Android | 面向 Android 8+ 的原生 Compose MVP;下载正式签名 APK,App 版本 1.0.1 (3)。已在真机验证跨设备撤回 |
iOS。 用 Xcode 26.6 或更新版本打开 ios/Ferry/Ferry.xcodeproj,运行 Ferry scheme。模拟器构建不需要 Team;真机需要你的 Apple Development Team。输入 Server 地址、设备名,以及可选的密码。要打 archive 时,在 Xcode 里设置 Team,并把证书和描述文件留在 Git 之外:
xcodebuild archive -project ios/Ferry/Ferry.xcodeproj -scheme Ferry \
-destination 'generic/platform=iOS' -archivePath /tmp/Ferry.xcarchive \
DEVELOPMENT_TEAM=YOUR_TEAM_ID
商店导出是需要维护者授权的一步。获得授权后,把 ios/ExportOptions.plist.example 复制成被忽略的 ios/ExportOptions.plist,替换 YOUR_TEAM_ID,再把这个文件传给 xcodebuild -exportArchive。
Android。 下载并打开发布 APK,如有提示则允许该来源安装,然后输入服务端地址。旧 debug 包可能使用不同签名;替换前请阅读发布说明。
要从源码构建,用 Android Studio 打开 android/,或者用 JDK 17 及以上和 Android SDK 37 构建 debug APK(wrapper 锁定 Gradle 9.8.1;Android Gradle Plugin 9.4.1,Kotlin 2.4.21):
cd android
./gradlew :app:assembleDebug
APK 生成在 android/app/build/outputs/apk/debug/ 下。要做签名 release,把 android/signing.properties.example 复制成被忽略的 android/signing.properties,把权限限制到当前用户,在本地创建它引用的 keystore,然后运行 ./gradlew :app:bundleRelease。任何会打包 release 的 Gradle 任务图,在签名配置缺失或不完整时都会失败。
开发
| 组件 | 当前状态 |
|---|---|
| Server + Web | Go/SQLite;从 1.0.0 起以双架构容器镜像发布 |
| iOS App | 原生 SwiftUI MVP;通过 App Store / TestFlight 单独分发 |
| Android App | 原生 Compose MVP;GitHub Release 提供签名 APK,也可从源码构建 |
自动发现、剪贴板同步、后台传输和 TLS/公网暴露都不在当前里程碑内。iOS 与 GitHub Release 单独分发;支持撤回的更新目前在内部 TestFlight。
贡献者需要:Go 1.26.3、Docker 和 Compose v2,按需安装 Xcode 26.6,或 Android Studio、JDK 17 及以上和 SDK 37。CI 不会在推送或 pull request 时自动运行;维护者会手动启动 GitHub Actions workflow,比如在发布之前。它运行的检查是:
scripts/check-repo.sh
go test -race -count=1 ./...
go vet ./...
node --check internal/webui/assets/app.js
docker compose config
scripts/ferry-data.sh self-test
(cd android && ./gradlew :app:testDebugUnitTest :app:lintDebug :app:assembleDebug)
xcodebuild test -project ios/Ferry/Ferry.xcodeproj -scheme Ferry \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=latest' \
-only-testing:FerryTests \
-derivedDataPath /tmp/FerryDerivedData
CI 还会构建 linux/amd64 和 linux/arm64 镜像,分别启动两个架构,检查数据能挺过重启、也能从源码构建切换过来,并把结果保留为发布候选。候选如何变成正式版本,见 docs/release-process.zh-Hans.md。
提交改动前请先读 CONTRIBUTING.zh-Hans.md。产品边界在 docs/product-core.zh-Hans.md,HTTP 合约是 api/openapi.yaml。
安全
Ferry 在可信私有网络里使用未加密的 HTTP,请不要把它暴露到公网。所有内容、设置和设备接口都需要可撤销的设备 Bearer token;可选的共享密码只拦截新设备。部署前或报告漏洞前,请先读 SECURITY.zh-Hans.md。
许可证
Ferry 以 MIT 许可证 授权。Web 应用内置了 Tabler Icons 和 QR Code generator library,两者均为 MIT 许可证。