开源、自托管的家庭管理工具
完全掌控你的家庭数据:在自己的服务器上运行。
|
|
|
| 餐食计划 | 家庭 | 每周计划 |
|---|---|---|
|
|
|
|
深色主题:
| 首页 | 日历 | 每周计划 |
|---|---|---|
|
|
|
|
在手机上:
| 首页 | 首页,深色主题 | 购物 | 日历 |
|---|---|---|---|
|
|
|
|
|
## 🔗 第三方集成
一键将 OpenFamily 连接到你的自托管生态系统,无需编辑配置文件。
| 应用 | 类型 | 同步内容 |
|---|---|---|
| **[Gladys Assistant](https://github.com/NexaFlowFrance/gladys-openfamily)** | 🏡 智能家居 | 在法国的开源智能家居助手 [Gladys](https://gladysassistant.com) 中显示家庭日历、购物清单和任务:仪表盘小组件、场景动作和触发器。从 Gladys 集成商店安装 |
| **Mealie** | 🍲 食谱 | 自动导入所有食谱(分页、API v1 和 v2) |
| **Tandoor** | 🌿 食谱 | 通过 Django REST API 导入 |
| **Home Assistant** | 🏠 购物 | 通过 WebSocket 同步购物清单(现代 `todo` 实体和旧版实体) |
| **Grocy** | 🥦 购物与库存 | 同步购物清单和库存 |
| **Nextcloud** | ☁️ 日历 | 通过自动发现和按 UID 去重导入 CalDAV |
> 🎬 感谢 **[Makernix](https://www.youtube.com/@Makernix)**:将 OpenFamily 与自托管家庭生态系统
> (Mealie、Grocy、Home Assistant、Nextcloud)连接起来的想法,来自与他的一次直接交流。
## 🚀 快速开始
### 🐳 Docker,一条命令
一个容器包含界面、API 和数据库。无需任何配置:密钥在首次启动时自动生成,并与数据保存在一起。
```bash
docker run -d --name openfamily --restart unless-stopped \
-p 3000:3000 -v openfamily:/data \
ghcr.io/nexaflowfrance/openfamily:latest
```
打开 http://localhost:3000,或在手机上打开 `http://<服务器地址>:3000`,然后创建账号。镜像支持 amd64 和 arm64(Raspberry Pi 4 和 5、大多数 NAS)。HTTPS、更新与备份见 **[服务器指南(英文)](INSTALLATION.md)**。
### 📦 从服务器的应用目录安装
在以下系统上,OpenFamily 可以像其他应用一样从应用目录安装。每个链接都有逐步的添加说明(英文):
| 系统 | 方式 |
|---|---|
| **Home Assistant**(OS 或 Supervised) | [添加应用仓库](https://github.com/NexaFlowFrance/home-assistant-apps) |
| **Umbrel** | [添加社区应用商店](https://github.com/NexaFlowFrance/umbrel-app-store) |
| **CasaOS、ZimaOS** | [添加应用商店](https://github.com/NexaFlowFrance/casaos-appstore) |
| **Runtipi** | [添加应用商店](https://github.com/NexaFlowFrance/runtipi-appstore) |
| **Unraid** | [获取模板](https://github.com/NexaFlowFrance/unraid-templates) |
| **TrueNAS** | 在社区应用目录中搜索 OpenFamily |
| **Proxmox** | 使用[脚本](INSTALLATION.md#proxmox)创建容器 |
前五项是新增的。如果在你的系统上无法使用,请[告诉我们](https://github.com/NexaFlowFrance/OpenFamily/issues),这对之后的用户也有帮助。
### 🪟 Windows 安装程序(.exe),最简单的方式
针对 Windows 用户,**NexaFlow** 提供一体化图形安装程序:内置 Node.js 和
PostgreSQL,**无需 Docker,也无需配置**。
运行 `OpenFamily-Setup.exe`,点击 **Start**,然后通过 http://localhost:3000 打开应用。
窗口中还会显示本地网络地址,便于使用同一 Wi-Fi 下的手机访问;**设置**页面中还会说明
如何配置 Tailscale 以实现安全的远程访问。
### 📱 Android 应用(APK)
OpenFamily 还提供原生 **Android 应用**,它是一个连接到**你自己**服务器的轻量客户端
(首次启动时输入服务器地址,与 Nextcloud 或 Home Assistant 应用类似)。它本身不托管任何服务。
安装 APK,在系统提示时允许安装未知来源应用,然后打开应用并输入服务器 URL
(例如 `http://192.168.1.10:3000`,或你的 HTTPS / Tailscale 地址)。
> 🔄 **自动保持最新版本:**将本仓库添加到
> **[Obtainium](https://github.com/ImranR98/Obtainium)**,即可直接通过 GitHub Releases 接收应用更新,无需应用商店。
### 🧩 Docker Compose,各部分独立容器
同一个应用拆成三个容器(PostgreSQL、API、Web 服务器),适合希望各部分分开运行或从源码构建的服务器。请按照分步 **[服务器指南(英文)](INSTALLATION.md)** 操作:需要设置的密钥、通过域名或 Tailscale 启用 HTTPS、更新与备份。
```bash
cp .env.example .env # 编辑配置
docker-compose up -d --build
```
- 前端:http://localhost:3000
- 后端 API:http://localhost:3001
运行端到端验证:
```bash
npm run smoke:api
```
**想直接使用现成镜像?** 每个版本都会发布 amd64 和 arm64 镜像。在 `docker-compose.yml` 旁边创建 `docker-compose.override.yml`:
```yaml
services:
server:
image: ghcr.io/nexaflowfrance/openfamily-server:2.2.0
client:
image: ghcr.io/nexaflowfrance/openfamily-client:2.2.0
```
然后运行 `docker compose pull server client && docker compose up -d`(不要加 `--build`)。镜像名必须带 `-server` / `-client` 后缀。`REGISTRATION_ENABLED` 等设置由服务器在启动时读取,已发布的镜像无需重新构建。
### 🛠️ 手动安装
```bash
npm run install:all
psql -U postgres -c "CREATE DATABASE openfamily;"
cp .env.example .env
npm run dev
```
- 前端:http://localhost:5173 · 后端:http://localhost:3001
## 🆚 为什么选择 OpenFamily?
| | OpenFamily | Cozi / FamilyWall |
|---|---|---|
| 数据存储在你自己的服务器上 | ✅ | ❌ |
| 开源(AGPL-3.0) | ✅ | ❌ |
| 无广告、无跟踪 | ✅ | ❌ |
| 自托管集成(Gladys Assistant、Home Assistant、Mealie、Grocy 等) | ✅ | ❌ |
| 带令牌和 Webhook 的文档化 API | ✅ | ❌ |
| 可在本地模型上运行的 AI 助手 | ✅ | ❌ |
| 离线工作(PWA) | ✅ | ⚠️ |
## 🧰 技术栈
**前端**:React 19 · TypeScript · Vite 7 · TailwindCSS · Radix UI · i18next · PWA(Service Worker、Web Push、离线模式)
**后端**:Node.js 26 · Express · PostgreSQL 16(自动迁移)· WebSocket · Web Push(VAPID)· JWT + bcrypt 12 · helmet · 限流
**DevOps**:一体化镜像,或 Docker Compose(postgres、server、client/nginx)· GitHub Actions(CI、发布 Docker 镜像到 ghcr.io、GitHub Pages 演示)
## 🔐 安全
JWT 身份验证(有效期 7 天,自动刷新)· 使用 **bcrypt(cost 12)** 哈希密码 · 通过 **helmet** 设置安全 HTTP 响应头 ·
身份验证接口限流 · 严格且可配置的 CORS · 服务端输入验证 · 结构化日志(不包含敏感数据)。
## 🗺️ 路线图
计划功能和设计决策请参阅 [ROADMAP.md](ROADMAP.md)。
## 💛 支持项目
OpenFamily 是免费、开源(AGPL-3.0)且自托管的:没有广告、没有追踪、没有付费版本。
它由个人业余时间开发和维护。如果它对你的家庭有帮助,欢迎支持它的开发:
给仓库点个 Star 同样有帮助:其他家庭正是这样发现这个项目的。
## 🤝 参与贡献
OpenFamily 的许多部分来自它的使用者:语言、集成,以及后来变成功能的想法。
- **有想法或疑问?** 发起一个[讨论](https://github.com/NexaFlowFrance/OpenFamily/discussions)。
- **发现问题?** 创建一个 [Issue](https://github.com/NexaFlowFrance/OpenFamily/issues/new/choose)。
- **缺少你的语言,或翻译不够好?** 参见 [TRANSLATING.md](TRANSLATING.md)(英文):翻译可以逐条提交,未翻译的部分会以英文显示。
- **想写代码?** [CONTRIBUTING.md](CONTRIBUTING.md)(英文)说明了如何运行项目以及 Pull Request 的要求。
## 📄 许可证
GNU Affero General Public License v3.0(AGPL-3.0-only),详见 [licence.md](licence.md)。
## 🙏 致谢
由 [NexaFlow France](https://nexaflow.fr) 开发和维护。