使用 Docker 和 Docker Compose 建立 Neo4j 資料庫

Neo4j 與容器化簡介

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

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

Docker 與 Docker Compose 基本概念

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

使用 Docker 運行 Neo4j

基本 Docker 命令

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

docker pull neo4j:latest

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

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

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

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 的網頁界面：http://localhost:7474。首次登入時，使用用戶名 “neo4j” 和之前設置的密碼。成功登入後，您將看到 Neo4j 瀏覽器界面，可以開始執行 Cypher 查詢語言來操作圖形資料庫。要檢查容器狀態，可以使用以下命令：

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

使用 Docker Compose 設置 Neo4j

Docker Compose 文件結構

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

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 配置文件後，可以使用以下命令啟動服務：

docker-compose up -d

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

docker-compose ps

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

docker-compose stop

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

docker-compose down

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

docker-compose down -v

設置持久化存儲

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

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

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

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 文件中，可以通過環境變量調整以下關鍵內存參數：

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 文件中添加以下環境變量：

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：

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：

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 僅監聽本地網絡接口來增強安全性：

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

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，首先將文件放入導入目錄：

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

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

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

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

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

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

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

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、應用服務器和反向代理的示例：

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，檢查端口映射是否正確，容器是否運行：

   docker-compose ps
   docker logs neo4j

2. 權限問題：如果遇到文件系統權限錯誤，可能需要調整卷的權限：

   sudo chown -R 7474:7474 ./data ./logs ./import ./plugins

3. 內存不足：如果 Neo4j 崩潰或性能不佳，可能是由於內存配置不當：

   docker stats neo4j  # 監控容器資源使用情況

4. 數據庫鎖定：如果數據庫被鎖定，可能需要修復：

   docker exec neo4j neo4j-admin check-consistency --database=neo4j

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

性能調優最佳實踐

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

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

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

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

   CREATE INDEX ON :Label(property)

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

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

4. 調整 Docker 資源限制：根據需要設置 CPU 和內存限制：

   services:
     neo4j:
       # 其他配置...
       deploy:
         resources:
           limits:
             cpus: "2"
             memory: 8G

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

結論

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

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