Qinglong 定时任务平台 Kubernetes 部署实战StatefulSet 单副本架构、PVC 存储与 Ingress 配置指南【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台Timed task management platform supporting Python3, JavaScript, Shell, Typescript项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong本文以仓库deploy/kubernetes目录下的 Kubernetes 部署方案为蓝本完整讲解如何将支持 Python3、JavaScript、Shell、TypeScript 的定时任务管理平台 Qinglong 以单副本StatefulSet形式部署到 Kubernetes 集群覆盖一键部署、本地端口转发访问、镜像仓库 overlay 定制、5Gi 持久化存储、健康探针、Ingress 路径与QlBaseUrl对齐以及ql check/ql update等容器内维护命令。读完本文你将掌握一套可直接复制运行的 Qinglong 云原生部署与日常运维方案。部署形态总览为什么是单副本 StatefulSetQinglong 的 Kubernetes 部署清单位于 deploy/kubernetes/base/qinglong.yaml其核心形态是单个Namespaceqinglong隔离部署资源一个ClusterIP类型 Serviceqinglong端口 5700为面板提供稳定的集群内访问入口一个StatefulSetreplicas: 1容器数据持久化挂载到/ql/datavolumeClaimTemplates动态申请 PVC数据随 Pod 调度持久保留。选用StatefulSet而非Deployment的根源在于 Qinglong 的有状态本质面板配置、定时任务记录、脚本、环境变量与日志都存放在持久化数据目录中包括 SQLite 数据库文件仓库docker/Dockerfile.debian中声明VOLUME /ql/data与清单中的mountPath: /ql/data一一对应。StatefulSet搭配稳定的volumeClaimTemplates命名data-statefulset-序号可以保证数据卷与实例身份一一绑定避免因 Pod 重建导致的卷错配问题。基础目录还包含一个 base/kustomization.yaml它通过 kustomize 的resources字段引用qinglong.yaml作为所有 overlay 的公共基底。一键部署与本地访问面板在已配置好kubectl并具备集群权限的环境下直接使用 kustomize 应用localoverlay 即可完成部署kubectl apply -k deploy/kubernetes/overlays/local kubectl -n qinglong rollout status statefulset/qinglong第一条命令通过 kustomize 渲染并下发清单会先创建qinglong命名空间与 PVC再滚动创建 StatefulSet第二条命令阻塞等待StatefulSet完成滚动并进入就绪状态返回成功即代表 Pod 已通过健康检查。若集群没有可直接访问 Service 的网络可用kubectl port-forward将集群内 5700 端口映射到本地kubectl -n qinglong port-forward svc/qinglong 5700:5700随后在浏览器访问 http://127.0.0.1:5700即可进入 Qinglong 初始化页面完成首次登录配置。镜像仓库 overlay 定制私有仓库迁移模板生产集群通常无法直接拉取 Docker Hub 公共镜像需要将镜像替换为私有仓库地址。仓库提供了提交到版本库的模板 overlays/example/kustomization.yamlapiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: - ../../base images: - name: whyour/qinglong newName: registry.example.com/whyour/qinglong newTag: debian它的作用一目了然字段含义resources: ../../base复用公共基底清单base/qinglong.yamlimages[].name匹配基底中被替换的原始镜像名whyour/qinglongimages[].newName替换为私有仓库地址registry.example.com/whyour/qinglongimages[].newTag替换镜像标签如debian模板效果即文档中的映射whyour/qinglong:debian - registry.example.com/whyour/qinglong:debian。基底清单默认镜像为whyour/qinglong:debian见 base/qinglong.yaml 的containers[].imagedebian标签对应 docker/Dockerfile.debian 构建的 Debian 基础镜像版本。实际操作建议在本地新建overlays/local/kustomization.yaml用于存放真实集群的镜像地址。localoverlay 被.gitignore忽略不会提交到仓库因此私有仓库名称、镜像 digest 以及拉取凭据相关引用可以安全地保存在本地而不泄露。部署命令kubectl apply -k deploy/kubernetes/overlays/local也正是针对该目录执行。存储配置5Gi PVC、StorageClass 与单副本约束清单通过volumeClaimTemplates声明持久化存储volumeClaimTemplates: - metadata: name: data spec: accessModes: - ReadWriteOnce resources: requests: storage: 5Gi要点如下容量默认申请5 GiBaccessModes为ReadWriteOnce单节点读写。StorageClass默认使用集群的default StorageClass动态供给 PVC。若集群未配置默认存储类需要显式指定在模板中补上storageClassName字段即可volumeClaimTemplates: - metadata: name: data spec: storageClassName: your-storage-class为什么必须保持replicas: 1Qinglong 的持久化数据目录中包含 SQLite 文件等状态数据多个副本共享同一数据卷会造成写入冲突与数据损坏因此严禁将副本数提升到 1 以上。如果需要横向扩展应在架构层面拆分职责而不是让多个实例共享同一份数据。值得一提的细节是清单中的安全上下文securityContext: fsGroup: 5432 fsGroupChangePolicy: OnRootMismatchfsGroup: 5432与 Debian 镜像中定义的运行时用户 UID/GID 对齐docker/Dockerfile.debian 中ARG QL_UID5432、ARG QL_GID5432并以USER qinglong运行确保容器内进程对挂载卷拥有读写权限fsGroupChangePolicy: OnRootMismatch则避免每次启动都递归变更卷属主加速 Pod 启动。这一点与 docker/docker-entrypoint.sh 中对/ql与/ql/dataDocker Volume 挂载点写入权限的启动期自检逻辑相互呼应——无论是 Docker 还是 Kubernetes 部署数据目录权限都是启动成败的关键前提。健康探针三个探针如何协同守护面板可用性清单为容器配置了三个 HTTP 探针全部探测后端健康接口/api/health端口http即 5700探针关键参数作用readinessProbeinitialDelaySeconds: 20、periodSeconds: 10、timeoutSeconds: 3、failureThreshold: 6判断容器是否可接收流量未就绪时 Service 不会把请求转发进来livenessProbeinitialDelaySeconds: 60、periodSeconds: 20、timeoutSeconds: 3、failureThreshold: 6判断容器是否存活连续失败触发 kubelet 重启容器startupProbeperiodSeconds: 5、timeoutSeconds: 3、failureThreshold: 60慢启动保护最多探测 60 次约 5 分钟成功前不启用存活/就绪判定三个探针的分工是startupProbe容忍首次启动时的依赖安装与初始化耗时readinessProbe保障滚动更新期间流量无损livenessProbe兜底运行期故障自愈。探针命中的/api/health在源码中有完整实现链路back/api/health.ts 的路由处理函数调用 back/services/health.ts 中的HealthService.check()该方法逐一校验 HTTP Server 与 gRPC Server 两个核心服务的存活状态并附带uptime进程运行秒数与内存占用heapUsed/heapTotal等指标。因此该接口不仅证明 Web 服务可访问还间接反映了定时调度所依赖的 gRPC 服务状态——探针判定的是 Qinglong 前后端整体健康度而不仅是静态页面可打开。Ingress 子路径部署QlBaseUrl 的前后端对齐如果通过 Ingress 的非根路径如/qinglong/暴露 Qinglong必须同步设置环境变量QlBaseUrl为相同路径且以斜杠开头和结尾env: - name: QlBaseUrl value: /qinglong/这一约束在源码层有明确依据后端归一化back/config/serverEnv.ts 会拾取QlBaseUrl若不以/开头则自动补前缀若不以/结尾则自动补后缀back/config/index.ts 随后统一去掉尾部斜杠用于路由定义二者配合保证环境变量无论书写成qinglong、/qinglong还是/qinglong/都能收敛为一致的路径语义前端路由基址前端构建时把QlBaseUrl注入window.__ENV__QlBaseUrl见 src/utils/config.ts 与 src/app.ts作为前端资源 public path 与路由 basename确保在子路径下刷新页面不会 404shell 侧shell/share.sh 同样读取QlBaseUrl生成ql_base_url用于健康检测等内部请求拼装路径。对比 Docker Compose 部署docker/docker-compose.yml 中QlBaseUrl: /注释明确说明“部署路径非必须以斜杠开头和结尾比如 /test/”Kubernetes 场景只是把同样的环境变量搬进了清单的env段。根路径部署时保持默认值/即可无需修改。仓库文档给出的 Ingress 示例以下 yaml 中省略了metadata之外的默认注解配置apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: qinglong namespace: qinglong spec: rules: - host: qinglong.example.com http: paths: - path: / pathType: Prefix backend: service: name: qinglong port: number: 5700示例以根路径Prefix匹配将qinglong.example.com的请求转发到qinglongService 的 5700 端口。若你改用path: /qinglong/等子路径务必同步把QlBaseUrl改为/qinglong/否则前端资源加载与 API 请求会因路径不匹配而失败。维护命令日志、环境检测与更新部署完成后日常运维围绕以下三条命令展开kubectl -n qinglong logs -f statefulset/qinglong kubectl -n qinglong exec -it statefulset/qinglong -- ql check kubectl -n qinglong exec -it statefulset/qinglong -- ql updatelogs -f跟随容器标准输出观察启动过程与运行日志。容器启动脚本 docker/docker-entrypoint.sh 会依次打印配置文件检测、PM2 服务启动、Bot 与自定义脚本启动等分步信息并自动探测调度模式存在crond则走system模式否则走node模式日志中可以看到这些决策痕迹。ql check执行环境自检与修复。对应脚本 shell/check.sh 会依次安装全局依赖pnpm、pm2、ts-node、typescript等、修复配置文件、安装 Qinglong 依赖、复制通知文件notify.py/notify.js随后探测面板首页检查div idroot/div特征与后台接口检查code:200与status:ok失败时还会输出 PM2 状态与最近 300 行系统日志用于诊断。ql update在线更新 Qinglong。ql命令实际软链接到 shell/update.sh见 docker/Dockerfile.debian 中的ln -sf ${QL_DIR}/shell/update.sh /usr/local/bin/ql。该脚本会根据网络可达性自动选择 GitHub/Gitee 源下载主分支与静态资源压缩包比对package.json变化决定是否重装依赖必要时整体替换back、src、shell等运行时目录并重启 PM2。由于更新过程会替换程序文件强烈建议在更新前确认 PVC 数据完好所有用户数据配置、脚本、SQLite都独立保存在持久卷中不会被更新流程覆盖。部署检查清单最后汇总一份可直接对照的检查清单确认kubectl可用且目标集群有default StorageClass没有则按上文补充storageClassName生产环境先创建overlays/local/kustomization.yaml用images覆盖为私有仓库镜像参考 overlays/example/kustomization.yaml执行kubectl apply -k deploy/kubernetes/overlays/local并等待rollout status完成本地联调用port-forward访问 5700 端口完成初始化若通过 Ingress 子路径暴露务必让path与QlBaseUrl保持一致前后都带斜杠保持replicas: 1切勿让多副本共享数据卷日常巡检使用logs -f、ql check、ql update三条命令出现存储类或权限问题时优先核对 PVC 与fsGroup: 5432配置。【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台Timed task management platform supporting Python3, JavaScript, Shell, Typescript项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考