feat: 统一 Commilitia Drop 全客户端命名与分发

2026-07-31 22:56:10 +08:00
parent f7b0f04c9c
commit c480f0d1c2
77 changed files with 861 additions and 263 deletions
@@ -1,6 +1,8 @@
-# cdrop 桌面端 D1 前决策就绪简报
+# Commilitia Drop 桌面端 D1 前决策就绪简报

-> 框架基线：Wails v2.12.0（Go 1.23 模块声明，本机 toolchain 1.26.3）+ 系统 WebView，瘦客户端，业务全走 `drop.commilitia.net`。平台优先级 macOS（Apple Silicon + Intel universal），Windows x64 兼容。
+> 框架基线：Wails v2.12.0（Go 1.23 模块声明，本机 toolchain 1.26.3）+ 系统 WebView，
+> 瘦客户端，业务全走 `drop.commilitia.net`。平台优先级 macOS（仅 Apple Silicon），
+> Windows x64 兼容。
 > 已对四项关键论断做对抗式核验：托盘能力 **refuted**、热键库可用性 **supported（附 pin 条件）**、Casdoor/R1 **mixed（需一处后端改动 + 版本前提）**、签名/公证 entitlement **mixed（核心子句成立，捆绑表述需修正）**。

 ---
@@ -121,7 +123,7 @@

 本节只覆盖 Wails/Go 客户端侧的实现机制。前提已确定：public client + PKCE，回调用 `http://127.0.0.1:<临时端口>/callback`，Casdoor 对 loopback 任意端口放行，后端 audience 改多值校验。Casdoor 端点：authorize=`/login/oauth/authorize`，token=`/api/login/oauth/access_token`。

-### 1. loopback vs 自定义 scheme `cdrop://` 的取舍（Wails 语境）
+### 1. loopback vs 自定义 scheme `commilitia-drop://` 的取舍（Wails 语境）

 两条路线都符合 RFC 8252 对原生应用的要求（§7.1 私有 scheme、§7.3 loopback），但在 Wails 下实现成本差异明显。

@@ -132,10 +134,15 @@
 - 跨平台零差异：macOS / Windows / Linux 代码一致，只依赖 `net/http`。
 - 必须用 IP 字面量 `127.0.0.1`（或 `[::1]`），不要用 `localhost`——RFC 8252 §8.3：用 `localhost` 可能因 DNS / hosts 解析意外监听到非回环接口。端口用 OS 分配的临时端口（`:0`），符合 RFC 8252 §7.3“服务器 MUST 允许请求时指定任意端口”。

-**自定义 scheme（`cdrop://callback`）：**
+**自定义 scheme（`commilitia-drop://callback`）：**

- 需要 OS 级登记：macOS 在 `Info.plist` 写 `CFBundleURLTypes` → `CFBundleURLSchemes`（值 `cdrop`）；Windows 要在注册表 `HKEY_CLASSES_ROOT\cdrop`（或 per-user `HKCU\Software\Classes\cdrop`）写 `URL Protocol` 键 + `shell\open\command` 指向 exe；Linux 走 `.desktop` 的 `x-scheme-handler/cdrop`。
- 必须配单实例锁。点 `cdrop://` 时 OS 会重新拉起 app 的“第二个实例”，深链作为命令行参数传入。需要 `options.App.SingleInstanceLock` 把这个 deep link 转发给首实例，否则 token 落在一个马上要退出的临时进程里，拿不到。
+- 需要 OS 级登记：macOS 在 `Info.plist` 写 `CFBundleURLTypes` → `CFBundleURLSchemes`
+  （值 `commilitia-drop`）；Windows 要在注册表
+  `HKEY_CLASSES_ROOT\commilitia-drop`（或 per-user
+  `HKCU\Software\Classes\commilitia-drop`）写 `URL Protocol` 键 +
+  `shell\open\command` 指向 exe；Linux 走
+  `.desktop` 的 `x-scheme-handler/commilitia-drop`。
+- 必须配单实例锁。点 `commilitia-drop://` 时 OS 会重新拉起 app 的“第二个实例”，深链作为命令行参数传入。需要 `options.App.SingleInstanceLock` 把这个 deep link 转发给首实例，否则 token 落在一个马上要退出的临时进程里，拿不到。
 - macOS 上单实例锁与深链协作有已知坑（见 wails issue #5089：v3 的 single instance lock 与 `OpenedWithURL` 不兼容；v2 也需自己从 `Args` 解析 URL 并 `WindowUnminimise` + `Show`）。

 scheme 路线的 `SingleInstanceLock` 形态（作为对比，**本项目不采用**）：
@@ -145,9 +152,9 @@ scheme 路线的 `SingleInstanceLock` 形态（作为对比，**本项目不采
 SingleInstanceLock: &options.SingleInstanceLock{
    UniqueId: "net.commilitia.cdrop",
    OnSecondInstanceLaunch: func(d options.SecondInstanceData) {
-        // d.Args 里含被 OS 透传的 cdrop://callback?code=...&state=...
+        // d.Args 里含被 OS 透传的 commilitia-drop://callback?code=...&state=...
        for _, arg := range d.Args {
-            if strings.HasPrefix(arg, "cdrop://") {
+            if strings.HasPrefix(arg, "commilitia-drop://") {
                runtime.WindowUnminimise(appCtx) // 回调不会自动聚焦窗口
                runtime.Show(appCtx)
                runtime.EventsEmit(appCtx, "oauth:callback", arg)
@@ -157,7 +164,7 @@ SingleInstanceLock: &options.SingleInstanceLock{
 },
 ```

-**推荐：loopback。** 在 Wails 下它省掉了单实例锁、`Info.plist`/注册表登记、深链解析与跨平台分叉这一整套，授权流在单进程内自洽，代码量和真机调试面都小得多。`cdrop://` 的唯一优势是不占端口、回调 URL 更“原生”，但对瘦客户端不值这些成本。scheme 留作未来若需“浏览器里点 cdrop 链接唤起桌面端”的备选——那是另一个用例（深链唤起），与本次登录回调无关。
+**推荐：loopback。** 在 Wails 下它省掉了单实例锁、`Info.plist`/注册表登记、深链解析与跨平台分叉这一整套，授权流在单进程内自洽，代码量和真机调试面都小得多。`commilitia-drop://` 的唯一优势是不占端口、回调 URL 更“原生”，但对瘦客户端不值这些成本。scheme 留作未来若需“浏览器里点 Commilitia Drop 链接唤起桌面端”的备选——那是另一个用例（深链唤起），与本次登录回调无关。

 ### 2. `runtime.BrowserOpenURL` 用法与注意

@@ -397,13 +404,13 @@ export async function onLoginClick(): Promise<void>
 func writeClosePage(w http.ResponseWriter, ok bool)
 {
    w.Header().Set("Content-Type", "text/html; charset=utf-8")
-    msg := "已登录，可关闭本页返回 cdrop。"
+    msg := "已登录，可关闭本页返回 Commilitia Drop。"
    if !ok
    {
-        msg = "登录未完成，可关闭本页返回 cdrop 重试。"
+        msg = "登录未完成，可关闭本页返回 Commilitia Drop 重试。"
    }
    fmt.Fprintf(w, `<!doctype html><html lang="zh-Hans"><head><meta charset="utf-8">`+
-        `<title>cdrop</title></head><body style="font-family:sans-serif;text-align:center;margin-top:20vh">`+
+        `<title>Commilitia Drop</title></head><body style="font-family:sans-serif;text-align:center;margin-top:20vh">`+
        `<p>%s</p><script>setTimeout(function(){window.close();},800);</script>`+
        `</body></html>`, msg)
 }
@@ -443,7 +450,8 @@ func writeClosePage(w http.ResponseWriter, ok bool)

 ## 打包·签名·公证操作手册（D6 补充）

-本节只补**具体命令与 CI 配置**；entitlement／公证“会不会被拒”的判断已在前文完成。环境基准：Wails v2.12.0（Go），macOS universal 优先 + Windows x64，瘦客户端。
+本节只补**具体命令与 CI 配置**；entitlement／公证“会不会被拒”的判断已在前文完成。
+环境基准：Wails v2.12.0（Go），macOS arm64 + Windows x64，瘦客户端。

 > 重要前提：Wails 官方 signing 指南至今仍推荐 `gon`，但该工具已停止维护、且依赖已废弃的 `altool` 语义。本手册一律改用 Apple 现行的 `codesign` + `notarytool` + `stapler` 链路，这是已确定的正确路径。

@@ -452,13 +460,15 @@ func writeClosePage(w http.ResponseWriter, ok bool)
 #### 1.1 构建产物与已知坑（已确定）

 ```bash
-wails build -platform darwin/universal -clean
+wails build -platform darwin/arm64 -clean
 ```

- 产物：`build/bin/<AppName>.app`（universal `.app` bundle，`lipo` 已合并 arm64 + amd64 两份 Go 二进制）。`<AppName>` 来自 `wails.json` 的 `outputfilename`／项目名。
+- 产物：`build/bin/<AppName>.app`（Apple Silicon arm64）。`<AppName>` 来自
+  `wails.json` 的 `outputfilename`／项目名。
 - 项目脚手架在 `build/darwin/` 下生成 `Info.plist`（模板 `Info.plist`／`Info.dev.plist`），这是 `.app` 内 `Contents/Info.plist` 的来源。改 bundle ID、版本号、`LSMinimumSystemVersion` 等都改这里。
 - 已知坑：
-  - universal 构建要求**本机同时具备 arm64 与 amd64 的 CGO 工具链**。在 Apple Silicon 的 `macos-latest`（macos-14/15）runner 上原生满足；不要尝试从 Linux 交叉编译 darwin（CGO + macOS SDK 缺失，社区反复确认不可行）。
+  - 当前只构建 arm64；不要尝试从 Linux 交叉编译 darwin（CGO + macOS SDK 缺失，
+    社区反复确认不可行）。
  - `wails build` 本身**不签名、不公证 macOS 产物**（与 Windows 的 `-nsis` 不同，没有内建签名参数）。签名／公证完全是构建后的独立步骤。
  - Wails 没有内建 DMG 封装，需自己做（见 1.4）。

@@ -563,7 +573,22 @@ xcrun stapler staple "YourApp.dmg"

 #### 1.6 Wails 对 darwin 签名的内建支持（已确定）

-`wails build -platform darwin/universal` **无签名参数**，不做 codesign／notarize；签名、公证、DMG 全是构建后的外部步骤。`build/darwin/` 下有 `Info.plist`／`Info.dev.plist`；`entitlements.plist` 非自动生成，需手动放进该路径。universal 由 Wails 内部 `lipo` 合并，无需手动 `lipo`。
+`wails build -platform darwin/arm64` **无签名参数**，不做 codesign／notarize；签名、
+公证、DMG 全是构建后的外部步骤。`build/darwin/` 下有 `Info.plist`／`Info.dev.plist`；
+`entitlements.plist` 非自动生成，需手动放进该路径。
+
+#### 1.7 本项目已验证的正式 recipe（2026-07-31）
+
+仓库根目录的 `just desktop-dist-mac` 已把上述外部步骤固化：ARM64 构建 → 复用既有
+Developer ID Application 身份签名 → `ditto` ZIP 公证 → app staple → 生成 DMG → DMG 签名与
+单独公证 → DMG staple → Gatekeeper 评估。DMG 由 `desktop/scripts/make-dmg.sh` 使用纯系统工具
+创建，内容只有 `Commilitia Drop.app` 和 `/Applications` 链接，不依赖 `create-dmg`。
+
+本次实测 app submission `0e2c80e1-e40d-4108-951e-64c810bd118e`、DMG submission
+`7a6aea7a-6c40-4bdb-96e3-46e6f8fbc813` 均为 `Accepted`；两者 staple／validate 成功，
+`spctl` 返回 `Notarized Developer ID`。这证明 Wails 应用本身满足 Apple 公证要求；后续发布应
+复用 recipe，不再使用 ad-hoc 签名或未公证 `.app` 作为正式分发物。面向操作者的完整流程见
+`docs/client-build-install.md`。

 ### 2. Windows

@@ -596,7 +621,7 @@ signtool sign /fd sha256 /tr http://ts.ssl.com /td sha256 /f certificate.pfx /p
 ```yaml
 jobs:
  macos:
-    runs-on: macos-latest          # Apple Silicon，原生支持 universal CGO
+    runs-on: macos-latest          # Apple Silicon arm64
    steps:
      - uses: actions/checkout@v4
        with: { submodules: recursive }   # cjk-autospace 等 submodule
@@ -605,7 +630,7 @@ jobs:
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: go install github.com/wailsapp/wails/v2/cmd/wails@v2.12.0
-      - run: wails build -platform darwin/universal -clean
+      - run: wails build -platform darwin/arm64 -clean
      - uses: apple-actions/import-codesign-certs@v7
        with:
          p12-file-base64: ${{ secrets.APPLE_CERT_P12_BASE64 }}
@@ -685,7 +710,7 @@ jobs:
 - Wails Mac App Store 指南（entitlements/codesign --options=runtime、build/darwin 路径）：https://wails.io/docs/guides/mac-appstore/
 - Wails NSIS installer 指南（build/windows/installer、-nsis）：https://wails.io/docs/guides/windows-installer/
 - Wails NSIS 不签主 exe 的 issue #3716：https://github.com/wailsapp/wails/issues/3716
- Wails Crossplatform build（GitHub Actions、darwin/universal 矩阵）：https://wails.io/docs/guides/crossplatform-build/
+- Wails Crossplatform build（GitHub Actions）：https://wails.io/docs/guides/crossplatform-build/
 - notarytool man page：https://keith.github.io/xcode-man-pages/notarytool.1.html
 - Apple TN3147 迁移到新公证工具：https://developer.apple.com/documentation/technotes/tn3147-migrating-to-the-latest-notarization-tool
 - Apple Disable Library Validation entitlement：https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_cs_disable-library-validation