本文定位:《对外发布操作手册》已覆盖 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。
| 平台 | 架构 | 产物 | 签名 / 公证 |
|---|---|---|---|
| Windows | x64 | 单文件 exe | 代码签名(OV/EV)✅ 已有手册 |
| macOS | arm64(Apple Silicon) | .app → .dmg | Developer ID 签名 + 公证 |
| macOS | x86_64(Intel) | .app → .dmg | 同上 |
| Linux | x86_64 | AppImage(或 .deb / .rpm) | GPG 签名(建议) |
| Linux | aarch64(视需求) | 同上 | 同上 |
① macOS:PyInstaller 不支持跨架构打包。
arm64 机器上只能产出 arm64 产物。要覆盖 Intel Mac,必须:
不要指望一次构建产出通用二进制。
② Linux:glibc 只向后兼容。
在 Ubuntu 24.04 上构建的产物跑不了 Ubuntu 20.04。 必须在最老的受支持发行版上构建(推荐 Ubuntu 20.04 LTS 容器),才能覆盖 20.04 及之后的所有版本。
打包前确认 __init__.py 中的 __version__ 已更新 (唯一来源;test_smoke.py §43 会把关 CHANGELOG / pyproject / MCP 版本是否一致)。
| 平台 | 数据目录 | 服务形态 |
|---|---|---|
| Windows | %APPDATA%\TrueAGT 或安装目录旁 | Windows 服务(deploy/install_service.bat) |
| macOS | ~/Library/Application Support/TrueAGT | launchd(deploy/macos/com.trueagt.agent.plist) |
| Linux | ~/.local/share/trueagt(服务形态用 /var/lib/trueagt) | systemd(deploy/trueagt.service) |
卸载不得残留密钥与用户数据 —— 用户会据此判断你是否真的「数据不出厂」。
xcrun notarytool store-credentials "trueagt-notary" \
--apple-id "<AppleID>" --team-id "<TeamID>" --password "<app专用密码>"
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 → 公证 → 装订票据 → 自检。
| 点 | 说明 |
|---|---|
| 签名顺序必须自内向外 | 先签 .dylib / .framework,最后签 .app。外层签名后再改内部文件会破坏封印,签名失效 |
| 必须开 hardened runtime | --options runtime。不开,公证会被直接驳回 |
| 必须 stapler 装订 | 公证票据要装订进 dmg,否则用户在离线环境首次打开会失败 |
| 服务形态不要跑 root | 见 plist 中的 UserName / GroupName;需提前创建 _trueagt 用户 |
从互联网下载的应用会被打上 com.apple.quarantine 属性。 未公证时用户需右键 → 打开才能绕过 —— 对企业交付体验极差,这正是公证不可省的原因。
公证后可用以下命令验证(但本机结果偏乐观,见验收清单):
spctl -a -vv -t open --context context:primary-signature TrueAGT-x.y.z-arm64.dmg
| 形态 | 优点 | 适用 |
|---|---|---|
| AppImage | 单文件、免安装、跨发行版 | 推荐默认:内网分发最简单 |
.deb / .rpm | 与系统包管理集成、便于集中运维 | 客户有统一运维体系时 |
# 务必在最老的受支持发行版上构建(见 §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。)
<id> 一致(com.trueagt.agent.desktop)。不一致会导致软件中心匹配不上应用。此项已由校验脚本断言。
—— 脚本在 GPG_KEY_ID 未设置时会明确告警而不是静默跳过。
项目已有 update 配置(url / mode / check_interval_hours / serve_dir)。
⚠️ 更新通道如果不做签名校验,就是一条远程代码执行路径。
发布更新包时,都必须:
<id> 与桌面文件名一致.desktop 文件满足 Desktop Entry 规范必需键bash -n 语法通过、启用 set -euo pipefailnotarytool 公证实际通过(首次常被驳回,需看日志)(⚠️ 本机的公证缓存会让 spctl 结果偏乐观,不能只信本机校验)
ldd 确认不缺共享库以下尚未在本项目实际执行过,属于「照官方流程编写、待首次实操确认」:
notarytool / codesign / stapler 的具体参数在当前 Xcode 版本下的行为.app 时的目录结构(脚本中 cp 的目标路径需按实际产物调整)trueagt.spec 在非 Windows 平台下是否需要平台相关调整首次实操后请把结论回填本文,并删除本节的对应条目。
| 文档 | 内容 |
|---|---|
| 《对外发布操作手册》 | Windows 代码签名、授权码签发、HTTPS、ICP 备案 |
deploy/build_sign_runbook.md | Windows 单文件 exe 构建与签名操作步骤 |
| 《许可与分发策略》 | 许可与分发方式的取舍、三平台发布要求的总览 |
docs/部署指南.md | 发布包部署、Docker、systemd、HTTPS、监控告警 |