Ubuntu 22.04 安装 Traggo 0.8.3 指南

在 Ubuntu 22.04 裸机服务器上从零安装 Traggo 0.8.3：官方二进制在线/离线两方案、配置文件、systemd 托管与验证，全部命令实测回显。

TraggoTraggo时间追踪Ubuntu 22.042026/10/25

Ubuntu 22.04 安装 Traggo 0.8.3 指南

目标：在 Ubuntu 22.04 裸机服务器上从零完成 Traggo 0.8.3 的安装、配置、systemd 托管与验证。本文全部命令与回显均来自真实环境实测（Traggo 为 Go 单二进制 + SQLite 形态，无需运行时依赖）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"）
  • 架构：x86_64（amd64；官方另提供 arm64、armv7、windows amd64 包）
  • 软件版本：Traggo v0.8.3（2026-03-01 发布，commit 6321119c3c2d55f04e2e4967f6492aabd6067b76）
  • 安装路径：/opt/traggo（程序）、/etc/traggo/server.ini（配置）、/var/lib/traggo（数据）
  • 运行账号：traggo（系统账号）；监听端口：3030
  • 数据库：SQLite（/var/lib/traggo/traggo.db）

二、前置条件

Traggo 是静态编译的 Go 单二进制，不需要 JDK/PHP/Node 等任何运行时。仅需准备下载与校验工具：

apt-get update -qq
apt-get install -y wget curl sqlite3 ca-certificates

验证工具版本（实测回显）：

wget --version | head -1
# GNU Wget 1.21.2 built on linux-gnu.

sqlite3 --version
# 3.37.2 2022-01-06 13:25:41 872ba256cbf61d9290b571c0e6d82a20c224ca3ad82971edc46b29818d5dalt1

💡 说明：sqlite3 命令行不是 Traggo 的运行依赖（Traggo 内嵌 SQLite 驱动），装它是为了运维时直接查库验证数据落盘。

三、版本选型说明

Traggo 官方 Release（GitHub traggo/server）为每个版本提供 4 个资产（v0.8.3 实查）：

资产适用
traggo_0.8.3_linux_amd64.tar.gz本文环境（x86_64 服务器）
traggo_0.8.3_linux_arm64.tar.gzARM64 服务器/树莓派 64 位
traggo_0.8.3_linux_armv7.tar.gz32 位 ARM
traggo_0.8.3_windows_amd64.zipWindows

⚠️ Traggo 没有 apt/yum 仓库，也没有 --version 子命令；版本号只能从启动日志或 GraphQL version 查询读取。选择版本时直接到 Releases 页取最新 tag 即可，本文实测 v0.8.3。

四、方案 A：官方预编译二进制在线安装（推荐）

官方推荐方式就是下载预编译 tarball，本节为完整 0→1 过程。

4.1 下载安装包

cd /tmp
wget https://github.com/traggo/server/releases/download/v0.8.3/traggo_0.8.3_linux_amd64.tar.gz

⚠️ 网络说明（实测记录）：本次实测时官方源 github.com 直连超时不可用，已改用代理通道完成下载，真实回显如下；若你的服务器可直连官方源，直接执行上面的命令即可。

2026-10-25 00:56:03 URL:https://release-assets.githubusercontent.com/... -> "/tmp/traggo_0.8.3_linux_amd64.tar.gz" [1]

校验文件大小与 SHA256（实测）：

ls -la /tmp/traggo_0.8.3_linux_amd64.tar.gz
# -rw-r--r-- 1 root root 7014851 Mar  1  2026 /tmp/traggo_0.8.3_linux_amd64.tar.gz

sha256sum /tmp/traggo_0.8.3_linux_amd64.tar.gz
# c14012c5d4975c23e8214770bba02a106de7fa8fcf1d10c7a127ebec30536639  /tmp/traggo_0.8.3_linux_amd64.tar.gz

4.2 创建用户与目录

useradd -r -s /usr/sbin/nologin traggo
mkdir -p /opt/traggo /etc/traggo /var/lib/traggo

说明：traggo 为系统账号（不可登录）；/opt/traggo 放程序，/etc/traggo 放配置，/var/lib/traggo 放 SQLite 数据。

4.3 解压安装

tar xzf /tmp/traggo_0.8.3_linux_amd64.tar.gz -C /opt/traggo
ls -la /opt/traggo

实测回显：

total 17528
drwxr-xr-x 2 root root     4096 Oct 25 00:56 .
drwxr-xr-x 1 root root     4096 Oct 25 00:56 ..
-rw-r--r-- 1 1001 1001      598 Mar  1  2026 .env.sample
-rw-r--r-- 1 1001 1001    35149 Mar  1  2026 LICENSE
-rw-r--r-- 1 1001 1001     2735 Mar  1  2026 README.md
-rwxr-xr-x 1 root root 17893864 Mar  1  2026 traggo

包内仅 4 个文件：可执行文件 traggo（约 17MB）、配置样例 .env.sample、LICENSE、README。修正属主：

chown -R traggo:traggo /opt/traggo /var/lib/traggo

4.4 编写配置文件

创建 /etc/traggo/server.ini（格式为 KEY=VALUE，与 .env 相同）：

cat > /etc/traggo/server.ini <<'EOF'
TRAGGO_PORT=3030
TRAGGO_DEFAULT_USER_NAME=admin
TRAGGO_DEFAULT_USER_PASS=q1w2e3r4
TRAGGO_PASS_STRENGTH=10
TRAGGO_LOG_LEVEL=info
TRAGGO_DATABASE_DIALECT=sqlite3
TRAGGO_DATABASE_CONNECTION=/var/lib/traggo/traggo.db
EOF
chmod 640 /etc/traggo/server.ini
chown root:traggo /etc/traggo/server.ini

逐项说明：

配置项本文取值含义
TRAGGO_PORT3030HTTP 监听端口
TRAGGO_DEFAULT_USER_NAMEadmin首次启动（库中无任何用户时）创建的默认用户名
TRAGGO_DEFAULT_USER_PASSq1w2e3r4首次启动默认用户的密码（官方默认 admin/admin，务必修改）
TRAGGO_PASS_STRENGTH10bcrypt 密码强度，越大越安全越慢
TRAGGO_LOG_LEVELinfo日志级别：debug/info/warn/error/fatal/panic
TRAGGO_DATABASE_DIALECTsqlite3数据库方言，官方仅声明 sqlite3
TRAGGO_DATABASE_CONNECTION/var/lib/traggo/traggo.dbSQLite 数据库文件绝对路径

⚠️ TRAGGO_DEFAULT_USER_* 只在首次启动建库时生效；库里已有用户后修改这两项不会影响已存在的账号。

4.5 systemd 托管

创建 /etc/systemd/system/traggo.service：

[Unit]
Description=Traggo - tag-based time tracking server
After=network.target

[Service]
Type=simple
User=traggo
Group=traggo
WorkingDirectory=/opt/traggo
ExecStart=/opt/traggo/traggo
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

加载、启用并启动（每行一个单元操作）：

systemctl daemon-reload
systemctl enable traggo
systemctl start traggo

验证服务状态（实测回显）：

systemctl is-active traggo
# active

systemctl status traggo --no-pager | head -12

● traggo.service - Traggo - tag-based time tracking server
     Loaded: loaded (/etc/systemd/system/traggo.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 00:58:48 UTC; 2s ago
   Main PID: 2685 (traggo)
      Tasks: 7 (limit: 3612)
     Memory: 3.9M
        CPU: 54ms
     CGroup: /system.slice/.../traggo.service
             └─2685 /opt/traggo/traggo

Oct 25 00:58:48 host systemd[1]: Started Traggo - tag-based time tracking server.
Oct 25 00:58:48 host traggo[2685]: 2026-10-25T00:58:48Z INF Traggo buildDate=2026-03-01T10:30:56Z buildMode=prod commit=6321119c3c2d55f04e2e4967f6492aabd6067b76 version=0.8.3

常驻内存仅约 3.9MB，非常轻量。

4.6 验证运行

端口监听（若无 ss 命令先 apt-get install -y iproute2）：

ss -ltnp | grep 3030
# LISTEN 0 4096 *:3030 *:* users:(("traggo",pid=2685,fd=6))

HTTP 探活：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3030/
# 200

curl -sI http://localhost:3030/ | head -3
# HTTP/1.1 200 OK
# Content-Type: text/html
# Date: Sun, 25 Oct 2026 00:58:56 GMT

数据库落盘验证：

ls -la /var/lib/traggo/
# -rw-r--r-- 1 traggo traggo 86016 Oct 25 00:58 traggo.db

sqlite3 /var/lib/traggo/traggo.db ".tables"
# dashboard_entries      devices                user_settings
# dashboard_ranges       tag_definitions        users
# dashboard_tag_filters  time_span_tags
# dashboards             time_spans

浏览器访问 http://<服务器IP>:3030，用 admin / q1w2e3r4 登录即可使用。

五、方案 B：离线包安装（断网/内网环境）

适用于目标服务器完全隔离、无法访问外网的场景。思路：在可联网机器下载 tarball，拷贝到目标机后按方案 A 安装。

5.1 在可联网机器下载并校验

与 4.1 相同，下载 traggo_0.8.3_linux_amd64.tar.gz 并记录 SHA256 c14012c5d4975c23e8214770bba02a106de7fa8fcf1d10c7a127ebec30536639。

5.2 拷贝到目标服务器

scp /tmp/traggo_0.8.3_linux_amd64.tar.gz root@<目标服务器>:/tmp/

5.3 目标机校验后安装

sha256sum /tmp/traggo_0.8.3_linux_amd64.tar.gz
# c14012c5d4975c23e8214770bba02a106de7fa8fcf1d10c7a127ebec30536639  /tmp/traggo_0.8.3_linux_amd64.tar.gz

哈希一致后，依次执行 4.2（用户与目录）→ 4.3（解压）→ 4.4（配置）→ 4.5（systemd）→ 4.6（验证），步骤与回显同方案 A，不再重复。

六、方案对比与选择建议

维度方案 A 在线安装方案 B 离线安装
版本0.8.30.8.3
是否需要联网需要（或可经代理）目标机不需要
安装方式wget 官方 Release + tar 解压拷贝 tarball + tar 解压
systemd 服务名traggotraggo
监听端口30303030
优点步骤最少适配内网隔离环境
缺点依赖外网可达多一次人工拷贝与校验

建议：能联网（含经代理）一律选方案 A；完全断网选方案 B，且务必核对 SHA256。容器化部署请直接参考本专栏《Traggo 0.8.3 Docker Compose 部署指南》。

七、配置说明

配置来源与优先级（首个出现的值生效，已实测验证）：环境变量 > .env.local（二进制同目录）> .env（二进制同目录）> $HOME/.config/traggo/server.ini > /etc/traggo/server.ini。本文采用 /etc/traggo/server.ini 全局配置。全部配置项的逐项详解（含默认值、实测优先级验证、非法值报错）见本专栏《Traggo 0.8.3 配置参数详解》。

升级方法：备份 /var/lib/traggo/traggo.db → 停服务 → 用新版 tarball 覆盖 /opt/traggo/traggo 二进制 → 启动即可（Traggo 启动时自动执行数据库迁移）。降级同理覆盖回旧二进制，但 0.x 阶段不保证高版本库能被旧版本读取，升级前务必备份。

八、常见问题

Q1：执行 traggo --help 或 traggo --version 为什么不打印帮助，反而把服务起起来了？

A：Traggo 二进制没有任何 CLI 子命令/参数解析，无论传什么参数都会直接启动服务并前台阻塞。实测：

$ /opt/traggo/traggo --version
INF Traggo buildDate=2026-03-01T10:30:56Z buildMode=prod commit=6321119... version=0.8.3
INF Creating default user.
INF Start listening port=3030

查看版本请看启动日志第一行的 version=，或调用 GraphQL version 查询。若不小心在前台起了一个实例，Ctrl+C 终止即可；注意它会按当前工作目录创建 data/traggo.db，误起后记得清理该目录。

Q2：修改了 TRAGGO_DEFAULT_USER_PASS 重启后密码没变？

A：默认用户只在库里没有任何用户时创建一次。库已存在用户后该配置不再生效；改密码请在 Web UI 中操作或用 API updateUser。

Q3：配置文件改了不生效？

A：按优先级检查是否存在更高优先级的来源——尤其是环境变量（systemd 单元里的 Environment= 也算）和二进制同目录的 .env.local/.env。把 TRAGGO_LOG_LEVEL 调成 debug 可在启动日志看到 Loading file ... 行，确认实际加载了哪些文件。

Q4：忘记 admin 密码怎么办？

A：没有找回机制。可在停服后用 sqlite3 删除用户再启动重建默认用户：sqlite3 /var/lib/traggo/traggo.db "DELETE FROM users;"，然后启动服务即可按 TRAGGO_DEFAULT_USER_* 重建（注意这会删掉所有用户及其数据关联，操作前备份）。

九、卸载与清理

systemctl stop traggo
systemctl disable traggo
rm /etc/systemd/system/traggo.service
systemctl daemon-reload
rm -rf /opt/traggo /etc/traggo /var/lib/traggo
userdel traggo

如需保留数据备份，删除前先把 /var/lib/traggo/traggo.db 复制到安全位置。

十、参考链接