PrivateApp

个人 PWA 仪表盘 — 基于 FastAPI 的后端 + React/Vite 构建的前端，支持插件化应用。

截图

安装配置

# 克隆并安装（自动创建虚拟环境、构建前端、配置 systemd/launchd）
git clone https://github.com/camopel/PrivateApp.git ~/Workspace/PrivateApp
cd ~/Workspace/PrivateApp
bash scripts/install.sh [--port 8800]

复制 scripts/config.example.json → scripts/config.json 并编辑：

{
  "host": "0.0.0.0",
  "port": 8800,
  "data_dir": "~/.local/share/privateapp",
  "file_browser": { "root": "~" },
  "push": { "vapid_email": "you@example.com" }
}

服务管理

# Linux（systemd 用户服务）
systemctl --user start privateapp
systemctl --user stop privateapp
systemctl --user restart privateapp
systemctl --user status privateapp

# macOS（launchd）
launchctl load ~/Library/LaunchAgents/com.privateapp.server.plist
launchctl unload ~/Library/LaunchAgents/com.privateapp.server.plist

# 手动启动
.venv/bin/python3 scripts/server.py --host 127.0.0.1 --port 8800

构建前端

每次修改前端代码后，需重新构建：

# 构建 Shell（主界面）
cd frontend && npm run build

# 构建所有应用的前端
for app_dir in apps/*/frontend; do
  [ -f "$app_dir/package.json" ] && (cd "$app_dir" && npm install && npm run build)
done

# 或直接运行安装脚本（自动构建全部）
bash scripts/install.sh

然后重启服务。

内置应用

添加新应用

在 apps/{app-id}/ 下新建目录，并包含以下内容：

• app.json — 应用元数据（id、name、shortcode、icon、description）
• backend/routes.py — FastAPI 路由器（挂载路径为 /api/app/{shortcode}/）
• frontend/ — React 单页应用（基于 Vite，构建输出至 frontend/dist/）

短代码（shortcode）必须唯一。应用加载器会在启动时自动发现并注册新应用。

可参考已有应用的实现模式。关键约定如下：

• 所有路由函数均为 async def，返回纯字典（plain dict）
• 前端使用 CSS 自定义属性（CSS custom properties）实现暗色模式适配
• 输入控件字体大小 ≥ 16px（防止 iOS 自动缩放）
• 每个应用均需提供返回首页（/）的返回按钮

推送通知

应用可通过 commons.push_client 发送推送：

from commons.push_client import send_push
await send_push(title="Alert", body="Something happened", url="/app/my-app/")

数据存储路径

~/.local/share/privateapp/
├── privateapp.db       # 设置、用户偏好、推送订阅信息
├── vapid_private.pem   # VAPID 签名私钥
└── vapid_public.txt    # VAPID 公钥

核心 API 接口

• GET /api/apps — 获取已安装应用列表
• GET /api/settings/preferences — 获取用户偏好设置（时区、语言、应用排序）
• POST /api/settings/preferences — 保存用户偏好设置
• POST /api/push/send — 发送推送通知
• GET /api/push/test — 推送功能测试接口