部署运维

客户单机部署推荐随包 Docker 方案，包含 Java、MySQL 和 Redis，MinIO 按需启用。前端独立构建部署，Java 容器不包含页面。生产需要域名、HTTPS 证书及持久化存储。

先选部署方式

场景	使用方式
新服务器，数据库也随项目部署	下文 Docker 首次安装
客户已有 MySQL / Redis	下文 JAR 交付，或独立应用容器
只在本机开发	快速开始，不要执行生产 update

本页命令默认在 Linux/macOS Shell 执行。Docker 命令在后端源码根目录执行；JAR 命令在独立发布目录执行。数据库、存储、域名和端口使用客户实际值。

上服务器前准备

准备配套前后端源码、可用的镜像/Maven 下载网络、前端域名及证书、持久化空间和备份位置。Docker 主机同时承担 Java、MySQL、Redis 及构建的资源消耗，容量按实际负载验证。

生产验收至少覆盖普通角色登录、文件上传下载、会话刷新和已启用业务。支付、外部模型、对象存储分别用客户的服务配置验证。

Docker 首次安装

服务器安装 Docker Engine 与 Compose v2（支持 --wait），并能访问镜像和 Maven 仓库。无需在服务器另装 Java、Maven、Node.js 或 Python。

在后端根目录执行，Origin 替换为实际前端网站，不附加路径或末尾斜杠：

sh scripts/deploy.sh init https://admin.example.com

检查生成的 config/application-prod.yml 与 deploy/compose.prod.yml，再启动：

sh scripts/deploy.sh update
curl --fail http://127.0.0.1:13001/actuator/health

init 首次构建镜像用于 YAML 初始化，不启动业务、不覆盖已有文件。update 构建并检查后更新服务。MySQL 初始化凭据只对空数据卷有效，已有库修改密码需实际轮换数据库账号，不能仅重新生成 YAML。

默认 API 仅绑定本机 127.0.0.1:13001。MySQL root 凭据保存在部署 YAML，业务应用使用应用账号。两份实际 YAML 不进入镜像或 Git。

部署前端和网关

前端 .env.production 使用实际 API 基础地址。同域网关可用 VITE_API_URL=/，静态文件部署后由 Nginx 转发 /api/。详细前端构建见 前端部署。

在前端源码目录编辑 .env.production 后执行：

pnpm install
pnpm build

将生成的 dist/ 内部文件发布到 Nginx 静态目录。VITE_API_PROXY_URL 只用于开发代理；生产请求转发由 Nginx 负责。前端构建不要求部署服务器安装 Node.js，可以在构建机生成产物后上传。

下面是同一台主机上 Nginx 转发 Java 的完整站点示例。替换域名、证书和静态目录后，加入 Nginx 的 http 配置中：

server {
    listen 80;
    server_name admin.example.com;
    return 301 https://admin.example.com$request_uri;
}

server {
    listen 443 ssl;
    server_name admin.example.com;
    ssl_certificate /etc/nginx/certs/admin.example.com.pem;
    ssl_certificate_key /etc/nginx/certs/admin.example.com.key;
    root /var/www/art-admin;
    index index.html;
    client_max_body_size 20m;

    location ^~ /api/ {
        # 不带末尾 /，保留请求中的 /api/ 路径。
        proxy_pass http://127.0.0.1:13001;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        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_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        # 通知和 AI 使用 SSE，关闭缓冲以便逐步显示内容。
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
    location ~* \.html$ {
        add_header Cache-Control "no-cache";
    }
    location / {
        try_files $uri $uri/ /index.html;
    }
}

已有站点只合并需要的设置，保留其他网站。运行 nginx -t 通过后再 nginx -s reload。如果 Nginx 自身运行在容器内，127.0.0.1:13001 指的是 Nginx 容器，需要改成它实际可达的后端地址。

外置配置 app.web.cors.allowed-origins 包含完整前端 HTTPS Origin。网关终止 TLS、内部 HTTP 转发时仍保持 app.auth.refresh-cookie-secure=true。跨站部署还需验证 SameSite=Lax 的 Cookie 行为，优先采用同站点网关。

JAR 交付

在没有运行实例依赖当前构建产物的环境中打包：

./mvnw -pl art-admin -am clean package -DskipTests

产物为 art-admin/target/art-admin.jar。-DskipTests 仅用于打包，不表示已完成发布验证。部署机准备 Java 21、MySQL、Redis，将 JAR 和仓库中的生产示例模板放到独立发布目录：

发布目录/
├── art-admin.jar
└── config/
    └── application-prod.example.yml  # 从后端源码 config/ 复制

进入该发布目录再执行下方命令。初始化工具从文件系统读取模板，示例 YAML 不在 JAR 内。实际配置已存在时保留它。

java -jar art-admin.jar --init-config=prod

填写生产 YAML 的连接和持久化上传目录，再检查、启动：

java -jar art-admin.jar --spring.profiles.active=prod --spring.config.additional-location=file:./config/ --check-config
java -jar art-admin.jar --spring.profiles.active=prod --spring.config.additional-location=file:./config/

自备数据库或独立容器使用同一应用配置。不要将随包 Compose 固定服务名照搬到无法解析这些名字的 JAR 环境。

日常操作

操作	随包命令
查看状态	sh scripts/deploy.sh status
检查构建而不更新服务	sh scripts/deploy.sh check
更新代码与镜像	sh scripts/deploy.sh update
仅应用配置变更	sh scripts/deploy.sh config
启动可选 MinIO	sh scripts/deploy.sh minio

查看应用日志：

docker compose --env-file /dev/null -p art-design-pro-x-java -f docker-compose.yml -f deploy/compose.prod.yml logs --tail=100 app

共享连接配置由部署脚本生成，不绕过脚本直接完整 Compose up。配置检查不验证依赖真实连通；更新也可能短暂中断，按实际维护窗口执行。

发布验收

检查 Flyway、健康、管理员改密、普通角色授权、刷新 Cookie、文件上传下载、通知与 AI 流式接口。Swagger 生产默认关闭，临时开启时限制访问。在线支付另做实际渠道验收。

更新、停止、备份和多实例要求见 备份与升级。完整网关模板和随包运维说明位于 Java 仓库 docs/guides/docker-setup.md。

部署完成后交给客户什么

记录前端访问地址、前后端版本、部署目录、实际端口、启用的外部服务及日常启动/日志入口。交接管理员账号后要求改密；实际 YAML、支付加密密钥、RSA 私钥与数据库备份一并受控保存。

通过 首次使用 完成业务初始化，再按 备份与升级 演练一次恢复。健康检查通过说明服务可运行，正式交付还应以客户选定的业务流程验收结果为准。