AGIOne 安装前环境预检指南
前言
| 项目 | 内容 |
|---|---|
| 适用角色 | 安装前检查人员、交付工程师、客户运维工程师 |
| 导航路径 | 部署 > AGIOne 安装前环境预检 |
| 功能定位 | 在执行 ./agione quick 或 ./agione install 前，识别资源、端口、权限、Docker、SSH、离线包和中间件连通性风险 |
预检不会安装产品。它的目标是在正式安装前暴露阻塞项。第一次执行时记住基本顺序：先跑 doctor，修复 FAIL，再决定如何处理 WARN。
新手理解
预检是安装前的彩排，不会解包运行数据。它会告诉你主机、端口、SSH、磁盘、Docker、离线包和托管中间件是否已经准备好。
预检时间线
| 阶段 | 你要做什么 | 完成标志 |
|---|---|---|
| 第 1 步：准备交付包 | 进入交付包目录并给 ./agione 授权 | ./agione help 可以执行 |
| 第 2 步：执行 doctor | 单节点执行 ./agione doctor，多节点执行 ./agione doctor --file /root/agione-install.yml | 终端输出预检结论 |
| 第 3 步：校验交付包 | 执行 ./agione verify-bundle | split bundle 的 SHA-256 完整性校验通过 |
| 第 4 步：修复 FAIL | 修复磁盘、端口、权限、SSH、中间件等阻塞项 | 不再存在 FAIL 项 |
| 第 5 步：确认 WARN | 和客户、交付负责人确认风险是否接受 | 每个 WARN 都有处理决策 |
| 第 6 步：执行安装 | 使用同一份配置执行 quick 或 TUI 安装 | 预检报告已归档 |
术语速查
| 术语 | 说明 |
|---|---|
doctor | 安装前诊断命令，用于检查主机和配置风险 |
verify-bundle | 按 SHA256SUMS 校验 split bundle 文件完整性的命令 |
| MD5 / SHA-256 | MD5 用于发现下载损坏；SHA-256 用于核对外层压缩包和解压后的 split bundle 内容 |
PASS | 检查通过，可继续 |
WARN | 存在风险但不一定阻塞，需要负责人确认 |
FAIL | 阻塞项，必须修复后才能安装 |
| 端口占用 | 目标端口已被其他进程监听，安装器无法绑定 |
| host-mode 远端检查 | 多节点场景下对每台目标机器执行 SSH、资源、端口和历史数据检查 |
| 外部托管中间件检查 | 对云厂商或客户已有数据库、Redis、Nacos、Kafka、对象存储执行连通性和凭据检查 |
本文档说明执行 ./agione quick 或 ./agione install 前应完成的环境检查。当前预检范围聚焦 agione-app 安装：主机资源、运行目录、Docker 与 Compose、SSH 访问、端口、离线资源以及中间件连通性。
预检目标是在安装流程开始前发现阻塞问题。
1. 适用场景
| 场景 | 是否建议预检 | 说明 |
|---|---|---|
| 单节点安装 | 是 | 安装前确认 CPU、内存、磁盘、端口、Docker、Compose 和基础命令 |
| host-mode 多节点安装 | 是 | 检查 SSH 访问、私网节点地址、远端资源、远端命令、Docker 状态和必要端口 |
| 离线或弱网交付 | 是 | 确认发布包、离线镜像、离线 Python 和运行目录可用 |
| 已有历史环境重装 | 是 | 确认旧数据、旧容器、旧端口和旧目录是否会影响安装 |
| 外部托管中间件 | 是 | 安装前确认连接地址、凭据和访问策略 |
2. 推荐命令
正式安装前执行 doctor：
cd /opt/hyperone/agione-release-v1.0-XXX
chmod +x ./agione
./agione doctor传输完成后校验发布包：
./agione verify-bundle该命令按 SHA256SUMS 校验 split bundle 文件的 SHA-256 摘要。下载页 MD5 只能检查传输损坏，不能替代 verify-bundle；正式生产交付还应通过受控渠道独立获取并核对外层 .tar.gz 的 SHA-256。不要在正式交付中设置 AGIONE_SKIP_BUNDLE_VERIFY=1。
host-mode 多节点安装时，预检应使用与正式安装一致的配置文件：
./agione doctor --file /root/agione-install.yml3. 检查结果级别
| 结果 | 含义 | 处理建议 |
|---|---|---|
PASS | 满足安装要求 | 可进入安装流程 |
WARN | 存在风险但不一定阻塞 | 需交付负责人和客户负责人确认是否接受 |
FAIL | 不满足关键前置条件 | 暂停安装，完成整改后重新检查 |
4. 检查项总览
| 类别 | 阻塞级别 | 说明 |
|---|---|---|
| 操作系统与权限 | 高 | 确认 Linux 发行版、root 或等效权限、基础命令可用 |
| CPU 与内存 | 高 | 确认主机满足所选部署模式 |
| 磁盘空间 | 高 | 默认 runtime_root 时，安装器优先选择合适的数据盘，必要时才回落到系统盘 /opt/hyperone；约 160 GiB 以上可通过 |
| 运行目录 | 高 | 确认最终选择的运行根目录可创建、可写入，重装时可按要求清理 |
| 端口占用 | 高 | 确认必要端口未被非受控进程占用 |
| Docker 与 Compose | 高 | 已安装则检查版本与状态；缺失时确认可通过离线资源安装 |
| SSH 访问 | host-mode 场景为高 | 确认发起安装的主机可访问所有 host-mode 节点 |
| host-mode 节点地址 | 高 | 确认运行节点地址均为私网 IPv4 地址 |
| 离线资源包 | 高 | 确认发布包校验值与离线资源可用 |
| 外部托管中间件 | 选中时为高 | 确认连接地址、用户名、密码、协议和网络策略 |
5. 资源检查
重点检查 /opt/hyperone 所在分区。
df -h /opt/hyperone 2>/dev/null || df -h /opt
df -ih /opt/hyperone 2>/dev/null || df -ih /opt
mkdir -p /opt/hyperone
touch /opt/hyperone/.agione-precheck-write-test
rm -f /opt/hyperone/.agione-precheck-write-test| 检查项 | 通过标准 | 处理建议 |
|---|---|---|
| 可用空间 | 推荐 200 GiB，最低约 160 GiB 以上 | 低于阈值时扩容或更换运行目录 |
| 写权限 | root 或等效权限可写入 /opt/hyperone | 修复目录权限或使用具备权限的账号 |
| inode | inode 使用率未接近 100% | 清理小文件或调整文件系统 |
| 历史数据 | 已确认是否保留、备份或清理 | 重装前必须完成数据确认 |
6. 端口检查
6.1 关键端口
| 端口 | 用途 | 预检重点 |
|---|---|---|
22/TCP | SSH 运维 | 运维端可登录目标主机 |
18090/TCP | AGIOne Web 入口 | 未被占用，客户端可访问 |
80/TCP | Nginx / OpenResty 入口 | 未被非受控进程占用 |
443/TCP | HTTPS 入口，可选 | 如启用 HTTPS，需提前规划 |
8089/TCP | 作业访问代理 | 未被非受控进程占用 |
3306/TCP | MariaDB | 未被旧数据库或其他服务占用 |
6379/TCP | Redis | 未被旧 Redis 或其他服务占用 |
8848/8849/TCP | Nacos | 未被旧 Nacos 或其他服务占用 |
9848/9849/TCP | Nacos 内部通信 | 未被旧 Nacos 或其他服务占用 |
9000/9001/TCP | MinIO API 与控制台 | 未被旧 MinIO 或其他服务占用 |
9092/9093/TCP | Kafka broker / controller | 未被旧 Kafka 或其他服务占用 |
18091/TCP | Kafka UI | 自建 Kafka UI 启用时未被占用 |
8021/8022/18088/TCP | KUBEM / CodeLab / IAM | 启用 kubem 服务组时检查 |
8011/8017/8012/8001/8002/TCP | 云厂商集成服务 | 启用 cloud 服务组时检查 |
7091/18181/18082/TCP | ISync / InfluxDB | 启用 core_isync 服务组时检查 |
6.2 推荐检查命令
ss -lntup | grep -E ':(22|80|443|3306|6379|8089|8848|8849|9000|9001|9092|9093|9848|9849|18090|18091|8021|8022|18088|8011|8017|8012|8001|8002|7091|18181|18082)\b'
lsof -iTCP -sTCP:LISTEN -P -n | grep -E ':(22|80|443|3306|6379|8089|8848|8849|9000|9001|9092|9093|9848|9849|18090|18091|8021|8022|18088|8011|8017|8012|8001|8002|7091|18181|18082)\b'
nc -vz <target-host-ip> 18090
nc -vz <target-host-ip> 227. host-mode 远端检查
host-mode 多节点安装时，需要检查 agione-install.yml 中定义的每台节点。
| 检查项 | 通过标准 | 失败表现 |
|---|---|---|
| SSH 连通性 | 可通过配置的用户和端口连接目标节点 | 认证失败或连接超时 |
| 私网 IPv4 地址 | 节点地址为 RFC1918 私网 IPv4 地址 | 使用公网 IP、公网域名或占位主机名 |
| 远端命令 | bash、tar、Python 可用，或可通过内置资源修复 | 必要命令缺失且无法修复 |
| SHA-256 工具 | 每个目标节点至少有 sha256sum 或 shasum | 任一节点缺少两个命令，bundle 同步前即停止 |
| 远端资源 | CPU、内存和最终选择的安装磁盘满足所选角色 | 节点资源低于阈值 |
| 已有数据 | 旧运行数据不存在；或已备份并通过 quick --force-overwrite 发起受控重装 | 存在旧运行数据但没有备份、清理决定或安全预检授权 |
| Docker 状态 | Docker 与 Compose 正常，或可通过离线资源安装 | Docker 修复失败 |
| 端口 | 节点需要绑定的端口均未被占用 | 已有进程占用必要端口 |
8. 外部托管中间件检查
当 agione-install.yml 选择外部托管中间件时，安装前需确认连通性。
注意：本节预检只验证网络、凭据和必要操作权限，不验证产品实现是否兼容。只有 部署综述中的云中间件兼容矩阵 列出的云厂商、产品、版本和接入方式受支持；未列出的组合即使全部检查为
PASS，仍按不支持处理。
| 组件 | 必要检查 |
|---|---|
| 数据库 | 地址、端口、root 用户、root 密码、SSL 模式、初始化库表权限 |
| Redis | 地址、端口、密码、网络策略 |
| Nacos | 地址、API 端口、命名空间、用户名、密码、健康接口 |
| Kafka | bootstrap servers、协议、认证配置、topic 创建权限 |
| 对象存储 | endpoint、access key、secret key、bucket 访问、上传和下载权限 |
托管 Kafka 需要同时确认 metadata 可用性和 Topic 策略。应用节点必须能访问 Kafka 返回的 advertised broker 地址；只让 bootstrap 端口连通不一定够。如果 agione_app.kafka.auto_create_topics 为 true，预检会按 broker 已开启自动建 Topic 处理；如果为 false，预检会检查 AGIOne 必需 Topic 是否存在。需要安装器创建缺失 Topic 时，账号必须有 Topic 管理权限，并在安装前设置 AGIONE_MANAGED_KAFKA_CREATE_TOPICS=1。
9. 报告输出建议
预检或 doctor 报告建议至少包含：
| 模块 | 输出内容 |
|---|---|
| 主机信息 | hostname、IP、操作系统、内核、CPU 架构 |
| 资源信息 | CPU 核数、内存、磁盘、inode、运行目录权限 |
| 端口 | 端口占用进程、监听地址、冲突端口列表 |
| Docker / Compose | 版本、服务状态、是否可用离线安装 |
| host-mode 节点 | SSH 结果、私网地址校验、远端资源、远端命令、旧数据、Docker 和端口 |
| 离线包 | SHA256SUMS 校验结果、bundle manifest、镜像包、离线 Python |
| 外部中间件 | 连接地址可达性与凭据校验结果 |
| 结论 | PASS / WARN / FAIL、阻塞项、整改建议 |
10. 安装准入建议
满足以下条件后再进入正式安装：
./agione doctor或预检脚本执行完成，并已归档报告。- CPU、内存、磁盘、端口、权限、Docker 等基础项均为
PASS。 - 配置 host-mode 节点时，远端预检结果为
PASS。 - 选择外部托管中间件时，中间件连通性检查为
PASS。 - 所有
FAIL项已整改并复检通过。 - 所有
WARN项已由交付负责人和客户负责人确认接受。 - 离线交付场景已执行
./agione verify-bundle，split bundle 的 SHA-256 校验通过；正式生产交付另已核对外层压缩包 SHA-256。
11. 与安装流程的关系
推荐执行顺序：
cd /opt/hyperone/agione-release-v1.0-XXX
chmod +x ./agione
./agione doctor --file /root/agione-install.yml
./agione verify-bundle
./agione quick --file /root/agione-install.yml
./agione health
./agione psdoctor 用于提前发现风险，不能替代安装过程中的系统检查。正式安装时，quick 仍会再次执行安装检查，并在检查通过后继续解包、配置、加载镜像和启动服务。