Private Agents Node Installer：多平台AI代理桌面服务的自动化构建方案

Private Agents Node Installer是一个可复用的GitHub Actions工作流，为Private Agents Node桌面服务构建签名的多平台安装包（.pkg/.msi/.deb）。作为Node Python服务的单一可信源，它被多个产品仓库复用，实现了AI代理桌面应用的自动化构建与分发。

在AI代理技术快速发展的今天，越来越多的企业开始将AI能力下沉到桌面端，为用户提供本地化的智能助手服务。Private Agents Node正是这样一个桌面级AI代理服务，它允许用户在本地环境中运行AI代理，处理敏感数据而无需上传到云端。然而，将这样的Python服务打包成用户友好的桌面应用并分发到不同操作系统平台，是一个充满挑战的工程问题。

Private Agents Node Installer项目正是为了解决这一痛点而生。它提供了一套完整的自动化构建方案，通过GitHub Actions工作流，将Python服务打包成Windows（.msi）、macOS（.pkg）和Linux（.deb）三大主流平台的安装包，并进行代码签名，确保用户能够安全、便捷地安装和使用。

项目采用了"单一可信源"（Single Source of Truth）的设计哲学。这意味着Private Agents Node的核心Python服务代码只维护在一个中心仓库中，而各个产品仓库通过引用这个共享的GitHub Actions工作流来获取构建能力，而不是各自维护独立的构建脚本。

这种设计带来了多重优势：

一致性保证：所有产品使用相同的构建流程，确保输出质量和行为的一致性

集中维护：构建逻辑的更新只需修改一处，所有依赖方自动受益

版本控制：通过GitHub Actions的版本引用机制，产品仓库可以选择使用特定版本的构建流程

安全合规：代码签名证书和密钥集中管理，降低泄露风险

项目实现了灵活的工作流复用模式：

# 产品仓库的工作流配置示例
jobs:
  build:
    uses: devwspito/private-agents-node-installer/.github/workflows/build.yml@main
    with:
      service_version: ${{ github.ref_name }}
      signing_enabled: true
    secrets:
      signing_certificate: ${{ secrets.CODE_SIGNING_CERT }}

这种声明式的复用方式让产品团队无需了解复杂的构建细节，只需配置少量参数即可获得专业的构建能力。

GitHub Actions工作流采用了矩阵策略（Matrix Strategy）来并行构建多个平台的安装包：

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    include:
      - os: ubuntu-latest
        target: deb
        arch: [x64, arm64]
      - os: windows-latest
        target: msi
        arch: [x64, arm64]
      - os: macos-latest
        target: pkg
        arch: [x64, arm64]

这种配置充分利用了GitHub Actions的并行执行能力，大幅缩短了多平台构建的总时间。

PyInstaller深度集成

工作流使用PyInstaller将Python服务及其依赖打包成独立的可执行文件：

• 依赖分析：自动分析requirements.txt，确保所有依赖都被正确包含
• 资源打包：将配置文件、静态资源等一并打包
• 单文件模式：可选的单文件（--onefile）模式，简化分发
• 隐藏导入：处理动态导入的模块，避免运行时错误

平台特定优化

Windows (.msi)

• 使用WiX Toolset创建专业的Windows Installer包
• 支持UAC权限提升，确保服务能够安装系统级组件
• 集成Windows服务注册，实现开机自启动
• 支持增量更新和回滚机制

macOS (.pkg)

• 使用pkgbuild构建符合Apple标准的安装包
• 支持Notarization流程，确保在macOS Gatekeeper下正常运行
• 集成LaunchAgent/LaunchDaemon，实现后台服务管理
• 遵循macOS应用沙盒规范

Linux (.deb)

• 使用dpkg-deb构建Debian系发行版安装包
• 自动生成systemd服务单元文件
• 支持依赖声明，自动安装Python运行时
• 遵循Filesystem Hierarchy Standard (FHS)

代码签名是桌面软件分发的关键环节，项目实现了完整的签名流程：

证书管理

• 硬件安全模块（HSM）：签名密钥存储在符合FIPS 140-2标准的HSM中
• 密钥轮换：定期轮换签名证书，降低密钥泄露风险
• 访问审计：详细的签名操作日志，支持合规审计

签名流程

Windows代码签名

• 使用signtool.exe进行Authenticode签名
• 支持SHA-256算法，符合现代安全标准
• 时间戳服务集成，确保证书过期后签名仍然有效

macOS代码签名

• 使用codesign进行Apple Developer ID签名
• 支持公证（Notarization）流程
• staple操作，确保离线环境下也能验证签名

Linux包签名

• 使用GPG进行DEB包签名
• 支持APT仓库的签名验证
• 提供公钥分发机制

工作流实现了完整的构建产物生命周期管理：

版本控制

• 自动从Git标签提取版本号
• 支持语义化版本（SemVer）规范
• 构建元数据注入，包含Git commit hash和构建时间

产物分发

• GitHub Releases：自动创建Release并上传安装包
• 预签名URL：生成有时间限制的下载链接
• 校验和生成：提供SHA-256校验和，供用户验证下载完整性

保留策略

• 自动清理过期的构建产物
• 保留关键版本的长期备份
• 支持手动标记保留特定构建