企业官网建设流程全解析

PyCaret 4.0 是一个开源的、可自托管的低代码 AutoML 平台，将 sklearn 原生引擎、FastAPI 控制平面与 React Web UI 打包进一个仓库，实现"引擎 + 控制平面 + UI 一体化"。本文以仓库根目录 README.md 为主线，结合 compose.yml、.env.example、services/api/pycaret_server/config.py 等源码与设计文档，完整讲解五分钟本地部署、环境配置、Golden Path 实战（Train → Register → Deploy → Predict）以及平台架构演进方向，帮助你快速把这个平台跑起来并理解它的内部构造。

项目定位：一个箱子装下的完整 ML 平台

PyCaret 4.0 与 3.x 的定位截然不同。3.x 只是一个 AutoML 库（PyPI 上的pycaret 3.4.0已冻结、不再提交新代码），而 4.0 是一次从零开始的架构重构（README 中明确标注为work in progress），交付物是完整的自托管 ML 平台，包含三大组件：

• Engine：基于 sklearn 1.7 的 AutoML 库（PyPI 包名仍为pycaret），位于 packages/engine，提供分类、回归、聚类、异常检测、时间序列五大任务类型。
• Control plane：FastAPI 后端，提供工作区（Workspaces）、项目、实验、运行（Runs）、模型注册（Model Registry）、部署、审批、监控、漂移检测、血缘（Lineage）、Webhooks、调度、LLM 辅助 copilot 等能力，代码位于 services/api。
• Web UI：React + Vite 构建、暗色模式优先的界面，位于 apps/web。所有配置通过点选完成，不需要手写 YAML。

部署形态刻意保持紧凑：docker compose up只启动两个容器——一个 nginx 托管的 React 静态资源，一个同时承载调度器（APScheduler）、进程内计算（ThreadPoolExecutor）与 SQLite 数据库的 FastAPI 进程，即"单二进制"自托管模式（README 中提到与 Plausible / Vaultwarden / n8n 同思路）。整个平台默认跑在http://localhost:3020。

五分钟本地安装

前提条件

只需要 Docker：Docker Desktop 4.27+，或Docker Engine 25.0+ 且带 Compose v2.24+。无需本地 Python、Node 或数据库。

启动命令

git clone https://github.com/pycaret/pycaret.git cd pycaret docker compose up --build

首次构建约 5 分钟（Python 依赖 + npm install + Vite build），之后再次启动小于 30 秒。当日志中出现pycaret-api | INFO: Application startup complete.和pycaret-web | … starting nginx后，打开：

http://localhost:3020

首次访问会出现 Setup 界面，引导你创建第一个管理员账号与工作区，创建完成即进入平台。

启动后运行了什么

这些端口、服务名与健康检查都定义在仓库根目录的 compose.yml 中：api 容器监听 8020，web 容器对外暴露${PYCARET_WEB_PORT:-3020}:8080，pycaret-data卷挂载到 api 容器的/data目录。api 容器带有 healthcheck（轮询/healthz），web 容器通过depends_on: api: condition: service_healthy等待后端就绪后再启动，避免首启时 UI 先于迁移完成而报 404。

常用运维命令

docker compose logs -f api # 追踪后端日志 docker compose logs -f web # 追踪 UI 日志 docker compose restart api # 仅重启后端 docker compose down # 停止全部（数据卷保留，数据与密钥安全） docker compose down -v # 彻底清空（连数据卷一起删，数据库与密钥全部丢失）

down与down -v的区别是平台持久化设计的关键：前者保留pycaret-data卷（SQLite 库、CSV、pkl、Fernet 密钥都在里面），后者则全部抹掉，下次up相当于全新安装。

常见故障排查

配置体系：从 .env 到源码

快速开始

所有可覆盖配置都通过仓库根目录的.env文件注入（该文件被 gitignore，模板见 .env.example）：

cp .env.example .env # 编辑 .env：把 PYCARET_JWT_SECRET 换成真实随机值等 docker compose up

核心配置项详解

源码视角：三层配置链

配置链条在仓库中有完整实现证据：

1. Compose 层：compose.yml 中 api 服务通过${VAR:-default}语法注入PYCARET_DATABASE_URL、PYCARET_ARTIFACT_DIR、PYCARET_CORS_ORIGINS、PYCARET_JWT_SECRET、PYCARET_ENVIRONMENT、PYCARET_DEBUG，并刻意不设置PYCARET_SECRETS_KEY——注释明确说明这是为了让入口脚本接管密钥生命周期。
2. 入口脚本层：infra/docker/docker-entrypoint.sh 处理密钥的持久化：若环境变量未提供密钥，则首次启动时用 Pythoncryptography生成 Fernet 密钥写入/data/.secrets/fernet.key（权限 0600），之后每次重启复用。脚本注释记录了这个设计的历史教训——session 55 曾因每次重启轮换临时密钥导致数据库中所有已加密密钥静默失效。脚本最后用exec "$@"替换自身进程，确保docker stop信号直达 uvicorn。
3. 应用配置层：services/api/pycaret_server/config.py 基于 pydantic-settings 定义Settings类，env_prefix="PYCARET_"、env_file=".env"，通过lru_cache提供进程级单例get_settings()。除 README 提到的核心变量外，还包含runs_backend（inprocess默认 /redis，对应 Phase 1 的 worker 化）、worker_queues、notebook_backend（local/docker）、enable_deployments、enable_websocket等功能开关。

黄金路径（Golden Path）：10 分钟走通 Train → Register → Deploy → Predict

README 给出了完整的端到端实操路径：

1. Setup—— 创建第一个管理员账号与你的工作区。
2. 配置 LLM（可选）—— 侧边栏 →Settings → LLM，粘贴 Anthropic 或 OpenAI 的 API Key，可解锁 AI 数据集顾问与实验设计 copilot。
3. 上传或选择数据集—— 侧边栏 →Build → Datasets→ 点击Browse samples一键获取仓库自带的 CSV（juice、bank、iris 等，见 datasets 目录）。
4. 创建项目—— 侧边栏 →Build → Projects→ New project。
5. 运行实验—— 进入项目 → New experiment → 选择数据集、任务类型（classification / regression / clustering / anomaly / time series）、目标列。运行自动开始，训练约 12 个算法。
6. 提升胜者—— 在 Run 详情页的排行榜上对比 12 个 trial，选择其一 →Promote，它以 v1 版本进入Model registry。
7. 部署—— Model registry → 点击模型 → 在版本行Deploy→ 给出端点 slug（如juice-prod）。
8. 预测—— 部署详情页使用Test a prediction面板，或直接调用：

curl POST http://localhost:8020/api/v1/deployments/juice-prod/predict

携带一行 JSON 特征数据即可获得预测结果。

这条路径在架构层面有清晰落点：部署与推理链路见 docs/revamp/ARCHITECTURE.md 中的说明——Run 成功并产出 pipeline pickle 后，POST /runs/{id}/promote生成工作区级的 Pipeline 记录，POST /pipelines/{id}/deployments生成带 slug 与 auth_mode 的 Deployment 记录，进程内DeploymentRegistry（LRU + p50/p95 滚动窗口）负责加载模型并响应POST /deployments/{slug}/predict。部署的鉴权模式包括workspace（JWT）以及后续版本的api-key、public（限流）。

本地开发（不走 docker compose）

若想带热重载开发代码，docker compose 反而显得笨重，可以绕过容器直接运行：

# 前置：Python 3.13 + Node 22 + uv 0.11+ + npm 10+ # 安装全部依赖（引擎 + 控制平面 + UI） uv sync --all-packages --all-extras cd apps/web && npm install && cd .. # 两个终端分别运行： uv run --package pycaret-server pycaret-server serve --reload # 后端 :8020 cd apps/web && npm run dev # 前端 :3020

apps/web/vite.config.ts把/api、/ws、/healthz代理到后端 8020 端口（注意配置里ws: true是为了转发/api/v1/runs/:id/events/ws的 WebSocket 升级，否则 EventStream 会显示 "closed · 0 events"），因此浏览器体验与 docker 部署一致。仓库采用 uv workspace 管理 Python 包（引擎packages/engine、服务端services/api、SDKpackages/sdk-python、共享 schemapackages/shared-schemas），目录结构规则是：packages/是可发布库、services/是常驻服务、apps/是面向用户的 UI、infra/是部署运维（详见 docs/revamp/ARCHITECTURE.md）。

安全：哪些能提交，哪些绝不能

仓库内置了scripts/check-secrets.sh扫描器，防止密钥被意外提交。可手动随时运行：

bash scripts/check-secrets.sh

更推荐安装为 git pre-push 钩子：

cp scripts/check-secrets.sh .git/hooks/pre-push && chmod +x .git/hooks/pre-push

脚本的设计是fail closed（宁可误报也不放过）：以 pre-push 钩子身份运行时只扫描本次推送的 diff；手动/CI 运行时扫描全部被 git 追踪的文件。它识别的敏感模式包括 Anthropic / OpenAI / Stripe / Slack / GitHub / AWS / Google API Key 形态、Fernet 密文块（ENC:v1:...）以及 PEM 私钥块（详见 scripts/check-secrets.sh 中的PATTERNS数组）。绕过方式有两种：整行放行（行尾追加# pragma: allow-secret）与整文件放行（路径写入 scripts/.secrets-allowlist）。

以下内容按设计永远不会被提交：

• *.db/*.sqlite（SQLite 文件，可能含加密的敏感数据块）
• .env（本地配置）
• *.pem/*.key/credentials.json/aws-credentials*
• /data/（若你绑定挂载过 docker-compose 数据卷）

完整清单见 .gitignore。

架构：诚实地讲"今天"与"明天"

今天：两个容器

docker compose up实际运行的部署非常紧凑：

• api 容器：单个 FastAPI / uvicorn 进程，同时承载进程内调度器（APScheduler）、进程内计算（ThreadPoolExecutor）、推理运行时，以及指向数据卷中 SQLite 文件的 SQLAlchemy 会话。
• web 容器：nginx 托管 React 构建产物，并把/api反向代理到 api 容器。

nginx 配置（infra/docker/nginx.ui.conf）的细节值得注意：/assets/静态资源缓存 1 年（immutable），普通/api/代理proxy_read_timeout 300s，而/api/v1/runs/单独配置了 3600s 的读写超时与 WebSocket upgrade 头——因为长时 AutoML 运行需要长连接。SPA 路由通过try_files $uri $uri/ /index.html回退。

明天：七后端槽位

架构的核心规则（见 docs/revamp/PLATFORM_ARCHITECTURE.md）：

平台接触的每一个外部依赖都必须藏在Protocol之后，且至少有两个实现：一个用于本地开发，一个（或多个）用于云端。

外部依赖指任何非"对内存中数据做纯 Python 计算"的东西：对象存储、关系数据库、任务队列、认证、密钥、通知、计算、缓存等。这条规则保证同一份代码既能靠docker compose up跑在笔记本上，也能经 Terraform 跑在 AWS 上，选择后端只是配置，业务代码永远看不到条件分支。

平台规划的七个后端槽位及当前状态：

✅ = 已实现、已测试、可通过配置选择；⚠ = 只有单一实现或尚未抽象出 Protocol。目标形态是单一的Backends容器（dataclass），启动时由from_config(settings)组装并依赖注入到各 handler，测试时注入内存假实现，handler 代码永远看不到boto3。

演进路线

• Phase 0 · 本地单进程（当前已发布）：SQLite、文件系统、进程内 worker、DB 内 Fernet，docker compose up即用。
• Phase 1 · 可插拔后端：抽取缺失的 5 个 Protocol，本地实现仍为默认，默认配置下零行为变化。
• Phase 2 · AWS 包：补齐 S3（已完成）、SecretsManager、SqsBackend、FargateRunner、SesNotifier，交付 infra/terraform/aws。
• Phase 3 · worker/runtime 拆分：把services/api、services/worker、services/deployment-runtime拆成独立进程/容器，API 变为无状态 HTTP，worker 从队列拉取任务，部署运行时独立提供推理，解锁水平扩展。
• Phase 4 · 认证包：Cognito + OIDC + SAML，SSO 成为配置选项。
• Phase 5 · 多云：GCP（Cloud SQL / GCS / Cloud Run / Pub/Sub）与 Azure（Azure SQL / Blob / Container Apps / Service Bus）。

平台也明确列出了不做什么：不做 SaaS 版控制平面（自托管、客户自带 AWS 账号、Terraform 是边界）、不做拖拽式流水线构建器（PyCaret 是配置驱动，UI 是配置向导而非图编辑器）、不做通用编排器（无 DAG，Run 是原子的，Schedule 只是重跑）、不做特征存储、不做流式推理（Phase 3+ 再考虑）。

许可证与延伸阅读

PyCaret 4.0 采用双许可证：

• 引擎（packages/engine）：MIT，任何用途（含商用）免费。
• 控制平面（services/api、apps/web、infra）：BUSL-1.1，4 年后变更为 Apache-2.0。组织自托管生产使用在 LICENSE 的 Additional Use Grant 下是允许的；被限制的场景是"把 PyCaret 本身作为托管 SaaS 出售"。引擎 MIT 条款见 LICENSE.engine.txt。

继续深入阅读的入口：

• docs/revamp/VISION.md —— 一页产品愿景
• docs/revamp/PLATFORM_ARCHITECTURE.md —— 可插拔后端架构与缺口矩阵
• docs/revamp/ARCHITECTURE.md —— 当前代码地图（monorepo 布局、路由表、Run 执行链路、数据模型）
• docs/revamp/CONTROL_PLANE_SPEC.md —— 完整功能规格（24 节）
• docs/revamp/ROADMAP.md 与 docs/revamp/STATUS.md —— 演进路线与当前进度
• AGENTS.md —— Agent 协作模式下的完整开发简报

需要注意的是，4.0 仍是进行中的架构重构版本，本文描述的均为当前仓库main分支（4.0 线）的实际形态；若需要稳定生产版本，PyPI 上的pycaret 3.4.0（3.x 线）已冻结可用。