自托管家庭规划工具Oikos

发表于 分类于 Waline： 阅读次数： 本文字数： 4k 阅读时长 ≈ 4 分钟
Oikos 是一个开源的家庭规划应用，支持任务管理、购物清单、餐食计划、日历同步和预算跟踪。

简介

什么是 Oikos ？

Oikos 是一个开源的家庭规划应用，可以帮助小家庭管理任务、购物清单、餐食计划、日历同步、预算、笔记和联系人。它是一个完全自托管的解决方案，所有数据都存储在本地，保护家庭隐私。

主要特点

  • 任务管理：共享任务支持截止日期、优先级、子任务、重复日程，卡片式看板视图支持触屏设备一键操作
  • 购物清单：协作式清单支持按 aisle 分类，可一键从餐食计划导入
  • 餐食计划：周计划支持拖拽操作，自动生成食材清单并导出到购物清单
  • 日历同步：双向同步支持 Google Calendar（OAuth）和 Apple iCloud（CalDAV）
  • 预算跟踪：收入支出记录、周期性条目、可配置货币（13种）、月度趋势、CSV 导出
  • 笔记和联系人：彩色便签支持 Markdown，联系人目录支持 vCard 导入导出
  • 零构建步骤：纯 ES 模块，无打包器、无转译器、无框架
  • 隐私优先：SQLCipher AES-256 加密数据库，完全自托管，无遥测
  • PWA 原生体验：可安装到任意设备，支持离线工作，暗色模式，响应式布局
  • 多语言：德语、英语、意大利语和瑞典语 UI，支持自动语言检测
  • 开源免费：基于 MIT 协议开源，可免费使用和修改

应用场景

  • 家庭任务协调：家庭成员可以创建和分配任务，设置截止日期和优先级，跟踪完成进度
  • 购物清单管理：每周计划餐食后自动生成购物清单，按商店区域分类，方便采购
  • 家庭预算管理：记录日常收支，查看月度趋势，导出数据进行分析
  • 日历统一管理：同步 Google 或 Apple 日历，全家人可以看到统一的日程安排

Oikos 是一个功能完整的家庭数字助手，特别适合注重隐私的家庭使用，所有数据都存储在自己的服务器上。

安装

在群晖上以 Docker 方式安装。

由于镜像托管在 ghcr.io，群晖 Docker 套件无法直接搜索，需要通过命令行部署。

docker-compose 安装

将下面的内容保存为 docker-compose.yml 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
services:
  oikos:
    image: ghcr.io/ulsklyc/oikos:latest
    container_name: oikos
    restart: unless-stopped
    ports:
      - "3522:3000"
    volumes:
      - ./data:/data
    env_file:
      - env.txt
    environment:
      - NODE_ENV=production
      - DB_PATH=/data/oikos.db
      # Set to false when not using HTTPS/reverse proxy (direct HTTP access)
      - SESSION_SECURE=false
    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

env.txt

同时需要创建 env.txt 环境变量文件，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# Oikos - Environment Variables
# Copy this file to .env and adjust the values.

# Server
PORT=3000
NODE_ENV=production
# LOG_LEVEL=info   # debug, info, warn, error (default: info)

# Session
SESSION_SECRET=REPLACE_WITH_A_LONG_RANDOM_STRING
# SESSION_SECURE=false   # Only set when not using HTTPS/reverse proxy (e.g. direct localhost)

# Database (SQLite/SQLCipher)
DB_PATH=/data/oikos.db
DB_ENCRYPTION_KEY=REPLACE_WITH_A_STRONG_ENCRYPTION_KEY

# Weather (OpenWeatherMap)
OPENWEATHER_API_KEY=YOUR_API_KEY
OPENWEATHER_CITY=Berlin
OPENWEATHER_UNITS=metric
OPENWEATHER_LANG=de

# Google Calendar (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=https://your-domain.com/api/v1/calendar/google/callback

# Apple Calendar CalDAV (optional)
APPLE_CALDAV_URL=https://caldav.icloud.com
APPLE_USERNAME=
APPLE_APP_SPECIFIC_PASSWORD=

# Calendar sync interval in minutes (default: 15)
SYNC_INTERVAL_MINUTES=15

# Security
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_ATTEMPTS=5
RATE_LIMIT_BLOCK_DURATION_MS=900000

环境变量说明

变量名 必填 说明
PORT 否 服务端口，默认为 3000
NODE_ENV 否 运行环境，默认为 production
SESSION_SECRET 是 用于 Session 加密，请使用一个长的随机字符串
SESSION_SECURE 否 是否启用 HTTPS cookie，仅在使用 HTTPS/反向代理时设为 true
DB_PATH 否 数据库路径，默认为 /data/oikos.db
DB_ENCRYPTION_KEY 是 数据库加密密钥，请使用一个强密钥
OPENWEATHER_API_KEY 否 OpenWeatherMap API Key，用于显示天气，注册地址： https://home.openweathermap.org/api_keys
GOOGLE_CLIENT_ID 否 Google Calendar OAuth Client ID
GOOGLE_CLIENT_SECRET 否 Google Calendar OAuth Client Secret
APPLE_CALDAV_URL 否 Apple Calendar CalDAV 服务器地址
APPLE_USERNAME 否 Apple 账号用户名
APPLE_APP_SPECIFIC_PASSWORD 否 Apple 应用专用密码

然后通过 SSH 登录到您的群晖，执行下面的命令：

1
2
3
4
5
6
7
8
9
10
# 新建文件夹 oikos 和子目录
mkdir -p /volume1/docker/oikos/data

# 进入 oikos 目录
cd /volume1/docker/oikos

# 将 docker-compose.yml 和 env.txt 放入当前目录

# 一键启动
docker-compose up -d

运行

创建管理员账户

首次启动后，需要初始化管理员账号。执行以下命令：

1
2
# 创建第一个管理员账户
docker-compose exec oikos node setup.js
  • Benutzername：就是用户名，例如：laosu
  • Anzeigename：就是显示的名称
  • Passwort：就是密码，不能少于 8 个字符，例如： 12345678
  • Passwort bestätigen：就是确认密码，要跟上面的密码一致才行

创建成功会有提示

登录

在浏览器中输入 http://群晖IP:3522 就能看到登录界面

用创建的管理员 laosu/12345678 登录，成功后的主界面

如果设置了 OPENWEATHER_API_KEY，会多出一行天气预报

所有的功能都在左侧菜单，包括任务、日历、餐食、购物、预算等等

也可以在 Settings 中添加家庭成员

注意事项

  1. 数据加密：Oikos 使用 SQLCipher 对数据库进行 AES-256 加密，请妥善保管 DB_ENCRYPTION_KEY，一旦丢失数据将无法恢复
  2. SESSION_SECRET：请使用一个足够长的随机字符串作为 Session 密钥
  3. 端口冲突：默认使用 3522 端口，请确保该端口未被占用
  4. 数据备份：建议定期备份 ./data 目录下的数据库文件
  5. HTTPS 配置：如需通过域名外部访问，建议配置反向代理并设置 SESSION_SECURE=true
  6. 首次设置：必须运行 docker-compose exec oikos node setup.js 来创建管理员账号，否则无法登录

参考文档

ulsklyc/oikos: Self-hosted family planner - tasks, calendars, shopping, meals, budget. Your data, your server.
地址：https://github.com/ulsklyc/oikos

Oikos — The Self-Hosted Family Planner
地址：https://ulsklyc.github.io/oikos/

oikos Docker 镜像
地址：https://ghcr.io/ulsklyc/oikos

Oikos 安装指南
地址：https://github.com/ulsklyc/oikos/blob/main/docs/installation.md