RAILWISE-OS 部署手册

RAILWISE-OS 部署手册

AI语义标签: #私有化部署 #Docker #运维指南 #安装手册 #PostgreSQL #生产环境

1. 部署概述

RAILWISE-OS 支持两种部署模式：

部署模式	适用场景	数据控制	运维责任
SaaS 云端	快速上线、中小团队	RailWise 托管	RailWise 负责
私有化本地	数据安全要求、大型机构	客户自有	客户/RailWise 联合

本文档针对 私有化本地部署 提供完整指导。

2. 环境要求

2.1 硬件配置

单机部署（推荐 50 人以下）

组件	最低配置	推荐配置
CPU	8 核	16 核
内存	16 GB	32 GB
磁盘	200 GB SSD	500 GB SSD
网络	100 Mbps	1000 Mbps

集群部署（推荐 50-500 人）

节点	数量	CPU	内存	磁盘
应用节点	2-3	16 核	32 GB	100 GB
数据库节点	2（主从）	16 核	64 GB	500 GB SSD
缓存节点	2	8 核	16 GB	50 GB
对象存储	1-2	8 核	16 GB	2 TB

2.2 软件依赖

软件	版本要求	说明
Docker	24.0+	容器运行时
Docker Compose	2.20+	容器编排
PostgreSQL	14+	主数据库
Redis	7.0+	缓存与会话
Nginx	1.24+	反向代理（可选）
MinIO	最新版	对象存储（可选）

2.3 操作系统

系统	版本	状态
CentOS	7.9+ / Stream 8+	✅ 推荐
Ubuntu	20.04 LTS / 22.04 LTS	✅ 推荐
Debian	11+	✅ 支持
Rocky Linux	8+	✅ 支持
Windows Server	2019+	⚠️ 实验性支持

3. 部署前准备

3.1 获取部署包

联系 RailWise 技术支持获取部署包：

# 部署包结构
railwise-os-deployment-3.2.0/
├── docker-compose.yml          # 主编排文件
├── docker-compose.prod.yml     # 生产环境覆盖
├── .env.example                # 环境变量模板
├── config/
│   ├── nginx/
│   │   └── nginx.conf          # Nginx 配置
│   ├── postgresql/
│   │   └── init.sql            # 数据库初始化脚本
│   └── minio/
│       └── policies/           # MinIO 策略配置
├── scripts/
│   ├── init.sh                 # 初始化脚本
│   ├── backup.sh               # 备份脚本
│   └── upgrade.sh              # 升级脚本
└── images/                     # 离线镜像包（可选）

3.2 申请授权

私有化部署需要授权文件：

# 1. 获取服务器指纹
./scripts/get-fingerprint.sh
# 输出: SERVER_FINGERPRINT=abc123def456...

# 2. 将指纹发送给 RailWise 技术支持
# 3. 接收授权文件 license.key，放置到 config/ 目录

3.3 网络配置

端口	服务	说明
80	Nginx	HTTP 入口（可重定向到 HTTPS）
443	Nginx	HTTPS 入口
5432	PostgreSQL	数据库（仅内网访问）
6379	Redis	缓存（仅内网访问）
9000	MinIO	对象存储 API
9001	MinIO	对象存储控制台

4. 安装步骤

4.1 安装 Docker

# CentOS / Rocky Linux
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl start docker
sudo systemctl enable docker

# Ubuntu
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
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

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl start docker
sudo systemctl enable docker

4.2 配置环境变量

cp .env.example .env

# 编辑 .env 文件
vim .env

关键配置项：

# 基础配置
APP_NAME=RAILWISE-OS
APP_ENV=production
APP_URL=https://os.yourcompany.com

# 数据库配置
DB_HOST=postgresql
DB_PORT=5432
DB_NAME=railwise_os
DB_USER=railwise
DB_PASSWORD=your_strong_password_here

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

# 对象存储配置
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=railwise
MINIO_SECRET_KEY=your_minio_secret
MINIO_BUCKET=railwise-os

# 授权配置
LICENSE_PATH=/app/config/license.key

# 安全配置
JWT_SECRET=your_random_jwt_secret_min_32_chars
ENCRYPTION_KEY=your_32_byte_encryption_key

# 邮件配置（可选）
SMTP_HOST=smtp.yourcompany.com
SMTP_PORT=587
SMTP_USER=noreply@yourcompany.com
SMTP_PASSWORD=your_smtp_password

4.3 启动服务

# 1. 加载镜像
docker compose -f docker-compose.yml pull

# 2. 初始化数据库
docker compose -f docker-compose.yml run --rm api java -jar app.jar db:migrate

# 3. 启动所有服务
docker compose -f docker-compose.yml up -d

# 4. 检查状态
docker compose ps

4.4 验证部署

# 检查服务健康状态
curl -s http://localhost/api/health | jq

# 预期响应
{
  "status": "healthy",
  "version": "3.2.0",
  "services": {
    "database": "connected",
    "cache": "connected",
    "storage": "connected"
  }
}

5. 生产环境配置

5.1 Docker Compose 生产配置

docker-compose.prod.yml

version: "3.8"

services:
  web:
    image: railwise/os-web:3.2.0
    restart: always
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
    environment:
      - VITE_API_BASE_URL=/api

  api:
    image: railwise/os-api:3.2.0
    restart: always
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '4.0'
          memory: 4G
    environment:
      - SPRING_PROFILES_ACTIVE=production
      - DB_POOL_MAX_SIZE=50
      - DB_POOL_MIN_IDLE=10
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgresql:
    image: postgres:14-alpine
    restart: always
    deploy:
      resources:
        limits:
          cpus: '4.0'
          memory: 8G
    volumes:
      - pg_data:/var/lib/postgresql/data
      - ./config/postgresql/postgresql.conf:/etc/postgresql/postgresql.conf
    command: postgres -c config_file=/etc/postgresql/postgresql.conf

  redis:
    image: redis:7-alpine
    restart: always
    command: redis-server --requirepass ${REDIS_PASSWORD}
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
    volumes:
      - redis_data:/data

  nginx:
    image: nginx:1.24-alpine
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./config/nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./config/nginx/ssl:/etc/nginx/ssl
    depends_on:
      - web
      - api

volumes:
  pg_data:
  redis_data:

5.2 Nginx 配置

config/nginx/nginx.conf

upstream api_backend {
    least_conn;
    server api:8080 max_fails=3 fail_timeout=30s;
}

server {
    listen 80;
    server_name os.yourcompany.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name os.yourcompany.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 前端静态资源
    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
        expires 1d;
    }

    # API 代理
    location /api/ {
        proxy_pass http://api_backend/;
        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;
        proxy_connect_timeout 30s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }

    # 文件上传大小限制
    client_max_body_size 100M;
}

6. 数据库配置

6.1 PostgreSQL 优化

config/postgresql/postgresql.conf

# 内存配置（根据实际内存调整）
shared_buffers = 4GB
effective_cache_size = 12GB
work_mem = 64MB
maintenance_work_mem = 1GB

# 连接配置
max_connections = 200

# WAL 配置
wal_buffers = 64MB
min_wal_size = 2GB
max_wal_size = 8GB

# 查询优化
random_page_cost = 1.1
effective_io_concurrency = 200

# 日志配置
log_min_duration_statement = 1000
log_checkpoints = on
log_connections = on
log_disconnections = on

6.2 数据库备份

scripts/backup.sh

#!/bin/bash
BACKUP_DIR="/backup/railwise-os"
DATE=$(date +%Y%m%d_%H%M%S)
DB_NAME="railwise_os"
DB_USER="railwise"
RETENTION_DAYS=30

# 创建备份
mkdir -p $BACKUP_DIR
docker exec railwise-os-postgresql-1 pg_dump -U $DB_USER -Fc $DB_NAME > $BACKUP_DIR/railwise-os_${DATE}.dump

# 压缩备份
gzip $BACKUP_DIR/railwise-os_${DATE}.dump

# 清理旧备份
find $BACKUP_DIR -name "railwise-os_*.dump.gz" -mtime +$RETENTION_DAYS -delete

echo "备份完成: $BACKUP_DIR/railwise-os_${DATE}.dump.gz"

6.3 数据库恢复

#!/bin/bash
# 从备份恢复

BACKUP_FILE="$1"
DB_NAME="railwise_os"
DB_USER="railwise"

# 停止应用
docker compose stop api

# 恢复数据库
docker exec -i railwise-os-postgresql-1 pg_restore -U $DB_USER -d $DB_NAME --clean --if-exists < $BACKUP_FILE

# 启动应用
docker compose start api

echo "恢复完成"

7. 监控与日志

7.1 健康检查

# 系统健康检查脚本
#!/bin/bash

HEALTH_URL="http://localhost/api/health"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" $HEALTH_URL)

if [ "$STATUS" != "200" ]; then
    echo "系统异常，HTTP 状态码: $STATUS"
    # 发送告警（邮件/钉钉/企业微信）
    # ...
    exit 1
fi

echo "系统健康"

7.2 日志管理

# 查看应用日志
docker logs -f railwise-os-api-1

# 查看错误日志
docker logs railwise-os-api-1 2>&1 | grep ERROR

# 日志轮转配置（docker daemon.json）
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

8. 升级维护

8.1 升级步骤

scripts/upgrade.sh

#!/bin/bash
VERSION="3.3.0"

# 1. 备份数据
./scripts/backup.sh

# 2. 拉取新镜像
docker compose pull

# 3. 执行数据库迁移
docker compose run --rm api java -jar app.jar db:migrate

# 4. 滚动更新
docker compose up -d

# 5. 验证
curl -s http://localhost/api/health | jq

echo "升级至 $VERSION 完成"

8.2 回滚步骤

# 1. 停止当前版本
docker compose down

# 2. 恢复旧镜像
docker compose -f docker-compose.yml -f docker-compose.prev.yml up -d

# 3. 恢复数据库（如需）
# ./scripts/restore.sh backup_file.dump

9. 故障排查

问题	可能原因	解决方案
服务启动失败	端口冲突	检查端口占用，修改映射端口
数据库连接失败	密码错误	检查 .env 中 DB_PASSWORD
内存不足	配置过高	调整 JVM 堆内存大小
文件上传失败	大小限制	调整 client_max_body_size
授权验证失败	license 过期	联系 RailWise 更新授权
性能下降	数据库未优化	执行 VACUUM ANALYZE

10. 相关文档

• RAILWISE-OS 产品概述
• RAILWISE-OS 性能优化指南
• RAILWISE-OS 数据安全白皮书
• RAILWISE-OS 与 TSM 数据对接

---

文档版本: v3.2.0 | 最后更新: 2026-07-08