产品文档已发布

RAILWISE-TSM 系统管理与运维指南

TSM平台系统管理、用户权限、备份恢复、性能监控与日常运维的完整操作手册

复核 2026-07-09入门公开可引用RailWise 技术团队

产品文档

RAILWISE-TSM 系统管理与运维指南

适用版本: TSM v3.2+ 阅读对象: 系统管理员、运维工程师、IT技术支持 部署方式: Docker Compose / Kubernetes / 裸机部署

1. 概述

RAILWISE-TSM 采用云原生架构设计，支持多种部署方式。本文档面向系统管理员，涵盖用户权限管理、系统配置、数据备份、性能监控、故障排查等运维全生命周期操作。

1.1 系统架构概览

┌──────────────────────────────────────────────────────────────┐
│                         接入层                                │
│    Nginx (SSL/负载均衡) / Traefik (K8s Ingress)             │
└──────────────────────────┬───────────────────────────────────┘
                           │
┌──────────────────────────▼───────────────────────────────────┐
│                      应用服务层                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │  Web前端  │ │  API网关  │ │ 计算服务 │ │ 消息服务 │       │
│  │ Next.js  │ │  NestJS  │ │  Rust   │ │  Redis  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└──────────────────────────┬───────────────────────────────────┘
                           │
┌──────────────────────────▼───────────────────────────────────┐
│                      数据存储层                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │PostgreSQL│ │  TimescaleDB  │ │  MinIO  │ │  ClickHouse│ │
│  │ 业务数据  │ │  时序数据     │ │ 文件存储│ │  分析引擎  │ │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└──────────────────────────────────────────────────────────────┘

2. 部署与安装

2.1 Docker Compose 部署（推荐）

# 1. 下载部署包
wget https://releases.railwise.cn/tsm/3.2.0/tsm-docker-compose.tar.gz
tar -xzf tsm-docker-compose.tar.gz
cd tsm-docker-compose

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置数据库密码、域名等

# 3. 启动服务
docker-compose up -d

# 4. 初始化数据库
docker-compose exec api npx prisma migrate deploy
docker-compose exec api npx prisma db seed

# 5. 验证状态
docker-compose ps

2.2 环境变量配置

# .env 核心配置项
# ─────────────────────────────────────────

# 基础配置
TSM_VERSION=3.2.0
NODE_ENV=production
TZ=Asia/Shanghai

# 数据库
DATABASE_URL=postgresql://tsm_user:${DB_PASSWORD}@postgres:5432/tsm_db
REDIS_URL=redis://redis:6379

# 存储
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=${MINIO_ACCESS_KEY}
MINIO_SECRET_KEY=${MINIO_SECRET_KEY}
MINIO_BUCKET=tsm-files

# 安全
JWT_SECRET=${JWT_SECRET}
API_KEY_SALT=${API_KEY_SALT}
ENCRYPTION_KEY=${ENCRYPTION_KEY}

# 邮件/短信（用于报警通知）
SMTP_HOST=smtp.railwise.cn
SMTP_PORT=587
SMTP_USER=${SMTP_USER}
SMTP_PASS=${SMTP_PASS}
SMS_ACCESS_KEY=${SMS_ACCESS_KEY}
SMS_SECRET=${SMS_SECRET}

# 性能
MAX_WORKERS=4
WORKER_TIMEOUT=300

所有密码和密钥必须使用 openssl rand -base64 32 生成
生产环境必须配置 HTTPS（Let’s Encrypt 或商业证书）
数据库端口不映射至宿主机，仅通过 Docker 网络访问
定期轮换 JWT_SECRET 和 API 密钥

2.3 Kubernetes 部署

# 简化版 deployment 示例
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tsm-api
  namespace: railwise-tsm
spec:
  replicas: 3
  selector:
    matchLabels:
      app: tsm-api
  template:
    metadata:
      labels:
        app: tsm-api
    spec:
      containers:
        - name: api
          image: registry.railwise.cn/tsm/api:3.2.0
          ports:
            - containerPort: 3000
          envFrom:
            - configMapRef:
                name: tsm-config
            - secretRef:
                name: tsm-secrets
          resources:
            requests:
              memory: "512Mi"
              cpu: "500m"
            limits:
              memory: "2Gi"
              cpu: "2000m"
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 5

3. 用户与权限管理

3.1 角色体系

角色	权限范围	适用人员
系统管理员	全部功能 + 系统配置	IT运维
组织管理员	组织内所有项目	公司技术负责人
项目经理	指定项目的全部管理	项目负责人
技术工程师	数据查看 + 配置修改	监测工程师
现场人员	移动端巡查 + 数据录入	现场巡查员
只读用户	查看报表和图表	业主/监理
API 应用	指定接口的调用权限	第三方系统

3.2 创建用户与分配角色

# 通过 CLI 创建用户
railwise-tsm admin user create \
  --email "engineer@railwise.cn" \
  --name "张工" \
  --phone "138****5678" \
  --role "technical_engineer" \
  --project "proj-2024-nb-001"

# 批量导入用户
railwise-tsm admin user import \
  --file ./users.csv \
  --project "proj-2024-nb-001"

3.3 权限矩阵

                    ┌─────────┬─────────┬─────────┬─────────┬─────────┐
                    │系统管理 │组织管理 │项目经理 │技术工程师│现场人员 │
├───────────────────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ 系统配置          │   ✅    │   ❌    │   ❌    │   ❌    │   ❌    │
│ 用户管理          │   ✅    │   ✅    │   ❌    │   ❌    │   ❌    │
│ 项目创建/删除     │   ✅    │   ✅    │   ❌    │   ❌    │   ❌    │
│ 测点配置          │   ✅    │   ✅    │   ✅    │   ✅    │   ❌    │
│ 阈值设置          │   ✅    │   ✅    │   ✅    │   ✅    │   ❌    │
│ 仪器管理          │   ✅    │   ✅    │   ✅    │   ✅    │   ❌    │
│ 数据查看          │   ✅    │   ✅    │   ✅    │   ✅    │   ✅    │
│ 手动数据录入      │   ✅    │   ✅    │   ✅    │   ✅    │   ✅    │
│ 报告生成          │   ✅    │   ✅    │   ✅    │   ✅    │   ❌    │
│ 报警确认/消警     │   ✅    │   ✅    │   ✅    │   ✅    │   ❌    │
│ 工作流配置        │   ✅    │   ✅    │   ✅    │   ❌    │   ❌    │
│ 数据导出          │   ✅    │   ✅    │   ✅    │   ✅    │   ❌    │
│ API密钥管理       │   ✅    │   ✅    │   ❌    │   ❌    │   ❌    │
│ 系统日志查看      │   ✅    │   ✅    │   ❌    │   ❌    │   ❌    │
└───────────────────┴─────────┴─────────┴─────────┴─────────┴─────────┘

3.4 单点登录（SSO）配置

支持企业微信、钉钉、飞书、LDAP/AD 对接：

sso:
  providers:
    - name: "dingtalk"
      type: "oauth2"
      client_id: "${DINGTALK_CLIENT_ID}"
      client_secret: "${DINGTALK_CLIENT_SECRET}"
      redirect_uri: "https://tsm.railwise.cn/auth/callback/dingtalk"
      scopes: ["openid", "unionid"]

    - name: "ldap"
      type: "ldap"
      host: "ldap.company.local"
      port: 636
      ssl: true
      base_dn: "dc=company,dc=local"
      bind_dn: "cn=tsm,dc=company,dc=local"
      bind_password: "${LDAP_PASSWORD}"
      user_filter: "(objectClass=person)"
      group_mappings:
        "cn=tsm-admins,ou=groups,dc=company,dc=local": "system_admin"
        "cn=tsm-engineers,ou=groups,dc=company,dc=local": "technical_engineer"

4. 数据备份与恢复

4.1 备份策略

数据类型	备份频率	保留周期	存储位置
PostgreSQL 业务库	每日 02:00	30天	本地 + 异地
TimescaleDB 时序数据	每日 02:00	90天	本地 + 异地
MinIO 文件存储	实时同步	永久	异地对象存储
Redis 缓存	每小时	7天	本地
配置文件	变更时	永久	Git 仓库

4.2 自动备份脚本

#!/bin/bash
BACKUP_DIR="/backup/tsm/$(date +%Y%m%d)"
RETENTION_DAYS=30
mkdir -p "$BACKUP_DIR"

# 1. PostgreSQL 备份
docker-compose exec -T postgres pg_dump \
  -U tsm_user -d tsm_db \
  | gzip > "$BACKUP_DIR/postgres.sql.gz"

# 2. TimescaleDB 备份（超表需特殊处理）
docker-compose exec -T timescaledb pg_dump \
  -U tsm_user -d tsm_timeseries \
  --format=custom \
  | gzip > "$BACKUP_DIR/timescale.dump.gz"

# 3. Redis 备份
docker-compose exec redis redis-cli BGSAVE
sleep 5
cp /var/lib/redis/dump.rdb "$BACKUP_DIR/redis.rdb"

# 4. MinIO 数据同步至异地
mc mirror --remove --overwrite \
  local/tsm-files \
  remote/backup-bucket/tsm-files

# 5. 清理旧备份
find /backup/tsm -type d -mtime +$RETENTION_DAYS -exec rm -rf {} \;

# 6. 发送备份报告
railwise-tsm admin notify \
  --channel email \
  --to "admin@railwise.cn" \
  --subject "TSM 备份完成 $(date +%Y-%m-%d)" \
  --body "备份路径: $BACKUP_DIR"

4.3 数据恢复流程

# 场景：恢复 PostgreSQL 至指定时间点

# 1. 停止相关服务
docker-compose stop api worker

# 2. 恢复数据库
gunzip -c /backup/tsm/20250115/postgres.sql.gz | \
  docker-compose exec -T postgres psql -U tsm_user -d tsm_db

# 3. 验证数据完整性
docker-compose exec api npx prisma validate

# 4. 重启服务
docker-compose start api worker

# 5. 验证业务功能
railwise-tsm health check --full

5. 性能监控

5.1 内置监控指标

TSM 内置 Prometheus 指标端点：/metrics

指标名	类型	说明
`tsm_api_requests_total`	Counter	API 请求总数
`tsm_api_request_duration_seconds`	Histogram	API 响应时间
`tsm_active_workers`	Gauge	当前活跃工作进程数
`tsm_queue_depth`	Gauge	任务队列深度
`tsm_db_connections`	Gauge	数据库连接数
`tsm_instrument_online`	Gauge	在线仪器数量
`tsm_alert_count`	Gauge	当前报警数量

5.2 Grafana 监控面板

services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana-dashboards:/etc/grafana/provisioning/dashboards
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}

5.3 关键性能阈值

指标	警告阈值	严重阈值	处理建议
API 平均响应时间	> 500ms	> 2s	增加实例 / 优化查询
数据库连接数	> 80%	> 95%	增加连接池 / 优化慢查询
内存使用率	> 70%	> 90%	扩容内存 / 优化缓存
磁盘使用率	> 80%	> 90%	扩容存储 / 清理日志
队列深度	> 100	> 500	增加 Worker / 检查阻塞任务
仪器离线率	> 10%	> 30%	检查网络 / 仪器故障排查

6. 日志管理

6.1 日志级别配置

logging:
  level: "info"  # debug / info / warn / error
  format: "json" # json / text
  outputs:
    - type: "stdout"
    - type: "file"
      path: "/var/log/tsm/app.log"
      max_size: "100MB"
      max_backups: 10
      max_age: 30
    - type: "loki"
      url: "http://loki:3100"
      labels:
        service: "tsm-api"
        environment: "production"

6.2 日志审计

系统自动记录以下操作日志：

操作类型	记录内容	保留周期
用户登录	时间、IP、设备、结果	1年
数据修改	操作用户、修改字段、前后值	3年
配置变更	变更人、变更内容、审批人	永久
报警处理	确认人、确认时间、处理意见	3年
数据导出	导出用户、时间、数据范围	1年
API 调用	应用ID、接口、调用量	90天

7. 系统升级

7.1 升级前检查清单

# 升级前执行
railwise-tsm admin pre-upgrade-check

# 检查项：
# □ 数据库备份已完成
# □ 当前版本无未处理报警
# □ 所有工作流已暂停或完成
# □ 磁盘空间充足（> 20GB 可用）
# □ 配置文件已版本控制
# □ 回滚方案已确认

7.2 滚动升级（Docker Compose）

# 1. 拉取新版本
docker-compose pull

# 2. 数据库迁移
docker-compose run --rm api npx prisma migrate deploy

# 3. 滚动更新服务
docker-compose up -d --no-deps api
docker-compose up -d --no-deps worker

# 4. 验证健康检查
curl -f http://localhost:3000/health || exit 1

# 5. 清理旧镜像
docker image prune -f

如升级后发现问题，立即执行：

docker-compose down
git checkout v3.1.x  # 回退至上一版本标签
docker-compose up -d
# 如需回滚数据库，使用升级前的备份

8. 故障排查手册

8.1 常见问题速查

现象	诊断命令	常见原因	解决方案
服务无法启动	`docker-compose logs api`	数据库连接失败	检查 DATABASE_URL
API 响应慢	`railwise-tsm perf analyze`	慢查询	优化索引 / 增加缓存
仪器批量离线	`railwise-tsm instrument status`	网络中断	检查交换机 / 重启网关
报警未推送	`railwise-tsm notify test`	短信配额耗尽	充值 / 切换通道
磁盘爆满	`df -h`	日志未轮转	配置 logrotate
内存泄漏	`docker stats`	缓存未清理	重启服务 / 调整缓存策略

8.2 紧急恢复流程

# 场景：数据库主节点故障

# 1. 提升备库为主库
docker-compose exec postgres-replica pg_ctl promote

# 2. 更新应用连接指向新主库
# 修改 .env 中 DATABASE_URL，指向备库地址

# 3. 重启应用服务
docker-compose restart api worker

# 4. 启动新备库同步
docker-compose up -d postgres-new-replica

9. 安全合规

9.1 等保要求对照

等保等级	要求项	TSM 实现
三级	身份鉴别	多因素认证 + SSO
三级	访问控制	RBAC + 字段级权限
三级	安全审计	全量操作日志
三级	数据完整性	传输TLS + 存储加密
三级	数据备份	自动备份 + 异地容灾
三级	入侵防范	WAF + 防暴力破解

9.2 数据加密

数据类型	加密方式	密钥管理
传输数据	TLS 1.3	Let’s Encrypt / 商业证书
数据库	AES-256	云KMS / HashiCorp Vault
备份文件	AES-256-GCM	独立密钥，离线存储
API 密钥	bcrypt + HMAC	数据库哈希存储

RAILWISE-TSM 系统管理与运维指南

RAILWISE-TSM 系统管理与运维指南

1. 概述

1.1 系统架构概览

2. 部署与安装

2.1 Docker Compose 部署（推荐）

2.2 环境变量配置

2.3 Kubernetes 部署

3. 用户与权限管理

3.1 角色体系

3.2 创建用户与分配角色

3.3 权限矩阵

3.4 单点登录（SSO）配置

4. 数据备份与恢复

4.1 备份策略

4.2 自动备份脚本

4.3 数据恢复流程

5. 性能监控

5.1 内置监控指标

5.2 Grafana 监控面板

5.3 关键性能阈值

6. 日志管理

6.1 日志级别配置

6.2 日志审计

7. 系统升级

7.1 升级前检查清单

7.2 滚动升级（Docker Compose）

8. 故障排查手册

8.1 常见问题速查

8.2 紧急恢复流程

9. 安全合规

9.1 等保要求对照

9.2 数据加密

相关文档