TimeTagger开源软件

概述

本节介绍 TimeTagger——一个开源的时间记录软件，作为我们资产追踪系统的后端数据库。学习完本节后，您将能够：

理解 TimeTagger 是什么及其主要功能
使用 Docker Compose 安装 TimeTagger
配置具有认证凭据的 TimeTagger
通过 Web UI 执行基本的 TimeTagger 操作

前置要求

开始本节前，请确保您已完成：

安装 Docker 和 Docker Compose（参见第 07 章）
基本了解 REST API
一台支持 Docker 的服务器或本地机器
Node-RED MQTT 连接正常工作（参见第 09 章）

核心概念

什么是 TimeTagger？

TimeTagger 是由 Sören Stelting 开发的开源、自托管的时间记录应用。它提供：

简单的 Web 界面：干净、简洁的手动时间记录 UI
REST API：完整的 CRUD 操作，支持程序化访问
自托管：在您自己的服务器上运行（Docker 或 Python）
注重隐私：无 Cookie、无追踪、无外部依赖
报告功能：内置时间分析和筛选

为什么选择 TimeTagger 进行资产追踪？

TimeTagger 为我们基于 RFID 的签到系统提供了完美的后端，因为：

特性	对资产追踪的好处
REST API	从 ESP32/Node-RED 以编程方式创建记录
自托管	数据保存在本地（工厂关心的隐私问题）
简单的数据模型	开始/结束时间戳、描述、标签
Docker 支持	与其他 IoT 服务一起轻松部署

TimeTagger 数据模型

TimeTagger 记录结构：
┌─────────────────────────────────────┐
│  记录对象                            │
├─────────────────────────────────────┤
│  key: "a1b2c3d4e5f6"               │ ← 客户端生成的唯一 ID
│  t1: 1715942400                     │ ← 开始时间戳（Unix 秒）
│  t2: 1715944200                     │ ← 结束时间戳（Unix 秒）
│  ds: "从事 ESP32 项目工作"          │ ← 描述
│  mt: 1715944200                     │ ← 修改时间戳
│  st: 1715944200                     │ ← 服务器时间戳（由服务器设置）
│  hidden: false                      │ ← 软删除标志
└─────────────────────────────────────┘

实施步骤

步骤 1：创建 Docker Compose 配置

TimeTagger 可以使用 Docker Compose 与其他 IoT 服务一起部署：

version: '3.8'

services:
  timetagger:
    image: ghcr.io/almarklein/timetagger:latest
    container_name: timetagger
    ports:
      - "8820:80"  # 外部端口 8820 → 容器端口 80
    volumes:
      - ./timetagger/data:/data  # 持久化数据存储
    environment:
      - TIMETAGGER_BIND=0.0.0.0:80
      - TIMETAGGER_DATA_DIR=/data
    restart: unless-stopped

配置说明：

外部使用端口 8820 以避免与其他服务冲突（Node-RED 使用 1880）
数据存储在 ./timetagger/data 中以确保持久性
restart: unless-stopped 策略确保系统重启后自动恢复运行

步骤 2：创建凭据文件

TimeTagger 需要在首次使用前设置认证凭据：

# 1. 创建数据目录
mkdir -p ./timetagger/data

# 2. 使用在线密码哈希工具生成凭据
#    或使用 Python 生成密码哈希：
python3 -c "
import hashlib
password = 'NoderedCourse2023'  # 选择一个强密码
hash = hashlib.sha256(password.encode()).hexdigest()
print(f'密码哈希：{hash}')
"

# 3. 创建凭据文件
#    格式：用户名:密码哈希
cat > ./timetagger/credentials << EOF
admin:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
EOF

# 注意：上面的哈希对应密码 "password" — 请使用真实密码

⚠️ 重要提示：

TimeTagger 凭据文件格式在 Docker Compose 中需要特殊处理，因为 YAML 解析器可能将 $ 符号解释为变量插值：

# 对于包含 $ 符号的密码哈希（例如来自 htpasswd 的），
# 在 docker-compose.yml 环境变量中将所有 $ 符号加倍
# 或者使用 Docker secrets 而非环境变量

简化的凭据设置：

# 1. 创建凭据目录
mkdir -p ./timetagger

# 2. 创建密码哈希
#    访问：https://timetagger.app/credentials
#    输入用户名：admin
#    输入密码：NoderedCourse2023
#    复制生成的哈希

# 3. 保存凭据
echo 'admin:$2b$12$LJ3m4ys3Lk0TSwHnbfFkJekKfRMEOYR3HpNqGMs.bQk4ZxvgVqFxq' > ./timetagger/credentials

# 4. 确保 Docker Compose 挂载此文件
#    在 timetagger 服务的 volumes 部分添加：
#    - ./timetagger/credentials:/data/credentials

步骤 3：启动 TimeTagger

# 启动 TimeTagger 容器
docker-compose up -d timetagger

# 检查容器状态
docker ps | grep timetagger

# 预期输出：
# CONTAINER ID   IMAGE                                    STATUS        PORTS
# abc123def456   ghcr.io/almarklein/timetagger:latest     Up 2 minutes  0.0.0.0:8820->80/tcp

# 查看日志
docker logs timetagger -f

步骤 4：访问 TimeTagger Web UI

1. 打开浏览器：http://localhost:8820
2. 使用凭据登录：
   - 用户名：admin
   - 密码：[您选择的密码]
3. 您应该看到 TimeTagger 仪表板：
   ┌──────────────────────────────────────┐
   │  TimeTagger                          │
   ├──────────────────────────────────────┤
   │  [开始新记录...]                      │
   │                                      │
   │  今天                                 │
   │  ├── ESP32 课程         1h 30m        │
   │  ├── 客户会议            45m          │
   │  └── 代码审查            30m          │
   │                                      │
   │  本周：12h 45m                        │
   └──────────────────────────────────────┘

步骤 5：基本 TimeTagger 操作

手动时间记录：

点击顶部的输入字段
输入描述（例如”从事 ESP32 项目工作”）
按 Enter 开始记录
点击停止按钮结束记录

使用标签筛选：

# 标签可以使用 #hashtag 语法添加
# 示例："Developed MQTT module #ESP32 #NodeRED"

# 之后，按标签筛选：
# 在 TimeTagger Web UI 中，使用筛选下拉菜单选择标签

查看报告：

TimeTagger 报告功能：
├── 日/周/月视图
├── 基于标签的筛选
├── CSV 导出
├── 时间线可视化
└── 总时间计算

验证

确认 TimeTagger 正常工作：

# 1. 验证容器正在运行
curl -s http://localhost:8820 | head -5
# 预期：包含 TimeTagger UI 的 HTML 内容

# 2. 验证 API 端点可访问
curl -s http://localhost:8820/api/v2/info
# 预期：包含服务器信息的 JSON

# 3. 测试认证
curl -s -X POST http://localhost:8820/api/v2/info \
  -H "Content-Type: application/json" \
  -d '{"auth": "your-auth-token"}'

故障排除

问题 1：TimeTagger 无法启动

症状：容器启动后立即退出

原因：数据目录权限不正确

解决方案：

# 修复目录权限
chmod 777 ./timetagger/data

# 检查日志以获取具体错误
docker logs timetagger

问题 2：无法登录

症状：登录失败，提示”凭据无效”

原因：凭据文件格式不正确