主题
平台部署方案
项目手册 · 平台部署与运行。本文提供部署、核验和回滚的操作框架；实际环境、运行版本、配置与操作权限须在执行前重新核对。
| 项目 | 内容 |
|---|---|
| 文档版本 | 0.21 |
| 最近核对日期 | 2026-11-09 |
| 本次环境核验 | 2026-11-09 在生产（15.50.3.142）与开发（1.12.68.9）发布 BIM 底座首期：生产新增 BIM 六表与普通管理员菜单授权、黑洞 PROD 项目配置、8888 /blackHole3D/ 同源反代与 2G 上传限制，应用切至 releases/20261109-0105-bim；开发更新前端 frontend-release-20261109-0107-bim 与后端包。生产接口与配置已回读验证；开发服务器到引擎网络不通，BIM 预览在远程 dev 受阻，本机开发已验证。细节见 §5.1 与 §9 |
1. 范围与资料位置
本方案覆盖平台前端、后端、数据库与相关依赖的部署、发布验证和回滚。文档站自身发布见环境配置与运行；数据库和流程定义的环境同步按双环境同步执行。
整理前的部署、迁移、故障处理和各次发布验证原文，保存在项目根 reports/部署运维/平台部署历史记录-截至2026-11-02.md。历史记录不是当前运行状态，也不是再次执行的操作依据。单次部署的证据与回退位置按项目交付规范留存，不再逐次堆入本方案。
本文不记录实际口令、密钥、令牌或内网地址。账号和连接信息按私有配置管理；访问生产、修改受保护配置和发布均遵循项目授权要求。
2. 环境与部署架构
| 环境 | 历史核验情况 | 本次状态 |
|---|---|---|
| 开发 | 腾讯云主机承载 DM8、Redis、MinIO、kkFileView、平台及文档站；后端 /opt/digital-construction-platform/backend，前端按 frontend-release-<时间戳> 目录由 nginx 提供，dev profile | 2026-11-04 回读：服务 active，前端 frontend-release-20261104-0300-27a9de45，后端本次 dev 包 |
| 生产 | 内网应用机（142）承载平台及部分中间件，DM8 位于独立内网数据库服务器；版本目录 + current 软链，prod profile 由 systemd 传入 | 2026-11-04 回读：服务 active，current → releases/20261104-0249-27a9de45，DM8 连接正常 |
| SnailAI | 2026-11-02 记录：独立服务由 systemd 管理，平台经反向代理访问；主应用客户端曾回读到在线节点 | 当前服务版本、模型配置及完整页面链路待重新核对 |
上述只说明当时部署形态；不根据代码版本、历史表数或数据库回读推定服务器运行版本。执行前分别核对主机归属、实际服务、发布目录、数据源与网络位置；涉及生产须具备具体授权。
平台通常由前端静态站点、Spring Boot 后端、DM8、Redis、MinIO 和 kkFileView 组成。SnailAI 使用独立服务与受保护的私有配置；对话、检索、模型和文件能力应按实际部署与权限核实，不能从服务在线推定业务链路已验证。
3. 拓扑与配置核对
3.1 服务和入口
| 项目 | 执行前核对 |
|---|---|
| 前端与反向代理 | 实际监听地址、端口、域名、证书、站点根目录、代理路径和 Host 白名单 |
| 后端服务 | systemd 单元、运行用户、启动参数、工作目录、监听地址及 profile |
| 数据库 | 环境、主机、实例和模式；经项目纳管入口确认连接目标 |
| Redis、MinIO、kkFileView | 实际连接目标、运行状态、数据目录及网络访问范围 |
| SnailAI（如适用） | 独立服务及反向代理、客户端连接、模型服务和受保护配置 |
历史记录显示生产入口曾收敛至 HTTPS 8888，旧资料中也出现过 443 和 8888 并存的说法；当前以目标机配置及网络回读为准，不能直接沿用任一旧端口结论。
3.2 配置和依赖
application.yml与对应环境的 profile 提供应用配置；凭据存放与覆盖方式遵循私有配置，具体值不进入公开文档、日志和截图。- 前端环境文件参与构建；发布前核对 API 前缀与预览入口是否对应目标环境。
- systemd、nginx 和中间件配置独立维护，发布前记录实际生效文件和可恢复副本；未经授权不调整受保护配置。
- 对象存储反代须核对实际路径与 Host 透传，避免签名校验失败。上传限制需要结合 nginx、应用和对象存储路径分别核对；历史记录中的限额不自动代表当前配置。
- 数据库、Redis、对象存储和预览服务可能分别影响启动、登录、附件或预览。根据实际依赖核对启动顺序、连通性和恢复方式。
3.3 BIM 底座（黑洞引擎）
BIM 依赖黑洞引擎的项目空间、转换队列和浏览器端 SDK。两个环境使用独立项目空间，禁止共用一个项目 ID：
| 环境 | 引擎项目空间 | 服务端连接 | 浏览器资源 | 凭据注入 |
|---|---|---|---|---|
| 开发（1.12.68.9） | 交开投数智建管平台-DEV（3a24c81b-151f-9a5c-169e-f5d79bc12be8） | http://15.50.3.12:9012 | 引擎直连 | profile 默认值，可用 preview.env 的 BIM_ENGINE_USERNAME/PASSWORD 覆盖 |
| 生产（142） | 交开投数智建管平台-PROD（3a24ce26-7194-6c89-6494-439cf8b0fdab） | http://15.50.3.12:9012 | 平台 8888 /blackHole3D/ 同源反代 | profile 默认值，可用 digital-construction-platform.service.d/bim.conf 覆盖 |
- 项目 ID、引擎地址与资源根固定在对应
application-dev.yml/application-prod.yml；同名环境变量可覆盖，但发布前须回读实际 profile 与项目 ID，避免把开发项目带入生产。 - 生产页面只经 HTTPS 8888 提供，浏览器直接请求 HTTP 引擎资源会被混合内容策略拦截。生产 nginx 的
/blackHole3D/反代必须保留路径、透传Host并关闭请求缓冲；应用侧BIM_ENGINE_USE_REQUEST_ORIGIN=true后按请求Origin生成 SDK 与数据集资源地址，IP 与域名入口各自同源。 - 上传限制：平台 multipart 2G，nginx
/dev-api/、/prod-api/、MinIO 反代与/blackHole3D/均为 2g 并关闭请求体缓冲；调整前保留配置副本并执行nginx -t。 - SDK 版本必须与引擎部署一致（当前 3.2.0.3772），按
/bh-sdk/<版本>/javascript/目录随前端产物发布。 - 开发服务器 1.12.68.9 到
15.50.3.12:9012当前网络不通；远程 dev 的转换与预览受阻，需网络放行后再验证。生产 142 与引擎同内网，已实测可达。
4. 发布前准备
- 确定目标环境、部署范围、受测代码和产物，核实发布授权、环境连接目标及适用的服务操作权限。
- 按改动范围完成项目规定的测试和检查；确认产物来源、构建 profile、完整性及前后端接口前缀。
- 核对当前运行版本、服务状态、配置、数据库变更及流程定义状态；记录可用的上一版本和实际回退方式。
- 对需要改动的配置及数据准备与本次风险相适应的备份和恢复依据；确认回退影响，不将开发业务数据直接覆盖生产。
- 确认相关依赖、磁盘空间、网络及验证账号。凭据通过受控方式使用，不写入命令、文档或日志。
5. 应用构建与发布
构建通过项目统一工具入口执行，命令、profile 和测试范围按实际交付内容选择。以下是生产 profile 构建示例，不代表已经完成测试或获得发布授权：
powershell
.\.agents\tools\dev.ps1 maven -P prod '-Dmaven.test.skip=true' package
.\.agents\tools\dev.ps1 pnpm --dir .\digital-construction-ui build后端产物位于 digital-construction-admin/target/，前端产物位于 digital-construction-ui/dist/。按本次影响另行执行必要测试；跳过测试的打包命令不能作为测试通过证据。
生产历史上使用版本目录与 current 软链；开发环境历史上通过替换后端包和更新 nginx 站点根目录发布。两环境方式不同，发布前必须回读实际目录、单元和反向代理配置，不把生产切换命令直接用于开发环境。
按获授权的部署方式上传并核对产物，在目标环境组装新版本、保留上一版本与必要配置副本，再执行对应的切换和服务操作。需要重启或 reload 前确认目标进程归属、影响范围与回退步骤；日志目录和运行用户权限须与实际服务配置匹配。发布完成后执行第 7 节验证。
生产采用版本目录与软链的场景，可按下列顺序处理，具体路径和服务名以目标环境回读为准：
- 将前后端产物放入新版本目录，核对文件摘要、运行用户权限及日志目录；保留旧版本目录和当前软链指向。
- 如有代理或服务配置变更，先保存配置副本并执行适用的语法检查；按本次授权切换软链、重启对应服务或重载代理。
- 回读软链、服务状态和启动日志，与本次产物及目标环境比对，再进行业务验证。
开发环境若仍采用后端包与 nginx 站点目录分别切换，须分别保留旧包和站点配置，并核实前后端均指向本次产物。服务名、配置文件和切换方式以现场回读结果为准。
5.1 2026-11-09 BIM 底座首期发布
| 项 | 生产（142） | 开发（1.12.68.9） |
|---|---|---|
| 应用版本 | releases/20261109-0105-bim；JAR SHA-256 b8ed1a84…71d51，首页 SHA-256 e9ade4e1…5fd7 | 后端 JAR SHA-256 53167de7…f0d7；前端 frontend-release-20261109-0107-bim，首页 SHA-256 9f4880b1…bf26 |
| 上一版本 | releases/20261108-0340-7c6b475e-frontend-fix（保留） | 后端 digital-construction-admin.jar.bak-20261109-bim；nginx 配置 .bak-20261109-bim |
| 数据库 | 新建 BIM_MODEL、BIM_MODEL_VERSION、BIM_MODEL_FILE、BIM_PROCESS_TASK、BIM_ELEMENT、BIM_ELEMENT_PROPERTY 六表与 6 个业务索引；回读 6 表、24 索引、27 约束与开发库一致 | 沿用既有六表与数据 |
| 菜单权限 | 生产已有 9 行 BIM 菜单及超级管理员授权；本次补齐普通管理员（normaladmin）9 行角色菜单 | 已具备 |
| 配置 | application-prod.yml 固定 PROD 项目与引擎账号默认值，bim.conf 可覆盖；nginx /blackHole3D/ 同源反代，/prod-api/、/fourthphase-minio/ 2g | application-dev.yml 固定 DEV 项目与引擎账号默认值，preview.env 可覆盖并开启按请求 Origin；nginx /blackHole3D/ 反代，/dev-api/ 2g |
| 回读验证 | 服务 active、prod profile、到生产库 15 条连接；首页与 JAR 哈希一致；/prod-api/auth/code 200；BIM 导航树、模型分页、预览上下文 200，上下文返回工点/标段/单位工程名称，SDK 地址分别按 IP 与域名同源；引擎代理 API 与资源 200 | 服务 active、启动完成；首页哈希一致；/dev-api/auth/code HTTP/HTTPS 200；BIM 预览上下文返回模型与名称，SDK 地址按请求 Origin 生成；开发机到引擎 TCP 不通，引擎代理超时 |
| 回退 | current 切回上一版本目录并重启；新表保留（BIM 菜单可同时保留，不影响旧版本） | 恢复 digital-construction-admin.jar.bak-20261109-bim 与上一前端目录，恢复 nginx 备份并 reload |
6. 数据库与流程定义
数据库查询、结构变更、数据变更与验证统一通过项目纳管入口。开发和生产分别核实环境、对象、条件和授权，变更前确认影响与必要备份，变更后回读；DDL 核对对象，DML 记录影响行数。仓库不保存业务 SQL 文件，禁止将历史整库导入、替换或清理命令当作常规发布步骤。
普通表结构变更与生产发布分开；Warm-Flow 定义按项目双环境专项规则处理。涉及数据迁移时，事先确定范围、依赖、数据处理和可恢复方案，经授权后通过适用纳管流程执行。对象存储文件本体不会因数据库变更自动同步；涉及附件时分别核查文件记录、对象本体和访问链路。
7. 发布后验证
根据本次变更和风险选择必要检查，分别记录环境、受测版本、实际结果和未覆盖范围：
| 核验项 | 要点 |
|---|---|
| 服务与产物 | systemd 状态、启动日志、当前运行版本、前后端产物及入口是否对应目标环境 |
| 配置与依赖 | profile、数据库连接目标、Redis、对象存储、预览及其他实际依赖 |
| 接口与权限 | 受影响接口、登录和相应角色的数据范围；检查失败时记录原因 |
| 页面与业务链路 | 用户明确要求或实际风险需要时，从真实页面入口检查受影响操作 |
| 附件与外部服务 | 受影响时核对上传、下载、预览及真实调用链；标明客户端网络位置和未覆盖范围 |
| 数据库与流程 | 受影响对象及数据回读；流程定义按目标环境核对版本、启用状态与在途实例 |
核对 systemd 服务时，可在目标机使用 systemctl is-active <服务名> 和 journalctl -u <服务名> -n 50 --no-pager；变更 nginx 配置时先执行 nginx -t。服务名和检查入口应先从实际环境确认，不把占位符作为可直接执行的参数。
服务启动、接口响应、数据库回读和页面操作各自只支持对应范围的结论。任何必要检查失败或受阻均应据实报告，不把历史证据当成本次验证。
8. 回滚与恢复
发布前针对实际变更确认可用回退点和影响范围。应用包、前端目录、代理和服务配置分别按目标环境实际方式恢复；确认数据库变更的可逆性、备份可用性及业务数据影响后，按授权的恢复方案处理。不要假定切换应用版本即可自动回滚数据库、流程或对象存储。
回滚后复核服务、实际版本、连接目标和受影响业务链路，记录原因、结果和剩余问题。涉及 SSH 等唯一管理通道的变更，先准备可用的恢复通道和回滚方式。
9. 已知事项与待核对项
以下来自历史记录，本次未重新核验其当前状态：
- 生产历史附件的对象本体曾未随数据库迁移，下载和预览受影响；当前范围与处理状态待核对。
- 生产数据库实例参数曾与开发实例不同；跨环境迁移前核对实际参数和兼容性。
- 2026-10-08 记录过 kkFileView 出站 HTTPS 证书校验关闭；当前配置及风险处置状态待核对。
- 历史记录中的生产 DM8 试用授权到期日为 2026-12-25；当前授权类型和有效期待核对。
- SnailAI 历史排查涉及模型内容拦截与检索上下文，页面完整问答和开发、生产向量索引隔离未据当时证据确认；当前状态待核对。
- 生产历史端口暴露、管理入口范围和旧库保留情况均需依据当前网络及运维配置核对。
- 开发服务器 1.12.68.9 到黑洞引擎
15.50.3.12:9012当前 TCP 不通（腾讯云与内网引擎之间未放行），远程 dev 的 BIM 转换与预览不可用；需网络管理开通后再验证，期间以本机开发环境验证 BIM 链路。 - 生产 BIM 已具备六表、菜单、PROD 项目与引擎同源代理；PAK 样本、同工点多资产叠加、非管理员未发布内容权限仍按 BIM 测试文档列为未验证项。
10. 参考资料
- 环境配置与运行：工具、数据库纳管入口和双环境同步。
- 软件交付文档：交付资料和验证状态。
- 系统设置数据库设计：系统基础表。
- 流程引擎底座数据库设计：公共工作流运行时表。