系统运维手册

本文档为 设备运维管理系统（ruoyi-plus） 的安装部署、日常运维与常见问题处理总览，供运维、测试与实施人员使用。

专项文档索引：

一、系统组成与端口

1.1 三端架构

生产环境 Web 通过 Nginx 反向代理，API 前缀为 /prod-api/。

1.2 基础组件（deploy 编排）

1.3 可选转换微服务

二、主系统部署

2.1 生产环境（deploy 目录）

详细步骤见 Deploy.md。简要流程：

# 1. 上传 deploy 目录到 Linux 服务器
# 2. 按顺序导入 deploy/sql/ 下脚本到 MySQL ry-vue 库
# 3. 启动
cd deploy
chmod +x start.sh
./start.sh

访问：http://<服务器IP>/（管理后台），API：/prod-api/ → 后端 8080。

2.2 开发环境

2.3 推荐启动顺序

MySQL → Redis → MinIO → 转换微服务（8095/8096，若启用）→ jula-admin → Nginx / 前端

三、数据库升级

3.1 新装环境

按顺序执行 deploy/sql/ 或 dmsysr-backend/script/sql/ 下脚本，业务表见 04_dmsys.sql。

3.2 存量环境增量升级

脚本均为可重复执行设计（部分语句在已升级库上可能报重复列/表，可忽略）。公开租户与 App 自助注册详见 PUBLIC租户与App自助入会运维说明.md；私有租户开租户、合同配额与用户接入详见 私有租户管理运维手册.md；App 用户 Web 权限与 Demo 写保护详见 App用户与现场运维员权限运维说明.md。

mysql -u root -p ry-vue < dmsysr-backend/script/sql/dmsys_upgrade_doc_preview.sql

四、资料/图纸附件上传限制

管理端上传或替换资料、图纸附件时，若文件过大可能导致上传失败。各层限制须保持一致，修改任一层时需同步调整其余层。

4.1 当前默认限制

Office PDF 预览转换另有独立上限 dmsys.office.convert.max-file-mb（默认 50 MB）。超过 50 MB 的 Office 文件可以上传成功，但服务端 PDF 转换会失败；需调大该值并同步调整 office-converter 的 MAX_FILE_MB。

4.2 上传失败常见原因

4.3 调大上传上限（示例：改为 500MB）

须同步修改以下配置后重启相关服务：

1. 后端 application.yml：

spring:
  servlet:
    multipart:
      max-file-size: 500MB
      max-request-size: 520MB

dmsys:
  upload:
    max-file-mb: 500

2. Nginx deploy/nginx/conf/nginx.conf：

client_max_body_size 520m;

3. 前端 dmsysr-frontend/src/constants/dms-upload.ts：

export const DMS_MAX_UPLOAD_MB = 500;

4. 重新构建/部署前端与后端，并重载 Nginx。

4.4 相关实现入口

五、Office 转 PDF 转换服务

资料模块上传 Office 文档（doc/docx/xls/xlsx/ppt/pptx）后，后端异步调用 dmsys-office-converter（端口 8096）生成 PDF 预览。

5.1 快速启动

Docker：

cd dmsysr-backend/script/docker
docker compose up -d dmsys-office-converter
curl http://127.0.0.1:8096/health   # 期望 {"status":"ok"}

命令行（Windows 开发）：

# 需安装 LibreOffice 并将 program 目录加入 PATH
cd dmsysr-backend\script\office-converter
pip install -r requirements.txt
uvicorn app:app --host 127.0.0.1 --port 8096

后端配置（application.yml）：

dmsys:
  office:
    convert:
      enabled: true
      converter-base-url: http://127.0.0.1:8096
      max-file-mb: 50
      timeout-sec: 300

5.2 转换状态

资料表 doc_process_status：NONE / PENDING / READY / FAILED。管理端列表可查看「PDF 预览」列；失败时可调用 POST /dmsys/document/{id}/reconvert 重新转换。

5.3 详细说明

完整安装、systemd 常驻、排障与验证步骤见：

资料Office转PDF转换服务部署运维说明.md

六、CAD 转换服务（简要）

cd dmsysr-backend/script/docker
docker compose up -d dmsys-cad-converter
curl http://127.0.0.1:8095/health

6.1 详细说明

完整安装、Docker / 本机启动、API、排障与验证步骤见：

图纸CAD转换服务部署运维说明.md

七、常见问题排障

7.1 Office 转换 HTTP 422 / Invalid HTTP request

现象：office-converter 日志出现 422 Unprocessable Entity 与 Invalid HTTP request received。

原因：Java HttpClient 默认 HTTP/2，uvicorn 解析异常。

处理：确认 DocConvertServiceImpl 已强制 HttpClient.Version.HTTP_1_1；重启 jula-admin；对失败资料执行「重新转换」。

7.2 Office 转换连接拒绝

处理：启动 office-converter；核对 converter-base-url；检查防火墙 8096 端口。

7.3 资料上传失败（非超限）

1. 检查 MinIO/OSS 是否可达（dmsys.upload.use-oss）
2. 查看 jula-admin 日志中 DmsFileStorageService 相关错误
3. 本地降级目录：./uploads/dmsys/{tenant}/document/{id}/

7.4 App 无法同步资料

1. 确认后端 /api/sync 可访问且 Token 有效
2. 检查资料授权（access_mode / dms_equipment_doc_grant）
3. 弱网环境：按分类同步或打开详情触发附件下载

7.5 生产环境修改配置后未生效

八、配置速查表

九、日志位置

十、日常巡检清单

• MySQL / Redis / MinIO 容器或进程运行正常
• curl http://127.0.0.1:8080 或健康检查端点可达
• 管理后台可登录，资料列表可加载
• office-converter GET /health 返回 ok（若启用 Office 预览）
• cad-converter GET /health 返回 ok（若启用 3D 预览）
• 磁盘空间：uploads/dmsys、MinIO 数据目录、MySQL 数据目录
• 抽查上传 10MB+ 资料附件是否成功
• 抽查 Office 资料 PDF 预览状态为 READY

文档版本：v1.0 | 随系统功能迭代更新，专项细节以各子文档为准