前阵子整理家里的数码设备和各种线材翻箱倒柜找一根 HDMI 线找了快半小时当时就在想这些物件要是都登记在案该省多少事。于是我把目光盯上了 HomeBox 这个开源的物品资产管理工具。用了一周之后我决定把它从临时跑的旧笔记本上挪到飞牛NASfnOS上常驻。这篇文章就把整个部署过程、配置思路和踩过的坑完整记录下来给也想在 NAS 上跑一个物品管理系统的朋友参考。HomeBox 在我的理解里就是给“家里的东西”建一个数据库物品放哪、什么时候买的、保修到哪天、借给谁了、盒子说明书放在哪个抽屉这些信息全部可以录进去。它跟简单记个 Excel 表格最大的区别在于它用分类、位置、标签、自定义字段把信息串成了结构化的数据配合照片和借还记录平时查起来比翻表格爽太多。而且它是纯网页应用部署在 NAS 上之后家里任何一台设备开浏览器就能用。1. 为什么选 HomeBox以及为什么要部署在飞牛 NAS1.1 它解决的是“东西到底去哪了”的问题先说说 HomeBox 到底能管什么。简单列一下我在用的核心功能物品登记名称、数量、序列号、购买日期、价格、保修截止日、存放位置可以按层级建比如“客厅-电视柜-中间抽屉”、分类标签、自定义字段、物品照片附件、借出与归还记录、CSV 导入导出还有多用户和 API。对于家庭场景来说这些功能基本把“家里东西太多记不住”这个痛点全覆盖了。我个人的使用场景是数码产品、充电线、工具、药品、证件文件、不常穿但又舍不得扔的衣服我都会在 HomeBox 里建档。登记的时候顺手拍一张实物照发票和保修单也拍照传上去。时间长了之后你会发现它不只是一个清单更像是一个“家庭物品档案库”。特别是大件家电的保修信息房子住了几年之后谁还记得当初在哪个平台买的、哪天过保有了这个工具翻一眼就知道。前两天我怀疑家里那台显示器的保修快到期了以前得去翻电商订单、翻邮箱找发票这次在 HomeBox 里直接搜型号保修截止日期、购买渠道、发票照片全在一条记录里整个过程不到十秒。这种体验一旦习惯了就再也回不到“翻箱倒柜找说明书”的日子了。1.2 同类工具不少为什么我留下了 HomeBox在定 HomeBox 之前我也看过别的方案。最基础的是用 Excel 或者在线表格优点是零门槛缺点是维护太随意图片、关系、借还记录都很难标准化时间一久就成了僵尸表。再往上是 Snipe-IT 这种正经的 IT 资产管理系统功能很强但需要 PHP、MySQL 一套环境对家庭用户来说太重了杀鸡用牛刀。HomeBox 刚好在中间Go 语言写的单容器应用数据落在 SQLite 里没有外部数据库依赖部署起来非常轻启动也快。整个项目是开源的GitHub 上一直有人在维护界面是现代 Web 风格中文支持也还不错。对我这种“想省事但不想将就”的用户来说它是目前最平衡的选择。要注意的是 HomeBox 的侧重点在“个人/家庭物品管理”不是专业的固定资产盘点公司资产那类需求还是老老实实上 Snipe-IT别拿 HomeBox 硬撑。1.3 把服务放到飞牛 NAS 上的现实理由一开始我是临时装在一台旧笔记本上跑的后来发现长期用还是得放到 NAS。原因很简单NAS 七乘二十四小时开机服务不会因为随手关电脑就失联飞牛 OSfnOS自带 Docker 环境无论用图形界面还是用编排功能部署都很顺数据放在本机硬盘上备份、迁移、扩容都可控。另外飞牛的 Docker 功能对新手比较友好镜像拉取、容器创建、日志查看都有界面可以操作不用一上来就啃命令行。如果你之前没在飞牛上部署过任何容器照着我下面的步骤走基本不会卡住。这里多说一句飞牛系统的文件路径是类似/vol1/1000/docker这样的结构跟群晖的/volume1有点像第一次用的时候别被这个路径格式吓到。2. 部署前的准备镜像、目录和端口一次想清楚2.1 镜像地址和版本差异HomeBox 的官方镜像地址是ghcr.io/hay-kot/homebox发布在 GitHub Container Registry 上。拉取时建议用latest标签或者直接固定到当前发布的版本号比如 0.16.x。网络环境正常的情况下直接拉就行如果拉取超时多试几次或者给飞牛的 Docker 配置镜像加速源再拉。这里有个历史坑早期版本很多教程写的镜像是ghcr.io/hay-kot/homebox:mainmain 是开发分支后来项目调整了发布机制main 标签不再推荐日常使用新版本统一走 release 标签。所以如果你在网上搜到老教程注意别照搬 main 标签。版本不同数据目录也不一样。新版本的容器内数据目录是/data旧版本可能是/root/.local/share/homebox。如果你是用全新部署直接用/data就可以如果你是老版本数据要迁移过来这个差异一定要搞清楚不然容器起来了数据却“不在同一个地方”。2.2 目录规划数据必须落在宿主机容器本身是无状态的真正的数据要持久化到飞牛硬盘上。我建议在建目录之前先把结构规划好。我的做法是在飞牛的 Docker 目录下新建一个专门的文件夹/vol1/1000/docker/homebox └── datadata 目录是用来存 SQLite 数据库和上传的附件的这个目录必须映射进容器并且要定期备份。顺便说一句不要图省事把 data 直接放在/vol1根目录或者系统盘上单独划一个目录出来后续做备份、迁移都方便得多。备份的时候直接把这个 data 目录打包下载就行整个工具的数据管理就是这么简单。2.3 端口规划先想好要暴露哪个端口HomeBox 容器内部默认监听 7745 端口。我直接把它映射成宿主机的 7745 端口访问地址就是http://飞牛IP:7745。如果你的 7745 已经被别的服务占了可以映射成别的端口比如 37745访问地址相应变成http://飞牛IP:37745。这里提醒一个容易忽略的点飞牛系统自身的 Web 管理界面也占用了 HTTP 端口所以部署完 HomeBox 之后别把 HomeBox 的端口和管理后台的端口搞混。我自己就干过这事部署完打开页面跳到了飞牛的登录页还以为容器挂了实际上只是端口写错了。3. 两种部署方式照着抄就行3.1 方式一飞牛 Docker 界面图形化部署飞牛的 Docker 管理界面在系统自带的应用里打开 Docker可以直接完成拉镜像和创建容器的操作。步骤如下第一步打开 Docker 应用进入“镜像”页面在搜索框里输入ghcr.io/hay-kot/homebox点击拉取。镜像比较大的时候会有一点时间耐心等。第二步镜像拉取完成后选中镜像点击“创建容器”。容器名称建议叫homebox方便后面识别。端口映射里把容器端口 7745 映射到宿主机 7745或者你规划的其他端口协议选 TCP。第三步在“存储”配置里添加一个卷映射宿主机路径填/vol1/1000/docker/homebox/data容器路径填/data挂载权限选读写。这一步非常关键漏掉了或者填错容器路径数据不会持久化容器一删就什么都没了。第四步环境变量按需加。最基础的是HBOX_LOG_LEVELinfo执行路径和默认配置都用镜像自带的值就行。TZAsia/Shanghai也可以顺手加上让容器日志时间正常。第五步点击创建并启动。容器状态变成 Running 之后浏览器打开http://飞牛IP:7745就能看到页面了。3.2 方式二用 docker compose 一键启动如果你更想用配置文件来管理飞牛 Docker 的“编排”功能支持 docker compose。这个方法的好处是以后想改配置、迁移机器一份 YAML 文件就够不用在界面里一个个点。我目前就是用的这种方式维护升级的时候特别省事。先在 SSH 或者飞牛的文件管理里建好目录比如/vol1/1000/docker/homebox然后在编排页面新建一个项目内容如下services: homebox: image: ghcr.io/hay-kot/homebox:latest container_name: homebox restart: unless-stopped environment: - HBOX_LOG_LEVELinfo - TZAsia/Shanghai volumes: - /vol1/1000/docker/homebox/data:/data ports: - 7745:7745保存并启动后同样用http://飞牛IP:7745访问。这里的参数含义不复杂restart: unless-stopped表示容器意外退出后会自动拉起NAS 重启后也会自动把服务带上volumes里的宿主机路径要改成你自己的实际路径ports左侧是宿主机端口右侧是容器端口想换宿主端口只改左侧就行。3.3 首次启动和初始账号配置首次打开 HomeBox 页面不同版本流程有差别。新版本0.16 之后打开会直接进入初始化页面让你创建第一个管理员账号填好用户名、邮箱、密码提交就行。老版本则是默认账号adminhomebox.local密码admin登录后强制你修改密码。如果你打开看到的不是这两个流程之一八成是访问地址或者端口有问题先回容器日志看看。初始账号创建完之后建议立刻完成两件事一是把“设置”里的基本资料补全二是去用户管理页面看一眼账号和权限。家庭使用一般一个管理员账号就够没必要给每个人都开账号。后续如果担心安全问题记得把默认端口改掉或者加一层反向代理做访问控制。4. 上手配置搭建自己的物品管理体系4.1 先建分类和位置再录物品很多新手上来就急着录物品录了半天发现系统很乱。我的建议是反过来先花半个小时把分类和位置体系建好。分类可以按照你家实际情况定我这边大致是这样的数码设备、线材配件、工具、音像影音、文件证件、药品护理、厨房用品、清洁用品、衣物箱包、其他。位置按“房间-柜子/抽屉”这种层级来建比如“书房-书桌上层抽屉”“客厅-电视柜-左柜”。先用分类和位置把“骨架”搭起来再往里录物品效率和体验会完全不一样。HomeBox 的位置是支持子层级的别嫌麻烦精确到抽屉是非常值得的因为查找的时候可以一层层展开比一长串列表舒服很多。建位置的时候顺带把每个位置拍张照片传上去以后隔着系统就能看到那个抽屉大概长什么样。4.2 录入物品时哪些字段值得认真填HomeBox 的物品字段很多但不是每个都值得填。根据我实际跑了两周的经验优先级大概是这样的字段优先级填法建议物品名称高按“品牌型号用途”格式写比如“绿联 HDMI 2.1 高清线 2 米”存放位置高一定要选精确到抽屉数量高线材、囤货类尤其要准确序列号中数码产品必填保修和出二手都用得上购买日期中知道就填不知道留空保修截止日中大件家电和数码设备必填自定义字段低按需添加我加了“颜色”“规格”“购买渠道”自定义字段不用贪多够用就行。附件功能强烈推荐用起来每个物品拍一张实物照购买订单截图也传上去。照片存在 NAS 本地相比纸质的发票和说明书不怕丢也不怕潮。4.3 借还、导入导出这些功能怎么用借出与归还是我很喜欢的模块。家里总有东西会被同事朋友借走或者是自己从车库、储藏室临时调拨到别处系统里直接标记借出记录借给谁、借出日期归还的时候再操作一次就不会出现“那本书和那个工具到底去哪了”的情况。CSV 导入导出适合已经有电子表格数据的人。先导出模板按照模板字段把数据填好再导入。实测导出功能很稳定导入时要注意字段名必须跟模板一致否则会报错。批量操作的时候先导入几条测试数据确认没问题再全量导入这是老玩家的基本操作。4.4 用到的几个贴心小功能HomeBox 还有一些容易被忽略但很好用的功能全局搜索可以跨名称、标签、备注搜索我找东西基本靠它标签可以配合分类做交叉筛选比如“易碎”“需要充电”“已过保”这种灵活性标签API 对有动手能力的人是加分项可以自己写脚本做定时导出或者对接家庭自动化。对于家庭用户来说还有一个很实际的用法在浏览器里把 HomeBox 添加到桌面。电脑端用书签栏手机端用浏览器自带的“添加到主屏幕”打开之后是全屏显示用起来和原生 App 差不多。反正服务跑在飞牛 NAS 上随时开机随时用不用额外装什么客户端。5. 常见问题与踩坑记录5.1 容器起来了但页面打不开遇到这个问题先做三件事第一看容器日志飞牛的 Docker 界面里能直接看日志开头会打印监听的地址和端口确认是不是 7745第二确认浏览器访问地址用的是http而不是httpsHomeBox 默认不启用 TLS直接上 https 会显示不安全的连接或者根本打不开第三检查端口映射如果宿主机端口改了别再用默认端口访问。如果容器一直处于启动中就退出大概率是卷映射有问题或者数据目录权限不对。把映射目录删掉重建一个新的空目录再试试注意别把有数据的目录轻易删除先备份。我把常见问题整理成一张速查表方便对照排查现象可能原因排查方法页面打不开端口映射错误或地址用了 https检查映射端口和访问协议容器反复重启卷映射路径不对、目录权限问题查看容器日志重建空数据目录登录后数据为空卷映射容器路径不是 /data检查映射配置启动报数据库错误从旧版本跨版本升级恢复备份按版本逐级升级搜索不到物品搜索关键词和录入手误用短关键词或标签筛选再试5.2 数据备份与迁移备份 HomeBox 超级简单把/vol1/1000/docker/homebox/data整个目录打包下载即可。数据库文件就在里面附件也在里面。恢复的时候只要把这个目录原封不动放回去重新创建容器并映射到/data即可。要迁移到另一台机器时我一般这样做在新机器上创建同样的目录结构把备份解压进去启动同一版本的容器。如果是跨版本迁移先起一个旧版本容器确认页面正常后再考虑升级。这个顺序能最大程度避免数据库版本不兼容的问题。迁移完记得把旧机器上的容器停掉避免两个实例同时操作同一份数据造成困扰。5.3 升级版本时的注意事项HomeBox 更新频率不低升级前一定要先备份 data 目录。用 docker compose 管理的话升级很简单进入编排项目目录拉新镜像然后重建容器。界面方式就麻烦一点需要先停掉旧容器重新拉镜像再创建一次容器配置要照着原来的一步步填。升级后如果页面报数据库相关的错误大概率是版本跨度太大。这时候不要慌乱把备份恢复回去降回原版本再考虑用官方文档里推荐的迁移方式逐步升级。我踩过一次教训就是大版本升级前一定看发布说明别直接跨好几个大版本拉 latest。5.4 权限和访问安全的几点提醒HomeBox 默认除了登录账号之外没有任何额外的访问控制如果只是在内网用问题不大。但如果要通过远程访问或者反向代理暴露到公网请务必加一层身份认证至少做到修改默认管理员账号、使用强密码、不要直接用默认端口裸奔。飞牛系统自己有远程访问的通道但我个人的建议是家庭数据类的服务尽量不要直接暴露用之前想清楚风险。另外多用户场景下给家人开账号时要注意 HomeBox 的权限模型是偏简单的没有特别细粒度的权限控制。家庭使用够用但不要把它当成可以精细管控权限的企业系统来依赖。如果家里人只是偶尔查一下东西开个只读性质的账号就够了。最后分享一个小技巧。因为我家里路由器是支持自定义域名的我直接在 DNS 里把hb.local指向飞牛 NAS 的内网 IP然后在飞牛上用反向代理把hb.local转到 HomeBox 的 7745 端口。这样平时只要在浏览器输入hb.local就能打开 HomeBox再也不用记 IP 和端口。当然如果你不想折腾域名直接把http://IP:7745存到书签里也完全够用。我自己跑了两周最大的感受是工具本身其实很轻量真正花时间的是整理物品信息和建立使用习惯。只要把分类、位置、保修日期这几样基础数据养成随手记录的习惯HomeBox 就是一个越用越值的“家庭物品地图”。如果你家里也有一堆“总觉得在哪但找不到”的东西照着上面的步骤在飞牛上部署一个大概率不会后悔。