# miao **Repository Path**: wliuslin/miao ## Basic Information - **Project Name**: miao - **Description**: miao 是用 JS 写的跨平台局域网即时通讯软件，可与飞鸽传书(ipmsg)互发消息和文件。 - **Primary Language**: JavaScript - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 3 - **Created**: 2024-07-06 - **Last Updated**: 2025-10-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README  # 简介 miao 是用 JS 写的跨平台局域网即时通讯软件，可与飞鸽传书(ipmsg)互发消息和文件。 - # 快捷安装步骤 1、用鼠标【右键】点击安装程序 run_miao.bat 的下载链接 [https://gitee.com/loyway/miao/raw/master/run_miao.bat](https://gitee.com/loyway/miao/raw/master/run_miao.bat)；【注意】不要用鼠标〖左键〗。用鼠标〖左键〗点击时，会直接在浏览器中显示文件内容，而不是下载它。 - 2、在弹出菜单中选择“从链接另存文件为...”, 当出现“请输入要保存的文件名...” 对话框时，注意选择一个合适的位置来保存 run_miao.bat 文件。【提示】miao 是一个开源、绿色软件，不写任何注册表信息。安装文件 run_miao.bat 所在的位置，就是 miao 软件将要安装的目的位置。在 Windows 下，建议把安装文件 run_miao.bat 放在硬盘 D: 或 E: 或 F: （等等）的根目录下。在 Linux 下，建议把 run_miao.bat 放在用户的主目录。 - 3、在 Windows 下（用鼠标左键）双击 run_miao.bat 即可开始安装。在 Linux 的终端命令提示符下，先（用 cd 命令）进入 run_miao.bat 所在的文件夹，再执行 sh run_miao.bat 命令即可开始安装。 - 4、安装完成后，会自动启动 miao。如果要卸载 miao，只需删除 miao 文件夹即可（需要先退出 miao 软件的运行）。 - 如果上述快捷安装未能成功，可能的原因和应对办法如下: - 出现了网络故障或其它异常情况, 导致安装程序未能成功下载 electron-v29.3.0-win32-x64.zip 文件（适用于 64 位 Windows）。请搜索 Internet, 找到后下载它, 并把它放在 run_miao.bat 所在的文件夹下, 然后再次尝试运行 run_miao.bat。如果 Windows 是 32 位系统, 则需要下载的文件是 electron-v29.3.0-win32-ia32.zip。如果是 Linux 系统, 则根据平台的不同, 需要下载的文件是 electron-v29.3.0-linux-x64.zip 或 electron-v29.3.0-linux-ia32.zip 或 electron-v29.3.0-linux-arm64.zip 或 electron-v29.3.0-linux-armv7l.zip 四者之一。【注意】从 electron-v23.0.0 开始，electron 不再支持 Win7/8。支持 Win7/8 的最后一个版本是 electron-v22.3.27。 - 另外, 在 Windows 下, 安装程序需要多次调用 wget.exe 和 unzip.exe 这两个工具。安装程序通常能够自动生成这两个工具。如果出现某种异常情况, 致使安装程序未能生成这两个 .exe 文件, 请从网络上找到它们, 并下载到 run_miao.bat 所在的文件夹下, 然后再次尝试运行 run_miao.bat。如果是 Linux 系统, 则需要在系统中安装 wget 和 unzip 这两条命令, 因为 run_miao.bat 运行时，需要多次调用这两条命令。 - ## 【重要说明】 新功能需要高版本的 nodejs, 因此从 2024 年开始不保证支持 WinXP 了。 - # miao 软件的特点 1、采用 nwjs、electron 跨平台技术，支持 Windows、Linux 等主流操作系统。 - 2、文件传输支持 UDP 协议，免除了（TCP 协议）跨路由器文件传输失败的困扰。 - miao 用户之间采用 UDP 协议收发文件。miao 与其它飞鸽类软件也可以互传文件，但 只能使用 TCP 协议（跨路由器传文件照样会失败）。 - 目前未实现发送文件夹的功能, 但可以用 TCP 协议接收飞鸽、飞秋发送的文件夹。 - 新版实现了简单的同步文件夹功能，可自动与好友同步文件。 - # 使用方法 本软件下载（解压）后即可使用, 无需安装。但是，本软件依赖 electron 或 nwjs， 您需要下载（或安装）两者之一，才能运行本软件。在有些操作系统（比如 ARM64 架构 的某厂商定制的 Debian 9.0）之下，直接安装 electron 或 nwjs 的办法（apt-get） 归于失败，只能手动下载 electron 或 nwjs 的二进制发布。下面只介绍手动下载的 安装步骤： - 1、下载本软件 miao（如果是压缩包，需要先解压），放在电脑上任意位置； - 2、下载 nwjs 或 electron，（解压后）放在电脑上任意位置，设置 PATH 环境变量； - 3、在命令行下，用 cd 命令进入 miao，然后执行“nw .”或“electron .”即可。 - ## 【提示】 1、Windows 下也可以通过把 miao 文件夹拖拽到 nw.exe 或 electron.exe 上来运行。 - 2、若把 electron 或 nwjs 解压后的顶级文件夹（即 electron-* 或 nwjs-*）与 miao 文件夹并列放在一起，比如，都放在 /home/foo 之下（Linux 的情况），或都放在 D:\ 之下（Windows 的情况），则可以通过运行 run_miao.bat 来启动 miao。 run_miao.bat 既是合法的 Windows 批处理, 也是合法的 Linux shell 脚本。 - 3、run_miao.bat 还可以当作全自动的安装程序来使用。它会自动下载 miao 以及 electron 或 nwjs 的压缩包，并解压到 run_miao.bat 所在的文件夹下。下载和解压 完成后，会立即启动 miao 。您需要保证 wget 和 unzip 能正常工作，否则可能 无法进行下载和解压。 - ## 【相关下载】 如果您使用全自动的安装程序，您不需要关心下面这些下载地址。 - 1、Windows XP 下，请下载能够支持 XP 的最后一个 nwjs 版本: - https://dl.nwjs.io/v0.14.7/nwjs-sdk-v0.14.7-win-ia32.zip (官网网速慢) - https://registry.npmmirror.com/-/binary/nwjs/v0.14.7/nwjs-sdk-v0.14.7-win-ia32.zip (快) - 2、Windows 7/8/10 以及 Linux 下，请下载 nwjs 的最新版或 electron 的最新版: - nwjs 的下载页: - https://nwjs.org.cn/download.html (官网网速慢) - https://registry.npmmirror.com/binary.html?path=nwjs/ (镜像网速快) - electron 的下载页: - https://releases.electronjs.org/ (官网网速慢) - https://registry.npmmirror.com/binary.html?path=electron/ (镜像网速快) - # 跨路由器的使用 本软件 miao 支持跨路由器的使用。若从路由器内网向路由器外网广播，只需在 miao 的 设置中添加外网的 IP 地址或网段即可。若要从路由器外网向路由器内网广播，则需要对 路由器本身进行一些必要的设置才行。下面介绍 miao 软件跨路由器通讯的原理。 - 位于路由器外网的主机（它与路由器的 WAN 口处于同一局域网），当它向路由器外部局 域网通告上线消息的时候，路由器（作为外部局域网的一个成员）本身也会收到消息。 但是，在默认情况下，路由器的防火墙会丢弃来自路由器外部局域网的消息，而不是自动 转发到内部局域网。要想让路由器进行自动转发，就得设置路由器（具体设置方法，请参 考路由器厂家提供的手册）。设置路由器的目的，是让路由器把外网主机发送到路由器 2425 端口的 TCP/UDP 消息，都自动转发到路由器内部局域网的某台主机上。最简单的 设置方法是使用 DMZ 选项，这个选项的意思是，把外网发来的全部消息都转发到内网的 某台主机上，而这台内网主机，就叫做 DMZ 主机。如果由于某种原因您不想使用 DMZ 选项，您也可以使用其它选项，只需转发端口 2425 的消息即可。为了方便，不管您用 什么方法进行设置，您设定的那台内网主机，在本软件中都称为 DMZ 主机。 - 假定您已经如上所述，为您的路由器设置好了端口转发。于是，路由器外网主机发送到路 由器 2425 端口的消息，就都能够穿过路由器防火墙而到达路由器内网的 DMZ 主机上。 接下来，您还需要在这台 DMZ 主机上安装 miao 软件，目的是能够进一步把从外网得到 的消息转发到内网的其它主机上。这就彻底打通了路由器内外网的连接，或者也可以说, 这是实现了某种形式的“内网穿透”。这样，路由器内外网的 miao 软件，就可以畅通无阻 地沟通了。需要说明的是，刚才提到的转发协议是 miao 软件为解决跨路由器通讯问题而 新增的，只对 miao 软件有效；其它飞鸽类软件无法解析 miao 软件转发给它的消息。 - 从以上描述中可以了解，DMZ 主机必须一直开着，不能休眠。一旦 DMZ 主机关机或休眠, 它所运行的 miao 软件将处于“无法工作”的死亡状态，不会有转发的动作了。就是说，在 DMZ 主机休眠期间，路由器内网的其它主机将无法收到来自外网的消息了。 - 总结一下。要想让 miao 软件在跨（多重）路由器的情况下仍能正常运转，须注意三点: - 1、必须设置每台路由器，把来自外网 2425 端口的消息自动转发至其内网的某台主机。 - 2、必须在这台内网主机上运行 miao 软件, 外网主机才能给内网其它主机发消息。 - 3、这台内网主机起着桥梁作用，您应该在操作系统中把它设置为永不关机、永不休眠。 - 将来 miao 有可能支持安装到路由器上，那时就不再需要设置一个 DMZ 主机了。 - 【注】新版已支持 UPnP 协议。如果路由器开启了 UPnP 功能, miao 会利用 UPnP 功能 自动填写路由器 udp/tcp 2425 端口的转发条目, 无需手动设置。 - # 同步文件夹功能 ## 【重要说明】 新版采用 http 方式的同步文件夹功能，下面的描述已经不适用了，请等待更新。 - 新版实现了简单的同步文件夹功能。设计此功能的主要目的并不是为了快速、高效地 进行文件夹同步, 而是针对文件数量不多但会频繁变动的情况。关注的重点在于如何 实现一种可行的自动化拷贝方案, 只要能够避免手动拷贝文件, 就达到了设计目标。 主要应用场景大致有两种：1、您想把日常办公生成的文件自动备份到另一台电脑上, 防止磁盘突然损坏造成惨重损失。2、您修改了一台电脑上的文件, 希望自动修改 其它几台电脑上的文件, 以便您下次切换到那些电脑上时可以立即投入工作。 - 同步文件夹是属于两个好友之间的概念。以下假定当前工作目录是 miao, 那么您通常 接收对方文件的位置是: - ../shared/好友昵称ID/ - 您不知道这个文件夹的位置究竟在哪里？不用担心, 您让对方随便发给您一个文件, 您接收后, 就会在您的电脑上自动创建这个文件夹, 并把接收到的文件放在里面。 - 此时您还没有同步文件夹, 您需要手动创建这个文件夹: - ../shared/好友昵称ID/sync/ - 它便是您的同步文件夹了, 如果它不存在, 您就不能使用同步文件夹功能。您把任何 文件放在里面, 同步功能都会帮您自动同步给对方。然而, 同步是需要双方配合的, 因此对方也得有同步文件夹才行。就是说, 对方也要在他的电脑上为您创建下面这个 文件夹: - ../shared/您的昵称ID/sync/ - 对方把他想要同步给您的文件放在其中, 就可以自动同步给您了。 - 【提示】您可以用常规的文件发送方式, 手动选择您的 sync 文件夹中的某个文件, 把它发送给对方。对方接收后, 也会自动放在他的 sync 文件夹里面。这样也就顺便 帮对方创建了 sync 文件夹, 同时也触发了对方 miao 软件的同步动作。 - 第一次接收对方的文件, 需要手动点击“接收”按钮, 表示信任对方; 此后将自动接收 对方发来的任何文件。如果您不再信任对方，您必须手动删除 - ../shared/对方昵称ID/ - 这个文件夹。删除之后，对方下次再发文件过来, 就不会自动接收了。然而只要您 再次点击“接收”按钮（表示信任对方）, 此后就又要自动接收对方发来的文件了。 - 注意: 文件长度为 0 的文件会被忽略，而不会发送给对方。文件名含有英文冒号的 文件, 也会被忽略, 不进行同步。空的文件夹也等同于不存在。 - 同名文件冲突怎么办？ - 如果您和对方有同名文件, 但您的文件比对方的旧, 那就不会发送给对方; 但对方 会把新文件发送给您, 您接收后, 您的同名旧文件就会被废弃, 这个被废弃的旧文件 会被更名为某个临时文件, 放在 - ../shared/好友昵称ID/ - 之下, 也就是说, 被废弃的文件（更名后）放在 sync 的外面, 不再参与同步。 - 被废弃了的文件是被更名了，而不是被删除了, 这很重要。因此, 您不会丢失任何文件。 但您可能需要手动删除那些无用的文件。 - 此功能在设计时就不考虑同步速度问题。此功能每分钟最多只能同步两个文件。因此, 同步大量文件会花费很长时间。 - 您可以为多个好友建立同步文件夹, 每个 sync 文件夹对应于某个好友。 - 软件启动后会监视本机那些同步文件夹(sync)的变动, 并把需要同步给对方的文件 发送给对方。任何一方接收文件时也会检查自己的同步文件夹, 并向对方发送需要 同步的文件。如果您在本机为某好友刚刚创建 sync 文件夹, 本软件可能需要重启 后才会监视这个新建的 sync 文件夹的变动。 - sync 文件夹（不含子文件夹）里面的文件变动会被监视, 一旦有变动就会触发同步 的动作。另外, 本机一旦收到别的 miao 用户发来的文件, 也会触发本机的同步动作。 - sync 的子文件夹里面文件的变动不会被监视, 但会被同步。就是说, sync 的 子文件夹里面的文件的变动, 可能不会触发同步的动作。但只要同步被别的条件触发, sync 的（任意级）子文件夹里面的文件也会被同步。 - 触发同步的条件: - 1、某个 miao 用户上线或应答。 - 2、接收某个 miao 用户发来的文件（无论是成功还是失败）后（立即）。 - 3、被监视了的某个 sync 文件夹（此处不涉及子文件夹）中的文件状态有变动时。 - 同步被触发后执行的动作是: - 检查所有 miao 用户的 sync 文件夹（不含子文件夹）, 如果存在, 就监视它们, 并实施同步（sync 的子文件夹也参与同步）。 - 同步文件夹的名称和位置可以更改吗？ - 不能更改, 必须是 - ../shared/好友昵称ID/sync - 您为每个好友都可以建立一个 sync 文件夹。 - 虽然 sync 的名称、位置都不能改, 但您可以把它做成一个符号链接, 这样, 这个符号 链接 sync 就可以指向任意一个文件夹了。 - 如果您的 sync 不是符号链接而是一个早已存在的真正的文件夹, 您可以先把这个真正 的 sync 文件夹更改为别的名字, 比如更改为 sync_old, 然后建立一个名叫 sync 的符号链接, 让它指向您喜欢的位置就可以了。 - Windows 的 NTFS 文件系统支持符号链接, 而 Linux 更是支持符号链接。比如, 在 Windows 下执行 - mklink /d sync d:\my_test_sync - 就可以让 sync 指向 d: 盘的 my_test_sync 文件夹。类似地, 在 Linux 下执行 - ln -s /home/user/my_test_sync sync - 就可以让 sync 指向 /home/user/my_test_sync 文件夹。注意 Windows 和 Linux 命令 的参数顺序不同。 - 利用符号链接, 您可以根据需要, 让多个好友的同步文件夹都指向同一个位置。 - # 许可协议 miao 本身的代码（顶级目录下的所有文件，不含子目录）采用 MIT license 发布。 子目录下都是 miao 需要引用的支持库，遵从各自的开源许可协议。 - # 已知问题 在 Linux 下运行 electron 时, 有时会报如下错误: - FATAL:setuid_sandbox_host.cc(157)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /home/live/electron/chrome-sandbox is owned by root and has mode 4755. - 解决方法: 以 root 身份执行 chown 和 chmod 改变权限即可。参考如下两条命令: - sudo chown root /home/live/electron/chrome-sandbox - sudo chmod 4755 /home/live/electron/chrome-sandbox - # 注意事项 miao 文件夹应该放在一个支持 4G 大文件的盘上，并且剩余可用空间也足够大。与 miao 文件夹并列放置的一个叫做 shared 的文件夹, 用来存放其他用户传过来的文件。 如果该盘不支持 4G 大文件，或者剩余可用空间不足，则有可能在接收文件时失败。 - --- # 码云特技 1. 使用 Readme_XXX.md 来支持不同的语言，例如 Readme_en.md, Readme_zh.md 2. 码云官方博客 [blog.gitee.com](https://blog.gitee.com) 3. 码云上的优秀开源项目 [https://gitee.com/explore](https://gitee.com/explore) 4. 码云最有价值开源项目 [GVP](https://gitee.com/gvp) 5. 码云官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help) 6. 码云封面人物是一档用来展示码云会员风采的栏目 https://gitee.com/gitee-stars/