Rustrak生产部署清单:从HTTPS反向代理到PostgreSQL,放心上线完整指南
Rustrak生产部署清单:从HTTPS反向代理到PostgreSQL,放心上线完整指南
Rustrak 是一款超轻量的自托管错误追踪(Error Tracking)服务器,兼容所有 Sentry SDK,一个容器同时提供 API 和仪表盘。本文是一份 Rustrak 生产部署清单:从生成安全密钥、配置 HTTPS 反向代理,到接入 PostgreSQL、设置限流与备份,最后用一张自检清单逐项打勾——照着走一遍,就能放心把错误监控搬上生产环境。
💡 官方生产部署指南原文:apps/docs/content/configuration/production.mdx 完整环境变量参考:apps/docs/content/configuration/environment.mdx
📋 部署前先看:SQLite 还是 PostgreSQL?
Rustrak 提供两种数据库镜像,仪表盘都内置,区别只在数据存哪里:
| 对比项 | SQLite(latest 镜像) |
PostgreSQL(postgres 镜像) |
|---|---|---|
| 额外服务 | 无,开箱即用 | 需要一个 PostgreSQL 服务 |
| 并发写入 | 单写者 | 完全并发 |
| 适合场景 | 个人项目、小团队,约 1000 事件/小时以内 | 生产环境、团队、高流量 |
| 备份方式 | 整卷打包或 sqlite3 .backup |
pg_dump |
👉 团队级生产部署建议直接选 PostgreSQL。仓库自带的编排文件是 docker-compose.postgres.yml,SQLite 版本则是 docker-compose.yml。
🔐 第 1 步:生成安全密钥
上线前先生成两个互相独立的密钥,不要复用同一个:
# 会话密钥(64 位,HTTPS 下必填)
openssl rand -hex 32
# 数据库密码(不要用它当会话密钥)
openssl rand -base64 24
两个关键变量:
SESSION_SECRET_KEY:用于签名会话 Cookie,跨重启必须保持一致,否则所有用户会被强制登出。启用SSL_PROXY=true时它是必填项,长度不足 64 位会直接拒绝启动。CREATE_SUPERUSER:格式为email:password,只在数据库还没有任何用户时创建首个管理员,之后被忽略。
🔒 第 2 步:用 HTTPS 反向代理终结 SSL
生产环境的正确姿势是:容器不暴露主机端口,让 nginx(或 Caddy、Traefik)终结 SSL 后转发到容器的 8080 端口。
修改 docker-compose.yml
- 删除
ports:配置块; - 把容器接入代理所在的 Docker 网络。
services:
server:
image: rustrak/rustrak-server:latest
environment:
- SESSION_SECRET_KEY=${SESSION_SECRET_KEY}
- SSL_PROXY=true
- PUBLIC_URL=https://rustrak.example.com
volumes:
- rustrak_data:/data
networks: [proxy]
restart: unless-stopped
networks:
proxy:
external: true
两个最容易踩的坑:
SSL_PROXY=true:告诉服务"我在 HTTPS 代理后面"。它会让 Cookie 只通过 HTTPS 发送(Secure标志),并让会话跨重启保持有效。PUBLIC_URL必须设置:它会被写进每个项目的 DSN。不设置的话,仪表盘里显示的 DSN 会带着0.0.0.0,你的 SDK 根本连不上。
nginx 配置参考
server {
listen 443 ssl http2;
server_name rustrak.example.com;
location / {
proxy_pass http://server:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
因为"一个容器同时回答仪表盘和 API",只需要一个上游、一条路由规则,Caddy 四行、Traefik 两条标签也能搞定。
进阶:双域名隔离。SDK 上报的 POST /api/<project>/envelope/ 是公网无认证流量,可以单独用一个域名(如 ingest.example.com),在代理层对它单独限流或做防火墙规则,而不影响团队登录的域名。此时 PUBLIC_URL 设为上报域名,DASHBOARD_URL 设为团队打开的仪表盘域名。
🐘 第 3 步:接入 PostgreSQL
仓库的 docker-compose.postgres.yml 已经做好两件事:postgres:16-alpine 带健康检查,server 容器 depends_on: service_healthy 保证数据库就绪后才启动。
生产要点:
- 镜像换成
rustrak/rustrak-server:postgres; DATABASE_URL建议强制 SSL:
DATABASE_URL=postgres://rustrak:密码@postgres:5432/rustrak?sslmode=require
- 用强密码、限制数据库的网络访问范围;
- 流量较大时可调连接池:
DATABASE_MAX_CONNECTIONS(默认 10)、DATABASE_MIN_CONNECTIONS(默认 1)。
⚠️ 注意:上传的 source maps 不在数据库里,而是存在 server 容器的 /data 卷(rustrak_data)中,备份时两个卷都要覆盖。
⚡ 第 4 步:限流、健康检查与重启策略
限流——默认值(全局 6 万事件/分钟、每项目 2 万/分钟)对绝大多数部署足够,小机器可适当调低:
MAX_EVENTS_PER_MINUTE=1000
MAX_EVENTS_PER_HOUR=20000
健康检查——用 Uptime Kuma、Prometheus 等监控这两个端点:
GET /health # 存活(Liveness)
GET /health/ready # 就绪(Readiness)
重启策略——确保 restart: unless-stopped,进程崩溃自动拉起。
资源参考:
| 组件 | CPU | 内存 |
|---|---|---|
| Server(API + 仪表盘) | 1 vCPU | 256 MB |
| PostgreSQL | 1 vCPU | 512 MB |
仪表盘是纯静态文件,整个进程空闲内存低于 100 MB。
另外两个建议:
- 匿名遥测:默认每 6 小时上报一次版本号、平台与健康计数(不含任何数据),介意则设置
RUSTRAK_TELEMETRY=off,请有意识地做这个决定; - Prometheus 指标:
RUSTRAK_METRICS=on会开启无认证的/metrics,开启前务必在反向代理层限制其访问来源。
💾 第 5 步:制定备份方案
自托管实例没有"别人会帮你发现磁盘满了",备份策略必须写进例行操作:
PostgreSQL:
pg_dump -h localhost -U rustrak rustrak > backup_$(date +%Y%m%d).sql
SQLite(服务停机的整卷备份):
docker compose stop server
docker run --rm -v <目录>_rustrak_data:/data -v "$PWD":/backup alpine \
tar czf /backup/rustrak-$(date +%Y%m%d).tgz -C /data .
docker compose start server
也可以不停机,用 SQLite 在线备份 API 只备份数据库(不含 source maps):sqlite3 /data/rustrak.db ".backup ..."。不要用 cp 直接拷文件,可能拷到写了一半的状态。
✅ 上线前自检清单
逐项打勾,全部通过再对外公布 DSN:
- [ ] 已生成安全密钥(
SESSION_SECRET_KEY) - [ ] HTTPS 反向代理已配置
- [ ] 已设置
SSL_PROXY=true - [ ]
PUBLIC_URL指向公网域名(而不是0.0.0.0) - [ ] 已挂载命名卷到
/data - [ ] 遥测开关状态已确认(开或
RUSTRAK_TELEMETRY=off) - [ ] 数据库 SSL 已启用
- [ ] 限流参数已按硬件设置
- [ ] 健康检查已接入监控
- [ ] 备份策略已落地并演练过恢复
- [ ] 已配置
restart: unless-stopped - [ ] 管理员账号已创建
- [ ] 已发送一条测试事件并确认收到
- [ ] 仪表盘中的 DSN 域名正确
🎉 小结
Rustrak 的生产部署核心就四件事:HTTPS 反向代理 + 两个密钥、SSL_PROXY/PUBLIC_URL 两个变量、PostgreSQL 强制 SSL、可恢复的备份。它没有独立的 dashboard 容器、没有消息队列、没有要额外调通的内部地址,1 vCPU 就能跑起来。完整细节可对照官方文档:生产清单、数据库选型、安装指南,以及独立仪表盘镜像的 nginx 配置模板。
清单全部打勾后,把仪表盘里的 DSN 交给团队——你的 Sentry SDK 只需改一个字符串,就能把错误事件稳稳送到自己的服务器上。