Traggo 0.8.3 Docker Compose 部署指南

用 Docker Compose 部署 Traggo 0.8.3：编排文件逐项说明、数据持久化、重启/重建数据保持实测、环境变量表与常用运维命令。

TraggoTraggo时间追踪DockerDocker Compose2026/10/25

Traggo 0.8.3 Docker Compose 部署指南

目标：用 Docker Compose 一键部署 Traggo 0.8.3，并完成数据持久化、默认账号初始化、重启/重建后的数据保持验证。本文全部命令与回显均来自真实环境实测。

一、环境信息

  • Docker 镜像：traggo/server:0.8.3（linux/amd64，digest sha256:8bf510774ce1729b5bd9a8930e174de03ebec8c25ca4aaa087c0e56e2bcbb67a）
  • 镜像工作目录：/opt/traggo，ENTRYPOINT 为 ./traggo，暴露端口 3030/tcp（docker image inspect 实测）
  • 宿主机映射端口：8134（可按需改）
  • 数据持久化：bind mount ./data → 容器内 /opt/traggo/data（SQLite 库文件 traggo.db 落于此）
  • Compose 项目名：traggo-0.8.3-stack

二、镜像选型说明

Traggo 官方在 Docker Hub 维护 traggo/server 镜像，tag 与 GitHub Release 版本一一对应（如 0.8.3、latest）。生产建议锁定具体版本 tag（本文用 0.8.3），不要用 latest，避免 0.x 阶段升级引入不兼容变更。多架构支持：官方 Release 提供 amd64/arm64/armv7，镜像同为多架构 manifest。

三、前置条件

  • 已安装 Docker Engine 与 Compose 插件（docker compose version 可用）；
  • 宿主机 8134 端口未被占用（ss -ltn | grep 8134 无输出）；
  • 拉取镜像慢时先配置镜像加速或代理，本文镜像拉取实测正常。

四、部署步骤

4.1 创建项目目录与编排文件

mkdir -p /srv/traggo/data && cd /srv/traggo

创建 docker-compose.yml：

name: traggo-0.8.3-stack

services:
  traggo:
    image: traggo/server:0.8.3
    container_name: traggo-0.8.3-compose
    restart: unless-stopped
    ports:
      - "8134:3030"
    environment:
      TRAGGO_PORT: 3030
      TRAGGO_DEFAULT_USER_NAME: admin
      TRAGGO_DEFAULT_USER_PASS: q1w2e3r4
      TRAGGO_LOG_LEVEL: info
      TRAGGO_DATABASE_DIALECT: sqlite3
      TRAGGO_DATABASE_CONNECTION: /opt/traggo/data/traggo.db
    volumes:
      - ./data:/opt/traggo/data

逐项说明：

  • name：显式固定 Compose 项目名，避免同机多套栈目录同名互相影响；
  • ports：宿主机 8134 → 容器 3030；
  • environment：7 个 TRAGGO_* 配置项直接注入（Traggo 原生按环境变量读取，详见《Traggo 0.8.3 配置参数详解》）；TRAGGO_DEFAULT_USER_PASS 必须改成本文示例的 q1w2e3r4 或更强口令；
  • volumes：把 SQLite 数据目录挂到宿主机 ./data，保证容器重建后数据不丢。

4.2 启动并验证

docker compose up -d

实测回显：

 Network traggo-083-stack_default  Created
 Container traggo-0.8.3-compose  Started

docker compose ps

NAME                   IMAGE                 COMMAND      SERVICE   STATUS         PORTS
traggo-0.8.3-compose   traggo/server:0.8.3   "./traggo"   traggo    Up 3 seconds   0.0.0.0:8134->3030/tcp, [::]:8134->3030/tcp

查看启动日志确认默认用户已创建：

docker logs traggo-0.8.3-compose | tail -3

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

4.3 功能验证

HTTP 探活与版本查询：

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

curl -s -X POST http://localhost:8134/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ version { name } }"}'
# {"data":{"version":{"name":"0.8.3"}}}

用默认账号 admin / q1w2e3r4 登录（GraphQL 实测）：

curl -s -X POST http://localhost:8134/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"mutation { login(username: \"admin\", pass: \"q1w2e3r4\", deviceName: \"compose-check\", type: NoExpiry, cookie: false) { token user { name } } }"}'
# {"data":{"login":{"token":"plYjyNhwMeUdTcEwljjt","user":{"name":"admin"}}}}

确认数据落盘到宿主机目录：

ls -la ./data/
# -rw-r--r-- 1 root root 86016 Oct 25 09:09 traggo.db

浏览器访问 http://<宿主机IP>:8134，用 admin / q1w2e3r4 登录。

五、数据持久化说明

Traggo 镜像工作目录为 /opt/traggo，默认数据库连接串是相对路径 data/traggo.db，即容器内 /opt/traggo/data/traggo.db。本编排显式把 TRAGGO_DATABASE_CONNECTION 指向该路径并把目录挂载到宿主机 ./data。验证重启/重建后数据保持：

docker compose restart
# Container traggo-0.8.3-compose Started

# 重启后原账号仍可登录（实测返回新 token）
curl -s -X POST http://localhost:8134/graphql -H 'Content-Type: application/json' \
  -d '{"query":"mutation { login(username: \"admin\", pass: \"q1w2e3r4\", deviceName: \"after-restart\", type: NoExpiry, cookie: false) { token } }"}'
# {"data":{"login":{"token":"NZdPtxsNVE71NqCAHQos"}}}

docker compose down
docker compose up -d
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8134/
# 200

down + up 重建容器后服务正常、数据完整（默认用户只创建一次，日志不再出现 Creating default user.）。

六、环境变量表

环境变量默认值本文取值说明
TRAGGO_PORT30303030容器内监听端口（改它要同步改 ports 映射）
TRAGGO_DEFAULT_USER_NAMEadminadmin首次建库时创建的默认用户名
TRAGGO_DEFAULT_USER_PASSadminq1w2e3r4首次建库时默认用户密码，务必修改
TRAGGO_PASS_STRENGTH1010（默认）bcrypt 强度
TRAGGO_LOG_LEVELinfoinfodebug/info/warn/error/fatal/panic
TRAGGO_DATABASE_DIALECTsqlite3sqlite3数据库方言
TRAGGO_DATABASE_CONNECTIONdata/traggo.db/opt/traggo/data/traggo.dbSQLite 文件路径（容器内绝对路径）

七、配置参数说明

Compose 场景下所有配置都通过 environment: 注入，无需挂载配置文件——环境变量在 Traggo 的配置优先级中最高。若你更习惯配置文件，也可把 server.ini 挂载到容器内 /etc/traggo/server.ini，但同一属性以环境变量为准。全部参数详解见本专栏《Traggo 0.8.3 配置参数详解》。

八、配置文件挂载（可选）

如需挂载 ini 配置（优先级低于环境变量）：

    volumes:
      - ./data:/opt/traggo/data
      - ./server.ini:/etc/traggo/server.ini:ro

注意：环境变量已设置的项会覆盖 ini 同名项，二者不要混用同一键，避免排查困难。

九、等价 docker run

不用 Compose 时等价命令：

docker run -d --name traggo-0.8.3-compose --restart unless-stopped \
  -p 8134:3030 \
  -e TRAGGO_PORT=3030 \
  -e TRAGGO_DEFAULT_USER_NAME=admin \
  -e TRAGGO_DEFAULT_USER_PASS=q1w2e3r4 \
  -e TRAGGO_LOG_LEVEL=info \
  -e TRAGGO_DATABASE_DIALECT=sqlite3 \
  -e TRAGGO_DATABASE_CONNECTION=/opt/traggo/data/traggo.db \
  -v /srv/traggo/data:/opt/traggo/data \
  traggo/server:0.8.3

十、常用运维命令

docker compose ps                 # 查看状态
docker compose logs -f            # 跟随日志
docker compose restart            # 重启（数据保持）
docker compose down               # 停止并删除容器/网络（数据保留在 ./data）
docker compose up -d              # 重新拉起
docker compose pull               # 拉取新镜像后 up -d 完成升级

升级流程：cp ./data/traggo.db ./data/traggo.db.bak 备份 → 修改 compose 中镜像 tag → docker compose pull && docker compose up -d。

十一、常见问题

Q1：改 TRAGGO_DEFAULT_USER_PASS 后重建容器，密码没变化？

A：默认用户只在库里没有用户时创建一次。./data/traggo.db 已存在用户后该项无效；请在 Web UI 中改密码。

Q2：忘记密码想重置？

A：docker compose down 后删除 ./data/traggo.db（会清空全部数据，先备份），再 up -d 即按环境变量重建默认用户。

Q3：日志报 Failed to connect to the database？

A：多为 TRAGGO_DATABASE_CONNECTION 指向的目录不存在或权限不足。确认挂载目录存在且容器进程可写。

Q4：宿主机端口冲突？

A：改 ports 左侧宿主机端口即可，容器内 3030 不变。

十二、参考链接