Traggo 0.8.3 配置参数详解
Traggo 0.8.3 全部 7 个 TRAGGO_* 配置项逐项详解：五级配置来源与优先级实测验证、默认值、非法值报错实录、裸机与 Compose 生产配置模板。
Traggo 0.8.3 配置参数详解
目标：逐项讲透 Traggo 0.8.3 的全部配置项、配置来源与优先级，并给出经实测验证的优先级实验与生产配置模板。本文基于 Traggo 0.8.3 真实环境实测（启动日志、debug 加载行、端口监听逐一验证）。
一、环境信息
- 软件版本：Traggo v0.8.3（commit
6321119c3c2d55f04e2e4967f6492aabd6067b76） - 操作系统：Ubuntu 22.04.5 LTS，x86_64
- 安装形态：官方预编译二进制
/opt/traggo/traggo（配置结论同样适用于编排化部署形态，该形态下通过环境变量注入） - 默认监听：3030；默认库：
data/traggo.db（SQLite）
二、前置条件
已按本专栏《Ubuntu 22.04 安装 Traggo 0.8.3 指南》或《Traggo 0.8.3 Docker Compose 部署指南》完成部署；本文示例命令均可在已部署环境上独立执行。
三、参数查看与修改方式
3.1 配置模型：只有 7 个环境变量式配置项
Traggo 没有命令行参数、没有 YAML/TOML 配置文件，全部配置就是 7 个 TRAGGO_* 键（源码 config/config.go 实查，默认值见下表）。配置格式为 KEY=VALUE，与 .env 文件格式一致。
3.2 配置来源与优先级（已实测）
Traggo 按以下顺序查找配置，首个出现的值生效（官方文档原话：Properties will never be overridden）：
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1（最高） | 操作系统环境变量 | 含 systemd 单元的 Environment= |
| 2 | .env.local | 与二进制同目录 |
| 3 | .env | 与二进制同目录 |
| 4 | $HOME/.config/traggo/server.ini | 运行用户的 home 下 |
| 5（最低） | /etc/traggo/server.ini | 全局配置 |
3.3 优先级实测验证
在装有 /etc/traggo/server.ini（含 TRAGGO_PORT=3030）的机器上逐级叠加配置，观察启动日志中的监听端口：
# 环境变量优先于 ini 文件：设置为 3040
TRAGGO_PORT=3040 ./traggo
# INF Start listening port=3040
# 二进制同目录放 .env（TRAGGO_PORT=3050），不带环境变量启动
./traggo
# INF Start listening port=3050
# 再放 .env.local（TRAGGO_PORT=3060），.env.local 盖过 .env
./traggo
# INF Start listening port=3060
# 环境变量 TRAGGO_PORT=3070 盖过 .env.local
TRAGGO_PORT=3070 ./traggo
# INF Start listening port=3070
# 删掉 .env/.env.local，放 $HOME/.config/traggo/server.ini（TRAGGO_PORT=3080）
./traggo
# INF Start listening port=3080
debug 日志可直接看到实际加载了哪些文件（TRAGGO_LOG_LEVEL=debug 实测）：
DBG Loading file /root/.config/traggo/server.ini
DBG Loading file /etc/traggo/server.ini
INF Start listening port=3080
💡 说明：注意「按属性首个生效」而非「按文件整体生效」——
.env.local里没写的键仍会从.env、home ini、/etc/traggo/server.ini补齐。
3.4 修改方式对照
- 裸机 systemd 部署：改
/etc/traggo/server.ini后systemctl restart traggo；或在单元文件中加Environment=TRAGGO_xxx=...（优先级更高）。 - 编排化部署：修改编排文件中的
environment:后重建服务生效（见本专栏 Compose 部署篇）。
四、参数总览
| 配置项 | 默认值 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
TRAGGO_PORT | 3030 | int | 否 | HTTP 监听端口 |
TRAGGO_DEFAULT_USER_NAME | admin | string | 否 | 首次建库的默认用户名 |
TRAGGO_DEFAULT_USER_PASS | admin | string | 否 | 首次建库的默认用户密码 |
TRAGGO_PASS_STRENGTH | 10 | int | 否 | bcrypt 密码强度 |
TRAGGO_LOG_LEVEL | info | enum | 否 | 日志级别 |
TRAGGO_DATABASE_DIALECT | sqlite3 | enum | 否 | 数据库方言 |
TRAGGO_DATABASE_CONNECTION | data/traggo.db | string | 否 | 数据库连接串 |
五、核心参数分类详解
5.1 网络：TRAGGO_PORT
- 含义：HTTP 服务器监听端口，监听地址固定为全部接口（
*:3030，ss -ltnp实测），无单独的 bind-address 配置项；需要只监听本机时，用前置反向代理或防火墙实现。 - 实测：
TRAGGO_PORT=3040启动后日志INF Start listening port=3040。 - 注意：编排化部署场景改它要同步修改端口映射的右侧。
5.2 初始账号：TRAGGO_DEFAULT_USER_NAME / TRAGGO_DEFAULT_USER_PASS
- 含义：当数据库中没有任何用户时，启动自动创建该默认账号（日志出现
INF Creating default user.）；库里已有用户后，这两项完全被忽略。 - 默认值 admin/admin 极不安全，首次部署务必改掉，本文示例统一为
admin/q1w2e3r4。 - 已有实例改密码：Web UI 内修改，或 GraphQL
updateUser（见《Traggo 0.8.3 API 使用详解》）。
5.3 密码强度：TRAGGO_PASS_STRENGTH
- 含义：bcrypt 哈希 cost 因子（默认 10），新建/修改用户密码时生效；提高它让暴力破解更难，但登录与建用户更慢。
- 建议：个人/小团队保持 10；对安全敏感的公网实例可调到 12，调整后先用
time实测登录延迟可接受再上线。 - 注意：只影响之后写入的密码哈希，已有密码不自动重哈希。
5.4 日志：TRAGGO_LOG_LEVEL
- 取值（实测确认）：
debug/info/warn/error/fatal/panic。 debug会额外输出配置加载明细（DBG Loading file ...）、DBG Logger initialized等，排障配置不生效时最有用；生产保持info。- 实测 debug 启动片段：
DBG Logger initialized
INF Traggo buildDate=2026-03-01T10:30:56Z buildMode=prod commit=6321119c3c2d55f04e2e4967f6492aabd6067b76 version=0.8.3
DBG Loading file /opt/traggo/.env.local
DBG Loading file /opt/traggo/.env
5.5 数据库方言：TRAGGO_DATABASE_DIALECT
- 官方文档声明仅支持
sqlite3（默认值）。 - 源码佐证（
database/database.go实查）：二进制中编译进了 gorm 的sqlite3、mysql、postgres三种方言；但官方未文档化也未在 Release 中提供相应支持承诺，生产环境请只使用 sqlite3。 - 实测非法/未文档化值的行为：把连接串指向不存在路径时启动直接致命退出，例如
TRAGGO_DATABASE_DIALECT=mysql且无可用 MySQL 时：
FTL Failed to connect to the database error="default addr for network '/etc/traggo' unknown"
5.6 数据库连接串：TRAGGO_DATABASE_CONNECTION
- sqlite3 方言下就是数据库文件路径，默认
data/traggo.db——注意这是相对进程工作目录的相对路径：- 直接双击/前台
./traggo启动时，工作目录就是当前目录，会在那里生成data/traggo.db； - systemd 部署务必写成绝对路径（如
/var/lib/traggo/traggo.db），或在单元里固定WorkingDirectory； - 编排化部署形态下应用工作目录为
/opt/traggo，默认即/opt/traggo/data/traggo.db，将该目录持久化即可。
- 直接双击/前台
- 父目录不存在时启动报
Failed to connect to the database（致命退出），先建目录再启动。 - 备份就是复制该文件（建议停服或使用 sqlite3
.backup在线备份）。
六、生产配置模板
6.1 裸机 systemd（个人/小团队，单机）
/etc/traggo/server.ini：
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
配套：chmod 640 + chown root:traggo；systemd 单元 User=traggo、WorkingDirectory=/opt/traggo（完整单元见《Ubuntu 22.04 安装 Traggo 0.8.3 指南》4.5 节）。资源占用极低（实测常驻内存约 3.9MB），512MB 内存的小 VPS 即可流畅运行。
6.2 systemd 环境变量注入模板（适合同一台机器多实例并存）
若同机要跑多个 Traggo 实例（如测试/正式分离），不改全局 ini，直接在各自的 systemd 单元里用 Environment= 注入（优先级最高，且互不影响）：
[Service]
User=traggo
WorkingDirectory=/opt/traggo
Environment=TRAGGO_PORT=3031
Environment=TRAGGO_DATABASE_CONNECTION=/var/lib/traggo-test/traggo.db
Environment=TRAGGO_DEFAULT_USER_NAME=admin
Environment=TRAGGO_DEFAULT_USER_PASS=q1w2e3r4
ExecStart=/opt/traggo/traggo
注意每行只写一个 Environment=；数据目录要事先建好并授权给运行账号。
公网暴露时建议前置 Nginx/Caddy 做 TLS 终止（官方文档提供 Reverse Proxy 指引），Traggo 本身不内建 TLS 配置项。
七、常见问题
Q1：改 /etc/traggo/server.ini 后没生效？
A：按 3.2 的优先级排查更高来源：环境变量（systemd Environment=、shell export）、二进制同目录 .env.local/.env、home ini。用 TRAGGO_LOG_LEVEL=debug 看 Loading file 行最直接。
Q2：为什么改了端口后 ss 里还是 3030？
A：同上——存在更高优先级来源把端口又盖回去了；或者你修改后忘了重启服务（systemctl restart traggo）。
Q3：TRAGGO_DATABASE_CONNECTION 用相对路径为什么数据「丢了」？
A：不是丢了，是换工作目录启动后生成了第二个 data/traggo.db。全局搜索 find / -name traggo.db 就能找到旧库。生产一律用绝对路径。
Q4：能配 HTTPS 或访问路径前缀吗？
A：0.8.3 没有内建 TLS、没有 base-path 配置项。HTTPS 交给前置反向代理；子路径挂载不被官方支持，建议用独立子域名。
八、参考链接
- 官方配置文档：https://traggo.net/config/ （查询日期 2026-10-25）
- 源码
config/config.go/database/database.go（traggo/server v0.8.3，2026-10-25 实查） - 本专栏：《Ubuntu 22.04 安装 Traggo 0.8.3 指南》、《Traggo 0.8.3 Docker Compose 部署指南》