Appearance
Docker 部署
本文说明 OARS 前后端容器化部署方式。当前交付支持两种路径：
- Docker Compose：适合客户服务器或标准容器环境。
- Podman 脚本：适合本地验证或没有
podman compose的环境。
目录结构
容器部署文件位于源码根目录：
text
deploy/docker/
├── backend.Dockerfile
├── frontend.Dockerfile
├── frontend.nginx.conf.template
├── docker-compose.yml
├── .env.example
├── podman-build.sh
├── podman-up.sh
├── podman-down.sh
└── podman-smoke-test.sh镜像组成
| 镜像 | 构建文件 | 内容 |
|---|---|---|
oars-backend:<tag> | backend.Dockerfile | Java 21 运行时，启动 oars-app Spring Boot 服务 |
oars-frontend:<tag> | frontend.Dockerfile | Nginx 静态站点，代理 /oars 到后端 |
前端镜像构建时默认把 VITE_GLOB_API_URL 设置为 /oars。前端 Nginx 会把 /oars/ 反向代理到后端容器，因此客户环境通常只需要暴露前端端口。
环境变量
先复制环境模板：
bash
cp deploy/docker/.env.example deploy/docker/.env关键变量：
| 变量 | 默认值 | 说明 |
|---|---|---|
OARS_IMAGE_TAG | local | 后端和前端镜像标签 |
OARS_FRONTEND_PORT | 18088 | 宿主机前端端口 |
OARS_BACKEND_PORT | 18080 | 宿主机后端端口 |
OARS_MYSQL_PORT | 13306 | 宿主机 MySQL 端口 |
OARS_REDIS_PORT | 16379 | 宿主机 Redis 端口 |
OARS_MYSQL_DATABASE | oars | MySQL 数据库名 |
OARS_MYSQL_ROOT_PASSWORD | oars_root_password | MySQL root 密码 |
OARS_REDIS_PASSWORD | redis123 | Redis 密码 |
OARS_JWT_SECRET | 示例值 | JWT 密钥，生产必须修改 |
OARS_UPLOAD_DIR | /app/uploads | 后端容器内上传目录 |
OARS_JAVA_OPTS | -Xms512m -Xmx1024m | JVM 参数 |
生产环境必须替换数据库密码、Redis 密码和 JWT 密钥。
Docker Compose 部署
在源码根目录执行：
bash
cp deploy/docker/.env.example deploy/docker/.env
docker compose --env-file deploy/docker/.env -f deploy/docker/docker-compose.yml up -d --build访问：
- 前端：
http://127.0.0.1:18088/ - 后端健康检查：
http://127.0.0.1:18080/oars/actuator/health
停止：
bash
docker compose --env-file deploy/docker/.env -f deploy/docker/docker-compose.yml down如需同时删除数据卷，执行前必须确认已备份数据库和上传文件：
bash
docker compose --env-file deploy/docker/.env -f deploy/docker/docker-compose.yml down -vPodman 本地部署
没有 podman compose 时，使用仓库内脚本直接创建网络、数据卷和容器：
bash
cp deploy/docker/.env.example deploy/docker/.env
deploy/docker/podman-up.sh脚本会执行以下操作：
- 构建
oars-backend:<tag>和oars-frontend:<tag>。 - 创建
oars-net网络。 - 创建 MySQL、Redis、上传目录和日志数据卷。
- 启动 MySQL、Redis、后端和前端容器。
- 等待后端健康检查和前端页面可访问。
验证：
bash
deploy/docker/podman-smoke-test.sh停止：
bash
deploy/docker/podman-down.sh数据卷
| 数据卷 | 内容 |
|---|---|
oars-mysql-data | MySQL 数据 |
oars-redis-data | Redis AOF 数据 |
oars-upload-data | OARS 上传文件 |
oars-backend-logs | 后端日志 |
升级、回滚或删除容器前，必须先备份 oars-mysql-data 和 oars-upload-data。
配置覆盖
后端容器通过环境变量覆盖生产配置：
text
SPRING_DATASOURCE_URL
SPRING_DATASOURCE_USERNAME
SPRING_DATASOURCE_PASSWORD
SPRING_DATA_REDIS_HOST
SPRING_DATA_REDIS_PORT
SPRING_DATA_REDIS_PASSWORD
JWT_SECRET
FILE_STORAGE_LOCAL_PATH
JAVA_OPTS前端容器运行时通过 Nginx 模板读取：
text
OARS_BACKEND_UPSTREAM=oars-backend:8080如客户使用外部数据库或 Redis，可以删除 Compose 中对应服务，改为把后端环境变量指向外部地址。
升级流程
客户环境升级按以下顺序执行：
- 备份 MySQL 数据和上传文件。
- 拉取或合并新的客户源码 tag。
- 更新
deploy/docker/.env中的镜像标签。 - 重新构建镜像。
- 启动新容器，让 Flyway 执行数据库迁移。
- 执行健康检查和关键业务回归。
Docker Compose：
bash
docker compose --env-file deploy/docker/.env -f deploy/docker/docker-compose.yml up -d --buildPodman：
bash
deploy/docker/podman-up.sh
deploy/docker/podman-smoke-test.sh回滚边界
源码和镜像可以回退到上一客户 tag 后重新部署。数据库不能通过删除迁移记录回滚；生产环境应使用备份恢复，或追加前向修复脚本。
podman-down.sh 和 docker compose down 默认只删除容器，不删除数据卷。
常见问题
前端能打开但接口不通
检查前端容器内 Nginx 代理目标：
bash
podman exec oars-frontend env | grep OARS_BACKEND_UPSTREAM
podman exec oars-frontend wget -qO- http://oars-backend:8080/oars/actuator/health后端启动失败
查看日志：
bash
podman logs --tail 200 oars-backend重点检查数据库地址、Redis 密码、Flyway 迁移和上传目录权限。
端口冲突
修改 deploy/docker/.env 中的宿主机端口，例如 OARS_FRONTEND_PORT、OARS_BACKEND_PORT、OARS_MYSQL_PORT、OARS_REDIS_PORT。