fluid-calendar：实践指南

真正理解fluid-calendar，要从它处理的任务开始：面向任务调度和日历管理的开源应用，提供智能排期、日历集成与可配置工作流，目前仍处于积极开发阶段。实际做软件开发时，经常会碰到依赖、接口和异常处理往往比主路径更影响采用，所以功能列表并不能代替验证。落地前可以在隔离分支完成一个可回滚的小任务，用安装步骤、接口契约、测试结果和错误信息判断它是否真的省事。它对需要可检查开发流程而非单次演示的工程师更有价值，但正式采用前仍要复查许可证、近期提交和问题区回应。

FluidCalendar

Motion 的开源替代方案，专为智能任务调度和日历管理而设计。 FluidCalendar 通过智能调度功能、日历集成和可定制的工作流程帮助您掌控任务。

⚠ WARNING: ACTIVE DEVELOPMENT VERY BUGGY - REPORT BUGS AND BE PATIENT ✌ ⚠

该项目正在积极开发中，目前包含许多错误和不完整的功能。尚不建议用于生产用途。如果您遇到问题：

1. 请检查 现有问题 是否已报告
2. 如果未找到，创建一个新问题：
   • 重现步骤
   • 预期行为
   • 实际行为
   • 任何相关的错误消息或屏幕截图

您的错误报告有助于使 FluidCalendar 变得更好！感谢您在我们努力稳定平台过程中的耐心和贡献。

关于

FluidCalendar 专为想要完全控制其调度工作流程的人员而设计。它结合了自动任务调度的强大功能和开源软件的灵活性。请阅读我的博客系列 的 [第 1 部分，了解有关旅程和动机的更多信息。

如果您觉得 FluidCalendar 有用，请考虑支持其开发。您的赞助有助于确保持续的维护和新功能。

通过成为赞助商，您：

• 帮助保持项目的积极维护
• 尽早使用新功能
• 支持开源软件开发

赞助商

NitroClaw - 您自己的 OpenClaw 助手，零 服务器麻烦

在 2 分钟内部署专用 OpenClaw AI 助手。选择您的 LLM，连接 T@elegrimm，然后 开始聊天 - 我们处理所有基础设施。 $100/month 包含 50 美元的 AI 积分。

开始使用

尝试SaaS版本

不想自行托管？我们目前正在 FluidCalendar.com 上对我们的托管版本进行 Beta 测试。注册候补名单，成为首批体验智能日历管理未来的人之一，拥有开源版本的所有功能以及：

• 托管基础设施
• 自动更新
• 高级支持
• 高级 AI 功能

付费自托管评论

尝试自己运行 FluidCalendar 并卡在数据库、OAuth 回调 URLs、Google/Outlook 范围、Docker 或生产环境值上？

首先使用 自托管设置清单。如果您想要第二双眼睛，您可以花费 12 美元 购买重点设置评论：

获取 FluidCalendar 设置审核

结账时会要求您提供存储库、部署 URL 或设置说明以及主要阻止程序。审核是对您的公共设置详细信息的简短手动传递，以及要尝试的下一个具体修复。请勿发送机密或私人 OAuth 凭证。

特点

• 智能任务安排 - 根据您的偏好和可用性自动安排任务
• 日历集成 - 与 Google 日历无缝同步（更多提供商即将推出）
• ⚡ 智能时间段管理 - 根据您的工作时间和缓冲偏好找到最佳时间段
• 现代 UI - 干净、响应灵敏的界面，过渡平滑
• 可定制 - 根据您的需求调整调度算法和偏好
• 注重隐私 - 自行托管您自己的实例

技术堆栈

• Next.js 15 带应用路由器
• TypeScript
• Prisma 用于数据库管理
• FullCalendar 日历 UI
• NextAuth.js 用于身份验证
• Tailwind CSS 用于造型

先决条件

• Node.js（.nvmrc中指定的版本）
• PostgreSQL 15 或更高版本（捆绑的 docker-compose.yml 使用 PostgreSQL 16；如果您将 DATABASE_URL 指向您自己的数据库，则它必须是 PostgreSQL 15+）
• Google Cloud 项目（用于 Google 日历集成）

谷歌云设置

要启用 Google 日历集成：

1. 创建一个项目：

   • 转到 Google Cloud 控制台
   • 单击“新建项目”并按照提示操作
   • 记下您的项目 ID

2. 启用所需的APIs：

   • 在您的项目中，转到“APIs & 服务”>“库”
   • 搜索并启用：
     • 谷歌日历 API
     • Google People API（用于用户个人资料信息）

3. 配置 OAuth 同意屏幕：

   • 前往“APIs 与服务”>“OAuth 同意屏幕”
   • 选择“外部”用户类型
   • 填写所需信息：
     • 应用程序名称：“FluidCalendar”（或您喜欢的名称）
     • 用户支持电子邮件
     • 开发商联系信息
   • 添加范围（这些范围与 FluidCalendar 实际请求的范围匹配）：
     • openid
     • email
     • https://www.googleapis.com/auth/calendar
     • https://www.googleapis.com/auth/calendar.events
     • https://www.googleapis.com/auth/userinfo.email
     • https://www.googleapis.com/auth/tasks （用于 Google 任务同步）
   • 如果处于测试模式，则添加测试用户

4. 创建 OAuth 2.0 凭证：

   • 前往“APIs 与服务”>“凭证”
   • 点击“创建凭证”>“OAuth客户端ID”
   • 选择“网络应用程序”
   • 设置授权 JavaScript 来源：
     • http://localhost:3000（用于开发）
     • 您的生产 URL（如果已部署）
   • 设置授权重定向 URIs（添加 两个 路径 - 一个用于 Google 登录，另一个用于连接日历）：
     • http://localhost:3000/api/auth/callback/google（用于开发）
     • http://localhost:3000/api/calendar/google（用于开发）
     • https://your-domain.com/api/auth/callback/google（用于生产）
     • https://your-domain.com/api/calendar/google（用于生产）
   • 点击“创建”
   • 保存生成的Client ID和Client Secret

   这些与应用内 设置 > 系统 面板为您的部署显示的两个重定向 URIs 相同，因此应用程序和这些说明相匹配。将主机替换为您打开 FluidCalendar 的确切 URL 。

5. 配置凭证：

   • 进入 FluidCalendar 设置 > 系统
   • 在 Google 日历集成部分输入您的 Google 客户端 ID 和客户端密钥
   • 或者将环境变量设置为后备：

     GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
     GOOGLE_CLIENT_SECRET="your-client-secret"
     

排查 Google 连接问题

如果 Google 在您连接时返回 Error 400: redirect_uri_mismatch 或“无效重定向”：

• NEXTAUTH_URL 必须与您在浏览器中打开的公共 URL 匹配。 OAuth 重定向主机源自 NEXTAUTH_URL（不是 NEXT_PUBLIC_APP_URL）。如果 NEXTAUTH_URL 仍然是 http://localhost:3000，但您通过不同的 URL 访问应用程序，则 Google 会被发送回 localhost，并且连接失败。将 NEXTAUTH_URL 设置为确切的公共 URL 并重新启动应用程序。
• 注册两个重定向 URIs。 如果确切的回调 URL 不在授权列表中，则 Google 会拒绝该请求。确保您的主机列出了 …/api/auth/callback/google 和 …/api/calendar/google（请参阅上面的步骤 4）。
• Google 不接受裸露的私有 IP 地址（e.g.http://192.168.1.150:3000）或 .local 主机名作为重定向 URIs（“必须以公共顶级域结尾”）。对于本地开发使用localhost；否则将应用程序公开在公共域（反向代理或隧道）上，并在 NEXTAUTH_URL 和 Google 重定向 URIs 中使用该域。

注意：对于生产部署，您需要：

• 验证您的域名所有权
• 如果您计划拥有超过 100 个用户，请提交申请进行验证
• 将您的生产域添加到授权源并重定向 URIs

微软 Outlook 设置

要启用 Outlook 日历集成：

1. 创建 Azure AD 应用程序：

   • 转到 Azure 门户
   • 点击“新注册”
   • 为您的应用程序命名（e.g.，“FluidCalendar”）
   • 在“支持的帐户类型”下，选择“任何组织目录中的帐户（任何 Azure AD 目录 - 多租户）和个人 Microsoft 帐户（e.g.Skype、Xbox）”
   • 点击“注册”

2. 配置平台设置：

   • 在您注册的应用程序中，转到“身份验证”
   • 点击“添加平台”
   • 选择“网络”
   • 添加重定向 URIs（这是 FluidCalendar 用于 Outlook 的确切回调路径 - 它必须与没有尾部斜杠的匹配）：
     • http://localhost:3000/api/calendar/outlook（用于开发）
     • https://your-domain.com/api/calendar/outlook（用于生产）
   • 在“隐式授予”下，选中“访问令牌”和“ID 令牌”
   • 点击“配置”

3. 添加 API 权限：

   • 转到“API权限”
   • 点击“添加权限”
   • 选择“Microsoft Graph”
   • 选择“委托权限”
   • 添加以下权限：
     • Calendars.ReadWrite
     • Tasks.ReadWrite
     • User.Read
     • offline_access
   • 点击“添加权限”
   • 点击“授予管理员同意”（如果您是管理员）

4. 创建客户端秘密：

   • 转到“证书和机密”
   • 点击“新客户端密码”
   • 添加描述并选择到期时间
   • 点击“添加”
   • 立即复制生成的秘密值（您将无法再次看到它）

5. 配置凭证：

   • 进入 FluidCalendar 设置 > 系统
   • 在 Outlook 日历集成部分中输入您的 Outlook 凭据：
     • 客户端 ID（应用程序 ID）
     • 客户秘密
     • 租户 ID（可选 - 留空以允许任何 Microsoft 帐户）
   • 或者将环境变量设置为后备：

     AZURE_AD_CLIENT_ID="your-client-id"
     AZURE_AD_CLIENT_SECRET="your-client-secret"
     AZURE_AD_TENANT_ID="your-tenant-id-or-common"
     

注意：对于生产部署：

• 更新重定向 URIs 以包含您的生产域
• 确保授予所有必需的权限
• 考虑根据您的需求实施额外的安全措施

安装

Docker 快速入门（推荐）

1. 在你的机器上安装 Docker

2. 克隆存储库（或仅下载 docker-compose.yml 文件）：

   git clone https://github.com/dotnetfactory/fluid-calendar.git
   cd fluid-calendar
   

3. 复制示例环境文件并配置它：

   cp .env.example .env
   

   编辑 .env 文件并至少设置以下值：

   DATABASE_URL=postgresql://fluid:fluid@db:5432/fluid_calendar
   NEXTAUTH_URL=http://localhost:3000
   NEXTAUTH_SECRET=your-random-secret-key
   

4. 运行应用程序：

   docker compose up -d
   

5. 访问 http://localhost:3000

就是这样！该应用程序将使用自动配置的 PostgreSQL 数据库运行。 docker-compose.yml 文件已配置为使用预构建的 Docker 映像。

关于端口的说明： 容器侦听 0.0.0.0:3000，docker-compose.yml 通过 environment: PORT=3000 和 HOSTNAME=0.0.0.0 进行引脚固定。在 .env 中设置 PORT 或 HOSTNAME 将不会更改应用程序绑定的位置（撰写会覆盖它们） - 这可以避免应用程序绑定到与发布的端口或环回地址不同的端口或环回地址。要在不同的主机端口上提供服务，请更改 docker-compose.yml 中 ports 映射的主机端（例如 "8080:3000" 以使用 http://localhost:8080）并更新 NEXTAUTH_URL（以及其他面向浏览器的 URLs - NEXT_PUBLIC_APP_URL、NEXT_PUBLIC_SITE_URL）将您的 .env 中的 host/port 更改为相同的 host/port，因为应用程序从 NEXTAUTH_URL 派生其 OAuth 重定向 URLs；在 :8080 上浏览时将其保留在 :3000 上会破坏登录和日历身份验证。

对于开发人员

如果要开发FluidCalendar：

1. 克隆存储库：

   git clone https://github.com/dotnetfactory/fluid-calendar.git
   cd fluid-calendar
   

2. 启动开发环境：

   docker compose -f docker-compose.yml up -d
   

3. 访问 http://localhost:3000

开发环境包括：

• 热重载
• PostgreSQL数据库
• 开发工具
• 公开数据库端口（5432）以供直接访问

有用的 Docker 命令

# View logs
docker compose logs -f

# Stop the application
docker compose down

# Update to the latest version
docker pull eibrahim/fluid-calendar:latest
docker compose up -d

# Reset database (caution: deletes all data)
docker compose down -v
docker compose up -d

# Access database CLI
docker compose exec db psql -U fluid -d fluid_calendar

环境设置

1. 将 .env.example 复制到 .env：

cp .env.example .env

2. 配置以下环境变量：

• DATABASE_URL：您的数据库连接字符串
• NEXTAUTH_URL：您的应用程序 URL
• NEXTAUTH_SECRET：会话加密的随机字符串

注意：Google 凭据和日志记录设置可以通过“设置”>“系统”中的 UI 进行管理。如果未配置系统设置，环境变量将用作后备。

开始使用

首先，运行开发服务器：

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

用浏览器打开 http://localhost:3000 查看结果。

需要专业帮助吗？

不想自己处理迁移？我们为您提供完整的定制服务，包括：

• 托管 OpenProject 托管
• 完成 Jira 迁移
• 24/7 技术支持
• 安全可靠的基础设施

请访问 portfolio.elitecoders.co/openproject，了解有关我们的托管 OpenProject 迁移服务的更多信息。

关于

该项目由 EliteCoders 构建，这是一家专门从事定制软件解决方案的软件开发公司。如果您需要帮助：

• 定制软件开发
• 系统集成
• 迁移工具和服务
• 技术咨询

请通过 [email protected] 联系我们或访问我们的网站 www.elitecoders.co。

SAAS 开发

FluidCalendar 可作为开源自托管解决方案和托管 SAAS 服务。开源版本包含所有核心功能，而 SAAS 版本则包含额外的高级功能。

开源与 SAAS 特性

特点	开源	SAAS
日历管理	✅	✅
任务管理	✅	✅
谷歌日历集成	✅	✅
Outlook 日历集成	✅	✅
CalDAV 集成	✅	✅
计费和订阅管理	❌	✅

SAAS 开发设置

如果您是 SAAS 版本的贡献者，请按照以下步骤设置您的开发环境：

1. 克隆私有 SAAS 存储库：

   git clone https://github.com/dotnetfactory/fluid-calendar-saas.git
   

2. 在您的环境中启用 SAAS 功能：

   # .env.local
   ENABLE_SAAS_FEATURES=true
   

3. 运行开发服务器：

   npm run dev
   

在存储库之间同步更改

要将更改从私有 SAAS 存储库同步到公共开源存储库：

1. 使用提供的同步脚本：

   ./scripts/sync-repos.sh /path/to/private/repo /path/to/public/repo
   

2. 查看公共存储库中的更改

3. 提交更改并将其推送到公共存储库