KTeam/kt-template-online-api
1
0
Fork 0
mirror of https://github.com/KwiTsukasa/kt-template-online-api.git synced 2026-05-27 15:44:54 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
d742a2fb16
kt-template-online-api/docs/fnos-docker-jenkins-k8s-standard.md

5.1 KiB
Raw Blame History

fnOS Docker + Jenkins + k3d/K8s 标准发布流程

这套流程把飞牛 NAS 上的 Docker 保留为基础控制面，把业务运行逐步迁到 k3d/K3s：

  • Jenkins Controller、Jenkins Agent、本地 Registry 仍由 Docker 管理。
  • 后端 API 进入 k3d/K8s，由 Jenkins 构建镜像、推送本地 Registry、滚动更新 Deployment。
  • Web 和 Playground 继续走现有 Nginx 静态发布，等后端链路稳定后再决定是否容器化。

固定命名

对象 名称
Jenkins Agent kt-node-agent
k3d 集群 kt-nas
K8s namespace kt-prod
本地 Registry k3d-kt-registry.localhost:5000
API Deployment kt-template-online-api
API Service kt-template-online-api
API K8s 容器名 api
API 容器端口 48085
API NodePort 30085
NAS 对外端口 48085

一次性初始化

先确保本机 SSH key 已授权到 NAS 的 root 用户，然后从仓库根目录执行：

.\ci\fnos-k8s\run-remote-bootstrap.ps1

如果 NAS 上旧的 Docker API 容器已经占用 48085，第一次真正切换时再执行：

.\ci\fnos-k8s\run-remote-bootstrap.ps1 -Cutover

-Cutover 会允许脚本停止旧的 kt-template-online-api Docker 容器，把 48085 交给 k3d loadbalancer 映射到 K8s NodePort 30085。

脚本会在 NAS 上完成：

  • 创建 /vol1/docker/kt-k8s/{registry,kubeconfig,secrets,manifests,backups}。
  • 安装缺失的 k3d 和 kubectl。
  • 创建本地 Registry。
  • 创建 kt-nas 集群。
  • 拉取并导入 rancher/mirrored-pause:3.6，避免 K3s 节点因 Docker Hub 超时卡在 ContainerCreating。
  • 导出 host kubeconfig 和 Jenkins Agent kubeconfig。
  • 创建 kt-prod namespace。
  • 将 kt-node-agent 接入 k3d Docker 网络。
  • 将 kubeconfig 复制到 Agent 内的 /home/jenkins/agent/kubeconfig/kt-nas.jenkins.yaml。
  • 如果 Agent 内已有 /home/jenkins/agent/env/kt-template-online-api/.env.production，同步创建 kt-template-online-api-env Secret。

Jenkins Agent 镜像

Agent 镜像位于：

ci/jenkins-agent/Dockerfile

镜像内置：

  • Node.js 22
  • pnpm 9
  • Docker CLI / Buildx / Compose
  • kubectl
  • Git / OpenSSH

NAS 上重新构建并重启 Agent：

docker build -t kt-jenkins-agent:node22 -f ci/jenkins-agent/Dockerfile ci/jenkins-agent
docker rm -f kt-node-agent

然后按 ci/jenkins-agent/README.md 中的 docker run 命令重新启动。Agent 启动后再跑一次：

.\ci\fnos-k8s\run-remote-bootstrap.ps1

这样脚本会把 kubeconfig 重新复制进 Agent，并把 Agent 接到 k3d-kt-nas 网络。

Jenkins 发布参数

后端 Jenkinsfile 的标准参数：

DEPLOY_TARGET=k8s
BUILD_DOCKER_IMAGE=true
PUSH_DOCKER_IMAGE=true
DOCKER_REGISTRY=k3d-kt-registry.localhost:5000
IMAGE_NAME=kt-template-online-api
CONTAINER_ENV_FILE=/home/jenkins/agent/env/kt-template-online-api/.env.production
KUBE_CONFIG_FILE=/home/jenkins/agent/kubeconfig/kt-nas.jenkins.yaml
K8S_MANIFEST_FILE=k8s/prod/api.yaml
K8S_NAMESPACE=kt-prod
K8S_DEPLOYMENT=kt-template-online-api
K8S_CONTAINER=api
K8S_ENV_SECRET=kt-template-online-api-env

发布阶段会做四件事：

  1. 构建后端 dist。
  2. 用仓库根目录 dockerfile 构建业务镜像。
  3. 推送到 NAS 本地 Registry，同时更新 latest 标签。
  4. 从 Agent 私有 .env.production 重建 K8s Secret，并滚动更新 Deployment 镜像。

验证

NAS 上验证集群：

kubectl --kubeconfig /vol1/docker/kt-k8s/kubeconfig/kt-nas.host.yaml get nodes
kubectl --kubeconfig /vol1/docker/kt-k8s/kubeconfig/kt-nas.host.yaml -n kt-prod get pod,svc

Agent 内验证：

docker exec kt-node-agent sh -lc 'kubectl --kubeconfig /home/jenkins/agent/kubeconfig/kt-nas.jenkins.yaml -n kt-prod get pod,svc'

API 验证：

curl -I http://127.0.0.1:48085

如果公网入口仍由腾讯云 WireGuard/Caddy 转发到 NAS 10.66.66.2:48085，切换到 K8s 后公网侧不需要改端口。

回滚

查看发布历史：

kubectl --kubeconfig /vol1/docker/kt-k8s/kubeconfig/kt-nas.host.yaml -n kt-prod rollout history deployment/kt-template-online-api

回滚上一个版本：

kubectl --kubeconfig /vol1/docker/kt-k8s/kubeconfig/kt-nas.host.yaml -n kt-prod rollout undo deployment/kt-template-online-api
kubectl --kubeconfig /vol1/docker/kt-k8s/kubeconfig/kt-nas.host.yaml -n kt-prod rollout status deployment/kt-template-online-api --timeout=180s

查看日志：

kubectl --kubeconfig /vol1/docker/kt-k8s/kubeconfig/kt-nas.host.yaml -n kt-prod logs -l app=kt-template-online-api --tail=200

如果需要临时退回旧 Docker 容器，先删除或停止 k3d loadbalancer 对 48085 的占用，再按旧 Jenkins Docker 参数重启 kt-template-online-api 容器。

参考