diff --git a/AGENTS.md b/AGENTS.md index 2e1ae77a..1625f014 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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:`、`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 " + +# 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 约定:`-<主题>--<短提交号>`,如 `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。