OARS 私有化部署手册

1. 概述

OARS 采用前后端分离架构：前端为 Vue 3 静态站点，后端为 Spring Boot 3 单体应用（模块化 Maven 工程）。 私有化部署时，客户通常只需对外暴露一个 Web 入口（Nginx），由 Nginx 托管前端静态资源并反向代理 API。

本手册覆盖两条主流路径：

• 推荐：Docker Compose 一键编排 MySQL、Redis、后端与 Nginx 前端 — 适合 POC、试点与标准私有化。
• 备选：源码交付 + 传统部署 — 适合需深度二开、接入现有中间件或信创数据库的项目。

2. 架构说明

标准 Compose 部署时的组件关系如下：

关键路径约定

前端构建时 VITE_GLOB_API_URL 须与浏览器实际访问的后端前缀一致。Compose 默认设为 /oars（同域反代，无需写完整域名）。

3. 环境要求

硬件建议

软件依赖

网络与端口

Docker Compose 与 Podman 脚本 均将 MySQL、Redis、后端映射到 127.0.0.1（仅本机可连），前端端口 18088 绑定 0.0.0.0 对外提供 Web 访问。生产环境仍须在云安全组 / 防火墙中禁止数据库与 Redis 端口对公网开放。

3.1 命令行环境

3.2 云服务器部署

多数客户会在腾讯云、阿里云、华为云等 ECS 上部署。以下为通用要点；装完 Docker 后按第 5 章 Compose 步骤执行即可。

实例规格（参考）

安全组 / 防火墙（必做）

云主机上的推荐步骤

1. 安装 Docker 与 Compose 插件 以 Ubuntu 为例：按 Docker 官方文档安装 Engine 与 docker compose v2；国内机器可配置镜像加速（阿里云 / 腾讯云容器镜像服务提供的加速器地址）。
2. 上传或拉取源码 将交付包解压至 /opt/oars/ 等目录，或通过客户 Git 仓库 clone；确认含 deploy/docker/。
3. 配置并启动 按第 5 章复制 .env、修改密码与 JWT，执行 docker compose ... up -d --build。
4. （可选）绑定域名与 HTTPS 在云厂商负载均衡或本机 Nginx 配置证书，将 443 反代到 127.0.0.1:18088 或直接托管静态资源（第 12 章）。
5. （可选）使用云数据库 生产可改用云 RDS MySQL、云 Redis，省略 Compose 中的 oars-mysql / oars-redis 服务，后端环境变量指向云实例（第 11 章）。

4. 交付物

源码交付包为 monorepo 结构（以实际合同清单为准）。注意：Flyway 迁移脚本位于 oars-java/oars-migration/，不是仓库根目录下的独立文件夹；运行时由 oars-app 依赖该模块，启动时自动执行迁移。

（源码根目录）
├── oars-java/                 # 后端 Maven 多模块
│   ├── oars-app/              # 启动入口（Spring Boot）
│   ├── oars-migration/        # Flyway 脚本（db/migration）
│   ├── oars-flow/、oars-form/ …
│   └── …
├── oars-web/                  # 前端 pnpm monorepo
│   └── apps/web-antd/         # 主应用，构建产物 dist/
├── deploy/
│   └── docker/                # Dockerfile、Compose、Podman 脚本、.env.example
└── …

5. Docker Compose 部署（推荐）

编排 MySQL、Redis、后端 Spring Boot 与 Nginx 前端，改 .env 后一条命令拉起完整环境。

5.1 准备

1. 进入源码根目录 确认存在 deploy/docker/docker-compose.yml。
2. 复制环境变量模板

   cp deploy/docker/.env.example deploy/docker/.env

3. 编辑 deploy/docker/.env 生产环境必须修改：MySQL root 密码、Redis 密码、JWT 密钥（建议 ≥ 32 字节随机串）。可选调整宿主机端口与 JVM 参数。

5.2 启动

在源码根目录执行（Linux bash）：

docker compose --env-file deploy/docker/.env \
  -f deploy/docker/docker-compose.yml up -d --build

首次构建耗时说明

首次 --build 会拉取基础镜像（Maven、Node、MySQL、Redis、Nginx 等）并在容器内编译前后端，通常需要 10～30 分钟，取决于：

• 出网带宽与是否配置 Docker 镜像加速（国内云主机建议开启）
• CPU / 内存（前端 pnpm 构建默认较大内存占用）
• Maven 中央仓库与 npm registry 可达性

后续升级若仅改业务代码，Docker 层缓存可显著缩短时间。构建过程中可用 docker compose ... logs -f oars-backend 观察进度。

停止服务（保留数据卷）：

docker compose --env-file deploy/docker/.env \
  -f deploy/docker/docker-compose.yml down

5.3 验证

建议按下列顺序做端到端冒烟（与仓库 deploy/docker/podman-smoke-test.sh 检查项一致）：

6. Podman 部署

若环境无 docker compose 但已安装 Podman，可使用仓库脚本（Linux bash）：

cp deploy/docker/.env.example deploy/docker/.env
chmod +x deploy/docker/*.sh
# 编辑 deploy/docker/.env 后
deploy/docker/podman-up.sh

脚本会构建镜像、创建网络与数据卷、依次启动 MySQL → Redis → 后端 → 前端，并等待健康检查通过。

冒烟验证与停止：

deploy/docker/podman-smoke-test.sh
deploy/docker/podman-down.sh

与 Docker Compose 的一致性

Podman 脚本的端口绑定策略与 Compose 相同：MySQL、Redis、后端监听 127.0.0.1，前端监听 0.0.0.0。环境变量、数据卷名称与冒烟脚本均可共用。

7. 源码传统部署

适合客户已有 MySQL/Redis 集群、需信创数据库驱动，或要在现有 CI/CD 流水线中构建的场景。

7.1 数据库

创建数据库（字符集必须为 utf8mb4）：

CREATE DATABASE oars
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

无需手工导入 SQL — 启动后端时 Flyway 自动执行 oars-java/oars-migration/src/main/resources/db/migration/ 下的脚本，并写入基线表与种子数据（含内置管理员）。

7.2 后端

1. 配置生产 Profile 编辑 oars-java/oars-app/src/main/resources/application-prod.yml，或通过环境变量覆盖数据库、Redis、JWT、上传目录等（见第 8 章）。
2. 编译打包

   cd oars-java
   mvn -pl oars-app -am -DskipTests package

3. 启动

   java -jar oars-app/target/oars-app-*.jar \
     --spring.profiles.active=prod

   首次启动等待 Flyway 完成（日志中出现迁移成功信息）。默认监听 8080，上下文路径 /oars。

7.3 前端

1. 配置构建变量 在 oars-web/apps/web-antd/.env.production 中设置：
   • VITE_GLOB_API_URL — 浏览器访问的后端 API 前缀，同域反代时填 /oars
   • VITE_BASE — 静态资源 public path，同域部署填 /；CDN 分离见第 13 章
2. 构建

   cd oars-web
   corepack enable
   pnpm install --frozen-lockfile
   pnpm run build:antd

   产物位于 oars-web/apps/web-antd/dist/。
3. 部署到 Nginx 将 dist 内容复制到 Nginx root，并配置 /oars/、/uploads/ 反代（见第 12 章）。

8. 配置说明

环境 Profile

Compose 环境变量（deploy/docker/.env）

后端关键配置项

敏感配置建议通过环境变量注入，勿将真实生产密码提交到版本库。个人本地覆盖可使用 application-local.yml（已在 .gitignore 中）。

9. 首次启动与验收

内置管理员

Flyway 基线迁移会创建超级管理员账号：

• 账号：admin
• 密码：开发环境默认为 123456；生产环境应在首次登录后立即修改，或通过 PasswordGenerator 工具生成 BCrypt 哈希后更新数据库

生成新密码哈希（在 oars-java 目录）：

mvn compile exec:java \
  -Dexec.mainClass="com.oars.common.util.PasswordGenerator" \
  -pl oars-common

冒烟测试清单

• 访问前端登录页，使用 admin 登录成功
• 进入工作台，页面无 API 404 / CORS 错误
• /oars/actuator/health 返回 UP
• 上传头像或附件，文件可正常访问
• 创建测试流程模板并发起、办理一条待办（验证核心业务链路）
• 登出后 Token 失效（JWT 黑名单依赖 Redis）

登录 API 示例

POST /oars/app/auth/login
Content-Type: application/json

{
  "account": "admin",
  "password": "123456"
}

10. 生产环境加固

以下四项直接影响安全与可用性，上线前务必处理：

1. JWT 密钥 替换默认开发密钥；登出 Token 黑名单依赖 Redis，密钥泄露风险极高。
2. 数据库与 Redis 凭据 使用强密码；MySQL/Redis 不对公网暴露；字符集 utf8mb4。
3. Swagger / 接口文档 生产环境建议关闭或限制内网访问：

   springdoc:
     swagger-ui:
       enabled: false
     api-docs:
       enabled: false

4. 上传目录与备份 确认上传目录权限与磁盘空间；制定 MySQL + 上传文件的定期备份策略。

11. 使用外部 MySQL / Redis

若客户已有数据库或缓存集群，可省略 Compose 中的 oars-mysql / oars-redis 服务，将后端环境变量指向外部地址：

SPRING_DATASOURCE_URL=jdbc:mysql://db.example.com:3306/oars?...
SPRING_DATASOURCE_USERNAME=oars_user
SPRING_DATASOURCE_PASSWORD=********
SPRING_DATA_REDIS_HOST=redis.example.com
SPRING_DATA_REDIS_PORT=6379
SPRING_DATA_REDIS_PASSWORD=********

外部 MySQL 仍须预先创建 oars 库（utf8mb4），Flyway 由后端首次启动时执行。确保网络连通性与防火墙白名单。

国产数据库（瀚高、达梦、金仓等）需额外安装 JDBC 驱动并按项目专篇配置，启用前请与技术支持确认兼容性。

12. Nginx 与 HTTPS

生产环境通常在客户自有域名下部署，由 Nginx 或网关统一入口。核心配置参考（与 Compose 内置模板一致）：

server {
  listen 443 ssl http2;
  server_name app.example.com;

  root /var/www/oars/dist;
  index index.html;
  client_max_body_size 80m;

  location /oars/ {
    proxy_pass http://127.0.0.1:8080/oars/;
    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_read_timeout 300s;
  }

  location /uploads/ {
    proxy_pass http://127.0.0.1:8080/uploads/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  location / {
    try_files $uri $uri/ /index.html;
  }
}

HTTPS 证书可使用 Let's Encrypt、客户 CA 或云厂商证书。若前端使用 Hash 路由（VITE_ROUTER_HISTORY=hash），try_files 配置可适当简化。

13. CDN 静态资源分离（可选）

当 JS/CSS 等静态资源托管在独立 CDN 域名时，构建前设置：

# oars-web/apps/web-antd/.env.production
VITE_BASE=https://cdn.example.com/
VITE_GLOB_API_URL=/oars

此时 index.html 通常保留在源站（主域名），其余静态资源上传 CDN。须在对象存储 / CDN 配置 CORS，允许主站域名跨域加载脚本：

• 允许来源：https://app.example.com
• 允许方法：GET、HEAD

14. ONLYOFFICE 文档中心（可选）

若授权版本包含文档中心在线编辑能力，需额外部署 ONLYOFFICE Document Server，并确保：

• 用户浏览器能访问 Document Server 地址
• Document Server 能回调 OARS 后端保存接口（网络双向可达）
• ONLYOFFICE 软件许可由客户自行采购（不含在 OARS 授权费内）

具体集成参数（回调 URL、JWT 等）在 OARS 管理后台配置，部署前请与技术支持确认版本与网络拓扑。

15. 升级与备份

升级前

1. 备份 MySQL 全库（mysqldump 或快照）
2. 备份上传目录（Compose 数据卷 oars-upload-data 或 file.storage.local.path）
3. 记录当前镜像 tag / 源码版本号

升级步骤

1. 获取新版本源码或镜像
2. 更新 deploy/docker/.env 中的 OARS_IMAGE_TAG（如适用）
3. 重新构建并启动：docker compose ... up -d --build
4. 观察后端日志，确认 Flyway 新迁移执行成功
5. 执行冒烟测试与关键业务回归

数据卷说明

16. 故障排查

前端能打开，接口全部失败

• 浏览器开发者工具 Network 查看 API 请求 URL 是否含 /oars
• 检查 Nginx /oars/ 反代目标是否可达
• 容器内测试：wget -qO- http://oars-backend:8080/oars/actuator/health

后端启动失败 / 反复重启

• docker logs oars-backend --tail 200 查看堆栈
• 常见原因：MySQL 未就绪、密码错误、Flyway 迁移冲突、Redis 密码不匹配
• 确认 SPRING_DATASOURCE_URL 中主机名在容器网络内可解析（Compose 内用服务名 oars-mysql）

登录成功但立即 401

• 检查 JWT 密钥是否在多实例间一致
• 确认 Redis 连通（Token 黑名单与部分会话能力依赖 Redis）

上传失败或文件 404

• 检查上传目录挂载与写权限
• Nginx client_max_body_size 是否 ≥ 80m
• 确认 /uploads/ 反代配置

端口冲突

修改 deploy/docker/.env 中 OARS_FRONTEND_PORT、OARS_BACKEND_PORT、OARS_MYSQL_PORT、OARS_REDIS_PORT 后重新启动。

附录

A. 默认端口与绑定地址

Compose 与 Podman 脚本使用相同映射（可在 deploy/docker/.env 中修改端口）：

云安全组策略见第 3.2 节。

B. 冒烟测试脚本

仓库提供 deploy/docker/podman-smoke-test.sh，对 Compose 与 Podman 均适用（检查本机 18080 / 18088 健康与前端 HTML）：

chmod +x deploy/docker/podman-smoke-test.sh
deploy/docker/podman-smoke-test.sh
# 成功时输出：Docker smoke test: OK

C. 常用命令

# 查看容器
docker compose --env-file deploy/docker/.env \
  -f deploy/docker/docker-compose.yml ps

# 跟踪后端日志
docker logs -f oars-backend

# 进入 MySQL
docker exec -it oars-mysql mysql -uroot -p

# Redis PING
docker exec oars-redis redis-cli -a <password> ping

D. 技术支持

部署过程中遇到问题，请联系 OARS 技术支持：电话 / 微信 18254181315。提供错误日志、docker compose ps 输出与环境说明可加快定位。