Skip to content

About

把本机端口、Docker 容器、局域网或公网服务一键放到飞牛 fnOS 桌面

Resources

Stars

15 stars

Watchers

0 watching

Forks

Latest commit

 

History

13 Commits

Folders and files

Repository files navigation

QLink2Desktop

把本机端口、Docker 容器、局域网 / 公网服务,一键放到飞牛 OS(fnOS)桌面。

QLink2Desktop logo

🙏 项目来源

自从接触到了飞牛之后,很多东西都想放在飞牛上来,因为家里装了米家的设备,还有Home Assistant(为了联动美的的家电),还有米家的中枢网关和米家WIFI,在外面的时候有时候就想设置下路由器和中枢之类的,原来也用过很多的软件,但是都不是很好的能适用,在外面打不开,用过的有米大神的fndesk、XIAOBONET的扩展图标管理、古大羊的lucky等,米大神的fndesk用着很好,但是就是路由器这个链接一直没弄好,提示权限相关的限制,就是通不了,lucky也一直捅不过去,所以米家路由器一直没有转过去,这次这个程序的开发是最近有公众号在推fndocker-to-desktop,我就使用了一下,嘿,竟然给弄好了,惊喜,不过原始的界面还有一些逻辑我自己不是太喜欢,所以就有了这个程序,当然了,还是除了图标全AI,HAHA。。。谁让咱不会写代码呢。。。以上。。。

本项目基于 fn-docker-to-desktop(把 Docker 放到桌面)二次重构而来。

原项目提供了非常出色的核心思路——把任意服务注册成飞牛原生桌面应用、并借助飞牛 Connect 打通外网访问。没有这个起点,就没有本项目。


✨ 功能特性

能力 说明
🔍 自动发现 流式解析内核套接字表 + Docker API,自动列出服务而不是一堆套接字(同一服务的 IPv4/IPv6、tcp/udp、多网卡绑定收成一条),标注可见范围与协议
🖥️ 一键上桌面 把端口 / 容器 / 代理 / 快捷方式注册为飞牛原生应用,出现在真实桌面上
🌐 反向代理 局域网、公网服务统一代理成本机端口,可测试连通性、可忽略自签证书
🔀 端口转发 四层 TCP / UDP 转发,SSH、远程桌面、数据库、DNS 都能穿过去,带黑白名单与连接记录
🔗 SSH 隧道 其它机器(另一台 NAS、软路由、树莓派)上的服务也能放到桌面
🏷️ Watchcow 兼容 直接识别 Docker Compose 里的 watchcow 标签,一键启用
🖼️ 自动抓图标 按镜像名匹配官方图标库;匹配不到就抓目标站点自己的 favicon(页面声明 → 根目录 /favicon.ico),内网服务也能有对的图标。查找过程可见:编辑器里显示「正在查找图标…」,结束后说明命中或失败的原因与地址;列表缩略图用的就是实际解析出的那枚
🔤 文字图标 内嵌点阵字模 + 配色,无图可用时现场生成一枚
🗂️ 图标库复用 编辑器里可直接从已上传的图标中挑一枚(带选中高亮与对勾),不必把同一张图反复重传
🎨 明暗 × 六色系 白天 / 暗黑 / 跟随系统,六套色系一键切换,偏好存在浏览器本地,首帧不闪白
🔁 CGI 跳转 网址快捷方式经由飞牛 CGI 入口 302 到目标网站,桌面入口的主机限制不影响抵达
♻️ 一键重启 面板内直接重启本应用服务,服务回来时页面自动重连,不必跑回应用中心
🚪 零端口占用 通过飞牛统一网关(Unix Domain Socket)接入,不占任何 TCP 端口
🧹 桌面图标对账 启动时只补齐缺失项、只修复过期项,健康项绝不重装
🛡️ 安全卸载 只清理 qlink2d. 命名空间下的包,绝不触碰用户的其它应用

📦 安装

  1. 前往 Releases 下载与设备架构匹配的安装包(文件名里带版本号):
    文件 适用设备
    qlink2desktop-<版本>-x86.fpk Intel / AMD 平台
    qlink2desktop-<版本>-arm.fpk ARM 平台(ARM 盒子、树莓派类设备)
  2. 飞牛 OS → 应用中心 → 右上角「手动安装」→ 选择 .fpk 文件。
  3. 安装完成后桌面出现 QLink2Desktop 图标,点开即用。

💡 访问走的是飞牛统一网关(/app/qlink2desktop),不占用任何端口,也不会与其它应用冲突。
如需局域网直连调试,可在启动环境里设置 PORT 环境变量。

🧭
若页面停在启动态,12 秒后会把版本号、文档 URL、加载失败的资源清单直接写在页面上;
这一条正是为了让「打不开」不再是一句无法排查的描述。
如果应用中心提示"已是最新"或拒绝覆盖安装,请先卸载旧版再安装。


🚀 快速上手

打开面板后有四类入口:

  1. 桌面应用 —— 已放到桌面的全部链接,可编辑、启停、重新同步、导出备份。
  2. 发现 —— 四个标签页:本机端口 / 容器标签 / 局域网扫描 / 远程主机,勾选即可一键放桌面。
  3. 图标库 —— 上传图标,之后在任何一条链接里都能直接挑着用。
  4. 设置 —— 界面主题(明暗 × 六色系)、门户名称、访问口令与启动行为。
  5. 系统 —— 版本信息、对账结果、运行日志、日志下载,以及重启本应用服务。

第一次使用建议:进入「发现 → 本机端口」,勾选一个正在跑的服务,点启用,回桌面看图标。

🎨 换个颜色:设置页第一张卡片就是「界面主题」——白天 / 暗黑 / 跟随系统,
外加晴空蓝、湖水青、新芽绿、紫罗兰、暖阳橙、玫瑰红六套色系。
顶栏右侧也有一颗明暗切换按钮,不用每次都绕进设置页。
这个偏好只存在当前浏览器里(localStorage),不会影响其它设备,
也不会写进服务端配置;首帧之前就已生效,深色用户不会看到闪白。


🛠️ 从源码构建

依赖:Go 1.23+(或 Docker)、bash。打包会自动从官方地址下载 fnpack。

# 全部质量门禁(gofmt + go vet + go test + 前端 import 校验)
make check

# 网关等效端到端验证:用两个 HTTP 代理复刻飞牛统一网关的两种转发方式,
# 逐条验证「网关之后」页面能否正常打开(尾斜杠自愈 / 资源 / import 图 /
# 首屏单请求 / 鉴权边界 / 深链接回退)。真机白屏类问题只能这样复现。
make e2e

# 打包(默认 x86,用 VERSION 文件里的版本号)
make fpk
make fpk ARCH=arm

# 双平台一起出包(同一版本号,便于反复验证)
make fpk-all

# 正式发版:先手动把 VERSION 改成目标版本号(脚本只读不写、不会自动 +1),再一次性构建双架构
make release

# 本地起服务调试
make run

🧭 架构一览

cmd/server          入口:server / cgi 双模式,飞牛统一网关接入
cmd/iconforge       从源图生成全套官方规格图标
internal/
  domain            领域模型:Link(定义)/ Status(运行态)严格分离
  store             JSON 持久化,原子写入 + 损坏文件隔离
  discovery         服务发现:procfs 套接字表 / Docker 标签 / 局域网扫描 / SSH
  proxy             反向代理:httputil.ReverseProxy + SSE 友好的传输层
  forward           端口转发:四层 TCP/UDP 中继、访问控制、会话回收与连接记录
  fnos              飞牛桌面注册:manifest / 包树 / appcenter-cli 编排 / 图标
  gateway           统一网关:Unix Socket 监听 + CGI 转发
  auth              口令派生 + 内存会话
  httpapi           REST API + SSE 实时事件
  logx              环形缓冲日志 + 轮转文件
  webui             原生 ES 模块前端,go:embed 内嵌,零构建步骤
  app               装配 + 编排器(对账 / 稳定端口分配 / 守护)
fnos-app/           本应用自身的 fpk 包骨架(manifest / cmd / config / wizard / ui)
scripts/            打包脚本(自动获取官方 fnpack)
docs/               架构说明

更多设计决策见 docs/ARCHITECTURE.md。


🔐 关于 Root 权限

本应用声明以 root 运行,原因是它必须:

  • 调用 appcenter-cli 安装 / 卸载其它桌面应用(这是产品的核心能力);
  • 读取宿主机视角的 /proc 套接字表与进程 fd,才能发现真实在跑的服务;
  • 访问 Docker 的 Unix Socket 以枚举容器。

📋 版本历史

版本 内容
v1.2.9 每条链接的外网访问可以自选链路了。此前桌面图标在外网只有一种走法:飞牛 Connect 中继(端口型转发),速度由飞牛的服务决定;自建的公网反代明明更快,却只能去 fnOS 应用设置里单独配反代域名,配完桌面入口照旧走中继。现在编辑页多了一张「外网访问」卡片,三段选择、逐链接生效:飞牛 ID(默认,行为与从前完全一致);fnOS 反代——桌面入口不再声明端口,改为 /<应用名>/ 前缀路径,由 fnOS 内置 Nginx 按应用端口反代,外网无论走 fnOS 的路径型中继还是用户自配的反代域名,落点都一致;自定义公网——填一个公网反代地址,桌面入口换成 CGI 分流:按访问来源的 Host 判定内外网(私有 IP、localhost、*.local 算内网),内网直连本机端口,外网 302 跳到反代地址。桌面列表会标注每条链接外网走哪条路。原有模式仍是默认,三种形态互不影响,网址快捷方式不受影响
v1.2.8 给链接选图标时,可以直接从「图标库」里挑一枚已有的了。此前图标库只有入口没有出口:能往里传,不能在别处从里面选 —— 想给第二条链接用上同一张图,唯一的办法是把那张图再从本机翻出来重传一遍,于是目录里堆出 miwifi.png / miwifi-1.png 好几份内容相同的文件,谁也说不清哪条链接在用哪一份。现在编辑器「图标」卡片多了一档**「图标库」**:列出已上传的全部图标(带文件名),点一下即选中,选中的那枚有描边、浅底与右上角对勾,缩略图立刻跟着换,下面还写明选的是哪一枚;换选另一枚时选中态会跟着走。它和「上传」档共用同一套数据(文件名 + 图标目录),所以列表缩略图、桌面图标、打包三条已有路径一行都没动。图标库为空时给出明确指引(切到「上传」档传一张,或去「图标库」页批量上传),不会只留一个空网格让人以为坏了
v1.2.7 服务发现不再一屏全是重复的端口。「本机端口」列表是按内核套接字逐条列的,而同一件事物往往占好几个套接字:IPv4 的 0.0.0.0 与 IPv6 的 :: 各一份、tcp 与 udp 各一份,nmbd 这类还会在每一个网卡地址上各绑一份。于是飞牛上"监听端口 101 个"里真正不同的服务不到二十个,屏幕上就是一片看起来一样的卡片;更糟的是协议只被当成"副标题为空时的兜底"来显示,同地址同端口的一对 tcp / udp 于是渲染成两条一模一样的行。现在改为按「进程 + 端口」收成一条:协议永远显示在端口号下方(TCP / UDP / TCP+UDP),绑定地址归纳成「全网卡可见」「仅本机」「N 个网卡地址」,悬停可看到完整地址清单;统计卡改称「监听服务」,并在提示里说明合并前共有多少个内核套接字(101 → 二十来个不能让人以为漏了端口)。另把窗口尺寸变化后重绘的行为也纳入真浏览器回归 —— 确认重绘是"替换"而不是"往后追加"。另:更新了软件 logo,并顺带解决了图标缩到 64 px 时不够清晰的问题(换成一步面积平均 + 轻度锐化的缩放管线)
v1.2.6 图标解析过程第一次对用户可见:此前「自动」那一档的预览永远画着内置默认图,而且一个字都不解释 —— 「还没去找」「去找了没找到」「根本没找」三种情况在界面上完全同形,用户得到的结论是「这个图标功能没反应」。现在编辑器里切到「自动」就会真的找一次,并在旁边显示「正在查找图标…」转圈,结束后给出结论与来龙去脉:命中了官方图标库(带关键词)、从站点抓到了(带地址)、还是访问过了但对方没有(带地址与原因);旁边有「重新查找」按钮,改端口 / 换形态 / 改地址会自动重查。桌面列表的缩略图也换成实际解析出的那枚(此前一律是默认图,这也是"没自动找到"的第一现场),鼠标移上去可以看到它的来历。另修一处真机 bug:解析接口原先用严格解码,而它收到的其实是整条链接的表单数据,于是链接多一个字段就会把预览打挂(报的是 json: unknown field "desc",与图标毫无关系)。顺带把官方图标库匹配也加上总预算 —— 它是「候选 × 关键词 × 4 个 CDN」的乘法,国内访问 jsDelivr 不通时会逐个等满超时
v1.2.5 「自动」图标现在会去抓站点自己的 favicon:按镜像名匹配不到官方图标库时,改为向目标地址要图标 —— 先读页面里的 rel="icon" / apple-touch-icon,再退到站点根目录的 /favicon.ico(ICO 解码内置实现,标准库不支持;自动挑尺寸最大的那一档)。这一步对内网服务尤其有用:公开图标库不会有你自家 NAS 上那个服务。抓取有 5 秒总预算、结果(含失败)进缓存,受 --no-remote-icon 管辖,带自签证书的站点勾选「忽略自签证书」即可取到。另:侧边栏那排计数徽标整个去掉(数字与圆圈),手机端连底部的状态圆点也一并撤掉 —— 那里没有文字,只剩一枚看不出含义的绿点
v1.2.4 手机端导航再打磨:底部条改为等分布局、圆角柔底选中态,条高与内容区留白统一由 --navbar-h 推导(两处不再各写一个数字),自动避开虚拟导航键与全面屏手势条(env(safe-area-inset-bottom)),安卓软键盘改为压缩内容而非顶起视口;修复侧边栏计数徽标要点进对应页面才显示——数字原先只在各视图自己的 mount() 里拉取,现在启动时统一拉一次,计数为 0 时不再挂一枚「0」;另补尺寸类回归守卫(图标 ≥20px、底条 ≥52px、留白 ≥ 条高),避免这类"能用但难看"的退化再溜过验证
v1.2.3 修复手机端导航整体消失:窄屏样式里一条 span:not(.nav-badge){display:none} 本意"只留图标",但图标本身也是 span,于是图标与文字一起被隐藏,七个功能项全变成看不见、仅 37×14px 的空白按钮(点不准也就切不了功能区)。现在窄屏改为底部固定导航条:图标 + 功能名并排、触摸目标 46px、自动避开全面屏手势条,宽屏仍是左侧栏。另补真浏览器窄屏回归(360 / 390 / 430 / 1280 四种视口,按真实坐标点击)
v1.2.2 新增四层端口转发:TCP / UDP 任意服务转发(与七层反向代理互补),支持 IP/CIDR 黑白名单、并发上限与实时连接记录;TCP 双向中继半关闭,UDP 会话表空闲回收;自转发 / 两跳环 / 规则端口冲突在落盘前拦截,端口被外部程序占用时不阻断保存、仅作 warning;Linux 监听绑定形态自动退让(双栈 → 仅 IPv4 → 仅 IPv6),列表标注实际监听形态,并通过 /proc/net + fd inode 反查端口占用进程;转发规则独立持久化于 forwards.json,前端新增转发管理页并支持「放到桌面」
v1.0.0 首个版本:本机端口与 Docker 容器自动发现,一键注册为飞牛原生桌面应用;局域网 / 公网服务反向代理(支持连通测试、忽略自签证书);远程主机 SSH 隧道;网页快捷方式(经飞牛 CGI 跳转)与文字图标生成器;兼容 Watchcow 容器标签;白天 / 暗黑 / 跟随系统 × 六套色系;启动时桌面图标对账、卸载仅清理本应用命名空间;飞牛统一网关原生接入,零 TCP 端口占用

完整发布记录见 Releases。


📄 许可证

MIT

本项目基于 fn-docker-to-desktop 二次重构,感谢原作者以 MIT 许可证开源。

About

把本机端口、Docker 容器、局域网或公网服务一键放到飞牛 fnOS 桌面

Resources

Stars

15 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages