用 HomeBox 建立家庭物品台账：Docker 部署、位置层级和保修资料

搬家前找不到配件，维修时想不起购买日期，抽屉里又买了一套已经有的工具。家庭物品台账的价值通常出现在这些时刻。HomeBox 可以记录物品、位置、标签、照片与相关文件，适合整理需要查找或维护的东西。

先从一处实际空间开始，例如书房工具柜。不要急着给每个小物件拍照建档，先收录会借出、价格较高、需要保修或容易重复购买的物品。十件资料完整的记录，比几百个只有名字的条目更能检验这个台账是否有用。

HomeBox 官方物品详情界面

官方截图用于说明字段与布局，图片中的物品、价格和记录是演示数据。

部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 KuZhuJi。

当前位置比最初放在哪里更重要

位置层级按实际找东西的路线建立，例如“家／书房／工具柜”。同一件物品移走后更新位置，不要仅在备注里写“后来借出”。配件可以在说明中列清楚，重要配件另建记录时，应留下与主设备的关系，避免看见独立条目却不知属于哪件设备。

名字写到能区分实物即可。例如型号、容量、颜色或一张清楚的照片。序列号能帮助核对维修与保修，但它不适合出现在公开截图中。购买日期、保修期限和票据应相互对照，缺了原始票据时标明资料缺口，不要凭产品上市时间推算自己的购买日期。

HomeBox 是资料入口。保修申请是否成立仍取决于供应商条件和原始凭证，照片也不能代替需要的发票。上传文件之前先遮去与查找无关的付款账号、住址等信息，原件保留在自己可恢复的档案中。

当前镜像要求持久保存 API 密钥 pepper

下面采用维护中的 ghcr.io/sysadminsmedia/homebox:latest，不是早期项目的旧镜像。当前配置要求 HBOX_AUTH_API_KEY_PEPPER 至少有 32 字节，官方建议用 openssl rand -base64 48 生成。它用于 API 密钥哈希，改变它会使已发出的 API 密钥失效，不能在重启时重新生成。

VPS 需要 Docker Engine 与 Compose 插件。本例使用常规镜像和宿主目录 /opt/homebox/data，数据挂载到容器 /data，网页容器端口为 7745。不同镜像变体的用户权限有所区别，不能只换成 rootless 标签却不处理目录所有权。

mkdir -p /opt/homebox
cd /opt/homebox
mkdir -p data
umask 077
printf 'HBOX_AUTH_API_KEY_PEPPER=%s\n' "$(openssl rand -base64 48 | tr -d '\n')" > .env
chmod 600 .env

建立 compose.yaml：

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:3100:7745"
    environment:
      TZ: "Asia/Shanghai"
      HBOX_LOG_LEVEL: "info"
      HBOX_LOG_FORMAT: "text"
      HBOX_OPTIONS_ALLOW_ANALYTICS: "false"
      HBOX_OPTIONS_ALLOW_REGISTRATION: "true"
      HBOX_AUTH_API_KEY_PEPPER: "${HBOX_AUTH_API_KEY_PEPPER:?set pepper}"
    volumes:
      - ./data:/data

这里暂时允许注册，是为了通过私人隧道建立第一个账号。初始化完成后把它改成 false 并重新创建容器，不要在未注册、未验收时就开放正式域名。

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100 homebox

在自己的电脑上运行：

ssh -N -L 13100:127.0.0.1:3100 user@VPS_IP

浏览器打开 http://localhost:13100，建立账号，添加一处位置与一件物品，再上传测试照片。关闭注册后执行 docker compose up -d，退出账号核对注册入口的行为，并用已有账号重新登录。仅修改文件还不代表运行中的环境已经更新。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 KuZhuJi。配置按实际任务选择，数据库和附件另做备份。

先让另一名家人找得到东西

把台账交给实际使用者试一次：不提示位置，让他搜索某个物品，查看照片与备注，再去取出实物。若只能由建档的人理解命名，应该改字段和位置，而不是继续增加标签。

借出记录应包含对象、日期和预计归还安排，避免只写“借出”。涉及成员共用时，按当前版本的账号与组功能分配访问，先用测试账号确认它能看见什么。不要用同一个管理员账号到处登录，再把个人登录记录误当成成员权限管理。

HomeBox 物品资料与备份结构

家庭照片与票据可能比物品名称更敏感。正式使用时通过独立 HTTPS 子域名访问，代理转发到本机 3100 端口。检查登录、上传、图片缩略图和原文件下载；代理的上传大小限制与应用限制都可能影响附件，不应只看首页是否打开。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 KuZhuJi；迁移前保留数据与原有部署配置。

标签服务于检索，不必重建一套目录

“维修中”“借出”“需要配件”这类状态可以帮助筛选；“书房”若已存在于位置树，就不必同时堆进每条标签。自定义字段也先用少量条目试验，尤其是金额、日期与重复文本，字段设计变动后要抽查旧记录。

二维码或标签功能应先打印几枚试用。贴纸上的入口是否需要登录、手机扫描后看到的是哪个实例，都要核对。别把标签直接贴在会被公开转卖的设备上却忘记它指向自己的私人台账。实物离开家时，必要的交接资料另行提供，内部文件权限继续保留。

盘点可按一个位置逐步完成：检查实物是否还在、照片是否对应、配件是否齐全。台账和现实出现差异时，以核对后的实物状态更新，留住有意义的历史说明。

数据目录与 pepper 一起恢复

默认 SQLite 与附件都要随数据目录保存。停写后归档，同时保留 Compose 和 .env，把备份复制到另一处存储。下面命令不会自动完成远程保存：

cd /opt/homebox
umask 077
mkdir -p backup-out
docker compose stop homebox
sudo tar -czf "backup-out/homebox-$(date +%F-%H%M%S).tgz" data compose.yaml .env
docker compose start homebox

恢复副本采用不同本机端口，先启动同一镜像版本。除了登录，还要打开照片、下载一张测试票据，核对位置层级、日期与成员可见范围。使用过 API 密钥时，原 pepper 也必须恢复，不能因为网页能登录就认为自动化客户端一定继续可用。

正式盘点前，先完成一次小规模恢复。确认十件样本能重新取回，再让更多家庭资料进入这个系统。