Ubuntu 22.04 安装 ActivityWatch 0.14.1 指南

Ubuntu 22.04（无图形界面）从 0 到 1 安装 ActivityWatch 0.14.1：官方 zip+systemd 托管（推荐）、deb 包、aw-server-rust 三方案，含下载校验、配置、升级降级、远程访问与排障实录，全部命令实测。

ActivityWatchActivityWatch时间追踪UbuntuLinux系统2026/10/23

Ubuntu 22.04 安装 ActivityWatch 0.14.1 指南

目标：在一台全新 Ubuntu 22.04 服务器（无图形界面）上从 0 到 1 安装 ActivityWatch 0.14.1 的服务器组件 aw-server，并用 systemd 完成托管与开机自启。本文提供官方 zip 包（推荐）、deb 包、aw-server-rust 三种安装方案，全部命令与回显均在 Ubuntu 22.04（22.04.5 LTS，x86_64）环境实测通过，安装路径 /opt/activitywatch，服务端口 5600。

一、环境信息

本文实测环境与关键路径如下：

  • 操作系统：Ubuntu 22.04（22.04.5 LTS），x86_64
  • 软件版本：ActivityWatch v0.14.1（2026-10-10 发布的官方最新稳定版，查询日期 2026-10-22）
  • 安装目录：/opt/activitywatch（zip 方案自选；deb 方案由包固定装到此路径）
  • 配置目录：~/.config/activitywatch/（本文以 root 运行，即 /root/.config/activitywatch/）
  • 数据目录：~/.local/share/activitywatch/
  • 服务端口：5600（默认，绑定 127.0.0.1）
  • 进程形态：无图形界面的服务器上只运行 aw-server 常驻服务，由 systemd 托管；aw-qt 托盘管理器、窗口/AFK 采集器依赖桌面会话，不在服务器形态使用（原因见 6.4 与常见问题）

二、前置条件

本章确认服务器满足安装的最低条件，避免安装中途缺依赖。

2.1 基础工具

需要 wget（下载）、unzip（解压 zip 方案）、curl（验证）。Ubuntu 22.04 最小安装通常自带 curl，wget/unzip 需补装：

apt-get update
apt-get install -y wget unzip curl

实测回显（节选尾部）：

Setting up unzip (6.0-26ubuntu3.1) ...
Setting up wget (1.21.2-2ubuntu1.1) ...
Processing triggers for man-db (2.10.2-1) ...

2.2 磁盘与端口

  • 安装目录占用实测约 454MB（du -sh /opt/activitywatch 实测回显：454M /opt/activitywatch），下载包另有约 187MB，建议预留 1GB；
  • 端口 5600 需空闲，检查命令与实测回显：
ss -ltn | grep 5600 || echo "port 5600 free"

port 5600 free

2.3 对图形界面依赖的说明

ActivityWatch 官方安装包是"全家桶"：桌面场景由 aw-qt 拉起 aw-server 与各采集器；服务器无图形会话时，只有 aw-server 能常驻运行（窗口/AFK/输入采集器依赖 X11/桌面会话）。因此本文主线是「aw-server + systemd」，这也是在服务器上落地 ActivityWatch 的唯一受支持形态。远程访问 Web UI 走 SSH 隧道（官方推荐，见 9.4）。

⚠️ 注意：官方文档明确表示把 aw-server 放到远程服务器给多台机器共用是"不受支持且强烈不建议"的场景（来源：官方文档 Remote Server 页，2026-10-22 查询）。服务器形态适合"这台服务器上的自托管 Web UI + 个人数据备份/查询"用途，请在理解该限制的前提下使用。

三、版本选型说明

3.1 版本选择

截至查询日 2026-10-22，官方发布资产如下（来源：GitHub Releases 与 releases.atom）：

版本类型发布日期是否建议安装
v0.14.1稳定版2026-10-10✅ 本文基线
v0.14.2b1开发预发布（b1）2026-10-22❌ 仅跟踪测试用

关键解读：ActivityWatch 大版本节奏约一年一代，稳定版即可满足生产使用；带 b 后缀的预发布不作为部署基线。获取最新稳定版的命令（无需记忆版本号）：

curl -s https://api.github.com/repos/ActivityWatch/activitywatch/releases/latest | grep -m1 tag_name

⚠️ 注意：上式直接调 GitHub API，有匿名限流（每 IP 每小时 60 次）；批量脚本场景建议改读 https://github.com/ActivityWatch/activitywatch/releases.atom。

3.2 安装资产选择

v0.14.1 的 Linux x86_64 资产（来源：Releases 页，2026-10-22 实查）：

资产文件适用
zip 全家桶activitywatch-v0.14.1-linux-x86_64.zip（约 187MB）服务器/桌面通用，路径完全自控（本文方案 A）
deb 包activitywatch-v0.14.1-linux-x86_64.deb（约 128MB）Ubuntu/Debian 桌面一键安装，可用 apt 管理（本文方案 B）
AppImageactivitywatch-linux-x86_64.AppImage桌面免安装直接运行
Tauri zipactivitywatch-tauri-v0.14.1-linux-x86_64.zip实验性，Linux 原生 Wayland 支持

关键差异：zip 与 deb 的程序本体完全一致（deb 就是把 zip 全家桶装进 /opt/activitywatch 并注册桌面自启动项）；服务器场景两者皆可，zip 方案便于"多版本并存 + 目录级升级"，deb 方案便于"包管理器统一卸载/查询"。AppImage 与 Tauri 发行版面向带桌面的终端，服务器场景不涉及。

四、方案 A：官方 zip 包安装 + systemd 托管（推荐）

4.1 方案说明

从 GitHub Releases 下载官方 zip 全家桶，解压到 /opt/activitywatch，只取其中的 aw-server 作为常驻服务，编写 systemd 单元实现开机自启与崩溃拉起。优点：路径自控、多版本可并存、不引入包管理器状态。

4.2 下载与校验

cd /root
wget https://github.com/ActivityWatch/activitywatch/releases/download/v0.14.1/activitywatch-v0.14.1-linux-x86_64.zip -O aw.zip

⚠️ 注意：国内网络直连 GitHub Releases 缓慢或失败时，为 wget 配置代理环境变量后重试（export http_proxy=<代理地址> https_proxy=<代理地址>），或先在其他机器下载后经 scp 上传。

校验文件完整性与大小（实测回显）：

ls -la /root/aw.zip
sha256sum /root/aw.zip

-rw-r--r-- 1 root root 196236767 Oct 10 19:04 /root/aw.zip
211514a8912c0a399a8c7048101b699e0a2fedb5e81b5ed224304d5c8e091f2a  /root/aw.zip

196236767 字节与上述 SHA-256 为 v0.14.1 Linux x86_64 zip 资产实测值（2026-10-22 下载）；官方未单独发布校验文件，建议以本值比对。

4.3 解压安装

cd /opt
unzip -q /root/aw.zip
ls /opt/activitywatch

实测回显（解压后目录结构）：

PyQt6
aw-notify
aw-qt
aw-qt.desktop
aw-server
aw-server-rust
aw-watcher-afk
aw-watcher-input
aw-watcher-window
base_library.zip
importlib_metadata-8.5.0.dist-info
lib-dynload
libQt6Core.so.6
libQt6DBus.so.6
libQt6Gui.so.6
...（Qt/X11 动态库若干，共 113 项）
media
setuptools

安装包为 PyInstaller 自包含发行：aw-server/aw-server（Python 服务器主程序）、aw-server-rust/aw-server-rust（Rust 服务器）、aw-qt（托盘管理器）、aw-watcher-*（采集器）全部自带依赖库，服务器上无需额外安装 X11/Qt 系统库即可运行 aw-server。

4.4 首次启动与配置文件

先裸启一次 aw-server，让它生成默认配置与数据目录：

cd /opt/activitywatch
./aw-server/aw-server --version

aw-server 0.14.1

./aw-server/aw-server > /root/aw-server-first.log 2>&1 &
sleep 6
curl -s http://localhost:5600/api/0/info

{"hostname": "aw-server01", "version": "v0.14.1", "testing": false, "device_id": "a34e4cfc-7992-4c03-a7a2-7422da090665", "profile": "default"}

返回的 JSON 中 version 即服务器版本。此时配置文件已自动生成：

cat /root/.config/activitywatch/aw-server/aw-server.toml

[server]
#host = "localhost"
#port = "5600"
#storage = "peewee"
#cors_origins = ""
## Cache query results for finished past periods in memory (see query_cache.py)
#query_cache = true

[server.custom_static]

[server.auth]
## Uncomment and set to enable API key authentication for /api/* endpoints.
## Clients must send: Authorization: Bearer <api_key>
## GET /api/0/info and OPTIONS preflight requests are always public.
## api_key = ""

[server-testing]
#host = "localhost"
#port = "5666"
#storage = "peewee"
#cors_origins = ""
#query_cache = true

[server-testing.custom_static]

[server-testing.auth]
#api_key = ""

💡 技术拓展：这是 TOML 注释式默认配置——所有键以注释形式列出（如 #host = "localhost"），未注释即"使用内置默认"。相比旧版本的 aw-server.ini（0.14 之前），TOML 支持嵌套表（如 [server.auth]）。各键含义的完整逐项解析见《ActivityWatch 0.14.1 配置参数详解》。

验证数据目录已建立：

find /root/.local/share/activitywatch -maxdepth 2

/root/.local/share/activitywatch
/root/.local/share/activitywatch/aw-server
/root/.local/share/activitywatch/aw-server/device_id
/root/.local/share/activitywatch/aw-server/peewee-sqlite.v2.db

4.5 修改绑定地址（按需）

默认只绑定 127.0.0.1，本机访问没问题；若确认要通过 SSH 隧道以外的受控网络访问（例如跳板机到内网服务器），可把 host 改为 0.0.0.0。编辑 /root/.config/activitywatch/aw-server/aw-server.toml，将 [server] 段的 host 注释打开并改值：

[server]
host = "0.0.0.0"
#port = "5600"
#storage = "peewee"
#cors_origins = ""
#query_cache = true

[server.custom_static]

[server.auth]
#api_key = ""

[server-testing]
#host = "localhost"
#port = "5666"
#storage = "peewee"
#cors_origins = ""
#query_cache = true

[server-testing.custom_static]

[server-testing.auth]
#api_key = ""

停掉裸启进程后重启验证绑定：

pkill -f "aw-server/aw-server"
sleep 2
./aw-server/aw-server > /root/aw-server.log 2>&1 &
sleep 6
grep "Running on" /root/aw-server.log

 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5600
 * Running on http://10.89.59.2:5600  (werkzeug:187)

回显出现 Running on all addresses (0.0.0.0) 即改绑生效（第三行为本机内网 IP，读者环境不同属正常）。

⚠️ 注意：0.0.0.0 会把 Web UI 与 REST API 暴露到所有网卡。公网/办公网环境必须同时启用 [server.auth] 的 api_key（写法与实测回显见 9.4）并配置防火墙，否则任何能路由到该端口的人都能读写你的全部时间数据。

4.6 systemd 托管

写入系统级服务单元 /etc/systemd/system/aw-server.service：

[Unit]
Description=ActivityWatch Server (aw-server)
After=network.target

[Service]
Type=simple
User=root
ExecStart=/opt/activitywatch/aw-server/aw-server
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

💡 技术拓展：systemd 服务 Type= 常见取值对比——

Type含义适用
simpleExecStart 进程即主进程，启动即认为就绪前台常驻程序（本文采用）
notify进程就绪后主动通知 systemd（需程序支持 sd_notify）Rust 版官方单元采用 Type=notify
forking程序自身 fork 后父进程退出传统 SysV 风格守护进程
exec类似 simple，但以 exec 完成为就绪需要更早就绪判定的场景

本文因 aw-server（Python 版）为前台常驻进程且未实现 sd_notify，采用 Type=simple；aw-server-rust 官方自带单元为 Type=notify。

加载并启动、设置开机自启（逐条执行）：

systemctl daemon-reload

systemctl start aw-server

systemctl enable aw-server

Created symlink /etc/systemd/system/multi-user.target.wants/aw-server.service → /etc/systemd/system/aw-server.service.

4.7 验证

systemctl is-active aw-server
systemctl is-enabled aw-server
systemctl status aw-server --no-pager | head -8

active
enabled
● aw-server.service - ActivityWatch Server (aw-server)
     Loaded: loaded (/etc/systemd/system/aw-server.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 16:29:22 UTC; 11s ago
   Main PID: 4347 (aw-server)
      Tasks: 1 (limit: 94371)
     Memory: 36.7M

（输出节选，实测首部；Memory 一行为 Python 版服务器稳定后的真实驻留内存，约 35MB。）

最终业务验证——REST API 与 Web UI：

curl -s http://localhost:5600/api/0/info

{"hostname": "aw-server01", "version": "v0.14.1", "testing": false, "device_id": "a34e4cfc-7992-4c03-a7a2-7422da090665", "profile": "default"}

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5600/

200

Web UI 返回 200 即服务器托管完成。日志走 journald：journalctl -u aw-server -f。

五、方案 B：deb 包安装

5.1 方案说明

Ubuntu/Debian 官方渠道没有 ActivityWatch 的 apt 仓库，官方提供的是自建 deb 包。安装后程序本体同样落在 /opt/activitywatch，并注册桌面自启动项；适合希望"用 dpkg/apt 统一管理文件清单与卸载"的读者。

5.2 下载与安装

cd /root
wget https://github.com/ActivityWatch/activitywatch/releases/download/v0.14.1/activitywatch-v0.14.1-linux-x86_64.deb -O aw.deb
sha256sum /root/aw.deb

05806625df65ab419fb6b0da5323d053c07f5e244905187f73673a50eff5ac77  /root/aw.deb

apt-get install -y /root/aw.deb

实测回显（节选尾部）：

Preparing to unpack .../9-aw.deb ...
Unpacking activitywatch (0.14.1) ...
Setting up xdg-user-dirs (0.17-2ubuntu4) ...
Setting up libglib2.0-0:amd64 (2.72.4-0ubuntu2.10) ...
Setting up libicu70:amd64 (70.1-2) ...
Setting up libwayland-client0:amd64 (1.20.0-1ubuntu0.1) ...
Setting up activitywatch (0.14.1) ...
Setting up libxml2:amd64 (2.9.13+dfsg-1ubuntu0.14) ...
Setting up shared-mime-info (2.1-2) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

可见 deb 包除本体（自带 PyQt6/Qt 库）外，还拉取了少量桌面基础库（glib、wayland、icu、libxml2 等，Ubuntu 22.04 上均为官方源现成版本），总下载增量小。

5.3 安装内容与目录

dpkg -L activitywatch | wc -l
dpkg -L activitywatch | grep -v "^/opt" | grep -E "desktop"

1614
/etc/xdg/autostart/aw-qt.desktop
/usr/share/applications/aw-qt.desktop

解读：共 1614 个文件，其中程序本体在 /opt/activitywatch（与 zip 方案布局一致）；额外落两个桌面入口——/etc/xdg/autostart/aw-qt.desktop（桌面登录自启动）与 /usr/share/applications/aw-qt.desktop（应用菜单项）。服务器（无桌面）上这两个入口不生效，仍需按下节配置 systemd 托管。

5.4 systemd 托管

deb 方案的 aw-server 路径与 zip 方案完全相同（/opt/activitywatch/aw-server/aw-server），直接复用 4.6 节的服务单元即可：写入同样的 /etc/systemd/system/aw-server.service 后执行：

systemctl daemon-reload

systemctl start aw-server

systemctl enable aw-server

5.5 验证

systemctl is-active aw-server
curl -s http://localhost:5600/api/0/info

active
{"hostname": "aw-server02", "version": "v0.14.1", "testing": false, "device_id": "645e4114-f177-4b71-aa49-52b55c99e8ab", "profile": "default"}

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5600/

200

⚠️ 注意：deb 安装后再执行 zip 解压会得到两份 /opt/activitywatch 内容冲突（后者直接覆盖前者文件），两者择一使用；本文建议服务器统一走 zip 方案，桌面机走 deb。

六、方案 C：aw-server-rust（Rust 实现，可选）

6.1 方案说明

官方 zip/deb 内已同时打包 Rust 版服务器 aw-server-rust/aw-server-rust：性能更好、内存更低，数据格式与 Python 版互通（首次启动自动检测并导入 Python 版遗留数据库），可直接作为 aw-server 的替代进程被 systemd 托管。

6.2 启动与验证

确认版本（注意：Rust 二进制的 --version 输出前缀同样是 aw-server）：

/opt/activitywatch/aw-server-rust/aw-server-rust --version

aw-server 0.14.1

先停掉 Python 版，再用 Rust 版验证启动（示例在 deb 安装环境实测）：

pkill -f "aw-server/aw-server"
sleep 2
cd /opt/activitywatch/aw-server-rust
./aw-server-rust

实测启动日志（完整）：

[2026-10-22 16:31:58][INFO][aw_server]: Using DB at path "/root/.local/share/activitywatch/aw-server-rust/sqlite.db"
[2026-10-22 16:31:58][INFO][aw_server]: Using aw-webui assets at path None
[2026-10-22 16:31:58][INFO][aw_server::endpoints]: Starting aw-server-rust at 127.0.0.1:5600
[2026-10-22 16:31:58][WARN][rocket::launch]: Rocket has launched from http://127.0.0.1:5600
[2026-10-22 16:31:58][INFO][aw_datastore::datastore]: Upgrading database to v2, adding data field to buckets
[2026-10-22 16:31:58][INFO][aw_datastore::datastore]: Upgrading database to v3, replacing the broken data field for buckets
[2026-10-22 16:31:58][INFO][aw_datastore::datastore]: Upgrading database to v4, adding table for key-value storage
[2026-10-22 16:31:58][INFO][aw_datastore::datastore]: Upgrading database to v5, replacing single-column events indexes with a composite index
[2026-10-22 16:31:58][INFO][aw_datastore::legacy_import::import]: Checking for legacy (Python aw-server) database at /root/.local/share/activitywatch/aw-server/peewee-sqlite.v2.db
[2026-10-22 16:31:58][INFO][aw_datastore::legacy_import::import]: Found legacy database at /root/.local/share/activitywatch/aw-server/peewee-sqlite.v2.db, importing
[2026-10-22 16:31:58][INFO][aw_datastore::legacy_import::import]: Legacy database has 0 bucket(s) to import
[2026-10-22 16:31:58][INFO][aw_datastore::datastore]: Successfully imported legacy database

日志显示两件关键事实：Rust 版数据库独立存放在 ~/.local/share/activitywatch/aw-server-rust/sqlite.db；启动时自动检查并导入 Python 版遗留库（legacy_import）。业务验证：

curl -s http://localhost:5600/api/0/info

{"hostname":"aw-server02","version":"v0.14.1 (rust)","testing":false,"profile":"default","device_id":"21d8ab68-fa7f-468b-8bc1-ecaf7f1df3e4"}

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5600/

200

version 字段出现 (rust) 后缀即 Rust 版在服务，Web UI 同样返回 200（aw-webui 静态资源已内嵌）。若改用 Rust 版常驻，把 4.6 节单元中 ExecStart 换为 /opt/activitywatch/aw-server-rust/aw-server-rust、Type 换为 notify 即可（官方自带参考单元见 /opt/activitywatch/aw-server-rust/aw-server.service，它是给 systemctl --user 用的模板）。

6.3 配置文件差异

Rust 版的配置文件路径与键名都不同：~/.config/activitywatch/aw-server-rust/config.toml，首次启动自动生成（实测原文）：

### DEFAULT SETTINGS ###
#address = "127.0.0.1"
#port = 5600
#cors = []
#cors_regex = []
#query_cache = true
#
#[auth]
#
#[custom_static]

键名对照：host（Python）↔ address（Rust）、cors_origins ↔ cors（另支持 cors_regex）。更多差异见《ActivityWatch 0.14.1 配置参数详解》。

七、方案对比与选择建议

维度方案 A（zip + systemd）方案 B（deb）方案 C（aw-server-rust）
安装载体官方 zip 全家桶，解压即用官方 deb 包，apt/dpkg 管理复用 A/B 安装包内的 Rust 服务器
安装路径自选（本文 /opt/activitywatch）固定 /opt/activitywatch随 A/B
是否需联网需（下载一次）需（下载 + 补桌面基础库）否（复用已装包）
systemd 单元自建 system 级单元自建 system 级单元自建（Type=notify）
数据目录~/.local/share/activitywatch/aw-server同左.../aw-server-rust（自动导入 Python 库）
配置文件aw-server.toml同左config.toml（键名不同）
多版本并存容易（目录级）难（dpkg 只保留一份）随 A/B
卸载删目录 + 删单元apt-get remove --purge随 A/B
适用服务器首选偏好包管理/桌面机性能敏感、可接受差异键名

选择建议：服务器场景默认方案 A（路径与升级完全自控）；已用桌面机 deb 安装、想顺手做服务器托管的用方案 B；对内存/性能敏感且能接受配置键名差异的再评估方案 C。三者都只托管 aw-server 单进程，采集器（窗口/AFK）在无桌面的服务器上不参与运行。

八、升级、降级与多版本管理

8.1 升级到新版本

zip 方案的升级即"解压新目录 + 切软链接"，数据目录与版本无关、天然保留：

cd /root
wget https://github.com/ActivityWatch/activitywatch/releases/download/v0.14.1/activitywatch-v0.14.1-linux-x86_64.zip -O aw-0.14.1.zip
unzip -q aw-0.14.1.zip -d /opt/tmp-extract
mv /opt/tmp-extract/activitywatch /opt/activitywatch-0.14.1
ln -sfn /opt/activitywatch-0.14.1 /opt/activitywatch
systemctl restart aw-server
curl -s http://localhost:5600/api/0/info

多版本目录 + 软链接的实测回显（0.14.1 目录 + activitywatch-latest 链接）：

drwxr-xr-x 13 root root 4096 Oct 10 18:03 activitywatch
drwxr-xr-x 13 root root 4096 Oct 10 18:03 activitywatch-0.14.1
lrwxrwxrwx  1 root root   25 Oct 22 16:30 activitywatch-latest -> /opt/activitywatch-0.14.1

readlink -f /opt/activitywatch-latest

/opt/activitywatch-0.14.1

软链接指向验证无误。systemd 单元中 ExecStart 可写 /opt/activitywatch/aw-server/aw-server（经软链接解析），升级时仅需 ln -sfn 切换后 systemctl restart。

8.2 降级

同法把软链接切回旧版本目录即可。两条注意：

  • Python 版（peewee 库）与 Rust 版数据库文件相互独立，混用实现后再降级前，先备份 ~/.local/share/activitywatch/；
  • Rust 版启动日志显示它会对库做 schema 升级（v2→v5，见 6.2 日志），从 Rust 版降回老版本 Python 版前务必备份数据目录，老程序可能读不懂新 schema。

8.3 升级前备份

tar czf /root/aw-data-$(date +%F).tar.gz -C /root/.local/share activitywatch

备份文件落到 /root/aw-data-<日期>.tar.gz，恢复时解回 ~/.local/share/ 即可。

九、配置说明（跨方案共用）

9.1 三类目录速查

用途路径说明
程序/opt/activitywatch安装包本体（zip 自选 / deb 固定）
配置~/.config/activitywatch/aw-server/aw-server.tomlPython 版服务器配置（Rust 版在 aw-server-rust/config.toml）
数据~/.local/share/activitywatch/aw-server/peewee-sqlite.v2.db 与 device_id，备份即备份这里
日志journaldjournalctl -u aw-server（systemd 托管后 stdout 进 journal）

9.2 aw-server.toml 常用键

键默认值说明
[server] hostlocalhost绑定地址，改 0.0.0.0 对外提供
[server] port5600监听端口（testing 配置段为 5666）
[server] storagepeewee存储后端，官方仅支持 peewee（SQLite）
[server] query_cachetrue已完成时段的查询结果内存缓存
[server] cors_origins""（空）额外允许的 CORS 来源
[server.auth] api_key""（不启用）设置后 /api/* 需带 Bearer 认证

逐项详解、实测行为与排障见《ActivityWatch 0.14.1 配置参数详解》。

9.3 数据目录持久化说明

~/.local/share/activitywatch/ 是唯一需要持久化/备份的目录（SQLite 单文件 + device_id）。换机迁移：停服 → 打包数据目录 → 新机同路径解包 → 启服，device_id 保持不变即历史数据无缝接续。

9.4 远程访问 Web UI 的两种方式

官方推荐 SSH 隧道（本地执行）：

ssh -L 5600:localhost:5600 root@<服务器IP>

之后本地浏览器访问 http://localhost:5600，流量全程走 SSH 加密，服务器无需对外开端口。

若确需直接监听对外（内网受控环境），改 host = "0.0.0.0" 并启用 API Key 认证。实测：在 [server.auth] 段设置 api_key = "q1w2e3r4" 并重启后——

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5600/api/0/buckets/

401

curl -s http://localhost:5600/api/0/buckets/

{"message": "Missing or invalid API key. Set Authorization: Bearer <key> header."}

curl -s -H "Authorization: Bearer q1w2e3r4" http://localhost:5600/api/0/buckets/

{"test-bucket": {"id": "test-bucket", ...}, "aw-watcher-afk_aw-server01": {"id": "aw-watcher-afk_aw-server01", ...}}

（第三个回显为节选，展示带 Key 请求通过。）注意 GET /api/0/info 恒为公开（无需 Key），其余 /api/* 一律校验。Web UI 页面会提示输入 Key。

十、常见问题（FAQ）

Q1：启动失败，日志报 Address already in use / Port 5600 is in use by another program？

这是端口被占：此前手动裸启的 aw-server 还在跑，systemd 拉起的新进程绑不上端口。定位与解决：

pgrep -af "aw-server/aw-server"

2860 ./aw-server/aw-server

kill 2860
systemctl restart aw-server
systemctl is-active aw-server

active

aw-server 自身的报错原文（journald 实测）：

 * Serving Flask app 'aw-server'
 * Debug mode: off
Address already in use
Port 5600 is in use by another program. Either identify and stop that program, or start the server with a different port.

Q2：照老教程改了 ~/.config/aw-server/aw-server.ini（或 settings.json）不生效？

0.14 起配置体系已改为 ~/.config/activitywatch/aw-server/aw-server.toml（注意目录名是 activitywatch 而非 aw-server，首次启动自动生成）。实测把 host 写进旧路径 ~/.config/aw-server/ 重启后日志仍是 Running on http://localhost:5600；写入正确路径后变为 Running on all addresses (0.0.0.0)。遇到"改了配置不生效"，第一步 find ~/.config -name "aw-server.toml" 确认真路径。

Q3：systemctl start 后 is-active 显示 activating？

PyInstaller 打包的程序首次启动要解包引导，数秒内属正常。实测 start 后 sleep 3 与 sleep 8 两次查询均为 active；若长期停在 activating，看 journalctl -u aw-server -n 50（多半是 Q1 的端口占用）。

Q4：服务器上 Web UI 打不开时间线，buckets 里只有 afk 一个桶？

无图形会话时窗口/AFK 采集器本就无法运行（它们依赖 X11/输入设备），服务器上没有"你在电脑前做了什么"的数据可采。这是设计边界而非故障：服务器形态定位是"数据查看/备份/查询服务"，采集发生在你日常使用的桌面机上。

Q5：远程访问除了 SSH 隧道还有别的官方方案吗？

没有。官方文档（Remote Server 页）明确：远程服务器部署"technically possible, not supported, and strongly discouraged"，唯一" somewhat secure" 的路径就是 SSH 隧道。若坚持直连，请自行承担风险并至少启用 api_key + 防火墙白名单（见 9.4）。

十一、卸载与清理

11.1 zip 方案

systemctl stop aw-server
systemctl disable aw-server
rm -f /etc/systemd/system/aw-server.service
systemctl daemon-reload
rm -rf /opt/activitywatch /opt/activitywatch-0.14.1
rm -rf /root/.config/activitywatch
rm -rf /root/.local/share/activitywatch
rm -f /root/aw.zip /root/aw-server*.log

（最后两行分别清配置与数据，数据含全部历史时间记录，删前确认备份。）

11.2 deb 方案

systemctl stop aw-server
systemctl disable aw-server
rm -f /etc/systemd/system/aw-server.service
systemctl daemon-reload
apt-get remove --purge -y activitywatch
rm -rf /root/.config/activitywatch /root/.local/share/activitywatch

--purge 移除 /opt/activitywatch 本体与两个 desktop 入口；配置/数据目录在用户家目录下，包管理器不负责，需手动清理。

十二、参考链接