# ELK-docker

**Repository Path**: kikt/ELK-base

## Basic Information

- **Project Name**: ELK-docker
- **Description**: ELK docker
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-30
- **Last Updated**: 2025-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ELK Stack 使用说明

本仓库提供一个可直接启动的 Elasticsearch + Logstash + Kibana (ELK) 栈，所有持久化数据均保存在当前目录，通过相对路径绑定到容器内。请按照以下步骤部署与使用。

## 目录结构说明

- `docker-compose.yaml`：定义 Elasticsearch、Logstash、Kibana 三个服务的镜像、端口、卷挂载与依赖关系。
- `.env`：集中管理镜像版本号、宿主机暴露端口等变量，方便统一调整。
- `config/`：包含各组件的配置文件，可根据业务需求定制。
  - `config/elasticsearch/elasticsearch.yml`
  - `config/logstash/logstash.yml`
  - `config/logstash/pipeline/logstash.conf`
  - `config/kibana/kibana.yml`
- `data/`：容器启动后写入的数据目录（日志索引、状态等）。默认未提交，可在首次启动前手动创建，或由 Docker 自动创建。

## 准备工作

1. **安装 Docker 与 Docker Compose**：确保本机已安装 Docker Engine 与 `docker compose` 插件。Mac/Linux 用户可以执行 `docker --version` 和 `docker compose version` 验证。若未安装，请参考 [Docker 安装指南](https://docs.docker.com/get-docker/)。
2. **克隆或复制项目**：将本仓库放置到希望持久化数据的路径（例：`/Users/you/workspace/ELK-Stack`）。
3. **进入目录**：

   ```bash
   cd /path/to/ELK-Stack
   ```

4. **（可选）创建数据目录**：提前创建并设置权限，避免容器以 root 身份写入时产生权限问题：

   ```bash
   mkdir -p data/elasticsearch data/logstash data/kibana
   chmod -R 777 data
   ```

   若不想开放 777，可根据宿主机用户与 Docker 容器的运行用户调整更细致的权限策略。

## 启动 ELK 栈

1. **加载环境变量**：`docker compose` 会自动读取同目录下的 `.env` 文件，无需额外操作。若需临时修改参数（例如端口或 Elastic 版本），请先编辑 `.env` 并保存。
2. **启动服务**：

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

   - 首次拉取镜像可能耗时较长，请保持网络畅通。
   - 若希望实时观察启动日志，可省略 `-d` 参数，以前台模式运行。

3. **确认容器状态**：

   ```bash
   docker compose ps
   ```

   - 状态为 `running` 表示启动成功。
   - 若有容器异常退出，可执行 `docker compose logs <服务名>` 查看详细日志。

4. **健康检查**：

   - 访问 Elasticsearch：`curl http://localhost:9200`，返回 JSON 状态即可。
   - 打开 Kibana：浏览器访问 `http://localhost:5601`，首次加载需要等待后端初始化。
   - Logstash 默认提供 Beats 输入和 HTTP 监控接口，可使用 `curl http://localhost:9600/_node/stats` 验证。

## 默认端口信息

| 组件                | 宿主机端口（默认） | 容器内端口 |
|---------------------|--------------------|------------|
| Elasticsearch        | 9200               | 9200       |
| Logstash Beats 输入  | 5044               | 5044       |
| Logstash HTTP API    | 9600               | 9600       |
| Kibana Web UI        | 5601               | 5601       |

- 如需修改，请编辑 `.env` 中的对应变量 (`ES_PORT`、`LOGSTASH_BEATS_PORT`、`LOGSTASH_HTTP_PORT`、`KIBANA_PORT`) 并重新 `docker compose up -d`。
- 修改端口后，别忘了同步更新防火墙、安全组或上报客户端配置。

## 常用运维命令

- 查看某服务日志（实时）：`docker compose logs -f logstash`
- 重启单个服务：`docker compose restart kibana`
- 停止全部服务：`docker compose down`
- 停止并删除卷（清空数据）：`docker compose down -v`（慎用）
- 更新到新版本：修改 `.env` 中 `ELASTIC_VERSION` → 执行 `docker compose pull && docker compose up -d`

## 更多官方资料

- [Elasticsearch 文档](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)
- [Logstash 文档](https://www.elastic.co/guide/en/logstash/current/index.html)
- [Kibana 文档](https://www.elastic.co/guide/en/kibana/current/index.html)
- [Beats 文档](https://www.elastic.co/guide/en/beats/filebeat/current/index.html)

阅读官方文档时，可结合本项目的配置文件了解每项参数的作用，逐步定制更符合业务需求的方案。

## 远程日志上报示例（以 Filebeat 为例）

1. **确保网络连通**：远端服务器需要能够访问 Logstash 所在主机的 `5044` 端口。若有防火墙或安全组限制，请提前放通。
2. **安装 Filebeat**：按照官方文档在远端机器安装 Filebeat。
3. **配置 Filebeat**（示例：`/etc/filebeat/filebeat.yml`）：

   ```yaml
   filebeat.inputs:
     - type: log
       enabled: true
       paths:
         - /var/log/messages
         - /var/log/nginx/*.log

   output.logstash:
     hosts: ["logstash.example.com:5044"]
   ```

   - 将 `logstash.example.com` 替换为可访问本地 Logstash 的域名或 IP。
   - 若 `.env` 中修改了 `LOGSTASH_BEATS_PORT`，此处也要同步更新。

4. **测试连接**：在远端执行 `filebeat test output` 检查是否正常连接到 Logstash。
5. **启动 Filebeat**：

   ```bash
   sudo systemctl enable --now filebeat
   ```

6. **验证数据是否进入 Elasticsearch**：在 Kibana Dev Tools 中执行：

   ```http
   GET /logstash-*/_search
   {
     "size": 5,
     "sort": [{"@timestamp": {"order": "desc"}}]
   }
   ```

   若返回最近的日志内容，说明数据链路畅通。

> 如果计划使用 TLS 或用户名/密码进行加密认证，需要在 Logstash input、Filebeat output 以及 Elasticsearch/Kibana 中开启 `xpack.security`，并配置证书。详细步骤请参考官方文档。

## 通过反向代理暴露服务

如果需要在公网或公司内部通过统一域名访问 ELK，可使用 Nginx / Traefik 等反向代理。以下以 Nginx 为例：

1. **准备域名与证书**：为 Kibana 和 Elasticsearch 申请 HTTPS 证书（可使用 Let’s Encrypt 或公司 CA）。假设需要两个子域：`kibana.example.com` 与 `es.example.com`。
2. **安装并配置 Nginx**：在代理服务器上创建配置文件，例如 `/etc/nginx/conf.d/kibana.conf`：

   ```nginx
   server {
       listen 80;
       server_name kibana.example.com;
       return 301 https://$host$request_uri;
   }

   server {
       listen 443 ssl;
       server_name kibana.example.com;

       ssl_certificate     /etc/nginx/ssl/kibana.crt;
       ssl_certificate_key /etc/nginx/ssl/kibana.key;

       location / {
           proxy_pass http://localhost:5601;
           proxy_set_header Host $host;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_read_timeout 300;
       }
   }
   ```

   - `proxy_pass` 指向运行 Kibana 的主机与端口，如代理与容器同机则为 `http://localhost:5601`。
   - Kibana 默认需要较长的超时时间，建议设置 `proxy_read_timeout` ≥ 300 秒。

3. **Elasticsearch 反代（可选）**：若要暴露 Elasticsearch REST API，可类似配置 `es.example.com`，但强烈建议在安全控制下使用，避免未授权访问。
4. **开启 Elastic 安全特性**：在公网环境请开启 `xpack.security`，为 Kibana 设置登录账户，并对 Elasticsearch 配置角色与权限。简要步骤：

   - 在 `config/elasticsearch/elasticsearch.yml` 中启用 `xpack.security.enabled: true`。
   - 在 `.env` 或 Compose 中添加初始用户凭据或使用 Elastic 提供的 `elasticsearch-setup-passwords` 工具设置密码。
   - 在 `config/kibana/kibana.yml` 中配置 `elasticsearch.username` 与 `elasticsearch.password`。
   - 在 `config/logstash/logstash.yml` 与 `logstash.conf` 中配置输出到受保护的 Elasticsearch。

5. **重启服务并验证**：

   ```bash
   sudo nginx -t && sudo systemctl reload nginx
   docker compose restart kibana elasticsearch logstash
   ```

   通过浏览器访问 `https://kibana.example.com` 验证是否能正常打开；使用 `curl https://es.example.com`（加上认证）检测 Elasticsearch。

## 故障排查建议

- **容器无法启动**：查看相应服务日志，检查配置语法、端口占用或内存不足。
- **Kibana 无法访问 Elasticsearch**：确认网络是否通畅、Elasticsearch 是否启动、认证信息是否正确。
- **Logstash 无数据输出**：检查 `logstash.conf` pipeline 语法、Beats 客户端配置和防火墙。
- **索引存储膨胀**：使用 ILM（Index Lifecycle Management）或定期清理历史索引，避免磁盘占满。

按照以上步骤即可更细致地掌控 ELK 栈的部署与运维。若需更高级功能（如 APM、Fleet、Machine Learning），可在此基础上继续扩展配置。祝使用顺利！