# 部署引擎设计 > *部署不是执行命令。* > > *部署是让一个未知环境变得可预测的过程。* > > *不理解环境的部署脚本，只能算是穿着风衣的命令。* --- ## 为什么需要部署引擎 `deploy.sh` 不是安装脚本。它是部署引擎。 安装脚本解决的是“怎么把文件放到正确的位置”。部署引擎解决的是“如何让一个未知环境进入可运行状态”。 用户的机器从来都不是一致的。在实际部署中，可能遇到： - Docker 未安装 - Docker 已安装但未启动 - `daemon.json` 不存在 - `daemon.json` 存在但为空 - `daemon.json` 存在但格式非法 - `registry-mirrors` 不存在 - `registry-mirrors` 存在但全部不可用 - `registry-mirrors` 存在但部分不可用 - `jq` 未安装 - Git 未安装 - `frpc-console` 容器已存在 - `frpc-console` 容器正在运行 - 当前版本高于目标版本（降级） - 当前版本低于目标版本（升级） - LTS 与 Preview 通道混用 因此：**部署不是执行命令。部署首先是环境诊断。** `deploy.sh` 的设计目标： 1. **探测** —— 了解当前环境的状态 2. **分析** —— 判断当前状态与目标状态之间的差距 3. **规划** —— 生成最小必要变更的执行计划 4. **确认** —— 让用户在执行前理解即将发生的变化 5. **执行** —— 按照计划执行变更 6. **验证** —— 确认变更生效且系统正常 7. **清理** —— 移除临时产物，保持系统整洁 --- ## 部署生命周期 `deploy.sh` 的执行流程可以用以下状态流转图表示： ``` ┌─────────────────────────────────────────────────────────────────┐ │ Environment Detection │ │ OS / ARCH / Git / Curl / Wget / Docker / jq / Container │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ State Analysis │ │ 镜像源状态 / 容器状态 / 版本状态 / 通道状态 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Deployment Planning │ │ 生成变更清单：镜像源配置 / 工具安装 / 代码拉取 / 镜像构建 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ User Confirmation │ │ 展示计划 → 等待确认 → 允许自定义配置 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Execution │ │ 备份（降级时）→ 安装工具 → 拉取代码 → 配置镜像源 → 构建镜像 │ │ → 清理旧容器 → 启动新容器 → 写入版本 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Verification │ │ 镜像内容 / 容器状态 / 数据库可用性 / 版本一致性 / frpc PID │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Cleanup │ │ 清理旧镜像（保留最近 N 个）/ 清理临时文件 │ └─────────────────────────────────────────────────────────────────┘ ``` 每个阶段都是独立的、可观测的、可失败的。任何一个阶段失败，系统都不会进入下一个阶段。 --- ## 状态机设计 `deploy.sh` 的核心不是“执行命令”，而是“状态转换”。 以 Docker 镜像源检测为例： ``` ┌─────────────────────────────────────────────────────────────────┐ │ 初始状态 │ │ daemon.json 存在性未知 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ daemon.json 不存在 │ │ 状态: no_file │ │ 动作: 创建并写入 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ daemon.json 存在但格式非法 │ │ 状态: (检测到非法) │ │ 动作: 备份 → 重建为 {} │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ daemon.json 存在但无 registry-mirrors │ │ 状态: no_key │ │ 动作: 写入可用镜像源 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ registry-mirrors 存在且全部可用 │ │ 状态: has_valid_ordered │ │ 动作: 跳过（无变更） │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ registry-mirrors 存在但可用源排在不可用源之后 │ │ 状态: has_valid_reorder_needed │ │ 动作: 重排（可用源前置） │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ registry-mirrors 全部不可用 │ │ 状态: all_invalid │ │ 动作: 插入可用默认源（如存在） │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 默认镜像源全部不可用 │ │ 状态: default_unavailable │ │ 动作: 跳过（提示用户手动配置） │ └─────────────────────────────────────────────────────────────────┘ ``` 这个状态机的核心原则是： > **只在需要时修改。只在确认后执行。每次修改都是可逆的或有备份的。** 所有状态都通过 `jq` 检测，所有修改都通过 `jq` 执行，所有原始配置都被备份。 --- ## 幂等设计 `deploy.sh` 是幂等的。多次执行的结果与一次执行相同。 幂等性通过以下方式保证： ### 1. 条件执行 ```bash # 只在容器存在时执行删除 if docker ps -a | grep -q frpc-console; then docker stop frpc-console docker rm frpc-console fi ``` ### 2. 状态检测前置 ```bash # 检测到用户配置全部可用时跳过修改 if [ "$MIRROR_STATUS" = "has_valid_ordered" ]; then WRITE_DAEMON=false RESTART_DOCKER=false fi ``` ### 3. 版本标记 ```bash # 每次构建使用唯一标签，不覆盖已有镜像 IMAGE_TAG="${SEMVER}-lts-$(date +%Y%m%d)" ``` ### 4. 增量修改而非覆盖 镜像源配置采用“插入到最前面”而非“替换整个文件”的策略，保留用户原有配置。 幂等性的意义在于： > **用户可以在任何时候重新运行 `deploy.sh`，而不必担心系统被破坏。** --- ## 事务完整性 `deploy.sh` 采用类似数据库事务的设计原则： ### 1. 变更前备份 降级操作会触发数据库备份： ```bash if [ "$TGT_SEMVER" \< "$CUR_SEMVER" ]; then BACKUP_DIR="/opt/frpc-console-backups/${TIMESTAMP}_${CHANNEL}" cp -r "$DEPLOY_DIR" "$BACKUP_DIR/frpc-console" fi ``` 修改 `daemon.json` 前也会备份原文件： ```bash cp "$DAEMON_JSON" "${DAEMON_JSON}.bak.$(date +%Y%m%d-%H%M%S)" ``` ### 2. 变更后验证 每次写入后都验证目标状态是否达成： - 写入镜像源后验证 JSON 有效性 - 启动容器后验证容器状态 - 写入版本后验证版本一致性 - 启动后验证 frpc 进程是否存在 ### 3. 失败不继续 任何关键步骤失败都会中断部署，不会进入下一阶段： ```bash if [ $? -ne 0 ]; then print_error "Docker 构建失败" exit 1 fi ``` --- ## 验证不是可选项 大多数安装脚本在“安装完成”后即结束。`deploy.sh` 在“安装完成”后才开始验证。 验证链： ``` 构建完成 │ ▼ 验证镜像内容 ──→ 失败则退出 │ ▼ 启动容器 │ ▼ 验证容器状态 ──→ 失败则退出 │ ▼ 验证数据库可用性 │ ▼ 验证版本一致性 ──→ 警告但不退出 │ ▼ 验证 frpc 子进程 ──→ 警告但不退出 ``` 验证的目的是区分“部署完成”和“部署成功”。 - **部署完成**：脚本执行完毕 - **部署成功**：所有组件正常运行 `deploy.sh` 提供明确的信号来区分这两种状态。 --- ## 边界条件处理 边界条件是部署脚本最大的不确定性来源。`deploy.sh` 在处理边界时遵循一个原则：**先假设它可能出问题，再设计应对方式。** 以下边界条件已被识别并处理： ### 已处理的边界 - `daemon.json` 不存在 → 创建 - `daemon.json` 为空 → 写入 `{}` - `daemon.json` 格式非法 → 备份并重建 - `jq` 未安装 → 尝试安装，失败则降级处理 - `registry-mirrors` 不存在 → 写入可用源 - `registry-mirrors` 全部不可用 → 插入可用默认源 - 用户镜像源全部失效 → 插入可用默认源到最前面 - 默认镜像源全部不可用 → 跳过配置，提示用户手动处理 - 旧版本文件在根目录 → 自动迁移到 `data/` - 容器已存在 → 停止并删除 - 容器正在运行 → 优雅停止 - 降级操作 → 自动备份，用户确认 - LTS ↔ Preview 通道切换 → 备份数据库，用户确认 - 旧镜像积累 → 保留最近 N 个，自动清理 ### 处理原则 每新增一个边界条件，都是在扩展一个同一个决策表：当 `环境变量 X` 处于 `状态 Y` 时，引擎应该执行 `动作 Z`。这些条目不相互覆盖，而是叠加在同一个状态机之上，彼此通过前置条件互锁。 这种方式的优点是：边界条件越多，系统对环境的适应能力越强，但状态机的核心结构不需要跟着膨胀。 --- ## 与工程设计哲学的关系 `deployment-engine-design.md` 与 `engineering-philosophy.md` 的关系是： | 文档 | 回答的问题 | |:---|:---| | `engineering-philosophy.md` | 为什么这样设计？ | | `deployment-engine-design.md` | 这些设计如何落地？ | | `deploy.sh` | 落地后的最终产物 | 三者形成一条完整的链路： ``` 哲学 → 架构 → 部署引擎 → 代码 ``` 哲学文档定义“为什么”，部署引擎文档定义“如何实现”，`deploy.sh` 是“实现的最终形态”。 --- ## 结语 > `deploy.sh` 不是安装脚本。 > > 它是 `frpc-console` 的部署引擎。 > > 它负责：环境探测、状态分析、部署规划、用户确认、执行动作、结果验证、环境清理。 > > 它的设计目标是：**在尽量不打扰用户已有环境的前提下，把部署成功率提高到接近 100%。** 这份文档记录了它为什么长成这样。