Homebox 家庭物品库:固定版本部署、邀请与完整备份
用固定版本 Homebox 记录物品位置、图片和票据,先关闭自由注册,再验证同组访问、整目录冷备与空目录恢复。
转接头明明买过,却不知道在哪个抽屉;电器要维修时,型号、发票和保修资料又散在几处。Homebox 可以把这些信息放进同一条物品记录。先整理一个常翻找的抽屉,确认能搜到东西、找回附件,再决定是否录完整个家。
本文使用当前维护项目 sysadminsmedia/homebox 的固定 0.27.1 版本、SQLite 与本地存储,先通过 SSH 建立账号,再安排家庭访问。二维码提供物品入口,不会自动知道东西被搬到了哪里;位置与数量仍要在使用后更新。
先定位置,再录物品
位置按实际寻找路径命名,例如“书房/右侧抽屉”;物品名写能区分的型号和用途,例如“65W USB-C 充电器”。保修日期、购买金额按票据填写,没有依据就留空。照片先拍全貌和铭牌,避免把住址、证件或门锁信息一起传进去。
已有 Linux VPS 还有余量,可以先复用。整机 2 GiB 内存、20 GiB 本地磁盘可作为家庭小规模试用起点,这是建议配置,不是本站测出的最低要求;图片和票据较多时另留磁盘与备份空间。下例给 Homebox 设 512 MiB 上限,主机还需容纳 Docker、系统和已有服务。选择家人日常访问顺畅的地区即可,不需要住宅 IP。
需要新机器时,可查看雨云 RCS 的地区与配置,比较月付、续费、本地磁盘和备份费用。先用少量记录验证手机访问、图片上传与恢复,再决定长账期。域名与异地备份可能单独收费,购买前核对结算页;不为了几个物品记录强行更换已有服务器。
新实例使用当前维护的镜像
服务器需已有 Docker Engine、Compose 插件和可用的 Docker 权限。下面在 Linux 的 root shell 中建立新目录;已有实例时先核对配置和数据,不覆盖它。普通镜像与 rootless、hardened 镜像的运行用户不同,不能直接混用目录权限。
set -eu
umask 077
mkdir -p /srv/homebox/data
chmod 700 /srv/homebox /srv/homebox/data
cd /srv/homebox
test ! -e .env
printf 'HBOX_AUTH_API_KEY_PEPPER=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .env
API Key pepper 至少需要 32 字节,应用用它保护所存的 API Key 哈希;它不是登录密码。生成后持续保留,轮换会使已发放的 API Key 失效。恢复时也要保存同一配置,不能把 .env 当作可以重建的临时文件。
保存 compose.yaml。固定版本及多架构索引摘要,避免下一次拉取 latest 时顺带升级。/data 使用本机目录,SQLite 与本地附件一起保存;不要把网络共享目录直接当作本例的本地磁盘。
services:
homebox:
image: ghcr.io/sysadminsmedia/homebox:0.27.1@sha256:9d0b64776c694f018c0ca06faf52105a33ca376024f46bb58e6ab0e2b728bb61
restart: unless-stopped
ports:
- "127.0.0.1:3100:7745"
environment:
TZ: Asia/Shanghai
HBOX_MODE: production
HBOX_AUTH_API_KEY_PEPPER: ${HBOX_AUTH_API_KEY_PEPPER:?pepper required}
HBOX_OPTIONS_ALLOW_REGISTRATION: "true"
HBOX_OPTIONS_ALLOW_ANALYTICS: "false"
HBOX_OPTIONS_GITHUB_RELEASE_CHECK: "false"
HBOX_WEB_MAX_UPLOAD_SIZE: "10"
volumes:
- ./data:/data
mem_limit: 512m
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80 homebox
curl --fail http://127.0.0.1:3100/api/v1/status
状态接口只说明服务能响应。还要在 Docker 实际配置中确认端口仅绑定 127.0.0.1、内存限制生效,且 /data 指向预期目录。不要为了解决写入错误把数据目录改成所有人可写。
家庭账号建立以后限制入口
在自己的电脑另开终端,将 SSH 用户和主机替换为实际地址:
ssh -N -L 13100:127.0.0.1:3100 user@your-server
打开 http://127.0.0.1:13100,注册首个账号并登录。随后立刻把 compose.yaml 中 HBOX_OPTIONS_ALLOW_REGISTRATION 改为 "false",在服务器执行 docker compose up -d。用未登录窗口尝试不带邀请的注册,确认被拒绝,再为家庭成员生成邀请,让需要共享物品的人加入同一个组。
0.27.1 中,关闭自由注册不等于关闭合法邀请;邀请仍要通过服务端的有效期和使用次数检查。不同人各自注册可能得到不同组,不能凭“都能登录”判断物品已经共享。把邀请链接当作私密凭据,不贴到公开页面;用普通成员账号确认实际可见范围。
先通过 SSH 访问完成后面两节的成员与附件权限检查;异常未解决时保留私有网络访问,暂不接公网域名。需要手机从外部访问时,可在宿主机现有 Caddy 配置中增加独立域名。DNS、证书申请与入站 80、443 要满足要求,验证配置后再重载,不覆盖其他站点。
items.example.com {
reverse_proxy 127.0.0.1:3100
}
代理若在另一个容器,127.0.0.1 指向代理自身,需按已有网络连接应用。只给家人使用时,也可以保留私有网络访问。本文没有配置邮件,不能假定找回密码或邮件通知已经可用;让家人长期使用前,按实际邮件设置验证恢复渠道。
第一轮只录一个抽屉
创建一个位置,录入几件经常翻找的配件。每件保存名称、数量和位置,上传一张能认出型号的照片,再附一份无敏感信息的测试文件。保存以后离开编辑页,从搜索结果重新打开,确认附件可下载,数量和位置没有只停留在未保存的表单里。
一套工具常常一起取用时,可以先作为一件记录;需要分别借出和查找时,再拆成独立物品。不要为了填满功能栏,把日常录入变成负担。物品搬走或消耗后马上更新位置与数量,软件中的“三个”才有参考价值。
录入完成后重建一次应用容器,再用原账号找回测试记录和附件。这能提前发现数据没有写进挂载目录的问题。执行更新前先保留已有数据,不用删除卷来“重新试一下”。
标签和附件要实际打开一次
先打印一两个测试标签,用家庭成员的手机扫描,确认进入正确物品,并检查登录要求。二维码不是定位器;换了抽屉后仍需更新记录。保留肉眼能认出的物品名称或编号,扫码失败时也能查找。
从未登录窗口直接打开测试附件地址,再用同组与不同组的账号检查访问结果。二维码、缩略图和附件可能走不同路径,不能只验证物品详情页。跨组请求或已用邀请返回 500 等异常时,保留请求条件与日志排查,先限制访问范围;“没有显示文件”不足以证明权限已经完整验收。敏感票据先留在独立受保护存储中,核清权限后再决定是否上传。
本例上传上限为 10 MB。超限时先压缩照片或拆分文件,再看应用日志与代理限制,不把所有限制直接调到无限大。重要发票另留原件或独立副本,不把唯一资料交给尚未练习恢复的新实例。
搜索不对,先检查记录怎么写的
同一位置不要混用“书房柜子”“工具柜”“右边柜子”三个近似名字。搜索结果太多时先补型号与用途,再考虑标签;仅仅增加一批同义标签,反而可能让家人更难维护。
物品存在而图片打不开,先查 /data 的挂载、文件和权限。登录失败时区分密码错误、账号所在组和访问地址,别先重建空数据库。容器反复退出,则查看日志、实际内存上限、整机剩余内存与磁盘。某张照片上传失败并不能直接证明 VPS 配置不够。
备份整个 data,保留密钥
本例采用 SQLite 和本地附件,完整恢复需要 data、Compose 和含 pepper 的 .env。CSV 导出可用于核对清单,但不能据此推断账号、附件和应用设置都已保存。若以后改成 PostgreSQL 或对象存储,备份范围也要重新制定。
在服务器维护窗口执行下列冷备。应用停止后再归档;中途失败会尝试重启原服务,未完成文件保留 .partial 后缀,不当作成功备份。
set -eu
cd /srv/homebox
umask 077
mkdir -p /srv/homebox-backups
snapshot=$(mktemp -d /srv/homebox-backups/cold-XXXXXX)
cid=$(docker compose ps -q homebox)
test -n "$cid"
trap 'docker compose start homebox >/dev/null' EXIT
docker compose stop -t 60 homebox
state=$(docker inspect --format '{{.State.Status}} {{.State.OOMKilled}} {{.State.ExitCode}}' "$cid")
case "$state" in
"exited false 0"|"exited false 143") ;;
*) printf '未确认正常停止,拒绝归档:%s\n' "$state" >&2; exit 1 ;;
esac
tar --numeric-owner -czpf "$snapshot/instance.tar.gz.partial" \
-C /srv/homebox compose.yaml .env data
tar -tzf "$snapshot/instance.tar.gz.partial" >/dev/null
mv "$snapshot/instance.tar.gz.partial" "$snapshot/instance.tar.gz"
(cd "$snapshot" && sha256sum instance.tar.gz > SHA256SUMS)
docker compose start homebox
trap - EXIT
printf '备份目录:%s\n' "$snapshot"
将归档与校验文件加密保存到另一台设备。包中可能有家庭财产、票据、账号与密钥,不放进网站可下载目录。校验通过只能证明归档字节一致,仍需从空目录恢复。
先确认测试主机有额外资源,把 snapshot 换成实际目录。以下只解压自己创建的可信归档,不操作原实例目录。
set -eu
snapshot=/srv/homebox-backups/cold-实际后缀
(cd "$snapshot" && sha256sum -c SHA256SUMS)
restore=$(mktemp -d /srv/homebox-restore.XXXXXX)
tar --numeric-owner -xzpf "$snapshot/instance.tar.gz" -C "$restore"
cd "$restore"
在这个恢复目录保存 compose.restore.yaml。副本使用相同版本、相同 pepper 与独立数据,关闭网络、不发布端口,避免重复运行外部集成。
services:
homebox:
image: ghcr.io/sysadminsmedia/homebox:0.27.1@sha256:9d0b64776c694f018c0ca06faf52105a33ca376024f46bb58e6ab0e2b728bb61
network_mode: none
restart: "no"
environment:
TZ: Asia/Shanghai
HBOX_MODE: production
HBOX_AUTH_API_KEY_PEPPER: ${HBOX_AUTH_API_KEY_PEPPER:?pepper required}
HBOX_OPTIONS_ALLOW_REGISTRATION: "false"
HBOX_OPTIONS_ALLOW_ANALYTICS: "false"
HBOX_OPTIONS_GITHUB_RELEASE_CHECK: "false"
HBOX_WEB_MAX_UPLOAD_SIZE: "10"
volumes:
- ./data:/data
mem_limit: 512m
保持在该目录执行;等待启动就绪后,再从容器内部检查状态接口:
project="homebox-recovery-$(basename "$restore" | tr 'A-Z.' 'a-z-')"
docker compose -p "$project" -f compose.restore.yaml up -d
docker compose -p "$project" -f compose.restore.yaml logs --tail=80 homebox
docker compose -p "$project" -f compose.restore.yaml exec -T homebox \
wget -qO- http://127.0.0.1:7745/api/v1/status
副本没有网络和对外端口,不能直接在电脑浏览器打开。完整验收还需通过容器内的应用 API,或有严格出站限制的受控测试环境,核对原账号、小组、物品字段、位置、数量、图片与附件字节;再新增测试记录并重启确认保留。只拿到状态接口响应时,保持“数据恢复待验”,不能宣称完整恢复。
验完在该目录执行 docker compose -p "$project" -f compose.restore.yaml stop,保留数据。正式换机前先停止旧实例,核对域名和集成,再只让一个实例继续提供服务。
升级前用原版本恢复一次
先阅读目标版本发布说明,完成整目录冷备,并用同版本副本验证恢复。保留旧镜像完整标识和 Compose 配置,再修改版本及 digest,拉取并重建。检查原账号、物品搜索、照片、附件和新增记录,不能只看首页。
新版本迁移过数据库后,旧镜像未必能读新数据。需要退回时,恢复升级前整套 data、.env 和旧配置,在独立目录验证后接管。旧 hay-kot 项目、当前普通镜像与 rootless 镜像之间的迁移另按对应文档处理,不把更换镜像名当成完整升级流程。
推荐码:KuZhuJi




