Docker

在自己的机器上用 Docker 运行 Calends；本页说明启动、持久化、HTTPS 和备份。

从 v1.1.0 起，预构建镜像发布在 Docker Hub xizozhe/calends 和 GHCR ghcr.io/imetn/calends，均可匿名拉取，支持 linux/amd64 和 linux/arm64。镜像在容器里用 workerd（Cloudflare Workers 的开源运行时）运行同一个 Worker，数据是数据目录里的 SQLite 文件。

1. 用下面任一方式启动容器，始终挂载 /data。
2. 从日志读取初始化令牌，在 /login 设置密码。
3. 公网使用前配置 HTTPS，并设置 SITE_URL。
4. 添加订阅和通知渠道后测试提醒，并安排备份。

直接运行预构建镜像

docker run

docker run -d --name calends -p 8787:8787 -v calends-data:/data xizozhe/calends:latest
docker logs calends

docker compose

在自行选择的部署目录中创建 compose.yaml（仓库里的 docker/docker-compose.yml 默认从源码构建）：

name: calends
services:
  calends:
    image: xizozhe/calends:latest
    restart: unless-stopped
    ports:
      - '8787:8787'
    volumes:
      - calends-data:/data
    environment:
      # 对外访问地址（提醒、日历订阅里的链接），可选
      # SITE_URL: https://calends.example.com
      # 在反向代理后面时设为 1
      # TRUST_PROXY: "1"
      TZ: UTC

volumes:
  calends-data:
    name: calends-data

docker compose up -d
docker compose logs calends

打开 http://localhost:8787，用 docker logs calends（或 docker compose logs calends）里的初始化令牌设置密码。如需改用 GHCR，将示例中的 xizozhe/calends:latest 换成 ghcr.io/imetn/calends:latest。

容器启动时做什么

1. 对数据目录里的数据库执行迁移（幂等，每次启动都会检查）；

2. 准备初始化令牌：设置了环境变量 SETUP_TOKEN 就用它；否则第一次启动时随机生成一个，保存在数据目录的 setup-token 文件里，之后一直沿用；

3. 启动 Worker，监听 PORT（缺省 8787）；

4. 如果还没设置密码，在日志里打印初始化令牌：

   [calends] first run: create your password at /login with this setup token:
   [calends]     <令牌>

5. 每小时第 5 分钟（UTC）触发一次定时任务，和 Cloudflare 上的 Cron 一样：到了提醒时刻就发提醒，汇率过期就刷新。

容器自带健康检查，请求 /api/auth/status。

环境变量

变量	缺省	说明
SETUP_TOKEN	自动生成	首次设置密码用的初始化令牌。
SITE_URL	访问应用时的地址	提醒和日历订阅里的链接。
TRUST_PROXY	不设	在反向代理后面时设为 1，登录限速才能拿到真实访客 IP。
DATA_DIR	/data	数据目录。
PORT	8787	监听端口。
LOG_LEVEL	warn	Worker 的日志级别。

只有 SETUP_TOKEN、SITE_URL、TRUST_PROXY（以及旧版的 OWNER_PASSCODE）会传给 Worker。容器的 TZ 不影响提醒，提醒按「设置 → 通用 → 时区」计算。

警告

Docker 部署没有 Cloudflare Email Sending，邮件渠道不可用。请使用 Telegram、飞书、Bark、ntfy 等其他通知渠道。

HTTPS

在公网使用时，请放在反向代理后面启用 HTTPS，并设置 TRUST_PROXY=1。Passkey 只能在 HTTPS 下使用。以 Caddy 为例：

calends.example.com {
  reverse_proxy 127.0.0.1:8787
}

更多见自定义域名与 HTTPS。

数据与备份

所有数据都在数据卷 calends-data（容器内 /data）里，包括 SQLite 数据库和 setup-token 文件。删除容器不会丢数据，删除数据卷会。

两种备份方式：

• 在应用「设置 → 数据 → 导出完整备份」，得到一个可以在任何部署上恢复的 JSON 文件，见备份与恢复；

• 停止容器后打包数据卷：

  docker stop calends
  docker run --rm -v calends-data:/data -v "$PWD":/backup alpine tar czf /backup/calends-data.tgz -C /data .
  docker start calends

从源码构建

Dockerfile 位于 docker/Dockerfile，仓库的 Compose 配置位于 docker/docker-compose.yml。用 Compose 构建并启动：

git clone https://github.com/imetn/calends && cd calends
cd docker && docker compose up -d --build
docker compose logs calends

该 Compose 项目名为 calends，数据卷为 calends_calends-data。备份或升级此部署时应使用这个卷名；它与上面预构建镜像示例使用的 calends-data 是两个独立的卷。

也可以在仓库根目录手动构建并启动：

docker build -f docker/Dockerfile -t calends:local .
docker run -d --name calends -p 8787:8787 -v calends-data:/data calends:local
docker logs calends

镜像标签

标签	含义
latest	跟随镜像更新。
1.6.0	固定发布版本，适合控制升级节奏。
1.6	跟随 1.6 系列的补丁版本。

两个仓库都提供这些标签。生产部署建议固定具体版本，例如 xizozhe/calends:1.6.0；GHCR 备选为 ghcr.io/imetn/calends:1.6.0。

升级镜像

先拉取新镜像，再使用原数据卷重建容器：

docker pull xizozhe/calends:latest
docker stop calends
docker rm calends
docker run -d --name calends -p 8787:8787 -v calends-data:/data xizozhe/calends:latest

重建时保留原有端口、环境变量和重启策略。删除容器会保留命名卷，不要删除数据卷。固定版本部署时，将两条命令中的 latest 都换成目标版本。使用上面的预构建镜像 compose.yaml 时，在其目录运行 docker compose pull，再运行 docker compose up -d，保留相同的 Compose 项目与数据卷配置。

源码构建的升级方法和升级后检查见升级。