安装部署操作手册

文档信息

属性	值
文档版本	v1.0
创建日期	2026-06-04
适用项目	BSG-WM 仓库管理系统
部署方式	Docker Swarm

1. 部署概述

BSG-WM 仓库管理系统采用 Docker Swarm 容器编排技术进行部署，包含以下核心服务：

服务名称	说明
mysql	MySQL 9.7.0 数据库服务
redis	Redis 8.6.3 缓存服务
otel-lgtm	OpenTelemetry + Grafana 监控服务
nginx	Nginx 1.31.0 反向代理服务
admin	前端 PC 管理平台
server	后端 API 服务
docs	文档服务

2. 环境要求

2.1 硬件要求

配置项	最低配置	推荐配置
CPU	2核	4核
内存	4GB	8GB
磁盘	50GB	100GB
网络	100Mbps	1Gbps

2.2 操作系统要求

支持以下 Linux 发行版：

发行版	版本	包管理器
Debian/Ubuntu	18.04+	apt
CentOS/RHEL	7+	yum/dnf
Fedora	34+	dnf
SUSE	15+	zypper
Alpine	3.14+	apk

2.3 软件依赖要求

依赖	版本	说明
Docker	20.10+	容器运行时
Docker Compose	2.0+	容器编排工具
Git	2.0+	代码版本控制
curl	7.0+	HTTP 请求工具
NFS	-	网络文件系统（用于数据持久化）

3. 部署架构

3.1 网络架构

3.2 目录结构

/wm/                              # 安装根目录
├── code/                         # 代码目录
│   └── bsg-wm/                   # Git 仓库代码
├── conf/                         # 配置目录
│   ├── mysql/                    # MySQL 配置
│   │   └── password.txt          # MySQL 密码文件
│   ├── redis/                    # Redis 配置
│   │   └── password.txt          # Redis 密码文件
│   ├── nginx/                    # Nginx 配置
│   ├── admin/                    # Admin 配置
│   ├── server/                   # Server 配置
│   ├── .env                      # 环境变量文件
│   └── compose.yaml              # Docker Compose 文件
├── data/                         # 数据目录
│   ├── mysql/                    # MySQL 数据
│   ├── redis/                    # Redis 数据
│   ├── otel-lgtm/                # 监控数据
│   └── nginx/                    # Nginx 数据
└── logs/                         # 日志目录
    └── server/                   # Server 日志

4. 一键安装部署

4.1 前提条件

以 root 用户或 sudo 权限执行安装脚本
服务器已连接互联网，可访问 Gitee 和 Docker Registry

4.2 执行一键安装

# 方式一：使用默认配置安装到 /wm 目录
bash install.sh

# 方式二：指定安装目录
bash install.sh -d /opt/wm

# 方式三：指定安装目录并选择镜像模式
bash install.sh -d /opt/wm -m pull

4.3 命令行参数说明

参数	说明	默认值
`-h`, `--help`	显示帮助信息	-
`-d`, `--dir`	指定安装目录	`/wm`
`-m`, `--mode`	镜像获取模式：`pull`（拉取）或 `build`（构建）	`pull`

4.4 安装流程

一键安装脚本会自动执行以下步骤：

权限检查 → 验证 root 权限
系统检查 → 检测操作系统和包管理器
依赖检查 → 检查并安装 curl、git、tar
Docker检查 → 检查 Docker 和初始化 Swarm
目录创建 → 创建必要的目录结构
代码克隆 → 从 Gitee 克隆代码仓库
配置复制 → 复制配置文件到指定目录
密码设置 → 设置 MySQL 和 Redis 密码
NFS配置 → 配置网络文件系统
镜像准备 → 拉取或构建 Docker 镜像
服务部署 → 使用 Docker Stack 部署服务
健康检查 → 验证所有服务启动状态

5. 手动分步部署

5.1 步骤一：环境准备

# 1. 更新系统包
sudo apt update && sudo apt upgrade -y  # Debian/Ubuntu
# 或
sudo yum update -y                      # CentOS/RHEL

# 2. 安装必要依赖
sudo apt install -y curl git tar        # Debian/Ubuntu
# 或
sudo yum install -y curl git tar        # CentOS/RHEL

# 3. 安装 Docker
curl -fsSL https://get.docker.com | sudo sh

# 4. 启动 Docker 服务
sudo systemctl enable --now docker

# 5. 初始化 Docker Swarm
sudo docker swarm init

5.2 步骤二：创建目录结构

# 设置安装目录
WM_DIR="/wm"

# 创建核心目录
sudo mkdir -p ${WM_DIR}/code
sudo mkdir -p ${WM_DIR}/conf/{mysql,redis,nginx,admin,server}
sudo mkdir -p ${WM_DIR}/data/{mysql,redis,otel-lgtm,nginx}
sudo mkdir -p ${WM_DIR}/logs/server

# 设置目录权限
sudo chmod 755 ${WM_DIR}/code
sudo chmod 755 ${WM_DIR}/conf
sudo chmod 755 ${WM_DIR}/data
sudo chmod 777 ${WM_DIR}/logs/server

5.3 步骤三：克隆代码仓库

cd ${WM_DIR}/code
git clone https://gitee.com/ice-run/bsg-wm.git

5.4 步骤四：配置文件复制

# 复制配置文件
cp -a ${WM_DIR}/code/bsg-wm/docker/. ${WM_DIR}/conf/

# 移动脚本文件
mv ${WM_DIR}/conf/build.sh ${WM_DIR}/code/
mv ${WM_DIR}/conf/deploy.sh ${WM_DIR}/

# 设置执行权限
chmod +x ${WM_DIR}/code/build.sh
chmod +x ${WM_DIR}/deploy.sh

5.5 步骤五：配置环境变量

编辑 ${WM_DIR}/conf/.env 文件：

# 项目配置
WM_DIR=/wm
WM_NAMESPACE=wm
WM_IMAGE_REGISTRY=registry.cn-beijing.aliyuncs.com
WM_IMAGE_NAMESPACE=daodao-bot
WM_IMAGE_TAG=latest

# NFS 配置
WM_NFS_HOST=127.0.0.1

# 数据库密码（运行时自动生成）
# MYSQL_PASSWORD=
# REDIS_PASSWORD=

5.6 步骤六：设置数据库密码

# 设置 MySQL 密码
MYSQL_PASSWORD=$(tr -dc '0-9A-Za-z_-' < /dev/urandom | head -c 8)
echo ${MYSQL_PASSWORD} > ${WM_DIR}/conf/mysql/password.txt

# 设置 Redis 密码
REDIS_PASSWORD=$(tr -dc '0-9A-Za-z_-' < /dev/urandom | head -c 8)
echo ${REDIS_PASSWORD} > ${WM_DIR}/conf/redis/password.txt

5.7 步骤七：配置 NFS 服务

# 安装 NFS 服务
sudo apt install -y nfs-kernel-server  # Debian/Ubuntu
# 或
sudo yum install -y nfs-utils          # CentOS/RHEL

# 配置导出目录
echo "${WM_DIR} 127.0.0.1(rw,sync,no_subtree_check,no_root_squash)" >> /etc/exports
echo "${WM_DIR} ::1(rw,sync,no_subtree_check,no_root_squash)" >> /etc/exports

# 刷新导出配置
sudo exportfs -r

# 启动 NFS 服务
sudo systemctl enable --now nfs-kernel-server  # Debian/Ubuntu
# 或
sudo systemctl enable --now nfs-server         # CentOS/RHEL

5.8 步骤八：拉取或构建镜像

方式一：拉取镜像

# 登录 Docker Registry（如需）
docker login ${WM_IMAGE_REGISTRY}

# 拉取镜像
docker pull ${WM_IMAGE_REGISTRY}/${WM_IMAGE_NAMESPACE}/bsg-wm-server:${WM_IMAGE_TAG}
docker pull ${WM_IMAGE_REGISTRY}/${WM_IMAGE_NAMESPACE}/bsg-wm-admin:${WM_IMAGE_TAG}

方式二：本地构建镜像

cd ${WM_DIR}/code
./build.sh bsg-wm-server ${WM_IMAGE_TAG}
./build.sh bsg-wm-admin ${WM_IMAGE_TAG}

5.9 步骤九：部署服务

# 替换配置文件中的变量
sed -i "s|\${WM_DIR}|${WM_DIR}|g" ${WM_DIR}/conf/compose.yaml
sed -i "s|\${MYSQL_PASSWORD}|${MYSQL_PASSWORD}|g" ${WM_DIR}/conf/compose.yaml
sed -i "s|\${REDIS_PASSWORD}|${REDIS_PASSWORD}|g" ${WM_DIR}/conf/compose.yaml
sed -i "s|\${WM_NFS_HOST}|${WM_NFS_HOST}|g" ${WM_DIR}/conf/compose.yaml

# 部署 Docker Stack
docker stack deploy -c ${WM_DIR}/conf/compose.yaml ${WM_NAMESPACE}

6. 服务配置说明

6.1 服务端口映射

服务	容器端口	宿主机端口	说明
mysql	3306	3306	数据库端口
redis	6379	6379	缓存端口
otel-lgtm	3000	3000	Grafana 监控面板
otel-lgtm	4317	4317	OTLP gRPC 端口
otel-lgtm	4318	4318	OTLP HTTP 端口
nginx	80	80	HTTP 端口
nginx	443	443	HTTPS 端口

6.2 环境变量说明

后端服务 (server)

变量名	说明	默认值
SERVER_PORT	服务端口	80
MYSQL_URL	MySQL 连接地址	jdbc:mysql://mysql:3306/wm
MYSQL_USERNAME	MySQL 用户名	root
MYSQL_PASSWORD	MySQL 密码	-
REDIS_HOST	Redis 主机	redis
REDIS_PORT	Redis 端口	6379
REDIS_PASSWORD	Redis 密码	-
REDIS_DATABASE	Redis 数据库	1

MySQL 服务 (mysql)

变量名	说明	默认值
MYSQL_ROOT_PASSWORD	root 用户密码	-
character-set-server	字符集	utf8mb4
collation-server	排序规则	utf8mb4_bin

Redis 服务 (redis)

变量名	说明	默认值
REDIS_PASSWORD	访问密码	-

7. 启动与停止

7.1 查看服务状态

# 查看所有服务
docker stack services ${WM_NAMESPACE}

# 查看服务日志
docker service logs ${WM_NAMESPACE}_server -f

# 查看容器列表
docker ps -a

7.2 停止服务

# 停止并移除 Stack
docker stack rm ${WM_NAMESPACE}

7.3 重启服务

# 重新部署（配置变更后）
docker stack deploy -c ${WM_DIR}/conf/compose.yaml ${WM_NAMESPACE}

# 重启特定服务
docker service update --force ${WM_NAMESPACE}_server

8. 健康检查

8.1 服务健康检查

# 检查所有服务状态
docker stack services ${WM_NAMESPACE}

# 检查后端服务健康端点
curl http://localhost:80/actuator/health

# 检查 MySQL 连接
mysql -h localhost -u root -p -e "SELECT VERSION();"

# 检查 Redis 连接
redis-cli -h localhost -a ${REDIS_PASSWORD} ping

8.2 预期健康状态

服务	状态	说明
mysql	running	1/1 副本运行
redis	running	1/1 副本运行
otel-lgtm	running	1/1 副本运行
nginx	running	全局模式运行
admin	running	1/1 副本运行
server	running	1/1 副本运行
docs	running	1/1 副本运行

9. 常见问题

9.1 Docker Swarm 初始化失败

问题：docker swarm init 失败

解决方案：

# 检查网络配置
ip addr show

# 使用指定 IP 初始化
docker swarm init --advertise-addr <服务器IP>

9.2 NFS 挂载失败

问题：容器无法挂载 NFS 卷

解决方案：

# 检查 NFS 服务状态
systemctl status nfs-kernel-server

# 检查导出配置
cat /etc/exports

# 重新导出
exportfs -r

9.3 数据库连接失败

问题：后端服务无法连接 MySQL

解决方案：

# 检查 MySQL 容器日志
docker service logs ${WM_NAMESPACE}_mysql

# 验证密码文件
cat ${WM_DIR}/conf/mysql/password.txt

# 检查网络连通性
docker exec -it <mysql-container> ping server

9.4 镜像拉取失败

问题：无法从 Registry 拉取镜像

解决方案：

# 检查网络连接
curl -I ${WM_IMAGE_REGISTRY}

# 重新登录 Registry
docker login ${WM_IMAGE_REGISTRY}

# 检查镜像标签是否存在
docker search ${WM_IMAGE_REGISTRY}/${WM_IMAGE_NAMESPACE}/bsg-wm-server

9.5 服务启动超时

问题：健康检查超时，服务未正常启动

解决方案：

# 查看服务日志
docker service logs ${WM_NAMESPACE}_server -f

# 检查资源限制
docker service inspect ${WM_NAMESPACE}_server

# 增加启动等待时间
# 修改 compose.yaml 中的 healthcheck start_period

附录：默认访问信息

服务	地址	用户名	密码
前端管理平台	http://服务器IP	admin	admin
监控面板	http://服务器IP:3000	admin	admin
后端 API	http://服务器IP/api	-	-

文档版本: v1.0
创建日期: 2026-06-04
适用项目: BSG-WM 仓库管理系统

文档信息​

1. 部署概述​

2. 环境要求​

2.1 硬件要求​

2.2 操作系统要求​

2.3 软件依赖要求​

3. 部署架构​

3.1 网络架构​

3.2 目录结构​

4. 一键安装部署​

4.1 前提条件​

4.2 执行一键安装​

4.3 命令行参数说明​

4.4 安装流程​

5. 手动分步部署​

5.1 步骤一：环境准备​

5.2 步骤二：创建目录结构​

5.3 步骤三：克隆代码仓库​

5.4 步骤四：配置文件复制​

5.5 步骤五：配置环境变量​

5.6 步骤六：设置数据库密码​

5.7 步骤七：配置 NFS 服务​

5.8 步骤八：拉取或构建镜像​

5.9 步骤九：部署服务​

6. 服务配置说明​

6.1 服务端口映射​

6.2 环境变量说明​

后端服务 (server)​

MySQL 服务 (mysql)​

Redis 服务 (redis)​

7. 启动与停止​

7.1 查看服务状态​

7.2 停止服务​

7.3 重启服务​

8. 健康检查​

8.1 服务健康检查​

8.2 预期健康状态​

9. 常见问题​

9.1 Docker Swarm 初始化失败​

9.2 NFS 挂载失败​

9.3 数据库连接失败​

9.4 镜像拉取失败​

9.5 服务启动超时​

附录：默认访问信息​

文档信息

1. 部署概述

2. 环境要求

2.1 硬件要求

2.2 操作系统要求

2.3 软件依赖要求

3. 部署架构

3.1 网络架构

3.2 目录结构

4. 一键安装部署

4.1 前提条件

4.2 执行一键安装

4.3 命令行参数说明

4.4 安装流程

5. 手动分步部署

5.1 步骤一：环境准备

5.2 步骤二：创建目录结构

5.3 步骤三：克隆代码仓库

5.4 步骤四：配置文件复制

5.5 步骤五：配置环境变量

5.6 步骤六：设置数据库密码

5.7 步骤七：配置 NFS 服务

5.8 步骤八：拉取或构建镜像

5.9 步骤九：部署服务

6. 服务配置说明

6.1 服务端口映射

6.2 环境变量说明

后端服务 (server)

MySQL 服务 (mysql)

Redis 服务 (redis)

7. 启动与停止

7.1 查看服务状态

7.2 停止服务

7.3 重启服务

8. 健康检查

8.1 服务健康检查

8.2 预期健康状态

9. 常见问题

9.1 Docker Swarm 初始化失败

9.2 NFS 挂载失败

9.3 数据库连接失败

9.4 镜像拉取失败

9.5 服务启动超时

附录：默认访问信息