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

ActivityWatch 是一款完全开源、数据不离本地的自动时间追踪工具——装在懒猫微服上，你的每一分钟使用记录都只属于你自己。 --- ## 一、打开看板安装完成后，在浏览器访问： ``` https://activitywatch. ``` 登录懒猫账号后，即进入 ActivityWatch 内置 Web 看板。顶部导航有这些核心页面： - **Activity**：按天、按应用/类别聚合的活动报表，一眼看清今天时间花在哪里。 - **Timeline**：时间轴明细，可以看每个窗口的切换顺序和时长。 - **Stopwatch**：在看板里手动为任务计时，无需任何客户端。 ![desktop-1-home.png](https://dl.playground.lazycat.cloud/guidelines/558/31dcf4f6-d461-4086-addb-43a27fe4d6dd.png "desktop-1-home.png") > 首次打开看板数据为空是正常的——服务端本身不采集数据，需要在你的电脑上装客户端（下一节操作）。 --- ## 二、在电脑上安装客户端并连接到微服这台懒猫应用只是 ActivityWatch 的**服务端**，真正记录窗口和活跃状态的是运行在你日常电脑上的 Watcher。 **步骤：** 1. 前往 [https://activitywatch.net/](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. 编辑该文件，将服务端地址指向你的微服： ```toml [server] hostname = "activitywatch." port = 443 protocol = "https" ``` 4. 启动 `aw-qt`，托盘图标出现后，客户端内置的 `aw-watcher-window`（记录活跃窗口）和 `aw-watcher-afk`（记录离开状态）会自动开始向微服上报数据。 5. 回到微服看板刷新页面，**Activity** 和 **Timeline** 即出现数据。 --- ## 三、在 Timeline 查看时间轴数据上报后，进入 **Timeline** 页，用顶部的「Show last」按钮选择回看时长（¼ 小时到 48 小时），或用日期选择器指定区间。 ![desktop-2-timeline.png](https://dl.playground.lazycat.cloud/guidelines/558/642b3031-f325-48d9-9141-6e4d6d52cd24.png "desktop-2-timeline.png") - 每个窗口活动以时间条形式排布，悬停可看应用名称和精确时长。 - 没有 Watcher 上报数据时，Timeline 显示「No events match」属正常——接入客户端后即有内容。 - **Activity** 页则把同样的数据按应用/类别聚合成每日报表，适合看总览。 --- ## 四、用 Stopwatch 手动为任务计时无需安装任何客户端，直接在看板的 **Stopwatch** 页就能用： 1. 在任务名输入框填写任务描述，例如「撰写本周项目周报」「代码评审与合并 PR」。 2. 点击 **Start** 开始计时，**Running** 区会实时显示已计时长。 3. 点击 **Stop** 结束，记录落入下方 **History**，按日期分组；点 **Start new** 可基于历史任务名快速再计时。 ![mobile-1-stopwatch.png](https://dl.playground.lazycat.cloud/guidelines/558/1fe81755-366a-4656-86b4-a141bd8d5cdb.png "mobile-1-stopwatch.png") 计时数据实时写入微服的 SQLite 数据库。Stopwatch 适合需要精确记录特定项目工时的场景。 --- ## 五、在 Buckets 管理数据桶 **Buckets** 页列出微服上所有的数据桶（bucket）——每个 Watcher、每台设备、Stopwatch 各自对应一个桶。 ![mobile-2-buckets.png](https://dl.playground.lazycat.cloud/guidelines/558/5bfccaae-50f1-44b9-9121-5fa2dbdb5a67.png "mobile-2-buckets.png") - 每行显示桶 ID、来源主机、最近更新时间，点 **Open** 可查看桶内事件明细。 - 页面底部的 **Import / Export buckets** 支持把某个桶导出为 JSON，或从 JSON 导入——换微服、做备份时很方便。 --- ## 六、在 Settings 个性化看板 **Settings** 页可以按习惯调整看板行为： ![mobile-3-settings.png](https://dl.playground.lazycat.cloud/guidelines/558/ac43ac56-9ebd-447b-ae93-98e344f4e3d1.png "mobile-3-settings.png") - **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`；长期方案：升级客户端到最新版，或将懒猫根证书导入系统信任库。