中科兴皖 Docker 部署指导手册

Docker中科兴皖系统部署指导

本手册帮助您在 Linux 服务器上完成预构建镜像方式的安装。交付包不含前后端源码，首次启动需联网拉取 MySQL / Redis / MinIO 等基础镜像。对外访问端口默认为 8112。

1. 概述

项目	说明
部署方式	`docker load` 导入应用镜像 + `docker compose up -d`
应用镜像	`zkxw-backend`、`zkxw-web`（已预构建，无需编译）
CPU 架构	`linux/amd64`（常见 x86 云主机；ARM 服务器需联系交付方重新打包）
对外端口	8112（Web 管理端 + API 反代）
默认账号	`admin` / `111111`（首次登录后请立即修改）

说明：MySQL、Redis、MinIO 仅在 Docker 内部网络通信，不占用宿主机 3306 / 6379 / 9000 端口，一般不会与贵方已有中间件冲突。

2. 环境要求

项	要求
操作系统	Linux x86_64（推荐 Ubuntu 22.04、CentOS 7+）
Docker	≥ 24.0
Docker Compose	v2（使用 `docker compose` 子命令）
网络	可访问 Docker Hub，或已配置国内 Registry 镜像加速
硬件建议	4 核 CPU、8 GB 内存、磁盘 ≥ 50 GB
端口	宿主机 8112 未被占用；防火墙 / 安全组已放行 TCP 8112

安装前请执行以下命令确认环境：

docker --version
docker compose version
docker info | grep -A2 "Registry Mirrors"   # 国内环境建议已配置加速

3. 交付包目录说明

解压 zkxw-docker-deploy-<版本>.tar.gz 后，目录结构如下：

zkxw-docker-deploy-<版本>/ ├── images/ │ └── zkxw-app-images.tar # 预构建前后端镜像（必做 docker load） ├── deploy/docker/ │ ├── docker-compose.yml │ ├── .env.example # 复制为 .env 后修改密码 │ ├── mysql/init/ │ └── 部署指导手册.html # 本手册 ├── docs/sql/zkxw.sql # 首次部署自动建库（非业务源码） ├── 部署说明.md # Markdown 版说明（可选阅读） └── VERSION.txt # 版本与镜像 tag 信息

不包含：后端 Python 源码、前端 Vue 源码、Dockerfile。数据库脚本仅为表结构与基线数据。

4. Docker 镜像加速（国内强烈建议）

应用镜像通过 docker load 本地导入；但首次 docker compose up 仍需从网络拉取 mysql:5.7.36、redis:7-alpine、minio/minio 等基础镜像。国内服务器建议配置 Registry 镜像加速。

编辑 /etc/docker/daemon.json（示例，任选可用加速地址）：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io"
  ]
}

sudo systemctl daemon-reload
sudo systemctl restart docker

若贵司已有阿里云 ACR 等专属加速地址，请优先使用官方提供的 URL。

5. 安装步骤

以下命令假设交付包已上传至 /opt/zkxw，请按实际路径调整。

解压交付包

mkdir -p /opt/zkxw && cd /opt/zkxw
tar -xzf zkxw-docker-deploy-*.tar.gz
cd zkxw-docker-deploy-*

导入应用镜像
```
docker load -i images/zkxw-app-images.tar
docker images | grep zkxw-
```
请记下镜像 tag（如 zkxw-backend:v1.0.0），下一步配置须一致。
配置环境变量
```
cd deploy/docker
cp .env.example .env
vi .env
```
至少修改：MYSQL_ROOT_PASSWORD、DATABASE_URL 中的密码、SECRET_KEY、MINIO_SECRET_KEY。

确认 ZKXW_BACKEND_IMAGE、ZKXW_WEB_IMAGE 与 docker images 显示的 tag 一致（可参考包内 VERSION.txt）。
启动全部服务
```
docker compose up -d
```
首次启动会自动拉取基础镜像，MySQL 导入 zkxw.sql 约需 1～3 分钟，请耐心等待。

（可选）查看启动进度

docker compose ps
docker compose logs -f mysql    # 可选，Ctrl+C 仅退出日志，不停止服务
docker compose logs -f backend

6. 配置说明（.env 要点）

默认模式 COMPOSE_PROFILES=full：自带 MySQL、Redis、MinIO。

变量	说明
`HTTP_PORT`	对外 HTTP 端口，默认 8112
`ZKXW_BACKEND_IMAGE`	后端镜像名:tag，须与 docker load 一致
`ZKXW_WEB_IMAGE`	前端镜像名:tag，须与 docker load 一致
`MYSQL_ROOT_PASSWORD`	MySQL root 密码（full 模式）
`DATABASE_URL`	数据库连接串，密码须与上面一致
`SECRET_KEY`	JWT 密钥，生产环境务必改为长随机串
`REDIS_HOST`	full 模式填 `redis`
`MINIO_ENDPOINT`	full 模式填 `minio:9000`
`MINIO_BASE_URL`	保持 `/minio/zkxw`（由 Web 镜像内 Nginx 反代）
`API_ENCRYPT_ENABLED`	默认 `false`，Docker 交付为明文 API

切勿将 .env 提交到版本库。修改密码后若服务已启动，执行 docker compose up -d 并 docker compose restart backend。

7. 验收检查

docker compose ps 中 mysql、redis、minio、backend、web 均为 running（backend/web 可为 healthy）
服务器本机：curl -s http://127.0.0.1:8112/health 返回正常
浏览器访问 http://<服务器IP>:8112/ 可打开登录页
使用 admin / 111111 登录成功（登录后请改密）
防火墙 / 安全组已放行 TCP 8112

地址	说明
`http://<IP>:8112/`	Web 管理端
`http://<IP>:8112/health`	健康检查
`http://<IP>:8112/docs`	Swagger API 文档

8. 服务架构

浏览器 :8112 └── web（Nginx + 前端静态） ├── /api/* → backend:8111（FastAPI） └── /minio/zkxw/* → minio:9000（附件，容器内网络） backend → mysql:3306（业务库 zkxw） → redis:6379（会话） → minio:9000（对象存储）

9. 部署模式（高级）

通过 .env 中 COMPOSE_PROFILES 切换，默认无需修改。

9.1 full（默认，全栈）

COMPOSE_PROFILES=full

启动 MySQL + Redis + MinIO + 后端 + 前端，适合独立部署一台服务器。

9.2 app（仅应用，连接已有中间件）

若贵方已有 MySQL、Redis、MinIO，可设为 COMPOSE_PROFILES=app，并将 DATABASE_URL、REDIS_HOST、MINIO_* 改为实际地址。具体示例见 deploy/docker/.env.example 注释。

9.3 app,storage（外部库 + 自带 MinIO）

已有 MySQL/Redis，仅 MinIO 由本 compose 提供时使用。

使用外部 MinIO 且不在 Docker 网络内时，可能需要交付方重新构建 Web 镜像。一般建议先按默认 full 模式完成安装。

10. 日常运维命令

以下命令均在 deploy/docker 目录执行：

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f backend
docker compose logs -f web

# 重启
docker compose restart

# 停止（不删数据卷）
docker compose down

# 进入后端容器
docker compose exec backend bash

警告：docker compose down -v 会删除所有数据卷（MySQL、MinIO 等），导致数据丢失。仅在首次部署失败且可接受清空数据时使用。

11. 备份与升级

11.1 数据卷

卷名（前缀 zkxw_）	内容
mysql_data	MySQL 业务数据
redis_data	Redis 持久化
minio_data	附件对象
backend_uploads	本地上传目录（若使用本地存储）

11.2 MySQL 备份示例

docker compose exec mysql mysqldump -uroot -p zkxw > zkxw_backup.sql

11.3 版本升级

备份数据库与 MinIO 数据
解压新版本交付包，docker load -i images/zkxw-app-images.tar
更新 .env 中 ZKXW_BACKEND_IMAGE、ZKXW_WEB_IMAGE
在 deploy/docker 执行 docker compose up -d
curl -s http://127.0.0.1:8112/health 验收

若仅有数据库结构变更，请使用交付方提供的增量 SQL，不要删除已有 mysql_data 卷。

12. 常见问题

无法访问 8112

检查云主机安全组 / 防火墙是否放行 TCP 8112
docker compose ps 确认 web 为 running
docker compose logs web 查看 Nginx 日志

/api 返回 502

后端未就绪：docker compose logs backend
首次部署 MySQL 仍在导入：等待 1～3 分钟后重试

拉取 mysql/redis/minio 镜像失败或很慢

请按第 4 节配置 Docker Registry 镜像加速后，重新执行 docker compose up -d。

附件无法显示

确认 STORAGE_TYPE=minio
docker compose logs minio-init 应显示 bucket 创建成功
浏览器中附件 URL 应为 /minio/zkxw/...

首次部署数据库初始化失败（可清空重来）

cd deploy/docker
docker compose down -v
docker compose up -d

此操作会清空所有数据，仅适用于尚未正式上线的环境。