AgensGraph 完全指南 / 第 02 章：安装与初始化配置

第 02 章：安装与初始化配置

2.1 安装方式概览

方式	适用场景	难度	推荐度
Docker 镜像	快速体验、开发测试	★☆☆	⭐⭐⭐⭐⭐
Docker Compose	完整开发环境	★★☆	⭐⭐⭐⭐
源码编译	定制需求、生产环境	★★★	⭐⭐⭐
包管理器	特定 Linux 发行版	★★☆	⭐⭐

推荐：初学者和日常开发使用 Docker 方式，生产环境根据需求选择源码编译或容器化部署。

2.2 Docker 快速部署

2.2.1 环境准备

# 检查 Docker 版本（需要 20.10+）
docker --version

# 拉取 AgensGraph 官方镜像
docker pull bitnine/agensgraph:v2.13

# 验证镜像
docker images | grep agensgraph

2.2.2 启动容器

# 基本启动
docker run -d \
  --name agensgraph \
  -p 5432:5432 \
  -e AG_PASSWORD=agens123 \
  bitnine/agensgraph:v2.13

# 带数据持久化启动（推荐）
docker run -d \
  --name agensgraph \
  -p 5432:5432 \
  -e AG_PASSWORD=agens123 \
  -v agensgraph_data:/home/agens/AgensGraph/data \
  bitnine/agensgraph:v2.13

2.2.3 参数说明

参数	说明
`-d`	后台运行
`--name`	容器名称
`-p 5432:5432`	端口映射（宿主机:容器）
`-e AG_PASSWORD`	设置超级用户密码
`-v`	数据卷挂载（持久化存储）

2.2.4 验证安装

# 检查容器状态
docker ps | grep agensgraph

# 查看日志
docker logs agensgraph

# 连接到 AgensGraph
docker exec -it agensgraph agens -U agens

连接成功后会看到类似以下提示：

agens (2.13)
Type "help" for help.

agens=#

2.3 Docker Compose 部署

2.3.1 创建项目结构

agensgraph-project/
├── docker-compose.yml
├── init/
│   └── 01-init.sql
├── data/
│   └── (持久化数据)
└── config/
    └── agens.conf

2.3.2 编写 docker-compose.yml

version: '3.8'

services:
  agensgraph:
    image: bitnine/agensgraph:v2.13
    container_name: agensgraph
    ports:
      - "5432:5432"
    environment:
      AG_PASSWORD: agens123
      AG_GRAPH_PATH: mygraph
    volumes:
      - agensgraph_data:/home/agens/AgensGraph/data
      - ./init:/docker-entrypoint-initdb.d
      - ./config/agens.conf:/home/agens/AgensGraph/data/agens.conf
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U agens"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  agensgraph_data:
    driver: local

2.3.3 初始化脚本

-- init/01-init.sql
-- 创建图数据库
CREATE GRAPH mygraph;

-- 切换到图路径
SET graph_path = mygraph;

-- 创建一些初始数据
CREATE (:Person {name: '管理员', role: 'admin', created: datetime()});

2.3.4 启动服务

# 启动
docker compose up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f agensgraph

# 停止
docker compose down

# 停止并删除数据卷
docker compose down -v

2.4 源码编译安装

2.4.1 系统依赖

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y \
  build-essential \
  libreadline-dev \
  zlib1g-dev \
  libssl-dev \
  libxml2-dev \
  libxslt-dev \
  libsystemd-dev \
  curl \
  git

# CentOS / RHEL
sudo yum install -y \
  gcc \
  gcc-c++ \
  readline-devel \
  zlib-devel \
  openssl-devel \
  libxml2-devel \
  libxslt-devel \
  systemd-devel \
  curl \
  git

2.4.2 获取源码

# 克隆仓库
git clone https://github.com/bitnine-oss/agensgraph.git
cd agensgraph

# 选择稳定版本
git checkout -b v2.13 v2.13.0

2.4.3 编译安装

# 配置（指定安装路径）
./configure --prefix=/usr/local/agensgraph

# 编译（使用所有 CPU 核心）
make -j$(nproc)

# 安装
sudo make install

# 添加到 PATH
echo 'export PATH=/usr/local/agensgraph/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

2.4.4 初始化数据库

# 创建专用用户
sudo useradd -m agens
sudo passwd agens

# 切换到 agens 用户
sudo su - agens

# 创建数据目录
mkdir -p ~/AgensGraph/data

# 初始化数据库集群
initdb -D ~/AgensGraph/data --encoding=UTF8 --locale=C

# 启动服务
ag_ctl -D ~/AgensGraph/data -l logfile start

# 创建图数据库
agens -c "CREATE GRAPH mygraph;"

2.5 初始配置

2.5.1 核心配置文件

配置文件位于 data/agens.conf（或 postgresql.conf），以下是最关键的参数：

# ============================
# 连接设置
# ============================
listen_addresses = '*'          # 监听地址（'*' 表示所有）
port = 5432                     # 监听端口
max_connections = 100           # 最大连接数

# ============================
# 内存设置
# ============================
shared_buffers = 256MB          # 共享缓冲区（建议为 RAM 的 25%）
work_mem = 16MB                 # 单次排序/哈希操作的内存
maintenance_work_mem = 128MB    # 维护操作内存（VACUUM、CREATE INDEX）
effective_cache_size = 768MB    # OS 缓存估算值（RAM 的 75%）

# ============================
# WAL 设置
# ============================
wal_level = replica             # WAL 级别
max_wal_size = 1GB              # WAL 最大大小
checkpoint_completion_target = 0.9

# ============================
# 日志设置
# ============================
logging_collector = on
log_directory = 'log'
log_filename = 'agens-%Y-%m-%d.log'
log_statement = 'ddl'           # 记录 DDL 语句
log_duration = off

# ============================
# 图查询设置
# ============================
enable_graph_path = on          # 启用图路径（默认开启）

2.5.2 客户端认证配置

编辑 data/pg_hba.conf：

# TYPE  DATABASE  USER   ADDRESS       METHOD
local   all       all                  trust
host    all       all    127.0.0.1/32  md5
host    all       all    ::1/128       md5
host    all       all    0.0.0.0/0     md5

2.5.3 配置优化建议

参数	开发环境	生产环境（小）	生产环境（大）
`shared_buffers`	128MB	1GB	8GB+
`work_mem`	4MB	32MB	128MB
`maintenance_work_mem`	64MB	512MB	2GB
`max_connections`	50	200	500
`effective_cache_size`	256MB	3GB	24GB

2.6 创建第一个图数据库

2.6.1 连接与图创建

# 连接到 AgensGraph
agens -U agens -d agens

-- 创建一个新的图数据库
CREATE GRAPH social_network;

-- 切换到图路径
SET graph_path = social_network;

2.6.2 验证图路径

-- 查看当前图路径
SHOW graph_path;

-- 列出所有图
SELECT * FROM ag_graph;

2.6.3 创建初始数据

-- 设置图路径
SET graph_path = social_network;

-- 创建顶点
CREATE (:Person {name: '张三', age: 30, city: '北京'});
CREATE (:Person {name: '李四', age: 28, city: '上海'});
CREATE (:Person {name: '王五', age: 35, city: '北京'});
CREATE (:Company {name: '科技公司', founded: 2015});

-- 创建关系
MATCH (a:Person {name: '张三'}), (b:Person {name: '李四'})
CREATE (a)-[:KNOWS {since: 2020}]->(b);

MATCH (a:Person {name: '张三'}), (b:Company {name: '科技公司'})
CREATE (a)-[:WORKS_AT {position: '工程师', since: 2021}]->(b);

-- 查询验证
MATCH (n) RETURN n;

2.6.4 期望输出

              n
-----------------------------
  :Person {name: "张三", age: 30, city: "北京"}
  :Person {name: "李四", age: 28, city: "上海"}
  :Person {name: "王五", age: 35, city: "北京"}
  :Company {name: "科技公司", founded: 2015}
(4 rows)

2.7 配置管理工具

2.7.1 ag_ctl 工具

# 启动服务
ag_ctl -D /path/to/data start

# 停止服务
ag_ctl -D /path/to/data stop

# 重启服务
ag_ctl -D /path/to/data restart

# 重新加载配置（不需要重启）
ag_ctl -D /path/to/data reload

# 查看状态
ag_ctl -D /path/to/data status

2.7.2 环境变量

# 设置环境变量（添加到 .bashrc）
export AGENSHOME=/usr/local/agensgraph
export PGDATA=$AGENSHOME/data
export PATH=$AGENSHOME/bin:$PATH
export PGHOST=localhost
export PGPORT=5432
export PGUSER=agens

2.8 常见安装问题

问题 1：端口被占用

# 查看占用端口的进程
sudo lsof -i :5432

# 解决方案 1：停止冲突进程
sudo systemctl stop postgresql

# 解决方案 2：修改端口
# 在 agens.conf 中修改 port = 5433

问题 2：权限不足

# 检查数据目录权限
ls -la $PGDATA

# 修正权限
chmod 700 $PGDATA
chown -R agens:agens $PGDATA

问题 3：Docker 容器无法启动

# 查看详细错误日志
docker logs agensgraph

# 常见原因：
# 1. 端口冲突 → 修改映射端口 -p 5433:5432
# 2. 数据卷权限 → 确保 volume 正确挂载
# 3. 内存不足 → 增加 Docker 内存限制

2.9 本章小结

步骤	Docker 方式	源码编译方式
环境准备	Docker 安装	系统依赖 + 编译工具
获取软件	`docker pull`	`git clone`
安装	自动	`./configure && make && make install`
初始化	自动	`initdb`
启动	`docker start`	`ag_ctl start`
配置	环境变量 / 挂载文件	编辑 `agens.conf`

AgensGraph 完全指南 / 第 02 章：安装与初始化配置

第 02 章：安装与初始化配置

2.1 安装方式概览

2.2 Docker 快速部署

2.2.1 环境准备

2.2.2 启动容器

2.2.3 参数说明

2.2.4 验证安装

2.3 Docker Compose 部署

2.3.1 创建项目结构

2.3.2 编写 docker-compose.yml

2.3.3 初始化脚本

2.3.4 启动服务

2.4 源码编译安装

2.4.1 系统依赖

2.4.2 获取源码

2.4.3 编译安装

2.4.4 初始化数据库

2.5 初始配置

2.5.1 核心配置文件

2.5.2 客户端认证配置

2.5.3 配置优化建议

2.6 创建第一个图数据库

2.6.1 连接与图创建

2.6.2 验证图路径

2.6.3 创建初始数据

2.6.4 期望输出

2.7 配置管理工具

2.7.1 ag_ctl 工具

2.7.2 环境变量

2.8 常见安装问题

问题 1：端口被占用

问题 2：权限不足

问题 3：Docker 容器无法启动

2.9 本章小结

2.10 扩展阅读