ActivityWatch 使用攻略：把你的时间数据留在自己的微服里

ActivityWatch 是一款完全开源、数据不离本地的自动时间追踪工具——装在懒猫微服上，你的每一分钟使用记录都只属于你自己。

---

一、打开看板

安装完成后，在浏览器访问：

https://activitywatch.<你的微服域名>

登录懒猫账号后，即进入 ActivityWatch 内置 Web 看板。顶部导航有这些核心页面：

• Activity：按天、按应用/类别聚合的活动报表，一眼看清今天时间花在哪里。
• Timeline：时间轴明细，可以看每个窗口的切换顺序和时长。
• Stopwatch：在看板里手动为任务计时，无需任何客户端。

首次打开看板数据为空是正常的——服务端本身不采集数据，需要在你的电脑上装客户端（下一节操作）。

---

二、在电脑上安装客户端并连接到微服

这台懒猫应用只是 ActivityWatch 的服务端，真正记录窗口和活跃状态的是运行在你日常电脑上的 Watcher。

步骤：

1. 前往 https://activitywatch.net/ 下载对应系统的客户端（Windows / macOS / Linux 均支持）。

2. 安装后先不要启动，找到 aw-client 的配置文件：

   系统	默认路径
   Windows	%APPDATA%\activitywatch\aw-client\aw-client.toml
   macOS	~/Library/Application Support/activitywatch/aw-client/aw-client.toml
   Linux	~/.config/activitywatch/aw-client/aw-client.toml

3. 编辑该文件，将服务端地址指向你的微服：

   [server]
   hostname = "activitywatch.<你的微服域名>"
   port = 443
   protocol = "https"
   

4. 启动 aw-qt，托盘图标出现后，客户端内置的 aw-watcher-window（记录活跃窗口）和 aw-watcher-afk（记录离开状态）会自动开始向微服上报数据。

5. 回到微服看板刷新页面，Activity 和 Timeline 即出现数据。

---

三、在 Timeline 查看时间轴

数据上报后，进入 Timeline 页，用顶部的「Show last」按钮选择回看时长（¼ 小时到 48 小时），或用日期选择器指定区间。

• 每个窗口活动以时间条形式排布，悬停可看应用名称和精确时长。
• 没有 Watcher 上报数据时，Timeline 显示「No events match」属正常——接入客户端后即有内容。
• Activity 页则把同样的数据按应用/类别聚合成每日报表，适合看总览。

---

四、用 Stopwatch 手动为任务计时

无需安装任何客户端，直接在看板的 Stopwatch 页就能用：

1. 在任务名输入框填写任务描述，例如「撰写本周项目周报」「代码评审与合并 PR」。
2. 点击 Start 开始计时，Running 区会实时显示已计时长。
3. 点击 Stop 结束，记录落入下方 History，按日期分组；点 Start new 可基于历史任务名快速再计时。

计时数据实时写入微服的 SQLite 数据库。Stopwatch 适合需要精确记录特定项目工时的场景。

---

五、在 Buckets 管理数据桶

Buckets 页列出微服上所有的数据桶（bucket）——每个 Watcher、每台设备、Stopwatch 各自对应一个桶。

• 每行显示桶 ID、来源主机、最近更新时间，点 Open 可查看桶内事件明细。
• 页面底部的 Import / Export buckets 支持把某个桶导出为 JSON，或从 JSON 导入——换微服、做备份时很方便。

---

六、在 Settings 个性化看板

Settings 页可以按习惯调整看板行为：

• Start of day：一天从几点算起（默认 04:00，照顾熬夜场景）。
• Start of week：一周从周几开始。
• Duration default value：Timeline「Show last」的默认回看时长。
• Landing page：打开 ActivityWatch 时默认进入哪个页面。
• Theme：浅色 / 深色主题切换。

---

七、数据存储位置与备份

所有数据持久化在微服的以下路径，重装应用不会丢失：

内容	宿主路径
SQLite 事件数据库	/lzcapp/var/data/activitywatch/data
配置文件	/lzcapp/var/data/activitywatch/config
运行时缓存	/lzcapp/var/data/activitywatch/cache

如需备份，直接打包 /lzcapp/var/data/activitywatch/data 目录即可。迁移到新微服时将该目录原样恢复，历史数据完整保留。

---

八、多台电脑同时上报

多台电脑可以同时连接同一个微服服务端：每台电脑的 Watcher 会用不同的 hostname 作为 bucket 的命名空间（格式为 aw-watcher-window_<主机名>），数据在看板里自动区分来源，互不干扰。在 Activity 页或 Buckets 页切换即可查看不同设备的记录。

---

排障与注意事项

看板 Activity / Timeline 页一直加载失败（数据不显示）
这是微服域名与 aw-server-rust 的 Host/CORS 校验冲突导致的已知问题，当前版本已通过内置 nginx 反代解决。若升级后重现，检查容器是否正常启动：健康检查地址为 https://activitywatch.<微服域名>/api/0/info，返回 JSON 即说明服务端正常。

客户端上报失败 / 看板没有新数据
确认 aw-client.toml 里 protocol = "https" 且端口为 443（不是 5600）。微服侧 nginx 监听 5600，但懒猫反向代理对外暴露的是标准 HTTPS 443。

Timeline 显示的时区不对
aw-server-rust 使用容器内的系统时区，默认为 UTC。若看板时间与本地差 8 小时，进入微服应用设置，将容器时区环境变量 TZ 设为 Asia/Shanghai 后重启容器即可。

Watcher 连不上微服（SSL 证书错误）
较旧版本的 aw-client 可能不信任懒猫的证书链。临时方案：在 aw-client.toml 添加 verify_ssl = false；长期方案：升级客户端到最新版，或将懒猫根证书导入系统信任库。