2. Agent安装包获取与版本选择

Agent的部署起点是获取正确且完整的安装包。本章从官方仓库地址定位、校验和验证、版本号命名惯例以及稳定版与测试版的区分四个维度，建立安装包获取阶段的配置边界管理规范。

2.1 官方仓库地址与发布渠道

所有公开发布的Agent安装包均托管于以下官方渠道，禁止使用第三方分流或非签名镜像：

2.2 校验和验证流程

每次下载后必须执行两步校验：哈希校验与签名校验。以下为标准的自动化验证脚本片段：

# 下载安装包及校验文件
wget https://downloads.example.com/agent/v1.2.3/agent-linux-amd64.tar.gz
wget https://downloads.example.com/agent/v1.2.3/agent-linux-amd64.tar.gz.sha256
wget https://downloads.example.com/agent/v1.2.3/agent-linux-amd64.tar.gz.asc

# 1. SHA-256 哈希校验
sha256sum --check agent-linux-amd64.tar.gz.sha256

# 2. GPG 签名校验（需提前导入官方公钥）
gpg --verify agent-linux-amd64.tar.gz.asc agent-linux-amd64.tar.gz

2.3 版本号命名规则

Agent遵循语义化版本 2.0.0（SemVer），并扩展了预发布标签用于区分稳定版与测试版。各段含义及边界判断方法如下：

2.4 稳定版与测试版区分策略

在自动化部署清单中，通过版本号字段和附加标签严格隔离两类版本。以下为常用区分模式：

• 稳定版（Stable）：格式 x.y.z 无预发布后缀，经过完整回归测试，部署在 stable 仓库源。
• 测试版（Beta/RC）：格式 x.y.z-beta.N 或 x.y.z-rc.N，仅允许在非生产环境（staging、dev）使用，且需在部署配置中显式声明 allow_prerelease: true。
• LTS（长期支持）：在稳定版基础上标记 -lts 后缀（如 3.2.1-lts），享受额外安全补丁周期。

2.5 安装包获取与验证决策流程

下图概括了从版本选择到校验通过的完整操作路径：

2.6 常见错误与调试清单

1. 哈希不匹配：检查下载是否被中间人篡改或文件截断，用 curl -C - 断点续传后重新校验。
2. GPG 签名使用过期的公钥：执行 gpg --refresh-keys 或手动导入最新 KEYS 文件。
3. 版本号排序混淆：使用 semver compare 工具（如 node -e "console.log(require('semver').gt('3.2.1-rc.1','3.2.0'))"）避免人工判断预发布标签优先级。
4. 仓库URL拼写错误：在部署脚本中硬编码 AGENT_REPO="https://downloads.example.com/agent"，避免shell环境变量陷阱。