# Ubuntu22.04 Docker 单容器嵌入式 Milvus Standalone 完整教程
## 环境说明
- 虚拟机：Ubuntu 22.04 LTS，4核8G
- 已装好 Docker，目标：**embed 单容器 Milvus（内置etcd+本地存储，无需单独minio/etcd容器）**，适合学习 SpringBoot4+JDK21+Ollama 向量检索开发
- Milvus 版本：v2.6（稳定最新版）
- 对外端口：`19530`（SDK连接核心端口）、`9091`（监控/Attu可视化）
## 一、前置检查 & 优化Docker（国内必做，解决拉镜像慢）
### 1.1 确认Docker正常、免sudo
```bash
# 查看docker版本
docker -v
# 把当前用户加入docker组，不用每次sudo
sudo usermod -aG docker $USER
newgrp docker
# 测试无sudo运行
docker run hello-world
```
### 1.2 配置国内Docker镜像加速器（关键，否则拉镜像超时）
```bash
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors": [
"https://docker.xuanyuan.me",
"https://docker.1ms.run",
"https://docker.m.daocloud.io"
]
}
EOF
# 重启docker生效
sudo systemctl daemon-reload
sudo systemctl restart docker
```
### 1.3 防火墙放行端口（外部Windows主机连Milvus必备）
```bash
# 放行Milvus核心端口
sudo ufw allow 19530/tcp
sudo ufw allow 9091/tcp
# 查看防火墙规则
sudo ufw status
```
## 二、一键安装嵌入式单容器 Milvus Standalone（官方脚本）
### 2.1 下载官方启动脚本（国内CDN加速，解决github raw打不开）
```bash
# 使用jsdelivr CDN下载脚本
curl -sfL https://cdn.jsdelivr.net/gh/milvus-io/milvus/scripts/standalone_embed.sh -o standalone_embed.sh
# 添加执行权限
chmod +x standalone_embed.sh
```
### 2.2 启动 Milvus
```bash
bash standalone_embed.sh start
```
执行逻辑：
1. 自动拉取 `milvusdb/milvus:v2.6.2` 镜像
2. 创建单容器 milvus，内置嵌入式etcd，**无需额外minio/etcd容器**
3. 自动创建本地持久化目录 `./volumes/milvus`（向量数据、元数据都存在这里）
4. 映射端口 `19530:19530`、`9091:9091`
5. 等待90秒左右，输出 `Start successfully.` 代表启动完成
### 2.3 常用管理命令
```bash
# 停止Milvus
bash standalone_embed.sh stop
# 重启Milvus（修改配置后用）
bash standalone_embed.sh restart
# 删除Milvus容器（保留本地数据volumes）
bash standalone_embed.sh delete
# 彻底删除容器+本地所有向量数据（清空测试数据）
bash standalone_embed.sh destroy
```
## 三、验证Milvus是否正常运行
### 3.1 查看容器状态
```bash
docker ps | grep milvus
```
正常输出：容器状态 `Up`，端口19530、9091映射成功。
### 3.2 使用Attu可视化工具连接Milvus（网页管理，推荐）
Attu是Milvus官方WebUI，方便建集合、插入向量、查询、看索引
1. 本地/Windows主机浏览器打开：`http://虚拟机IP:9091/webui`
2. 连接参数：
- Host：虚拟机IP
- Port：19530
- 用户名/密码：默认无，直接连接
### 3.3 Python快速连通测试（可选，验证服务可用性）
```bash
# 安装sdk
pip install pymilvus
```
新建 `test_milvus.py`
```python
from pymilvus import connections
# 替换为你的虚拟机IP
connections.connect(
alias="default",
host="192.168.1.100",
port="19530"
)
print("Milvus连接成功！")
```
运行：`python test_milvus.py`，无报错即服务正常。
## 四、SpringBoot4 连接Milvus关键信息（你后续开发用）
### 连接地址
```
milvus.address=虚拟机IP
milvus.port=19530
```
### Maven依赖（SpringBoot4 + JDK21）
```xml
```
## 五、目录与配置说明
执行脚本后当前目录生成文件：
1. `volumes/milvus`：**持久化数据目录**，删除容器数据不丢失
2. `user.yaml`：自定义Milvus配置文件，修改后 `restart` 生效
3. `embedEtcd.yaml`：内置etcd配置，一般不用改
## 六、常见踩坑解决（4核8G虚拟机专属）
### 坑1：容器启动几秒就退出 Exited(134)
原因：内存不足/权限不足
```bash
# 给数据目录完整权限
sudo chmod -R 777 ./volumes
# 虚拟机分配内存至少6G，8G推荐关闭其他占用程序
```
### 坑2：外部Windows连不上19530端口
1. 虚拟机防火墙放行端口（前面步骤已做）
2. 虚拟机网络模式改为**桥接模式**，不要NAT仅主机
3. 查看虚拟机IP：`ip a`，用桥接IP连接，不要127.0.0.1
### 坑3：拉镜像超时/失败
确认已配置Docker国内镜像加速器，重启docker后重新执行start脚本。
### 坑4：4核8G运行卡顿
1. 测试阶段向量数据量不要过大（单集合十万以内向量）
2. Ollama、Milvus不要同时满载运行，可分开启动测试
## 七、手动docker run 单容器命令（不想用脚本备用方案）
不想用官方脚本，直接一条命令启动嵌入式Milvus：
```bash
# 创建持久化目录
mkdir -p ~/milvus_data
sudo chmod 777 ~/milvus_data
# 启动单容器embed milvus
docker run -d \
--name milvus-standalone \
--restart unless-stopped \
-p 19530:19530 \
-p 9091:9091 \
-v ~/milvus_data:/var/lib/milvus \
-e ETCD_USE_EMBED=true \
-e DEPLOY_MODE=STANDALONE \
milvusdb/milvus:v2.6.2 milvus run standalone
```
## 八、端口汇总
| 端口 | 用途 | 访问方 |
|-------|------|--------|
| 19530 | gRPC核心端口，SDK/Java/SpringBoot连接 | 你的开发电脑、后端服务 |
| 9091 | Attu WebUI、监控指标 | 浏览器 |
部署完成后，你就可以在SpringBoot4项目中对接Milvus，配合Ollama生成向量存入Milvus做检索学习。