从源码跑控制台

本页是所有执行后端共用的底座；后端专属配置见各自页面。

git clone https://github.com/tuneplane/tuneplane && cd tuneplane
uv sync
export TUNEPLANE_DB_URL="postgresql+psycopg://user:password@127.0.0.1/tuneplane"
uv run tuneplane-server serve --port 8080 --serve    # --serve 绑定 0.0.0.0

要打包好的部署方式，改用 Docker Compose、 Kubernetes 或 Helm。这一页是源码安装，而下面那些设置对四种方式都适用。配置走前缀为 TUNEPLANE_ 的环境变量，或仓库根目录的一个 .env。那里的 .env.example 是带注释的模板。

每个部署都需要的设置

环境变量	说明
`TUNEPLANE_WEB_JWT_SECRET`	必设固定强随机串；缺省随机生成会导致重启全员掉线、多副本 token 互不通用
`TUNEPLANE_PUBLIC_URL`	对外可达地址（OIDC 回调 / CLI 授权用）
`TUNEPLANE_INGEST_URL`	训练容器回传指标的地址；必须是集群网内可达的 console URL，勿填 127.0.0.1
`TUNEPLANE_ALLOWED_IMAGE_REGISTRIES`	用户 `--image` 允许的仓库主机，逗号分隔。空：一等框架覆盖不限制，自定义镜像拒绝
`TUNEPLANE_IMAGE_VERL` / `TUNEPLANE_IMAGE_TRL` / `TUNEPLANE_IMAGE_OPENRLHF`	这些框架的默认 OCI 镜像（部署工件；catalog 不内嵌引用）
`TUNEPLANE_DB_URL`	必填的 PostgreSQL 连接地址；启动控制台之前先创建数据库
`TUNEPLANE_REDIS_URL`	多副本部署强烈建议：token 即时吊销、分布式限流、一致性
`TUNEPLANE_TIMEZONE`	服务级时区（时段窗口与日报边界）

对象存储（MinIO / S3）

数据集、作业包分发（kubernetes 必需）、产物归档共用一套：

TUNEPLANE_S3_ENDPOINT=https://minio.internal
TUNEPLANE_S3_ACCESS_KEY=…
TUNEPLANE_S3_SECRET_KEY=…
TUNEPLANE_S3_BUCKET=tuneplane

作业侧永远只拿预签名 URL，不持有存储凭据。控制台上传数据集和 Volume 文件走的是同一条路——浏览器直接 PUT 到上面这个 endpoint——所以存储桶需要配 CORS：允许来自控制台域名的 PUT 与 GET，并暴露 ETag。没配的话，这类上传会在浏览器里失败，而不经过浏览器的 tp dataset push 照常可用：

mc admin config set myminio api cors_allow_origin=https://console.internal

反向代理

deploy/nginx.conf.example 提供模板，要点：

/api 关闭代理缓冲（SSE 日志流）；
/docs 反代 Mintlify 托管站（见 mintlify/README.md）；
WebSocket / 长连接超时放宽。

迁移

服务启动自动执行 Alembic 迁移；手动操作：

uv run alembic upgrade head

第一个管理员

一套全新部署上的第一个用户，通过控制台首次访问的引导流程在 /api/auth/setup 创建，或者用 tp admin user-add。单点登录见配置登录。

确认成功

curl https://tuneplane.your-company.com/api/version

它返回控制台版本和它说的 JobSpec 方言。然后在上线之前跑一次冒烟测试：一条命令就能验证整条提交、调度、容器和 ingest 的链路配对了，而且不需要 GPU。

下一步

选一个后端 · Fleet · 配置参考

迁移现有 SQLite 安装

先停止 API 和 worker，保留 SQLite 数据库备份和原有密钥。创建空的 PostgreSQL 数据库，设置 TUNEPLANE_DB_URL，然后运行：

uv run --no-sync python -c 'from tuneplane_server.core.db import make_engine, resolve_db_url; make_engine(resolve_db_url()).dispose()'
uv run --no-sync python scripts/import_sqlite.py /absolute/path/to/web.db

导入工具以只读方式打开源文件，拒绝向已有业务数据的目标库写入。两边结构必须与当前版本的迁移版本一致；旧源库需要先使用仍支持 SQLite 的版本完成升级。导入会保留 ID、重置序列、核对行数并验证已有审计哈希，发现无效数据会回滚整次导入。确认 PostgreSQL 控制台运行正常之前请保留源备份，不要将两个数据库同时作为同一部署的可写实例使用。以上脚本需要在源码仓库内运行；容器部署可以使用版本匹配的源码完成一次性导入，之后正常使用 PostgreSQL 备份和升级流程。

把部署跑起来

执行器

平台治理

日常运维

从源码跑控制台

每个部署都需要的设置

对象存储（MinIO / S3）

反向代理

迁移

第一个管理员

确认成功

下一步

迁移现有 SQLite 安装

​每个部署都需要的设置

​对象存储（MinIO / S3）

​反向代理

​迁移

​第一个管理员

​确认成功

​下一步

​迁移现有 SQLite 安装

每个部署都需要的设置

对象存储（MinIO / S3）

反向代理

迁移

第一个管理员

确认成功

下一步

迁移现有 SQLite 安装