# Model Platform

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

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

## 它做什么

能力清单、组件图、容器表、存储布局、配置参考——**全部在 [`DEVELOP.md`](./DEVELOP.md)**：

- 系统整体架构（[§Architecture](./DEVELOP.md#architecture)）
- 18 张 MySQL 表的 Eventing 协作模式（[§Eventing](./DEVELOP.md#eventing--outbox--inbox--business-tables)）
- 代码目录布局（[§Code layout](./DEVELOP.md#code-layout)）
- 全部 26 个环境变量（[§Configuration system](./DEVELOP.md#configuration-system)）
- 写代码的约定（[§Conventions](./DEVELOP.md#conventions)）
- 加新表 / 新桶 / 新节点类型的步骤（[§Common tasks](./DEVELOP.md#common-tasks)）

`ARCHITECTURE.md` 现已并入 `DEVELOP.md`；`HANDOVER.md` 记录近期重构与待办事项。

## 快速启动

```bash
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`。

### 日志

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

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

```bash
docker compose down
```

### 抹数据

```bash
docker compose down -v
```

## 文档

- [`DEVELOP.md`](./DEVELOP.md) — 权威文档：架构、代码布局、配置、约定、常用任务、测试、故障排查
- [`HANDOVER.md`](./HANDOVER.md) — 近期 commit / 实现偏离 / 待办事项
- [`API.md`](./API.md) — REST API 契约
- [`CLAUDE.md`](./CLAUDE.md) — agent 面向的本仓库规约

## 许可

内部。