macOS 与 Linux 打包指南

本文定位:《对外发布操作手册》已覆盖 Windows(代码签名 OV/EV、HTTPS、ICP 备案), deploy/build_sign_runbook.md 覆盖了 Windows 单文件 exe 构建。 macOS 与 Linux 此前完全空白 —— 本文补上这两块。 ⚠️ 诚实标注:本文及配套脚本是待实操验证的模板,不是验证过的 runbook。 项目当前在 Windows 上开发,无法交叉验证 macOS/Linux 构建。 所有命令首次在目标平台上执行时,请逐条确认;验证通过后请回填文末验收清单。 产物与脚本: - deploy/macos/build-and-notarize.sh —— macOS 构建 → 签名 → 公证 → 装订 - deploy/macos/com.trueagt.agent.plist —— launchd 守护进程配置 - deploy/linux/build-appimage.sh —— Linux AppImage 构建 + GPG 签名 - deploy/linux/trueagt.desktop、deploy/linux/trueagt.appdata.xml 双版本(EDITION):两个脚本均支持 EDITION=personal(个人版,默认)或 EDITION=enterprise(企业版), 内部统一走 python3 build_pack/build.py --edition ...,由它写入不可变 EDITION 常量与 build_info.json; 切勿绕过 build.py 直接调 PyInstaller,否则产出的包没有版本标记(企业版也就不会强制授权校验)。 产物名会带版本标记,例如 TrueAGT-0.9.243-personal-x86_64.AppImage、TrueAGT-0.9.243-enterprise-arm64.dmg。 ⚠️ 从 Windows 工作树直接拷贝(scp / zip)脚本到 Linux / macOS 前,务必确认换行是 LF: 本机 core.autocrlf=true,工作树里是 CRLF(只有 git 检出到 Linux/macOS 才会还原成 LF)。 CRLF 的 shell 脚本会以 bad interpreter: /usr/bin/env bash\r 直接失败。 静态可验证部分(plist 可解析、AppStream 良构、桌面文件必需键、脚本 bash 语法、签名顺序等) 在 0.9.243 由人工逐项核验通过;文中早期提到的 validate_packaging.py 并未随仓库提供, 如需让这些校验可重复执行,应补一个校验脚本并接入 precommit。

一、通用前置

1.1 架构矩阵(每个组合都要实测冒烟,不是「打包出来就行」)

平台架构产物签名 / 公证
Windowsx64单文件 exe代码签名(OV/EV)✅ 已有手册
macOSarm64(Apple Silicon).app → .dmgDeveloper ID 签名 + 公证
macOSx86_64(Intel).app → .dmg同上
Linuxx86_64AppImage(或 .deb / .rpm)GPG 签名(建议)
Linuxaarch64(视需求)同上同上

1.2 ⚠️ 两条最容易翻车的铁律

① macOS:PyInstaller 不支持跨架构打包。

arm64 机器上只能产出 arm64 产物。要覆盖 Intel Mac,必须:

不要指望一次构建产出通用二进制。

② Linux:glibc 只向后兼容。

在 Ubuntu 24.04 上构建的产物跑不了 Ubuntu 20.04。 必须在最老的受支持发行版上构建(推荐 Ubuntu 20.04 LTS 容器),才能覆盖 20.04 及之后的所有版本。

1.3 版本号

打包前确认 __init__.py 中的 __version__ 已更新 (唯一来源;test_smoke.py §43 会把关 CHANGELOG / pyproject / MCP 版本是否一致)。

1.4 数据目录(三平台不同,且影响卸载残留)

平台数据目录服务形态
Windows%APPDATA%\TrueAGT 或安装目录旁Windows 服务(deploy/install_service.bat)
macOS~/Library/Application Support/TrueAGTlaunchd(deploy/macos/com.trueagt.agent.plist)
Linux~/.local/share/trueagt(服务形态用 /var/lib/trueagt)systemd(deploy/trueagt.service)

卸载不得残留密钥与用户数据 —— 用户会据此判断你是否真的「数据不出厂」。


二、macOS 全流程

2.1 前置

  1. Apple Developer 账号(年费,以官网当前价格为准)
  2. Developer ID Application 证书已装入登录钥匙串
  3. 建立 notarytool 钥匙串 profile(用 app 专用密码,不要用 Apple ID 主密码):
xcrun notarytool store-credentials "trueagt-notary" \
    --apple-id "<AppleID>" --team-id "<TeamID>" --password "<app专用密码>"

2.2 执行

export SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"
export NOTARY_PROFILE="trueagt-notary"
export EDITION="personal"          # 或 enterprise(企业版)
./deploy/macos/build-and-notarize.sh

脚本依次完成:构建 → 自内向外签名 → 打 dmg → 公证 → 装订票据 → 自检。

2.3 四个关键点(错了会浪费数小时)

点说明
签名顺序必须自内向外先签 .dylib / .framework,最后签 .app。外层签名后再改内部文件会破坏封印,签名失效
必须开 hardened runtime--options runtime。不开,公证会被直接驳回
必须 stapler 装订公证票据要装订进 dmg,否则用户在离线环境首次打开会失败
服务形态不要跑 root见 plist 中的 UserName / GroupName;需提前创建 _trueagt 用户

2.4 Gatekeeper 与隔离属性

从互联网下载的应用会被打上 com.apple.quarantine 属性。 未公证时用户需右键 → 打开才能绕过 —— 对企业交付体验极差,这正是公证不可省的原因。

公证后可用以下命令验证(但本机结果偏乐观,见验收清单):

spctl -a -vv -t open --context context:primary-signature TrueAGT-x.y.z-arm64.dmg

三、Linux 全流程

3.1 产物选型

形态优点适用
AppImage单文件、免安装、跨发行版推荐默认:内网分发最简单
.deb / .rpm与系统包管理集成、便于集中运维客户有统一运维体系时

3.2 执行

# 务必在最老的受支持发行版上构建(见 §1.2 ②)
export GPG_KEY_ID="<你的签名密钥>"
export EDITION="personal"          # 或 enterprise(企业版)
./deploy/linux/build-appimage.sh

产出 dist/TrueAGT-<版本>-<版本标记>-<架构>.AppImage,并生成 .asc 签名与 .sha256 校验值。 (可执行名是 TrueAGT,与 Windows 的 TrueAGT.exe 一致;Linux 大小写敏感, desktop 的 Exec 与 AppStream 的 <binary> 已同步为 TrueAGT。)

3.3 两个易错点

不一致会导致软件中心匹配不上应用。此项已由校验脚本断言。

—— 脚本在 GPG_KEY_ID 未设置时会明确告警而不是静默跳过。


四、更新包签名(三平台通用,高危项)

项目已有 update 配置(url / mode / check_interval_hours / serve_dir)。

⚠️ 更新通道如果不做签名校验,就是一条远程代码执行路径。

发布更新包时,都必须:

  1. 对更新包签名(macOS 用 Developer ID、Windows 用代码签名证书、Linux 用 GPG)
  2. 客户端在应用更新前校验签名,校验失败即拒绝安装并告警
  3. 传输走 HTTPS,且不要因为「内网部署」就跳过校验 —— 内网同样可能被投毒

五、验收清单

5.1 已静态验证(本机可完成,全部通过)

5.2 必须在目标平台上人工验证(当前未做)

(⚠️ 本机的公证缓存会让 spctl 结果偏乐观,不能只信本机校验)


六、当前未验证项(诚实列出)

以下尚未在本项目实际执行过,属于「照官方流程编写、待首次实操确认」:

首次实操后请把结论回填本文,并删除本节的对应条目。


七、相关文档

文档内容
《对外发布操作手册》Windows 代码签名、授权码签发、HTTPS、ICP 备案
deploy/build_sign_runbook.mdWindows 单文件 exe 构建与签名操作步骤
《许可与分发策略》许可与分发方式的取舍、三平台发布要求的总览
docs/部署指南.md发布包部署、Docker、systemd、HTTPS、监控告警
本文档随 TrueAGT 安装包一同发布;如与软件实际行为不一致,以软件当前版本为准。