OpenFlare/docs/plan/20260606-interactive-installer.md

交互式智能安装脚本实现计划

本计划旨在拓展 OpenFlare Agent 安装脚本的功能，支持交互式选择本地安装或 Docker 容器安装，并提供智能检测/在线安装 Docker 环境的机制，同时保留通过命令行传参进行自动化安装的既有能力。

---

1. 目标与背景 (Goal & Context)

• 需求背景：当前安装脚本 install-agent.sh 仅支持在宿主机直接下载二进制并配置为本地 systemd 服务运行。随着 Docker 部署方式的普及，需要让用户在一键安装时能根据需要交互式选择 Docker 或本地部署，从而提升部署体验。
• 开发范围 (Scope)：
  • 支持交互式运行（未传参时）：提示用户选择 Local 方式或 Docker 方式。
  • 当选择 Docker 方式时，检测本地是否存在 docker 命令。若不存在，提示并在线安装 Docker（支持国内镜像源及自动测速选择最低延迟源）。
  • 交互引导用户配置 server_url 和 agent-token 或 discovery-token。
  • 如果选择 Docker，则最终拉取 Agent 镜像并运行容器；如果选择 Local，则继续原有的本地二进制下载及配置发布逻辑。
  • 兼容非交互式模式：如果执行脚本时传递了任意参数，则跳过任何交互式提示，直接进行自动化安装（支持新参数 --docker / --method docker 来自动选用 Docker 部署）。

---

2. 设计与决策 (Design & Decisions)

交互工作流

1. 检查 $#（参数数量）。若 $# -eq 0，激活 INTERACTIVE=true。
2. 在交互模式下：
   • 引导用户选择安装方法（1: Local, 2: Docker）。
   • 若选择 Docker，调用 Install_Docker 检测并安装环境。
   • 引导用户输入 SERVER_URL 并进行非空校验。
   • 引导用户选择 Token 类型（1: Discovery Token, 2: Agent Token），并输入对应的 Token 值。
   • 若选择 Local 且未传 --openresty-path，如果 openresty 二进制未能在 $PATH 中找到，交互提示用户手动输入 OpenResty 路径。
3. 非交互模式下：
   • 解析命令行参数。
   • 支持通过 --docker 或 --method docker 指定 Docker 容器安装。
   • 依然根据传入的 --server-url 和 Token 自动执行安装，绝不进行任何交互。

数据流与架构图

graph TD
    Start[执行 install-agent.sh] --> CheckArgs{是否有命令行参数?}
    
    CheckArgs -- 是 (非交互模式) --> ParseArgs[解析参数]
    ParseArgs --> IsDockerParam{是否指定 Docker?}
    IsDockerParam -- 是 --> RunDocker[Docker 容器拉取与启动]
    IsDockerParam -- 否 --> RunLocal[本地二进制下载与 systemd 服务创建]
    
    CheckArgs -- 否 (交互模式) --> PromptMethod[提示选择 Local 或 Docker]
    PromptMethod --> MethodChosen{选择结果}
    
    MethodChosen -- Docker --> CheckDocker{本地有 Docker 吗?}
    CheckDocker -- 否 --> PromptDockerInstall[询问是否安装 Docker?]
    PromptDockerInstall -- 是 --> InstallDocker[在线安装 Docker + 配置国内镜像加速]
    PromptDockerInstall -- 否 --> ExitScript[取消安装并退出]
    CheckDocker -- 是 --> PromptServerUrl[提示输入 Server URL & Token]
    InstallDocker --> PromptServerUrl
    
    MethodChosen -- Local --> PromptLocalConfig[检测 OpenResty 并提示输入 Server URL & Token]
    
    PromptServerUrl --> RunDocker
    PromptLocalConfig --> RunLocal

---

3. 具体修改文件清单 (Proposed Changes)

边缘 Agent 与部署脚本

• [MODIFY] install-agent.sh

  • 职责：
    1. 引入交互式选择逻辑和 Install_Docker / configure_accelerator 函数。
    2. 新增 --docker 和 --method 命令行参数支持。
    3. 支持用户交互输入配置项。
    4. 增加 Docker 镜像拉取、停止旧容器并启动新容器的安装路径。

• [MODIFY] agent.md

  • 职责：更新一键安装说明文档，增加交互式模式的说明以及 --docker 参数的自动化 Docker 安装说明。

---

4. 验证计划 (Verification Plan)

自动化与脚本测试

• 在干净的测试环境运行脚本：
  • bash scripts/install-agent.sh （测试交互模式 -> 选用 Local）
  • bash scripts/install-agent.sh （测试交互模式 -> 选用 Docker）
  • bash scripts/install-agent.sh --server-url http://127.0.0.1:3000 --discovery-token mytoken （测试自动 Local 安装）
  • bash scripts/install-agent.sh --server-url http://127.0.0.1:3000 --discovery-token mytoken --docker （测试自动 Docker 安装）

数据面生效验证

• 通过 docker ps 和 docker logs openflare-agent 确认容器成功拉取并启动，环境参数注入正确。