model-platform/README.md

Model Platform

自托管的 Jupyter 模型开发平台：交互式 workspace、DAG 调度、对象存储工件、 按 workspace 隔离的运行时 — 全部经一个 Nginx 网关对外。

技术栈：React Router SPA · FastAPI · APScheduler · MySQL · S3 兼容存储 （或本地文件系统，STORAGE_BACKEND=local）· 共享 Jupyter · rclone FUSE 挂载（仅 s3 模式） 单一入口（Nginx :80）；其他服务只在 Docker 内网互通。

它做什么

能力	位置
workspace 内 notebook 编辑，行级锁	backend/jupyter.py + scripts.is_locked
Jupyter 鉴权路由（浏览器永远拿不到 runtime token）	nginx/default.conf + auth_request + backend/jupyter.py
notebook / script / version / run_log 的对象存储（s3 / local 二选一）	common/storage/ + backend/scripts.py
DAG 调度：节点、边、cron、手动触发、重试、快照	backend/schedules.py + backend/schedule_runs.py + schedule/（5 个模块）
DAG 执行走 MySQL Outbox（无 Redis，无进程内队列）	schedule/orchestrator.py + schedule/worker.py
每个 workspace 一个 Jupyter 子进程池，配 asyncio 锁	runtime/process.py
runtime 内 rclone FUSE 把 workspace 桶挂上来（s3 模式）	runtime/mount.py
仅 MySQL 持久化（26 张表，软删除，无外键）	common/db/models/

架构一览

                        ┌────────────────────┐
                        │  Browser (SPA)     │
                        └─────────┬──────────┘
                                  │ HTTPS / WS
                        ┌─────────▼──────────┐
                        │  Nginx (only :80) │  ← templates/default.conf
                        │   /api/  /jupyter/ /storage/
                        └────┬───────┬──────┘
                             │       │
              ┌──────────────┘       └─────────────┐
              ▼                                     ▼
   ┌──────────────────┐               ┌──────────────────────┐
   │ FastAPI Backend  │               │ Runtime (Jupyter)     │
   │ + /internal/v1   │   control     │ - rclone FUSE mount  │ (P0-1)
   │   /objects       │   token-Auth  │                       │
   │ (storage)        ├──────────────►│ - subprocess pool    │
   │ - DAG CRUD       │               │   (per workspace)    │
   │ - script CRUD    │               └──────────┬───────────┘
   │ - auth_request   │                          │ FUSE / shared vol
   │ - /api/v1/...    │                          ▼
   └────┬──────┬──────┘               ┌──────────────────────┐
        │      │                       │ Object storage      │
        │      └──────── HTTP ───────►│ (s3: S3 service /    │
        ▼                              │  local: shared vol) │
   ┌────────────┐                      │ 4 buckets per usage │
   │  MySQL     │◄───────── poll ─────│                      │
   │ - 26 tbls  │                      └──────────────────────┘
   │ - outbox   │
   │ - jobstore │
   └────┬───────┘
        ▲
        │ outbox poll
   ┌────┴──────────────────────────┐
   │ Schedule Executor             │
   │ - CronScheduler (APScheduler) │
   │ - DispatchOrchestrator        │
   │ - NodeExecutor (worker)       │
   │ - SchedulerService (facade)   │
   └───────────────────────────────┘

对象存储通过 STORAGE_BACKEND（s3 | local）二选一。s3 模式下 4 个 purpose 命名桶 （workspace / version / run-log / trash）是独立的 S3 bucket；local 模式下 是 LOCAL_STORAGE_BASE_DIR 的子目录，通过 Docker volume local-storage 共享。 详见 DEVELOP.md §存储。

详细设计见 ARCHITECTURE.md。实现的偏离和近期重构记录在 HANDOVER.md。

目录结构

frontend/                    React Router SPA
backend/                     FastAPI：公开 API + 内部存储 API
runtime/                     Jupyter 子进程管理 + rclone FUSE
schedule/                    DAG 调度器（5 模块：context/scheduler/
                             orchestrator/worker/service）
common/                      配置、SQLAlchemy 模型、存储 SDK、
                             outbox 事件、jobstore
migrations/                  Alembic 基线 + 各特性 migration
nginx/                       （仅概念 — 见下方「容器」一节）
scripts/                     nginx-entrypoint.sh（模板渲染）
docker-compose.yml           4 服务 — web / backend / runtime / schedule
default.conf                 Nginx 模板（挂载，启动时渲染）
.env.example                 common.config.Settings 消费的所有环境变量

容器

服务	镜像	暴露	用途
web	nginx:alpine	宿主机 :8888 → :80	SPA、/api/ 反向代理、/jupyter/{ws}/ auth_request 代理、/storage/ S3 直通（仅 s3 模式）
backend	Dockerfile	仅内网	DAG CRUD、script CRUD、schedule 触发、/api/v1/auth/jupyter、/internal/v1/objects 服务间 RPC(共享 INTERNAL_SERVICE_TOKEN 鉴权,P0-1)
runtime	Dockerfile	仅内网	每个 workspace 一个 Jupyter 子进程池、rclone FUSE 挂载 workspace 桶（s3 模式）
schedule	Dockerfile	仅内网	cron tick + DAG 执行（轮询 MySQL Outbox）

架构故意只暴露一个宿主机端口(网关);其他服务都在 Docker 内网。 这一点在 docker-compose.yml 里强制执行 — backend / runtime / schedule 都没有 ports:。在 P0-1 之前,backend 与 runtime 曾短暂地把 8891 / 8892 映射到宿主机;此映射已被删除,改用 INTERNAL_SERVICE_TOKEN 头对 /internal/v1/* 做服务间鉴权,见 API.md §9。

快速启动

cp .env.example .env
# 编辑 .env — 至少改 MYSQL 密码，以及（s3 模式下）S3 凭据。

# 静态检查
uv sync --all-packages
uv run --frozen --package backend python -m compileall -q backend/src common/src
uv run --frozen --package schedule python -m compileall -q schedule/src
uv run --frozen --package runtime python -m compileall -q runtime/src

# 应用 schema
uv run --frozen --package backend alembic upgrade head

# 启动整套服务
docker compose config          # 校验
docker compose up -d --build
docker compose ps

访问 http://localhost:8888。

日志

docker compose logs -f backend
docker compose logs -f schedule
docker compose logs -f runtime

停服（保留 MySQL + S3 / local-storage 数据卷）

docker compose down

抹数据

docker compose down -v

配置

所有环境变量在 common/src/common/config.py 里用 pydantic-settings 的 Settings 类一次性声明，外面套一层 @lru_cache 单例。新增环境变量：

1. 在 common/src/common/config.py 的 Settings 里加字段（带合理 default，使 dev 启动不需要设）
2. 在 .env.example 加一行带注释
3. 调用点用 settings.<name>，永远不要用 os.environ["..."]

完整环境变量列表和含义见 DEVELOP.md。

存储布局

4 个 purpose 命名桶。从 StorageObjects.usage_type 到桶的映射由 单一入口（backend/storage_api.py:resolve_bucket）决定：

usage_type	桶（环境变量）	默认名
working_copy、public_script、data_resource、snapshot	S3_WORKSPACE_BUCKET	workspace
version_artifact	S3_VERSION_BUCKET	version
run_log、run_result	S3_RUN_LOG_BUCKET	run-log
（软删除目标）	S3_TRASH_BUCKET	trash

STORAGE_BACKEND=s3 模式下是 4 个独立 S3 桶。STORAGE_BACKEND=local 模式下 是 LOCAL_STORAGE_BASE_DIR（默认 /data）下的 4 个子目录：

/data/
├── workspace/   # S3_WORKSPACE_BUCKET
├── version/     # S3_VERSION_BUCKET
├── run_log/     # S3_RUN_LOG_BUCKET
└── trash/       # S3_TRASH_BUCKET

某个 workspace 的 artifact_bucket 列（非 NULL 时）覆盖该 workspace 的默认桶， 无视 usage_type — 适合把付费客户隔离到专属桶。

对象 key 是两层扁平路径 — workspace_id 加服务端签发的 ulid：

<workspace_bucket>/<workspace_id>/<ulid>{.<ext>}

文件名、扩展名、MIME、逻辑路径都放在 StorageObjects 和 Scripts 行里，不进 object key — 重新组织存储不需要重写数据库。

Backend 代码从不写容器本地文件系统（STORAGE_BACKEND=local 模式除外，那里共享 local-storage volume 就是规范存储）。Schedule Executor 在 tempfile.TemporaryDirectory() 里暂存节点工件（自动清理）。只有 runtime 容器保留宿主 volume — s3 模式下 rclone FUSE 挂载需要；local 模式下是 no-op 透传。

文档

• README.md（本文）— 快速导读
• ARCHITECTURE.md — 设计图 + 简化历史
• HANDOVER.md — 实现偏离、近期重构、待办事项
• DEVELOP.md — 开发指南（环境变量、代码规约、常用操作）
• CLAUDE.md — agent 面向的本仓库规约

许可

内部。