买过的转接头找不到，又买一枚；电器要维修，发票和型号却在不同地方。需要记下的往往是东西放在哪、属于谁、带了什么附件。Homebox 可以记录物品、位置、图片和相关文件，适合从一间书房或一个工具柜开始整理。
不必第一次就把全屋所有东西录进去。先选经常找不到、需要保修或需要追踪附件的物品，建立能查到的记录。这篇部署私人实例，再走完录入、搜索、附件和备份流程；不会把物品库当作实时定位系统，东西换了地方仍然需要更新记录。
先定位置，再录物品
位置名称按家里实际找东西的方式安排，例如“书房—右侧抽屉”“工具柜—第二层”。分类描述物品是什么，位置描述它在哪里，两者不要混成一棵难以维护的目录。一枚转接头可以属于配件分类，同时放在电脑包里。
物品名写能分辨的型号或特征。三条都叫“充电器”，搜索后还得逐张看照片；“笔记本 65W USB-C 充电器”就更容易识别。价格、购买时间和保修期限按已有票据填写，没有依据就留空，不靠回忆凑出准确日期。
拍一张物品全貌，再拍型号标签，避免把家庭住址、门锁密码或其他私人信息一起拍进去。附件可以放说明书或发票，但访问物品库的人也可能访问这些文件，需要安排家庭账号与分享范围。
新实例使用当前维护的镜像
Homebox 当前维护项目的容器入口为 ghcr.io/sysadminsmedia/homebox，不要从旧教程随意混用不同维护者的版本。下面选择普通镜像；rootless 与 hardened 镜像有额外的运行用户和目录权限要求，不把它们的参数直接套到本例。
服务器已安装 Docker Engine 和 Compose 插件，账号能运行 Docker。Caddy 在宿主机提供 HTTPS，items.example.com 是自己的域名示例。数据全部挂载到 /data，这个目录需要持久保存。
mkdir -p /opt/homebox/data
cd /opt/homebox
umask 077
printf 'HBOX_AUTH_API_KEY_PEPPER=' > .env
openssl rand -base64 48 >> .env
chmod 600 .env
当前项目建议设置 API Key pepper，它是服务端保护 API Key 哈希的随机秘密。生成后保存进配置和备份，不每次启动重新生成。它不是账号密码，恢复时也需要保持对应配置，不能把它当成随时可以删的临时文件。
保存为 compose.yaml。初始化期间允许注册，但入口仅在宿主机回环地址可访问；家庭账号建立后再关闭注册。
services:
homebox:
image: ghcr.io/sysadminsmedia/homebox:latest
restart: unless-stopped
ports:
- "127.0.0.1:3100:7745"
env_file: .env
environment:
TZ: Asia/Shanghai
HBOX_MODE: production
HBOX_OPTIONS_ALLOW_REGISTRATION: "true"
volumes:
- ./data:/data
首次拉取当前镜像后，记录摘要并固定到验证过的版本。后续升级前先阅读发布说明，特别是数据与认证相关变化。若实际使用 rootless 或 hardened 镜像，按对应文档设置数据目录所有者，不能用目录对所有人可写来掩盖权限问题。
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 homebox
curl -I http://127.0.0.1:3100/
检查应用读取到的数据库和存储位置，录入一条测试记录后重建容器，再确认还在。网页暂时能登录，但数据没落进挂载目录，通常要到下一次更新才暴露出来，提前验证能少丢一批记录。
家庭账号建立以后限制入口
先从自己的电脑通过 SSH 转发访问本机 13100 端口，替换 SSH 账号和服务器地址。按注册与小组流程建立自己和家庭成员的账号，确认各人应加入的组。
ssh -N -L 13100:127.0.0.1:3100 [email protected]
账号建立完成，把 HBOX_OPTIONS_ALLOW_REGISTRATION 改为 "false"，再运行 docker compose up -d 应用变更。用未登录窗口检查注册已受限，不把“登录成功”当成入口设置完成。
需要手机访问时，宿主机 Caddy 添加如下站点段，验证后重载，并确保 DNS 与入站 80、443 正常。代理在容器里时使用共享 Docker 网络中的服务地址。
items.example.com {
reverse_proxy 127.0.0.1:3100
}
如果物品信息只给家人使用，也可以把访问范围限制在 VPN。用普通成员账号核对小组、物品和附件，不能一直在管理员界面里判断所有人的权限。对外分享或打印带入口的标签时，另用未登录设备检查它实际能打开什么。
第一轮只录一个抽屉
创建实际位置，录入十来件常用配件，每件写清名称、数量与位置，上传一张能辨认的照片。相关附件放在对应记录里，不要让说明书成为没有归属的一堆文件。录入一批后，离开编辑页面再用搜索找回几件物品。
需要记录一套组合物品时，先考虑以后怎么查。例如工具箱和箱内工具可能分别建记录，备注它们的关系；一套很少拆分的附件也可以先作为同一件物品管理。结构按使用方式决定，不为了使用每个功能把日常录入变复杂。
库存数量必须在使用后更新，尤其是电池、滤芯和消耗品。Homebox 中显示还有三个，可能只是上一次录入的数字。给更新设一个简单习惯，例如取出最后一份时马上修改，比每个月等想起来再全面核对更容易保持可信。
物品搬到另一间房时更新位置，借给别人则记录时间与去向。涉及借用和保修的记录保留事实，不把备注写成没有来源的购买承诺。找到东西以后，也要把它放回系统记录的位置，否则位置字段很快失去作用。
标签和附件要实际打开一次
需要实体标签时先打印少量测试，贴到不影响设备铭牌的位置，再用手机扫描检查入口、登录要求和物品对应关系。二维码通常提供查找入口，不会自动测出物品的新位置。移动物品以后，软件里的位置仍要更新。
纸张、胶材和打印尺寸会影响可读性。标签小到难扫时先调整排版，不要为了好看省掉可辨认的文字编号。离开家里的网络再试一次，也能发现标签域名只在某个局域网里可解析的问题。
发票和说明书上传以后，下载一份核对能打开。上传失败先看文件大小、格式和应用设置；反向代理的限制也可能参与，但不应只把所有限制调到无限大。重要票据另外保留原件或独立副本，不把唯一资料交给还没练习恢复的新服务。
搜索不对，先检查记录怎么写的
只按一句非常模糊的名称搜索，结果可能很多。物品名写型号和用途，备注写使用场景，位置保持一致，往往比不停加标签更有效。相同位置不要同时使用“书房柜子”“书房工具柜”“工具柜”三个近似名字。
图片丢失或附件报错时，检查数据挂载、文件权限和存储配置。记录还在数据库里，不代表附件文件也在。只更新镜像而未保存数据目录，可能让页面和文件状态不同，需要从日志与目录核对。
忘记密码时按当前邮件或管理员恢复流程处理。先验证账号恢复渠道，再让其他家人长期依赖这个库；没有配置邮件就不能假定重置链接一定会发送。共享账号看起来省事，但也让撤销某一位成员访问变得困难。
备份整个 data，保留密钥
本例的持久数据在 data，配置在 Compose 与 .env。若后来改用其他数据库或对象存储，备份范围也随之改变，不能继续套这份小实例流程。先核对实际文件落点，再定备份任务。
cd /opt/homebox
mkdir -p /opt/backups
docker compose stop homebox
tar -czf "/opt/backups/homebox-$(date +%F-%H%M).tgz" compose.yaml .env data
docker compose start homebox
停止应用后打包取得一致副本，失败也要恢复服务。备份中有家庭财产信息、票据和 pepper，限制读取，并复制到不同存储位置。磁盘剩余容量不足时，打包可能失败，不靠看到文件名就认定备份可用。
恢复演练用原版本，在独立目录和不同回环端口启动，暂时不接正式域名。检查物品、位置、账号组和附件，再扫描一个测试标签核对目标。升级出现数据库变化后，回退需要旧镜像与升级前完整数据一起恢复。
等一个抽屉的记录确实能帮忙找东西，再增加工具柜、电器和保修资料。定期核对常用位置，把已经处理掉的物品移出日常列表，留下必要的历史。记录保持贴近实际使用，比一次录满全屋、以后再也不更新更有用。