家里东西多了以后，总会遇到一个让人抓狂的瞬间：明明刚买回来的设备，过两个月就忘了塞在哪个箱子。与其每次靠记忆翻箱倒柜，不如把每一件资产的位置、照片、价格、保修信息都收进一个数据库。最近我在飞牛（fnOS）上部署了 HomeBox，一个开源、轻量的物品资产管理工具，把“家里有什么、东西在哪、值多少钱、什么时候过保”这些事全部标准化。
实际用下来，HomeBox 比想象中更贴近家庭场景：它不像 ERP 系统那么重，没有复杂的审批流工单，学一次就能上手。这篇文章会从零讲清楚，为什么我选了 HomeBox，飞牛上怎么规划目录、写 Compose 文件、启动访问，以及长期运行必须处理的备份、升级和几个容易踩的坑。适合已经装好飞牛、想把家里物品做一次数字化的朋友，也适合折腾过 Docker 但还在找合适资产管理方案的用户。
1. 为什么用 HomeBox 管物品：把“找东西”变成“查数据库”
1.1 HomeBox 能管到哪一层：从整间房子到抽屉里的充电器
HomeBox 的核心单位是“物品”，一个物品可以是一台电视、一把螺丝刀、一包备用纽扣，也可以是一份纸质说明书扫描件。它的数据模型不复杂，但恰好覆盖了家庭资产的常见信息：物品名称、数量、存放位置、分类、标签、图片、购买日期、价格、保修到期时间、供应商和备注。
你可能觉得这些用 Excel 也能记，但 HomeBox 强在位置体系和标签搜索。位置支持层级嵌套，比如“家 > 杂物间 > 置物架 > 收纳箱 C”，每一层都可以挂物品。购买信息、发票照片和说明文档能直接附在物品卡片上，以后要保修、要找发票，不用再去翻聊天记录或邮箱。
它对硬件的占用也极小。一个几十块钱的小主机、一台淘汰的旧笔记本，只要能跑飞牛，跑 HomeBox 基本没有感知。镜像也不大，内存占用长期维持在几十兆这个量级，完全不会影响 NAS 上其他服务。
1.2 为什么我选了飞牛当底座，而不是群晖或威联通
飞牛最吸引我的点不是“免费”两个字，而是它在 Docker 体验上做得很顺手。系统基于 Debian，自带 Docker 和 Compose，Web 管理界面里的“项目”功能可以直接粘贴 compose 文件并创建容器，不用专门开 SSH 敲长命令，想细调的时候又能随时进终端，两者都有。
相比群晖，飞牛把 DOCKER 的权限和路径暴露得更直接，新手容易理解“数据文件夹在哪个目录、备份该拷哪一块”。相比威联通，飞牛在国产中文环境里的资料和社区讨论更丰富，遇到问题能搜到的教程数量明显更多。当然，群晖威联通也能跑 HomeBox，只是飞牛的上手成本更低。
我一直觉得，家庭资产管理工具最怕“记录两次”。如果你用 Excel，手机查不方便；如果你写在备忘录，没有图片和位置结构；如果上一个自建系统又太重，根本坚持不下去。HomeBox 的定位刚好卡在中间：够轻、够自由、数据归自己。
2. 部署前的三步准备：目录、端口与镜像源
2.1 数据目录：别放进系统盘
很多新手装 HomeBox 失败，问题不出在镜像，而是随便找了个路径挂载，最终数据散落在系统盘或者临时目录里。HomeBox 默认把数据文件写到容器内的/data，Compose 里通过卷挂载映射到宿主机某个目录。这个目录一定要放在飞牛的存储盘里，而不是系统分区。
我在飞牛文件管理里先建了一个docker共享目录，然后在下面建了homebox目录，Compose 文件和数据文件都放这里。飞牛的具体路径通常类似/vol1/1000/docker/homebox，但不同机器、不同盘位会有差异，你以文件管理器里实际看到的路径为准。
如果你有一块专门用于备份的硬盘，建议同时建一个backup目录，后面做数据库备份时直接用，不用临时找地方。目录建好后，检查一下权限，Web 界面创建的目录一般没有大问题，但如果是用 SSH 手工创建的，要确认当前用户有读写权限。
2.2 端口检查：别一上来就被 7745 卡住
HomeBox 默认使用宿主机端口 7745。飞牛上跑着各种 Docker 应用，端口冲突很常见。如果之前部署过其他服务占用 7745，容器会反复启动失败，日志里会报端口绑定错误。
部署前可以先在飞牛上跑一条命令确认端口占用：
ss -lntp | grep 7745没有任何输出，说明端口空闲。如果已有服务监听，不必强行释放，直接在 Compose 里把宿主机端口改掉，比如7746:7745。右边 7745 是容器内部固定端口，不要动；左边是宿主机开放端口，可以随意换。
2.3 镜像源：HomeBox 镜像放在了 ghcr.io
HomeBox 的官方镜像是ghcr.io/sysadminsmedia/homebox:latest，托管在 GitHub 的容器仓库上。国内部分网络环境拉取 ghcr.io 会比较慢，甚至超时。
飞牛 Docker 设置里一般可以配置镜像加速。如果你拉取失败，可以先去飞牛的系统设置或 Docker 设置里补一个支持 ghcr 的加速地址，也可以先在宿主机登录一次容器仓库验证连通性：
docker pull ghcr.io/sysadminsmedia/homebox:latest如果长时间停留在 Pulling，大概率是网络问题。把镜像拉下来之后，后续部署几乎不会有坑。
3. 用 Docker Compose 把 HomeBox 跑起来
3.1 一份能直接用的 Compose 文件
我最终使用的 Compose 文件很简单，四个核心配置：镜像、容器名、端口、数据卷。
services: homebox: image: ghcr.io/sysadminsmedia/homebox:latest container_name: homebox restart: unless-stopped ports: - "7745:7745" volumes: - ./data:/data environment: - HBOX_LOG_LEVEL=info - HBOX_LOG_FORMAT=text - HBOX_WEB_MAX_UPLOAD_SIZE=10第一次部署时，我特意没有加HBOX_OPTIONS_ALLOW_REGISTRATION=true，因为新版 HomeBox 在首页会直接展示注册入口，第一个注册的用户自动成为管理员。如果你发现首页只有登录框没有注册入口，再把这个环境变量加上并重建容器。
有个细节说一下：我没有在 Compose 里写version字段。新版本 Docker Compose 已经把版本号废弃了，写上反而可能出现 schema 版本警告。飞牛的 Docker 界面和 Docker CLI 都支持这种省略写法的 Compose 文件。
3.2 启动、查日志和第一次注册
在飞牛的 Docker 项目界面，直接新建项目，项目名填homebox，把上面的 YAML 粘贴进去，保存启动即可。如果你习惯终端，也可以 SSH 到飞牛目录下执行：
docker compose up -d启动后看日志：
docker logs -f homebox正常情况下会看到服务启动日志，没有明显 ERROR。随后打开浏览器访问http://飞牛IP:7745，看到欢迎页后，注册第一个账号。第一个账号会被识别为管理员，直接进后台就能创建分类、位置和物品。
这一步很容易被忽略：注册完第一件事就是确认菜单里的“管理”入口是否可用。如果可用，说明你这个账号权限正确。后面家人要用，直接用同一账号登录就行，没必要再开多个用户，家庭场景下简单反而省事。
3.3 环境变量怎么按需调整
上面 Compose 里的几个环境变量，日常只需要关心两个。
HBOX_WEB_MAX_UPLOAD_SIZE控制上传附件大小，单位是 MB，默认值 10 意味着单张照片或单个 PDF 不超过 10MB。如果你习惯把说明书扫描成清晰的多页 PDF，可以改成 20 或 30，稍微留点余地。
HBOX_LOG_LEVEL控制日志详细程度。平时保持 info 就行，排查问题时可以临时改成 debug，再执行docker compose up -d会创建一个新的容器实例，让日志输出更详细。不过要注意，改完之后日志目录会变大，问题定位完记得改回 info。
4. 数据模型设计：位置树、分类、标签，少一个都后悔
4.1 先把“家”拆成位置树
HomeBox 的所有物品最终都会落在一个位置上。如果位置树一开始没设计好，后面录到第两百个物品时会非常痛苦。我自己一开始按“房间 > 柜子 > 抽屉 > 盒子”建了四层，后来发现太细了，搬一次家就要改几十个位置。
建议把位置控制在三层以内，以“房子 > 房间 > 储物单元”为最稳妥的粒度。
我的家 ├── 客厅 │ ├── 电视柜 │ └── 玄关抽屉 ├── 书房 │ ├── 书桌 │ └── 工具柜 └── 杂物间 ├── 收纳箱 A └── 收纳箱 B在这个设计下，“左数第二格抽屉”“靠墙蓝色储物箱”这类更细的信息，应写进物品描述或标签里，而不是继续拆位置节点。位置太细，后面细化调整的成本直线上升。
4.2 分类不要直接照抄别人的清单
分类的作用是让同类物品被快速筛出来，所以应该符合你的生活习惯。比如摄影爱好者可以设“相机与镜头”，有宠物的家庭可以设“宠物用品”，药用箱可以设“医药物资”。
我的分类比较简练，也没过度细拆：数码设备、家用电器、电动工具、纸质文件、衣物箱包、药品护理、收藏纪念。每种分类下面不再建子分类，需要精确区分时交给标签，分类和标签配合用，比一棵无限深的分类树好维护得多。
4.3 标签是“查得到”的关键
标签是 HomeBox 里最灵活的信息维度。当一件物品同时属于多个维度时，标签能帮你干净地打上多个标记。我常用的标签有这些类型：
- 权益类：贵重、易碎、租赁、待报废
- 时间类：保修-2027、年检-2026
- 状态类：待处理、缺失、需要找
- 场景类：露营、维修用、办公室
搜索时输入标签关键词，结果很精准。比如我想找“露营时带的小燃气炉”，不用翻位置，直接搜“露营”标签就行。
4.4 录入物品时，哪些字段值得认真填
不是每个字段都需要填，但下面几个字段我建议尽量写全：
- 名称：建议包含品牌和型号，比如“索尼 WH-1000XM5”，而不是“头戴耳机”。
- 描述：写清楚物品的配件清单、颜色、特别需要注意的事项。
- 数量：同款物品一次买了多个时，填数量比分别录多条更直观。
- 价格与购买日期：对未来做家庭资产盘点、保险理赔都有用。
- 保修到期：HomeBox 仪表板能帮你留意哪些东西快过保，比纸质保修卡可靠。
- 照片和附件：给物品拍一张正面照，再把发票 PDF、说明书扫描件上传，以后维权时不用翻邮箱。
4.5 批量导入和二维码标签
如果家里已经有几百件物品要录，一条条手填不现实。HomeBox 的管理后台支持 CSV 导入。我们可以先用 Excel 整理物品清单，把列名和系统字段对齐，导成 CSV 之后一次性导入。第一次导入前建议先导出官方示例文件看表头结构，不要盲目自定义。
二维码是 HomeBox 一个很实用的功能。物品详情页可以生成二维码，打印出来贴在收纳箱侧面或者设备背面。后面想找东西，手机扫一下就能直接跳到该物品的页面。如果某些版本没有现成二维码按钮，就把物品页面 URL 复制到二维码生成工具里，效果一样。
5. 备份、恢复与版本升级：长期使用不能少的三件事
5.1 说到底，备份只是一个 SQLite 文件
HomeBox 默认把数据保存在 SQLite 数据库里。Compose 中映射了./data:/data，宿主机对应目录下会有一个homebox.db文件，所有物品数据、位置、分类和设置都在里面。
因此备份的粒度非常小：备份整个data目录就够了。家庭使用场景下，这个数据库通常只有几兆到几十兆，每天备份一份成本极低。
我建议至少做两种备份：
- 数据库文件备份：定期把
data目录打包到另一块硬盘或飞牛其他存储区间。 - 系统导出备份：在 HomeBox 管理后台使用官方导出功能，把全部物品导出成 JSON 或 CSV，存在飞牛文件目录里。这个备份适合灾难恢复，万一数据库文件损坏，可以用导出数据重新建库再导入。
5.2 在飞牛上做自动备份
飞牛系统本身有定时任务能力，也可以直接用 SSH 写 crontab。我的做法是每天凌晨 4 点，把data目录打包到备份目录：
tar -czf /vol1/1000/docker/backup/homebox-$(date +\%F).tar.gz -C /vol1/1000/docker/homebox/data .把这条命令放进定时任务后，每天早上都能得到一份带日期的压缩包。为了避免旧备份堆满硬盘，可以再写一条清理任务，只保留最近 30 天：
find /vol1/1000/docker/backup/ -name "homebox-*.tar.gz" -mtime +30 -delete如果你所在的飞牛存储池支持快照功能，也可以直接把整个homebox目录加入快照计划。快照还原速度快，而且不依赖 tar 备份是否跨磁盘。
提示：如果对在线备份的一致性要求很高，最稳妥的办法是先在备份窗口停掉容器再打包，比如
docker stop homebox。家庭使用量不大，凌晨停几十秒完全不影响体验。
5.3 恢复实战：换机、重装之后怎么办
恢复流程比想象中简单。在新的飞牛环境或重装系统后，先把同样的目录结构建好，把备份文件解压到原来的data目录，再启动容器，HomeBox 就会读到原来的数据库，所有物品都在。
如果遇到数据库文件损坏这种极端情况，可以从两个方向补救：
- 用之前导出的 JSON/CSV 文件，在新库里重新导入。
- 用最近一份 tar 备份里的
homebox.db覆盖损坏文件。
所以我前面强调，数据库备份和系统导出备份一定要同时做。一个应对快速恢复，一个应对数据完整性意外。
5.4 容器升级时怎么不丢数据
HomeBox 更新比较频繁，升级方式是重新拉取镜像并重建容器：
cd /vol1/1000/docker/homebox docker compose pull docker compose up -d因为数据卷一直挂载在同一个宿主机目录，容器重建不会覆盖data里的数据库，所以升级本身是安全的。但升级前还是建议至少做一次数据库文件备份，以防新版镜像启动时有自动迁移逻辑，万一迁移过程出问题还能回退。
升级后打开日志看一眼：
docker logs homebox如果出现数据库相关错误，立即停止容器，把备份还原回去，再回到原来的镜像版本。我升级过好几次，目前都没遇到问题，但“先备份再升级”这条纪律我一直没破。
6. 飞牛环境里最常见的几个坑
6.1 端口被占，日志反复启动失败
有几次容器一直处于 “Restarting” 状态，排查后发现日志里有bind: address already in use，基本就是宿主机 7745 端口被其他服务占了。
解决办法不是去杀其他服务，而是直接修改 Compose 端口映射。比如改成：
ports: - "7746:7745"改完执行docker compose up -d，HomeBox 会自动重建容器，并暴露到新端口。记得浏览器里访问新端口，别再用旧地址。
6.2 数据目录权限导致启动报错
如果你用 SSH 手工创建了data目录，但目录权限不是容器内用户能访问的，会出现挂载目录后无法读写数据库的错误。日志里常有permission denied字样。
先确认容器内运行的用户 ID：
docker exec -it homebox id然后再宿主机上把数据目录所有权改成对应 UID。如果输出是 uid=1000，就执行：
chown -R 1000:1000 /vol1/1000/docker/homebox/data如果此前容器已经启动并写了部分文件，最好先停止容器再改权限，改完重启。在飞牛文件界面直接创建的目录通常没有这个问题，权限坑主要发生在 SSH 手工操作时。
6.3 中文界面与语言设置
HomeBox 界面默认可能是英文，但设置里一般可以切换语言，找到语言选项改成中文即可。部分细节如果还没完整汉化，配合浏览器翻译也能顺畅使用。
更关键的是：物品名称一定要坚持用中文。HomeBox 的搜索是直接匹配文本的，你用中文命名、中文描述、中文标签，搜索“充电器”“扳手”“药箱”时结果才准确。语言切换只影响界面，不影响你录入的数据本身。
6.4 与飞牛其他服务的配合
HomeBox 不需要单独的手机 App，手机浏览器访问首页后，用“添加到主屏幕”就能得到一个类似原生应用的口子，平时查找物品和扫码都方便。
说明文档、发票这类文件，我通常仍然放在飞牛的文件系统里，归类到对应目录，然后在 HomeBox 里记录文件的存放位置。这样 HomeBox 负责物品索引，飞牛负责实际文件存储，各管各的分工，不会把 HomeBox 的数据库撑得很大。
如果你有拍照扫描一类需求，可以把扫描文件直接落到飞牛共享目录，再按说明文档挂到对应物品下。坚持一段时间后，HomeBox 会逐渐从一个“物品清单”变成一个真正属于家庭的资产查找系统。
用下来我最想提醒后来者的一句话是：位置树千万别建得太细。一开始我按抽屉建位置，觉得非常精确，结果搬家一次就体会到什么叫返工成本。后来我把位置收到“房间 + 柜子”，把“哪个抽屉”写进备注和标签，维护成本立刻降下来，家人用起来也更顺。你可以借鉴这个思路，先跑通再优化，千万别一开始就追求尽善尽美。
