---
title: "十分钟上手：用 Docker 快速拉起 Easysearch"
date: 2026-01-09
lastmod: 2026-01-09
description: "详解用 Docker 快速部署 Easysearch 单节点环境的完整步骤，深入讲解配置持久化、证书管理、UID 602 权限处理、Docker Compose 编排及常见部署陷阱，帮助新手 10 分钟快速上手。"
tags: ["Docker", "快速启动", "部署"]
summary: "对于开发者来说，使用 Docker 是体验 INFINI Easysearch 最快捷的方式。但如果只是简单地启动容器，重启后会导致SSL 证书重置和数据丢失。
为了避免这些坑，本文将教你用“正确的姿势”在 10 分钟内搭建一个配置持久化、证书固定、数据安全的单节点 Easysearch 环境。
核心知识点预告 #  在开始之前，请记住 Easysearch Docker 镜像的两个特殊设定，这能帮你避开 99% 的启动报错：
 **初始密码：**通过环境变量 EASYSEARCH_INITIAL_ADMIN_PASSWORD 来设置。 用户 ID (UID)：镜像内部进程使用 UID 602，而非 Docker 常见的 1000 或 0。 配置目录：/app/easysearch/config 必须持久化，否则每次重启都会生成新证书，导致客户端连接失败。   第一步：初始化项目与获取配置 #  由于我们不能挂载一个空目录到容器的配置路径（会导致启动报错），我们需要先启动一个临时容器，把里面的默认配置“偷”出来。
打开终端，执行以下命令：
# 1. 创建项目目录 mkdir -p easysearch/{data,logs} cd easysearch # 2. 启动一个临时容器（后台运行） # 注意：这一步不需要挂载任何卷 docker run -d --name es-temp -e EASYSEARCH_INITIAL_ADMIN_PASSWORD=Easysearch123! infinilabs/easysearch:2.0.3 # 3. 从容器中拷贝 config 目录到宿主机 docker cp es-temp:/app/easysearch/config ."
---


对于开发者来说，使用 Docker 是体验 INFINI Easysearch 最快捷的方式。但如果只是简单地启动容器，重启后会导致**SSL 证书重置**和**数据丢失**。

为了避免这些坑，本文将教你用“正确的姿势”在 10 分钟内搭建一个**配置持久化、证书固定、数据安全**的单节点 Easysearch 环境。

## 核心知识点预告

在开始之前，请记住 Easysearch Docker 镜像的两个特殊设定，这能帮你避开 99% 的启动报错：

1. **初始密码：**通过环境变量 EASYSEARCH_INITIAL_ADMIN_PASSWORD 来设置。
2. **用户 ID (UID)**：镜像内部进程使用 **UID 602**，而非 Docker 常见的 1000 或 0。
3. **配置目录**：`/app/easysearch/config` 必须持久化，否则每次重启都会生成新证书，导致客户端连接失败。

---

## 第一步：初始化项目与获取配置

由于我们不能挂载一个空目录到容器的配置路径（会导致启动报错），我们需要先启动一个临时容器，把里面的默认配置“偷”出来。

打开终端，执行以下命令：

```bash
# 1. 创建项目目录
mkdir -p easysearch/{data,logs}
cd easysearch

# 2. 启动一个临时容器（后台运行）
# 注意：这一步不需要挂载任何卷
docker run -d --name es-temp -e EASYSEARCH_INITIAL_ADMIN_PASSWORD=Easysearch123! infinilabs/easysearch:2.0.3

# 3. 从容器中拷贝 config 目录到宿主机
docker cp es-temp:/app/easysearch/config ./config

# 4. 删除临时容器
docker rm -f es-temp
```

此时，你的当前目录下应该有两个文件夹：`data` (空) 和 `config` (包含 easysearch.yml, jvm.options, certs 等)。

---

## 第二步：修正文件权限 (关键步骤)

这是 Easysearch 最特别的地方。因为容器内进程 ID 是 **602**，如果宿主机的文件夹权限属于 root 或其他用户，容器将无法读写。

**Linux / macOS 用户请执行：**

```bash
# 将 data 和 config 目录的所有者修改为 602
sudo chown -R 602:602 ./data ./config ./logs

# 验证权限（可选）
ls -ln
# 确保输出中文件夹的属主 ID 是 602
```

_Windows Docker Desktop 用户通常不需要此步骤，因为 Docker Desktop 会自动处理跨系统的权限映射。_

---

## 第三步：编写 Docker Compose

创建 `docker-compose.yml` 文件，填入以下内容。这是标准的单节点开发环境配置：

```yaml
version: "3"

services:
  easysearch:
    image: infinilabs/easysearch:2.0.3
    container_name: easysearch-node
    environment:
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m" # 限制堆内存，适合个人电脑
    ulimits:
      memlock:
        soft: -1
        hard: -1
    volumes:
      - ./data:/app/easysearch/data # 【持久化】数据目录，重启不丢数据
      - ./config:/app/easysearch/config # 【持久化】配置目录，重启不丢证书和配置
      - ./logs:/app/easysearch/logs # 【持久化】日志目录，重启不丢日志
    ports:
      - "9200:9200"
    networks:
      - easysearch-net

networks:
  easysearch-net:
    driver: bridge
```

---

## 第四步：启动服务

一切准备就绪，启动容器：

```bash
docker compose up -d
```

等待约 10-30 秒，查看容器日志确认启动成功：

```bash
docker logs -f easysearch-node
```

当你看到类似 `started` 的日志，且没有报错退出时，说明服务已上线。

---

## 第五步：验证运行

Easysearch 默认开启了 HTTPS 和 HTTP Basic Auth 认证。

### 1. 检查证书

由于我们持久化了 config 目录，可以直接在本地查看生成的证书：`ls ./config/certs/`

### 2. 使用 Curl 访问

由于是自签名证书，curl 需要加 `-k` (insecure) 参数。

```bash
curl -k -u 'admin:Easysearch123!' https://localhost:9200
```

**预期返回：**

```json
{
  "name" : "node-1",
  "cluster_name" : "infinilabs",
  "cluster_uuid" : "8znEx5sqTmGmiGXC7TBe4w",
  "version" : {
    "distribution" : "easysearch",
    "number" : "2.0.3",
    "distributor" : "INFINI Labs",
    ......
  },
  "tagline" : "You Know, For Easy Search!"
}
```

---

## 进阶：如何修改配置？

现在你已经拥有了一个完美的开发环境。

- **修改参数**：比如想开启跨域支持，只需用文本编辑器打开本地的 `./config/easysearch.yml`，添加配置项，保存。
- **生效配置**：执行 `docker compose restart`。
- **结果**：因为证书在本地 `./config/certs` 里没变，你的 Java/Python 客户端不需要重新导入证书，开发体验极其丝滑。

## 总结

通过 **“先拷贝配置 -> 修正 602 权限 -> 挂载启动”** 这三板斧，你成功避开了 Docker 部署 Easysearch 最常见的权限与证书陷阱。现在，你可以开始尽情探索搜索的世界了！