RAILWISE-TSM 部署与安装指南

RAILWISE-TSM 部署与安装指南

1. 环境准备

1.1 硬件要求

根据部署模式选择相应硬件配置：

部署模式	CPU	内存	存储	网络
单机版	8 核	16 GB	200 GB SSD	千兆局域网
标准版	16 核	32 GB	500 GB SSD	公网带宽 ≥ 50 Mbps
集群版	32 核+	64 GB+	1 TB SSD + NAS	专线/双链路

1.2 软件依赖

组件	版本要求	用途
Docker	≥ 24.0	容器化运行
Docker Compose	≥ 2.20	多服务编排
Git	≥ 2.40	代码拉取
Node.js	≥ 18.17 (可选)	源码构建
Bun	≥ 1.0 (可选)	源码构建

1.3 操作系统支持

• 推荐: Ubuntu 22.04 LTS / CentOS 8 Stream / Debian 12
• 支持: Windows Server 2022 (WSL2 + Docker Desktop)
• 最低: Windows 10 Pro (WSL2) — 仅适用于单机版演示

---

2. 安装步骤

2.1 安装 Docker 与 Docker Compose

提示

建议配置国内 Docker 镜像源，以提升镜像拉取速度。

Ubuntu/Debian:

# 更新包索引
sudo apt-get update

# 安装依赖
sudo apt-get install -y ca-certificates curl gnupg

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加仓库
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 验证安装
docker --version
docker compose version

CentOS/RHEL:

# 安装依赖
sudo yum install -y yum-utils

# 添加仓库
sudo yum-config-manager --add-repo \
  https://download.docker.com/linux/centos/docker-ce.repo

# 安装 Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动服务
sudo systemctl start docker
sudo systemctl enable docker

2.2 下载 TSM 部署包

# 创建工作目录
mkdir -p /opt/railwise-tsm && cd /opt/railwise-tsm

# 克隆部署仓库（请联系技术支持获取仓库地址与访问权限）
git clone https://git.railwise.cn/tsm/deployment.git .

# 目录结构说明
# ├── docker-compose.yml      # 主编排文件
# ├── .env.example            # 环境变量模板
# ├── nginx/                  # Nginx 配置
# ├── init-scripts/           # 数据库初始化脚本
# └── data/                   # 数据持久化目录

2.3 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件（推荐使用 vim 或 nano）
vim .env

.env 文件关键配置项：

# ============================================
# TSM 基础配置
# ============================================
APP_NAME=RAILWISE-TSM
APP_ENV=production
APP_VERSION=2.5.0

# 服务器域名或 IP
SERVER_HOST=tsm.railwise.cn
SERVER_PORT=3000

# ============================================
# 数据库配置
# ============================================
DB_HOST=postgres
DB_PORT=5432
DB_NAME=tsm_production
DB_USER=tsm_admin
DB_PASSWORD=your_secure_password_here

# TimescaleDB 扩展（与 PostgreSQL 共用）
TSDB_ENABLED=true

# ============================================
# Redis 配置
# ============================================
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password_here

# ============================================
# 存储配置
# ============================================
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=tsm_minio_access
MINIO_SECRET_KEY=your_minio_secret_here
MINIO_BUCKET=tsm-data

# ============================================
# 安全与认证
# ============================================
JWT_SECRET=your_jwt_secret_key_here
JWT_EXPIRES_IN=7d

# 初始管理员账号
ADMIN_USERNAME=admin
ADMIN_PASSWORD=change_me_immediately
ADMIN_EMAIL=admin@railwise.cn

# ============================================
# 邮件服务（用于告警通知）
# ============================================
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=alerts@railwise.cn
SMTP_PASS=your_smtp_password

• 生产环境务必修改所有默认密码
• JWT_SECRET 建议使用 openssl rand -base64 32 生成
• 数据库密码长度应 ≥ 16 位，包含大小写字母、数字和特殊字符
• 切勿将 .env 文件提交到 Git 仓库

2.4 启动服务

# 拉取最新镜像
docker compose pull

# 启动所有服务（后台运行）
docker compose up -d

# 查看服务状态
docker compose ps

# 预期输出：
# NAME                   IMAGE                           STATUS
# tsm-web                railwise/tsm-web:2.5.0          Up 30 seconds
# tsm-api                railwise/tsm-api:2.5.0          Up 30 seconds
# tsm-compute            railwise/tsm-compute:2.5.0      Up 30 seconds
# postgres               timescale/timescaledb:2.11-pg15   Up 30 seconds
# redis                  redis:7-alpine                    Up 30 seconds
# minio                  minio/minio:RELEASE.2024-...    Up 30 seconds
# nginx                  nginx:alpine                    Up 30 seconds

2.5 初始化数据库

# 执行数据库迁移与种子数据
docker compose exec tsm-api npx prisma migrate deploy
docker compose exec tsm-api npx prisma db seed

# 验证数据库连接
docker compose exec postgres psql -U tsm_admin -d tsm_production -c "\dt"

2.6 访问系统

Web 界面: http://<SERVER_HOST>:3000
管理员登录: admin / change_me_immediately
MinIO 控制台: http://<SERVER_HOST>:9001

首次登录后，系统会强制要求修改管理员密码。请设置高强度密码并妥善保存。

---

3. 配置检查清单

检查项	命令/方法	预期结果
Docker 运行状态	docker info	无错误信息
容器全部启动	docker compose ps	所有容器状态为 Up
数据库连接	docker compose exec tsm-api npx prisma db pull	成功连接
Redis 连接	docker compose exec redis redis-cli ping	返回 PONG
MinIO 服务	curl http://localhost:9000/minio/health/live	HTTP 200
Web 服务	curl http://localhost:3000/api/health	JSON 健康状态
端口占用	netstat -tlnp | grep -E '3000|5432|6379|9000'	对应端口在监听

---

4. 常见问题排查

4.1 容器启动失败

现象: docker compose up -d 后部分容器状态为 Restarting 或 Exit

排查步骤:

# 查看容器日志
docker compose logs --tail=100 tsm-api

# 常见原因与解决方案：
# 1. 端口冲突 → 修改 .env 中的端口映射
# 2. 内存不足 → 增加服务器内存或调整 JVM/Node 内存限制
# 3. 数据库连接失败 → 检查 DB_HOST/DB_PASSWORD 配置
# 4. 权限不足 → 确保 data/ 目录有写权限

4.2 数据库连接超时

# 检查 PostgreSQL 是否接受连接
docker compose exec postgres pg_isready -U tsm_admin

# 若未就绪，查看 PostgreSQL 日志
docker compose logs --tail=50 postgres

# 常见修复：
# 1. 增加连接超时时间：在 .env 中设置 DB_CONNECTION_TIMEOUT=30000
# 2. 检查防火墙是否放行 5432 端口

4.3 前端无法访问

# 检查 Nginx 配置
docker compose exec nginx nginx -t

# 查看 Nginx 访问日志
docker compose logs --tail=50 nginx

# 常见修复：
# 1. 确保 SERVER_HOST 配置正确
# 2. 检查防火墙/安全组是否放行 3000 端口
# 3. 确认 DNS 解析正确（如使用域名）

4.4 全站仪设备无法连接

详见 全站仪配置与连接设置 中的网络配置章节。

---

5. 升级与维护

5.1 版本升级

cd /opt/railwise-tsm

# 拉取最新配置
git pull origin main

# 更新镜像
docker compose pull

# 执行数据库迁移
docker compose exec tsm-api npx prisma migrate deploy

# 重启服务
docker compose up -d

5.2 数据备份

# 数据库备份
docker compose exec postgres pg_dump -U tsm_admin tsm_production > \
  /backup/tsm_$(date +%Y%m%d_%H%M%S).sql

# 文件存储备份
docker compose exec minio mc alias set local http://localhost:9000 \
  $MINIO_ACCESS_KEY $MINIO_SECRET_KEY
docker compose exec minio mc mirror local/tsm-data /backup/minio/

5.3 日志管理

# 查看实时日志
docker compose logs -f tsm-api

# 限制日志大小（docker-compose.yml 中配置）
# logging:
#   driver: "json-file"
#   options:
#     max-size: "100m"
#     max-file: "5"

---

6. 相关文档

文档	路径	说明
TSM 平台概览	./tsm-overview.md	产品介绍与系统架构
全站仪配置与连接设置	./tsm-station-config.md	设备接入与通信配置
监测项目创建与管理	./tsm-monitoring-project.md	项目生命周期管理
数据采集与自动化流程	./tsm-data-acquisition.md	采集任务与调度

---

7. 元数据标签

# AI 语义标签
semantic_tags:
  - deployment_guide
  - docker_compose
  - installation
  - system_administration
  - postgresql
  - timescaledb
  - redis
  - minio
  - production_setup
  - troubleshooting

---

📌 版本记录

• v1.0.0 (2025-07-08) — 初始版本，涵盖单机/标准版部署流程

如需技术支持，请联系 RailWise 客户服务团队：support@railwise.cn