docs: 补充生产部署流程与脚本、变量位置

This commit is contained in:
tongtong committed 2026-11-09 19:04:01 +08:00
1 parent 68d86feea4
commit 9c906bdb2e
1 file changed
+62
+62
View File
@@ -156,3 +156,65 @@ xxx/
- 禁止为旧前端/旧设备端保留旧接口、旧字段或旧 URL 前缀;需要它们同步修改时,在提交说明中列明改动点。
- 存储位置由业务语义决定:一类资源对应 `StorageDir` 中的一个固定常量,使用**专用接口**落盘(如 `POST /api/v1/client/files/avatar`),不得让调用方通过 `directory` 之类的参数决定目录。该约定仅约束我方新增接口,不改动上游 `POST /api/v1/files`。
- 存量历史数据(旧本地路径、旧对象目录、旧字段格式)只允许用一次性迁移脚本或管理接口处理,不得在业务代码中长期保留运行时回退分支。
## 7. 生产部署(k3s)
### 7.1 环境
| 项 | 值 |
| --- | --- |
| 服务器 | `175.178.213.60`,root 登录(密码/密钥不写入仓库,走本地运维渠道) |
| 集群 | 单节点 k3s,namespace `youlai` |
| 工作负载 | `deploy/youlai-boot`,单副本,`Recreate` 策略 |
| 端口 | 容器 8000,Service NodePort **30800** |
| 公网入口 | `https://api.ttstd.com`(服务器 nginx 反代到 30800) |
| 健康检查 | `/api/v1/health`(readiness 45s 起、liveness 120s 起) |
| Spring Profile | `prod`(配置见 `src/main/resources/application-prod.yml`) |
### 7.2 服务器上的文件与变量位置
| 路径 | 作用 |
| --- | --- |
| `/opt/youlai-boot/redeploy.sh` | 部署入口:追加 jar 层 → 导入 k3s containerd → `set image` + `rollout restart` |
| `/opt/youlai-boot/build_image.py` | 被 `redeploy.sh` 调用,拼装镜像 manifest |
| `/opt/youlai-boot/deploy.yaml` | Namespace / Deployment / Service 清单(JVM 参数、资源限额、探针、`envFrom` 均在此) |
| `/opt/youlai-boot/app.jar` | 当前生产 jar(部署成功后替换) |
| `/opt/youlai-boot/app.jar.new` | 新 jar 上传暂存路径 |
| `/opt/youlai-boot/app-*.jar`、`album-*`、`profile-*` | 历史 jar / 版本留档,回滚时使用 |
- `redeploy.sh` 内变量:`JAR`、`TAG`(参数)、`IMG=docker.io/library/youlai-boot:<TAG>`、`BASE=docker.m.daocloud.io/library/eclipse-temurin:17-jre`、`W=/opt/imgwork`。
- 运行参数在 `deploy.yaml`:`-Xms128m -Xmx384m -XX:MaxMetaspaceSize=192m -XX:+UseSerialGC`,requests 300m/384Mi、limits 1500m/768Mi。
- 敏感配置不在仓库:短信等密钥由 Secret `youlai-sms` 通过 `envFrom` 注入;数据源、Redis、MQTT 等在 `application-prod.yml`,改动后随 jar 一起发布。
- 不要用 `docker build`:服务器无法访问 Docker Hub,脚本改为把 jar 作为新层追加到已缓存的 `eclipse-temurin:17-jre` 上;该基础镜像必须已存在于节点 containerd。
### 7.3 部署步骤
```bash
# 1. 本地打包(会包含工作区未提交改动,发布前先确认 git status)
mvn -B -DskipTests clean package
sha256sum target/youlai-boot.jar
# 2. 上传到暂存路径
pscp -P 22 target/youlai-boot.jar root@175.178.213.60:/opt/youlai-boot/app.jar.new
# 3. 校验上传完整性
plink -ssh root@175.178.213.60 "sha256sum /opt/youlai-boot/app.jar.new"
# 4. 构建镜像并滚动重启
plink -ssh root@175.178.213.60 "bash /opt/youlai-boot/redeploy.sh /opt/youlai-boot/app.jar.new <tag>"
# 5. 验收
plink -ssh root@175.178.213.60 "kubectl -n youlai get pods -o wide; \
kubectl -n youlai get deploy youlai-boot -o jsonpath='{.spec.template.spec.containers[0].image}{\"\n\"}'; \
curl -s -o /dev/null -w 'health:%{http_code}\n' http://127.0.0.1:30800/api/v1/health; \
kubectl -n youlai exec deploy/youlai-boot -- sha256sum /app/app.jar"
# 6. 用新 jar 覆盖现网留档
plink -ssh root@175.178.213.60 "cd /opt/youlai-boot && mv -f app.jar.new app.jar"
```
- Tag 约定:`<pom 版本>-<主题>-<yyyymmdd>-<短提交号>`,如 `4.14.1-wip-20261109-4dd7d98c`;同一 tag 重建必须依赖脚本内的 `rollout restart`,否则 kubelet 继续用旧镜像。
- `Recreate` + 单副本:发布期间服务短暂不可用;新 Pod 冷启动约 1–2 分钟,这段时间 `health:000`、`rollout status` 超时属正常,等 Pod Running 后复查。
- `redeploy.sh` 不 `kubectl apply deploy.yaml`;改 JVM 参数、资源、探针、环境变量时,先改 `deploy.yaml` 再 `kubectl apply -f /opt/youlai-boot/deploy.yaml`。
- 回滚:`kubectl -n youlai set image deploy/youlai-boot app=docker.io/library/youlai-boot:<上一 tag>` 后 `kubectl -n youlai rollout restart deploy/youlai-boot`,再走第 5 步验收。
- 排障:`kubectl -n youlai logs deploy/youlai-boot --tail=200`、`kubectl -n youlai describe pod -l app=youlai-boot`、`journalctl -u k3s --since '1 hour ago'`。节点内存较紧(3.6Gi,容器上限 768Mi),关注探针超时与 OOM。