61 lines
3.3 KiB
Plaintext
61 lines
3.3 KiB
Plaintext
---
|
||
title: 在线更新与安全回退
|
||
description: Host Updater、Release 检查、数据库备份迁移、健康验证与异常回退机制。
|
||
---
|
||
|
||
# 在线更新与安全回退
|
||
|
||
管理后台的“系统配置 → 系统更新”只负责管理员鉴权、展示状态和发起操作。真正的 Docker、数据库备份与服务切换由宿主机上的 `open-ai-canvas-host-updater` 执行，业务后端不挂载 Docker Socket。
|
||
|
||
```text
|
||
管理员浏览器 → Backend 管理 API → 带 Token 的 Unix Socket → Host Updater → Docker Compose
|
||
```
|
||
|
||
## 安全更新顺序
|
||
|
||
1. 从 GitHub Releases 读取包含预览版在内的最高语义版本，并与 `.env` 中固定的 `CANVAS_IMAGE_TAG` 比较。
|
||
2. 下载目标版本的 `docker-compose.deploy.yml`，执行 `docker compose config --quiet`，检查部署文件、磁盘空间和当前版本。
|
||
3. 创建 `backup-YYYYMMDD-HHMMSS.zip.partial`，其中包含 PostgreSQL custom-format dump、后端数据目录 tar 和元数据；写入完成后 `fsync`、原子改名，并复核 ZIP 结构和 SHA-256。
|
||
4. 拉取目标 backend/web 镜像并要求存在仓库 `sha256` 摘要。任何失败都在停服前中止。
|
||
5. 停止 web/backend，等待 Backend 的 SIGTERM drain 完成；PostgreSQL 和 Redis 保持运行。
|
||
6. 用目标 backend 镜像独立执行 `migrate-schema up`。整批迁移在事务和 PostgreSQL advisory lock 内完成，迁移名称与 checksum 必须匹配。
|
||
7. 原子更新 `CANVAS_IMAGE_TAG` 和 Compose 文件，启动目标版本。
|
||
8. 连续检查 `/api/health/ready` 的数据库、运行时、schema 和 build version，并经过稳定窗口后才标记成功。
|
||
|
||
更新状态写入 `/var/lib/open-ai-canvas-updater/state.json`。Backend 或浏览器在切换期间断线不会终止宿主机操作，恢复后可继续读取日志。
|
||
|
||
## 自动回退
|
||
|
||
停服后的迁移、启动或健康验证失败会触发自动回退：
|
||
|
||
1. 停止目标 web/backend；
|
||
2. 恢复更新前保存的 Compose 文件；
|
||
3. 再次校验备份 ZIP 和 SHA-256；
|
||
4. 使用 `pg_restore --clean --if-exists` 恢复 PostgreSQL；
|
||
5. 恢复旧 `CANVAS_IMAGE_TAG`，启动旧服务并重新进行稳定窗口验证。
|
||
|
||
回退任一步失败时状态变为 `manual_intervention`，不伪造成功。管理后台仅在存在旧版本和已校验备份时开放人工回退按钮。
|
||
|
||
## 安装与升级约束
|
||
|
||
GHCR 镜像部署必须把 `CANVAS_IMAGE_TAG` 固定到具体 Release，不可使用 `latest`。安装更新器：
|
||
|
||
```bash
|
||
cd /opt/open-ai-canvas
|
||
curl -fsSL https://raw.githubusercontent.com/ddcat-ai/open-ai-canvas/main/scripts/install-host-updater.sh | sudo bash
|
||
sudo docker compose --env-file .env -f docker-compose.deploy.yml up -d --force-recreate backend web --wait
|
||
```
|
||
|
||
脚本会下载与当前 Release 匹配的 Linux amd64/arm64 二进制和 `SHA256SUMS`，生成随机 `CANVAS_UPDATER_TOKEN`，创建 systemd 服务、Socket 目录、状态目录和 `backups/`。Token 只保存在服务器 `.env` 与 root-only 更新器环境文件中。
|
||
|
||
## 运维检查
|
||
|
||
```bash
|
||
sudo systemctl status open-ai-canvas-updater
|
||
sudo journalctl -u open-ai-canvas-updater -n 200 --no-pager
|
||
sudo ls -lh /opt/open-ai-canvas/backups
|
||
sudo sha256sum /opt/open-ai-canvas/backups/*.zip
|
||
```
|
||
|
||
备份文件包含业务数据，应限制为 root 访问并纳入异机备份策略。数据卷本身不是备份。
|