Cal.diy v6.2.0 介绍与选型指南

Cal.diy v6.2.0 介绍与选型指南：Cal.com 官方开源社区版（MIT）定位、Next.js+tRPC+Prisma 核心架构、预约调度功能特性、快速上手路径与社区版能力边界，及 Easy!Appointments/Rallly/LibreBooking/Hi.Events 等同类量化对比。社区与版本数据 2026-10-19 实查。

Cal.diy调度2026/10/19

Cal.diy v6.2.0 介绍与选型指南

目标：介绍开源预约调度系统 Cal.diy 的定位、核心架构、功能特性与同类方案选型结论，帮助读者判断是否选用以及与 Easy!Appointments、Rallly、LibreBooking 等同类方案如何取舍。版本与社区数据已于 2026-10-19 通过 GitHub、官方文档站逐项实查，关键论断均标注来源与查询日期。

一、环境信息

本章是本文全部结论的信息基准：所有版本号、社区数据、仓库与许可信息，均于查询日期 2026-10-19 通过官方渠道实查获得，未做任何推测性补齐。

  • 信息基准（查询日期）：2026-10-19
  • 版本依据：GitHub Releases 最新稳定版 v6.2.0，发布于 2026-03-01（来源：https://github.com/calcom/cal.diy/releases.atom，2026-10-19 实查；该版本为普通正式发布，非 Pre-release）
  • 官方来源清单：
    • 代码仓库：https://github.com/calcom/cal.diy（注：cal.com/cal.com 已不存在，官网 GitHub 入口指向 calcom/cal.com 并 301 重定向至 calcom/cal.diy，2026-10-19 实查）
    • 官方文档站（自托管文档）：https://cal.diy
    • 官网：https://cal.com（商业云服务）
  • 社区数据（2026-10-19 实查）：
    • Stars：48,971（来源：awesome-selfhosted 收录快照 + https://img.shields.io/github/stars/calcom/cal.diy.json）
    • 许可证：MIT（README 与仓库许可文件实查。注意：部分第三方资料将其误记为 AGPL-3.0，实查结果为 MIT）
    • 版本节奏：v6.1.10（2026-02-02）至 v6.2.0（2026-03-01）约一个月内发布 8 个版本，patch 迭代频繁，处于活跃维护期
  • 技术栈（仓库 package.json / Dockerfile 实查）：Next.js（App Router + Pages Router 混合）+ TypeScript + tRPC + Prisma ORM + PostgreSQL（必需）+ Redis（可选，多副本必需）+ Node.js 20

二、软件概述

Cal.diy 是 Cal.com 官方开源的预约调度基础设施社区版，定位为「Scheduling infrastructure for absolutely everyone」。它是 Cal.com 商业云产品（app.cal.com）的上游社区发行版：官方仓库 README 明确说明 Cal.diy 是 Cal.com 的一个 fork，其中所有企业版/商业授权代码（enterprise/commercial code）已被移除，允许用户在自有服务器上自托管一套与 Cal.com 云服务同源的预约调度系统。

对个人与小团队而言，Cal.diy 解决的核心问题是「公开可预约的日程协调」：使用者维护自己的可预约时段规则，外部预约者打开个人预约页选择时段完成预约，系统自动完成时段锁定、双向时区换算、确认通知与视频会议链接生成。它对标的是 Calendly 这类 SaaS 调度工具的自托管替代，而非会议室资源管理或活动售票工具。

理解品牌关系需要区分三个名称：Cal.com 是公司与其商业云服务；cal.com/cal.com 仓库已于 2025 年前后更名，GitHub 现重定向到 calcom/cal.diy；Cal.diy 即社区可自由自托管的开源主体。市面资料中「Cal.com 开源自托管版」的说法指的就是本项目。

三、核心架构

Cal.diy 采用单体 Next.js 应用 + PostgreSQL 的经典形态，按 v6.2.0 仓库代码与官方部署文档（https://cal.diy/docker）梳理如下：

  • Web 应用（apps/web）：Next.js 全栈单体，同时承载预约页渲染、个人设置后台、管理后台与内部 API。内部服务间调用大量使用 tRPC（类型安全 RPC），对外集成则走 REST。
  • API v2（apps/api/v2）：独立 NestJS 服务，提供版本化的 REST API（/v2/...），供第三方平台集成使用。官方 Docker Compose 形态中以独立服务编排（v6.2.0 的 compose 内为 build 构建形态，无预构建镜像发布位，见第五章说明）。
  • 数据层：PostgreSQL 单库，Prisma ORM 管理（v6.2.0 schema 含 588 个迁移文件）；Redis 用于会话缓存、限流与多副本场景下的任务队列，官方文档标注单实例部署为可选、多副本部署为必需。
  • 运行时自动化：官方启动脚本 start.sh 在每次启动时执行 npx prisma migrate deploy（数据库结构迁移）与 seed 脚本（内置应用目录初始化），保证版本升级时数据结构自动前滚。
  • 定时与队列：提醒邮件、日程同步等异步任务依赖 Redis 队列与工作进程；视频会议默认通过 Daily.co（Cal Video）生成即时会议链接。
  • 认证体系：内置邮箱密码 + 可选双因素认证（TOTP/备份码）；SSO/SAML/Organization 等企业登录能力随 EE 代码移除，社区版不包含。
  • 有删减的企业能力：Teams/Organizations 协作、Insights 报表、Workflows 自动化序列、SSO/SAML、Stripe 托管计费等在 Cal.diy 中已被移除，个人级功能（事件类型、日程规则、 Booker 页面、Webhook、API）完整保留。

四、功能特性

以下功能均以 v6.2.0 代码与官方文档为准（2026-10-19 实查）：

  • 事件类型与预约页：每人可创建多类事件（30 分钟技术交流、1 小时深度咨询等），每类事件有独立的时长、时段规则、地点与缓冲设置；预约页形如 <域名>/<用户名>/<事件slug>，支持嵌入到第三方站点（embed.js）。
  • 时段规则（Schedule）：按星期几定义工作时间，支持多时段、时区归属与日期覆盖（date override）；预约者看到的时段自动按其本地时区换算。
  • 时区处理：全链路时区感知——预约者浏览器时区、事件类型锁定时区、用户配置时区三层语义，预约确认页与日历事件均带正确时区。
  • 日历双向同步：连接 Google Calendar、Microsoft 365/Outlook、CalDAV 等，预约写入日历 busy 状态、冲突时段自动排除，避免双重预订（double-booking）。
  • 视频会议：内置 Cal Video（Daily.co）；亦支持按事件类型指定 Zoom、Google Meet 等第三方会议应用自动生成会议链接。
  • Webhook：预约创建、取消、改期、支付等核心事件可推送至外部地址，带 X-Cal-Signature-256 HMAC-SHA256 签名可用于回调验真（本文同批《Cal.diy 日常运维与排障手册》有实测复现）。
  • API：REST API v2 覆盖用户、日程、事件类型、时段查询、预约、Webhook 等资源，支持 API Key 与 OAuth Client 两种凭据（详见第五章限制说明）。
  • 管理后台：ADMIN 角色可管理用户、开关平台级 Feature Flags、查看部署信息；首个注册用户由管理员在数据库提权（标准自托管流程，见《Cal.diy 快速入门与实战示例》）。
  • 界面与语言：界面支持包括简体中文（zh-CN）在内的多语言；深浅色主题自动切换。

五、快速上手

Cal.diy 官方提供 Docker Compose 自托管形态（官方文档：https://cal.diy/docker，2026-10-19 实查）。要点如下，完整逐命令过程见同批《Cal.diy Docker Compose 部署指南》：

  • 部署最小集为「应用 + PostgreSQL」，Web 应用启动时自动执行数据库迁移；官方 compose 文件另含 API v2 与 Prisma Studio（可选调试工具）服务定义。
  • 官方应用发布位为 calcom/cal.com（Docker Hub 实查 5,155,588 pulls，v6.2.0 tag 于 2026-03-02 推送）；注意 calcom/cal.diy 仓库在 Docker Hub 虽存在但无任何 tag，直接 pull calcom/cal.diy 会失败——这是官方文档与镜像发布位不一致的一个已知坑点。
  • 首次访问 /auth/setup 进入初始化向导创建管理员；自托管模式下首个用户默认普通角色，需在数据库中将 role 提升为 ADMIN 才能使用管理后台。
  • 配置核心是 .env：数据库连接、NEXTAUTH_URL（站点对外地址）、NEXTAUTH_SECRET 与 CALENDSO_ENCRYPTION_KEY 两个密钥（官方文档提供生成命令），以及 ALLOWED_HOSTNAMES（非标准域名访问时必须配置）。

六、适用场景与限制

适用场景：

  • 个人/小团队对外预约：咨询、面试、销售演示、技术支持等需要外部人员预约时间的场景，是最贴合 Cal.diy 主线能力的用法。
  • 替代 Calendly 的私有化部署：对数据出境、品牌白标有要求的团队，用自有域名自托管，预约页与数据完全留在内网/自有服务器。
  • 需要 API 与 Webhook 集成的调度中枢：把预约事件流推送到自有业务系统（CRM、工单、IM 通知），或用 API 批量管理事件类型与时段。

限制与注意点（v6.2.0 实查）：

  • 无团队协作：Teams/Organizations 代码已移除，不能做多人排班、集体可用性聚合（round-robin 等）；此类需求需评估 SaaS 或商业授权版本。
  • 无 Workflows 自动化：预约前后的多步自动化提醒序列不可用；通知仅保留邮件基础形态。
  • API v2 的 license 门槛：API v2 服务启动需要 STRIPE_API_KEY 等环境变量存在；API Key 认证链路在校验 CALCOM_LICENSE_KEY（企业 license，需向 Cal.com 购买）不通过时返回 401，社区版免费额度不含 API Key 通道——但携带 Web 会话（NextAuth Cookie）调用 API v2 不经 license 校验，实测可用（复现过程见《Cal.diy 快速入门与实战示例》）。纯 API Key 对接的读者请先评估这一点。
  • 单库 PostgreSQL 为状态基座：备份与升级策略围绕数据库展开，需按《Cal.diy 日常运维与排障手册》建立例行备份。
  • 无官方 Helm/Operator：官方形态是 Docker Compose 与裸机构建，Kubernetes 部署需自行封装。

七、同类选型对比

以下数据均为 2026-10-19 实查（Stars 与最新 Release 取自 shields.io GitHub 徽章接口 img.shields.io/github/{stars,v,release}/<owner>/<repo>.json；任务清单中提到的「Taki」经 GitHub 与全网多轮检索无对应自托管预约调度项目，未列入对比，特此说明）。

项目Stars（2026-10-19）最新稳定版定位与 Cal.diy 的差异
Cal.diy48,971v6.2.0（2026-03-01）个人预约调度（Calendly 类）本体；MIT；社区版无团队/工作流/SSO
Easy!Appointments4.4kv1.6.1传统预约管理（服务商-客户排班）PHP 技术栈；面向线下服务门店（诊所/美容/培训），带客户档案与仪表盘；社区规模约为 Cal.diy 的 1/11
Rallly5.3kv4.15.5多人投票选时（Doodle 类）解决「一群人互约时间」，无长期时段规则与日历同步；与 Cal.diy 互补而非同类
LibreBooking830v7.1.0资源预约（会议室/设备）以资源为中心的排期管理，无个人日程语义；由 Booked 项目延续维护
Hi.Events4.1kv1.11.1-beta活动售票与活动页面向活动的票务（含支付），不是持续性预约调度；当前为 beta 线
Alf.io1.6kv2.0-M5-2609活动售票（会议/展会）同为票务域，Java 技术栈；成熟但非调度类
Seatsurfing316v1.136.1办公工位/座位预订企业内部工位共享场景，垂直度极高，与通用预约调度交集小

选型结论：

  • 要「Calendly 的自托管替身」：Cal.diy 是唯一与 Cal.com 云服务同源、预约页体验对齐 SaaS 产品、且社区规模（约 4.9 万 Stars）显著领先的选择；同档竞品 Easy!Appointments 功能更偏线下服务管理，Rallly 是投票选时而非时段规则，域内没有量级相当的直接对手。
  • 要团队排班/多人可用性聚合：Cal.diy 社区版不含 Teams，需确认该缺口可接受，或改用商业授权/云服务。
  • 要 API 深度对接：Cal.diy 的 API v2 面完整（资源模型覆盖用户/日程/事件类型/时段/预约/Webhook），但 API Key 通道有 license 门槛（见第六章），轻量集成可用会话通道或 Webhook 出站替代。
  • 自托管通知体系选型：若需要把预约事件接入邮件/IM 通知流水线，Webhook 出站是标准路径，可配合站内《Listmonk》v6.2.0（24k Stars，邮件列表）构建订阅通知，或参考站内ntfy做实时消息推送。

八、参考链接