Yuvomi自托管家庭规划器部署指南

一、Yuvomi 应用是什么？

Yuvomi是一款 MIT 协议开源的自托管家庭规划器。

它把日程、任务、餐食、购物、预算、文档、健康等二十个模块装进同一个容器和同一个 SQLite 数据库里，所有数据只存在你自己的服务器或 NAS 上：没有订阅、没有厂商账号、零遥测。

支持PWA 形态运行，手机浏览器即可"安装"到桌面

解决了什么痛点？

家里事情一多，烦恼往往很相似：周末安排容易撞车，水电物业订阅总等提醒才想起，家庭开支分散难复盘，资料、保修记录和重要日期又散落在各处。

有没有一个平台，能统一管理家庭日程、任务、预算、购物、菜谱、文件和提醒，还能让家人一起用？

功能特点：

• 二十个可开关模块：Tasks、Calendar、Rewards、Notes、Contacts、Schedule、Kitchen（Meals/Recipes/Shopping/Pantry）、Housekeeping、Waste collection、Documents、Inventory、Health、Birthdays、Budget，以及 Family、Reminders、API Tokens、Backup 等设置类模块

• 模块之间数据联动：一周菜单可以一键把全部食材按货架分区导入共享购物清单；橱柜里某样东西见底，点一下就进购物单，采购勾选后再一键回填库存；任务完成按执行人自动结算积分并进入奖励兑换

• 单容器单文件：全部业务数据落在一个 SQLite 文件（/data/yuvomi.db），迁移与导出就是复制这个文件

• 可选静态加密：配置 DB_ENCRYPTION_KEY 后由 SQLCipher 以 AES-256 加密数据库，密钥丢失即数据不可恢复

• 家庭级权限模型：管理员、家庭成员等角色可对每个模块设置完全可用、只读或隐藏；单条日程、笔记、健康记录还能细到"仅自己可见"

• 邀请制入驻：成员通过有效期 7 天的邀请链接自行设置密码；没有手机的孩子可由管理员直接建账号

• 两因素与单点登录：支持 TOTP 二次验证（可对全家庭强制开启）、恢复码，以及对接 Authentik、Keycloak 等 OIDC 提供方并关闭密码登录

• PWA 与墙挂模式：手机加到主屏幕即可全屏运行，离线可读已加载的清单；平板可开 wall mode 显示今日安排，空闲时可用 Immich 相册做屏保

• 与既有生态对接：日历支持 Google 与 CalDAV 双向同步、ICS 订阅、Outlook 单向推送；联系人走 CardDAV；文档可存本地目录、WebDAV 或 Google Drive；菜谱可只读镜像 Mealie / Tandoor；文档可接 Paperless-ngx / Papra

• 通知通道齐全：应用内角标、Web Push，以及 Gotify、ntfy、Webhook、邮件等家庭级通道

• 对外开放接口：提供 OpenAPI 3.1 规范与 Bearer Token，另有 /mcp 端点，可让支持 MCP 的 AI 客户端直接驱动 API

• 轻量且跨架构：镜像约 500 MB，支持 amd64 与 arm64（含树莓派 4/5），最低 256 MB 内存、单端口 3000

• 多语言与零追踪：内置 27 种语言

1.1、使用场景介绍

Yuvomi 的定位不是"再装一个待办 App"，而是把家庭里散落在多个付费应用中的信息收回一处

以下几类场景最贴合它的设计：

1. 有孩子的双职工家庭：谁几点去哪、本周吃什么、家务谁做、零花钱怎么算，都落在同一个首页时间线上，减少"口头传话"的信息损耗

2. 厨房墙挂屏：一台旧平板常驻 wall mode，全家人抬头就能看到今日安排与谁在家；家务完成后在平板上点选执行人，积分自动入账

3. 共同开支与 AA 分摊：家庭日常开销、旅行费用、活动支出可以按成员分摊并自动做债务简化，谁欠谁一目了然

4. 健康与用药管理：按成员记录血压、血糖、体重、用药与疫苗计划，带补药提醒，数据默认私有，只有被授权的人能看到

5. 合租与小型共同生活单元：共用一个购物清单、一个账单池、一个文档夹，但各自保留私人日程

1.2、和同类别产品对比

同类别的有SaaS 型家庭协作应用（Cozi、FamilyWall）与硬件型家庭日历屏（Skylight）

维度YuvomiCoziFamilyWallSkylight运行位置自己的服务器或 NAS，单容器厂商云厂商云厂商云 + 专用硬件屏费用模式免费开源（MIT），无付费档免费版带广告，高级功能订阅免费版受限，高级功能订阅硬件一次性购买 + 订阅数据归属完全自有，可整库导出或加密存于厂商服务器存于厂商服务器存于厂商服务器模块联动菜单→购物→库存、任务→积分→奖励闭环日历、清单、待办各自独立以家庭社交与消息为中心以日历展示与照片为中心成员与隐私粒度角色 + 模块级 + 单条记录级家庭共享为主家庭共享为主家庭共享为主离线与自控PWA 离线可读，无外网依赖依赖云服务依赖云服务依赖云服务上手门槛需要一台常开主机与基本 Docker 操作注册即用注册即用买硬件即用

如果家里已有一台 7×24 运行的 NAS 或小主机，且在意数据归属与长期成本，Yuvomi 是更划算的选择；如果完全不想碰命令行、也不接受自维护，SaaS 方案仍更省心

Yuvomi界面

image-20261111150027765

image-20261111150054452

image-20261111150154229

image-20261111150215293

二、Yuvomi 安装部署

安装前准备工作，适用安装于NAS、软路由、服务器等设备

前置条件要求DockerDocker Engine 20.10 以上，或 Podman；Compose 建议 v2 插件版（docker compose）CPU 架构amd64 或 arm64，树莓派 4/5 可用内存与磁盘最低 256 MB 内存；镜像约 500 MB，另需给数据库与文档留出空间端口容器内固定监听 3000，宿主机端口可自定义访问方式内网可直接 HTTP；要使用推送、外网访问与安全 Cookie，需自备反向代理与 HTTPS

2.1、创建本地文件夹目录

Yuvomi 需要四个持久化目录，缺一个都会在更新容器时丢数据。

统一放在 /opt/yuvomi 下：】

data 存数据库与首次启动生成的密钥文件，backups 存定时备份，modules 存第三方扩展模块，documents 存文档附件的本地副本。

sudo mkdir -p /opt/yuvomi/{data,backups,modules,documents} # 生成会话密钥（用于签名 Session Cookie） openssl rand -hex 32 # 生成数据库加密密钥（必须在首次启动前确定） openssl rand -hex 32

使用openssl生成两个密钥：SESSION_SECRET与DB_ENCRYPTION_KEY`

权限方面不必手动 chown：镜像以 node 用户（uid 1000）运行，入口脚本会在启动时修正挂载目录权限；但在 Synology、TrueNAS 等以 uid 568 运行的环境，若日志出现 Permission denied，需要把目录属主改为 568:568

2.2、Docker Compose 配置

在 /opt/yuvomi 下新建 docker-compose.yml，内容如下：

services: yuvomi: image: ghcr.io/ulsklyc/yuvomi:latest container_name: yuvomi restart: unless-stopped ports: - "3000:3000" volumes: - ./data:/data - ./backups:/backups - ./modules:/app/modules - ./documents:/documents environment: NODE_ENV: production TZ: Asia/Shanghai DB_PATH: /data/yuvomi.db BACKUP_DIR: /backups MODULES_DIR: /app/modules DOCUMENT_STORAGE_LOCAL_ENABLED: "true" DOCUMENT_STORAGE_LOCAL_PATH: /documents SESSION_SECRET: "把openssl生成的第一个值粘到这里" DB_ENCRYPTION_KEY: "把openssl生成的第二个值粘到这里" SESSION_SECURE: "false" TRUST_PROXY: "0" healthcheck: test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))"] interval: 30s timeout: 10s retries: 3 start_period: 10s

保存后在 /opt/yuvomi 目录执行 docker compose up -d

使用docker compose logs -f yuvomi` 观察启动日志。

看到服务就绪后访问 http://服务器IP:3000 即可进入初始化向导

参数说明：

• image：官方预构建镜像，amd64/arm64 双架构；可用 :latest 跟进更新，也可固定为具体版本号以保证可回滚

• container_name：固定容器名，方便后续用 docker logs、docker exec 直接操作

• restart：unless-stopped 让主机重启后自动拉起；若担心频繁崩溃可用 on-failure:5 限制重试

• ports：宿主机:容器，容器内固定 3000；宿主端口改成 8080 等值时，只改冒号左边

• volumes / data：数据库 yuvomi.db 与首次启动生成的 .secrets 密钥文件都落在这里，是唯一必须备份的目录

• volumes / backups：定时与手动备份的落盘位置，默认每天凌晨 2 点、保留 7 份

• volumes / modules：第三方扩展模块的投放目录，无扩展需求也建议保留

• volumes / documents：开启本地文档存储后，上传的附件写在这；注意数据库备份只含元数据，不含这些二进制文件

• TZ：容器时区，同时作为定时备份与日历推送的默认时区，务必写对，否则日程时间整体偏移

• DB_PATH：数据库文件路径，容器内固定为 /data/yuvomi.db，不建议改动

• BACKUP_DIR / MODULES_DIR：容器内的备份与模块目录，需与 volumes 的挂载目标一致

• DOCUMENT_STORAGE_LOCAL_ENABLED：设为 true 时附件存本地目录而非数据库，优先于 WebDAV 后端

• DOCUMENT_STORAGE_LOCAL_PATH：容器内文档目录，必须与挂载目标一致，否则文件落进容器层、更新即丢

• SESSION_SECRET：签名会话 Cookie 的密钥，官方仓库中的占位值会被拒绝启动，必须替换

• DB_ENCRYPTION_KEY：SQLCipher 的 AES-256 密钥，首次启动前确定；中途更换等于让旧库永久不可读

• SESSION_SECURE：走 HTTPS 反向代理时改 true，纯 HTTP 内网访问保持 false

• TRUST_PROXY：反代在 Docker 内时设为 1；直连无代理时设为 loopback 或省略

• healthcheck：轮询 /health，让编排层能识别"进程在但不健康"的状态

2.3、Docker 命令安装方式

不使用 Compose 时，可用 docker run 一次性拉起。两者等价，选一种即可，不要对同一容器名重复创建。

docker run -d --name yuvomi --restart unless-stopped -p 3000:3000 -v /opt/yuvomi/data:/data -v /opt/yuvomi/backups:/backups -v /opt/yuvomi/modules:/app/modules -v /opt/yuvomi/documents:/documents -e NODE_ENV=production -e TZ=Asia/Shanghai -e DB_PATH=/data/yuvomi.db -e BACKUP_DIR=/backups -e MODULES_DIR=/app/modules -e DOCUMENT_STORAGE_LOCAL_ENABLED=true -e DOCUMENT_STORAGE_LOCAL_PATH=/documents -e SESSION_SECRET=你的会话密钥 -e DB_ENCRYPTION_KEY=你的数据库密钥 -e SESSION_SECURE=false -e TRUST_PROXY=loopback --health-cmd "node -e "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))"" --health-interval 30s --health-timeout 10s --health-retries 3 ghcr.io/ulsklyc/yuvomi:latest

执行后 docker ps 应看到 yuvomi 为 Up (healthy)，日志无密钥报错即表示启动成功

参数说明：

• -d：后台运行，容器日志通过 docker logs -f yuvomi 查看

• --name：容器名，后续升级、排查都以此为准

• --restart：与 Compose 的 restart 语义一致，保证开机自启

• -p：端口映射，左侧为宿主机端口，右侧必须是 3000

• -v /data：唯一不可丢失的挂载，含数据库与自动生成的密钥文件

• -v /backups：备份落盘目录，建议再指向独立磁盘或对象存储

• -v /app/modules：扩展模块目录，路径名不可改，应用按此路径读取

• -v /documents：本地文档目录，需与 DOCUMENT_STORAGE_LOCAL_PATH 保持一致

• -e NODE_ENV：生产模式，隐藏 API 文档页

• -e TZ：容器时区，影响日志时间戳与定时备份触发时刻

• -e DB_PATH：数据库绝对路径，保持默认以免与备份脚本脱节

• -e BACKUP_DIR：备份目标目录，不设置会回落到容器内不可写路径

• -e MODULES_DIR：模块目录，容器内固定 /app/modules

• -e DOCUMENT_STORAGE_LOCAL_ENABLED：开启本地文档存储，避免附件挤占数据库

• -e DOCUMENT_STORAGE_LOCAL_PATH：容器内文档路径，与挂载目标绑定

• -e SESSION_SECRET：会话签名密钥，明文写在命令历史里，多人共用主机时建议改用 --env-file 或 Docker Secret

• -e DB_ENCRYPTION_KEY：数据库加密密钥，同样建议走 Secret 文件方式（DB_ENCRYPTION_KEY_FILE）

• -e SESSION_SECURE：HTTPS 场景置 true，否则登录态在部分浏览器下会被拒绝

• -e TRUST_PROXY：直连场景用 loopback，反代场景用 1，影响真实客户端 IP 与限流判断

• --health-cmd 及后续三项：容器级健康检查，配合监控或编排策略使用

三、使用教程

容器跑起来只是完成了"装"，建议按"建管理员 → 拉家人 → 关模块 → 接日历 → 设备份"的顺序走一遍，避免后期返工

3.1、首次登录与管理员初始化

浏览器打开 http://服务器IP:3000，首次访问会跳到 /setup。依次填写管理员用户名、密码与家庭名称，提交后即成为该实例的唯一管理员，并自动登录进入首页。

image-20261111143744822

此时数据库已按你的 DB_ENCRYPTION_KEY 完成加密初始化，若密钥缺失或格式错误，启动阶段就会直接失败，不会出现"能登录但数据是空的"这类中间态。

进入首页后先做三件事：

1. 在设置 → 个人 → 外观切换主题与语言；

2. 在设置 → 管理 → 家庭和角色确认家庭时区（会覆盖容器 TZ 在业务层的默认值）

3. 在设置 → 模块（可选）关掉 Inventory、Waste collection、Schedule 等默认关闭或暂时用不到的功能，菜单会立刻变清爽

image-20261111144003182

3.2、邀请家庭成员与分配权限

在设置 → 管理 → 家庭和角色点"添加成员"或生成邀请链接。邀请链接有效期 7 天，成员打开后自设密码即可加入；对没有手机的孩子，管理员可直接创建账号并代管。角色决定的是模块级权限，每个模块可设为完全可用、只读或隐藏；而具体到一条日程、一条健康记录、一条预算条目，还能单独设为"仅自己可见"或"指定成员可见"。

如果家庭成员较多或涉及健康数据，建议先想清楚角色划分再录入数据：权限是逐条附着的，后期调整角色会得到"部分记录仍不可见"的混合结果，排查成本高。

3.3、核心模块上手

模块第一步该做什么任务新建几条家务并指定执行人与优先级（Urgent/High/Medium/Low），切换到看板视图确认拖拽改状态的手感；带截止日的任务才会进入首页与提醒日历先订阅一份公共 ICS 或农历节日日历验证时区，再按需接入 Google（需在 Google Cloud 建 OAuth 客户端并回填三个变量）或 CalDAV 双向同步Meals & Recipes把常做的几道菜建成菜谱并填好食材，然后拖进本周菜单；点"导出到购物清单"即可看到食材按货架分区落到清单Shopping & Pantry采购时勾选条目，回来后用"Into pantry"回填库存与保质期；库存见底的项目会在列表里提示并可直接补进购物单预算先建账户与分类，再记两三笔支出，最后设置月度预算与储蓄目标；共同支出选好分摊成员后会自动算出谁欠谁文档在设置里选择存储后端（本地目录 / WebDAV / Google Drive）后再上传；切换后端不会迁移历史文件，只会影响新上传健康按成员录入一次血压或体重，确认趋势图正常；用药项填好补药提醒，通知通道在"设置 → 通知"里选择积分先建奖励目录与所需积分，再给任务打上分值；孩子完成并勾选后，积分进入可审计的流水，兑换需家长审批

手机端在浏览器打开同一地址后，通过"添加到主屏幕"即可获得全屏 PWA 体验：已加载的购物清单、日程与任务在断网时仍可读，但勾选等写操作需要联网，失败时会明确提示而不是静默丢失。

3.3.1、任务管理

支持列表和看板

支持创建分配给指定成员的任务、设置截止时间、优先级与积分，提供看板和列表多种视图，支持重复任务、任务状态流转、到期提醒，可和奖励模块联动自动累计积分，依托精细化权限控制实现任务可见范围隔离，用来统一安排家务、代办事项、家庭分工，方便全家协同跟进任务进度。

image-20261111151803825

image-20261111151822208

3.3.2、日历

日历模块是面向家庭的共享日程中心，支持创建家庭共用、个人私有、指定成员可见的日程，支持重复事件、节假日叠加与事件提醒，可双向同步 Google 日历、CalDAV 日历，也能订阅 ICS 只读日历源、单向推送至 Outlook，多成员日程在同一时间线视图汇总展示，搭配权限控制实现日程隔离，同时可和任务、生日等模块数据联动，适合统一管理全家的预约、纪念日、家务安排与出行计划。

image-20261111151853477

3.3.3、生日管理

Yuvomi生日模块用于统一管理家庭成员与亲友的生日信息，支持录入姓名、出生日期、提前提醒时间，自动计算年龄并生成年度生日日程，可直接同步到日历模块，搭配通知通道自动推送生日提醒，同时依托权限设置控制查看范围，方便一家人提前准备生日安排，避免遗漏重要纪念日。

添加生日

右上角点击生日+

image-20261111144644188

image-20261111144607510

3.3.4、健康

健康模块是以家庭成员为单位的健康数据记录中心，可录入血压、体重、血糖、用药、疫苗等健康指标，支持设置用药提醒与随访计划，自动生成健康趋势图表，记录内容可配置仅本人或指定成员可见，同时支持通知提醒，数据还能联动日历模块，适合全家跟踪健康状况、管理服药计划与定期体检安排。

image-20261111152254351

3.3.5、厨房

Yuvomi厨房模块是一体化家庭膳食管理中心，整合菜谱库、周食谱规划、共享购物清单与食材库存管理，可录入菜品做法、食材用量，将菜谱安排进每周食谱后一键汇总食材生成购物清单，清单支持按超市货架分类排序，采购完成后勾选商品可自动回填至库存，同时能设置食材保质期提醒，支持对接外部菜谱源，搭配权限控制实现全家协同规划三餐、管理食材库存，减少重复采购与食材浪费。

image-20261111152338918

image-20261111152351720

3.3.6、便签

支持创建富文本便签、分类整理、设置可见权限，可设为全员可见、仅自己或指定成员查看，支持标签检索，内容可和日历、任务联动，同时支持通知提醒，适合用来记录家庭备忘、临时消息、采购备注、育儿小贴士等碎片化信息，方便全家人随时查阅、协同记录。

3.3.6、家务

用于家庭家务分工协同，支持创建各类家务事项、分配执行人、设置循环周期、截止时间与对应积分，自动生成家务排班计划，到期推送提醒，完成后可同步累计积分对接奖励模块，搭配细粒度权限控制区分可见范围，清晰展示家务完成状态，帮助家庭成员有序分担家务、跟踪落实情况。

内置模板，很方便

image-20261111152527868

3.3.7、预算

家庭共享收支管理中心，支持添加账户、收支分类、录入日常消费与共同开销，可设置月度预算目标，支持多人分摊账单、自动计算成员间债务，生成收支统计图表，记录内容支持权限隔离，还能搭配提醒功能跟进账单，适合一家人共同记账、管控家庭开支、理清共同费用分摊。

轻量化的账本，主打提醒预告

image-20261111152602404

作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～