Candlr：把全家生日装进自己的服务器，到期自动提醒

发表于 2026-09-30 分类于各种折腾 Waline：阅读次数：本文字数： 3.5k 阅读时长 ≈ 3 分钟

Candlr 是一个自托管的生日和纪念日日历提醒工具，支持日历订阅和多种通知方式。

简介

什么是 Candlr ？

Candlr 是一个开源的、支持自托管的生日与纪念日日历工具。它把所有人的生日、结婚纪念日和自定义重要日子集中记录在一个地方，配合每日定时提醒，让你再也不会错过任何一个重要的日子——你的数据，你的服务器。

主要特点

人物卡片 + 多日期：一张卡片可以记录多个日期（例如同一位亲友的生日和结婚纪念日），支持上传照片并内置裁剪编辑，备注支持 Markdown；年份可留空，只记录月日。
批量操作：在事件页可一次选中多张卡片，批量删除、批量转换日期类型（如把”生日”改为自定义类型），或一键批量开启/关闭提醒。
数据导入导出：支持以 CSV 或 JSON 格式导出全部卡片，也可从这两种格式导入并与现有数据合并，重复导入不会产生重复数据。
日历订阅：提供私有的 iCal 订阅链接，可把全部日期同步进 Google Calendar、Apple Calendar、Thunderbird 等支持 URL 订阅的应用，按年自动重复并随卡片更新。
OIDC / SSO 单点登录：支持对接 Authelia、Authentik、Keycloak 等任意 OpenID Connect 提供商，可选自动创建账号，也可仅使用本地账号。
丰富的通知渠道：支持邮件、ntfy、Discord、Telegram、Pushover 以及浏览器/设备推送，每个账号可在设置页自行配置，并带”发送测试”按钮，当天还会自动提醒。
深色/浅色主题：默认跟随系统，也可在导航栏和登录/注册页手动切换。
SQLite 单文件存储：数据存放在一个 SQLite 文件中，无需独立数据库容器，备份即复制整个 data 目录。

应用场景

家庭纪念日管理：把全家人的生日、结婚纪念日集中记录，开启邮件或 Telegram 通知，到了当天自动提醒家人，避免遗漏。
团队/社群日期提醒：管理者可为成员记录生日或入职纪念日，通过 Discord 等通知渠道在当日自动发送祝福或告示。
个人日程补充：把不想塞进主日历的重要日期（如宠物生日、设备保修到期日）单独记录，并通过 iCal 订阅回流到常用日历。
开发者测试：开发人员可以快速使用 Docker 搭建测试环境，体验 Astro 前端 + FastAPI 后端的完整技术栈。

Candlr 仪表盘界面

Candlr 是一个轻量、自托管、强隐私的生日与纪念日记录提醒工具，把数据牢牢握在自己手里。

安装

在群晖上以 Docker 方式安装。

在注册表中搜索 candlr，选择第一个 bellamy/candlr，版本选择 latest。

本文写作时，latest 版本对应为 1.3.4。

卷

在 docker 文件夹中，创建一个新文件夹 candlr，并在其中建一个子文件夹 data

文件夹	装载路径	说明
`docker/candlr/data`	`/app/backend/data`	存放 `SQLite` 数据库和上传的照片

卷设置截图

端口

本地端口不冲突就行，不确定的话可以用命令查一下

1 2	# 查看端口占用 netstat -tunlp \| grep 4258

本地端口	容器端口
`4258`	`4258`

端口设置截图

环境

可变	值
`SECRET_KEY`	必填，用于 JWT 签名和 2FA 秘钥加密，用 `openssl rand -hex 32` 生成
`PUID`	运行进程的用户 ID，默认 `1000`
`PGID`	运行进程的组 ID，默认 `1000`
`TIMEZONE`	IANA 时区名（如 `Asia/Shanghai`），默认 `UTC`，决定”今天”和提醒时间
`COOKIE_SECURE`	通过 HTTPS 访问时设为 `true`，默认 `false`
`SERVER_URL`	外部访问地址，用于邮件内构建密码重置链接
`ENABLE_REGISTRATIONS`	是否允许更多用户注册，默认 `false`（首个账号始终可创建）

更多环境变量，请参考官方文档 https://github.com/ellite/candlr#configuration

环境变量说明：SECRET_KEY 是必填项，应用在留空默认值时会拒绝启动；请用 openssl rand -hex 32 生成随机串。TIMEZONE 建议设置为 Asia/Shanghai 以匹配本地时区，否则提醒时间和”今天”会按 UTC 计算。

docker cli 安装

通过 SSH 登录到你的群晖后，执行下面的命令：

# 新建文件夹 candlr 和 子目录
mkdir -p /volume1/docker/candlr/data

# 进入 candlr 目录
cd /volume1/docker/candlr

# 运行容器
docker run -d \
  --name candlr \
  --restart unless-stopped \
  -p 4258:4258 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e SECRET_KEY="$(openssl rand -hex 32)" \
  -e TIMEZONE=Asia/Shanghai \
  -v $(pwd)/data:/app/backend/data \
  bellamy/candlr:latest

docker-compose 安装

将下面的内容保存为 docker-compose.yml 文件：

services:
  candlr:
    image: bellamy/candlr:latest
    container_name: candlr
    restart: unless-stopped
    ports:
      - "4258:4258"
    volumes:
      - ./data:/app/backend/data
    environment:
      - PUID=1000
      - PGID=1000
      - SECRET_KEY=changeme   # 必填，用 openssl rand -hex 32 生成
      - TIMEZONE=Asia/Shanghai   # IANA 时区名，默认 UTC

然后通过 SSH 登录到您的群晖，执行下面的命令：

# 新建文件夹 candlr 和 子目录
mkdir -p /volume1/docker/candlr/data

# 进入 candlr 目录
cd /volume1/docker/candlr

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -d

运行

在浏览器中访问 http://<群晖IP>:4258 即可进入登录界面

第一次需要点下面的 Create one 新建账号

密码不能少于 8 位；注册完成的第一个账号自动成为实例管理员

登录成功后的主界面

进入 Event 添加人物卡片

随便编了几个

除了生日，还可以添加其他的纪念日

回到 Dashboard

进入设置，可以选择通知的方式

邮件需管理员配置 SMTP，ntfy/Discord/Telegram/Pushover 则由各用户自行填写

如需订阅日历，在日历页点击 Subscribe 按钮获取私有 iCal 链接，即可同步进其他日历应用

注意事项

SECRET_KEY 必须设置且保持稳定：它用于 JWT 签名和 2FA 秘钥加密，请使用 openssl rand -hex 32 生成，并与数据库一起备份。修改它会令已保存的身份验证器秘钥无法读取。[需确认]
务必开启 HTTPS 并设置 COOKIE_SECURE=true：生产环境暴露外网时建议配置反向代理并启用 HTTPS，确保认证 Cookie 标记为安全。
时区设置：TIMEZONE 默认是 UTC，对单实例家庭应用来说几乎总不是想要的值，建议设置为本地时区（如 Asia/Shanghai），否则提醒和”今天”的判断会不准。
数据库迁移自动执行：升级到新版本无需手动迁移，启动时自动完成；升级前建议先完整备份整个 data/ 目录（含 candlr.db 数据库和 images/ 照片）。
外部通知依赖：如需邮件提醒或忘记/重置密码功能，必须先配置 SMTP 相关变量，否则邮件通道会整体停用。
安全建议：默认关闭注册（ENABLE_REGISTRATIONS=false），首个账号永远可以注册；如只自己使用，保持关闭以避免他人注册。

参考文档

elitte/candlr: Candlr - a self-hosted birthday / anniversary calendar and reminder
地址：https://github.com/ellite/candlr

bellamy/candlr - Docker Hub 镜像页
地址：https://hub.docker.com/r/bellamy/candlr

Candlr 官网（演示站）
地址：https://candlr.henrique.pt