# 08. RailwaySystem 部署与发布指南

> **文档定位**：面向运维工程师、发布主管及系统管理员的生产与测试环境部署、数据库迁移及服务维护手册。
> **当前基线**：Final Candidate `5a49b2e2988bf23ca2a70568264c05b24dfda1b6` (`origin/feat/cicd-pipeline`)

---

## 1. 目标运行环境标准

系统在多环境部署中遵循标准化的网络拓扑与端口规划：

```mermaid
flowchart LR
    subgraph Clients["客户端层"]
        Web["PC 浏览器 (Admin/教师/学员)"]
        BoardDev["物联网终端 (电子班牌)"]
    end

    subgraph ReverseProxy["反向代理与静态托管 (端口 8082)"]
        Nginx["Nginx Web 服务<br/>静态托管 build_ui / SSL 443 / 8082"]
    end

    subgraph AppCluster["业务应用服务 (端口 8092)"]
        SpringBoot["Spring Boot 容器 (ruoyi-admin)<br/>JVM 4GB+ / 端口 8092"]
    end

    subgraph DataTier["国产数据库与缓存层"]
        KB[("人大金仓 KingbaseES V9<br/>端口 54321 / 4321")]
        Redis[("Redis 缓存服务<br/>端口 6379")]
    end

    Web -->|HTTP / HTTPS| Nginx
    BoardDev -->|HTTP API| Nginx
    Nginx -->|反向代理 /prod-api| SpringBoot
    SpringBoot -->|JDBC 8.6.0| KB
    SpringBoot -->|Jedis / Lettuce| Redis
```

| 组件名称 | 本地开发环境端口 | 集成与验收测试环境端口 | 生产环境建议规范 |
| :--- | :---: | :---: | :--- |
| **后端 API 服务 (Spring Boot)** | `8090` | **`8092`** | 8090~8099 负载均衡集群，JVM 内存建议分配 4GB+ |
| **前端交互应用 (Vue/Nginx)** | `8080` | **`8082`** | Nginx 反向代理（443/80），开启 Gzip 压缩与静态缓存 |
| **KingbaseES 国产主库** | `127.0.0.1:4321` (SSH隧道)| 直连实例 `54321` / `4321` | 国产人大金仓数据库实例，标准单主库配置 |
| **Redis 缓存服务** | `6379` (无密码) | `6379` (带密码预检) | 标准 Redis 缓存服务，用于 Token 校验与验证码防重放 |

---

## 2. 发布增量迁移规范 (Release DB Delta)

在系统从初始 V2 物理结构演进到当前 Final Candidate 的过程中，形成了正式的发布增量迁移序列：

> **正式发布增量版本**：`CURRENT_RELEASE_DB_DELTA = 3`

### 2.1 正式 Delta 脚本清单
1. **Delta 001** —— `RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql`
   - 作用：补齐 Kingbase 系统操作日志表中的消耗时间（`cost_time`）统计字段，保障运维监控正常运行。
2. **Delta 002** —— `RuoYi-Vue/sql/system/kingbase/002_legacy_analytics_permissions.sql`
   - 作用：将旧分析模块菜单权限与 V2 契约精准对齐，建立只读报表查询与导出安全屏障。
3. **Delta 003** —— `RuoYi-Vue/sql/system/kingbase/003_report_attendance_action_permissions.sql`
   - 作用：向 `public.sys_menu` 表声明开班现场报到确认（`train:report:confirm`）、课次考勤打卡（`train:attendance:checkin`）与考勤人工修正（`train:attendance:edit`）三项按钮级原子权限。

### 2.2 字典初始化红线警示
* ⚠️ **`007_dicts.sql` 明确执行禁令**：
  - **`DO NOT EXECUTE`**：该脚本包含了大量未经环境幂等校验的历史字典初始数据，若盲目物理执行会污染生产 `sys_dict_data` 主键并引发唯一性冲突。在当前发布版本中严格禁止在生产库物理执行！

---

## 3. 标准发布与升级步骤

生产升级必须遵循受控操作规程：

```bash
# 步骤 1：拉取受控发布分支最新代码
git checkout feat/cicd-pipeline
git pull origin feat/cicd-pipeline

# 步骤 2：驱动依赖与环境预检
bash scripts/bootstrap/check-kingbase-jdbc.sh

# 步骤 3：数据库增量应用 (仅执行当前 Delta 001/002/003)
ksql -U SYSTEM -d training -f RuoYi-Vue/sql/system/kingbase/001_sys_oper_log_cost_time.sql
ksql -U SYSTEM -d training -f RuoYi-Vue/sql/system/kingbase/002_legacy_analytics_permissions.sql
ksql -U SYSTEM -d training -f RuoYi-Vue/sql/system/kingbase/003_report_attendance_action_permissions.sql

# 步骤 4：后端服务编译打包与启动 (8092 目标端口)
mvn clean package -DskipTests
java -Xms2048m -Xmx4096m -jar RuoYi-Vue/ruoyi-admin/target/ruoyi-admin.jar --server.port=8092 &

# 步骤 5：前端静态资源编译并由 Nginx 承载 (8082 目标端口)
cd build_ui
npm run build:prod
# 部署至 Nginx html 目录，加载 deploy/nginx.conf.example 配置
```

---

## 4. 技术参考链接 (Technical References)

* Kingbase JDBC 驱动依赖说明：[deployment/kingbase-jdbc-provisioning.md](deployment/kingbase-jdbc-provisioning.md)
* 发版说明与变更记录：[docs/reports/archive/20260915/release-notes.md](../reports/archive/20260915/release-notes.md)
* 部署验收与就绪报告：[docs/reports/archive/20260915/deployment-report.md](../reports/archive/20260915/deployment-report.md)
* 数据库物理模型清单：[docs/database-v2/01_table_inventory.md](../database-v2/01_table_inventory.md)