003 TimeTagger 时间跟踪工具本地部署与开机自启
TimeTagger 本地部署与开机自启手册
一、TimeTagger 产品介绍
TimeTagger 是一款轻量级、开源免费的Web端时间跟踪工具，基于Python+Web技术开发，支持本地离线运行、时间记录分类、数据统计分析，无需云端账号即可实现数据本地持久化存储，界面简洁易用，适合个人日常时间管理、工作时长统计等场景，兼顾轻量化与实用性，支持自定义部署端口与数据存储位置。
TimeTagger 官网：https://timetagger.app/
二、前置准备
操作系统：Windows 全系列（Win10/Win11 优先）
已安装Python 3.8及以上版本，并配置好系统环境变量（可通过
python \-\-version验证）下载 TimeTagger 官方源码压缩包（ZIP格式）
三、完整部署步骤
1. 下载并解压源码包
第一步：访问 TimeTagger GitHub 仓库（下载压缩包）
打开浏览器，输入 GitHub 仓库地址：
https://github.com/almarklein/timetagger进入仓库后，找到页面右侧的Releases（版本发布）区域（或直接访问：
https://github.com/almarklein/timetagger/releases）在 Releases 列表中，找到26.1.3 版本（标有「Latest」或「Stable」的稳定版）
向下滚动，找到「Assets」（资源）板块，点击
Source code (zip)下载源码压缩包（文件名：timetagger-26.1.3.zip）- 若看不到 26.1.3，可在版本列表中翻找，或用页面搜索（Ctrl+F）输入「26.1.3」定位
第二步：解压压缩包（关键：无中文 / 特殊字符路径）
找到下载的
timetagger-26.1.3.zip（默认在「下载」文件夹）右键压缩包 → 选择「解压到…」
在弹出的路径选择窗口中：
选择磁盘根目录下的纯英文文件夹（推荐
D:\tools，若没有则先新建：右键 → 新建 → 文件夹，命名为tools）确认解压后的完整路径为：
D:\tools\timetagger-26.1.3（重点：路径中不能有中文、空格、括号、特殊符号（如！@#￥%））点击「确定」完成解压
验证解压结果：打开
D:\tools\timetagger-26.1.3，能看到requirements.txt、setup.py等文件，说明解压正确
2. 安装项目依赖
按下
Win\+R输入cmd，打开命令提示符窗口通过
cd命令切换到解压后的项目根目录，示例命令：cdD:\tools\timetagger-26.1.3执行依赖安装命令，一键安装所需组件（推荐搭配国内镜像源加速）：
pipinstall-rrequirements.txt-ihttps://pypi.tuna.tsinghua.edu.cn/simple
3. 启动服务并验证部署
打开命令提示符（CMD），通过
cd命令切换到解压后的项目根目录（示例）：cd D:\tools\timetagger-26.1.3执行启动命令（TimeTagger 默认端口为 8080，我自定义调整为 8787，命令如下）：
python -m timetagger --bind=127.0.0.1:8787- 若想恢复默认端口，命令改为：
python -m timetagger --bind=127.0.0.1:8080 - 端口可任意自定义（如 8788、8081），只要未被其他程序占用即可
- 若想恢复默认端口，命令改为：
启动成功验证：
- 命令行窗口会保持运行状态，打印服务相关日志，无红色报错、无「端口被占用」提示即代表部署正常；
- 打开任意浏览器，输入你自定义的端口访问地址：
http://localhost:8787/timetagger/app/（若用默认端口则访问http://localhost:8080/timetagger/app/），确认页面能正常加载。
4. 进入正式APP模式（核心步骤）
页面加载完成后，找到并点击左上角的 APP 菜单
在下拉选项中点击APP应用程序，切换至本地持久化模式
此时退出演示沙箱状态，所有时间记录、标签配置都会本地保存，关闭浏览器不会丢失数据
5. 配置开机自启（免手动启动）
完成APP模式切换后，关闭当前命令行窗口，重启电脑
开机后无需双击任何脚本、无需重新执行启动命令，直接浏览器访问原有地址即可使用
服务会在后台静默自启，全程无弹窗、不占用桌面资源
四、常规使用流程
电脑开机，等待系统加载完成
浏览器输入地址：
http://localhost:8787/timetagger/app/直接进入TimeTagger操作界面，开始时间记录、分类、统计
五、完整注意事项
项目解压路径严禁包含中文、空格、特殊符号，否则会导致依赖安装失败、服务无法读取数据
必须点击左上角APP菜单→APP应用程序，否则处于沙箱演示模式，关闭页面数据立即丢失
保持8787端口不被其他程序占用，若端口冲突，可将启动命令端口改为8788、8080等未占用端口
禁止删除Python环境，否则会导致服务无法自启、运行崩溃
数据默认存储在系统用户目录，定期手动备份数据目录，防止系统故障丢失记录
开机自启为后台静默运行，任务管理器可查看对应的python.exe进程，勿随意结束该进程
六、常见故障排查
1. 端口被占用，无法启动
:: 查找8787端口占用进程PIDnetstat-ano|findstr :8787 :: 强制终止占用进程（替换PID为实际数字） taskkill /F /PID12342. 依赖安装失败/超时
:: 先升级pip工具 python-mpipinstall--upgradepip :: 重新安装依赖，更换国内镜像源 pipinstall-rrequirements.txt-ihttps://mirrors.aliyun.com/pypi/simple/3. 开机无法自启
重新进入项目根目录，手动执行启动命令
再次点击APP→APP应用程序切换模式
重启电脑，验证自启效果
4. 数据无法保存
确认已退出沙箱模式，完成APP模式切换
检查当前Windows用户是否拥有目录读写权限
关闭杀毒/防护软件，排除拦截进程的情况
七、服务启停补充
临时停止服务：找到运行的python.exe命令行窗口，按下
Ctrl\+C，关闭窗口即可禁用开机自启：删除自启配置或卸载全局TimeTagger，恢复手动启动模式
- GitHub 仓库主页：https://github.com/almarklein/timetagger
- 26.1.3 版本发布页：https://github.com/almarklein/timetagger/releases/tag/26.1.3