google-calendar-sync

Google Calendar Sync 是一项自托管服务，可将目标日历作为源日历的投射保持同步。每条规则只观察一个源日历，并只管理一个目标日历，源和目标可以属于不同的 Google 身份。该项目明确标注为 pre-alpha：架构、同步引擎、带认证的 API、Google 适配器和 Web UI 构成了可用的首个纵向切片，但真实账号的耐久性测试和生产就绪审查尚未完成，因此建议使用测试日历并做好备份。 README 中描述的关键设计要点： - 定向规则：一个源、一个目标，并采用以源为准的行为。目标端编辑、缺失的投射和源端取消都会在同步与对账期间被修复。 - 隐私默认值：新规则默认使用 Busy 投射；详情复制为可选，且绝不复制参与者、组织者身份、会议数据、附件或邀请。 - 安全启用：规则必须先通过无副作用的预览，之后才能启用。 - 自包含部署：SQLite、调度、API 和 Web UI 作为一个轻量服务运行，以 Docker 镜像和 Compose 服务形式发布，支持 linux/amd64 和 linux/arm64。 - 无遥测：正常安装仅与同步所需的 Google API 以及操作员配置的任何通知端点通信。 列出的能力包括定时事件和全天事件、重复系列、单次发生变更和取消；仅忙碌或复制详情策略，并可按规则包含全天事件；每五分钟增量轮询，外加手动 Sync Now；每日完整对账，外加 Reconcile Now 并提供漂移报告；通过私有 managed-origin 元数据防止循环；稳定的操作键、游标最后持久化、重试退避和隔离的规则失败；带认证的 Activity 视图，支持去重以及可选的 SMTP 或 webhook 事件投递；一个本地管理员密码，以及加密的 Google OAuth 凭据；浅色/深色主题。 设置需要一个启用了 Calendar API 的 Google Cloud 项目、一个 OAuth 2.0 Web 应用客户端，以及精确的重定向 URI http://localhost:8000/api/v1/oauth/google/callback。本地密钥通过 .env 文件配置，其中包括一个 256 位主密钥，用于以 AES-256-GCM 加密存储的 Google 凭据。README 指出，丢失主密钥会导致已连接账号的凭据无法读取，并且 LAN 主机部署需要特殊处理，因为 Google 会拒绝除 localhost 以外的纯 HTTP 重定向 URI。 同步行为：首次运行会读取结束时间不早于运行前 30 天的源事件，观察目标端，并记录两个端点的 Google 增量令牌。后续运行会消费两个变更流，因此仅目标端的编辑或删除会被修复，而无需完整重新扫描。对于每个相关的源事件，领域层会选择 Create、Update、Delete、Ignore 或 Conflict；身份或归属不明确时不会猜测。游标仅在批次完全成功后推进，提供方写入携带稳定的操作键，因此重试不会重复创建投射。 隐私与安全说明：事件标题、描述和位置在内存中处理，不会存储在 SQLite 或审计条目中；映射保留提供方 ID、修订版本和不可逆指纹；断开账号会丢弃存储的凭据，但不会删除规则、映射或受管理的投射；Google 写入使用 sendUpdates=none；Web UI 和操作 API 需要本地管理员会话，而 /health 保持公开且最小化。 架构是采用 ports-and-adapters 边界的模块化单体；同步领域不依赖 FastAPI、SQLite、Google SDK、React、OAuth 或 Docker。后端开发使用 Python 3.12 和 FastAPI，前端使用 Node.js 22+、React、TypeScript、Vite 和 Tailwind CSS。质量检查包括 ruff、mypy、pytest 且覆盖率下限为 80%、前端 typecheck/lint/test/build，以及多平台 Docker 构建。Google Calendar 是初始版本中唯一的提供方；Outlook 和 CalDAV 被描述为架构上的可能性，而非受支持的功能。该项目目标版本为 0.1.0，采用 MIT License。