Node.js 需要 20 以上。 阿里云 ECS 镜像自带的 Node 往往版本偏低，先 node --version 确认，推荐用 nvm 装 22 LTS，不要用包管理器默认版本；npm 源可换 npmmirror 加速。
npm i -g tokentracker-cli
tokentracker status # 先看 hook 挂接状态，别跳过
tokentracker doctor # 深度健康检查
免安装体验版是 npx tokentracker-cli，首次运行会自动装 hook、同步数据并在 7680 端口打开 Dashboard。
用 systemd 常驻服务
Dashboard 默认跑前台，SSH 断开就没了，ECS 上应做成服务：
# /etc/systemd/system/tokentracker.service
[Unit]
Description=TokenTracker Dashboard
After=network.target
[Service]
Type=simple
User=devuser
Environment=PORT=7680
ExecStart=/home/devuser/.nvm/versions/node/v22.19.0/bin/tokentracker serve
Restart=on-failure
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now tokentracker
journalctl -u tokentracker -f # 端口冲突时会顺延，真实端口在这里
ExecStart 必须用绝对路径，systemd 不加载你的 shell 环境变量。
安全组与反向代理
第一条原则：ECS 安全组不要放行 7680。 Dashboard 是无鉴权的本地工具，直接开放等于把用量数据暴露在公网。安全组入方向只需放行 22（SSH，建议限来源 IP）、443（HTTPS）、80（跳转，可选），Nginx 反代到回环地址：
server {
listen 443 ssl http2;
server_name tracker.example.com;
location / {
proxy_pass http://127.0.0.1:7680;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# 热力图与按项目归因首屏数据较多，默认 60s 易被掐断
proxy_read_timeout 300s;
proxy_send_timeout 300s;
}
}
第二条原则：给它独立系统用户。 多开发者共用 root 时 ~/.tokentracker/ 会互相覆盖。
避坑要点
坑一：ECS 镜像自带的 Node 版本低于 20
现象：npm 直接报 engines.node 不满足。原因是包的 engines 声明为 >=20。解决方案是用 nvm 装 22 LTS。
坑二：安全组放行了 7680，看板裸奔在公网
现象：http://<公网IP>:7680 能直接打开。原因是 Dashboard 无鉴权。解决方案是安全组不放行 7680，改用 Nginx 反代到 443，鉴权交给反代层。
坑三：反代超时太短导致首屏加载失败
现象：反代配好后页面转圈或 504。原因是活跃度热力图与按项目归因在首屏拉取的数据量偏大，默认 60 秒读超时不够。解决方案是显式设置 proxy_read_timeout 300s。
坑四：systemd 里找不到 tokentracker 命令
现象：服务启动失败，报 command not found。原因是 ExecStart 写的是裸命令名，而 systemd 不加载 nvm 的 shell 环境。解决方案是填 nvm 版本目录下的绝对路径。
坑五：装完不重启宿主 CLI，hook 不生效
现象：包装好了但看板没数据。原因是 hook 只在宿主 CLI 启动时加载，且不补记历史会话。解决方案是重启目标 CLI 并开新会话；先跑 tokentracker status 能分清「没挂上」和「没数据」。
坑六：多人共用账号导致配置互相覆盖
现象：A 配好的 hook，B 一登录就失效。原因是 ~/.tokentracker/ 与各宿主配置都在用户目录下。解决方案是按开发者建独立系统用户，或用 CODEX_HOME、GEMINI_HOME、TOKENTRACKER_GROK_HOME 隔离数据目录。
坑七：CI 环境要关掉 Git 归因并改用非交互输出
现象：容器里出现多余 git 调用，流水线日志被 spinner 控制字符污染。原因是 Git 提交归因会在工作目录执行 git log，默认输出为交互式设计。解决方案是设 TOKENTRACKER_DISABLE_GIT_ATTRIBUTION=1，输出改用 status --light 或 status --json。
小结
部署要点五条：Node 用 nvm 装 22 LTS → npm i -g tokentracker-cli → 按独立系统用户隔离 → systemd 常驻且 ExecStart 用绝对路径 → 安全组只放行 22/443，Nginx 反代并给足读超时。
兼容性方面：站点结论是「自动检查通过」，但明确标注未经人工实机验证，原话是「能装不等于用着没问题」，且该包未声明 dsh 版本约束。最后验证时间 2026-09-17 04:55:32。
