---
title: "使用 Docker 和 Docker Compose 建立 Neo4j 資料庫"
description: "Neo4j作為領先的圖形資料庫，專為高效處理關聯性資料而設計，其獨特的節點與關係模型使其在處理複雜連接資料時表現出色。圖形資料庫的核心優勢在於其能夠直觀地表示和查詢實體間的關係，這對於社交網絡分析、推薦系統和知識圖譜等應用尤為重要。使用Docker容器化Neo4j帶來諸多好處，包括環境隔離、快速部署、版本控制和資源管理等。容器化技術確保開發、測試和生產環境的一致性，同時簡化了擴展和遷移過程。"
slug: "how-to-create-neo4j-database-using-docker-and-docker-compose"
date: 2025-03-18T00:00:00.000Z
url: https://calpa.me/blog/how-to-create-neo4j-database-using-docker-and-docker-compose/
---

> ⚠️ **時效警告**：本文發佈於 2025 年，文中指令針對 Neo4j 4.4（Neo4j 5 起備份指令改為 `neo4j-admin database backup`，APOC 版本也需對應主版本）。內容保留作為歷史紀錄，最新做法請參考官方文件。

## Neo4j 與容器化簡介

### 圖形資料庫與容器的結合優勢

Neo4j 作為領先的圖形資料庫，專為高效處理關聯性資料而設計，其獨特的節點與關係模型使其在處理複雜連接資料時表現出色。圖形資料庫的核心優勢在於其能夠直觀地表示和查詢實體間的關係，這對於社交網絡分析、推薦系統和知識圖譜等應用尤為重要。使用 Docker 容器化 Neo4j 帶來諸多好處，包括環境隔離、快速部署、版本控制和資源管理等。容器化技術確保開發、測試和生產環境的一致性，同時簡化了擴展和遷移過程。

### Docker 與 Docker Compose 基本概念

Docker 是一個開源的容器化平台，它使應用程序及其依賴項可以被打包成標準化單元（稱為容器），確保在任何環境中都能一致地運行。Docker 容器輕量且獨立，共享主機系統的核心，但在應用層面保持隔離。Docker Compose 則是一個用於定義和運行多容器 Docker 應用的工具，它使用 YAML 檔案來配置應用的服務，並通過單一命令創建和啟動所有服務。在設置 Neo4j 等資料庫時，Docker Compose 特別有用，因為它簡化了網絡設置、持久化存儲和環境變量配置等複雜任務。

## 使用 Docker 運行 Neo4j

![Docker Neo4j](/images/blog/how-to-create-neo4j-database-using-docker-and-docker-compose/unsplash-c5249f4df085-4GAru8B.jpg)

### 基本 Docker 命令

使用 Docker 部署 Neo4j 的第一步是獲取官方映像。Neo4j 提供了多個版本的 Docker 映像，包括社區版和企業版。要獲取最新的 Neo4j 映像，可以執行以下命令：

```bash
docker pull neo4j:latest
```

對於特定版本或企業版，可以指定相應的標籤：

```bash
docker pull neo4j:4.4.0
# 或企業版
docker pull neo4j:4.4.0-enterprise
```

拉取映像後，可以使用 `docker run` 命令啟動 Neo4j 容器：

```bash
docker run \
    --name neo4j \
    -p 7474:7474 -p 7687:7687 \
    -d \
    -v $HOME/neo4j/data:/data \
    -v $HOME/neo4j/logs:/logs \
    -v $HOME/neo4j/import:/var/lib/neo4j/import \
    -v $HOME/neo4j/plugins:/plugins \
    --env NEO4J_AUTH=neo4j/yourpassword \
    neo4j:latest
```

### 理解重要參數與配置

上述命令包含多個重要參數，每個參數都對容器的運行方式有顯著影響。`--name` 參數為容器指定名稱，便於後續操作引用。`-p` 參數映射容器端口到主機，7474 是 Neo4j 瀏覽器界面的 HTTP 端口，7687 是 Bolt 協議端口，用於應用程序連接。`-d` 參數使容器在後台運行。`-v` 參數建立卷映射，確保資料持久化存儲；這裡我們映射了四個重要目錄：資料存儲、日誌文件、導入目錄和插件目錄。`--env` 參數設置環境變量，特別是初始身份驗證憑據。

### 訪問與驗證 Neo4j 實例

![Neo4j Website](/images/blog/how-to-create-neo4j-database-using-docker-and-docker-compose/unsplash-c5249f4df085-kgTQYPK.jpg)

容器啟動後，可以通過瀏覽器訪問 Neo4j 的網頁界面：`http://localhost:7474`。首次登入時，使用用戶名 "neo4j" 和之前設置的密碼。成功登入後，您將看到 Neo4j 瀏覽器界面，可以開始執行 Cypher 查詢語言來操作圖形資料庫。要檢查容器狀態，可以使用以下命令：

```bash
docker ps
# 查看容器日誌
docker logs neo4j
```

## 使用 Docker Compose 設置 Neo4j

### Docker Compose 文件結構

雖然可以使用單一 Docker 命令運行 Neo4j，但 Docker Compose 提供了更組織化和可維護的方法。首先，創建一個名為 `docker-compose.yml` 的文件，其基本結構如下：

```yaml
version: "3"
services:
  neo4j:
    image: neo4j:latest
    container_name: neo4j
    ports:
      - "7474:7474"
      - "7687:7687"
    volumes:
      - ./data:/data
      - ./logs:/logs
      - ./import:/var/lib/neo4j/import
      - ./plugins:/plugins
    environment:
      - NEO4J_AUTH=neo4j/yourpassword
      - NEO4J_dbms_memory_pagecache_size=1G
      - NEO4J_dbms.memory.heap.initial_size=1G
      - NEO4J_dbms_memory_heap_max__size=1G
```

這個配置文件定義了一個名為 "neo4j" 的服務，設置了必要的端口映射、卷和環境變量。相對路徑 `./data`、`./logs` 等會自動創建在 `docker-compose.yml` 所在的目錄下，提供了更清晰的結構化管理。除了基本設置，此配置還包含了內存配置參數，這對於生產環境的性能優化至關重要。

### 啟動與管理 Neo4j 容器

有了 Docker Compose 配置文件後，可以使用以下命令啟動服務：

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

`-d` 參數使服務在後台運行。要檢查服務狀態，使用：

```bash
docker-compose ps
```

若需要停止服務而不刪除容器：

```bash
docker-compose stop
```

完全停止並移除容器和網絡：

```bash
docker-compose down
```

若需連同卷一起刪除（慎用，將永久刪除資料）：

```bash
docker-compose down -v
```

### 設置持久化存儲

Docker 容器本身是臨時的，如果容器被刪除，其中的資料也會丟失。因此，正確設置持久化存儲對於資料庫至關重要。在 Docker Compose 配置中，我們通過卷映射實現持久化：

```yaml
volumes:
  - ./data:/data # 存儲資料庫文件
  - ./logs:/logs # 存儲日誌
  - ./import:/var/lib/neo4j/import # 用於導入 CSV 等文件
  - ./plugins:/plugins # 用於額外的插件
```

這些卷確保即使容器被刪除，資料仍然安全地存儲在主機上。此外，還可以使用 Docker 命名卷代替相對路徑，提供更好的隔離性：

```yaml
volumes:
  - neo4j_data:/data
  - neo4j_logs:/logs
  - neo4j_import:/var/lib/neo4j/import
  - neo4j_plugins:/plugins

volumes:
  neo4j_data:
  neo4j_logs:
  neo4j_import:
  neo4j_plugins:
```

## Neo4j 的進階配置

### 內存設置優化

Neo4j 是一個內存密集型資料庫，適當的內存配置對性能有顯著影響。在 Docker Compose 文件中，可以通過環境變量調整以下關鍵內存參數：

```yaml
environment:
  - NEO4J_dbms_memory_pagecache_size=4G # 頁緩存大小
  - NEO4J_dbms.memory.heap.initial_size=4G # 初始堆大小
  - NEO4J_dbms_memory_heap_max__size=4G # 最大堆大小
```

頁緩存用於存儲圖形資料，而堆內存用於查詢處理和事務管理。一般建議將頁緩存設置為可用內存的 30%，堆內存設置為 30-40%。對於生產環境，這些值應根據工作負載和可用資源進行調整，確保系統有足夠的內存處理圖形操作，同時避免過度分配導致的性能問題。

### 啟用 APOC 插件

APOC (Awesome Procedures On Cypher) 是 Neo4j 最受歡迎的插件，提供了大量的實用函數和程序。要在 Docker 環境中啟用 APOC，可以在 Docker Compose 文件中添加以下環境變量：

```yaml
environment:
  - NEO4J_dbms_security_procedures_unrestricted=apoc.*
  - NEO4J_apoc_export_file_enabled=true
  - NEO4J_apoc_import_file_enabled=true
  - NEO4J_apoc_import_file_use__neo4j__config=true
```

對於 Neo4j 4.x 版本，APOC 核心功能已經預裝，但對於完整功能，需要將 APOC 插件 JAR 文件放入 plugins 目錄。可以使用以下方式在 Docker Compose 中自動下載 APOC：

```yaml
services:
  neo4j:
    # 其他配置...
    volumes:
      # 其他卷...
    command: >
      bash -c "
        [ ! -f /plugins/apoc.jar ] && 
        wget -P /plugins https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/4.4.0.2/apoc-4.4.0.2-all.jar;
        /sbin/tini -g -- /docker-entrypoint.sh neo4j
      "
```

### 配置網絡安全

對於生產環境，確保 Neo4j 的網絡安全至關重要。可以在 Docker Compose 文件中配置 TLS/SSL：

```yaml
environment:
  - NEO4J_dbms_ssl_policy_bolt_enabled=true
  - NEO4J_dbms_ssl_policy_bolt_base__directory=/var/lib/neo4j/certificates
  - NEO4J_dbms_ssl_policy_bolt_private__key=private.key
  - NEO4J_dbms_ssl_policy_bolt_public__certificate=public.crt
volumes:
  - ./certificates:/var/lib/neo4j/certificates
```

此配置啟用了 Bolt 連接的 SSL，並指定了證書位置。此外，可以通過設置 Neo4j 僅監聽本地網絡接口來增強安全性：

```yaml
environment:
  - NEO4J_dbms_connector_bolt_listen__address=0.0.0.0:7687
  - NEO4J_dbms_connector_http_listen__address=0.0.0.0:7474
```

## Neo4j 數據庫的開發與管理

### 連接到 Neo4j 實例

![Neo4j Driver for JavaScript](/images/blog/how-to-create-neo4j-database-using-docker-and-docker-compose/unsplash-29b0f74f9713-1E15J3R.jpg)

部署 Neo4j 容器後，有多種方式可以與其交互。最直接的方式是通過 Neo4j 瀏覽器，訪問 `http://localhost:7474`。對於程序化訪問，可以使用 Neo4j 官方驅動。以 JavaScript/TypeScript 為例：

```javascript
import neo4j from "neo4j-driver";

const driver = neo4j.driver(
  "bolt://localhost:7687",
  neo4j.auth.basic("neo4j", "yourpassword")
);
const session = driver.session();

try {
  const result = await session.run("MATCH (n) RETURN count(n) AS count");
  console.log(result.records[0].get("count").toNumber());
} finally {
  await session.close();
}

// 應用程序結束時關閉驅動
await driver.close();
```

對於 Node.js 環境，這段代碼建立了與 Neo4j 的連接，執行了一個簡單的 Cypher 查詢，然後處理返回結果。正確處理連接和會話的關閉非常重要，以避免資源洩漏。

### 數據導入與備份

在生產環境中，數據導入和備份是關鍵操作。要將 CSV 文件導入 Neo4j，首先將文件放入導入目錄：

```bash
# 複製檔案到容器的導入目錄
cp your_data.csv $(pwd)/import/
```

然後使用 Cypher 的 LOAD CSV 命令導入數據：

```cypher
LOAD CSV WITH HEADERS FROM 'file:///your_data.csv' AS line
CREATE (n:Node {id: line.id, name: line.name})
```

對於備份，Neo4j 提供了內建工具。可以通過以下方式創建備份：

```bash
# 創建目錄
mkdir -p $(pwd)/backups

# 執行備份
docker exec neo4j neo4j-admin backup \
  --backup-dir=/backups \
  --name=graph.db-backup
```

要還原備份，首先停止容器，然後執行還原命令：

```bash
docker-compose stop neo4j

docker run --rm \
  -v $(pwd)/data:/data \
  -v $(pwd)/backups:/backups \
  neo4j:latest \
  neo4j-admin restore \
  --from=/backups/graph.db-backup \
  --database=neo4j \
  --force
```

### 建立複雜的多服務架構

在實際應用中，Neo4j 通常是更大系統的一部分。Docker Compose 使得創建包含多個服務的架構變得簡單。以下是一個結合 Neo4j、應用服務器和反向代理的示例：

```yaml
version: "3"
services:
  neo4j:
    image: neo4j:latest
    # Neo4j 的配置...

  app:
    build: ./app
    depends_on:
      - neo4j
    environment:
      - NEO4J_URI=bolt://neo4j:7687
      - NEO4J_USER=neo4j
      - NEO4J_PASSWORD=yourpassword

  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - app
```

此配置創建了一個完整的應用堆棧，應用服務可以通過 Neo4j 的內部網絡名稱 (`neo4j`) 連接到數據庫，而 Nginx 則作為應用的前端代理。使用 Docker 網絡，服務之間可以安全通信，無需暴露不必要的端口到主機。

## 故障排除與效能優化

### 常見問題診斷

使用 Docker 和 Neo4j 時可能遇到各種問題。以下是一些常見問題及其解決方法：

1. **連接問題**：如果無法連接到 Neo4j，檢查端口映射是否正確，容器是否運行：

   ```bash
   docker-compose ps
   docker logs neo4j
   ```

2. **權限問題**：如果遇到文件系統權限錯誤，可能需要調整卷的權限：
   ```bash
   sudo chown -R 7474:7474 ./data ./logs ./import ./plugins
   ```
3. **內存不足**：如果 Neo4j 崩潰或性能不佳，可能是由於內存配置不當：
   ```bash
   docker stats neo4j  # 監控容器資源使用情況
   ```
4. **數據庫鎖定**：如果數據庫被鎖定，可能需要修復：
   ```bash
   docker exec neo4j neo4j-admin check-consistency --database=neo4j
   ```

正確診斷問題的關鍵是檢查容器日誌，監控資源使用情況，以及了解 Neo4j 的運行機制。

### 性能調優最佳實踐

為了獲得最佳性能，可以採取以下措施：

1. **適當的內存配置**：根據工作負載調整頁緩存和堆內存設置。

   ```yaml
   environment:
     - NEO4J_dbms_memory_pagecache_size=4G
     - NEO4J_dbms.memory.heap.initial_size=4G
     - NEO4J_dbms_memory_heap_max__size=4G
   ```

2. **使用索引**：對於頻繁查詢的屬性創建索引：

   ```cypher
   CREATE INDEX ON :Label(property)
   ```

3. **優化 Cypher 查詢**：使用 EXPLAIN 和 PROFILE 分析查詢效率：

   ```cypher
   EXPLAIN MATCH (n:Person)-[:KNOWS]->(m:Person) RETURN n, m
   ```

4. **調整 Docker 資源限制**：根據需要設置 CPU 和內存限制：
   ```yaml
   services:
     neo4j:
       # 其他配置...
       deploy:
         resources:
           limits:
             cpus: "2"
             memory: 8G
   ```

通過組合這些技術，可以顯著提升 Neo4j 在 Docker 環境中的性能和穩定性。

## 結論

![Blue and red cargo ship on sea during daytime photo](https://assets.calpa.me/ian-taylor-jOqJbvo1P9g-unsplash.avif)

使用 Docker 和 Docker Compose 部署 Neo4j 提供了一種靈活、高效且易於管理的方式來運行圖形數據庫。透過本報告介紹的方法，開發者可以快速建立從開發環境到生產環境的 Neo4j 部署，並掌握必要的配置、優化和維護技術。容器化的 Neo4j 不僅簡化了部署過程，還提供了一致的運行環境，使團隊能夠專注於應用邏輯而非基礎設施管理。

隨著圖形數據庫應用的日益普及，熟練掌握 Neo4j 的容器化部署已成為現代開發者的重要技能。無論是處理社交網絡分析、知識圖譜還是推薦系統，基於 Docker 的 Neo4j 解決方案都能提供可靠且可擴展的基礎。通過合理的配置和優化，開發者可以充分發揮 Neo4j 的強大功能，構建出高效且穩定的圖形數據應用。
