镜像发布与后台更新
发布已提交的镜像,安装更新器,检查更新并按数据库兼容性恢复。
在开发机发布镜像
将待发布改动提交并合并到本地 main 后,在应用仓库根目录运行发布脚本。脚本从 git archive main 构建,不包含未提交内容,不自动拉取远程代码;默认发布 main 和带提交前缀的标签,不发布 latest。需要 Docker、Buildx、Git、Bash、tar 以及仓库推送权限。
docker login
./deploy/publish-image.sh选择镜像架构并保留构建缓存
发布脚本默认只构建 linux/amd64,适用于 Intel / AMD 64 位 Linux 服务器。ARM 服务器或 Apple silicon Mac 原生运行需发布 linux/arm64;面向两种架构时显式指定以下变量。Linux 跨架构构建需要已有 QEMU / binfmt 支持或对应原生构建节点。
后续发布复用 bosapi-release builder,保留依赖与编译缓存。仅前端变化可复用后端编译结果;版本号变化不会重新安装运行镜像系统依赖。首次构建、依赖变更、网络和上传仍影响耗时。Dockerfile 优化需提交到本地 main 才能进入发布构建。
BOS_RELEASE_PLATFORMS=linux/amd64,linux/arm64 ./deploy/publish-image.shBOS_RELEASE_PLATFORMS=linux/arm64 ./deploy/publish-image.sh在部署主机安装更新器
先完成首次部署并保留原配置、数据挂载、数据库密码和加密密钥。部署主机需要对应版本的脚本、Docker Compose v2、Buildx 和 Python 3.9+。Linux 使用有 Docker 访问权的已有非 root 部署用户;macOS 以当前 Docker Desktop 用户运行,不加 sudo。
sudo python3 deploy/image-updater/install.py --user deploy-user
sudo systemctl status bosapi-image-updater.servicepython3 deploy/image-updater/install.py
launchctl print gui/$(id -u)/com.bosapi.image-updater- 替换 deploy-user。安装生成的 deploy/image-updater.env 和 deploy/image-updater.enabled 属于本机私有配置,不要提交或复制到其他机器。
首次切换与后续更新
首次切换前备份数据库,新镜像启动可能执行 SQL 迁移。由运行服务的部署用户在应用仓库根目录检查,等待状态为 available 或 up_to_date;仅 available 时提交 apply,然后继续查看状态。
python3 deploy/image-updater/agent.py check
python3 deploy/image-updater/agent.py statuspython3 deploy/image-updater/agent.py apply
python3 deploy/image-updater/agent.py status- 完成后超级管理员进入“系统设置 → 系统更新”,后续依次使用“检查更新”和“立即更新”。单实例更新会短暂中断,关闭页面不终止宿主机任务。
- 后台更新固定检查到的镜像摘要,仅重建应用并保留数据;它不会更新宿主机 Compose 文件、更新器或安装脚本。按发布说明同步必要文件,禁止与手动部署并发。
手动选择部署方式
在部署主机的应用仓库根目录显式选择源码或镜像模式。源码模式使用当前检出,镜像模式需要指定镜像引用;两者均不执行 git pull。
./deploy/stack.sh up --source
./deploy/stack.sh up --image xiaolinger/bosapi:main排错与恢复
Linux 查看 journalctl -u bosapi-image-updater.service;macOS 查看 ~/.local/share/bosapi-updater/private/service.stderr.log。启动或前端发布失败时,应用可能已切换且数据库可能已迁移,应先核对运行镜像和健康状态。
旧镜像保留为 bosapi-image-updater:previous。确认数据库结构兼容旧版后,才能使用下列命令恢复;恢复不会撤销 SQL 迁移。数据库不兼容时先按备份和迁移方案恢复。
python3 deploy/image-updater/agent.py rollback --confirm-schema-compatible
python3 deploy/image-updater/agent.py status按部署版本核对具体能力与操作。 查看文档适用范围