feat(update): 支持 Docker Compose 页面一键升级并发布 v1.3.0
This commit is contained in:
+2
-1
@@ -1,7 +1,7 @@
|
||||
# Fonu 文档索引
|
||||
|
||||
> 维护约定：新增方案 / 审查文档时在下方登记；方案落地后在「状态」列标注实施结果，并给已被推翻的描述加时效说明。
|
||||
> 最近更新：2026-09-27（v1.2.21）
|
||||
> 最近更新：2026-09-27（v1.3.0）
|
||||
|
||||
## 方案与设计（本目录）
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
| --- | --- | --- |
|
||||
| `project-analysis-2026-09-27.md` | 全项目详细分析（v1.2.19）：架构、模块、数据、API、前端、链路、风险与改进路线 | 当前版本快照 |
|
||||
| `improvement-roadmap-2026-09-27.md` | P0-P3 改进路线实施方案：逐项改法、测试、验收、依赖、发布与回滚 | P0-1、P0-3 已完成，其余待实施 |
|
||||
| `system-upgrade.md` | Docker Compose 一键升级：sidecar 架构、首次部署、安全边界、回滚与故障排查 | 已实施（v1.3.0） |
|
||||
| `project-audit-2026-09-24.md` | 全项目审查：P0/P1/P2 分级，含精确行号与逐条修法 | **进行中**——P0 已随 v1.2.7 完成，P1 实施中 |
|
||||
| `frp-server-list-merge-plan.md` | FRP 服务端列表并入「公网服务端」页（方案 A，四步） | 步 1/2 已完成（v1.2.6）；步 3 文案收尾、步 4 死样式清理未做 |
|
||||
| `agent-capability-plan.md` | fonu-agent 能力扩展（P0/P1/P2/P3） | 已实施（agent 0.11.0）；P3 三项不做 |
|
||||
|
||||
@@ -172,8 +172,10 @@ FONU_VERSION=1.2.18 docker compose up -d
|
||||
| `FONU_LISTEN` | `:6893` | 面板监听地址 |
|
||||
| `FONU_SESSION_SECRET` | 空 | 留空即自动生成并持久化；**它是凭据加密密钥，有数据后不要更换** |
|
||||
| `FONU_NGINX_HTTP_PORT` / `FONU_NGINX_HTTPS_PORT` | `80` / `443` | 反代监听端口（host 网络那份默认 18080/9443） |
|
||||
| `FONU_UPDATER_SOCKET` | `/run/fonu-updater/updater.sock` | 一键升级 sidecar 的 Unix Socket |
|
||||
| `DOCKER_SOCK` | `/var/run/docker.sock` | 宿主机 Docker Socket；rootless Docker 或自定义路径时覆盖 |
|
||||
| `TZ` | `Asia/Shanghai` | 通知与日志显示用的时区 |
|
||||
| `NODE_IMAGE` / `GO_IMAGE` / `RUNTIME_IMAGE` | 国内镜像源 | 构建用的基础镜像，被加速器拦截时用来覆盖 |
|
||||
| `NODE_IMAGE` / `GO_IMAGE` / `RUNTIME_IMAGE` / `UPDATER_IMAGE` | 国内镜像源 | 构建用的基础镜像，被加速器拦截时用来覆盖 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
# Fonu Web 一键升级方案
|
||||
|
||||
> 实施版本：v1.3.0
|
||||
> 适用范围：`docker-compose.yml`、`docker-compose.hub.yml`
|
||||
> 不适用范围：`docker-compose.host.yml`、原生 systemd 安装、Windows 直接运行
|
||||
|
||||
## 1. 设计目标
|
||||
|
||||
在管理后台检测到新版本后，用户点击「一键升级」即可完成：
|
||||
|
||||
1. 读取远端最新版本；
|
||||
2. 构建新的 `fonu` 镜像；
|
||||
3. 只重建 `fonu` 容器；
|
||||
4. 等待 `/api/version` 返回目标版本；
|
||||
5. 失败时尝试回滚到升级前的镜像 tag；
|
||||
6. 把升级过程和结果返回给前端。
|
||||
|
||||
## 2. 安全边界
|
||||
|
||||
主程序容器**不挂载** `/var/run/docker.sock`。
|
||||
|
||||
只有 `fonu-updater` sidecar 持有：
|
||||
|
||||
- Docker Socket；
|
||||
- Docker CLI 与 Compose；
|
||||
- 项目目录；
|
||||
- Git。
|
||||
|
||||
主程序与 sidecar 通过一个共享 Unix Socket 通信：
|
||||
|
||||
```text
|
||||
浏览器
|
||||
→ fonu 后端 /api/system/update/*
|
||||
→ /run/fonu-updater/updater.sock
|
||||
→ fonu-updater
|
||||
→ docker compose build/up
|
||||
```
|
||||
|
||||
这表示：
|
||||
|
||||
- 管理后台被攻破时，攻击者仍需通过 sidecar 的固定接口才能触发升级；
|
||||
- sidecar 只接受固定的 Compose 文件名和固定的 `fonu` 服务名；
|
||||
- 不提供任意命令执行接口；
|
||||
- 不支持自定义 shell 命令。
|
||||
|
||||
## 3. 两种升级模式
|
||||
|
||||
| Compose 文件 | 模式 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| `docker-compose.yml` | `local` | 在项目目录检查 Git 工作区，干净时执行 `git pull --ff-only`，再构建 |
|
||||
| `docker-compose.hub.yml` | `git` | Compose 的 build context 直接从 Git 仓库拉取，updater 只负责构建与重建 |
|
||||
|
||||
两种模式都会：
|
||||
|
||||
- 读取目标版本；
|
||||
- 构建 `fonu` 镜像；
|
||||
- 执行 `docker compose up -d --no-deps --force-recreate fonu`；
|
||||
- 轮询 `/api/version` 验证升级结果。
|
||||
|
||||
## 4. 首次部署
|
||||
|
||||
一键升级依赖 `fonu-updater` 已经运行。
|
||||
|
||||
旧版本升级到 v1.3.0 时，需要先手动执行一次：
|
||||
|
||||
```bash
|
||||
# 本地源码部署
|
||||
docker compose up -d --build
|
||||
|
||||
# 单文件 Git 构建部署
|
||||
docker compose -f docker-compose.hub.yml up -d --build
|
||||
```
|
||||
|
||||
完成这一轮后，后续版本即可在 Web 页面一键升级。
|
||||
|
||||
## 5. 环境变量
|
||||
|
||||
### 主程序
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `FONU_UPDATER_SOCKET` | `/run/fonu-updater/updater.sock` | 与 sidecar 通信的 Unix Socket |
|
||||
|
||||
### updater sidecar
|
||||
|
||||
| 变量 | 说明 |
|
||||
| --- | --- |
|
||||
| `FONU_UPDATER_SOCKET` | sidecar 监听的 Unix Socket |
|
||||
| `FONU_UPDATE_PROJECT_DIR` | Compose 项目目录，容器内为 `/workspace` |
|
||||
| `FONU_UPDATE_COMPOSE_FILE` | 只允许 `docker-compose.yml`、`docker-compose.hub.yml`、`docker-compose.host.yml` |
|
||||
| `FONU_UPDATE_SERVICE` | 要重建的服务，默认 `fonu` |
|
||||
| `FONU_UPDATE_MODE` | `local` 或 `git` |
|
||||
| `FONU_UPDATE_REPO` | `git` 模式下的仓库地址 |
|
||||
| `FONU_UPDATE_BRANCH` | `git` 模式下的分支，默认 `main` |
|
||||
| `FONU_UPDATE_APP_URL` | 健康检查地址，默认 `http://fonu:6893` |
|
||||
| `DOCKER_SOCK` | 宿主机 Docker Socket，默认 `/var/run/docker.sock` |
|
||||
|
||||
## 6. 前端行为
|
||||
|
||||
侧栏版本区在满足以下条件时显示「一键升级」：
|
||||
|
||||
- sidecar 可用；
|
||||
- 远端版本高于当前版本；
|
||||
- 当前没有正在执行的升级任务。
|
||||
|
||||
点击后弹窗显示：
|
||||
|
||||
- 当前版本；
|
||||
- 目标版本；
|
||||
- 升级方式；
|
||||
- 当前阶段；
|
||||
- 最近日志。
|
||||
|
||||
升级开始后，页面会持续轮询升级状态。容器重建期间请求会短暂失败，前端会显示「服务正在重启，等待恢复」，恢复成功后自动刷新页面。
|
||||
|
||||
## 7. 回滚
|
||||
|
||||
升级前会记录当前容器镜像。升级后健康检查超时，sidecar 会尝试：
|
||||
|
||||
```bash
|
||||
FONU_VERSION=<上一个版本> docker compose up -d --no-deps --force-recreate fonu
|
||||
```
|
||||
|
||||
回滚是否成功会写入升级日志。
|
||||
|
||||
## 8. 常见问题
|
||||
|
||||
### 侧栏没有「一键升级」
|
||||
|
||||
检查：
|
||||
|
||||
1. 当前是否使用 `docker-compose.yml` 或 `docker-compose.hub.yml`；
|
||||
2. `fonu-updater` 容器是否在运行；
|
||||
3. `FONU_UPDATER_SOCKET` 是否在两侧指向同一路径；
|
||||
4. 共享卷 `fonu-updater-sock` 是否存在。
|
||||
|
||||
### `docker-compose.yml` 模式提示存在未提交改动
|
||||
|
||||
升级前的 Git 工作区检查要求干净，避免覆盖用户修改。先处理工作区，或手动执行：
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### `docker-compose.hub.yml` 模式无法读取远端版本
|
||||
|
||||
检查 sidecar 容器内是否可以访问 Git 仓库：
|
||||
|
||||
```bash
|
||||
docker exec -it fonu-updater sh -lc 'git ls-remote http://45.207.223.190:10082/mrlee/-Fonu.git main'
|
||||
```
|
||||
|
||||
### 升级卡在 `running`
|
||||
|
||||
查看 sidecar 日志：
|
||||
|
||||
```bash
|
||||
docker logs -f fonu-updater
|
||||
```
|
||||
|
||||
以及 Compose 输出：
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs --tail 100 fonu
|
||||
```
|
||||
|
||||
### 回滚失败
|
||||
|
||||
确认升级前的镜像 tag 仍然存在：
|
||||
|
||||
```bash
|
||||
docker images fonu
|
||||
```
|
||||
|
||||
然后用明确的版本 tag 手动切回：
|
||||
|
||||
```bash
|
||||
FONU_VERSION=<旧版本> docker compose up -d --no-deps --force-recreate fonu
|
||||
```
|
||||
|
||||
## 9. 暂不支持
|
||||
|
||||
- `docker-compose.host.yml`：需要确认 host 网络与端口占用后再设计；
|
||||
- 原生 systemd 安装：需要单独的受控升级 helper；
|
||||
- 回滚到远端不存在的镜像：需要额外发布流程；
|
||||
- 升级 `fonu-updater` 自身：当前只重建 `fonu` 服务，sidecar 更新仍需一次手动 Compose 操作。
|
||||
Reference in New Issue
Block a user