做时间序列分析的朋友应该都有过这种经历数据模型跑通了、图表也画出来了但那些异常区间、事件拐点、分类标签到底该怎么记录始终是个头疼的问题。用 Excel 记时间点格式乱得没法看写备注文件核查时到处翻直接在代码里硬编码换个人接手就彻底抓瞎。我前一阵在 Linux 服务器上做设备时序数据的标注整理试了好几个方案最后把 TimeTagger 这个开源的时间序列注解工具部署到了本地顺带解决了局域网和公网访问的问题。这篇文章把整个部署链路原原本本记录下来包括环境准备、服务启动、反代公网访问、安全加固以及我踩过的几个坑。如果你正准备在 Linux 上私有化部署一套时间序列标注系统这篇内容可以直接照着抄。1. TimeTagger 到底解决了什么问题一个时序标注工具的真实定位1.1 从时序标注需求到 TimeTagger 的选型先聊一下我为什么需要它。当时我在处理一组传感器时间序列数据需要把某几段设备异常状态标注出来供后续做监督学习训练集使用。需求其实很朴素能横向看整条时间轴、能框选一个时间范围、能给这段范围打上标签和备注最后能把标注结果导出来喂给训练脚本。市面上通用 BI 工具不适合干这个活它们擅长展示数据却不擅长做标记。直接用 Python matplotlib 也确实能画框但每一次改标签都要改代码重跑团队协作时大家标注的口径也很容易不一致。TimeTagger 这类工具把浏览时序数据-圈选区域-填写注解-导出结果整个流程闭环了并且跑在浏览器里不需要给每台机器装客户端。它的定位和监控系统不一样监控看的是当前有没有异常报警TimeTagger 关注的是这段历史数据里发生了什么我要把它记下来。这个粒度差异决定了它非常适合算法工程师、数据标注团队、运维做故障复盘这三类人群。1.2 技术栈速览Node.js 生态下的轻量服务我实测的这个版本基于 Node.js 构建现在很多同类工具也选了这个技术栈生态成熟、部署简单。服务端用 Express 这类框架提供 REST API通过 WebSocket 把数据加载进度、标注状态变更实时推送到前端页面数据落盘用的 SQLite单文件存储备份和迁移都很方便。这个组合对本地部署有很实际的意义不依赖外部数据库没有容器编排的负担在一台 2 核 4G 的服务器上就能跑得很稳。前端是一个单页应用浏览器打开之后通过接口读取 SQLite 里的数据所有标注结果通过接口写回数据库整个链路是闭环的数据不会经过任何第三方服务器。部署起来相对清爽。1.3 数据模型与标注流程的关系Tab 和 Annotation理解 TimeTagger 的部署最好先理解它的数据组织方式。概念上它有两类核心对象Tab数据视图对应一个数据源或一份 CSV/JSON 数据集。你可以给每个 Tab 设定时间字段、数值字段工具会按时间轴把数据渲染出来。Annotation注解项标注的对象本身分为区间型某一时间段持续异常和点型某一时刻发生的事件两类。每条 Annotation 可以挂标签、写备注、设定颜色。实际使用流程是先创建一个 Tab导入时间序列数据然后在时间轴上框选需要标注的区间填上标签和描述最后导出完整的标注结果。部署本质上是把这个Tab Annotation的工作台变成一个常驻服务让团队里的同事通过浏览器共同使用同一份标注库。2. Linux 环境下的部署准备版本检查、依赖安装与初始配置2.1 环境检查清单Linux 发行版与运行时的选择我手头是 Ubuntu 22.04 服务器这套步骤在 Debian 系发行版上基本通用。如果用 CentOS / Rocky Linux包管理命令换成 yum / dnf 即可核心逻辑不变。部署前先把运行时环境确认好检查项推荐配置说明操作系统Ubuntu 20.04 / 22.04 或 Debian 11Linux 内核 5.x 以上即可无需特殊内核模块CPU / 内存2 核 2G 起步数据集较小的场景内存占用约 300M大 CSV 文件建议 4GNode.js18 LTS 或 20 LTS低于 16 会出现依赖安装失败高于 22 个别旧版本有兼容问题磁盘空间预留 2G 以上主体程序很小主要是数据文件和标注导出文件的增长Node.js 的版本坑我后面会单独讲这里多说一句尽量装 LTS 版本别追奇偶新版本。当时有个同事在服务器上默认装了 Node 16npm install 直接报错后来换成 Node 20 一次性通过。2.2 获取源码、安装依赖与 SQLite 初始化确认好环境之后先把项目部署目录建好。我习惯把这类自部署服务统一放在/opt下方便后续 systemd 管理# 创建部署目录并拉取源码以实际仓库地址为准 sudo mkdir -p /opt/timetagger cd /opt/timetagger git clone 项目仓库地址 . # 安装 npm 依赖 npm install --production # 查看版本确认安装成功 node -v npm -v如果服务器在中国大陆环境直接拉取 GitHub 仓库速度不理想可以给 git 配一个国内镜像加速或者把仓库下载后手动上传到服务器。npm 安装依赖同理建议设置淘宝 registrynpm config set registry https://registry.npmmirror.com依赖装完之后正常情况下项目目录下会有一个配置文件模板一般叫.env.example或config/default.json。复制一份出来cp .env.example .env然后按实际需要修改几个关键项下面是我当时的配置思路。2.3 关键配置项监听端口、数据目录与导入文件大小配置文件里核心就三块我逐个说明监听端口PORT默认 3000。端口选择上注意两点一是别选被系统预留的端口二是如果你后面要用 Nginx 反代这个端口可以保持默认不必直接暴露到公网。数据目录DATA_DIRSQLite 数据库文件和上传的数据文件存放位置。建议单独指向一个磁盘空间充足的路径避免后面数据量涨起来之后把系统盘占满。导入文件大小上限MAX_UPLOAD_SIZE默认通常是 20MB。如果你要导入的是高频采集的传感器数据单个 CSV 很容易超过这个值提前改到 100MB 或更高省得后面导入时报错又重启服务。用我服务器上的配置举例PORT3000 DATA_DIR/var/lib/timetagger MAX_UPLOAD_SIZE104857600其中/var/lib/timetagger目录需要提前创建并给运行用户赋予写权限。这一步容易被忽略很多人会在启动时遇到数据库无法写入的报错其实只是目录权限没给够。提示DATA_DIR建议单独规划不要直接放在项目代码目录里。原因很简单代码升级时容易误覆盖数据目录且项目目录一般不挂独立磁盘。3. 启动服务后让局域网设备访问监听地址、防火墙与 systemd3.1 把监听地址从 127.0.0.1 改到 0.0.0.0服务默认只监听本机回环地址127.0.0.1也就是说只有服务器本机能访问。如果你只是想在自己这台 Linux 机器上用保持默认就行。但标题里的外部访问第一步就是把监听地址改成0.0.0.0。有两种改法如果项目配置里有HOST或BIND_ADDRESS项直接在.env里设HOST0.0.0.0如果没有启动命令里手动绑定以 Node.js 为例node server.js --host 0.0.0.0改完之后用ss -tlnp验证State Local Address:Port LISTEN 0.0.0.0:3000看到0.0.0.0:3000而不是127.0.0.1:3000说明监听地址已经生效。这一步是整个外部访问链路里最简单、也是最容易被忽略的一步很多人折腾半天发现局域网设备访问不了一查监听地址还是回环地址。3.2 防火墙放行端口和设备固定 IP监听地址改完局域网设备访问时还差一道防火墙。Ubuntu 默认一般没开 ufw但如果你之前手动开过需要放行对应端口sudo ufw allow 3000/tcp sudo ufw status这里有个细节如果局域网设备是通过服务器内网 IP 访问的只需放行3000/tcp如果你后续在路由器上做了端口映射那要放行的是你映射到外网的那个公网端口。放行端口权限尽量做到最小只开必要端口别图省事直接ufw allow 3000配合外部访问时裸奔。局域网设备访问时使用http://服务器内网IP:3000即可。为了以后访问地址不漂移建议在路由器或服务器上给这台机器绑定固定内网 IPDHCP 静态分配。我见过不少人在家里/公司局域网部署之后第二天发现服务访问不了原因就是 DHCP 分配的 IP 变了浏览器里存的还是旧地址。3.3 用 systemd 托管服务实现开机自启命令行直接启动的方式只适合验证不适合长期运行。把 TimeTagger 变成系统服务好处是程序崩溃会自动拉起、服务器重启后自动启动日志统一交给 journal 接管。在/etc/systemd/system/timetagger.service创建服务单元[Unit] DescriptionTimeTagger Service Afternetwork.target [Service] Typesimple Usertimetagger WorkingDirectory/opt/timetagger EnvironmentFile/opt/timetagger/.env ExecStart/usr/local/bin/node server.js Restarton-failure RestartSec5 # 如果日志量比较大可以限制 journal 增长速度 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target创建完成后sudo systemctl daemon-reload sudo systemctl enable --now timetagger sudo systemctl status timetagger注意Usertimetagger最好单独建一个无需登录权限的系统用户来跑服务不要直接用 root。到这一步局域网访问已经非常稳定了但从外部网络还是无法访问接下来进入真正的外部访问环节。4. 打通公网访问链路Nginx 反向代理与 WebSocket 升级头4.1 端口映射与动态域名公网访问的基础设施要让外网设备访问到这台 Linux 服务器上的 TimeTagger核心路径是外网设备 → 路由器公网 IP 端口映射→ 服务器 Nginx80/443→ TimeTagger127.0.0.1:3000。如果你有固定的公网 IP直接在路由器管理页面找到端口映射或虚拟服务器功能把公网端口比如 8080映射到服务器的 80 端口即可。但大部分家庭宽带拿的是动态公网 IP这时候需要一个动态域名DDNS服务把每次变化的公网 IP 绑定到一个固定域名上。路由器里现在基本都内置了 DDNS 客户端登录账号后自动更新解析记录。一个需要注意的问题很多地区运营商把 80 和 443 端口屏蔽了。遇到这种情况可以映射一个高位端口比如公网8181→ 内网80访问时用http://域名:8181即可。端口号不影响服务本身只是美观程度差点。4.2 Nginx 反向代理的完整配置如果直接把 TimeTagger 的 3000 端口暴露到公网虽然能用但你无法在同一台服务器上做域名分发、HTTPS 终结、限流也不安全。更合理的做法是让 Nginx 监听 80/443 端口收到请求后转发给本机 3000 端口的 TimeTagger。安装 Nginx 并创建站点配置sudo apt-get install nginx -y sudo vim /etc/nginx/sites-available/timetagger配置文件如下server { listen 80; server_name timetagger.example.com; client_max_body_size 200m; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket 支持 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }然后启用站点并重载sudo ln -s /etc/nginx/sites-available/timetagger /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx4.3 最容易漏掉的 WebSocket 升级头我在这里栽过跟头。一开始按普通 Web 服务配置了反向代理页面能打开数据列表也能加载但时间轴上的实时更新通道一直建立不起来表现就是数据加载转圈半天下不来或者标注状态不同步。查了半天发现是 Nginx 默认没有把Upgrade和Connection头转发给后端WebSocket 握手被拦在了中间。所以上面配置里的这四行是核心不能删proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s;proxy_read_timeout同样关键WebSocket 连接是长连接如果默认 60 秒超时浏览器长时间挂在页面上不操作连接就会被 Nginx 掐断。改成 3600 秒只是权宜之计更合理的是配合后端的 ping/pong 心跳机制保持连接活跃。实测下来这个反代配置对内外网访问体验影响很大。配置正确之后局域网和公网访问的流畅度基本没差前提是服务器上行带宽够用——如果你要公网加载一个大 CSV 文件服务器 4M 上行带宽和 100M 上行带宽的体验差距非常明显。4.4 动态 IP 变化后的域名解析问题公网访问还有一个容易踩的坑DDNS 解析更新不是实时的运营商分配的公网 IP 变了之后域名解析可能还指向旧 IP导致外部设备访问失败。我在实际使用中给路由器设置了一个定时任务每 5 分钟检查一次公网 IP检测到变化立即调用 DDNS 服务商的 API 更新解析记录。如果你用的路由器没有这个功能可以直接在 Linux 服务器上写个 cron 脚本把更新解析的任务交给服务器自己完成。5. 外部访问不能裸奔鉴权、HTTPS 与数据备份5.1 默认无鉴权是最大的安全隐患TimeTagger 这类工具默认部署时通常不强制登录这对于只在 localhost 上用是没问题的但一旦开放到局域网、尤其是映射到公网任何人都可以直接打开页面查看、修改、删除你的标注数据。标注数据往往就是业务数据的浓缩认知对很多团队来说属于核心资产裸奔几天可能就出大问题。我建议的底线是只要是外部访问就必须做一层访问控制。不要指望端口映射的隐蔽性来保护服务公网扫描器无时无刻不在扫 8181、8080 这类非常规端口不用多长时间你的服务就会被发现。5.2 加一层 Basic Auth 的完整步骤最简单的解决方案是在 Nginx 层加 Basic Auth。它不修改 TimeTagger 任何代码纯粹在访问入口拦截成本最低、见效最快。安装 htpasswd 工具并创建账号密码sudo apt-get install apache2-utils -y sudo htpasswd -c /etc/nginx/.htpasswd timetagger然后在 Nginx 配置里加两行location / { auth_basic Restricted Access; auth_basic_user_file /etc/nginx/.htpasswd; # ...原有反代配置不变 }重载 Nginx 之后浏览器再访问就会弹出用户名密码框。如果你用 API 自动化访问在 URL 里携带认证信息或添加Authorization: Basic base64(user:pass)请求头都可以。提示Basic Auth 是明文传输的仅 base64 编码所以它必须配合 HTTPS 使用否则用户名密码等于在公网裸奔。如果你对访问控制有更高的要求比如想让团队里的不同成员有不同的权限可以用 OAuth2 Proxy 这类工具对接 LDAP / GitHub / 企业微信登录统一走身份认证后把请求转发给 TimeTagger。我实际用过 Basic Auth 方案小团队内部够用了先跑起来再迭代。5.3 补一份免费的 HTTPS 证书有了域名之后用 certbot 签一张 Lets Encrypt 证书是性价比最高的选择sudo apt-get install certbot python3-certbot-nginx -y sudo certbot --nginx -d timetagger.example.comcertbot 会自动修改你的 Nginx 配置加入证书路径并配置 80 端口自动跳转到 443。签完证书后面记得测试一下自动续期sudo certbot renew --dry-runHTTPS 的作用不只是加密 Basic Auth 的用户名密码还可以避免在公网环境里数据被劫持篡改。时间序列标注结果如果在传输过程中被插入错误标注那后续训练出来的模型大概率也是错的这个风险不值得冒。5.4 数据备份策略一次性搞定 SQLite 和配置外部访问意味着服务承载了团队协作任务这时候备份变得非常重要。SQLite 数据库的备份很简单直接拷贝文件即可。比较稳妥的方式是每天凌晨做一次冷备并把备份文件同步到另一台机器或对象存储# 备份数据库和数据目录到备份盘 tar -czf /backup/timetagger-$(date %F).tar.gz /var/lib/timetagger # 保留最近 7 份清理旧备份 find /backup/timetagger-*.tar.gz -mtime 7 -delete把这个命令写进 cron 或 systemd timer每天自动执行。有一个细节拷贝 SQLite 文件最好先触发一次WAL checkpoint或者干脆在备份前短暂停掉服务再拷贝避免备份到正在写入中的数据库文件导致备份损坏。我自己是写了个脚本先调用 sqlite3 PRAGMA wal_checkpoint 再打包备份文件一直很健康。6. 部署中遇到的五个典型问题和排查过程6.1 坑一npm install 阶段直接崩在 Node 版本上第一次部署时服务器上预装的是系统源自带的 Node 12npm install 跑到一半报了一堆语法错误。原因是 TimeTagger 依赖的某个包要求 Node 至少 18而 Node 12 的 V8 引擎不支持新的 JavaScript 语法安装时预编译脚本直接失败。排查过程很简单先node -v确认版本再对比项目文档里的要求发现差了一整个大版本。处理方式是彻底移除旧版安装 NodeSource 提供的 20 LTScurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs这里有一个细节不要用系统 apt 自带的 nodejs/npm 包版本往往很旧。也不要直接在官网下载 tar 包解压后覆盖容易留下权限隐患。NodeSource 官方源再国内服务器上速度不理想可以把deb.nodesource.com替换为镜像源其他不变。6.2 坑二启动成功但接口全部 500SQLite 报 database is locked服务启动成功了页面也能打开但导入数据时总是报错后端日志里出现SQLITE_BUSY: database is locked。一开始以为是数据库文件损坏检查后发现不是。根本原因有两个一是之前用 root 启动过一次服务SQLite 数据库文件的 owner 变成了 root后续服务降权到普通用户后无法写入尝试写入时触发了锁错误二是并发写入时 SQLite 默认的 busy timeout 太短手滑连续点击操作时更容易触发。处理方法# 修正数据目录权限 sudo chown -R timetagger:timetagger /var/lib/timetagger # 在应用配置中把 busy_timeout 调大并开启 WAL 模式WALWrite-Ahead Logging模式对并发读写改善很大。开启后读操作不会阻塞写操作多用户同时标注时的冲突概率明显下降。注意修改完数据库模式之后重启一次服务让配置生效。6.3 坑三外部访问能打开页面但数据加载一直转圈WebSocket 连接失败这个前面提过直接把排查链路完整说一遍。现象是局域网内用http://内网IP:3000访问页面完全正常但通过 Nginx 反代访问时页面加载后数据一直不刷新。排查步骤先确认应用本身没问题内网直连正常说明后端正常。打开浏览器开发者工具看 Network 面板发现数据列表接口返回了但一个 WebSocket 连接始终处于pending状态。再看 Console 报错提示WebSocket connection failed。检查 Nginx 错误日志看到upgrade相关报错确认是代理层对 WebSocket 升级协议的处理问题。补充proxy_set_header Upgrade、Connection upgrade后重载问题消失。这个坑在整个部署过程中出现频率很高凡是给 Node.js 实时服务配 Nginx 反代都容易遇到。建议在配置反代时直接把 WebSocket 相关头带上省得事后排查。同样的思路也适用于其他基于 WebSocket 的时序可视化工具。6.4 坑四公网访问图片/文件加载慢上传大文件时 504外部访问通了但公网加载大 CSV 或导出文件时经常出现 504 Gateway Timeout。本质是 Nginx 网关等待后端处理超时。两个位置需要调整一是 Nginx 的proxy_read_timeout和proxy_send_timeout二是文件上传大小限制client_max_body_size。我当时的最终配置里把client_max_body_size设为200m超时时间设为3600s给大文件导入留足余量。如果数据量还要更大更好的方案是把导入文件先放到共享存储盘让 TimeTagger 直接读取本地文件路径绕开浏览器上传环节。6.5 坑五防火墙规则调整导致内网也访问不了排查公网访问问题时我顺手改了一次防火墙规则结果内网访问也断了。当时的情况是原有规则是ufw allow 3000/tcp我为了测试端口映射临时加了一条拒绝规则测试完忘了删。端口映射到公网之后公网请求经过路由器转发到内网时在服务器防火墙层面被拒绝了。排查时把关键链路每一跳都验证了一遍公网请求是否到达路由器路由器日志、是否转发到服务器tcpdump 抓包、服务器防火墙是否放行ufw status。最终定位到是防火墙规则叠加导致的。处理建议向外放行端口只用一条明确规则其他一律默认拒绝改动后立即验证内网访问确保没有误伤。写在最后这套 TimeTagger 部署链路跑通之后我又陆续做了几处小优化数据目录单独挂了一块盘、WebSocket 心跳间隔调到 30 秒、备份脚本加入了完整性校验。日常团队协作已经完全绕开了过去用 Excel 记录时序事件的痛苦流程。如果你也在 Linux 上部署这套工具个人建议按本地验证 → 局域网访问 → 反代公网 → 安全加固 → 备份这个顺序走任何一步踩坑都别急链路每一跳都验证清楚再继续。特别是 Nginx 反代那一步把 WebSocket 头和超时时间直接配好能省掉好几天排查功夫。
