自托管宠物记录工具CoPaw：从时间线数据到家庭协作的技术实践

1. 起因当现成的宠物记录工具满足不了我的“较真”1.1 市面上的宠物App缺的恰好是最重要的那几块先说清楚CoPaw是什么它是我自己从零写的一个宠物记录与家庭协作工具主要面向多个人共同照顾一只或几只宠物的场景。功能说白了就是几件事——记录喂食、遛弯、疫苗、体重、异常行为给关键事件设置提醒然后让家里所有人能看到同一份真实的数据而不是各记各的。为什么放着现成的宠物软件不用非要自己造轮子我用过的宠物记录类工具不少但它们的共同问题很典型。第一是数据封闭记录都存在别人的服务器上想导出成一份自己能看懂的文件非常困难有些甚至压根不提供导出功能。第二是账号绑定太死一个App往往只允许一个“主要看护人”创建档案其他家庭成员要么共用账号要么只能看不能记实际生活中“今天谁喂了猫”“疫苗是不是我妈带去打的”这类协作场景完全覆盖不了。第三是广告和社区内容太喧宾夺主打开软件先弹各种商城、探店、萌宠视频我只是想记一条喂食时间得先关掉三个浮窗。第四也是最让我没法忍的——它们都没有把“时间”当作核心数据来对待。仔细想想宠物日常记录的本质就是一条时间线几点喂的、吃了多少、什么时候换的水、上次体内驱虫是哪天.Date这些都是事件而事件最核心的属性就是时间。市面大多数工具却把每条记录当成一个孤立的表单字段导致“我家猫上周三突然不怎么吃东西这周又恢复了”这种需要对比时间线才能发现的规律在那些App里根本看不出来。1.2 从一张共享喂食表到CoPaw的第一版草图CoPaw的雏形其实更简单——一张放在家里的共享表格。我和家里人轮流记录猫的喂食、铲屎和体重变化用手机编辑同一个在线表格。用了一段时间发现表格能解决一部分问题起码知道上次喂食是什么时候了但痛点很快暴露手机上填表格效率极低一不小心就会误改别人的数据而且不管是什么类型的记录混在同一张表里时间一长根本没法检索。所以第一版CoPaw的需求清单是我自己逐条逼问出来的每条都很具体宁可砍功能也不模糊同一份数据必须支持多个家庭成员同时查看和记录不需要注册复杂的账号体系。每条记录必须带精确到分钟的时间戳同时记录“事件发生时间”和“录入时间”两者可以不同。提醒规则要灵活比如“每28天提醒一次体内驱虫”“罐头隔6小时提醒一次”而不是简单地设一个闹钟。数据必须掌握在自己手里备份就是拷贝文件迁移就是恢复文件。那时我对这个项目的期望很朴素只要它比那张共享表格好用就算成功。后续所有开发方向都以这份清单为基准任何功能开发前先问一句“它是在帮我们记录还是在制造新负担”。2. 功能盘子CoPaw的第一版到底做了些什么2.1 四条纵向主线档案、日程、事件流、趋势图CoPaw的功能可以拆成四条互相咬合的纵向主线每条解决一类问题。第一条是宠物档案记录基本信息、绝育状态、过敏史、体重曲线。档案的特点是低频修改但高频查看所以界面重点是“一眼能看到重点”而不是堆一堆花哨卡片。第二条是日程提醒喂食、喂药、驱虫、疫苗、遛弯、洗澡凡是周期性的事情都交给这个模块。第三条是事件流所有成员手动记录的每一次行为比如“吐了”“精神不好”“换粮”“打喷嚏”都按时间戳追加成一条流支持关键词检索和按日期范围筛选。第四条是趋势图把体重、食量、遛弯时长这些可量化的记录汇总成折线图用于观察规律。四条主线的联动关系值得单独说。事件流里的“喂食”会反向影响日程模块的下一次提醒时间体重趋势图的数据来自档案里的每一次称重记录而疫苗计划是否到期取决于档案里最近一次疫苗日期加上固定周期。也就是说CoPaw不是四张孤立的表它是一个以“宠物”为聚合根的小型事件系统。模块核心数据数据来源主要输出档案基本信息、疫苗史、过敏史主人手工维护宠物全貌卡片、疫苗到期判断日程周期模板、最近一次执行时间模板初始化 事件流回写提醒推送、待办清单事件流事件类型、发生时间、备注、操作人所有成员实时录入时间线检索、行为统计趋势图体重、食量、活动量量化事件自动聚合折线图、异常波动报警每条主线从设计到实现都有明确的“为什么”。事件流之所以放最核心的位置是因为我后来发现大多数健康问题不是靠某一次检查发现的而是靠记录连续性发现“今天和上周不一样了”。如果只把数据锁在一张张表单里这种规律很难浮出来。2.2 最“重”的模块不是数据表而是提醒规则引擎写第一版之前我踩过一个想当然的坑以为提醒功能就是建一张“提醒表”每个提醒存一个时间到点触发就行。真开始用才发现完全不是那么回事。以体内驱虫为例有些药要求每季度一次有些是每个月一次还有“连续两个月每月一次、之后每半年一次”的治疗方案。如果把提醒当成固定时间点硬编码进表里那每次执行完都要手动把下次提醒时间算好再改一次人一旦忘记改整个提醒链条就断了。所以CoPaw的日程模块改成“规则引擎”的思路。一条提醒不再是“某个时间点”而是一个由三部分组成的规则触发周期模板、生效对象、最近一次实际执行记录。数据库只存这个规则每次查询“今天有没有到期”时系统根据最近一次执行时间加上模板周期动态算出下一次提醒时间。如果用户提前喂了药系统会把最近一次执行时间更新为当天下一次提醒自动往后顺延不需要任何人手工重算。具体实现上周期模板支持两种模式。固定周期就是“每N天/周/月”适合罐头投喂、洗澡这类日历模式则是“每月的某一天”或者“每季度的第一个周一”适合疫苗这类需要按日历对齐的事。为了不让规则复杂化我没有做跨时区调度而是把提醒计算放在查询时即时执行这样既避免半夜任务堆积也不需要维护一个庞大的调度队列。2.3 权限模型为什么一个家庭工具需要三个角色很多同类项目根本不考虑权限所有能打开页面的人都能改所有数据。但CoPaw运行一阵子后我发现家庭内部的协作角色其实差异很大必须区分对待。我最终设计了三个角色主人、看护者、访客。主人能修改宠物档案、管理成员、删除任何记录看护者能新增事件、查看全量数据但不能改档案和删除他人记录访客只能查看用于偶尔来帮忙遛狗的邻居或者临时照看宠物的人。这个设计的出发点是降低误操作风险。举个例子某次我妈帮忙喂猫她想在App里记一下“已喂”但如果不小心点到了档案页把猫的体重从5.2公斤改成了3.2公斤这个错误数据会直接污染趋势图。看护者没有档案编辑权限从机制上就堵住了这类事故。权限实现没有用太复杂的方案就是在后端接口层做了一次简单的中间件校验前端只是隐藏不可操作的按钮真正的约束都在服务端。这也是个人项目的底线原则前端限制只是体验优化数据安全必须靠后端强制执行。3. 技术选型一个人写全栈我选择怎么“偷懒”3.1 数据层一个单文件关系库解决九成问题个人开发项目最大的敌人不是功能复杂而是运维负担。CoPaw从一开始就定了一个原则能装在自己机器上、能简单备份的方案优先。所以在数据存储上我没有选择需要单独安装服务、还要配账号密码的服务型数据库而是用了一个单文件关系型数据库。单文件数据库的好处非常直白备份等于拷贝文件迁移等于拷贝文件出问题也只有一个文件要考虑。CoPaw每天凌晨自动把数据库文件复制到另一块硬盘做一次历史归档。这个备份策略在真实使用中救过我一次——有一次我升级程序时误删了数据目录从备份恢复只花了三分钟而如果是远程数据库恢复流程至少要牵扯导出、导入两个环节。当然单文件方案也有坑最需要注意的是并发写入。CoPaw的写入频率很低多人同时记录的情况其实不多但为了保险所有写操作都走了队列避免两个成员在同一毫秒写数据导致锁异常。实测这个队列方案足够应付一个大家庭的日常记录频率。3.2 前后端分工不做App先做Web端验证需求熟悉我做法的人都知道我信奉“能用Web解决的绝不做原生App”。CoPaw第一版完全是一个Web应用后端是单体服务提供一套JSON接口前端是一个浏览器端应用。选择Web而不是做App的原因很现实家里人的手机上都能开浏览器不需要装额外软件也不需要经过应用商店审核改完部署上去刷新就能看见新版本。前后端的分工上我把重逻辑都放在后端前端只负责渲染数据和处理交互。这样做的好处是业务规则比如提醒周期计算只维护一份代码不会出现“App里算出来和网页里算出来不一样”的分裂。接口设计遵循简单的REST风格所有资源通过URL定位操作类型用HTTP方法表达返回数据结构保持扁平方便后续如果真要再接一个小程序端不用为每个接口单独做适配层。3.3 部署形态一台小主机加容器化编排跑起来部署方面CoPaw用的是“一台低功耗小主机 容器化编排”的组合。容器化编排不是因为它多时髦而是它让我能一键复现整个运行环境——数据库、后端服务、前端静态文件、反向代理全部用一份编排文件定义好。小主机的配置很低内存只有几GB但跑CoPaw这种量级的应用绰绰有余。容器化之后升级流程变得非常可控先在另一台机器上跑一遍新镜像确认接口正常再把生产环境的镜像切过去若有问题可以秒级回滚。对个人项目来说能快速回滚比几乎没有出过错更让人安心。为什么坚持自托管而不是直接用云服务除了数据控制权之外还有一个原因是成本。CoPaw的数据量非常小每天的读写频率也低但如果是托管到云上要么按固定费付钱要么折腾一堆免费额度。自己家里一台小主机一次性投入之后电费可以忽略不计我这算下来怎么都不亏。4. 开发实录三个让我返工最多的设计细节4.1 时区不是小事宠物作息不能被夏令时带偏CoPaw踩过最隐蔽的坑是时区。最初我把所有时间都存成UTC想着显示的时候再转成本地时间这是不少系统惯用的做法。但实际用起来出了怪问题晚上喂罐头的提醒总是比预期晚一个小时而且不同季节偏差还不一样。排查过程很有意思。我先怀疑是提醒计算逻辑写错了但把代码翻了几遍没发现故障然后怀疑是前端渲染时区转换的问题修了好几个timezone相关的bug还是不行最后才意识到根因在“UTC存储”和“宠物作息”之间的结构性矛盾。宠物的喂食时间本质上是“当地时间”概念——每天18点喂食这个18点不会因为服务器搬去别的时区就改变更不应该因为夏令时而漂移。但如果我把“18点喂食”转成UTC存储那它在不同季节、不同系统时区下换算回本地时间的结果就会不一样。最终的方案是所有事件的发生时间都按“本地时间 时区偏移量”存储显示时不做任何转换。也就是说数据库里存的就是“2026-05-12 18:00 08:00”这种结构前端拿到后直接把时间部分渲染出来不经过任何时区换算。这样保证在任何设备上看到的“18:00”就是记录那一刻墙上挂钟的时间彻底消除了夏令时和服务器时区带来的漂移。这个教训让我明白处理“用户关心的时间点”和“服务器需要的时间戳”要分开对待。系统内部可以用标准时间戳做排序和计算但对外展示的“几点几分”必须坚持存储原始墙上时间。4.2 “软删除”差点害了统计曲线第二个返工大户是删除功能。最初做删除时我图省事用了软删除——给每条记录加一个deleted标记删除只是打个标记保留原始数据方便以后找回。这个设计在多数业务系统里是对的但在CoPaw的事件流模块里差点把数据统计做坏。事情的经过是这样的有一天我想看猫过去两周的体重趋势发现某一天直接断档了前一天5公斤、后一天5公斤中间那天却消失不见。排查后发现那天家里人有两次称重其中一次因为猫咪挣扎明显称错了他们就把那条记录删了。但我的趋势图代码是“统计所有未被删除的记录”结果把那天的所有称重都排除了视觉上形成一天的空窗。思考之后我把“删除”拆成了两种语义一种是用户误操作想撤回的“废弃记录”一种是数据本身错误需要“修正”的情况。CoPaw现在对每条量化的记录都额外存一个“状态”字段区分正常、撤回、修正。统计聚合时默认只算“正常 修正”的记录但有修正标记的原始记录仍然保留在事件流里可查。这样一来错误数据不会污染趋势但删除行为本身也变成了时间线上可追溯的一环。4.3 多人同时记录同一只猫离线冲突怎么合并CoPaw允许多人同时操作自然就绕不开并发冲突。最初的版本很粗暴谁后保存谁赢后保存的数据覆盖之前的数据。这个方案正常使用时没毛病但一旦一个人离线状态下改了数据等网络恢复后同步就可能把另一个人刚上传的新增记录整段覆盖掉。我处理这个问题的方式没有上复杂的数据库锁也没有引入CRDT这类分布式数据结构而是采用了一条务实的规则变化只做追加更新只改部分字段。每次操作都带上服务端下发的操作时间戳服务端合并时只比较单个字段的更新时间谁的字段新就保留谁的对于列表类的事件记录直接以新增方式追加不做覆盖式更新。这样即使两个人同时记录同一只猫的体重结果也是产生两条记录其中错误的一条可以通过撤回机制修掉而不是静静丢失。这套方案虽然不够“分布式高精尖”但它足够简单、可解释符合CoPaw的家庭协作场景——毕竟一个家庭的并发量不会高到需要为它设计一套复杂的冲突解决协议。5. 上线真实使用后暴露的问题5.1 家里断网时所有记录都“消失”了CoPaw部署在家里的小主机上后第一个现实问题就是我家一断网这个系统就废了。有一回小区光纤改造断网一天家里人想记一下猫的进食情况打开页面直接白屏那一刻我才意识到把数据放在自己家里的一个副作用是可用性高度依赖网络环境。对症下药的做法是给前端加“本地暂存”能力。前端通过网络正常时先往本地缓存里写一份副本提交记录时若网络失败请求不会直接报错而是进入一个待重试队列等网络恢复后台自动重新提交。同时页面做了轻量化的PWA支持断网时还能打开页面看到本地缓存的历史记录。这套方案虽然不是真正的离线优先架构但它把断网对“记录”这个核心行为的影响降到了最低。经过这次改造CoPaw从“断网没法用”变成了“断网能用但同步会延迟”对这个项目的定位来说已经够用了。5.2 移动端输入体验Web表单在手机上就是反人类CoPaw第一版的前端是按桌面端习惯设计的表单字段多、按钮小、键盘类型也没优化。家里人试用后的反馈非常一致“手机上记一条记录要点的次数太多了不如用表格。”坏消息是体验确实差好消息是他们还愿意提意见。我花了一个下午专门做移动端适配改造核心思路是“减少不必要的选择”。喂食记录预置了几个快捷标签早餐、午饭、晚饭、夜宵用户点一下标签就能填入默认值体重记录增加了趋势图区域内直接点击加号进入快速录入的入口所有数字字段在移动端都设成数字输入键盘避免弹字母键盘再切数字。这次改造让我意识到个人工具的功能再强大如果入口路径太长用户就会用脚投票回去用便利贴。5.3 长期跑着的服务进程守护、日志与数据安全系统跑了一个多月后我开始意识到“长期运行”带来的问题远不只是功能逻辑。小主机重启过几次有一次重启后发现前端正常但后端没起来数据库文件倒是完好无损纯粹是服务进程没设自动拉起。从那之后我花了比预期更多的时间在“让系统能自己稳定跑着”这件事上。现在的部署配置里加了三层防护。第一层是容器级别的重启策略主力容器挂了会立刻自动重启重启间隔逐步拉长防止故障循环。第二层是健康检查后端服务暴露一个健康接口反代层每30秒探测一次连续失败三次就触发告警。第三层是数据层的周期健康检查每天凌晨自动打开数据库文件做一次完整性校验把检查结果写到日志里。除此之外日志系统做了按天轮转避免单个日志文件无限膨胀撑满磁盘。个人项目最容易忽略的就是运维稳定性因为开发时你自己盯着终端出问题马上能看到但上线之后没人24小时盯着所有隐患都会在深夜悄悄放大。CoPaw这套三层防护谈不上精致但对一个家庭场景的工具来说已经足够让人睡得踏实。6. 个人实操体会与后续可以扩展的方向6.1 哪些“花里胡哨”的功能被我去掉了开发过程中有不少功能是做到一半砍掉的其中最典型的是两个一个是识别猫粮包装自动记录喂食品牌另一个是照片上传和相册墙。前一个砍掉是因为识别准确率不够稳定经常把两种包装认混反而需要人工修改增加操作成本后一个砍掉是因为它偏离了CoPaw的定位——它是记录工具不是晒宠社区照片再多也不会让数据变更准确。根据这次经历我总结出一个取舍原则功能如果不能让记录更准确、更省事就不要加。每加一个功能都对应未来一段时间的维护成本独开发者尤其要克制功能欲望。6.2 可以怎么扩展分享报告、硬件对接、多宠混养CoPaw目前已经满足了我最初对它的全部期待但它还能扩展出好几个实际有用的方向。最直接的是生成健康报告把一段时间的事件流和趋势图汇总成一份简洁文件分享给兽医参考省得到时候翻聊天记录口述。其次是对接一些常见的智能硬件比如智能体重秤自动回传体重饮水机能记录饮水量这部分数据如果能自动进入到事件流会大大减轻人工录入负担。再者是支持更复杂的多宠混养场景比如家里两只猫共用一台自动喂食器如何区分每只猫的进食量这类功能的复杂度会显著提升但需求是真实存在的。开发CoPaw带给我的最大体会是衡量一个工具是否好用的唯一标准是看它有没有让记录这件事变得更轻而不是看它功能列表有多长。从一开始的共享表格到现在的自托管应用最大的变化不是技术上的而是整个系统真正契合了家里的使用习惯和节奏。如果你也被市面工具的种种限制困扰不妨从一张表开始梳理自己的真实需求再决定下一步怎么走。