BasicPaper Gateway 部署

王金城大约 6 分钟

我们共有三个安装包，分别对应不同的 CPU 架构。自行到 178 文件服务器的 产品安装包\BasicPaperCloud\basic-paper-gateway 目录下获取对应的安装包。

x86_64: basic-paper-gateway-deploy-2.1.4-x86_64.tar.gz
ARM64: basic-paper-gateway-deploy-2.1.4-aarch64.tar.gz
x86_64 兼容模式，在较老的 CPU 上使用: basic-paper-gateway-deploy-2.1.4-x86_64-compatibility.tar.gz

📋 前提条件

在开始部署前，请确保目标服务器满足以下要求：

操作系统: Ubuntu 20.04 LTS 或更高版本（推荐 Ubuntu 24.04）。
已安装软件:
- Docker Engine (v20.10 或更高)
- Docker Compose Plugin (v2.x 或更高)
- acl 包（用于日志目录权限控制，可选项），推荐直接配置 docker-compose.yml 中的 user: 1000:1000 为宿主机用户的 UID:GID
```
sudo apt update
sudo apt install -y acl
```
网络: 服务器能访问 Nacos 服务器地址（配置在 docker-compose.yml 的 SPRING_CLOUD_NACOS_SERVER_ADDR）。
权限: 执行部署的用户需有 sudo 权限（用于创建目录和设置权限）。

📦 部署步骤

1️⃣ 解压交付包

将你收到的部署包（例如 basic-paper-gateway-deploy-2.1.4-x86_64.tar.gz）上传到目标服务器，然后解压：

# 假设文件在当前目录
tar -xzf basic-paper-gateway-deploy-2.1.4.tar.gz
cd basic-paper-gateway-deploy-2.1.4

解压后目录结构应如下：

basic-paper-gateway-deploy-2.1.4-x86_64/
├── basic-paper-gateway-2.1.4.tar  # Docker 镜像文件
└── docker-compose.yml             # 部署配置文件

2️⃣ 加载 Docker 镜像

提示

docker load 支持直接加载压缩文件，如果是 tar.gz 或 tar.xz 都可以直接加载，例如：

docker load -i basic-paper-gateway-2.1.4.tar.gz
docker load -i basic-paper-gateway-2.1.4.tar.xz

将 .tar 文件加载为本地 Docker 镜像：

docker load -i basic-paper-gateway-2.1.4.tar

✅ 验证镜像是否加载成功：
docker images | grep basic-paper-gateway
应能看到类似输出：
basic-paper-gateway   2.1.4   abc123def456   2 minutes ago   123MB

3️⃣ 准备日志目录及权限

应用配置会将日志写入 /var/simperfect/logs/bp-cloud，因此需要在宿主机上创建该目录并设置正确的权限。

# 1. 创建日志目录
sudo mkdir -p /var/simperfect/logs/bp-cloud/bak

# 2. 设置目录权限，确保容器用户(UID:GID 1000:1000)可以写入
sudo chown -R 1000:1000 /var/simperfect/logs
sudo chmod -R 755 /var/simperfect/logs

# 3. (可选) 如果需要更宽松的权限
# sudo chmod -R 777 /var/simperfect/logs

🔍 说明:
由于配置中指定了 user: 1000:1000，我们需要确保该 UID/GID 的用户对日志目录有写权限
日志将被写入到 /var/simperfect/logs/bp-cloud 和备份到 /var/simperfect/logs/bp-cloud/bak
建议在宿主机上创建对应的用户(UID 1000)以更好地管理权限，也可以直接指定使用宿主机的 UID 启动容器，详见第 4 步。

4️⃣ 检查并修改 `docker-compose.yml` 配置

打开 docker-compose.yml 文件，检查以下几项配置是否符合你的部署环境：

📍 网络模式 (`network_mode`)

network_mode: 'host'

使用 host 网络模式，直接使用宿主机网络
应用将监听在 SERVER_PORT=8000 指定的端口上
确认宿主机的 8000 端口未被占用

📍 用户配置 (`user`)

user: 1000:1000

容器将以 UID:GID 为 1000:1000 的用户身份运行
宿主机可以切换到对应用户，输入 id 可以查看当前用户的 UID 这 GID 等信息，并修改为应对的配置
确保宿主机上 /var/simperfect/logs 目录对此用户有写权限

📍 Nacos 配置 (`environment`)

environment:
  # 端口号
  - SERVER_PORT=8000
  # 配置时区，如果使用其他时区请修改
  - TZ=Asia/Shanghai
  # nacos 访问地址（必填）。配置多个，用逗号分隔开。如：127.0.0.1:8848,127.0.0.2:8848
  - SPRING_CLOUD_NACOS_SERVER_ADDR=127.0.0.1:8848
  # 命名空间（必填），用于注册中心、配置中心的数据隔离（在同一个注册中心负责多个环境时极其重要），只读取此命名空间下的配置文件。
  - SPRING_CLOUD_NACOS_NAMESPACE=bp-cloud-uat
  # nacos 账号密码（必填），注意：请务必将 nacos 服务器开启账号密码功能，并修改默认密码，严禁使用默认密码。
  - SPRING_CLOUD_NACOS_USERNAME=username
  - SPRING_CLOUD_NACOS_PASSWORD=password
  # 镜像内的日志文件输出路径，修改后需要修改 volumes 映射
  - LOGGING_FILE_PATH=/var/simperfect/logs/bp-cloud
  # 镜像内的日志文件备份路径，修改后需要修改 volumes 映射
  - LOGGING_FILE_BAK_PATH=/var/simperfect/logs/bp-cloud/bak
  # 日志留存时间（天）
  - LOGGING_LOGBACK_ROLLINGPOLICY_MAX_HISTORY=180
  # 您想要为您的服务实例注册的IP地址，如果自动检测IP工作正常，则无需设置。
  #- SPRING_CLOUD_NACOS_DISCOVERY_IP=

务必根据你的实际 Nacos 服务器信息修改以上环境变量
LOGGING_* 相关配置定义了日志文件的存储路径和保留策略

📍 日志路径 (`volumes`)

volumes:
  - /var/simperfect/logs:/var/simperfect/logs

确认 /var/simperfect/logs 目录已按第 3 步创建并设置好权限
容器内的日志将写入到映射的宿主机目录中

5️⃣ 启动服务

在 basic-paper-gateway-deploy-2.1.4-x86_64 目录下，运行以下命令启动服务：

docker compose up -d

✅ -d 参数表示在后台运行。

6️⃣ 验证服务状态

查看容器运行状态：

docker compose ps

你应该看到类似以下输出，表示容器正在运行：

NAME                      IMAGE                           COMMAND                  SERVICE             CREATED          STATUS          PORTS
basic-paper-gateway       basic-paper-gateway:2.1.4       "./gateway"              gateway             10 seconds ago   Up 9 seconds    0.0.0.0:8000->8000/tcp

查看实时日志：

docker compose logs -f

按 Ctrl+C 退出日志跟踪。

检查健康状态：

在 nacos 控制台，检查服务是否正常。

🛑 停止和清理服务

停止服务（不停止容器）：

docker compose stop

停止并删除容器：

docker compose down

⚠️ 此操作会删除容器和其使用的网络，但不会删除镜像和宿主机上的日志文件。

🔄 版本升级

当收到新的部署包（如 basic-paper-gateway-deploy-1.1.0.tar.gz）时，请按以下步骤操作：

停止旧服务：

cd /path/to/old/basic-paper-gateway-deploy-2.1.4
docker compose down

加载新镜像：

docker load -i basic-paper-gateway-1.1.0.tar

进入新包目录，检查并更新 docker-compose.yml（如有必要，特别是 Nacos 配置）。
启动新服务：
```
docker compose up -d
```

💡 提示: 旧的镜像不会自动删除，可以通过 docker rmi basic-paper-gateway:2.1.4 手动清理。

🧰 常见问题排查

❓ 容器启动失败，日志提示权限不足？

确认 /var/simperfect/logs 目录已创建。
确认已正确执行第 3 步中的命令。
确认已正确执行第 4 步中 user: 1000:1000 用户配置的 UID 与宿主机的用户匹配。

❓ 无法连接到 Nacos？

检查 docker-compose.yml 中的 SPRING_CLOUD_NACOS_* 环境变量是否正确。
确保服务器网络能访问 Nacos 地址和端口（可以用 telnet 或 nc 测试）。

❓ 日志时间不对？

确认 TZ=Asia/Shanghai 环境变量是否正确。

❓ 如何确认容器内的用户不是 root?

运行以下命令查看容器进程的用户：
```
docker exec basic-paper-gateway ps aux
```
你应该看到主进程（./basic-paper-gateway）是由一个 UID 非 0 的用户启动的。