# ModelRail **Repository Path**: buera/model-rail ## Basic Information - **Project Name**: ModelRail - **Description**: ModelRail 是一个开源的 AI 模型全生命周期管理平台，提供模型与数据集管理、模型下载、量化、评估、部署，以及用户、角色和权限管理。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: develop2 - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-09-27 - **Last Updated**: 2026-10-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
ModelRail

Model lifecycle, running on rails.

# ModelRail [简体中文](README.md) | [English](README.en.md) ModelRail 是一个可自托管的 AI 模型生命周期管理前后端平台。它提供 Web 控制台和 API，用于管理模型下载、数据集、微调、评估、量化、推理部署、知识库与对话；同时提供用户账号、角色、权限和登录审计功能。前端使用 React、TypeScript 与 Vite，后端使用 NestJS 和 PostgreSQL。 ModelRail 负责控制台、API、元数据和任务编排。Compose 在首次启动时从上游源码构建 LLaMA Factory 与 llama.cpp 镜像，并以官方预编译 vLLM 镜像生成本地 tag。应用镜像内置从 llama.cpp 源码编译的量化工具、评测和 RAG 入口，并在构建时下载五个默认文本评测基准数据集及 Qwen3 嵌入模型；微调和推理用的模型权重由使用者按需准备。 ## 快速开始 面向 Linux x86_64 主机。使用 GPU 微调、推理或监控时，还需 NVIDIA 显卡、驱动和 NVIDIA Container Toolkit；详细检查命令见[主机要求与检查](#主机要求与检查)。首次构建需要网络连接、较多磁盘空间和时间。 ```bash cp .env.example .env # 编辑 .env：为数据库、Redis、JWT 和初始管理员设置各自独立的密钥 docker compose up -d ``` 启动后访问 `http://localhost:9000`，用 `admin` 和 `.env` 中设置的 `INITIAL_ADMIN_PASSWORD` 登录。完整说明和无 GPU 启动方式见[一键启动](#一键启动)。 ## 界面预览 点击截图可查看原图。仪表盘展示已运行的推理服务和 GPU 资源；模型仓库、对话与角色管理分别对应模型生命周期和多用户管理能力。 | 仪表盘与资源监控 | 模型仓库 | | :------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------: | | [![仪表盘显示推理服务队列和 GPU 资源曲线](docs/images/modelrail-dashboard.png)](docs/images/modelrail-dashboard.png) | [![模型仓库显示已下载的 Qwen 模型](docs/images/modelrail-model-registry.png)](docs/images/modelrail-model-registry.png) | | 推理对话 | 角色管理 | | [![使用已部署模型进行推理对话](docs/images/modelrail-conversation.png)](docs/images/modelrail-conversation.png) | [![系统角色管理列表](docs/images/modelrail-roles.png)](docs/images/modelrail-roles.png) |
登录页面 ![ModelRail 登录页面](docs/images/modelrail-login.png)
## 功能概览 - 数据集、模型、微调、评估、量化和推理部署管理。 - 知识库文件管理、检索和模型对话入口。 - 用户账号管理、角色分配、权限控制、登录日志，以及任务状态和运行日志查看。 - llama.cpp 与 vLLM 推理引擎配置入口。 - 通过 Docker Engine 创建训练和推理容器；独立 Collector 提供 GPU 状态。 - PostgreSQL 保存平台数据，Redis 支持会话和缓存。 - Docker Compose 构建应用与模型运行镜像，并部署数据库和缓存服务。 本项目提供多用户账号与基于角色的访问控制。当前数据模型没有独立的组织或租户实体，因此不应将它描述为具备租户级隔离的多租户 SaaS；若在共享实例中承载不同组织的数据，部署方应先自行验证各业务资源的授权和隔离边界。 ## 与相关开源项目的定位 以下对比依据各项目的官方文档，着重说明主要使用场景和与 ModelRail 的交集；具体功能会随上游版本变化。知识库、对话和权限管理并非 ModelRail 独有能力。ModelRail 当前的侧重点，是在自托管控制台中串联本地模型下载、数据集、微调任务、量化、评测、推理部署，以及知识库和用户权限管理。 | 项目 | 主要使用场景与交集 | ModelRail 的侧重点 | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | [Dify](https://github.com/langgenius/dify/blob/main/README.md) | AI 应用开发，提供 RAG 和模型接入；与 ModelRail 的知识库、模型调用有交集。 | 管理本地模型文件及其微调、量化、评测和推理任务。 | | [Open WebUI](https://docs.openwebui.com/features/) | 多用户模型交互界面，提供对话、知识库和[角色/群组权限](https://docs.openwebui.com/features/authentication-access/rbac/)；与 ModelRail 的对话、RAG 和访问控制有交集。 | 将模型准备与运行任务纳入同一控制台。ModelRail 目前提供用户、角色和权限管理，但不宣称具备 Open WebUI 的群组共享与资源 ACL。 | | [LLaMA Factory](https://llamafactory.readthedocs.io/en/latest/getting_started/webui.html) | 提供训练、评估、预测、对话及导出界面，重点是模型微调。 | 将 LLaMA Factory 作为外部训练运行引擎，另行编排模型下载、GGUF 量化、评测和 llama.cpp/vLLM 推理部署；两者可配合使用。 | | [MLflow](https://mlflow.org/docs/latest/ml/tracking/) | 实验追踪、模型注册、[评估](https://mlflow.org/docs/latest/genai/datasets/)与[部署](https://mlflow.org/docs/latest/ml/deployment)。 | 面向单机 Docker 环境的模型任务操作界面。 | 如果主要目标是开发 AI 应用，可优先了解 Dify；以知识库对话和多人协作为主，可了解 Open WebUI；需要深入训练配置或实验追踪，可分别使用 LLaMA Factory 或 MLflow。ModelRail 适合希望自行托管模型文件，并通过一个 Web 界面管理从准备到本地部署这段流程的团队。 ## 仓库结构 | 路径 | 内容 | | -------------------- | -------------------------------- | | `packages/apps/web` | Web 管理界面 | | `packages/apps/api` | API、业务逻辑和任务编排 | | `docs/images` | README 界面截图 | | `docker-compose.yml` | 应用、数据库和运行镜像的启动配置 | | `Dockerfile` | 构建 Web、API 和内置运行工具 | | `docker/` | 推理镜像构建及评测、RAG 入口 | | `quick-deploy.sh` | 从镜像仓库拉取应用镜像并启动服务 | | `DEPLOY.md` | 部署及运维操作说明 | | `LICENSE` | MIT 开源许可证 | ## 架构与镜像边界 ModelRail 使用 Docker Compose 管理首次构建和启动。应用镜像包含 Web、API、量化工具、评测入口、五个默认文本基准数据集、Qwen3 嵌入模型及 RAG 服务；训练与模型推理仍由 API 通过 Docker Engine 按任务创建容器。 | 镜像 | `docker compose up -d` 的行为 | 用途 | | ------------------------------- | ---------------------------------------------- | -------------------------- | | `modelrail:local` | 从本仓库构建 | Web、API、量化、评测和 RAG | | `postgres:17-bookworm` | 拉取 PostgreSQL 官方镜像 | 持久化数据库 | | `redis:7.4.0-alpine` | 拉取 Redis 官方镜像 | 缓存与任务队列 | | `modelrail-train:local` | 从 LLaMA Factory 官方源码构建 | 微调任务 | | `modelrail-llamacpp:local` | 从 llama.cpp 官方源码编译 CUDA server | GGUF 推理 | | `modelrail-vllm:local` | 以官方 `vllm/vllm-openai` 预编译镜像为基础构建 | Hugging Face 模型推理 | | `modelrail-gpu-collector:local` | 启用 `gpu` profile 时从本仓库构建 | 独立采集 NVIDIA GPU 状态 | Compose 中 `training-image`、`llamacpp-image` 和 `vllm-image` 是构建专用服务，执行成功后退出，退出码为 0 属于正常状态。Web/API 启动只依赖数据库和 Redis；创建微调或部署任务前，相应的运行镜像需已构建。数据库和 Redis 使用官方已构建镜像，不在用户主机从源码编译。 GPU 监控由可选的 `gpu-collector` 服务负责。它使用独立的 NVIDIA CUDA 基础镜像运行 `nvidia-smi`，通过内部 HTTP 接口把设备状态交给 API，不使用训练镜像。API 中的 `GpuProvider` 接口隔离采集方式，当前实现为 NVIDIA 和禁用模式；后续可添加其他硬件的 provider。采集器无宿主机端口映射，也不需要 Docker socket。 量化依赖的 `llama-cli`、`llama-quantize`、GGUF 转换脚本、`conversion`/`gguf-py` 包和共享库在应用镜像构建时从 llama.cpp 源码编译、复制；量化任务仍由 API 调用本地程序。评测使用内置的 EvalScope 入口脚本和官方离线数据集。RAG 的 HTTP 服务及 Qwen3 嵌入模型也打包在应用镜像中。量化、评测和 RAG 无需单独的长期运行容器。 ## 主机要求与检查 Web/API 可以在没有 GPU 的 Linux 开发环境启动；GPU 监控、训练和 GPU 推理需要 Linux x86_64（AMD64）、NVIDIA GPU、Docker Engine、Docker Compose V2 和 NVIDIA Container Toolkit。首次构建需要访问 GitHub、Docker Hub、PyPI、Conda 和 ModelScope 数据源等上游服务，并预留充足的磁盘空间和内存。vLLM 官方 CUDA 镜像与 llama.cpp CUDA 编译所需的驱动版本由所选镜像决定；请核对 [NVIDIA Container Toolkit 安装文档](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)、[llama.cpp Docker 文档](https://github.com/ggml-org/llama.cpp/blob/master/docs/docker.md)及 [vLLM Docker 文档](https://docs.vllm.ai/en/stable/deployment/docker/)。 在 Linux 主机执行： ```bash uname -m # 预期为 x86_64 nvidia-smi # 能列出 NVIDIA GPU 和驱动 docker version docker compose version docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi ``` 启用 GPU 功能前，最后一条需要在容器内成功列出 GPU。若失败，先按 NVIDIA 文档配置 Docker runtime（`sudo nvidia-ctk runtime configure --runtime=docker`，然后重启 Docker）。示例 CUDA 测试镜像需与主机驱动兼容。 ## 一键启动 克隆仓库并进入项目根目录后执行： ```bash cp .env.example .env docker compose up -d ``` `.env.example` 已填好本地镜像名和目录默认值，复制后可用于本机首次启动。文件内数据库、Redis、JWT 和管理员密码是公开示例值；在开放网络访问或存放真实数据之前，务必把这些值替换为各自独立的随机密钥。首次构建会下载上游源码、大型 CUDA 镜像和约 1.2 GB 的 Qwen3 嵌入模型，耗时取决于网络与硬件。重新编译现有镜像可执行 `docker compose up -d --build`。 ```bash docker compose ps -a docker compose logs -f modelrail-app ``` Web 默认访问 `http://localhost:9000`，API 前缀为 `/api`，初始管理员账号为 `admin`，密码取自 `INITIAL_ADMIN_PASSWORD`。三个构建专用服务显示为 `Exited (0)` 是预期结果。模型下载由 API 执行，下载后可选择量化、微调、评测和部署。 默认 `GPU_PROVIDER=none`，Web/API 无需 GPU 就能启动，GPU 列表为空。只启动 Web/API 和基础服务、跳过训练与推理镜像构建时，可执行 `docker compose up -d modelrail-app`。在 NVIDIA 主机启用监控时，把 `.env` 中的 `GPU_PROVIDER` 改为 `nvidia`，加入 `COMPOSE_PROFILES=gpu`，再执行 `docker compose up -d`；也可用 `docker compose --profile gpu up -d gpu-collector modelrail-app` 启动采集器和应用。监控无需运行训练任务容器；检查 `docker compose ps gpu-collector` 和 `docker compose logs gpu-collector` 可确认采集状态。 检查 API 返回：`curl http://localhost:9000/api/resources/gpu`。无 GPU 模式下返回空的 `gpus_info`；启用采集器后应能看到设备信息。仪表盘在无 GPU 模式下仍显示 CPU 和内存曲线。旧版本自动创建的 `gpu-monitor` 容器不再使用，可在确认没有旧版应用运行后自行清理。 ### 镜像来源与版本 `TRAIN_REF` 和 `LLAMA_CPP_REF` 分别选择 LLaMA Factory 与 llama.cpp 的 Git ref，默认跟随 `main`、`master`；正式部署应改为经过验证的 release tag 或 commit，以便复现构建结果。Compose 使用 [LLaMA Factory 官方 CUDA Dockerfile](https://github.com/hiyouga/LlamaFactory/blob/main/docker/docker-cuda/Dockerfile) 构建训练镜像。llama.cpp 镜像使用本仓库的 `docker/llamacpp/cuda-server.Dockerfile` 拉取官方源码并编译 CUDA 服务端；平台只使用推理 API，因此跳过上游 Web UI 及其 npm 构建。应用镜像也用 `LLAMA_CPP_REF` 编译 CPU 量化工具，避免跨容器共享本机动态库。 vLLM 从 [官方预编译镜像](https://docs.vllm.ai/en/stable/deployment/docker/)生成固定本地 tag，默认基础镜像为 `vllm/vllm-openai:latest`。要固定运行版本，请将 `VLLM_BASE_IMAGE` 设置为经过验证的版本 tag 或 digest。自行从 vLLM 源码编译需要更多构建时间与 CUDA 工具链；可依照官方文档构建后把镜像命名为 `VLLM_IMAGE` 指定的 tag。 API 使用固定的 `TRAIN_IMAGE`、`LLAMA_CPP_IMAGE` 和 `VLLM_IMAGE` 创建任务容器。训练镜像须提供 `llamafactory-cli train`；vLLM 使用 OpenAI 兼容 API Server，llama.cpp 使用 `llama-server`。默认 LLaMA Factory 上游不保证支持 Gemini 扩展参数，Web 创建微调任务时默认关闭 Gemini；只有换用兼容的定制训练镜像时才启用它。 ### 数据目录 | 变量 | 默认值 | 用途 | | ------------------------ | --------------------------- | ----------------------------------------------------------- | | `MODEL_DATA_DIR` | `/var/lib/modelrail/data` | 用户数据、训练和评测输出 | | `MODEL_CACHE_DIR` | `/var/lib/modelrail/cache` | 模型与训练缓存 | | `MODEL_STORAGE_DIR` | `/var/lib/modelrail/models` | 下载的模型 | | `TRAIN_IMAGE` | `modelrail-train:local` | 微调任务镜像 | | `LLAMA_CPP_IMAGE` | `modelrail-llamacpp:local` | llama.cpp 推理容器 | | `VLLM_IMAGE` | `modelrail-vllm:local` | vLLM 推理容器 | | `DIRECT_INFERENCE_PORTS` | `false` | 是否直接将引擎端口发布到主机；默认通过带密钥的 API 网关访问 | | `GPU_PROVIDER` | `none` | `none` 或 `nvidia`；NVIDIA 需启用 `gpu` profile | `MODEL_DATA_DIR`、`MODEL_CACHE_DIR` 和 `MODEL_STORAGE_DIR` 应使用 Docker 主机的绝对路径：API 创建的训练和推理容器会再次挂载这些路径。首次启动会由 Docker 创建目录；部署时应检查可写权限和空间。 容器内的 `DATASETS_DIR` 和 `EMBEDDING_MODELS_DIR` 分别固定为 `/opt/modelrail/datasets` 和 `/opt/modelrail/embedding-models`，随应用镜像提供，不需要在根目录 `.env` 中设置，也不需要挂载空的宿主机模型目录。 ### 推理兼容与外部 API 模型仓库会读取本地 `config.json`、`tokenizer_config.json` 或 GGUF 元数据，记录模型格式、架构、量化方式、任务类型与聊天模板。创建或重启部署前，API 会检查模型路径与运行引擎：llama.cpp 使用 GGUF，vLLM 使用 Hugging Face 格式。嵌入模型以 embeddings 模式启动；无法识别的格式会拒绝部署。此检查是静态预检，不能保证所选镜像一定支持该架构或量化方式，最终仍以运行日志为准。 已登录用户可访问 `GET /api/inferences/runtime-profiles` 查看版本为 `1` 的运行画像，包括引擎、支持的格式与任务、镜像名、当前镜像 ID 和仓库 digest。部署前可以在仓库根目录执行 `bash scripts/check-inference-runtime.sh`，确认本机 Docker、推理镜像、NVIDIA 驱动及容器 GPU 访问。正式环境建议把 `.env` 中的上游源码 ref 和 vLLM 基础镜像固定到 tag/commit/digest，并记录上述接口返回的镜像 ID。 部署正常运行后，打开“模型部署”的详情，为该部署生成外部 API 密钥。密钥只显示一次，服务端仅存哈希；轮换会立即使旧密钥失效，也可以直接撤销。默认不直接发布引擎端口，外部程序调用 ModelRail 的 OpenAI 风格接口： ```bash curl http://localhost:9000/api/v1/models -H 'Authorization: Bearer <部署密钥>' curl http://localhost:9000/api/v1/chat/completions \ -H 'Authorization: Bearer <部署密钥>' -H 'Content-Type: application/json' \ -d '{"model":"<部署的模型名称>","messages":[{"role":"user","content":"你好"}]}' ``` `POST /api/v1/chat/completions` 支持普通和 `stream: true` 的 SSE 对话；`POST /api/v1/embeddings` 接受字符串或字符串数组。两者都需要与部署匹配的 `model` 名称和密钥。每个部署的密钥只允许访问该部署，网关有请求限流，并记录部署 ID、路由、状态及耗时。多模态输入仅接受消息中的 base64 图片，且只对检测为视觉模型的 vLLM 部署放行；实际效果取决于所选模型及 vLLM 镜像。工具调用只对包含聊天模板的模型放行，仍需所选运行时支持对应模板、解析器和参数。音频、视频、重排等端点尚未接入。参考 [vLLM 的 OpenAI 兼容服务说明](https://docs.vllm.ai/en/latest/serving/online_serving/openai_compatible_server/)与 [llama.cpp server 文档](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md)。 需要绕过网关并让引擎自行提供网络 API 时，可显式设置 `DIRECT_INFERENCE_PORTS=true` 后重启部署。此模式不经过 ModelRail 的密钥、限流与审计，端口访问控制需由部署方配置。 ### 离线评测数据与知识库模型 项目固定使用 EvalScope 1.12.0。应用镜像构建时按 [EvalScope 离线评测指引](https://evalscope.readthedocs.io/en/latest/get_started/basic_usage.html)从 ModelScope 下载五个文本基准： | 页面名称 | ModelScope 数据集 ID | 评测方向 | | ----------- | --------------------- | ------------ | | `arc` | `allenai/ai2_arc` | 科学常识推理 | | `gsm8k` | `AI-ModelScope/gsm8k` | 数学推理 | | `mmlu` | `cais/mmlu` | 综合知识 | | `cmmlu` | `evalscope/cmmlu` | 中文综合知识 | | `hellaswag` | `evalscope/hellaswag` | 常识推理 | 数据分别存入镜像中的 `/opt/modelrail/datasets/data/<页面名称>`；下载失败时镜像构建会失败。评测页面按实际安装的目录列出原生基准，运行时无需挂载宿主机的 `datasets` 目录。EvalScope 官方还支持许多文本、多模态和其他类型的基准，但当前页面只对接 OpenAI 兼容的文本模型 API，且不同基准可能需要裁判模型、沙箱、其他依赖或数据许可，因此不在默认构建时全部下载。如需扩展，请先按[官方基准目录](https://evalscope.readthedocs.io/en/latest/get_started/supported_dataset/index.html)确认数据集 ID、格式、运行条件和许可，再在镜像中增加 `modelscope download --dataset --local_dir /opt/modelrail/datasets/data/<基准名>`；目录名必须与 EvalScope 基准名一致。 创建评测任务时选择数据集并提供已启动的 OpenAI 兼容模型 API 地址。平台生成的自定义数据集保存在用户数据目录，格式为 JSON 对象数组；上传的自定义评测文件也可使用 JSONL（每行一个对象）。每条数据需要 `query`/`response` 或 `instruction`/`output` 字段，自定义评测还需选择可访问的裁判模型 API。需要重新获取内置数据集时执行 `docker compose build --no-cache modelrail-app`，再执行 `docker compose up -d`；数据集仓库未固定修订版本，新构建获取的内容可能变化。 知识库固定使用 [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B)（Apache 2.0、1024 维）。`docker compose up -d` 构建应用镜像时从 [ModelScope](https://modelscope.cn/models/Qwen/Qwen3-Embedding-0.6B) 下载到 `/opt/modelrail/embedding-models/Qwen3-Embedding-0.6B` 并检查权重文件；下载失败会使新镜像构建失败。模型权重不存入 Git 仓库。RAG 服务在首次向量化或检索时从镜像内加载模型，检索查询使用模型自带的 `query` 指令；没有 NVIDIA GPU 时可在 CPU 上运行，但速度取决于主机性能。旧 `.env` 中的 `EMBEDDING_MODELS_DIR` 可以删除；宿主机直接运行 `pnpm dev` 时仍须自行准备模型目录和 Python 依赖。 ### 使用与更新 应用在控制台中管理模型下载、数据集、微调任务、量化、评测、推理部署、知识库和对话，也提供用户、角色、权限及登录审计。微调与推理容器由 Docker Engine 按任务创建，停止 Compose 服务不会自动删除所有任务容器；停机前应先在页面停止运行中的任务。 ```bash docker compose down # 保留 PostgreSQL、Redis 与备份卷 docker compose up -d --build # 修改源码或镜像版本后重建 ``` `docker compose down -v` 会删除持久化卷。数据库主版本升级应先备份和迁移，不能直接复用旧主版本的数据目录。应用容器挂载 Docker socket，部署主机须限制访问权限。 ## 本地开发 安装 Node.js 20 和 pnpm 9，然后安装 workspace 依赖： ```bash pnpm install ``` 复制根目录环境变量模板并启动本地 PostgreSQL 17 与 Redis。开发服务器环境文件里的数据库和 Redis 用户、库名、端口及密码应与根目录 `.env` 保持一致： ```bash cp .env.example .env docker compose up -d postgresql redis ``` 分别准备后端环境变量，并根据本机数据库、Redis 和外部运行引擎填写连接信息： ```bash cp packages/apps/api/.env.example packages/apps/api/.env.development cp packages/apps/web/.env.example packages/apps/web/.env ``` 在空的本地开发库运行初始迁移，然后启动前端与后端开发服务： ```bash pnpm --filter api build pnpm --filter api db:migrate pnpm dev ``` 开发 API 默认监听端口由后端环境配置中的 `APP_PORT` 控制（示例为 `3001`）；数据库与 Redis 必须先启动并可从开发主机访问。若执行数据写入或迁移操作，请先使用本地开发数据库，不要指向生产环境。 在宿主机直接运行 `pnpm dev` 时，量化、评测和知识库仍需本机具备对应的 Python 依赖、llama.cpp 工具和运行目录；完整功能以 Compose 构建的应用镜像为准。 构建应用容器镜像： ```bash docker build -t modelrail:local . ``` ## 数据与端口 | 服务 | 默认端口 | 用途 | | ----------------- | ---------------- | ------------------------------------------------- | | ModelRail Web/API | `9000` | 浏览器访问；API 路径为 `/api` | | PostgreSQL | `127.0.0.1:5432` | 应用持久化数据；可用 `POSTGRES_PORT` 修改主机端口 | | Redis | `127.0.0.1:6379` | 会话及缓存；可用 `REDIS_PORT` 修改主机端口 | Compose 使用命名卷 `postgres-data`、`redis-data` 和 `backup-data`。模型与缓存目录通过宿主机路径挂载；官方离线评测数据、量化、评测和 RAG 程序由应用镜像提供。部署前请检查磁盘空间、目录权限和备份策略。 根目录 `.env.example` 将 `DB_SYNCHRONIZE` 设为 `false`。首次启动时，应用先运行 TypeORM 初始迁移创建空库表结构，再启动 Web/API；后续版本通过新增迁移文件变更结构。空库初始化、迁移状态与备份恢复步骤见 [数据库迁移指南](docs/database-migrations.md)。 PostgreSQL 的主版本升级需要单独迁移数据。从 PostgreSQL 15 升级时，不要把旧数据目录直接挂载到 PostgreSQL 17；应先备份，再使用 `pg_dump`/`pg_restore` 或 `pg_upgrade` 迁移。 ## 安全说明 - 不要提交 `.env`、密钥、生产凭据、用户数据或私有模型文件。 - 为每个部署生成独立的数据库、Redis、JWT、刷新令牌和管理员密码；不要在互联网上公开默认数据库端口。 - 初始管理员密码在生产环境至少为 8 个字符，开发环境至少为 6 个字符；生产环境请使用独立且不易猜测的密码。 - 旧版本使用 MD5 加盐的账号可继续登录；成功验证后，后端会自动将密码哈希升级为 scrypt。 - 应用容器访问 `/var/run/docker.sock` 后，便拥有对 Docker Engine 的高权限控制能力。训练与推理任务只使用服务端配置的镜像、受限的用户目录挂载和带归属标签的容器；vLLM 额外参数只允许 `--disable-log-requests` 与 `--enforce-eager`。这些输入限制不能替代进程隔离：生产部署仍应限制主机和 Docker API 的访问，并将 Docker 执行端独立安全审查。 - 外部模型镜像及模型文件应从可信来源获取；固定镜像 tag 或 digest，按部署流程检查更新与来源。 - 生产环境应配置 TLS 终止、网络访问控制、数据备份和日志保留策略。 ## 部署文档 Compose 快速部署和外部引擎接入步骤见本 README；备份、恢复和常用运维命令见 [DEPLOY.md](DEPLOY.md)。 ## 参与贡献与反馈 欢迎通过 [Gitee Issues](https://gitee.com/buera/model-rail/issues) 报告可复现的问题或提出改进建议。提交代码前，请先说明问题与预期行为；Pull Request 尽量只处理一个主题，并同步更新受影响的中英文文档。报告故障时可附上操作步骤、相关版本和脱敏日志，请勿上传 `.env`、访问密钥、用户数据或私有模型。安全漏洞请联系仓库维护者私下报告，避免在公开 Issue 中披露利用细节。 ## 开源许可 本项目以 [MIT License](LICENSE) 发布。构建时获取的上游源码、运行镜像、数据集和模型权重分别遵循其原始许可。 ## 项目名称 ModelRail 描述平台为模型开发、评估与部署提供的一条连续工作轨道。