From 4dd5cc07b4b08e432562172c70c5b41f5905fe6e Mon Sep 17 00:00:00 2001 From: lxh2875931338 Date: Thu, 6 Aug 2026 00:02:49 +0800 Subject: [PATCH] =?UTF-8?q?=E4=B8=80=E4=BB=BD=E6=96=B0=E7=9A=84Docs?= =?UTF-8?q?=EF=BC=8C=E7=BB=99=E9=83=A8=E7=BD=B2=E5=BC=95=E6=93=8E=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E9=A2=84=E7=95=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Docs/deployment-engine-design.md | 355 +++++++++++++++++++++++++++++++ readme.md | 1 + 2 files changed, 356 insertions(+) create mode 100644 Docs/deployment-engine-design.md diff --git a/Docs/deployment-engine-design.md b/Docs/deployment-engine-design.md new file mode 100644 index 0000000..6135a2a --- /dev/null +++ b/Docs/deployment-engine-design.md @@ -0,0 +1,355 @@ +# 部署引擎设计 + +> *部署不是执行命令。* +> +> *部署是让一个未知环境变得可预测的过程。* +> +> *不理解环境的部署脚本，只能算是穿着风衣的命令。* + +--- + +## 为什么需要部署引擎 + +`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%。** + +这份文档记录了它为什么长成这样。 \ No newline at end of file diff --git a/readme.md b/readme.md index 33ccfbd..0904791 100644 --- a/readme.md +++ b/readme.md @@ -21,6 +21,7 @@ |---|---| | [📖 工程设计哲学](./Docs/engineering-philosophy.md) | 为什么它会长成今天这样 | | [🔄 更新策略](./Docs/update-strategy.md) | Preview / LTS | +| [🚀 更新引擎设计](./Docs/deployment-engine-design.md) | deploy.sh 的架构设计 | | [🏗 架构设计](./Docs/architecture.md) | 整体架构设计思路 | | [⚙ 设计决策](./Docs/design-decisions.md) | 为什么没有 CI？为什么叫 Console？ | | [🌐 边缘节点](./Docs/edge-node.md) | 为什么支持 BusyBox、ARMHF |