新架构运维文档

该文档主要说明目前服务架构改变后如何管理和配置部署服务

简述

新架构服务为滚动发布，底层从原有 docker 切换为k3s，无集群，每个节点是一个单独的节点。

后端：必须有 /actuator/health 健康检测接口，否则将无法正常部署。

前端：由原有直接打包变为 docker 镜像包，所以将不再进行本地打包，直接发布到 jenkins 进行自动打包及发布。前端配置文件仍然读取服务器目录：/app/frontend/conf/下的配置文件。

K3S

这里主要简短描述k3s 及更新部署服务常见命令，k3s详细运维信息见： k3s 运维文档

部署

1.下载
wget -O /usr/local/k3s https://github.com/k3s-io/k3s/releases/download/v1.33.3%2Bk3s1/k3s
2.写入 systemd 文件
cat > /etc/systemd/system/k3s.service << EOF
[Unit]
Description=Lightweight Kubernetes
Documentation=https://k3s.io
Wants=network-online.target
After=network-online.target

[Install]
WantedBy=multi-user.target

[Service]
Type=notify
EnvironmentFile=-/etc/default/%N
EnvironmentFile=-/etc/sysconfig/%N
EnvironmentFile=-/etc/systemd/system/k3s.service.env
KillMode=process
Delegate=yes
User=root
# Having non-zero Limit*s causes performance problems due to accounting overhead
# in the kernel. We recommend using cgroups to do container-local accounting.
LimitNOFILE=1048576
LimitNPROC=infinity
LimitCORE=infinity
TasksMax=infinity
TimeoutStartSec=0
Restart=always
RestartSec=5s
ExecStartPre=/bin/sh -xc '! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service 2>/dev/null'
ExecStartPre=-/sbin/modprobe br_netfilter
ExecStartPre=-/sbin/modprobe overlay
ExecStart=/app/k3s/k3s server
EOF
3.启动
systemctl daemon-reload #重载systemd
systemctl start k3s

管理

查看状态：

root@test-server:/app/frontend/conf# systemctl status k3s
● k3s.service - Lightweight Kubernetes
     Loaded: loaded (/etc/systemd/system/k3s.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2025-09-04 13:18:04 CST; 59s ago
       Docs: https://k3s.io
    Process: 3256572 ExecStartPre=/bin/sh -xc ! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service 2>/dev/null (code=exited, status=0/S>
    Process: 3256574 ExecStartPre=/sbin/modprobe br_netfilter (code=exited, status=0/SUCCESS)
    Process: 3256575 ExecStartPre=/sbin/modprobe overlay (code=exited, status=0/SUCCESS)
   Main PID: 3256576 (k3s-server)
      Tasks: 626
     Memory: 5.2G
        CPU: 1min 40.664s
     CGroup: /system.slice/k3s.service
#Active: active (running)为正常状态

启动/重启：

systemctl start k3s #启动
systemctl restart k3s #重启

重新部署：

在k3s服务出问题并且找不到原因的时候可以考虑重新部署k3s，因为都是单节点，结构简单，不会发生什么问题，唯一的需要注意的是所有已经部署了的服务需要重新部署一次。

k3s重新部署

systemctl stop k3s && rm -rf /var/lib/rancher/k3s/  && systemctl start k3s

服务部署

yaml文件部署

除生产环境，预演测试是jenkins自动部署的。第一次部署jenkins打包会在/app/backend/项目（前端是/app/frontend/项目）目录下生成一个项目.yml的文件，只需要通过命令 cd /app/backend/项目然后执行命令

kubectl apply -f . 即可部署，部署文件则为项目.yml

部署命令：

前端：
cd /app/frontend/项目名/ 
kubectl apply -f .
后端：
cd /app/backend/项目名/ 
kubectl apply -f .

备注：

1.如果项目部署文件没生成，可以删除项目文件夹并重新打包，使nginx生成部署yml文件

2.部署文件是通过模板生成的，绝大部分项目可以直接部署，少数项目例如没有健康监测端口需要单独调整一下部署文件。

3.除非特殊情况，一般不用考虑手动部署

手动部署

部署由原有docker-compose 改为helm,helm 为k3s 部署模板。为了标准化部署，模版预置了前后端部署了绝大部分参数，使得前端只需要传递环境和域名，后端部署只需要传递环境。如果存在部署问题，则统一调整部署模板，而非手动调整单个部署yaml文件。

需要注意的是这里的zhxx/frontend 和zhxx/backend 是前端和后端的 helm 部署模板，可以理解为和docker-compose.yml 一样，存储于 minio.zhxx.site 上的 helm 桶里面，其中前端部署在模板中只需要传递环境和域名即可，而后端仅需要传递环境，每个服务的镜像、启动参数、端口已经在模板中预置定义，部署时无需再传递这些参数，如果无法部署，则说明模板里面没有预置该服务的参数，例如端口。

helm repo add zhxx http://minio.zhxx.site:9000/helm #所有服务器只有第一次部署需要使用该命令

前后端部署命令：

前端：
helm install 项目名称 zhxx/frontend --set branch=环境 --set url=域名
后端：
helm install 项目名称 zhxx/backend --set branch=环境

前端部署会读取/app/frontend/conf/项目名.conf，该文件为前端 nginx 配置文件，如果这个文件不存在则无法部署成功，并且前端需要手动指定其访问的域名。

后端部署默认将 /app/backend/项目名/upload/ 挂载至容器 /app/data/，如有服务需要做数据持久化，则默认将服务目录写入至/app/data

例如环卫测试环境部署：

前端：
helm install zh-sanitation-frontend zhxx/frontend --set branch=test --set url=zh-sanitation.test.zhxx.site
后端：
helm install zh-urban-sanitation zhxx/backend --set branch=test

单独指定镜像部署

在默认情况下，服务的镜像部署规则为：项目名_环境，后端服务生产统一环境为 prod，前端则细分环境例如 lvzhou、shifang，举个例子，如果部署绿洲环卫后端生产使用命令helm install zh-urban-sanitation zhxx/backend --set branch=lvzhou ，则镜像默认为harbor.zhxx.site/app/zh-urban-sanitation_prod:latest ，而如果部署绿洲环卫前端生产，则镜像默认为harbor.zhxx.site/app/zh-sanitation-frontend_lvzhou:latest。

如果想单独指定镜像，例如生产部署预演镜像则指定环境变量imageRepository。如下：

helm install zh-urban-sanitation zhxx/backend --set branch=lvzhou --set imageRepository=harbor.zhxx.site/app/zh-urban-sanitation_prev

单独指定端口

传递环境servicePorts.服务名=端口号，例如绿州环卫部署端口改为 20333，则：

helm install zh-urban-sanitation zhxx/backend --set branch=lvzhou --set servicePorts.zh-urban-sanitation=20333

helm常用管理命令

卸载：

helm uninstall 服务名

查看已部署服务：

helm list

服务更新

1.jenkins 打包

测试、预演环境：直接 jenkins 构建即可部署

生产环境：jenkins 构建成功后在生产环境执行命令：kubectl rollout restart deployment 项目名

2.服务部署更新

更新命令如下：

kubectl rollout restart deployment 项目名

更新逻辑如下：

下面是实际更新命令使用过程：

1.执行更新命令

➜  helm-new git:(main) ✗ kubectl rollout restart deployment plant-service
deployment.apps/plant-service restarted

2.ContainerCreating表示容器正在拉取最新镜像（plant-service-7859bdbb84-5lbf6是老容器，在完全更新结束前都不会被停止）

➜  helm-new git:(main) ✗ kubectl get pod
NAME                                  READY   STATUS              RESTARTS        AGE
plant-service-6f6c57d497-78bcc        0/1     ContainerCreating   0               3s
       1/1     Running             0               27h
zh-reservoir-new-786785c577-4n5gf     1/1     Running             0               44h
zh-reservoir-webui-56d8848c56-6wzv7   1/1     Running             1 (3h21m ago)   3h21m

3.镜像拉取完成，开始进入运行状态，这个时候等待服务启动完成并开始健康接口检测，直至检测完成以前这里的READY字段都是0/1。

➜  helm-new git:(main) ✗ kubectl get pod
NAME                                  READY   STATUS    RESTARTS        AGE
plant-service-6f6c57d497-78bcc        0/1     Running   0               40s
plant-service-7859bdbb84-5lbf6        1/1     Running   0               27h
zh-reservoir-new-786785c577-4n5gf     1/1     Running   0               44h
zh-reservoir-webui-56d8848c56-6wzv7   1/1     Running   1 (3h22m ago)   3h22m

4.服务启动完成且健康检测完成，READY字段变为1/1，这个时候容器访问的流量将会被调度调新容器，老的容器状态变为Terminating，开始销毁停止老容器

➜  helm-new git:(main) ✗ kubectl get pod
NAME                                  READY   STATUS        RESTARTS        AGE
plant-service-6f6c57d497-78bcc        1/1     Running       0               81s
plant-service-7859bdbb84-5lbf6        1/1     Terminating   0               27h
zh-reservoir-new-786785c577-4n5gf     1/1     Running       0               44h
zh-reservoir-webui-56d8848c56-6wzv7   1/1     Running       1 (3h22m ago)   3h22m

5.老容器销毁完成，新容器正常运行。

➜  helm-new git:(main) ✗ kubectl get pod
NAME                                  READY   STATUS    RESTARTS        AGE
plant-service-6f6c57d497-78bcc        1/1     Running   0               82s
zh-reservoir-new-786785c577-4n5gf     1/1     Running   0               44h
zh-reservoir-webui-56d8848c56-6wzv7   1/1     Running   1 (3h22m ago)   3h22m

需要注意的是现在的服务为平滑更新，在更新完成之前，其中任何一步更新失败是不会影响原有容器的正常运行的

服务管理

日志查看

1.拿到部署的服务名

首先使用kubectl get pod ，找到对应服务的 pod 名称（容器名称），pod 名称一般以：服务名-随机字符串组成,例如找到水库流域的pod 名

➜  nginx-for-noK3s git:(main) ✗ kubectl get pod  |grep zh-reservoir-new
zh-reservoir-new-67948c6c67-tq77q                          1/1     Running   0               17h

2.使用kubectl logs 命令查看日志

使用kubectl logs pod名查看日志，其参数和 docker logs 一致，一般实时查看日志常使用参数 --tail 100 -f

nginx-for-noK3s git:(main) ✗ kubectl logs zh-reservoir-new-67948c6c67-tq77q --tail 100 -f

c 2025-09-04 10:47:20.701 [ WARN] - [  XNIO-2 task-9] o.s.w.s.m.m.a.ExceptionHandlerExceptionResolver :: Failure in @ExceptionHandler io.github.atom.kernel.web.exception.ServletGlobalExceptionHandler#handleServletException(Exception, HttpServletRequest)

org.springframework.http.converter.HttpMessageNotWritableException: No converter for [class io.github.atom.kernel.core.api.R] with preset Content-Type 'application/octet-stream;charset=UTF-8'

停止服务

方法1，通过helm卸载服务：

helm uninstall 服务名

方法2，通过kubectl删除服务：

kubectl delete deployment 服务名

服务回滚

一般更新失败不会用到回滚操作，因为现在的平滑更新在更新失败的时候不会影响到老的服务，所以如果要回滚，一般是新服务部署成功了但服务本身存在一定的问题，这个时候可以回滚。

回滚到上个版本：

kubectl rollout undo deployment 服务名

示例

和更新一样，会将上个版本的容器拉一个起来，直至回滚完毕当前容器才会被关闭

➜  cert-manager git:(main) ✗ kubectl rollout undo deployment hj-auth

deployment.apps/hj-auth rolled back
➜  cert-manager git:(main) ✗ kubectl get pod |grep hj-auth
hj-auth-5c47594c4f-zsjd2                                   1/1     Running   0               9m5s
hj-auth-7ff9896c6c-w9smg                                   0/1     Running   0               8s

回到指定版本：

首先通过kubectl rollout history deployment 服务名，可以看到历史版本。
➜  cert-manager git:(main) ✗ kubectl rollout history deployment hj-auth
deployment.apps/hj-auth
REVISION  CHANGE-CAUSE
1         <none>
2         <none>
3         <none>
4         <none>
6         <none>
7         <none>
8         <none>
例如这里示例服务有 8 个版本，则当前版本为8，前七个版本为历史版本。例如我想回滚到上上个版本，则回滚命令如下：
kubectl rollout undo deployment hj-auth --to-revision=6

如果对回滚的版本不太确定，可以通过下面的命令查看该版本具体信息（例如部署时间）：
kubectl rollout history deployment hj-auth --revision=3