docs: 更新全客户端命名与构建分发文档
This commit is contained in:
+802
-202
File diff suppressed because one or more lines are too long
+37
-9
@@ -3,18 +3,18 @@
|
|||||||
<head>
|
<head>
|
||||||
<meta charset="UTF-8">
|
<meta charset="UTF-8">
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
<title>cdrop — Changelog</title>
|
<title>Commilitia Drop — Changelog</title>
|
||||||
<meta name="generated-at" content="2026-06-28">
|
<meta name="generated-at" content="2026-07-31">
|
||||||
<meta name="source" content="cdrop · docs branch">
|
<meta name="source" content="Commilitia Drop · docs branch">
|
||||||
<!-- RUNTIME_CSS -->
|
<!-- RUNTIME_CSS -->
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
|
|
||||||
<header class="page">
|
<header class="page">
|
||||||
<div class="meta">
|
<div class="meta">
|
||||||
<h1>cdrop — Changelog</h1>
|
<h1>Commilitia Drop — Changelog</h1>
|
||||||
<p class="subtitle">时间倒序。细粒度迭代见 git 历史；本档只记录结构性 / 行为性变更与重要 fix。</p>
|
<p class="subtitle">时间倒序。细粒度迭代见 git 历史；本档只记录结构性 / 行为性变更与重要 fix。</p>
|
||||||
<p class="timestamp"><time>2026-06-28</time> · <span>docs branch</span></p>
|
<p class="timestamp"><time>2026-07-31</time> · <span>docs branch</span></p>
|
||||||
</div>
|
</div>
|
||||||
<div class="actions">
|
<div class="actions">
|
||||||
<!-- ACTIONS -->
|
<!-- ACTIONS -->
|
||||||
@@ -25,6 +25,21 @@
|
|||||||
|
|
||||||
<p class="lede">本 Changelog 自 2026-05-22 起以 HTML 格式维护。此前之变更可从 main 分支 <code>git log</code> 取得；下表为近期较显著之 commit。</p>
|
<p class="lede">本 Changelog 自 2026-05-22 起以 HTML 格式维护。此前之变更可从 main 分支 <code>git log</code> 取得；下表为近期较显著之 commit。</p>
|
||||||
|
|
||||||
|
<h2>2026-07-31 — 全客户端正式命名、认证迁移与构建分发收口</h2>
|
||||||
|
|
||||||
|
<p>Windows、macOS、iPhone、iPad、Web 与服务端完成一次面向用户文本和可诊断协议面的统一。正式产品名固定为 <strong>Commilitia Drop</strong>；桌面端移除 “Desktop” 后缀，每个平台只保留一份正式客户端。</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>正式客户端矩阵</strong>：Windows 使用 Wails x86-64；macOS 继续使用 Wails ARM64；iPhone 与 iPad 共用 SwiftUI target；Web 使用 React SPA / PWA。原生 macOS target 仍是迁移候选，在功能对等、签名扩展和真机验收完成前不切换，也不作为第二个 macOS 客户端发布</li>
|
||||||
|
<li><strong>用户可见命名与协议</strong>：应用显示名统一为 “Commilitia Drop”；登录回调改为 <code>commilitia-drop://auth-callback</code>；DataChannel 与 iOS 文件流 Scheme 改为 <code>commilitia-drop-file</code>；Bonjour 服务类型改为 <code>_commilitia-drop._tcp</code>；Auth Broker application key 原位迁移为 <code>commilitia-drop</code></li>
|
||||||
|
<li><strong>内部身份兼容边界</strong>：Bundle ID、App Group、Keychain service、LaunchAgent label、环境变量、数据库与配置目录在不直接决定系统显示名时保持稳定，以保留既有权限、钥匙串和配置。稳定 AppId 本身不作为用户可见命名迁移对象</li>
|
||||||
|
<li><strong>认证链修复</strong>：Broker、Caddy 与服务端 application key 同步后，修复桌面端“无法连接”以及 iPhone / iPad 在 Broker 批准后显示“登录失败”的问题；旧 session 允许失效，双移动端已重新登录验证</li>
|
||||||
|
<li><strong>macOS 分发</strong>：复用既有 Developer ID Application 证书，对 Wails ARM64 app 与 DMG 完成 hardened runtime 签名、Apple 公证、staple 与 Gatekeeper 验证；正式分发只保留公证 DMG</li>
|
||||||
|
<li><strong>Windows 与 iOS 安装</strong>：Windows x86-64 客户端已以唯一正式文件安装并更新登录启动项，当前产物尚无 Authenticode 签名；iPhone 与 iPad 全程使用 CLI、复用既有 Apple Development 证书覆盖安装，不打开 Xcode GUI、不创建新证书</li>
|
||||||
|
<li><strong>分支收口</strong>：<code>native-transfer</code> 的原生数据面工作已并入 <code>main</code>，旧分支不再作为开发或发布入口</li>
|
||||||
|
<li><strong>流程文档与验证</strong>：新增 <a href="CLIENT_BUILD_INSTALL.md">全客户端构建与安装手册</a>，记录 Web / 服务端、Broker、Windows、macOS、iPhone、iPad 的构建、签名、安装、分发和验证步骤。代码落点为 main commit <code>c480f0d</code></li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
<h2>2026-06-28 — 原生数据面收口：桌面 pion + iOS libwebrtc，逃离 WebView WebRTC 限制</h2>
|
<h2>2026-06-28 — 原生数据面收口：桌面 pion + iOS libwebrtc，逃离 WebView WebRTC 限制</h2>
|
||||||
|
|
||||||
<p>P2P 数据面（DataChannel 字节收发）从系统 WebView 的 JS 移出、改跑原生：桌面用 <code>pion/webrtc</code>（Go 进程），iOS 用 <strong>libwebrtc</strong>（<code>RTCPeerConnection</code>）。两端逃出 WebKit 写死的 256KB SCTP 接收窗与渲染器节流；JS 仅留信令 / 会话 / presence / 消息 / relay 编排。</p>
|
<p>P2P 数据面（DataChannel 字节收发）从系统 WebView 的 JS 移出、改跑原生：桌面用 <code>pion/webrtc</code>（Go 进程），iOS 用 <strong>libwebrtc</strong>（<code>RTCPeerConnection</code>）。两端逃出 WebKit 写死的 256KB SCTP 接收窗与渲染器节流；JS 仅留信令 / 会话 / presence / 消息 / relay 编排。</p>
|
||||||
@@ -32,7 +47,7 @@
|
|||||||
<ul>
|
<ul>
|
||||||
<li><strong>桌面 pion 数据面</strong>：吞吐专项定位两根因 —— WebView2 的 SCTP 处理活在渲染器进程内、窗口隐藏即被 backgrounding 节流（Windows host↔host 仍 100KB/s），WebKit usrsctp 接收窗写死 256KB。改由 Go <code>pion/webrtc</code> 跑数据面（<code>SetSCTPMaxReceiveBufferSize</code> 大 rwnd、真实 IP host 候选去 mDNS、Go 直接读写磁盘去 base64 桥），窗口状态与网络栈彻底解耦；引入 <code>p2pBackend</code> 抽象使 <code>transfer.ts</code> 编排零改动（<code>isDesktop()</code> 走 Go 桥、web / iOS 走 JS）。Win↔Mac 实测约 10MB/s</li>
|
<li><strong>桌面 pion 数据面</strong>：吞吐专项定位两根因 —— WebView2 的 SCTP 处理活在渲染器进程内、窗口隐藏即被 backgrounding 节流（Windows host↔host 仍 100KB/s），WebKit usrsctp 接收窗写死 256KB。改由 Go <code>pion/webrtc</code> 跑数据面（<code>SetSCTPMaxReceiveBufferSize</code> 大 rwnd、真实 IP host 候选去 mDNS、Go 直接读写磁盘去 base64 桥），窗口状态与网络栈彻底解耦；引入 <code>p2pBackend</code> 抽象使 <code>transfer.ts</code> 编排零改动（<code>isDesktop()</code> 走 Go 桥、web / iOS 走 JS）。Win↔Mac 实测约 10MB/s</li>
|
||||||
<li><strong>iOS libwebrtc 数据面（U1→U2 翻案）</strong>：先试 gomobile + pion（与桌面同引擎，U1），真机 POC 证伪 —— Go raw BSD socket 不与 iOS Network framework 集成（连接时好时坏 + 中途断流）。按闸退到 <strong>libwebrtc.framework</strong>（stasel/WebRTC M149 经 SPM、pin <code>149.0.0</code>），新增 <code>LibWebRtcEngine.swift</code> 端口桌面线协议；libwebrtc 原生集成 iOS 网络栈 + DcSCTP ~5MB 默认 rwnd</li>
|
<li><strong>iOS libwebrtc 数据面（U1→U2 翻案）</strong>：先试 gomobile + pion（与桌面同引擎，U1），真机 POC 证伪 —— Go raw BSD socket 不与 iOS Network framework 集成（连接时好时坏 + 中途断流）。按闸退到 <strong>libwebrtc.framework</strong>（stasel/WebRTC M149 经 SPM、pin <code>149.0.0</code>），新增 <code>LibWebRtcEngine.swift</code> 端口桌面线协议；libwebrtc 原生集成 iOS 网络栈 + DcSCTP ~5MB 默认 rwnd</li>
|
||||||
<li><strong>三端线协议逐字节对齐</strong>：DataChannel <code>cdrop-file</code>（ordered）、<code>meta</code> / 二进制分片(64KB) / <code>done</code> / <code>ack</code> 帧、16MB-4MB 水位背压、接收端 ack 追平完成、不冲突落盘 —— 桌面 pion ↔ iOS libwebrtc ↔ 浏览器 JS 互通。新增结构化日志把 pion 内部日志路由到宿主（真机无 stderr 时诊断连接）；进度回调 ~10Hz 节流（高吞吐下每片一回调打满宿主主线程）</li>
|
<li><strong>三端线协议逐字节对齐</strong>：DataChannel 当时名为 <code>cdrop-file</code>（2026-07-31 已迁移为 <code>commilitia-drop-file</code>），采用 ordered、<code>meta</code> / 二进制分片(64KB) / <code>done</code> / <code>ack</code> 帧、16MB-4MB 水位背压、接收端 ack 追平完成、不冲突落盘 —— 桌面 pion ↔ iOS libwebrtc ↔ 浏览器 JS 互通。新增结构化日志把 pion 内部日志路由到宿主（真机无 stderr 时诊断连接）；进度回调 ~10Hz 节流（高吞吐下每片一回调打满宿主主线程）</li>
|
||||||
<li>验证：环回端到端 20MB 逐字节完整性 + 模拟器全 app 编译 + web typecheck / build 过；iOS 真机已装、用户反馈“传输总体良好”，真网吞吐互通为剩余闸。设计依据见 <code>desktop/NATIVE-TRANSFER.md</code> §7/§8、<code>ios/PLAN.md</code> 决策 F</li>
|
<li>验证：环回端到端 20MB 逐字节完整性 + 模拟器全 app 编译 + web typecheck / build 过；iOS 真机已装、用户反馈“传输总体良好”，真网吞吐互通为剩余闸。设计依据见 <code>desktop/NATIVE-TRANSFER.md</code> §7/§8、<code>ios/PLAN.md</code> 决策 F</li>
|
||||||
<li>commit <code>ab57afd</code>（桌面 pion）· <code>f1a00d1</code> · <code>349d94a</code>（iOS libwebrtc，native-transfer 分支）</li>
|
<li>commit <code>ab57afd</code>（桌面 pion）· <code>f1a00d1</code> · <code>349d94a</code>（iOS libwebrtc，native-transfer 分支）</li>
|
||||||
</ul>
|
</ul>
|
||||||
@@ -205,23 +220,36 @@
|
|||||||
</main>
|
</main>
|
||||||
|
|
||||||
<footer class="page">
|
<footer class="page">
|
||||||
<p>cdrop · docs branch · CHANGELOG</p>
|
<p>Commilitia Drop · docs branch · CHANGELOG</p>
|
||||||
</footer>
|
</footer>
|
||||||
|
|
||||||
<!-- RUNTIME_SPRITE -->
|
<!-- RUNTIME_SPRITE -->
|
||||||
|
|
||||||
<script type="text/markdown" id="md-source">
|
<script type="text/markdown" id="md-source">
|
||||||
# cdrop — Changelog
|
# Commilitia Drop — Changelog
|
||||||
|
|
||||||
时间倒序。细粒度迭代见 git 历史；本档只记录结构性 / 行为性变更与重要 fix。
|
时间倒序。细粒度迭代见 git 历史；本档只记录结构性 / 行为性变更与重要 fix。
|
||||||
|
|
||||||
|
## 2026-07-31 — 全客户端正式命名、认证迁移与构建分发收口
|
||||||
|
|
||||||
|
Windows、macOS、iPhone、iPad、Web 与服务端完成面向用户文本和可诊断协议面的统一。正式产品名固定为 **Commilitia Drop**；桌面端移除 “Desktop” 后缀，每个平台只保留一份正式客户端。
|
||||||
|
|
||||||
|
- 正式客户端矩阵：Windows Wails x86-64；macOS 继续使用 Wails ARM64；iPhone / iPad 共用 SwiftUI target；Web 使用 React SPA / PWA。原生 macOS target 仍是迁移候选，完成对等与验收前不切换、不并行发布
|
||||||
|
- 用户可见命名与协议：显示名 “Commilitia Drop”；回调 `commilitia-drop://auth-callback`；DataChannel / iOS 文件流 Scheme `commilitia-drop-file`；Bonjour `_commilitia-drop._tcp`；Broker application key `commilitia-drop`
|
||||||
|
- 内部身份兼容边界：Bundle ID、App Group、Keychain service、LaunchAgent label、环境变量、数据库与配置目录在不直接决定显示名时保持稳定；稳定 AppId 本身不迁移
|
||||||
|
- 认证链修复：Broker、Caddy 与服务端 application key 同步，修复桌面“无法连接”及 iPhone / iPad 批准后“登录失败”；旧 session 允许失效，双移动端已重登验证
|
||||||
|
- macOS：复用既有 Developer ID Application 证书，Wails ARM64 app / DMG 完成 hardened runtime 签名、Apple 公证、staple 与 Gatekeeper 验证；正式分发只留 DMG
|
||||||
|
- Windows / iOS：Windows x86-64 以唯一正式文件安装并更新登录启动项（当前尚无 Authenticode）；iPhone / iPad 仅用 CLI 和既有 Apple Development 证书覆盖安装，不用 Xcode GUI、不建新证书
|
||||||
|
- 分支收口：`native-transfer` 的原生数据面工作已并入 `main`，旧分支不再作为开发或发布入口
|
||||||
|
- 新增全客户端构建与安装手册 `CLIENT_BUILD_INSTALL.md`；代码落点 main commit `c480f0d`
|
||||||
|
|
||||||
## 2026-06-28 — 原生数据面收口：桌面 pion + iOS libwebrtc，逃离 WebView WebRTC 限制
|
## 2026-06-28 — 原生数据面收口：桌面 pion + iOS libwebrtc，逃离 WebView WebRTC 限制
|
||||||
|
|
||||||
P2P 数据面从系统 WebView 的 JS 移出改跑原生：桌面 pion（Go），iOS libwebrtc（RTCPeerConnection）。两端逃出 WebKit 写死的 256KB 接收窗与渲染器节流；JS 仅留信令 / 会话 / presence / 消息 / relay 编排。
|
P2P 数据面从系统 WebView 的 JS 移出改跑原生：桌面 pion（Go），iOS libwebrtc（RTCPeerConnection）。两端逃出 WebKit 写死的 256KB 接收窗与渲染器节流；JS 仅留信令 / 会话 / presence / 消息 / relay 编排。
|
||||||
|
|
||||||
- 桌面 pion：吞吐两根因（渲染器节流 + 256KB rwnd）经 Go pion 根治（大 rwnd / 真 host 候选去 mDNS / 直接读写磁盘去 base64 桥）；p2pBackend 抽象使 transfer.ts 编排零改动。Win↔Mac 约 10MB/s
|
- 桌面 pion：吞吐两根因（渲染器节流 + 256KB rwnd）经 Go pion 根治（大 rwnd / 真 host 候选去 mDNS / 直接读写磁盘去 base64 桥）；p2pBackend 抽象使 transfer.ts 编排零改动。Win↔Mac 约 10MB/s
|
||||||
- iOS libwebrtc（U1→U2 翻案）：gomobile + pion 真机证伪（Go raw socket 不与 iOS Network framework 集成），退 libwebrtc.framework（stasel/WebRTC M149 SPM pin 149.0.0），LibWebRtcEngine.swift 端口桌面线协议
|
- iOS libwebrtc（U1→U2 翻案）：gomobile + pion 真机证伪（Go raw socket 不与 iOS Network framework 集成），退 libwebrtc.framework（stasel/WebRTC M149 SPM pin 149.0.0），LibWebRtcEngine.swift 端口桌面线协议
|
||||||
- 三端线协议逐字节对齐（cdrop-file ordered / meta + chunk(64KB) + done + ack / 16MB-4MB 水位 / ack 追平完成 / 不冲突落盘）互通；pion 日志路由宿主 + 进度 ~10Hz 节流
|
- 三端线协议逐字节对齐（当时名为 cdrop-file，2026-07-31 已迁移为 commilitia-drop-file；ordered / meta + chunk(64KB) + done + ack / 16MB-4MB 水位 / ack 追平完成 / 不冲突落盘）互通；pion 日志路由宿主 + 进度 ~10Hz 节流
|
||||||
- 环回 20MB 逐字节 + 模拟器全编 + web 双过；真机已装、真网吞吐为剩余闸。见 NATIVE-TRANSFER.md §7/§8、PLAN 决策 F
|
- 环回 20MB 逐字节 + 模拟器全编 + web 双过；真机已装、真网吞吐为剩余闸。见 NATIVE-TRANSFER.md §7/§8、PLAN 决策 F
|
||||||
- commit ab57afd（桌面 pion）· f1a00d1 · 349d94a（iOS，native-transfer 分支）
|
- commit ab57afd（桌面 pion）· f1a00d1 · 349d94a（iOS，native-transfer 分支）
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,348 @@
|
|||||||
|
# Commilitia Drop 全客户端构建与安装手册
|
||||||
|
|
||||||
|
本文记录 Web、服务端、Windows、macOS、iPhone 与 iPad 的正式构建、签名、安装和验证流程。
|
||||||
|
命令默认从仓库根目录执行。项目内部目录名和稳定系统身份可以继续使用 `cdrop`；所有用户可见名称、
|
||||||
|
协议和诊断界面统一使用 “Commilitia Drop” 或 `commilitia-drop` 命名空间。
|
||||||
|
|
||||||
|
## 1. 正式客户端矩阵
|
||||||
|
|
||||||
|
| 平台 | 唯一正式实现 | 架构／设备 | 正式产物 |
|
||||||
|
|---|---|---|---|
|
||||||
|
| Web | `web/` React SPA / PWA | 现代浏览器 | `web/dist/`，嵌入服务端 |
|
||||||
|
| Windows | `desktop/` Wails | x86-64 | `Commilitia Drop.exe` |
|
||||||
|
| macOS | `desktop/` Wails | Apple Silicon ARM64 | `Commilitia Drop.app`／`.dmg` |
|
||||||
|
| iPhone | `ios/CDrop` SwiftUI | 已登记真机 | `CommilitiaDrop.app` |
|
||||||
|
| iPad | `ios/CDrop` SwiftUI | 已登记真机 | 与 iPhone 共用 target |
|
||||||
|
|
||||||
|
`ios/CDrop` 中的原生 macOS target 只是迁移候选。它在功能对等、三语界面、签名扩展和真机验收
|
||||||
|
全部完成前，不得替代 Wails，也不得作为第二个 macOS 客户端发布。macOS 只考虑 ARM64。
|
||||||
|
|
||||||
|
## 2. 命名与兼容边界
|
||||||
|
|
||||||
|
- 用户可见产品名：`Commilitia Drop`，桌面应用名中不再出现 `Desktop`。
|
||||||
|
- iOS／iPadOS 登录回调：`commilitia-drop://auth-callback`。
|
||||||
|
- WebRTC DataChannel 与 iOS 文件流 Scheme：`commilitia-drop-file`。
|
||||||
|
- Bonjour 服务类型：`_commilitia-drop._tcp`。
|
||||||
|
- Auth Broker application key：`commilitia-drop`。它会出现在 OAuth 参数和 JWT scope 中，属于
|
||||||
|
用户可见／可诊断协议文本。
|
||||||
|
- Bundle ID、App Group、Keychain service、LaunchAgent label、环境变量、数据库和配置目录不直接
|
||||||
|
决定显示名，保持稳定以保护系统权限、钥匙串数据和既有配置。
|
||||||
|
- 每个平台只保留上表的一份正式客户端；迁移验证成功后删除同平台旧名称副本。
|
||||||
|
|
||||||
|
命名复扫时应区分用户可见文本和内部身份。建议至少检查：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
rg -n -i 'commilitia drop desktop|cdrop desktop|cdrop://|_cdrop\._tcp|cdrop-file' \
|
||||||
|
README.md docs auth desktop ios web
|
||||||
|
```
|
||||||
|
|
||||||
|
允许保留的典型内部值包括 `CDROP_*` 环境变量、`net.commilitia.cdrop` LaunchAgent／Bundle ID、
|
||||||
|
源码 package 和存储目录。若某个内部值直接、不可更改地成为系统显示名，则必须单独迁移。
|
||||||
|
|
||||||
|
## 3. 通用前置与密钥规则
|
||||||
|
|
||||||
|
本地需要 Go、Node.js、Wails v2、Just、Xcode Command Line Tools、XcodeGen，以及 iOS 依赖所需的
|
||||||
|
Swift Package Manager。环境配置放在仓库根目录、已被 Git 忽略的 `.env`；变量说明见
|
||||||
|
`.env.example`。
|
||||||
|
|
||||||
|
签名和密钥遵循以下规则：
|
||||||
|
|
||||||
|
- 不在仓库记录 `.p8`、私钥、Broker internal key、VAPID 私钥或证书导出文件。
|
||||||
|
- iPhone／iPad 必须复用钥匙串中既有 Apple Development 证书。把其 SHA-1 写入
|
||||||
|
`CDROP_APPLE_DEVELOPMENT_IDENTITY`；recipe 会在构建前检查身份并把该值固定传给
|
||||||
|
`xcodebuild`。不得用 Xcode GUI，不得新建证书或修改私钥 ACL。
|
||||||
|
- macOS 正式分发必须复用既有 Developer ID Application 证书；完整身份名写入
|
||||||
|
`CDROP_DEVID_IDENTITY`。
|
||||||
|
- App Store Connect API Key 只通过 `CDROP_ASC_KEY_PATH`、`CDROP_ASC_KEY_ID` 和
|
||||||
|
`CDROP_ASC_ISSUER_ID` 引用。
|
||||||
|
- 登录钥匙串必须已经解锁。`errSecInternalComponent` 通常表示签名进程不能使用私钥；先在用户的
|
||||||
|
普通 Terminal 解锁登录钥匙串，再重试同一证书，不要创建替代证书。
|
||||||
|
|
||||||
|
构建前可做基础检查：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
git status --short
|
||||||
|
go version
|
||||||
|
node --version
|
||||||
|
just desktop-doctor
|
||||||
|
security find-identity -v -p codesigning
|
||||||
|
xcrun devicectl list devices
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Web 与服务端
|
||||||
|
|
||||||
|
### 4.1 构建和验证 Web
|
||||||
|
|
||||||
|
```sh
|
||||||
|
just typecheck-front
|
||||||
|
just build-front
|
||||||
|
```
|
||||||
|
|
||||||
|
正式 Web 构建输出在 `web/dist/`。服务端通过嵌入静态文件提供 SPA、PWA manifest、service worker
|
||||||
|
和 iOS 原生引擎页，因此发布 Web 改动时必须重新构建服务端镜像，不能只替换单个 HTML 文件。
|
||||||
|
|
||||||
|
```sh
|
||||||
|
just test
|
||||||
|
just docker-image
|
||||||
|
```
|
||||||
|
|
||||||
|
部署新镜像后至少验证：
|
||||||
|
|
||||||
|
```text
|
||||||
|
/healthz
|
||||||
|
/api/auth/config
|
||||||
|
/site.webmanifest
|
||||||
|
/engine.html
|
||||||
|
```
|
||||||
|
|
||||||
|
`/api/auth/config` 应返回 `broker_app=commilitia-drop`；manifest 的 `name` 与 `short_name` 均应为
|
||||||
|
“Commilitia Drop”。登录、扫码批准、设备续期和传输必须各做一次实际冒烟。
|
||||||
|
|
||||||
|
### 4.2 Auth Broker 原位迁移
|
||||||
|
|
||||||
|
Broker application 不创建并行副本，直接把既有 `cdrop` 项改为：
|
||||||
|
|
||||||
|
```text
|
||||||
|
key: commilitia-drop
|
||||||
|
callback: commilitia-drop://auth-callback
|
||||||
|
```
|
||||||
|
|
||||||
|
只需在修改前备份一次 Broker 配置；客户端和服务端源码由 Git 历史恢复，不另做文件备份。迁移后旧
|
||||||
|
session 可以全部失效，客户端重新登录。Broker、Caddy 和服务端的 application key 必须同时一致；
|
||||||
|
否则批准可以完成，但客户端会在兑换或 scope 校验阶段显示“登录失败”。
|
||||||
|
|
||||||
|
若 Caddyfile 以单文件 bind mount 进入容器，宿主机上的 `sed -i`／原子替换会生成新 inode，而运行
|
||||||
|
容器仍可能读旧 inode。修改后必须热加载，并从 Caddy admin API 或容器内实际挂载内容验证生效；
|
||||||
|
不能只查看宿主机路径。
|
||||||
|
|
||||||
|
## 5. macOS 正式客户端（Wails ARM64）
|
||||||
|
|
||||||
|
### 5.1 开发构建
|
||||||
|
|
||||||
|
```sh
|
||||||
|
just desktop-build-mac
|
||||||
|
```
|
||||||
|
|
||||||
|
任务先构建最新 Web 前端，再执行 `wails build -clean -s -platform darwin/arm64`。输出为：
|
||||||
|
|
||||||
|
```text
|
||||||
|
desktop/build/bin/Commilitia Drop.app
|
||||||
|
```
|
||||||
|
|
||||||
|
`-clean` 是必要的：macOS 与 Windows 共用 `desktop/build/bin/`，另一平台的残留产物可能被 Wails／Go
|
||||||
|
误判为构建输入。不要把原生 macOS 候选 target 的产物放进正式分发目录。
|
||||||
|
|
||||||
|
### 5.2 Developer ID 签名、公证与 DMG
|
||||||
|
|
||||||
|
在 `.env` 配齐以下变量：
|
||||||
|
|
||||||
|
```text
|
||||||
|
CDROP_DEVID_IDENTITY
|
||||||
|
CDROP_ASC_KEY_PATH
|
||||||
|
CDROP_ASC_KEY_ID
|
||||||
|
CDROP_ASC_ISSUER_ID
|
||||||
|
```
|
||||||
|
|
||||||
|
然后运行：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
just desktop-dist-mac
|
||||||
|
```
|
||||||
|
|
||||||
|
该 recipe 会依次完成：
|
||||||
|
|
||||||
|
1. ARM64 Wails 构建；
|
||||||
|
2. 使用既有 Developer ID Application 身份、hardened runtime 和 secure timestamp 签名 `.app`；
|
||||||
|
3. 将 `.app` 以 `ditto` 打包提交 Apple 公证，等待 `Accepted`，再 staple／validate；
|
||||||
|
4. 生成含 `.app` 和 `/Applications` 链接的压缩 DMG；
|
||||||
|
5. 对 DMG 签名、单独提交公证并 staple／validate；
|
||||||
|
6. 用 Gatekeeper `spctl` 分别评估 app 和 DMG。
|
||||||
|
|
||||||
|
最终文件为 `desktop/build/bin/Commilitia Drop.dmg`。发布前再次检查：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
codesign --verify --deep --strict --verbose=2 \
|
||||||
|
'desktop/build/bin/Commilitia Drop.app'
|
||||||
|
xcrun stapler validate 'desktop/build/bin/Commilitia Drop.app'
|
||||||
|
xcrun stapler validate 'desktop/build/bin/Commilitia Drop.dmg'
|
||||||
|
spctl --assess --type execute --verbose=2 \
|
||||||
|
'desktop/build/bin/Commilitia Drop.app'
|
||||||
|
spctl --assess --type open --context context:primary-signature --verbose=2 \
|
||||||
|
'desktop/build/bin/Commilitia Drop.dmg'
|
||||||
|
```
|
||||||
|
|
||||||
|
2026-07-31 已用既有 Developer ID 证书验证完整链路：app 与 DMG 均获 Apple `Accepted`，并完成
|
||||||
|
staple 和 Gatekeeper 的 `Notarized Developer ID` 评估。
|
||||||
|
|
||||||
|
### 5.3 本机安装
|
||||||
|
|
||||||
|
先验证新 app，再替换 `/Applications` 中的正式客户端；不保留第二个 `Desktop` 副本：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
ditto 'desktop/build/bin/Commilitia Drop.app' \
|
||||||
|
'/Applications/Commilitia Drop.app'
|
||||||
|
```
|
||||||
|
|
||||||
|
LaunchAgent label `net.commilitia.cdrop` 是稳定内部身份，可以保留；但其 `ProgramArguments` 必须指向：
|
||||||
|
|
||||||
|
```text
|
||||||
|
/Applications/Commilitia Drop.app/Contents/MacOS/Commilitia Drop
|
||||||
|
```
|
||||||
|
|
||||||
|
更新磁盘 plist 后需要重新 bootstrap，不能只看文件，因为 launchd 可能仍缓存旧路径。最终检查已安装
|
||||||
|
app 的签名、公证、架构、进程路径，以及“登录后启动”开关。
|
||||||
|
|
||||||
|
## 6. Windows 正式客户端（Wails x64）
|
||||||
|
|
||||||
|
### 6.1 构建
|
||||||
|
|
||||||
|
```sh
|
||||||
|
just desktop-build-win
|
||||||
|
```
|
||||||
|
|
||||||
|
输出为 `desktop/build/bin/Commilitia Drop.exe`。在 macOS 上交叉构建无需 MinGW；Windows 特有通知
|
||||||
|
和 WebView2 绑定不依赖 Darwin CGO。当前 EXE 尚无 Authenticode 签名，Windows 会报告
|
||||||
|
`NotSigned`，并可能显示 SmartScreen 提示；获得 Windows 代码签名证书后应把签名步骤加入 recipe。
|
||||||
|
|
||||||
|
### 6.2 通过 mDNS 无代理直连安装
|
||||||
|
|
||||||
|
目标主机使用 `Desktop-C.local`、SSH 端口 `223`、用户 `commilitia`。访问该主机不得使用任何代理。
|
||||||
|
先确认 shell、系统和 SSH 配置没有代理：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
env | rg -i '^(http|https|all|ftp|no)_proxy='
|
||||||
|
scutil --proxy
|
||||||
|
ssh -G -p 223 commilitia@Desktop-C.local | \
|
||||||
|
rg -i '^(hostname|user|port|proxycommand|proxyjump) '
|
||||||
|
```
|
||||||
|
|
||||||
|
mDNS 可能先返回不可达 IPv6，使 SSH 看似超时；继续保留 mDNS 主机名并用 `-4` 强制 IPv4。显式清除
|
||||||
|
代理变量、禁用 SSH 代理和跳板，并建立任务专用、10 分钟 TTL 的复用连接：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
env -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
|
||||||
|
-u http_proxy -u https_proxy -u all_proxy \
|
||||||
|
ssh -4 -M -S /tmp/commilitia-drop-windows-%C \
|
||||||
|
-o ControlPersist=600 -o ProxyCommand=none -o ProxyJump=none \
|
||||||
|
-p 223 commilitia@Desktop-C.local exit
|
||||||
|
```
|
||||||
|
|
||||||
|
复用前用 `stat` 检查 socket 创建时间仍在 TTL 内，并执行 `ssh -O check`。安装流程为：
|
||||||
|
|
||||||
|
1. 在 Windows 上只读侦查 `D:\Tools`、匹配进程和
|
||||||
|
`HKCU\Software\Microsoft\Windows\CurrentVersion\Run`；
|
||||||
|
2. 本地记录 EXE 的 SHA-256；
|
||||||
|
3. 用同一 `-4`、`ProxyCommand=none`、`ProxyJump=none` 连接上传到用户目录暂存；
|
||||||
|
4. 远端再次校验 SHA-256；
|
||||||
|
5. 停止旧 `D:\Tools\Commilitia Drop Desktop.exe` 进程；
|
||||||
|
6. 先复制为 `Commilitia Drop.installing.exe` 并再次校验，再原子移到
|
||||||
|
`D:\Tools\Commilitia Drop.exe`；
|
||||||
|
7. 把既有 “Commilitia Drop” Run 项改为
|
||||||
|
`"D:\Tools\Commilitia Drop.exe" --hidden`；
|
||||||
|
8. 只有新文件哈希正确后才删除旧 `Desktop` 文件与上传暂存文件；
|
||||||
|
9. 从 SSH 服务会话直接 `Start-Process` 可能因没有交互桌面而立即退出。使用当前用户完整 Windows
|
||||||
|
身份注册 `LogonType=Interactive` 的一次性计划任务，启动后立即删除任务；
|
||||||
|
10. 独立复核新进程在交互 Session、旧文件不存在、Run 项正确且应用日志无新错误。
|
||||||
|
|
||||||
|
2026-07-31 在 `Desktop-C.local` 已完成上述流程，正式路径为
|
||||||
|
`D:\Tools\Commilitia Drop.exe`，旧 `Desktop` 文件已删除，登录启动项和运行进程均指向新路径。
|
||||||
|
|
||||||
|
## 7. iPhone 与 iPad
|
||||||
|
|
||||||
|
两种设备共用 `CommilitiaDrop` scheme 和一套签名约束。全程使用 CLI，不打开 Xcode GUI。
|
||||||
|
|
||||||
|
### 7.1 模拟器验证
|
||||||
|
|
||||||
|
```sh
|
||||||
|
just ios-sim-build
|
||||||
|
```
|
||||||
|
|
||||||
|
该任务会拉取／生成品牌字体、运行 XcodeGen、解析 SPM 的 libwebrtc，并针对通用 iOS Simulator
|
||||||
|
目标编译。模拟器不需要 Apple 签名，但不能替代真机的 URL Scheme、本地网络、APNs、Share
|
||||||
|
Extension 和后台行为验收。
|
||||||
|
|
||||||
|
### 7.2 复用既有证书真机构建
|
||||||
|
|
||||||
|
在 `.env` 配齐：
|
||||||
|
|
||||||
|
```text
|
||||||
|
CDROP_TEAM_ID
|
||||||
|
CDROP_ASC_KEY_PATH
|
||||||
|
CDROP_ASC_KEY_ID
|
||||||
|
CDROP_ASC_ISSUER_ID
|
||||||
|
CDROP_APPLE_DEVELOPMENT_IDENTITY=<既有 Apple Development 证书 SHA-1>
|
||||||
|
```
|
||||||
|
|
||||||
|
确认设备与身份：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
just ios-devices
|
||||||
|
security find-identity -v -p codesigning | \
|
||||||
|
rg -F "$CDROP_APPLE_DEVELOPMENT_IDENTITY"
|
||||||
|
```
|
||||||
|
|
||||||
|
分别覆盖安装 iPhone 与 iPad：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
just ios-device <iPhone-UDID>
|
||||||
|
just ios-device <iPad-UDID>
|
||||||
|
```
|
||||||
|
|
||||||
|
`ios-device` 会把 SHA-1 作为 `CODE_SIGN_IDENTITY` 固定传入 `xcodebuild`，ASC API Key 仅用于自动
|
||||||
|
provisioning 的设备、能力和 profile 更新。若签名测试返回 `errSecInternalComponent`，应解锁当前
|
||||||
|
登录钥匙串后重试，不得生成新证书或修改私钥 ACL。
|
||||||
|
|
||||||
|
安装后验证：
|
||||||
|
|
||||||
|
- 设备端显示名为“Commilitia Drop”；
|
||||||
|
- Bundle ID 保持 `net.commilitia.Commilitia-Drop`；
|
||||||
|
- `commilitia-drop://auth-callback` 已登记；
|
||||||
|
- 旧 session 失效时能进入登录页，经 Broker 批准后回到 app 并成功建立新 session；
|
||||||
|
- iPhone 与 iPad 各自完成一次发送、接收、本地网络权限和后台／扩展冒烟。
|
||||||
|
|
||||||
|
更完整的真机能力清单见 `ios/CDrop/REALDEVICE.md`。
|
||||||
|
|
||||||
|
## 8. 发布顺序与分发目录
|
||||||
|
|
||||||
|
Wails 的 macOS 和 Windows recipe 都用 `-clean` 且共享 `desktop/build/bin/`，因此不能假设两个产物
|
||||||
|
会同时保留。推荐固定顺序：
|
||||||
|
|
||||||
|
1. `just desktop-dist-mac`；
|
||||||
|
2. 复制 `Commilitia Drop.dmg` 到分发目录；
|
||||||
|
3. `just desktop-build-win`；
|
||||||
|
4. 复制 `Commilitia Drop.exe` 到分发目录；
|
||||||
|
5. 检查分发目录只保留这两个正式文件，不保留 `Commilitia Drop Desktop.*`；
|
||||||
|
6. 记录两者 SHA-256。
|
||||||
|
|
||||||
|
当前分发目录约定为：
|
||||||
|
|
||||||
|
```text
|
||||||
|
~/Library/CloudStorage/Dropbox/软件客户端/Commilitia Drop/
|
||||||
|
```
|
||||||
|
|
||||||
|
不要把 `.app` bundle 当成 Dropbox 的正式发布物；macOS 使用已签名、公证、装订的 DMG。
|
||||||
|
|
||||||
|
## 9. 提交前验证矩阵
|
||||||
|
|
||||||
|
```sh
|
||||||
|
git diff --check
|
||||||
|
go test ./...
|
||||||
|
(cd desktop && go test ./...)
|
||||||
|
(cd web && npm run typecheck)
|
||||||
|
(cd web && npm run build)
|
||||||
|
just ios-sim-build
|
||||||
|
bash -n desktop/scripts/make-dmg.sh
|
||||||
|
just --dry-run desktop-dist-mac
|
||||||
|
```
|
||||||
|
|
||||||
|
平台产物还需验证：
|
||||||
|
|
||||||
|
| 对象 | 必验项 |
|
||||||
|
|---|---|
|
||||||
|
| Web／服务端 | health、auth config、manifest、登录、传输 |
|
||||||
|
| Mac app／DMG | ARM64、Developer ID、hardened runtime、Accepted、staple、Gatekeeper |
|
||||||
|
| Windows EXE | PE32+ x86-64、SHA-256、唯一文件、Run 项、交互 Session 进程 |
|
||||||
|
| iPhone／iPad | 既有证书 SHA-1、签名验证、显示名、URL Scheme、Broker 登录、真机传输 |
|
||||||
|
|
||||||
|
提交时不加入 `.env`、`.p8`、构建产物、临时 PowerShell／安装脚本或 Broker 备份。客户端源码和构建
|
||||||
|
流程由 Git 历史恢复；Auth Broker 配置备份由服务端运维位置单独保留。
|
||||||
+20
-3
@@ -1,8 +1,23 @@
|
|||||||
# Commilitia Drop — 前端设计
|
# Commilitia Drop — 前端设计
|
||||||
|
|
||||||
补充 PROJECT_BRIEF.md，专注 web 前端实现。后端、协议、鉴权见主 brief。
|
补充 [`PROJECT_BRIEF.md`](PROJECT_BRIEF.md)，专注 Web 前端实现。后端、协议、鉴权见主 brief；
|
||||||
|
正式客户端矩阵与发布流程见 [`CLIENT_BUILD_INSTALL.md`](CLIENT_BUILD_INSTALL.md)。
|
||||||
|
|
||||||
> 本文记录 MVP 初版前端设计（Mantine + 浅色）。其后前端经「Theme B」重塑：自定义设计 token、品牌 web font、Dracula 深色、聚珍（Juzhen）CJK 综合排版——视觉部分以 [`CHANGELOG`](CHANGELOG.html) 与实际代码为准。
|
> 本文记录 MVP 初版前端设计（Mantine + 浅色）。其后前端经“Theme B”重塑：自定义设计
|
||||||
|
> token、品牌 Web font、Dracula 深色、聚珍（Juzhen）CJK 综合排版——视觉部分以
|
||||||
|
> [`CHANGELOG`](CHANGELOG.html) 与实际代码为准。文中的 `cdrop` 仅表示内部项目代号或历史
|
||||||
|
> 代码标识；所有当前用户可见产品名均为“Commilitia Drop”。
|
||||||
|
|
||||||
|
## 当前多客户端边界（2026-07-31）
|
||||||
|
|
||||||
|
- Web 页面与 PWA 的 `name` / `short_name` 均显示“Commilitia Drop”。
|
||||||
|
- Windows 与 macOS 共享本项目的 Web UI 和 Wails 宿主，但各平台只发布一份正式客户端；桌面
|
||||||
|
显示名不带 “Desktop”。macOS 正式实现仍为 Wails ARM64，原生 macOS target 只作迁移候选。
|
||||||
|
- iPhone / iPad 使用原生 SwiftUI 界面和 libwebrtc 数据面，共用一个正式 target。
|
||||||
|
- 登录回调、DataChannel、iOS 文件流 Scheme、Bonjour 服务类型与 Auth Broker application key
|
||||||
|
都属于用户可见或可诊断文本，使用 `commilitia-drop` 命名空间。
|
||||||
|
- Bundle ID、App Group、Keychain service、LaunchAgent label 等稳定内部身份不因品牌显示名而
|
||||||
|
改动，除非它们直接且不可配置地成为系统显示名。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -55,7 +70,9 @@ lucide-react 图标
|
|||||||
|
|
||||||
**配色**：浅色优先，且 MVP 阶段**仅实现浅色**。深色模式属阶段三 UX 完善的范围，不在 MVP 内。Mantine 配置 `defaultColorScheme="light"`，不读取 `prefers-color-scheme`，不提供切换控件。
|
**配色**：浅色优先，且 MVP 阶段**仅实现浅色**。深色模式属阶段三 UX 完善的范围，不在 MVP 内。Mantine 配置 `defaultColorScheme="light"`，不读取 `prefers-color-scheme`，不提供切换控件。
|
||||||
|
|
||||||
强调色 cdrop 蓝（`#3b82f6` 量级，待最终选定）。文本主色深灰（`#1f2937`），次级灰阶按 Mantine `gray.6 / gray.7` 走。背景纯白或近白（`#fafafa`）以减少屏幕反光强度。
|
历史设计稿把强调色称为内部“cdrop 蓝”（`#3b82f6` 量级，待最终选定）。文本主色深灰
|
||||||
|
（`#1f2937`），次级灰阶按 Mantine `gray.6 / gray.7` 走。背景纯白或近白（`#fafafa`）以减少
|
||||||
|
屏幕反光强度。
|
||||||
|
|
||||||
### 字体与 CJK 排版
|
### 字体与 CJK 排版
|
||||||
|
|
||||||
|
|||||||
+27
-2
@@ -1,13 +1,38 @@
|
|||||||
# Commilitia Drop — 跨 OS 剪贴板与文件传输服务
|
# Commilitia Drop — 跨 OS 剪贴板与文件传输服务
|
||||||
|
|
||||||
> 本文是项目最初的 MVP 规格（设计基线），保留作架构参考；**当前实现状态以 [`CHANGELOG`](CHANGELOG.html) 为准**——其后已落地剪贴板/消息通道、Wails 桌面端、扫码登录与 Auth Broker、**原生数据面（P2P 数据面从浏览器 JS 下沉原生：桌面 pion、iOS libwebrtc）**、iOS 原生客户端、安全加固等，部分「远期」项已实现。
|
> 本文是项目最初的 MVP 规格（设计基线），保留作架构参考；**当前实现状态以
|
||||||
|
> [`CHANGELOG`](CHANGELOG.html) 为准**。全客户端正式构建、签名、安装和分发流程见
|
||||||
|
> [`CLIENT_BUILD_INSTALL.md`](CLIENT_BUILD_INSTALL.md)。
|
||||||
|
|
||||||
项目代号 / 仓库名 / 二进制名：`cdrop`
|
产品名：Commilitia Drop
|
||||||
|
内部项目代号 / 仓库名：`cdrop`
|
||||||
部署域名：`drop.commilitia.net`
|
部署域名：`drop.commilitia.net`
|
||||||
节点：自托管（单机 Docker + 反代）
|
节点：自托管（单机 Docker + 反代）
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 当前实现叠加层（2026-07-31）
|
||||||
|
|
||||||
|
以下状态覆盖本文后续仍保留的历史 MVP 假设：
|
||||||
|
|
||||||
|
- 正式客户端为 Web、Windows Wails x86-64、macOS Wails ARM64，以及共用 SwiftUI target 的
|
||||||
|
iPhone / iPad。macOS 原生 target 尚未完成迁移验收，不得替代 Wails，也不得并行发布。
|
||||||
|
- 用户可见应用名统一为“Commilitia Drop”，桌面端不再带 “Desktop” 后缀；正式桌面产物为
|
||||||
|
`Commilitia Drop.exe`、`Commilitia Drop.app` 和 `Commilitia Drop.dmg`。
|
||||||
|
- 用户可见或可诊断的协议命名统一为 `commilitia-drop://auth-callback`、
|
||||||
|
`commilitia-drop-file`、`_commilitia-drop._tcp` 和 Broker application key
|
||||||
|
`commilitia-drop`。
|
||||||
|
- Bundle ID、App Group、Keychain service、LaunchAgent label、环境变量和数据目录等内部身份，
|
||||||
|
只要不直接、不可更改地决定系统显示名，就保持稳定以保护既有权限、钥匙串和配置。
|
||||||
|
- 鉴权已委托 Auth Broker，Broker、Caddy 与服务端使用同一个 application key；历史 Casdoor
|
||||||
|
直连、自签会话和 shortcut token 描述仅用于理解演进，不代表当前部署。
|
||||||
|
- P2P 数据面已从 WebView JavaScript 下沉：桌面使用 Go / pion，iOS / iPadOS 使用 libwebrtc；
|
||||||
|
Web 仍使用浏览器 `RTCPeerConnection`。三端共享信令、relay 编排与线协议。
|
||||||
|
- macOS 正式分发复用既有 Developer ID Application 证书并经 Apple 公证；iPhone / iPad
|
||||||
|
复用既有 Apple Development 证书，使用 CLI 构建安装，不使用 Xcode GUI。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 1. 目标
|
## 1. 目标
|
||||||
|
|
||||||
跨 OS（Win / macOS / Linux / iOS / Android）服务，提供：
|
跨 OS（Win / macOS / Linux / iOS / Android）服务，提供：
|
||||||
|
|||||||
Reference in New Issue
Block a user