ActivityWatch安装配置与使用指南

ActivityWatch是一款跨平台的开源自动化时间追踪工具，本文提供了从安装配置到高级使用的完整指南。文章详细介绍了Windows、macOS和Linux三大平台的多种安装方式，包括二进制包安装和源码编译安装，并阐述了系统环境要求、依赖管理架构以及打包系统集成。此外，还深入讲解了核心配置参数、自定义设置方法、Web界面与系统托盘功能的使用，以及数据导出与分类管理的最佳实践，帮助用户充分发挥ActivityWatch的时间管理潜力。

多平台安装方法与环境要求详解

ActivityWatch作为一款跨平台的自动化时间追踪工具，提供了多种安装方式来满足不同用户的需求。无论您是Windows、macOS还是Linux用户，都能找到适合的安装方式。本节将详细介绍各平台的安装方法、系统环境要求以及相关的技术细节。

系统环境要求

ActivityWatch对系统环境的要求相对宽松，但为了确保最佳性能和稳定性，建议满足以下最低要求：

平台	最低要求	推荐配置
Windows	Windows 7 SP1+	Windows 10+
macOS	macOS 10.12+	macOS 11+
Linux	Ubuntu 16.04+	Ubuntu 20.04+
内存	2GB RAM	4GB RAM
存储	100MB可用空间	500MB可用空间
Python	3.8+	3.9+

二进制包安装方式

对于大多数用户，推荐使用预编译的二进制包进行安装，这种方式简单快捷，无需配置开发环境。

Windows平台安装

Windows用户可以通过以下步骤安装ActivityWatch：

1. 下载安装包：访问官方发布页面，下载最新的.exe安装程序
2. 运行安装向导：双击安装文件，按照提示完成安装
3. 自动启动服务：安装完成后会自动启动ActivityWatch服务

Windows安装包使用Inno Setup打包，提供了完整的安装体验：

; Inno Setup配置文件示例
[Setup]
AppName=ActivityWatch
AppVersion=0.13.2
DefaultDirName={pf}\ActivityWatch
DefaultGroupName=ActivityWatch
OutputDir=output
OutputBaseFilename=activitywatch-setup

[Files]
Source: "dist\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs

macOS平台安装

macOS用户可以通过DMG包或Homebrew进行安装：

DMG包安装：

# 下载DMG文件后双击挂载
# 将ActivityWatch.app拖拽到Applications文件夹
# 首次运行需要在系统偏好设置中允许运行

Homebrew安装：

brew install --cask activitywatch

macOS打包使用dmgbuild工具，配置文件包含应用签名和权限设置：

# dmgbuild配置文件示例
app = {
    'title': 'ActivityWatch',
    'icon': 'icon.icns',
    'background': 'background.png',
    'format': 'UDZO',
    'contents': [
        {'x': 448, 'y': 344, 'type': 'link', 'path': '/Applications'},
        {'x': 192, 'y': 344, 'type': 'file', 'path': 'ActivityWatch.app'}
    ]
}

Linux平台安装

Linux用户有多种安装选择，包括DEB包、AppImage和源码编译：

DEB包安装（Ubuntu/Debian）：

wget https://github.com/ActivityWatch/activitywatch/releases/download/v0.13.2/activitywatch_0.13.2_amd64.deb
sudo dpkg -i activitywatch_0.13.2_amd64.deb
sudo apt-get install -f  # 安装依赖

AppImage方式：

wget https://github.com/ActivityWatch/activitywatch/releases/download/v0.13.2/ActivityWatch-x86_64.AppImage
chmod +x ActivityWatch-x86_64.AppImage
./ActivityWatch-x86_64.AppImage

源码编译安装

对于开发者和高级用户，可以从源码编译安装ActivityWatch，这种方式可以获得最新的功能和自定义配置。

环境准备

首先需要安装必要的开发工具和依赖：

# Ubuntu/Debian
sudo apt-get install git python3 python3-pip python3-venv build-essential

# macOS
brew install git python3

# Windows
# 安装Git for Windows和Python 3.8+

源码获取与编译

# 克隆仓库（使用镜像地址）
git clone https://gitcode.com/gh_mirrors/ac/activitywatch.git
cd activitywatch

# 初始化子模块
git submodule update --init --recursive

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install poetry
poetry install

# 构建项目
poetry build

依赖管理架构

ActivityWatch使用Poetry进行依赖管理，项目结构清晰，各组件依赖关系明确：

graph TB
    aw-core[aw-core库] --> aw-client[aw-client库]
    aw-client --> aw-server[aw-server服务]
    aw-client --> aw-watcher-afk[AFK监视器]
    aw-client --> aw-watcher-window[窗口监视器]
    aw-server --> aw-qt[QT图形界面]
    aw-server --> aw-webui[Web用户界面]
    
    style aw-core fill:#e1f5fe
    style aw-client fill:#fff3e0
    style aw-server fill:#f3e5f5
    style aw-qt fill:#e8f5e8
    style aw-webui fill:#ffebee

打包系统集成

ActivityWatch支持多种打包格式，确保在不同平台上的良好集成：

打包格式	适用平台	特点
EXE安装包	Windows	完整的安装体验，自动创建开始菜单项
DMG镜像	macOS	符合macOS应用分发标准，拖拽安装
DEB包	Debian/Ubuntu	系统级集成，apt管理
AppImage	Linux通用	无需安装，直接运行
RPM包	Fedora/RHEL	RedHat系Linux发行版支持

环境变量配置

ActivityWatch支持通过环境变量进行配置，常用的环境变量包括：

# 数据存储路径
export AW_DATA_DIR="$HOME/.local/share/activitywatch"

# 服务器端口
export AW_SERVER_PORT=5600

# 日志级别
export AW_LOG_LEVEL=INFO

# Python路径设置
export PYTHONPATH="/path/to/activitywatch:$PYTHONPATH"

系统服务集成

在各平台上，ActivityWatch都可以配置为系统服务自动启动：

Linux systemd服务配置：

[Unit]
Description=ActivityWatch Time Tracker
After=network.target

[Service]
Type=simple
User=%i
ExecStart=/usr/bin/activitywatch
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

macOS launchd配置：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>net.activitywatch</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Applications/ActivityWatch.app/Contents/MacOS/ActivityWatch</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

通过以上多种安装方式和配置选项，用户可以根据自己的技术水平和系统环境选择最适合的安装方案。无论是简单的二进制包安装还是灵活的源码编译，ActivityWatch都能提供稳定可靠的时间追踪服务。

核心配置参数与自定义设置指南

ActivityWatch作为一款高度可定制的自动化时间追踪工具，提供了丰富的配置选项来满足不同用户的需求。通过合理的配置，您可以优化数据采集精度、调整存储策略、自定义监控行为，从而获得更加精准和个性化的时间追踪体验。

核心配置参数详解

ActivityWatch的配置主要通过环境变量和配置文件进行管理。以下是主要的配置参数分类：

数据采集配置

graph TD
    A[数据采集配置] --> B[心跳间隔]
    A --> C[轮询频率]
    A --> D[AFK超时]
    A --> E[窗口标题过滤]
    
    B --> B1[默认: 30秒]
    C --> C1[默认: 1秒]
    D --> D1[默认: 5分钟]
    E --> E1[正则表达式匹配]

参数名称	默认值	说明	推荐设置
AW_HEARTBEAT_INTERVAL	30秒	心跳数据发送间隔	15-60秒
AW_POLL_INTERVAL	1秒	系统状态轮询频率	0.5-2秒
AW_AFK_TIMEOUT	5分钟	AFK状态判定超时	3-10分钟
WINDOW_TITLE_FILTER	-	窗口标题过滤正则	自定义规则

服务器配置

flowchart LR
    S[服务器配置] --> P[端口设置]
    S --> H[主机绑定]
    S --> D[数据存储]
    S --> L[日志级别]
    
    P --> P1[默认: 5666]
    H --> H1[默认: localhost]
    D --> D1[SQLite数据库]
    L --> L1[INFO/DEBUG]

配置项	默认值	功能描述
AW_SERVER_PORT	5666	REST API服务端口
AW_SERVER_HOST	localhost	服务绑定地址
AW_DATABASE_URL	SQLite文件	数据存储路径
AW_LOG_LEVEL	INFO	日志输出级别

存储与性能配置

pie title 存储配置分布
    "事件数据" : 65
    "元数据" : 20
    "索引数据" : 10
    "缓存数据" : 5

参数	默认值	影响范围
AW_MAX_EVENTS	无限制	单Bucket最大事件数
AW_EVENT_TIMEOUT	无	事件自动清理超时
AW_CACHE_SIZE	100MB	内存缓存大小
AW_COMPRESSION	关闭	数据压缩开关

自定义配置方法

环境变量配置

通过环境变量是最直接的配置方式，适用于临时调整或容器化部署：

# 设置心跳间隔为15秒
export AW_HEARTBEAT_INTERVAL=15

# 修改服务器端口
export AW_SERVER_PORT=8080

# 启用调试日志
export AW_LOG_LEVEL=DEBUG

# 设置AFK超时为3分钟
export AW_AFK_TIMEOUT=180

配置文件方式

创建配置文件 ~/.config/activitywatch/config.toml：

[server]
port = 5666
host = "127.0.0.1"
storage_path = "~/.local/share/activitywatch"

[watchers.window]
poll_interval = 1.0
heartbeat_timeout = 30.0

[watchers.afk]
timeout = 300.0
poll_interval = 1.0

[logging]
level = "INFO"
file = "~/.cache/activitywatch/activitywatch.log"

运行时参数配置

启动时通过命令行参数进行配置：

# 指定配置文件和日志级别
activitywatch --config ~/.config/activitywatch/config.toml --log-level DEBUG

# 直接设置参数
activitywatch --port 8080 --host 0.0.0.0

高级配置示例

优化数据采集精度

[watchers.window]
# 提高轮询频率以获得更精确的窗口切换记录
poll_interval = 0.5
heartbeat_timeout = 15.0

[watchers.afk]
# 降低AFK检测灵敏度
timeout = 600.0  # 10分钟
poll_interval = 0.5

自定义数据保留策略

[storage]
# 限制单个Bucket的最大事件数量
max_events_per_bucket = 100000

# 设置事件自动清理时间（7天）
event_timeout = 604800

# 启用数据压缩
compression = true
compression_level = 6

网络与安全配置

[server]
# 允许远程访问
host = "0.0.0.0"
port = 5666

# HTTPS配置
ssl_cert = "/path/to/cert.pem"
ssl_key = "/path/to/key.pem"

# 认证配置
auth_required = true
auth_token = "your-secure-token"

监控器特定配置

不同的监控器（Watchers）有各自的配置选项：

窗口监控器配置

[watchers.window]
# 基础配置
poll_interval = 1.0
heartbeat_timeout = 30.0

# 过滤配置
exclude_titles = ["^$", "Desktop", "Screen Saver"]
exclude_classes = ["dwm", "explorer"]

# 高级配置
detect_fullscreen = true
ignore_minimized = false

AFK监控器配置

[watchers.afk]
# 活动检测配置
timeout = 300.0
poll_interval = 1.0

# 输入设备配置
check_keyboard = true
check_mouse = true
check_joystick = false

# 灵敏度调整
movement_threshold = 2
keypress_resets = true

性能调优建议

根据使用场景的不同，可以采用不同的配置策略：

使用场景	推荐配置	说明
开发环境	高频率采样，详细日志	需要精确的时间记录
生产环境	标准采样，INFO日志	平衡性能与精度
资源受限	降低频率，压缩数据	节省存储和内存
长期运行	启用数据清理	避免存储空间耗尽

故障排除与调试

启用调试模式可以帮助诊断配置问题：

# 启用详细日志
export AW_LOG_LEVEL=DEBUG

# 查看实时日志
tail -f ~/.cache/activitywatch/activitywatch.log

# 检查配置加载
activitywatch --check-config

通过合理配置这些参数，您可以充分发挥ActivityWatch的潜力，获得最适合您工作流程的时间追踪体验。记得在修改配置后重启服务以使更改生效。

Web界面与系统托盘功能使用教程

ActivityWatch提供了直观的Web界面和便捷的系统托盘功能，让用户可以轻松查看和管理时间追踪数据。本节将详细介绍如何使用这些功能来最大化ActivityWatch的使用体验。

Web界面访问与功能详解

ActivityWatch的Web界面是数据可视化和管理的核心平台，默认运行在本地服务器的5600端口上。

访问Web界面

启动ActivityWatch后，可以通过以下方式访问Web界面：

1. 自动打开：首次启动时，系统会自动在默认浏览器中打开Web界面
2. 手动访问：在浏览器地址栏输入 http://localhost:5600
3. 系统托盘菜单：右键点击系统托盘图标，选择"Open Web UI"

主要功能区域

Web界面包含以下几个核心功能区域：

flowchart TD
    A[ActivityWatch Web界面] --> B[仪表盘 Dashboard]
    A --> C[时间线 Timeline]
    A --> D[查询分析 Query]
    A --> E[设置 Settings]
    
    B --> B1[今日活动概览]
    B --> B2[应用程序使用统计]
    B --> B3[网站访问分析]
    
    C --> C1[时间轴视图]
    C --> C2[活动块可视化]
    C --> C3[详细时间记录]
    
    D --> D1[自定义查询]
    D --> D2[数据过滤]
    D --> D3[导出功能]
    
    E --> E1[数据管理]
    E --> E2[外观设置]
    E --> E3[备份恢复]

仪表盘功能详解

仪表盘是Web界面的首页，提供全面的时间使用概览：

组件	功能描述	使用技巧
今日摘要	显示当天总活动时间、AFK时间	点击可查看详细时间分布
应用程序排名	按使用时间排序的应用程序列表	支持按日/周/月查看
网站排名	网站访问时间统计	可过滤特定域名
活动图表	时间使用可视化图表	支持柱状图和饼图切换

时间线视图

时间线视图以直观的方式展示您的时间使用情况：

// 示例：时间线数据格式
{
  "timestamp": "2024-01-15T09:00:00Z",
  "duration": 1800, // 30分钟
  "data": {
    "app": "Visual Studio Code",
    "title": "README.md - activitywatch",
    "url": "file:///projects/activitywatch/README.md"
  }
}

系统托盘功能使用指南

系统托盘图标提供了快速访问和控制ActivityWatch的便捷方式。

托盘图标状态指示

ActivityWatch的系统托盘图标通过不同颜色显示状态：

图标颜色	状态含义	说明
🟢 绿色	正常运行	所有组件正常工作
🟡 黄色	部分运行	某些watcher未启动
🔴 红色	服务停止	需要重新启动
⚫ 灰色	未运行	ActivityWatch未启动

右键菜单功能

右键点击系统托盘图标显示完整功能菜单：

flowchart LR
    M[托盘菜单] --> O[Open Web UI]
    M --> D[Dashboard]
    M --> T[Timeline]
    M --> S[Settings]
    M --> P1[Pause/Resume]
    M --> R[Restart Service]
    M --> Q[Quit]
    
    P1 --> P2[暂停15分钟]
    P1 --> P3[暂停1小时]
    P1 --> P4[暂停自定义时间]

快捷操作示例

通过系统托盘可以快速执行以下操作：

1. 暂停追踪：临时停止时间记录
2. 查看状态：快速检查服务运行状态
3. 打开界面：一键跳转到Web界面
4. 重启服务：解决组件异常问题

高级功能配置

自定义Web界面端口

如果需要更改默认端口，可以通过配置文件修改：

# 编辑配置文件
vim ~/.config/activitywatch/aw-server/aw-server.toml

# 修改端口配置
[server]
host = "127.0.0.1"
port = 5600

系统托盘主题定制

支持自定义托盘图标和菜单样式：

配置选项	默认值	说明
tray_icon_theme	auto	自动适应系统主题
menu_font_size	12px	菜单字体大小
show_notifications	true	启用桌面通知

常见问题解决

Web界面无法访问

如果无法访问Web界面，请检查：

1. 服务状态：确认aw-server正在运行
2. 端口占用：检查5600端口是否被其他程序占用
3. 防火墙设置：确保本地连接未被阻止

系统托盘图标消失

托盘图标消失的解决方法：

1. 重启服务：通过命令行重启ActivityWatch
2. 系统设置：检查系统托盘设置是否隐藏了图标
3. 重新安装：可能需要重新安装系统托盘组件

最佳实践建议

1. 定期查看：建议每天查看一次仪表盘，了解时间使用情况
2. 设置目标：基于数据设置合理的时间使用目标
3. 使用查询：利用查询功能分析特定时间段的数据
4. 备份数据：定期导出和备份时间追踪数据

通过熟练掌握Web界面和系统托盘功能，您可以充分发挥ActivityWatch的时间管理潜力，获得有价值的时间使用洞察。

数据导出与分类管理最佳实践

ActivityWatch作为一款强大的开源时间追踪工具，其核心价值在于帮助用户收集和分析时间使用数据。有效的数据导出和分类管理是充分发挥其价值的关键环节。本文将深入探讨ActivityWatch数据导出与分类管理的最佳实践。

数据导出策略与格式选择

ActivityWatch支持多种数据导出格式，每种格式适用于不同的使用场景：

导出格式	适用场景	优势	局限性
JSON	程序化处理、数据迁移	结构化完整、易于解析	文件体积较大
CSV	电子表格分析、统计	兼容性好、易于处理	嵌套结构扁平化
SQLite	本地数据库查询	查询性能优秀	需要数据库知识

JSON导出示例：

{
  "bucket_id": "aw-watcher-window_username",
  "events": [
    {
      "timestamp": "2024-01-15T10:30:00+08:00",
      "duration": 120.5,
      "data": {
        "app": "chrome.exe",
        "title": "GitHub - ActivityWatch/activitywatch"
      }
    }
  ]
}

分类规则引擎设计

建立有效的分类规则是数据管理的核心。ActivityWatch支持基于正则表达式的智能分类：

# 分类规则配置示例
category_rules = {
    "编程开发": [
        r".*Visual Studio Code.*",
        r".*PyCharm.*", 
        r".*IntelliJ IDEA.*",
        r".*GitHub.*",
        r".*GitLab.*"
    ],
    "文档处理": [
        r".*Microsoft Word.*",
        r".*Google Docs.*",
        r".*LibreOffice.*"
    ],
    "社交媒体": [
        r".*Twitter.*",
        r".*Facebook.*",
        r".*Instagram.*"
    ]
}

自动化导出工作流

建立定期自动化导出机制确保数据安全和持续分析：

flowchart TD
    A[ActivityWatch数据收集] --> B[每日数据备份]
    B --> C{导出格式选择}
    C --> D[JSON全量备份]
    C --> E[CSV统计分析]
    D --> F[云存储归档]
    E --> G[本地分析处理]
    F --> H[长期数据保留]
    G --> I[生成可视化报告]

数据分类层级体系

构建多层次分类体系提高数据分析精度：

mindmap
  root(时间使用分类)
    工作相关
      编程开发
        IDE使用
        代码审查
        文档编写
      会议沟通
        团队会议
        客户会议
    学习成长
      技术学习
        在线课程
        文档阅读
      专业发展
        行业研究
        技能提升
    个人生活
      社交媒体
        微信
        Twitter
      娱乐休闲
        视频观看
        游戏娱乐

数据质量监控与清洗

确保导出数据的准确性和一致性：

数据验证检查表：

• ✅ 时间戳格式一致性验证
• ✅ 事件去重处理
• ✅ 异常值检测与处理
• ✅ 分类标签完整性检查
• ✅ 数据边界合理性验证

集成第三方分析工具

将ActivityWatch数据与其他工具集成实现更深入的分析：

集成工具	集成方式	主要用途
Pandas	CSV导入	数据统计分析
Tableau	JSON转换	可视化仪表板
Elasticsearch	API推送	实时搜索分析
Grafana	数据源配置	监控仪表板

隐私保护与数据安全

在数据导出过程中确保用户隐私：

1. 数据脱敏处理：移除或加密敏感个人信息
2. 访问控制：设置导出数据访问权限
3. 存储加密：对导出的数据文件进行加密
4. 定期清理：建立数据保留策略，定期清理过期数据

性能优化策略

处理大量时间追踪数据时的性能考虑：

# 分批处理大数据导出
def batch_export_data(bucket_id, batch_size=1000):
    events = []
    for i in range(0, total_events, batch_size):
        batch = get_events(bucket_id, limit=batch_size, offset=i)
        events.extend(batch)
        # 分批保存避免内存溢出
        if len(events) >= batch_size:
            save_batch(events)
            events = []
    if events:
        save_batch(events)

分类准确性评估与优化

建立分类效果评估机制：

def evaluate_categorization_accuracy(manual_labels, auto_labels):
    """评估自动分类准确性"""
    correct = 0
    total = len(manual_labels)
    
    for manual, auto in zip(manual_labels, auto_labels):
        if manual == auto:
            correct += 1
    
    accuracy = correct / total
    precision = calculate_precision(manual_labels, auto_labels)
    recall = calculate_recall(manual_labels, auto_labels)
    
    return {
        'accuracy': accuracy,
        'precision': precision,
        'recall': recall,
        'f1_score': 2 * (precision * recall) / (precision + recall)
    }

通过实施这些最佳实践，您可以建立健壮的ActivityWatch数据管理流程，确保时间追踪数据的准确性、安全性和可用性，为个人时间管理和工作效率提升提供有力支持。

ActivityWatch作为一款功能强大的开源时间追踪工具，通过本文的全面介绍，用户可以掌握从基础安装到高级配置的全流程。工具支持多平台安装，提供灵活的配置选项，具备直观的Web界面和便捷的系统托盘功能，同时支持丰富的数据导出格式和智能分类管理。通过合理配置和使用，ActivityWatch能够帮助用户精准追踪时间使用情况，获得有价值的时间洞察，从而提升个人效率和时间管理能力。实施文中的最佳实践，可以建立健壮的数据管理流程，确保时间追踪数据的准确性、安全性和可用性。