PyCaret 平台运维指南：备份、升级、可观测性与弹性扩展实战

PyCaret 4.0 的 sklearn 原生引擎之上构建了完整的控制平面（FastAPI 后端 + React UI + 独立 Worker），本文以仓库根目录下的 OPERATIONS.md 为骨架，结合 INSTALL.md、docker-compose.prod.yml、values.yaml 与 config.py 等源码，系统讲解如何把一套真实部署跑起来、看得住、能回滚、能扩容。读完你将掌握：双存储一致性备份、Alembic 迁移的升级/回滚 runbook、健康检查与指标接口的用法、按队列分离的 GPU/CPU 弹性伸缩，以及生产环境的关键安全加固点。

一、先认清平台的两块"状态"：备份的前提

PyCaret 平台的持久化数据由两半组成，OPERATIONS.md 在备份章节开门见山：

• DB（Postgres / 开发环境 SQLite）：用户、工作区、实验、Run、Trial、部署记录、审批流等全部元数据；
• 对象存储（MinIO / S3）：Run 输出物（run.ipynb、fitted_pipeline.pkl、leaderboard.json、events.jsonl、preview.html等），DB 行里只存stored_path这类 URI 引用。

只备份其一必然产生"元数据指向缺失工件"或"工件无人引用"的孤儿状态，所以PG dump 与对象存储 mirror 必须成对做。从 config.py 可以看到存储的完整能力矩阵：PYCARET_STORAGE_BACKEND支持local（工件落在PYCARET_ARTIFACT_DIR，DB 存file://URI）、s3/minio（S3 兼容 API）；而PYCARET_RUNS_BACKEND决定任务是进程内执行还是走 Redis 队列（见 config.py）。

1.1 Postgres：Compose 与 Kubernetes 两条 dump 路径

# Docker Compose 栈 docker exec pycaret-postgres pg_dump -U pycaret pycaret \ | gzip > pycaret-$(Get-Date -Format yyyyMMdd-HHmmss).sql.gz # Kubernetes kubectl -n pycaret exec sts/pycaret-pycaret-postgres -- pg_dump -U pycaret pycaret \ | gzip > pycaret-$(Get-Date -Format yyyyMMdd-HHmmss).sql.gz

恢复即对全新 DB 执行pg_restore。注意 Compose 中 Postgres 的用户/库默认值：POSTGRES_USER=pycaret、POSTGRES_DB=pycaret（可通过PYCARET_PG_USER/PYCARET_PG_DB覆盖），见 docker-compose.prod.yml。强烈建议每季度做一次恢复演练，只备份不验证的备份等于没有备份。

1.2 对象存储：mc mirror 与 aws s3 sync

mc alias set source http://minio:9000 $env:S3_ACCESS_KEY $env:S3_SECRET_KEY mc mirror source/pycaret-artifacts ./backup/artifacts

对真实 S3 使用aws s3 sync等价操作。pycaret-artifacts是 Compose 栈minio-bootstrap一次性服务创建的默认 bucket（见 docker-compose.prod.yml），Helm 部署则由 values.yaml 的minio.bucket指定。调度建议交给 cron 或 KubernetesCronJob，至少保留最近 14 份日备份 + 6 份月备份。

1.3 顺序很关键：先 dump DB，再 mirror 对象存储

正确顺序是DB dump 在前、对象存储 mirror 在后：dump 时 DB 行可能引用了尚未同步的工件，第二天重跑 sync 即可补齐。反过来（先 mirror 再 dump）会让 dump 指向未被捕获的工件，产生不可修复的引用悬空。这是两条命令之间最容易踩的坑。

二、升级 runbook：六步走与安全回滚

OPERATIONS.md 给出的升级流程是六步，每一步都有对应源码佐证：

1. 读 release notes——每个 PyCaret 版本都会在docs/revamp/PHASE-*-NOTES.md中标注迁移与破坏性变更；
2. 先快照 DB + 对象存储——复用上一节的备份流程，动手前必须有退路；
3. 拉取新镜像——Compose 下docker pull，Helm 下--set global.imageTag=…（镜像标签入口在 values.yaml）；
4. 先应用迁移，再拉起 API：

   docker exec pycaret-api pycaret-server migrate

   （K8s 下用kubectl exec进入 api pod。）Alembic 前向兼容：对仍在运行的旧版 API 应用纯增量迁移是安全的；但涉及破坏性 schema 翻转（典型如 Phase 0 的 trials/runs pivot）时，必须先把 API 停掉；

5. 滚动 API——先 drain worker（让在途 Run 跑完）再滚动 worker；
6. 冒烟测试——在任一 pod 内执行pycaret-server doctor。

pycaret-server migrate的实现见 cli.py：它默认使用PYCARET_DATABASE_URL，支持--revision指定目标版本（默认head）；--reset-dev会删除 SQLite 开发库文件并拒绝作用于非 SQLite URL，防止误操作。迁移脚本本身存放在 services/api/pycaret_server/migrations/versions，每个版本都带有downgrade。

坏版本回滚：先把镜像回滚到上一个 tag，再执行pycaret-server migrate --revision <previous>撤销 schema 变更（downgrade保证可逆）。补充一个值得知道的细节：serve --reload模式下，cli.py 会显式排除.venv、node_modules、artifacts、*.db等路径——因为 reload 触发重启会轮换进程内临时生成的PYCARET_SECRETS_KEY，把 DB 里已加密的 Secret 全部"打不开"，这是开发期最容易忽视的坑。

三、可观测性：健康检查、结构化日志与指标接口

3.1 三个健康检查入口

/healthz在 app.py 中直接返回{"ok": True}，并被审计中间件白名单排除（见 audit.py）。doctor的源码在 cli.py：逐一探测 DB（SELECT 1）、Redis（仅runs_backend=redis时，否则输出SKIP）、工件目录可写性（写入并删除.doctor-probe探针文件），任一失败返回退出码 1——这正是它能充当 K8sinitContainer就绪门卫的原因。

3.2 日志

API 与 worker 向 stderr 输出结构化日志，默认级别INFO；设置PYCARET_DEBUG=true可临时提升到DEBUG（调试完记得关掉，避免日志爆炸）。对接 Loki / CloudWatch / Datadog 直接利用容器运行时的 logging driver 即可。Helm 的api.env默认即为PYCARET_DEBUG: "false"，见 values.yaml。

3.3 指标：当前是 admin 端点，未来是 Prometheus

• GET /admin/queues与GET /admin/workers实现在 queue_admin.py：前者按Job.queue × Job.status分组统计queued/running/succeeded/failed/cancelled并附加近一小时succeeded数作为吞吐信号；后者没有独立的 workers 表，直接从Job.locked_by反推当前正在跑任务的 worker 列表（空闲 worker 会自然消失）——这意味着它更像"运行中任务视图"而非完整心跳，真正的worker_heartbeats表留待后续版本。
• 部署指标在 monitoring.py 与 deployments.py：read_metrics默认取最近 1 小时、按ts_bucket升序返回{metric, ts, value, count, extra}点列；预测时_record_predict_metrics维护 p50/p95 延迟滑动窗口并写回Deployment.p95_latency_ms。

未来版本会通过 Prometheus/metrics一次性暴露全部指标；当前阶段可用自定义 exporter 抓取上述 admin 端点，或直接使用平台内置告警规则 + Slack/email 目的地。邮件目的地依赖 config.py 的 SMTP 配置（smtp_host未设置时，邮件告警会返回明确的 "SMTP not configured" 错误而非静默丢弃）。

四、弹性伸缩：何时扩、扩什么、怎么扩

OPERATIONS.md 的缩放决策表是日常运维的速查手册：

Helm 默认值见 values.yaml：API 默认replicaCount: 2（250m CPU / 512Mi 请求），worker 默认 2 副本（500m CPU / 1Gi 请求）且queues: "default,cpu-heavy"，Postgres PVC 默认 20Gi、MinIO 默认 50Gi。Compose 栈的 worker 启动命令是pycaret-server worker --queues default（见 docker-compose.prod.yml）。

4.1 队列分离（Phase 14）：按任务类别拆 worker

默认队列规划为四类：

• default——兜底队列：compare / create / search 类任务；
• cpu-heavy——长时调参，避免饿死 default 池；实验上设置setup_params.queue=cpu-heavy；
• gpu——调度到声明了nvidia.com/gpu的节点；worker 部署同时设置setup_params.queue=gpu与nvidia.com/gpu=1资源限制；
• inference——轻量、延迟敏感、纯 predict 任务；副本数压低、CPU request 拉高，让延迟可预测。

队列机制的配置根基在 config.py：PYCARET_WORKER_QUEUES（默认"default"，逗号分隔）决定 worker 监听哪些队列。Helm 的 GPU worker 池安装方式在 INSTALL.md 有完整示例：

helm install pycaret-gpu ./infra/helm/pycaret -n pycaret \ --set api.replicaCount=0 \ --set web.replicaCount=0 \ --set postgres.enabled=false \ --set redis.enabled=false \ --set minio.enabled=false \ --set worker.replicaCount=2 \ --set worker.queues=gpu \ --set worker.resources.limits."nvidia\.com/gpu"=1

提交带setup_params.queue=gpu的 Run 后，GPU worker 会接单而 default 队列 worker 保持空闲，实现异构节点的精细调度。

五、安全加固：密钥、加密与审批

OPERATIONS.md 的安全条目与源码一一对应：

• JWT secret——要求 48+ 字节随机数，每年轮换；轮换期间临时把 refresh-token TTL 提到"1d"，避免存量会话集体失效。对应配置为 config.py 的jwt_secret（开发默认值故意设弱并会在日志中体现）、access_token_ttl_minutes=60、refresh_token_ttl_days=30。
• Secrets-key（Fernet）——加密 LLM API 密钥 + Phase 4 secrets + Phase 5 PAT 的静态存储。轮换时启动过程会对每条 Secret 行重加密，每 10 万条 secrets 需预留几分钟停机时间。生成方式：python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'。若未设置PYCARET_SECRETS_KEY，进程会生成临时密钥并打警告日志——加密值在重启后不可解密（见 config.py）。
• JupyterLab tokens——按会话生成、绝不复用，token 只在 iframe URL 中短暂出现，平台不会以明文落库（会话行之外）。
• 审批流（Phase 12）——把promote_to_production接到审批流上保护重要部署；默认工作流为空（单签自审批），避免阻塞独立开发者。审批的实现骨架在 governance.py：POST /workspaces/{ws}/approvals打开请求，POST /approvals/{id}/approve累加签名直到len(approvals) >= required_approvals才置为approved，最终POST /approvals/{id}/execute执行被门控的动作。

K8s 部署的密钥注入方式在 INSTALL.md：pycaret-jwt、pycaret-encryption、pycaret-postgres、pycaret-minio四个 Secret 由 Helm 分别挂载到对应组件的jwtSecretRef/encryptionKeyRef/passwordSecretRef（见 values.yaml）。

六、排障速查表

OPERATIONS.md 给出的症状—原因—修复映射，配合源码可以定位到具体配置项：

其中notebook_backend与notebook_image、notebook_idle_timeout_seconds（默认 1800 秒）等参数定义在 config.py。定位问题时建议先用pycaret-server doctor二分：它一次输出 DB / Redis / storage 三项状态，能快速缩小排查范围。

七、关联阅读

• INSTALL.md——首次部署：单进程开发、Docker Compose 全栈、Kubernetes Helm 三条路径任选；
• docs/revamp/PHASES.md——平台演进路线图（Phase 0–14，本指南中的队列分离、审批流均对应具体 Phase）；
• docker-compose.prod.yml——Compose 生产形态全栈定义；
• values.yaml——Helm 全部可调参数与资源默认值；
• config.py——PYCARET_*环境变量完整清单与默认值；
• cli.py——pycaret-server全部子命令（init / serve / migrate / worker / doctor）实现。