PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.
Dart airdrop-alternativeclipboardclipboard-sharingclipboard-synccopy-pastecross-platformend-to-end-encryptionfile-syncfile-transferfluttergolanglinuxmacosnat-traversalp2pself-hostedtailscaleuniversal-clipboardwebrtcwindows
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<script>
(function () {
if (location.hostname !== "baiyuze.github.io") return;
var prefix = /^\/(?:pasteferry|copysync)(?=\/|$)/.exec(location.pathname);
if (!prefix) return;
var path = location.pathname.slice(prefix[0].length) || "/";
location.replace("https://pasteferry.cc" + path + location.search + location.hash);
})();
</script>
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Windows 客户端技术方案:隔空贴技术方案</title>
<meta name="description" content="状态:已实现,随 1.2.0 发布(2026-10-09)。实机验证记录见 windows-validation-2026-10-09.md(安装、同步、生命周期)与 windows-features-validation-2026-10-09.md(托盘、配对弹窗、图片预览)">
<link rel="canonical" href="https://pasteferry.cc/design/windows-client.html">
<meta name="theme-color" content="#141416">
<link rel="icon" href="../assets/favicon.svg?v=df696024d8" type="image/svg+xml">
<link rel="stylesheet" href="../assets/site.css?v=dbae55d27c">
</head>
<body>
<a class="skip" href="#main">跳到正文</a>
<header class="bar">
<div class="wrap">
<a class="brand" href="../" aria-label="隔空贴首页"><img src="../assets/icon.svg?v=65a69999e0" alt="" width="26" height="26">隔空贴</a>
<nav aria-label="页面导航">
<a href="../start/">快速开始</a>
<a href="../start/#server">连接方式</a>
<a class="wide" href="https://github.com/baiyuze/pasteferry/blob/main/design/windows-client.md">在 GitHub 上查看</a>
<a class="wide" href="https://github.com/baiyuze/pasteferry">GitHub</a>
</nav>
</div>
</header>
<main id="main">
<article class="article">
<p class="crumb"><a href="../">隔空贴</a>的技术方案</p>
<h1>Windows 客户端技术方案</h1>
<blockquote><p>状态:已实现,随 1.2.0 发布(2026-10-09)。实机验证记录见 <a href="https://github.com/baiyuze/pasteferry/blob/main/design/windows-validation-2026-10-09.md">windows-validation-2026-10-09.md</a>(安装、同步、生命周期)与 <a href="https://github.com/baiyuze/pasteferry/blob/main/design/windows-features-validation-2026-10-09.md">windows-features-validation-2026-10-09.md</a>(托盘、配对弹窗、图片预览)</p><p>目标版本:1.2.0(Mac 与 Windows 同时发布)</p><p>相关:<a href="nat-traversal.html">多出口网络的 NAT 打洞</a></p></blockquote>
<nav class="toc" aria-label="目录"><strong>目录</strong><ul><li><a href="#一-目标">一、目标</a></li><li><a href="#二-现状-哪些能直接用">二、现状:哪些能直接用</a></li><li><a href="#三-总体架构">三、总体架构</a></li><li><a href="#四-剪贴板">四、剪贴板</a></li><li><a href="#五-跨平台内容兼容">五、跨平台内容兼容</a></li><li><a href="#六-后台服务的生命周期">六、后台服务的生命周期</a></li><li><a href="#七-网络">七、网络</a></li><li><a href="#八-界面">八、界面</a></li><li><a href="#九-安全">九、安全</a></li><li><a href="#十-安装-签名与发布">十、安装、签名与发布</a></li><li><a href="#十一-测试与验证">十一、测试与验证</a></li><li><a href="#十二-里程碑">十二、里程碑</a></li><li><a href="#十三-需要拍板的事">十三、需要拍板的事</a></li><li><a href="#附-要改动的代码">附:要改动的代码</a></li></ul></nav>
<h2 id="一-目标">一、目标</h2>
<p>让 Windows 电脑加入隔空贴:与 Mac、与其他 Windows 电脑互相同步文本、带格式文本、图片和文件,体验与 Mac 版一致。</p>
<ul><li>在一台上 <code>Ctrl+C</code>,另一台上 <code>Ctrl+V</code>(或 <code>⌘V</code>)。粘贴文件时得到的是真实文件,可以直接粘贴进资源管理器、微信、Office。</li><li>开机自启,关掉窗口照常同步,崩溃自动拉起。Windows 安装时创建桌面快捷方式;后台服务持有托盘图标,点击可打开界面,右键可打开界面或退出隔空贴。</li><li>网络行为与 Mac 版完全相同:直连优先、多出口打洞、自动中转、端到端加密。</li><li>与 Mac 版互通,Mac 端不升级也能和 Windows 配对、同步(协议不变)。</li></ul>
<p><strong>一期不做:</strong></p>
<div class="table-scroll"><table><thead><tr><th scope="col">不做</th><th scope="col">原因</th><th scope="col">何时</th></tr></thead><tbody><tr><td>ARM64 原生包</td><td>Flutter 3.47 才正式支持 Windows ARM64,且只能在 ARM 机器上构建;x64 版在 ARM 上可以模拟运行</td><td>二期,用 GitHub 的 ARM Windows 构建机</td></tr><tr><td>虚拟文件(Outlook 附件、压缩包里直接复制的文件)</td><td>剪贴板里没有真实路径,只有流,需要实现 COM 接口</td><td>视需求</td></tr><tr><td>自动更新、微软商店</td><td>先跑通分发与签名</td><td>二期</td></tr></tbody></table></div>
<p>支持的系统:Windows 10 与 Windows 11,x64,Windows 10 不限版本。Flutter 引擎(<code>flutter_windows.dll</code>)与 Go 1.26 都要求 Windows 10;引擎直接引用的系统函数 Windows 8 就有,按 DPI 缩放这类新接口是运行时查找、找不到就退回。Windows 7、8 装不上。</p>
<h2 id="二-现状-哪些能直接用">二、现状:哪些能直接用</h2>
<p>后台服务除剪贴板外全部是纯 Go:数据库用的是纯 Go 的 <code>modernc.org/sqlite</code>,压缩是纯 Go 的 zstd,cgo 只出现在 <code>internal/clipboard/darwin.go</code>。实测在 Mac 上已经可以直接交叉编译出 Windows 版:</p>
<pre><code>CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build ./cmd/... # pasteferryd.exe、pasteferry-cli.exe
CGO_ENABLED=0 GOOS=windows GOARCH=arm64 go build ./cmd/pasteferryd</code></pre>
<div class="table-scroll"><table><thead><tr><th scope="col">模块</th><th scope="col">Windows 上</th><th scope="col">说明</th></tr></thead><tbody><tr><td>信令、配对、签名(<code>transport/signaling</code>、<code>peers</code>、<code>identity</code>)</td><td>直接复用</td><td></td></tr><tr><td>P2P、出口探测、打洞、中转(<code>transport/p2p</code>)</td><td>直接复用</td><td>防火墙与虚拟网卡见第七节</td></tr><tr><td>同步引擎、补发、存储、缓存、回收(<code>sync</code>、<code>store</code>、<code>cache</code>、<code>gc</code>)</td><td>直接复用</td><td></td></tr><tr><td>本机接口(<code>rpc</code>,127.0.0.1 + 一次性 token)</td><td>直接复用</td><td></td></tr><tr><td>数据目录(<code>config.DefaultPaths</code>)</td><td>已有 Windows 分支</td><td><code>%LOCALAPPDATA%\PasteFerry</code></td></tr><tr><td>打包解包(<code>pack</code>)</td><td>要改</td><td>文件名、符号链接,见第五节</td></tr><tr><td>剪贴板(<code>clipboard</code>)</td><td><strong>要新写</strong></td><td>目前是返回「不支持」的占位实现,见第四节</td></tr><tr><td>进程生命周期(<code>cmd/pasteferryd</code>)</td><td>要改</td><td>自启、守护、日志、单实例、注销,见第六节</td></tr><tr><td>界面(<code>ui/</code>)</td><td>要改</td><td>已有 Flutter 的 <code>windows/</code> 工程骨架;后台服务管理、窗口外观、文案,见第八节</td></tr><tr><td>构建与发布(<code>scripts/</code>、CI)</td><td>要新写</td><td>Flutter 的 Windows 版只能在 Windows 上构建,见第十节</td></tr></tbody></table></div>
<h2 id="三-总体架构">三、总体架构</h2>
<p>与 Mac 版同构,三个可执行文件:</p>
<pre><code>PasteFerry.exe(Flutter 界面)
│ gRPC,127.0.0.1 随机端口 + token(%LOCALAPPDATA%\PasteFerry\daemon.json)
▼
pasteferryd.exe(Go 后台服务,用户会话内运行,无控制台窗口)
├─ 剪贴板:隐藏的消息窗口 + Win32 剪贴板 API
├─ 同步引擎 / 存储 / 缓存
└─ 信令(WebSocket)+ P2P(WebRTC)──► 信令服务器 / 对端设备
pasteferry-cli.exe(命令行,排障用)</code></pre>
<p>后台服务必须作为<strong>登录用户的普通进程</strong>运行,不能做成 Windows 服务。Windows 服务运行在会话 0,与用户桌面隔离,访问不到用户的剪贴板。这与 Mac 上用 LaunchAgent、不用 LaunchDaemon 是同一个原因。</p>
<h2 id="四-剪贴板">四、剪贴板</h2>
<p>这是一期的主要工作量。用纯 Go 实现(<code>golang.org/x/sys/windows</code> 加按需加载的 user32、kernel32、shell32 函数),不用 cgo,这样仍能在 Mac 上交叉编译。</p>
<h3 id="1-线程与消息循环">1. 线程与消息循环</h3>
<p>现有的 <code>MainLoop</code> 设计可以原样沿用,只是「事件循环」换成 Windows 的消息泵:</p>
<ul><li>主线程(已 <code>LockOSThread</code>)创建一个<strong>隐藏的顶层窗口</strong>作为剪贴板的拥有者。不用「仅消息窗口」(HWND_MESSAGE),因为它收不到会话结束、电源变化等广播消息。</li><li><code>pumpRunLoop</code> 改为 <code>PeekMessage</code>/<code>DispatchMessage</code> 循环,空闲时 <code>MsgWaitForMultipleObjects</code> 等待,不空转。</li><li>用 <code>AddClipboardFormatListener</code> 订阅 <code>WM_CLIPBOARDUPDATE</code>,变化时立即触发一次探测,比 Mac 的 300 毫秒轮询更跟手;轮询保留作兜底。</li><li><code>ChangeCount</code> 用 <code>GetClipboardSequenceNumber()</code>。它与 Mac 的 changeCount 语义一致,<code>Watcher</code> 里「跳过本机写入」(selfWrites)的逻辑不用改。</li><li>权限:Windows 没有剪贴板授权机制,<code>Permission()</code> 恒为 <code>PermissionNotApplicable</code>,界面上的授权提示自然不显示。</li></ul>
<h3 id="2-格式对照">2. 格式对照</h3>
<div class="table-scroll"><table><thead><tr><th scope="col">类型</th><th scope="col">读取(优先级从高到低)</th><th scope="col">写入</th></tr></thead><tbody><tr><td>文件</td><td><code>CF_HDROP</code>(<code>DragQueryFileW</code> 取路径)</td><td><code>CF_HDROP</code>(<code>DROPFILES</code> 结构 + 双 NUL 结尾的 UTF-16 路径表),加上 <code>Preferred DropEffect = DROPEFFECT_COPY</code>,资源管理器粘贴时执行复制而不是移动</td></tr><tr><td>图片</td><td>注册格式 <code>PNG</code>(Chrome、Office、截图工具都提供)→ <code>CF_DIBV5</code> → <code>CF_DIB</code>,后两者转成 PNG</td><td><code>PNG</code> + <code>CF_DIBV5</code>(带透明通道);<code>CF_DIB</code>、<code>CF_BITMAP</code> 由系统自动合成</td></tr><tr><td>带格式文本</td><td>注册格式 <code>HTML Format</code>(CF_HTML),解析头部偏移量取出 HTML</td><td><code>HTML Format</code>(生成带偏移量的头部)+ <code>CF_UNICODETEXT</code></td></tr><tr><td>纯文本</td><td><code>CF_UNICODETEXT</code></td><td><code>CF_UNICODETEXT</code>(<code>CF_TEXT</code> 由系统合成)</td></tr></tbody></table></div>
<p>判型顺序:文件最优先(资源管理器复制文件时剪贴板里同时有文件名文本);只有图片、没有文本时才算图片(截图、画图、浏览器里「复制图片」);Excel、Word 复制的内容同时带着一份渲染出来的图片,但有文本,按带格式文本处理。</p>
<p><strong>文件粘贴不需要 COM。</strong>占位实现的注释里写着「文件粘贴需要在 Go 里实现 COM IDataObject」,那是按延迟渲染设想的。Mac 版已经验证过延迟渲染行不通,改成了「先落盘、再写剪贴板」;Windows 也一样,收到的文件已在本地缓存里,直接给 <code>CF_HDROP</code> 真实路径即可。</p>
<h3 id="3-不同步敏感内容">3. 不同步敏感内容</h3>
<p>密码管理器复制密码时,会在剪贴板里放一个标记,告诉剪贴板工具「别记录、别同步」。Windows 上的约定(微软文档「Cloud Clipboard and Clipboard History Formats」,以及老的通行做法):</p>
<div class="table-scroll"><table><thead><tr><th scope="col">标记</th><th scope="col">规则</th><th scope="col">谁在用</th></tr></thead><tbody><tr><td><code>ExcludeClipboardContentFromMonitorProcessing</code></td><td>存在即跳过</td><td>KeePass、KeePassXC</td></tr><tr><td><code>Clipboard Viewer Ignore</code></td><td>存在即跳过</td><td>KeePass 等较老的工具</td></tr><tr><td><code>CanIncludeInClipboardHistory</code></td><td>值为 DWORD 0 时跳过(只看存在与否不够)</td><td>Bitwarden 只写这一个</td></tr><tr><td><code>CanUploadToCloudClipboard</code></td><td>值为 0 时跳过:它的含义正是「不要同步到别的设备」</td><td></td></tr></tbody></table></div>
<p>命中就既不同步,也不写进复制记录。<strong>Mac 版目前没有做这件事</strong>(应检查 <code>org.nspasteboard.ConcealedType</code> 和 <code>org.nspasteboard.TransientType</code>),1Password、Bitwarden 复制的密码会被同步过去并留在记录里。这一条应先在 Mac 版单独修掉,不等 Windows。</p>
<h3 id="4-其他细节">4. 其他细节</h3>
<ul><li><strong>剪贴板被占用</strong>:<code>OpenClipboard</code> 在别的程序正打开剪贴板时会失败,按 20 毫秒间隔重试 10 次,仍失败就放弃这一次,等下一次变化。</li><li><strong>写入时的标记</strong>:把对端内容写进本机剪贴板时,加上 <code>CanUploadToCloudClipboard = 0</code>,免得 Windows 自带的云剪贴板再把它同步一遍,在用户的其他 Windows 电脑上出现重复。写入本机剪贴板历史(<code>Win+V</code>)不受影响。</li><li><strong>不支持的内容</strong>:只有虚拟文件(<code>FileGroupDescriptorW</code>/<code>FileContents</code>)而没有 <code>CF_HDROP</code> 时判为未知类型,跳过并记日志。</li></ul>
<h2 id="五-跨平台内容兼容">五、跨平台内容兼容</h2>
<p>网络上传输的格式保持现状(与 Mac 版一致),差异都在 Windows 一侧的剪贴板层与解包时消化:</p>
<div class="table-scroll"><table><thead><tr><th scope="col">项目</th><th scope="col">网络上的约定</th><th scope="col">Windows 侧的处理</th></tr></thead><tbody><tr><td>文本换行</td><td><code>LF</code></td><td>读取时把 <code>CRLF</code> 统一成 <code>LF</code>;写入时转成 <code>CRLF</code>(记事本等程序依赖它)</td></tr><tr><td>带格式文本</td><td>完整的 HTML 文本</td><td>读取时去掉 CF_HTML 头部;写入时生成头部,用 <code><!--StartFragment--></code> 标出片段</td></tr><tr><td>图片</td><td>PNG</td><td>DIB(倒序扫描行、<code>BI_BITFIELDS</code>、32 位透明通道)与 PNG 互转</td></tr><tr><td>条目类型(<code>ClipItem.content_type</code>)</td><td>沿用 Mac 的 UTType 字符串,如 <code>public.png</code></td><td>Windows 侧按扩展名映射成同样的字符串,不另起一套</td></tr><tr><td>文件与文件夹</td><td>tar + zstd</td><td>解包时按下表处理文件名</td></tr></tbody></table></div>
<p><strong>文件名</strong>是最容易出事的地方。Mac 上合法的文件名在 Windows 上未必合法,处理不好轻则解包失败,重则有安全问题:</p>
<div class="table-scroll"><table><thead><tr><th scope="col">情况</th><th scope="col">例子</th><th scope="col">处理</th></tr></thead><tbody><tr><td>Windows 不允许的字符 `: * ? " < > \</td><td>\`</td><td><code>会议:纪要.txt</code></td><td>换成对应的全角字符(<code>:*?"<>|\</code>),名字仍然可读。冒号还关系到安全:<code>a.txt:stream</code> 会写进 NTFS 的备用数据流</td></tr><tr><td>结尾是点或空格</td><td><code>notes.</code></td><td>末尾加 <code>_</code></td></tr><tr><td>设备保留名</td><td><code>CON</code>、<code>nul.txt</code>、<code>COM1</code></td><td>前面加 <code>_</code></td></tr><tr><td>只差大小写</td><td><code>Readme.md</code> 与 <code>README.md</code></td><td>第二个改名为 <code>README (2).md</code>,不能互相覆盖</td></tr><tr><td>分解形式的 Unicode</td><td>Mac 上的 <code>が</code> 可能是 <code>か</code> + 濁点两个码位</td><td>统一成组合形式(NFC),否则资源管理器里显示成两个字符、搜索也搜不到。中文不受影响</td></tr><tr><td>路径超过 260 个字符</td><td>深层文件夹</td><td>Go 的 <code>os</code> 包会自动加 <code>\\?\</code> 前缀,读写没问题;只是资源管理器对超长路径支持不好,记一条已知限制</td></tr><tr><td>符号链接</td><td>文件夹里的软链接</td><td>普通用户没有创建符号链接的权限(除非开启了开发者模式)。改为跳过并记录,不能让整次解包失败</td></tr><tr><td>系统垃圾文件</td><td><code>.DS_Store</code>、<code>Thumbs.db</code>、<code>desktop.ini</code></td><td>打包时跳过(Mac 版同步修改)</td></tr></tbody></table></div>
<p><code>pack.safeJoin</code> 的防目录穿越检查保留,在<strong>清洗文件名之后</strong>做;Windows 上额外拒绝驱动器号开头(<code>C:foo</code>)和 <code>\\</code> 开头的路径。</p>
<h2 id="六-后台服务的生命周期">六、后台服务的生命周期</h2>
<div class="table-scroll"><table><thead><tr><th scope="col">需求</th><th scope="col">Mac 版的做法</th><th scope="col">Windows 版的做法</th></tr></thead><tbody><tr><td>开机自启</td><td>LaunchAgent</td><td><code>HKCU\Software\Microsoft\Windows\CurrentVersion\Run</code> 下写一项。只影响当前用户,不需要管理员权限</td></tr><tr><td>崩溃自动拉起</td><td>launchd <code>KeepAlive</code>,10 秒节流</td><td><code>pasteferryd.exe</code> 自带守护模式:父进程拉起子进程,子进程异常退出就 10 秒后重启</td></tr><tr><td>只运行一个</td><td>launchd 保证</td><td>命名互斥量 <code>Local\PasteFerry.Daemon</code>,第二个实例直接退出</td></tr><tr><td>不弹黑框</td><td>本来就没有</td><td>以 GUI 子系统编译(<code>-ldflags -H=windowsgui</code>)</td></tr><tr><td>日志</td><td>launchd 把标准输出重定向到文件</td><td>自己写 <code>%LOCALAPPDATA%\PasteFerry\logs\daemon.log</code>,按大小轮转(Mac 版的日志目前不轮转,一并加上)</td></tr><tr><td>注销、关机</td><td>SIGTERM</td><td>隐藏窗口处理 <code>WM_QUERYENDSESSION</code>/<code>WM_ENDSESSION</code>,正常收尾</td></tr><tr><td>睡眠唤醒</td><td>靠重连巡检</td><td>处理 <code>WM_POWERBROADCAST</code>:唤醒后立即重新探测出口、重连,不等巡检</td></tr><tr><td>升级</td><td>打开新版 App 时校正登录项并重启服务</td><td>安装程序借助「重启管理器」关掉旧进程,装完再启动;界面同样校验版本、必要时重启服务</td></tr></tbody></table></div>
<p>也评估过「计划任务」:它自带失败重启,但创建「登录时运行」的任务通常要管理员权限,与「不需要管理员即可安装」的目标冲突,所以不用。</p>
<h2 id="七-网络">七、网络</h2>
<p>打洞、多出口探测、中转、补发的代码原样复用。Windows 上要注意三件事:</p>
<ol><li><strong>防火墙弹窗</strong>。后台服务在 0.0.0.0 上收发 UDP,Windows 防火墙第一次会弹窗询问是否允许。允许最好;即使用户拒绝,防火墙对 UDP 也是有状态的,本端先往对端发过包,对端的回包就能进来。打洞时双方本来就会互相发包,所以预计仍能直连,<strong>需要实测确认</strong>。安装程序不加防火墙规则,因为那需要管理员权限。</li><li><strong>虚拟网卡</strong>。装了 WSL、Hyper-V、Docker 或 VPN 的电脑有很多虚拟网卡,其中 WSL 的网卡地址每次开机都会变。出口历史是按「本机各网卡的地址」区分网络的(<code>localNetworkKey</code>),会因此失效。Windows 上计算时排除名字以 <code>vEthernet</code> 开头的网卡和已知的 VPN 虚拟网卡。</li><li><strong>「公用网络」</strong>。连上咖啡馆等网络时,Windows 默认把它设为「公用网络」,防火墙更严。行为同第 1 条,实测时覆盖。</li></ol>
<h2 id="八-界面">八、界面</h2>
<p>继续用 Flutter,一套代码。Flutter 的 <code>windows/</code> 工程骨架已经在仓库里,<code>daemon_client.dart</code> 也已有 Windows 的数据目录分支。</p>
<h3 id="1-外观-像-windows-11-自带的应用">1. 外观:像 Windows 11 自带的应用</h3>
<p>Mac 版刻意做成系统自带应用的样子(石墨 + 系统蓝、透明标题栏、侧边栏延伸到红绿灯下)。Windows 版沿用同一个原则,参照 Windows 11 的「设置」应用:</p>
<div class="table-scroll"><table><thead><tr><th scope="col"></th><th scope="col">Mac</th><th scope="col">Windows</th></tr></thead><tbody><tr><td>窗口</td><td>透明标题栏,红绿灯在左上</td><td>自绘标题栏,最小化、最大化、关闭在右上;侧边栏顶部放应用名,与「设置」应用一致</td></tr><tr><td>背景</td><td>系统材质</td><td>Mica 材质(在 <code>windows/runner</code> 里调用 <code>DwmSetWindowAttribute</code>,不引入插件)</td></tr><tr><td>字体</td><td>SF Pro、苹方(跟随系统)</td><td>Segoe UI Variable、微软雅黑 UI(跟随系统)</td></tr><tr><td>图标</td><td>Cupertino</td><td>Fluent 图标</td></tr><tr><td>强调色</td><td>系统蓝</td><td>跟随系统强调色,取不到时用同一个蓝</td></tr></tbody></table></div>
<p>实现上在 <code>theme.dart</code> 加一层平台差异(字体、图标、标题栏高度、圆角),页面结构与交互不变:复制记录、设备、设置三页。</p>
<h3 id="2-后台服务管理">2. 后台服务管理</h3>
<p><code>background_service.dart</code> 目前全是 launchd 的逻辑,抽成接口,分 Mac 与 Windows 两个实现。Windows 的状态判定:</p>
<div class="table-scroll"><table><thead><tr><th scope="col">状态</th><th scope="col">判定</th></tr></thead><tbody><tr><td>未安装</td><td><code>Run</code> 下没有隔空贴项</td></tr><tr><td>指向旧位置</td><td><code>Run</code> 项的路径不是当前这份 <code>pasteferryd.exe</code></td></tr><tr><td>已停止</td><td><code>daemon.json</code> 不存在,或其中的进程号已不在运行</td></tr><tr><td>运行中</td><td>能连上,且版本与界面一致(不一致就重启服务)</td></tr></tbody></table></div>
<h3 id="3-文案与小处">3. 文案与小处</h3>
<ul><li>「这台 Mac」「两台 Mac」等十余处文案改为按平台显示(「这台电脑」「两台设备」)。Mac 版同步修改,因为对端可能是 Windows。</li><li>设备列表的平台图标已有 <code>windows</code> 分支,换成 Fluent 图标即可。</li><li>打开网页用 <code>open</code> 命令的地方改为跨平台的写法。</li><li>截图脚本(<code>tools/screenshots</code>)加 Windows 外观的版本,用于 README 与网站。</li></ul>
<h2 id="九-安全">九、安全</h2>
<div class="table-scroll"><table><thead><tr><th scope="col">项目</th><th scope="col">做法</th></tr></thead><tbody><tr><td>设备私钥(<code>identity.json</code>)</td><td>用 DPAPI(<code>CryptProtectData</code>,当前用户范围)加密后落盘。别的用户、拷走文件到别的电脑都解不开。Mac 版目前是权限 0600 的明文文件,后续可迁到钥匙串</td></tr><tr><td>数据目录</td><td><code>%LOCALAPPDATA%</code> 本身只有当前用户可访问,不另设权限</td></tr><tr><td>本机接口</td><td>与 Mac 相同:只监听 127.0.0.1,必须带 token</td></tr><tr><td>密码等敏感内容</td><td>见第四节第 3 条:命中标记就不同步、不记录</td></tr><tr><td>收到的文件</td><td>一期不加「来自网络」标记(MOTW):内容来自自己的设备,加了会让 Office 以受保护视图打开、可执行文件弹警告。二期考虑「源文件带标记才带过去」</td></tr></tbody></table></div>
<h2 id="十-安装-签名与发布">十、安装、签名与发布</h2>
<h3 id="1-安装包">1. 安装包</h3>
<p>用 Inno Setup 做<strong>按用户安装</strong>的安装包(类似 VS Code 的「用户安装版」):</p>
<ul><li>装到 <code>%LOCALAPPDATA%\Programs\PasteFerry</code>,不需要管理员权限,不弹 UAC。</li><li>创建开始菜单项;装完直接打开隔空贴,由界面引导「启用后台同步」,流程与 Mac 一致。</li><li>卸载时停掉后台服务、删掉自启项,询问是否保留复制记录与设备身份。</li><li>另出一个 zip 便携版,给不想运行安装程序的人。</li><li>界面程序依赖 VC++ 运行库(<code>msvcp140.dll</code>、<code>vcruntime140.dll</code>、<code>vcruntime140_1.dll</code>),Windows 不一定自带。构建时从 Visual Studio 里取这三个 DLL 放在 <code>PasteFerry.exe</code> 旁边(微软说的「应用本地部署」),安装包与便携版都带着,不用另装系统级的运行库。</li></ul>
<p>也评估过 MSIX:好处是安装干净、能自动更新;但要求必须有受信任的签名证书,且应用写入 <code>%LOCALAPPDATA%</code> 的数据会被重定向到包的私有目录,命令行工具与后台服务对不上路径。一期不用。</p>
<h3 id="2-代码签名">2. 代码签名</h3>
<p>不签名的安装包在下载、运行时会被 SmartScreen 拦一下(「Windows 已保护你的电脑」→「更多信息」→「仍要运行」),与 Mac 版没经过公证时「仍要打开」是一回事。可选的路子:</p>
<div class="table-scroll"><table><thead><tr><th scope="col">方案</th><th scope="col">费用</th><th scope="col">效果</th></tr></thead><tbody><tr><td>不签名(一期)</td><td>0</td><td>每个新版本都被 SmartScreen 拦,README 里写清楚怎么放行</td></tr><tr><td>普通代码签名证书(OV)</td><td>每年数百美元起</td><td>有发布者名称;SmartScreen 信誉要随下载量慢慢积累</td></tr><tr><td>微软的云签名服务</td><td>按月计费</td><td>价格低,但对个人开发者有地区限制,需要确认是否可用</td></tr></tbody></table></div>
<h3 id="3-构建与发布">3. 构建与发布</h3>
<p>Flutter 的 Windows 版只能在 Windows 上构建,现有的 <code>scripts/package.sh</code> 跑在 Mac 上,所以 Windows 包由 CI 构建:</p>
<ul><li>新增 GitHub Actions 任务(<code>windows-latest</code>):编译 Go(<code>GOOS=windows</code>)→ <code>flutter build windows</code> → Inno Setup 打包 → 上传到同一个 Release。</li><li>发布时在 Mac 上照常运行 <code>package.sh</code> 出 DMG,推送标签后 CI 补上 Windows 包。</li><li>发布资源沿用「不带版本号」的命名,下载直链不会失效:<code>PasteFerry-Setup.exe</code>、<code>PasteFerry-windows-x64.zip</code>。</li><li>CI 的常规检查增加 Windows:<code>go vet</code>、<code>go test</code>、<code>flutter analyze</code>、<code>flutter test</code>。</li></ul>
<h2 id="十一-测试与验证">十一、测试与验证</h2>
<ol><li><strong>纯函数单测</strong>(任何系统上都能跑):CF_HTML 头部的生成与解析、DIB 与 PNG 互转(含倒序扫描行、透明通道)、<code>DROPFILES</code> 编解码、换行转换、文件名清洗(第五节每一行一个用例)、敏感标记判定。</li><li><strong>Windows 上的集成测试</strong>:真实剪贴板的读写往返(文本、HTML、图片、文件)、跳过本机写入、密码管理器标记。GitHub 的 Windows 构建机能否访问剪贴板需要先验证;不行的话这部分在本地 Windows 机器上跑。</li><li><strong>Mac ↔ Windows 联调清单</strong>:<ul><li>内容:中英文文本;从网页、Word、Excel 复制的带格式文本;截图、带透明背景的 PNG;单个文件、多个文件、深层文件夹、中文与日文文件名、含 <code>:</code> 的文件名;1 GB 大文件按需拉取。</li><li>粘贴目标:资源管理器、微信、Office、记事本。</li><li>网络:同一局域网、公司多出口网络、家用宽带、防火墙弹窗点「取消」、睡眠唤醒、断网恢复。</li><li>生命周期:注销与重启、升级安装、卸载后重装。</li></ul></li><li><strong>NAT 打洞实验室</strong>:网络代码与平台无关,现有 11 个场景继续覆盖。</li></ol>
<h2 id="十二-里程碑">十二、里程碑</h2>
<p>按一个人全职估算,约 6 周:</p>
<div class="table-scroll"><table><thead><tr><th scope="col">阶段</th><th scope="col">内容</th><th scope="col">产出</th><th scope="col">估时</th></tr></thead><tbody><tr><td>M1</td><td>剪贴板实现(第四节)与后台服务生命周期(第六节)</td><td><code>pasteferryd.exe</code> 在 Windows 上跑通:用 <code>pasteferry-cli</code> 能与 Mac 配对、互相同步文本与图片</td><td>2 周</td></tr><tr><td>M2</td><td>文件与内容兼容(第五节)、敏感内容过滤</td><td>联调清单里的内容类全部通过</td><td>1 周</td></tr><tr><td>M3</td><td>界面适配(第八节)</td><td>Windows 外观的界面,能启用、管理后台服务</td><td>1.5 周</td></tr><tr><td>M4</td><td>安装包、CI、文档与网站</td><td>Release 里出现 Windows 安装包,README 与网站补上 Windows</td><td>1 周</td></tr><tr><td>M5</td><td>实机联调与修复,发布 1.2.0</td><td></td><td>0.5 周起</td></tr></tbody></table></div>
<p>M1 结束时就能验证最大的不确定点:剪贴板方案、防火墙行为、Windows 上的打洞。之后的阶段风险较小。</p>
<h2 id="十三-需要拍板的事">十三、需要拍板的事</h2>
<ol><li><strong>代码签名</strong>:一期不签名(推荐,先验证需求),还是一开始就买证书?</li><li><strong>托盘图标</strong>:已按用户需求加入一期,由后台服务持有,随登录自启、关闭主窗口后保留;退出时停止当前后台同步,但保留下次登录的自启设置。</li><li><strong>ARM64</strong>:一期只出 x64(推荐,ARM 机器可以模拟运行),还是同时出 ARM64?</li><li><strong>Mac 版的敏感内容漏洞</strong>(第四节第 3 条):建议马上单独修,发 1.1.3。</li></ol>
<h2 id="附-要改动的代码">附:要改动的代码</h2>
<div class="table-scroll"><table><thead><tr><th scope="col">位置</th><th scope="col">改动</th></tr></thead><tbody><tr><td><code>client-core/internal/clipboard/windows.go</code>(新)</td><td>Win32 剪贴板实现、消息窗口、格式转换</td></tr><tr><td><code>client-core/internal/clipboard/other.go</code></td><td>构建标签改为排除 darwin 与 windows</td></tr><tr><td><code>client-core/internal/clipboard/sensitive.go</code>(新)</td><td>敏感内容判定(两个平台共用接口)</td></tr><tr><td><code>client-core/internal/pack/pack.go</code></td><td>文件名清洗、符号链接、垃圾文件过滤</td></tr><tr><td><code>client-core/internal/transport/p2p/egress_history.go</code></td><td>网络标识排除虚拟网卡</td></tr><tr><td><code>client-core/internal/identity/identity.go</code></td><td>Windows 上用 DPAPI 保护私钥</td></tr><tr><td><code>client-core/cmd/pasteferryd/main.go</code></td><td>守护模式、单实例、日志文件、会话结束与电源事件</td></tr><tr><td><code>ui/lib/background_service.dart</code></td><td>拆成接口与 Mac、Windows 两个实现</td></tr><tr><td><code>ui/lib/theme.dart</code>、<code>ui/lib/main.dart</code></td><td>平台外观、自绘标题栏</td></tr><tr><td><code>ui/windows/runner/</code></td><td>Mica 背景、窗口尺寸记忆、应用图标</td></tr><tr><td><code>scripts/</code>、<code>.github/workflows/</code></td><td>Windows 构建、安装包、发布</td></tr><tr><td><code>tools/installer/</code>(新)</td><td>Inno Setup 脚本</td></tr></tbody></table></div>
</article>
</main>
<footer class="footer">
<div class="wrap">
<p>隔空贴以 GNU AGPL-3.0 开源。</p>
<nav aria-label="页脚链接">
<a href="https://github.com/baiyuze/pasteferry/releases">所有版本</a>
<a href="https://github.com/baiyuze/pasteferry/blob/main/CHANGELOG.md">更新记录</a>
<a href="https://pasteferry.cc/design/nat-traversal.html">技术方案</a>
<a href="https://github.com/baiyuze/pasteferry/blob/main/LICENSING.md">许可说明</a>
<a href="https://github.com/baiyuze/pasteferry/issues">反馈问题</a>
<a href="../privacy/">隐私说明</a>
<a href="../feedback/">讨论与反馈</a>
</nav>
<nav aria-label="语言">
<a href=".././" hreflang="zh-CN" lang="zh-CN" data-lang="zh" aria-current="page">简体中文</a>
<a href="../zh-tw/" hreflang="zh-TW" lang="zh-TW" data-lang="zh-tw">繁體中文(台灣)</a>
<a href="../zh-hk/" hreflang="zh-HK" lang="zh-HK" data-lang="zh-hk">繁體中文(香港)</a>
<a href="../en/" hreflang="en" lang="en" data-lang="en">English</a>
<a href="../ja/" hreflang="ja" lang="ja" data-lang="ja">日本語</a>
</nav>
</div>
</footer>
<script src="/assets/analytics.js?v=e2777f714d" defer></script>
<script type="module" src="https://static.cloudflareinsights.com/beacon.min.js" data-cf-beacon='{"token": "7ee226baf4a949a397c4bfd69a9e7461"}'></script>
</body>
</html>