家里东西多了以后总会遇到一个让人抓狂的瞬间明明刚买回来的设备过两个月就忘了塞在哪个箱子。与其每次靠记忆翻箱倒柜不如把每一件资产的位置、照片、价格、保修信息都收进一个数据库。最近我在飞牛fnOS上部署了 HomeBox一个开源、轻量的物品资产管理工具把“家里有什么、东西在哪、值多少钱、什么时候过保”这些事全部标准化。实际用下来HomeBox 比想象中更贴近家庭场景它不像 ERP 系统那么重没有复杂的审批流工单学一次就能上手。这篇文章会从零讲清楚为什么我选了 HomeBox飞牛上怎么规划目录、写 Compose 文件、启动访问以及长期运行必须处理的备份、升级和几个容易踩的坑。适合已经装好飞牛、想把家里物品做一次数字化的朋友也适合折腾过 Docker 但还在找合适资产管理方案的用户。1. 为什么用 HomeBox 管物品把“找东西”变成“查数据库”1.1 HomeBox 能管到哪一层从整间房子到抽屉里的充电器HomeBox 的核心单位是“物品”一个物品可以是一台电视、一把螺丝刀、一包备用纽扣也可以是一份纸质说明书扫描件。它的数据模型不复杂但恰好覆盖了家庭资产的常见信息物品名称、数量、存放位置、分类、标签、图片、购买日期、价格、保修到期时间、供应商和备注。你可能觉得这些用 Excel 也能记但 HomeBox 强在位置体系和标签搜索。位置支持层级嵌套比如“家 杂物间 置物架 收纳箱 C”每一层都可以挂物品。购买信息、发票照片和说明文档能直接附在物品卡片上以后要保修、要找发票不用再去翻聊天记录或邮箱。它对硬件的占用也极小。一个几十块钱的小主机、一台淘汰的旧笔记本只要能跑飞牛跑 HomeBox 基本没有感知。镜像也不大内存占用长期维持在几十兆这个量级完全不会影响 NAS 上其他服务。1.2 为什么我选了飞牛当底座而不是群晖或威联通飞牛最吸引我的点不是“免费”两个字而是它在 Docker 体验上做得很顺手。系统基于 Debian自带 Docker 和 ComposeWeb 管理界面里的“项目”功能可以直接粘贴 compose 文件并创建容器不用专门开 SSH 敲长命令想细调的时候又能随时进终端两者都有。相比群晖飞牛把 DOCKER 的权限和路径暴露得更直接新手容易理解“数据文件夹在哪个目录、备份该拷哪一块”。相比威联通飞牛在国产中文环境里的资料和社区讨论更丰富遇到问题能搜到的教程数量明显更多。当然群晖威联通也能跑 HomeBox只是飞牛的上手成本更低。我一直觉得家庭资产管理工具最怕“记录两次”。如果你用 Excel手机查不方便如果你写在备忘录没有图片和位置结构如果上一个自建系统又太重根本坚持不下去。HomeBox 的定位刚好卡在中间够轻、够自由、数据归自己。2. 部署前的三步准备目录、端口与镜像源2.1 数据目录别放进系统盘很多新手装 HomeBox 失败问题不出在镜像而是随便找了个路径挂载最终数据散落在系统盘或者临时目录里。HomeBox 默认把数据文件写到容器内的/dataCompose 里通过卷挂载映射到宿主机某个目录。这个目录一定要放在飞牛的存储盘里而不是系统分区。我在飞牛文件管理里先建了一个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.ioHomeBox 的官方镜像是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_LEVELinfo - HBOX_LOG_FORMATtext - HBOX_WEB_MAX_UPLOAD_SIZE10第一次部署时我特意没有加HBOX_OPTIONS_ALLOW_REGISTRATIONtrue因为新版 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 -dHomeBox 会自动重建容器并暴露到新端口。记得浏览器里访问新端口别再用旧地址。6.2 数据目录权限导致启动报错如果你用 SSH 手工创建了data目录但目录权限不是容器内用户能访问的会出现挂载目录后无法读写数据库的错误。日志里常有permission denied字样。先确认容器内运行的用户 IDdocker exec -it homebox id然后再宿主机上把数据目录所有权改成对应 UID。如果输出是 uid1000就执行chown -R 1000:1000 /vol1/1000/docker/homebox/data如果此前容器已经启动并写了部分文件最好先停止容器再改权限改完重启。在飞牛文件界面直接创建的目录通常没有这个问题权限坑主要发生在 SSH 手工操作时。6.3 中文界面与语言设置HomeBox 界面默认可能是英文但设置里一般可以切换语言找到语言选项改成中文即可。部分细节如果还没完整汉化配合浏览器翻译也能顺畅使用。更关键的是物品名称一定要坚持用中文。HomeBox 的搜索是直接匹配文本的你用中文命名、中文描述、中文标签搜索“充电器”“扳手”“药箱”时结果才准确。语言切换只影响界面不影响你录入的数据本身。6.4 与飞牛其他服务的配合HomeBox 不需要单独的手机 App手机浏览器访问首页后用“添加到主屏幕”就能得到一个类似原生应用的口子平时查找物品和扫码都方便。说明文档、发票这类文件我通常仍然放在飞牛的文件系统里归类到对应目录然后在 HomeBox 里记录文件的存放位置。这样 HomeBox 负责物品索引飞牛负责实际文件存储各管各的分工不会把 HomeBox 的数据库撑得很大。如果你有拍照扫描一类需求可以把扫描文件直接落到飞牛共享目录再按说明文档挂到对应物品下。坚持一段时间后HomeBox 会逐渐从一个“物品清单”变成一个真正属于家庭的资产查找系统。用下来我最想提醒后来者的一句话是位置树千万别建得太细。一开始我按抽屉建位置觉得非常精确结果搬家一次就体会到什么叫返工成本。后来我把位置收到“房间 柜子”把“哪个抽屉”写进备注和标签维护成本立刻降下来家人用起来也更顺。你可以借鉴这个思路先跑通再优化千万别一开始就追求尽善尽美。