lxh2875931338/frpc-console
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

一份新的Docs，给部署引擎设计预留

Browse Source
This commit is contained in:
lxh2875931338
2026-08-06 00:02:49 +08:00
parent c03c8cf9ce
commit 4dd5cc07b4
2 changed files with 356 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Docs/deployment-engine-design.md
+355
View File
@@ -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%。**
这份文档记录了它为什么长成这样。
readme.md
+1
View File
@@ -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 |