部署指南

将 RTKHUB 部署到生产环境。

准备工作

下载 RTKHUB 发布包或准备 Docker 镜像
准备配置文件
准备服务器环境

选择部署方式

安全提醒

不要将 RTKHUB 的 5426 端口直接暴露到公网。生产环境务必使用反向代理（Nginx/Cloudflare Tunnel）并启用 HTTPS。详见安全与权限。

方式	适合场景	说明
Windows 单机	本机试运行、Windows Server 生产部署	使用 Release x64 包，配合 NSSM 或计划任务管理
Docker	云服务器、标准化交付、测试环境	推荐挂载 `conf/`、`database/`、`log/`、`result/`
反向代理	需要 HTTPS 或统一域名入口	使用 Nginx、Cloudflare Tunnel 或 VPN，不建议直接公网暴露 `5426`

Docker 详细配置见 Docker 部署。

本地部署

1. 解压文件

# 解压到目标目录
Expand-Archive rtkhub-vX.Y.Z.zip D:\rtkhub\
cd D:\rtkhub

2. 创建配置

参考配置指南

3. 启动服务

.\rtkhub.exe -s -k conf\rtkhub.list

Windows 服务

创建服务

# 使用 NSSM
nssm install RTKHUB "D:\rtkhub\rtkhub.exe"
nssm set RTKHUB AppParameters "-s -k conf\rtkhub.list"
nssm set RTKHUB AppDirectory "D:\rtkhub"
nssm set RTKHUB Start SERVICE_AUTO_START

# 启动服务
nssm start RTKHUB

管理服务

# 停止
nssm stop RTKHUB

# 重启
nssm restart RTKHUB

# 删除
nssm remove RTKHUB confirm

Nginx 反向代理

配置 HTTPS

server {
    listen 443 ssl;
    server_name rtkhub.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://127.0.0.1:5426;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name rtkhub.example.com;
    return 301 https://$server_name$request_uri;
}

Docker 部署

如果你需要用容器统一部署，优先阅读 Docker 部署。核心原则是：

只把镜像当作运行环境，不把配置和结果文件写入镜像层。
将 conf/、database/、log/、result/ 挂载到宿主机。
当前主项目提供 Dockerfile，可本地构建 rtkhub:latest；未来正式镜像发布后再替换 image。
生产环境固定镜像版本，并保留旧镜像用于回滚。
串口或 USB 设备需要额外映射和权限验证。

最小 Compose 形态：

services:
  rtkhub:
    build:
      context: .
      dockerfile: Dockerfile
    image: rtkhub:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:5426:5426"
    volumes:
      - ./conf:/app/conf
      - ./database:/app/database
      - ./log:/app/log
      - ./result:/app/result

防火墙配置

Windows 防火墙

New-NetFirewallRule -DisplayName "RTKHUB" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 5426 `
  -Action Allow

Linux iptables

sudo iptables -A INPUT -p tcp --dport 5426 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4

自动备份

备份脚本

# backup.ps1
$date = Get-Date -Format "yyyyMMdd"
$backupPath = "E:\backups\rtkhub_$date"

# 停止服务
nssm stop RTKHUB

# 备份
Copy-Item D:\rtkhub\conf $backupPath\conf -Recurse
Copy-Item D:\rtkhub\database $backupPath\database -Recurse

# 启动服务
nssm start RTKHUB

# 压缩
Compress-Archive $backupPath "$backupPath.zip"
Remove-Item $backupPath -Recurse

定时任务

# 每天凌晨 2 点备份
$action = New-ScheduledTaskAction -Execute "PowerShell.exe" `
  -Argument "-File D:\rtkhub\backup.ps1"
$trigger = New-ScheduledTaskTrigger -Daily -At 2AM
Register-ScheduledTask -TaskName "RTKHUB Backup" `
  -Action $action -Trigger $trigger

监控告警

进程监控

# monitor.ps1
if (!(Get-Process rtkhub -ErrorAction SilentlyContinue)) {
    # 发送告警邮件
    Send-MailMessage -To "admin@example.com" `
      -Subject "RTKHUB服务停止" `
      -Body "RTKHUB服务异常停止，已自动重启" `
      -SmtpServer "smtp.example.com"
    
    # 重启服务
    nssm start RTKHUB
}

性能优化

系统调优

关闭不必要的服务
增加虚拟内存
使用 SSD 存储结果文件

RTKHUB 优化

调整日志级别（-t 0）
减少历史数据保留
定期清理日志

安全加固

修改默认密码
限制访问 IP
定期更新
启用 HTTPS
配置防火墙

故障恢复

数据恢复

# 从备份恢复
nssm stop RTKHUB
Remove-Item D:\rtkhub\database -Recurse
Expand-Archive E:\backups\rtkhub_YYYYMMDD.zip D:\rtkhub\
nssm start RTKHUB

从 v1.2.0 升级到 v1.3.0

v1.3.0 版本修复了多个安全漏洞（2 个 P0 严重、1 个 P1 高危、1 个 P2 中危），强烈建议所有生产环境用户升级。

升级前准备

兼容性说明

v1.3.0 完全兼容 v1.2.0 的配置文件和数据库，无需任何迁移操作。升级后 EPHUB 流会自动重连。

备份关键数据：

# 创建升级前备份
$date = Get-Date -Format "yyyyMMdd_HHmmss"
$backupPath = "E:\backups\rtkhub_v1.2.0_$date"

# 停止服务
nssm stop RTKHUB

# 备份配置、数据库和日志
Copy-Item D:\rtkhub\conf $backupPath\conf -Recurse
Copy-Item D:\rtkhub\database $backupPath\database -Recurse
Copy-Item D:\rtkhub\log $backupPath\log -Recurse

# 备份当前二进制文件（用于回滚）
Copy-Item D:\rtkhub\rtkhub.exe $backupPath\rtkhub.exe.v1.2.0

# 压缩备份
Compress-Archive $backupPath "$backupPath.zip"
Remove-Item $backupPath -Recurse

Write-Host "备份完成: $backupPath.zip"

升级步骤

下载 v1.3.0 发布包

# 从 GitHub Releases 下载
# https://github.com/apkpai/rtkhub/releases/tag/v1.3.0

替换二进制文件

# 解压新版本（假设已下载到 Downloads 目录）
Expand-Archive "$env:USERPROFILE\Downloads\rtkhub-v1.3.0.zip" D:\rtkhub_v1.3.0

# 替换主程序
Copy-Item D:\rtkhub_v1.3.0\rtkhub.exe D:\rtkhub\rtkhub.exe -Force

# 如果使用 STRHUB/EPHUB，也需要替换
Copy-Item D:\rtkhub_v1.3.0\strhub.exe D:\rtkhub\strhub.exe -Force
Copy-Item D:\rtkhub_v1.3.0\ephub.exe D:\rtkhub\ephub.exe -Force

启动新版本

# 启动服务
nssm start RTKHUB

# 检查服务状态
nssm status RTKHUB

# 查看日志确认启动正常
Get-Content D:\rtkhub\log\rtkhub.log -Tail 20

验证检查

升级验证清单

升级完成后，依次验证以下功能确保系统正常运行：

1. Web 访问验证

# 访问 Web 界面
Start-Process "http://127.0.0.1:5426"

# 检查登录和会话功能
# - 登录成功后应生成新的会话 ID（P1 修复验证）
# - 查看浏览器开发者工具 > Application > Cookies > rtkhub_session

2. API 功能测试

# 测试基本 API
curl http://127.0.0.1:5426/api/status

# 测试路径遍历防护（应返回 400 或 403）
curl "http://127.0.0.1:5426/api/..%2F..%2Fsecret.txt"
curl "http://127.0.0.1:5426/api/..%5c..%5csecret.txt"

3. EPHUB 热更新测试（如果使用 EPHUB）

访问 EPHUB 管理页面 http://127.0.0.1:5428，测试：

添加输入流（CLI: add input <path>）
添加输出流（CLI: add output <path>）
保存配置（CLI: save）

4. 安全功能验证

# 测试登录速率限制（连续 6 次失败登录应触发 429）
for ($i=1; $i -le 6; $i++) {
    curl -X POST http://127.0.0.1:5426/api/login `
        -H "Content-Type: application/json" `
        -d '{"username":"test","password":"wrong"}'
    Start-Sleep -Seconds 1
}
# 第 6 次应返回 HTTP 429 Too Many Requests

5. 日志检查

# 检查是否有启动错误
Get-Content D:\rtkhub\log\rtkhub.log -Tail 50 | Select-String -Pattern "error|fail|crash"

# 确认版本号
Get-Content D:\rtkhub\log\rtkhub.log | Select-String -Pattern "v1.3.0"

回滚步骤

回滚说明

如果升级后遇到问题，可以回退到 v1.2.0。回滚不会丢失数据，因为 v1.3.0 没有修改数据库结构。

# 1. 停止服务
nssm stop RTKHUB

# 2. 恢复旧版本二进制（从升级前备份中提取）
$backupZip = "E:\backups\rtkhub_v1.2.0_YYYYMMDD_HHmmss.zip"
Expand-Archive $backupZip "D:\rtkhub_restore" -Force
Copy-Item D:\rtkhub_restore\rtkhub.exe.v1.2.0 D:\rtkhub\rtkhub.exe -Force

# 3. 启动服务
nssm start RTKHUB

# 4. 验证回滚成功
Get-Content D:\rtkhub\log\rtkhub.log -Tail 20 | Select-String -Pattern "v1.2.0"

回滚后注意事项

回滚后系统会重新暴露 v1.2.0 的安全漏洞，应尽快诊断升级失败原因并重新升级
如果回滚后问题仍然存在，说明问题可能与版本无关，需要检查配置或环境
回滚不会影响配置文件和数据库，但会丢失 v1.3.0 引入的新功能（如 EPHUB 热更新）

已知问题和解决方案

问题 1：升级后 EPHUB 流无法连接

# 检查 EPHUB 日志
Get-Content D:\rtkhub\log\ephub.log -Tail 50

# 通常是流配置路径问题，尝试重启 EPHUB
nssm restart EPHUB

问题 2：Web 界面无法访问

# 检查端口占用
netstat -ano | findstr "5426"

# 检查防火墙规则
Get-NetFirewallRule -DisplayName "RTKHUB"

# 尝试重启服务
nssm restart RTKHUB

问题 3：登录后立即退出

这可能是会话 ID 重新生成机制导致的兼容性问题（P1 修复副作用）。检查：

# 清除浏览器 Cookie 后重新登录
# Chrome: 开发者工具 > Application > Cookies > 右键删除 rtkhub_session

# 如果问题持续，检查日志
Get-Content D:\rtkhub\log\rtkhub.log | Select-String -Pattern "session"

技术支持

如遇升级问题，请在 GitHub Issues 提供以下信息：

操作系统版本和架构
v1.2.0 和 v1.3.0 的完整日志文件（已脱敏）
详细的错误信息或异常行为描述
配置文件（已脱敏凭据）

下一步

使用教程 - 功能使用
Docker 部署 - 容器化部署和运维
故障排查 - 问题诊断
安全与权限 - 安全最佳实践和 v1.3.0 安全修复详情

准备工作​

选择部署方式​

本地部署​

1. 解压文件​

2. 创建配置​

3. 启动服务​

Windows 服务​

创建服务​

管理服务​

Nginx 反向代理​

配置 HTTPS​

Docker 部署​

防火墙配置​

Windows 防火墙​

Linux iptables​

自动备份​

备份脚本​

定时任务​

监控告警​

进程监控​

性能优化​

系统调优​

RTKHUB 优化​

安全加固​

故障恢复​

数据恢复​

从 v1.2.0 升级到 v1.3.0​

升级前准备​

升级步骤​

验证检查​

回滚步骤​

已知问题和解决方案​

技术支持​

下一步​