管理员文档

01安装部署

deb（Ubuntu 24.04 / Debian 12+，amd64）——实机验证通过

wget https://db.myagent.pub/dl/tsdb-server_0.2.0-1_amd64.deb
sudo apt install ./tsdb-server_0.2.0-1_amd64.deb   # 依赖自动解析
sudo systemctl start tsdb

rpm / 其他 Linux / Windows / macOS

RHEL/Fedora 用随仓库 packaging/rpm/tsdb.spec：./scripts/package-rpm.sh（需 rpmbuild 主机）；无包管理器环境用 fallback tarball（含 install.sh）。

Windows x86_64（MSVC，实机构建 + 冒烟验证，§8.41）：tsdb-0.2.0-windows-x86_64.tar.gz（tsdb-server.exe + tsdb-cli.exe；含 every-write 持久 WAL 修复）。构建路径见 scripts/build-windows.sh。

macOS x86_64（Intel，实机构建 + 冒烟验证，§8.50）：tsdb-0.2.0-macos-x86_64.tar.gz（tsdb-server + tsdb-cli；HDF5 静态链接，无需 Homebrew）。构建路径见 scripts/build-macos.sh。

嵌入模式（进程内库）

引擎本身是 Rust 库：Tsdb::open(config) 进程内直调（零网络开销），data_dir: ":memory:" 纯内存库；运行中可 start_server()/stop_server() 动态升降级（引擎与数据不变）。cargo build --no-default-features 裁掉整个网络栈。同一 data_dir 跨进程独占（文件锁）。示例：examples/embedded_and_server.rs。

02systemd 服务

systemctl start|stop|restart tsdb     # 常规操作
systemctl status tsdb                  # 状态（active / restart 计数）
systemctl enable|disable tsdb          # 开机自启（装包已 enable）
journalctl -u tsdb -f                  # 跟随日志
journalctl -u tsdb -n 50 --no-pager    # 最近 50 行

03配置参考

解析顺序：CLI flag > TSDB_* 环境变量 > tsdb.toml > 内置默认。

主配置（/etc/tsdb/tsdb.toml）

[protocols] 段（协议监听器）

[protocols]
http_enabled = true          # 关闭可组纯二进制节点
tcpmgmt_enabled = true
stream_enabled = true
fast_enabled = true
mpx_enabled = true
# tcpmgmt_port = 19090       # 缺省 = addr 端口 +1010
# stream_port  = 19091       # +1011
# fast_port    = 19092       # +1012
# mpx_port     = 19093       # +1013
# mpx_max_conns = 128        # tcp-mpx 连接上限

环境变量等价：TSDB_PROTO_{HTTP,TCPMGMT,STREAM,FAST,MPX}_ENABLED、TSDB_{TCPMGMT,STREAM,FAST,MPX}_PORT、TSDB_MPX_MAX_CONNS（env > toml > 默认）。

04端口与协议矩阵

05安全

认证三态（2026-08-25 大版本）

• 信任模式：未配置任何凭证（仅本地开发）。用户模式下删光用户/损坏 users.json 均fail-closed，不回退信任。
• 静态 token：auth_token 一枚共享 token；HTTP Bearer + 四个 TCP 端口首帧 AUTH（常量时间比较）。
• 用户模式：PG 风格登录 + 双 token——access 短 TTL（默认 15 分钟）/ refresh 长 TTL（默认 7 天，每次刷新轮换并作废旧串，防重放）。HMAC-SHA256 签名，Claims 内嵌 pwd_version（改密即失效全部旧 token）；签名密钥持久化 <data_dir>/auth_secret（0600）。用户口令 PBKDF2-HMAC-SHA256（10 万迭代、独立盐、恒定时间比较、防枚举时序）。

账户管理：SQL（CREATE/ALTER/DROP USER、SHOW USERS，admin 门）与 HTTP（/auth/login|refresh|logout|me|users）两套等价入口；首启引导 --admin-user/--admin-password（仅用户表为空时生效）。

加固清单（12 项 High 以上全落地）

• cluster/backup/stream/tx 路由 30 处 body 16MB 上限；/cluster/* 认证门（ClusterGate）。
• 解码边界 12 处边界检查 + String 长度上限 + zstd/gzip/lz4 解压双上限（防炸弹流）。
• SQL 标识符校验 补齐 drop/rename/backup/restore/列名；账户语句 admin 门挂全部网络入口。
• 登录防滥用：spawn_blocking + body 上限 + 并发信号量；PASSWORD 字面量进日志/metrics 前脱敏。
• 流订阅 有界通道（64）+ 慢消费者踢除；tcp-mpx 连接计数 RAII 守卫。
• 文件权限：users.json / auth_secret 创建即 0600，原子写。
• 依赖：lz4_flex/bytes/h2/rustls-webpki/crossbeam/postgres 族升级，rustls-pemfile→pki-types（12→1 漏洞）。

通用

• TLS：tls_cert + tls_key（PEM，成对）启用 HTTPS。
• 数据目录独占锁：同一 data_dir 跨进程只允许一个实例（OS 文件锁，崩溃自动释放）；跨进程双开得到明确错误而非静默损坏 WAL。
• 版本升级：历史事故档案——旧版本二进制的 9092 曾无认证可执行 SQL（§8.24）；升级后用 curl 9092 直连自检应被拒。
• io 沙箱：/import /export 路径限制在 <data_dir>/io 内，拒绝绝对路径与穿越。
• 防火墙：默认绑定 127.0.0.1；对外仅放行必要端口。

06备份与恢复

崩溃恢复（实测）

WAL 重放保证 kill -9 零丢行：TSDB 0.22–0.24s（含脏尾）/ DDB 0.61s / PostgreSQL 0.98s（§8.27，432 万行实测）。重启即自动重放，无需人工介入。

备份

systemctl stop tsdb                # 或使用 /backup 端点（在线）
tar -czf tsdb-backup.tgz /var/lib/tsdb
systemctl start tsdb

OPTIMIZE（空间整理）

tsdb-cli query "OPTIMIZE TABLE mytable"

L3 终层自合并：实测 8460 个小段 → 32 个大段（1.4s），幂等（二次执行报 already optimized、零重写，§8.18）。purge 卸载后 /var/lib/tsdb 数据保留。

07监控运维

运维环境变量

08故障排查