Hullkeep

数据安全的容器升级——升级前自动备份，升级后健康检查，不行就回滚，数据永远有退路。

English README

出事的时候，它是这样的

升级前自动备份 → 拉取新镜像（服务照常运行）→ 重建容器 → 健康检查没过 → 自动回滚到原版本，数据完好。

为什么做 Hullkeep

自托管久了，机器上会攒下十几个 docker compose 服务。它们各自更新，你却很难回答三个问题：谁出新版本了？升级安不安全？升坏了怎么办？

「谁出新版本了」只是开头。真正让人不敢点升级的，是后两个问题——尤其当容器里跑着数据库、相册、网盘这些有状态服务的时候：新版本改了数据结构，旧数据还回得去吗？

Hullkeep 的回答是把升级做成一条完整的链路：看见更新 → 备份数据 → 升级 → 健康检查 → 不行就回滚。每一步都有记录，每一步都可以反悔。它面向普通自托管用户设计——界面上每个选项都配有讲人话的说明，不需要你先成为 Docker 专家。

数据永远有退路

这条链路是 Hullkeep 的核心，值得单独讲清楚：

1. 升级前，先把数据备好：compose 目录、绑定目录（bind mount）和 docker 具名卷（named volume）打进同一份备份——数据不管挂在哪，都不会被漏掉。可选「备份前停止容器」获得强一致快照。
2. 升级后，先体检再放行：自动健康检查，失败自动回滚到旧版本，不用你半夜爬起来救火。
3. 新版本不合适，一键退回去：备份存档就在界面里，不用 SSH 解 tar——直接翻看某份存档里都有什么文件，一键把数据恢复回去；恢复前会先把当前状态另存一份，恢复本身也可以反悔。
4. 主盘坏了，副本还在：可选配置备份镜像目录，每份备份完成后自动复制一份过去——把 NFS 或第二块盘挂进容器再填上路径即可。
5. 备份不会吃光磁盘：空间安全阀给 Hullkeep 自己占用的磁盘设上限，超限时按「损失最小」的顺序回收，且每个容器最后一份存档永远保留。

存档不是写完就算——它能翻开看，能一键放回去，而恢复本身也会先留一份退路：

界面预览

看板	升级确认（版本跨度 + 更新说明）

翻看备份存档（含具名卷）	通知渠道配置

能力全览

看见更新

• 全景看板：所有容器的运行状态、健康检查、CPU / 内存占用、数据卷大小、端口映射、备份情况，一页看全。
• 更新检查：识别语义化版本的更高稳定版（跳过 alpha / beta / rc），也能发现同 tag 之下的上游镜像更新；支持定时检查（固定间隔 / 每天 / 每周 / cron 表达式，带时区）。
• 升级分档：每个容器单独选跟到哪一级——只跟修订版（1.2.3 → 1.2.9）、只跟小版本（不跨大版本）、最新稳定版、含预发布，或钉死在你指定的某个 tag。分档之外的更高版本只发通知，不会自动升上去。
• 版本情报：升级候选的官方发布时间与 GitHub 更新说明直接展示在容器详情里，并标出哪条对应当前安装版本、哪条是升级目标。
• 版本跨度提醒：升级确认弹窗会告诉你这一跳跨越了几个版本，并把中间那些版本的更新说明直接摆出来——跨度大本身就是风险信号，按下按钮之前你会先看到它。

升级与回滚

• 带备份升级：升级前自动备份 compose 目录与数据目录；升级后自动健康检查，失败自动回滚到旧版本。
• 一键回滚 / 原地重装：新版本不合适，一键回到升级前的版本；容器状态异常时可用当前版本原地重建。
• 批量升级与自动升级：勾选多个容器依次带备份升级；对信任的容器可开启自动升级，只在你设定的维护窗口（如深夜）内执行。
• 自更新：Hullkeep 也能升级它自己——先给自己做一份带数据库一致快照的备份，再由独立 helper 容器接手重建，页面断开几十秒后自动恢复。
• 升级后清理旧镜像：只删 Hullkeep 自己换下来的、且没有任何容器还在引用的镜像，默认保留最近一代当回滚锚点；不碰你自己拉的其它镜像。

备份与恢复

• 具名卷一起备份：绑定目录和 docker 具名卷（named volume）打进同一份备份、恢复时一起放回。
• 独立备份：不升级也能一键备份任何容器，按每容器保留份数自动清理旧存档。
• 备份镜像目录（异地副本）：第二个目录里始终有整套存档的副本；副本随主备份一起清理，复制失败只记录提醒，绝不拖垮备份本身。
• 翻看存档与数据恢复：在界面里直接浏览存档内容，一键恢复，恢复前自动另存当前状态。
• 空间安全阀：备份存档、运行记录、升级换下来的旧镜像统一计算占用，超限自动回收，每一步删了什么都写进运行记录。

通知与远程控制

• 七渠道通知：Bark、Telegram、飞书、企业微信、钉钉、Server酱、PushPlus 推送新版本提醒与升级结果。
• Telegram 机器人远程操作：几乎全部功能都能在聊天窗口里完成——查看状态 / 容器列表 / 上游有哪些版本 / 升级历史 / 存档列表 / 运行记录，以及升级（可指定版本）、回滚、备份、重建、升级 Hullkeep 自己。恢复备份、改设置、改管理员密码这三类会强制二次确认——机器人先复述要做什么并给出一次性确认码，回错即作废。

一切有记录

• 运行记录：Hullkeep 自己做过的每件事都记下来——定时检查跑没跑、结果如何、谁触发的（手动 / 定时 / 自动升级 / 机器人）。「跑了但没发现新版本」这种没有动静的轮次同样记录，所以「今早到底检查了没有」永远查得到，不必靠有没有收到通知去猜。默认保留 90 天。

网络与语言

• 私有镜像仓库：存一份仓库登录凭据，私有镜像照样检查更新、照样拉取；局域网自建仓库（自签证书 / HTTP）可标记为不验证证书，且默认直连不走代理。
• 网络友好：内置 HTTP 代理支持、一键网络诊断与带宽测速；放在反向代理后（子域名或子路径、HTTPS）开箱即用；同一个镜像发布在 GHCR 与 Docker Hub 两个仓库，哪个连得通用哪个。
• 中英双语界面，包括后端产生的报错说明也跟随界面语言；来自镜像仓库或 Docker 的底层报错原文保留英文不翻译，方便你直接拿去搜索。

安装

在 NAS 上装？直接看平台教程：群晖 · 绿联 · 极空间；其它系统看通用安装教程。

两种方式任选其一，都从克隆仓库开始：

git clone https://github.com/ailenshow/Hullkeep.git
cd Hullkeep

方式一：一键安装脚本（推荐新手）

bash install.sh

脚本会用中文或英文引导你完成全部配置：面板端口、compose 项目根目录、管理员账号、时区、镜像源（自动探测 GHCR 与 Docker Hub 哪个连得通，默认选通的那个），然后自动写好 .env、拉取镜像并启动，最后告诉你访问地址和初始密码在哪看。

方式二：手动 docker compose

cp .env.example .env
# 编辑 .env：把 HULLKEEP_DOCKER_ROOT 指向你的 compose 项目根目录
docker compose up -d
# 打开 http://<主机IP>:8180

两种方式默认都使用预构建的多架构镜像（amd64 / arm64）。同一个镜像发布在两个仓库，哪个连得通用哪个，在 .env 里用 HULLKEEP_IMAGE 切换：

镜像源	地址
GHCR（默认）	ghcr.io/ailenshow/hullkeep:latest
Docker Hub	docker.io/ailenshow/hullkeep:latest

想从源码构建，把 docker-compose.yml 里的 image: 行换成 build: . 即可。

登录凭据

• 用户名默认 admin（可在 .env 里用 HULLKEEP_ADMIN_USER 修改）。
• 密码二选一：
  • 在 .env 里设置 HULLKEEP_ADMIN_PASSWORD；
  • 留空则首次启动时自动生成随机密码，只在容器日志里打印一次（docker compose logs hullkeep | grep password），之后可在「设置 → 安全」里随时修改。

关键概念：同路径挂载

Hullkeep 通过 compose 标签找到每个容器的项目目录，因此这个目录必须以相同的路径挂载进 Hullkeep 容器（docker-compose.yml 里的 ${HULLKEEP_DOCKER_ROOT}:${HULLKEEP_DOCKER_ROOT} 就是干这个的）。路径对不上时，界面会在升级前明确提示缺了哪个挂载。

反向代理

子域名和子路径两种方式都支持：

• 子路径（如 https://nas.example.com/hullkeep/）：前端资源与 API 全部使用相对路径，代理只需去掉路径前缀再转发（nginx location /hullkeep/ { proxy_pass http://127.0.0.1:8180/; } 结尾的 / 即完成前缀剥离）。
• 真实来源 IP 与 HTTPS：在「设置 → 网络 → 可信反向代理」填入代理的 IP 或 CIDR 后，登录限流按 X-Forwarded-For 里的真实客户端 IP 计，X-Forwarded-Proto: https 时会话 cookie 自动携带 Secure 属性。留空则不信任任何转发头。

设计原则

• 默认只通知、不自动升级——升级是运维决策，不是后台副作用。
• 每次升级前自动备份，失败可自动回滚；备份存档随时可手动创建。
• 不越界：不直接重建 Hullkeep 自身（自更新交由独立 helper 容器完成）；不碰非 compose 管理的容器。

隐私与零遥测

Hullkeep 不收集、不上报任何数据：没有使用统计，没有崩溃上报，没有匿名指标，没有任何形式的「回家连接」。它发出的每一个网络请求都只服务于你配置的功能，且全部可以在界面里看到来龙去脉：

• 镜像仓库（Docker Hub / GHCR / 你自己的私有仓库）——检查更新与拉取镜像；
• GitHub Releases——读取镜像来源项目的更新说明，展示在升级弹窗里；
• 你配置的通知渠道——只有你填了对应的 key / webhook 才会连接；
• Hullkeep 自己的发布地址——检查面板自身有没有新版本。

不配代理就直连，配了代理按各渠道的说明走或不走代理。所有数据（数据库、备份存档、运行记录）都留在你自己的机器上。

路线图

按需求反馈排优先级，欢迎在 Issues 里投票或补充场景：

• 更多通知渠道（ntfy / Discord / Gotify）
• OIDC 单点登录
• 备份存档加密
• 增量备份

License

Copyright (C) 2026 ai-lenshow

Hullkeep 以 GNU Affero General Public License v3.0 发布。你可以自由使用、部署与修改；若基于修改后的版本对外提供网络服务，AGPL-3.0 要求公开对应源码。

作者

ai-lenshow · https://github.com/ailenshow