RuoYi AI 使用教程：按官方 Docker 流程从零启动
这篇文章按 RuoYi AI 官方仓库给出的 Docker 流程整理，从克隆源码、一键启动、查看服务状态到访问管理端和排查端口，尽量不跳步骤。
我这次整理 RuoYi AI，不打算把它写成“功能介绍合集”。真正容易卡住的地方不是它支持多少模型、多少智能体，而是第一次把服务跑起来时，目录、命令和端口很容易混在一起。
下面的流程严格按官方仓库 https://github.com/ageerle/ruoyi-ai 里的 Docker 部署说明来走。只要你的机器已经装好 Docker 和 Docker Compose，就可以先用“一键启动所有服务”的方式把环境跑通。
先确认这是什么项目
RuoYi AI 是一个企业级 AI 助手平台，后端基于 Spring Boot 3.5.8 + Langchain4j，数据层用到 MySQL 8.0、Redis、向量数据库，前端包括管理端和用户端。
官方仓库把项目拆成几个部分：
| 模块 | 仓库 |
|---|---|
| 后端服务 | ageerle/ruoyi-ai |
| 用户前端 | ageerle/ruoyi-web |
| 管理后台 | ageerle/ruoyi-admin |
如果只是想先体验系统，优先使用后端仓库里提供的 Docker 一键启动方案，不要一开始就分别编译三个项目。这样可以先确认服务、数据库、缓存和前端之间能正常连起来。
准备环境
开始之前，先在服务器或本机确认这几件事：
docker -v
docker-compose -v如果你的环境使用的是新版 Compose 插件，也可能是：
docker compose version官方 README 使用的是 docker-compose 写法，下面也先保留这个写法。要是你的机器只有 docker compose，把命令里的 docker-compose 替换成 docker compose 即可。
另外，建议提前确认这些端口没有被占用：
| 服务 | 一键启动端口 | 用途 |
|---|---|---|
| 管理端 | 25666 | 管理后台页面 |
| 用户端 | 25137 | 用户前端页面 |
| 后端 API | 26039 | 后端接口服务 |
| MySQL | 23306 | 数据库 |
| Redis | 26379 | 缓存 |
| Weaviate | 28080 | 向量数据库 |
| MinIO API | 29000 | 对象存储 API |
| MinIO Console | 29090 | 对象存储控制台 |
端口占用是第一次部署时最常见的问题之一。尤其是 MySQL、Redis，本机可能已经有服务在跑。
第一步：克隆后端仓库
先把官方后端仓库拉下来：
git clone https://github.com/ageerle/ruoyi-ai.git
cd ruoyi-ai这里不要急着进入其他目录。后面的 Docker Compose 命令都默认你在 ruoyi-ai 项目目录下执行。
第二步：用官方一键 Compose 启动全部服务
官方推荐的一键启动方式是使用 docker-compose-all.yaml，它会启动这些服务：
- MySQL 8.0，包含初始化 SQL；
- Redis 6.2；
- Weaviate 向量数据库；
- MinIO 对象存储；
- RuoYi AI 后端服务；
- 管理端前端；
- 用户端前端。
执行命令：
docker-compose -f docker-compose-all.yaml up -d如果你的仓库版本里 Docker 文件放在 docs/docker/ruoyi-ai/ 下，可以进入对应目录，或者把 compose 文件复制到项目根目录后再执行。关键点是：使用官方提供的 docker-compose-all.yaml，不要自己临时拼服务。
启动时会拉取官方预构建镜像，镜像仓库地址是：
crpi-31mraxd99y2gqdgr.cn-beijing.personal.cr.aliyuncs.com/ruoyi_ai可用镜像包括：
mysql:v3
redis:6.2
weaviate:1.30.0
minio:latest
ruoyi-ai-backend:latest
ruoyi-ai-admin:latest
ruoyi-ai-web:latest第一次拉镜像会比较慢，尤其是网络不稳定时，不要看到终端没动就立刻中断。
第三步：查看服务是否都起来了
启动完成后先看容器状态：
docker-compose -f docker-compose-all.yaml ps正常情况下，至少应该能看到这些容器：
ruoyi-ai-mysql
ruoyi-ai-redis
ruoyi-ai-weaviate
ruoyi-ai-minio
ruoyi-ai-backend
ruoyi-ai-admin
ruoyi-ai-web如果后端没有起来，先看后端日志：
docker-compose -f docker-compose-all.yaml logs -f backend这里要注意一个顺序：后端依赖 MySQL 和 Redis。MySQL 第一次初始化会花一点时间，所以后端刚开始重启一两次并不一定是严重问题。等数据库健康检查通过后，再看后端是否稳定。
第四步：访问管理端、用户端和后端 API
官方一键启动的访问地址是：
管理端：http://localhost:25666
用户端：http://localhost:25137
后端 API：http://localhost:26039管理端默认账号：
admin / admin123如果你是在服务器上部署，把 localhost 换成服务器 IP 或域名。例如：
http://你的服务器IP:25666如果页面打不开，先不要急着改配置。按这个顺序查：
docker-compose -f docker-compose-all.yaml ps看容器是否运行；- 确认服务器安全组、防火墙是否放行端口；
- 看管理端日志和后端日志；
- 确认浏览器访问的是一键启动端口，不是分步部署端口。
第五步：常用管理命令
停止全部服务：
docker-compose -f docker-compose-all.yaml down查看某个服务日志：
docker-compose -f docker-compose-all.yaml logs -f 服务名例如查看后端：
docker-compose -f docker-compose-all.yaml logs -f backend重启某个服务：
docker-compose -f docker-compose-all.yaml restart 服务名例如重启后端：
docker-compose -f docker-compose-all.yaml restart backend这几个命令比反复 down 再 up 更适合排查问题。尤其是数据库已经初始化后，不要随便删除 volume，否则数据会被清掉。
分步部署适合什么情况
如果你只是体验系统，用一键启动就够了。
如果你要改后端源码，再考虑官方的分步部署。流程大致是：
1. 后端服务源码编译启动
cd ruoyi-ai
docker-compose up -d --build
docker-compose logs -f backend这个方式会从源码构建后端服务，同时启动后端依赖的 MySQL、Redis、Weaviate 和 MinIO。
2. 管理端单独构建
cd ruoyi-admin
docker-compose up -d --build分步部署下，管理端访问地址是：
http://localhost:56663. 用户端单独构建
cd ruoyi-web
docker-compose up -d --build分步部署下，用户端访问地址是：
http://localhost:5137这里最容易混淆的是端口：一键启动和分步部署端口不完全一样。比如管理端一键启动是 25666，分步部署是 5666。
我建议保留的一套检查顺序
如果你想严格按流程操作，可以把下面这段当成部署检查单：
1. 安装 Docker 和 Docker Compose
2. 克隆 https://github.com/ageerle/ruoyi-ai
3. 进入 ruoyi-ai 项目目录
4. 执行 docker-compose -f docker-compose-all.yaml up -d
5. 执行 docker-compose -f docker-compose-all.yaml ps
6. 后端异常时查看 docker-compose -f docker-compose-all.yaml logs -f backend
7. 访问 http://localhost:25666
8. 使用 admin / admin123 登录管理端
9. 再访问 http://localhost:25137 检查用户端
10. 最后根据需要配置模型、知识库、向量库和对象存储这套顺序看起来有点慢，但第一次部署 AI 平台时，慢一点反而更稳。因为 RuoYi AI 不是单容器应用，它同时依赖数据库、缓存、向量数据库、对象存储、后端和两个前端。跳过检查，很容易不知道问题出在哪一层。
几个常见问题
1. 页面打不开
先确认容器状态：
docker-compose -f docker-compose-all.yaml ps如果容器都正常，再检查端口放行。服务器环境里，云厂商安全组经常会拦住 25666、25137 这类非标准端口。
2. 后端一直重启
优先看后端日志：
docker-compose -f docker-compose-all.yaml logs -f backend再看 MySQL 是否健康。第一次启动时数据库初始化慢，后端可能会等不到数据库。
3. 端口和文档对不上
记住这个区别：
| 部署方式 | 管理端 | 用户端 | 后端 API |
|---|---|---|---|
| 一键启动 | 25666 | 25137 | 26039 |
| 分步部署 | 5666 | 5137 | 6039 / 映射后按 compose 为准 |
实际访问以你使用的 compose 文件为准。如果改过端口，浏览器地址也要跟着改。
4. 要不要一开始就改数据库密码
本地体验可以先不改，先把系统跑通。准备放到公网或长期使用时，再统一修改 MySQL、Redis、MinIO 等密码，并检查后端环境变量是否同步更新。
收尾
RuoYi AI 第一次部署，最重要的不是马上配置所有模型，而是先确认基础链路跑通：数据库能初始化、后端能连上 Redis、管理端能打开、默认账号能登录。
等这一步稳定后，再去配置模型接入、RAG 知识库、MCP 工具和多智能体编排，后面排错会轻松很多。