Docker 部署指南

最后更新: 5 天前

实践版本: v4.0.0

本篇文档将详细介绍如何基于 Docker 部署 ContiNew Admin 项目到生产环境的完整流程。

环境要求

以下是 Docker 部署所需的运行环境，请确保您的环境符合要求，以减少因环境差异导致的问题。

运行环境	推荐版本	最低版本	安装教程
Docker	24.0.7	19.x+	《Ubuntu 安装 Docker、Docker Compose》
Docker Compose	2.23.0	-	-

准备工作

在项目打包部署前，请确保已按生产要求正确配置前、后端环境。

后端配置

默认提供的后端 Dockerfile 基于 application-prod.yml 配置运行，请务必确认并修改以下关键配置项：

数据源连接池配置
SQL 日志打印（生产环境默认关闭）
接口文档（生产环境默认关闭）
日志级别（生产环境默认 INFO）

日志配置

除修改 application-prod.yml 中的日志级别配置外，还需在 logback-spring.xml 文件中调整日志配置。重点关注环境配置部分，若重命名或新增环境，需修改 <springProfile> 标签的 name 属性。

logback-spring.xml

xml

<!-- 开发环境：只打印到控制台 -->
<springProfile name="dev">
    <!-- 如果配置的日志等级与 application.yml 中的日志等级配置重叠，application.yml 配置优先级更高 -->
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</springProfile>

<!-- 生产环境：打印到控制台并输出到文件 -->
<springProfile name="prod">
    <root level="INFO">
        <appender-ref ref="CONSOLE_PROD"/>
        <appender-ref ref="ASYNC_FILE"/>
    </root>
    <!-- 日志保留天数（根据国家法律，网络运行状态、网络安全事件、个人敏感信息操作等相关记录，留存的日志不少于六个月，并且进行网络多机备份。） -->
    <property name="FILE_MAX_HISTORY" value="180"/>
</springProfile>

跨域配置

本项目通过后端控制跨域，请及时修改配置文件中的跨域设置。跨域问题需通过正确配置解决，而非简单设置为 false。

application-prod.yml

yaml

--- ### 跨域配置
continew-starter.web.cors:
  enabled: true
  # 配置允许跨域的域名（可配置多个，并列追加 - 即可）
  allowed-origins:
    - ${application.url}
    - https://another-domain.com
  # 配置允许跨域的请求方式
  allowed-methods: '*'
  # 配置允许跨域的请求头
  allowed-headers: '*'
  # 配置允许跨域的响应头
  exposed-headers: '*'

前端配置

pnpm build 命令默认使用 .env.production 配置文件进行构建，请确认并修改以下配置项。

后端接口地址配置

本项目演示环境采用前、后端不同域名部署方式，若采用相同方式，直接修改接口地址即可。

.env.production

# 接口地址（开启 SSL：https、wss；未开启 SSL：http、ws）
VITE_API_BASE_URL = 'https://api.continew.top'
VITE_API_WS_URL = 'wss://api.continew.top'

若采用前、后端同域名部署方式，需修改接口前缀及接口地址，并同步放开默认提供的 Nginx 配置文件中的对应代理配置。

.env.production

# 接口前缀
VITE_API_PREFIX = '/api'

# 接口地址（开启 SSL：https、wss；未开启 SSL：http、ws）
VITE_API_BASE_URL = 'http://localhost:18000'
VITE_API_WS_URL = 'ws://localhost:18000'

nginx.conf

nginx

# /api/ 代理到后端（如果使用 /api/ 前缀代理而不使用 api 域名提供后端服务，可放开此配置）
location /api/ {
    proxy_pass http://admin-server/;
    proxy_ignore_client_abort on;
    proxy_http_version 1.1;

    # Proxy headers
    proxy_set_header Upgrade           $http_upgrade;
    proxy_set_header Connection        "Upgrade";
    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;
}

是否启用应用配置面板

为方便演示，默认配置为 true。若无需此功能，建议设置为 false。

.env.production

# 应用配置面板
VITE_APP_SETTING = false

项目打包

后端打包

在 continew-admin 根目录下打开终端，执行以下命令进行后端打包：

bash

mvn clean package

打包完成后，continew-server/target/app 目录下的内容即为后端项目部署物料，结构如下：

app
├─ bin（核心程序目录）
│  └─ continew-admin.jar
├─ config（配置文件目录）
│  ├─ application.yml
│  ├─ application-dev.yml（dev 环境配置文件，可自行删除）
│  └─ application-prod.yml（生产环境配置文件）
└─ lib（依赖 jar 目录）

随后，将 app 目录下的所有内容复制到 continew-admin/docker/continew-admin 目录下。

若需使用定时任务，还需将 continew-extension/continew-extension-schedule-server/target/continew-extension-schedule-server.jar 复制到 continew-admin/docker/schedule-server 目录下（也可直接基于 Snail Job 官方 Docker 镜像部署）。

后端打成一个 jar 包

从 v1.3.0 开始，项目打包结构进行了拆分优化（方便 CI/CD 按需上传），打包出的 jar 包较小（我们称为"瘦包"）。若需将依赖、配置文件等打包为一个 jar 包（我们称为"胖包"），可修改 continew-server/pom.xml 中的构建配置。

将 <plugins> 标签完整替换为以下内容：

continew-server/pom.xml

xml

<build>
   <plugins>
       <!-- Spring Boot 打包插件（将 Spring Boot Maven 应用打包为可执行的 jar 包） -->
       <plugin>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-maven-plugin</artifactId>
           <configuration>
             <includeSystemScope>true</includeSystemScope>
           </configuration>
           <executions>
               <execution>
                   <goals>
                       <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

如要打成“胖包”，可删除 docker-compose.yml 文件中 continew-server 容器的如下 volumes 配置项。

shell

- /docker/continew-admin/config/:/app/config/
- /docker/continew-admin/lib/:/app/lib/

温馨提示

曾发现个别用户部署时出现 Error: Could not find or load main class top.continew.admin.ContiNewAdminApplication 错误，本地运行正常但 Docker 部署到 Linux 服务器时出错，最终通过修改为打成一个 jar 包（"胖包"）解决。

替换完 bin 目录下的 jar 包后（lib 目录、config 目录如果你没有特殊需求，可直接删除），如果你已经使用 docker-compose 启动过容器，请执行下方命令重新构建镜像及启动容器。

shell

docker-compose up --force-recreate --build -d continew-server

前端打包

在 continew-admin-ui 目录下打开终端，执行以下命令进行前端打包：

bash

pnpm build

打包完成后，dist 目录下的内容即为前端项目部署物料。将 dist 目录下的所有内容复制到 continew-admin/docker/continew-admin/html 目录下。

部署前配置

完成上述步骤后，continew-admin/docker 部署目录结构应如下所示。接下来进行最后的配置调整。

docker
├─ nginx（Nginx 容器挂载目录）
│  └─ conf
│     └─ nginx.conf
├─ redis（Redis 容器挂载目录）
│  ├─ conf
│  │  └─ redis.conf
│  └─ data
├─ continew-admin（ContiNew Admin 部署目录及后端容器挂载目录）
│  ├─ Dockerfile
│  ├─ bin
│  ├─ config
│  ├─ lib
│  └─ html
├─ schedule-server（任务调度服务端部署目录及容器挂载目录，如不需要定时任务可删除）
│  ├─ Dockerfile
│  └─ continew-extension-schedule-server.jar
└─ docker-compose.yml（Docker Compose 部署脚本）

Docker Compose 配置

编辑 docker/docker-compose.yml 文件，根据实际需求修改以下配置项：

MySQL 配置
Redis 配置
ContiNew Admin Web 配置（Nginx 配置）
ContiNew Admin Server 配置
Schedule Server 配置（可选，如不需要定时任务可删除该段配置）

注意事项

端口号修改后，需确保所有相关配置文件（如 Nginx、应用配置等）中的对应端口也同步更新。

修改 redis.conf

在 docker/redis/conf/redis.conf 中，根据实际需要修改以下配置：

bind 指定 Redis 绑定的网络地址，默认 0.0.0.0 可选
requirepass Redis 密码必选
appendonly 是否启用 AOF 可选

修改 nginx.conf

在 docker/nginx/conf/nginx.conf 中，根据实际需要修改以下关键配置：

upstream admin-server.server 后端服务地址必选
server.listen Nginx 服务监听端口两处配置，必选
server.server_name Nginx 服务监听域名两处配置，必选
server.ssl_certificate SSL 证书位置（.pem）两处配置，必选
server.ssl_certificate_key SSL 证书位置（.key）两处配置，必选

温馨提示

若无需开启 HTTPS，可删除所有 server.ssl_xxx 配置，修改 server.listen 监听端口为 80，并删除将 HTTP 请求转发到 HTTPS 的 Server 配置。

部署运行

将部署目录 continew-admin/docker 完整上传到服务器的 / 根目录。

shell

# 为部署目录设置权限
chmod -R 777 /docker

# 进入部署目录
cd /docker

# 创建并后台运行所有容器
docker-compose up -d

等待镜像下载、构建及容器启动完成后，可使用以下命令检查部署状态：

shell

# 查看已下载的镜像列表
docker images

# 查看所有容器状态
docker ps -a

# 查看指定容器的实时运行日志
docker logs -f <容器名称或ID>

部署完成后，/docker/continew-admin 目录结构如下：

/docker
 ├─ continew-admin（ContiNew Admin 部署目录及后端容器挂载目录）
 │  ├─ bin（核心程序）
 │  ├─ config（配置文件）
 │  ├─ lib（依赖 jar）
 │  ├─ html（前端部署物料）
 │  ├─ data（本地文件数据存储，自动生成）
 │  ├─ logs（日志，自动生成）
 │  └─ Dockerfile
 └─ 其他略...

友情提示

🎉 恭喜你！你已经成功完成 ContiNew Admin 项目的部署！果然难不倒你！如果这个过程中遇到了未知错误，你也确认自己操作无误的话，可以在常见问题中先找找看。

项目每增长一颗 star，可以给维护者们注入莫大的激情，诚恳的希望您能动动发财的小手，为 ContiNew Admin 点亮一颗小星星。

常见问题

项目启动后，访问 URL 提示跨域错误

开发环境（dev）的跨域配置默认设置为 *（放行所有域名），而生产环境（prod）的跨域配置则限制为项目前端 URL。若遇到跨域问题，请首先确认 application-prod.yml：

前端项目 URL 是否已正确修改
后端项目的跨域配置是否正确

若确认配置无误，可尝试关闭本地 V*N 等代*软件后重试。

图形验证码接口报 load font error 错误

问题描述： 访问图形验证码接口时，控制台报错 load font error，无法正常生成验证码图片。

原因分析： 该错误通常是由于服务器环境中缺少字体配置工具 fontconfig 导致的。验证码生成需要系统支持字体渲染，而 fontconfig 是 Linux 系统中管理字体的标准工具。

解决方案：

根据 Linux 发行版，执行以下命令安装字体配置工具：

CentOS/RHEL 系统：
bash
```
yum install fontconfig -y
```
Debian/Ubuntu 系统：
bash
```
apt-get install fontconfig -y
```

Docker 部署指南 ​

环境要求 ​

准备工作 ​

后端配置 ​

日志配置 ​

跨域配置 ​

前端配置 ​

后端接口地址配置 ​

是否启用应用配置面板 ​

项目打包 ​

后端打包 ​

后端打成一个 jar 包 ​

前端打包 ​

部署前配置 ​

Docker Compose 配置 ​

修改 redis.conf ​

修改 nginx.conf ​

部署运行 ​

常见问题 ​

Docker 部署指南

环境要求

准备工作

后端配置

日志配置

跨域配置

前端配置

后端接口地址配置

是否启用应用配置面板

项目打包

后端打包

后端打成一个 jar 包

前端打包

部署前配置

Docker Compose 配置

修改 redis.conf

修改 nginx.conf

部署运行

常见问题