自托管

把 OpenTickly 跑在自己的机器上只需要一个 docker-compose.yml。下面走一遍从零到能用的完整流程。

系统要求

• 任一装了 Docker Engine 20.10+ 和 Docker Compose v2 的 Linux、macOS 或 Windows 机器
• 约 1 GB 内存、1 GB 磁盘空间
• 一个空闲的 TCP 端口（默认 8080）

没装 Docker 的话，先按官方指南装好再回来。

部署服务器

步骤 1 — 下载 docker-compose.yml

新建一个目录，把官方 compose 文件拉下来：

mkdir -p opentickly && cd opentickly

wget -O docker-compose.yml \
  https://raw.githubusercontent.com/CorrectRoadH/OpenTickly/main/docker-compose.yml

这份 compose 定义了三个容器：

• OpenTickly — Web UI + REST API（对外暴露 8080）
• postgres — 数据库（只在内部网络，不对外暴露）
• redis — 缓存和后台任务队列（只在内部网络，不对外暴露）

步骤 2 — （可选）配置 .env

默认值开箱即用。需要改端口或密码时，在同目录下建一个 .env：

# Web UI 和 API 的对外端口
OPENTOGGL_PORT=8080

# 生产部署前强烈建议改成强密码
OPENTOGGL_POSTGRES_PASSWORD=postgres
OPENTOGGL_REDIS_PASSWORD=opentoggl

这三个变量是整个 compose 文件仅有的可覆盖配置 — 其他一切（数据库名、用户、镜像、内部连接串）都直接写死，避免配置漂移。需要更深度定制就直接编辑 docker-compose.yml。

步骤 3 — 启动容器

docker compose up -d

访问 Web 应用

浏览器打开 http://<你的 IP>:8080，注册第一个账号就能开始记录时间。

手机端

目前没有官方移动应用，但你可以把 Web UI 加到手机主屏幕上(PWA)。第三方 toggl 客户端如 timery，正在联系开发者适配 OpenTickly 中。

接入 AI Agent

OpenTickly 没有 30 次/小时的 API 限流，这意味着 Claude、Cursor 这类 Agent 可以大胆用。配合 toggl-cli 把技能包装进 Agent 环境，几分钟就能让 AI 帮你启停计时器、整理项目。

升级

docker compose pull
docker compose up -d

部署到 NAS / Homelab

OpenTickly 能跑在任何支持 Docker Compose 的平台上。下面这些只是把上面的流程套进各家的 UI 而已 — 底层命令没有任何差别。

CasaOS

1. 打开 CasaOS 控制面板
2. 进入 应用商店 → 自定义安装 → 导入 docker-compose
3. 粘贴 docker-compose.yml 的内容
4. 把 Web UI 端口设为 8080，保存
5. 从控制面板启动

通过 http://<你的 CasaOS IP>:8080 访问。

ZimaOS

ZimaOS（Zimablade / Zimacube 的官方系统）和 CasaOS 共用同一套应用商店，步骤完全一样：应用商店 → 自定义安装 → 导入 docker-compose，粘贴 compose 文件即可。

群晖 Synology

群晖 DSM 7.2+ 通过 Container Manager 支持 Docker Compose：

1. 打开 Container Manager → 项目 → 新建
2. 项目名例如 opentickly
3. 选 使用 docker-compose.yml，粘贴 compose 文件
4. 一路下一步完成向导

飞牛 fnOS

fnOS 自带 Docker 面板：

1. 打开飞牛桌面的 Docker 应用
2. 左侧选 Compose → 新建项目
3. 项目名 opentickly，存储路径保持默认
4. Compose 内容粘贴 compose 文件
5. 点 部署，等三个容器变绿

其他平台

以下平台都走同样的 Docker Compose 流程：

• Unraid — Community Applications 或 Compose Manager 插件
• TrueNAS SCALE — 自定义应用 + Docker Compose
• Proxmox LXC — 在 LXC 容器里装 Docker，再按 部署服务器 的步骤来

配置参考

整个 compose 文件只有三个可覆盖配置：

其他所有配置（数据库名、用户、镜像 tag、内部连接串、卷名）都直接写死在 docker-compose.yml 里。需要改就编辑文件。

健康检查端点

下一步

• AI 集成 — 让 Claude、Cursor 连上你自己的实例
• GitHub 仓库 — 源码、Issues、Discussions
• 部署中遇到问题？欢迎在 Issues 反馈