02 - 安装与配置

2.1 安装方式概览

GoAccess 提供多种安装方式，适用于不同场景：

安装方式	适用场景	优点	缺点
包管理器	快速部署	简单、自动依赖	版本可能较旧
源码编译	需要最新版或自定义编译选项	最新特性、可定制	需要编译环境
Docker	容器化环境	隔离、可复现	需要 Docker 运行时
Snap	Ubuntu 环境	沙盒隔离	配置灵活性受限

2.2 包管理器安装

2.2.1 Ubuntu / Debian

# 更新包索引
sudo apt update

# 安装 GoAccess
sudo apt install -y goaccess

# 验证安装
goaccess --version

注意：Ubuntu/Debian 官方源中的版本可能较旧。如需最新版本，可添加 PPA：

# 使用官方提供的第三方源获取最新版本
echo "deb http://deb.goaccess.io/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/goaccess.list
wget -O - https://deb.goaccess.io/gnugpg.key | sudo apt-key add -
sudo apt update
sudo apt install -y goaccess

2.2.2 CentOS / RHEL / Fedora

# CentOS / RHEL — 需要 EPEL 源
sudo yum install -y epel-release
sudo yum install -y goaccess

# Fedora
sudo dnf install -y goaccess

# 验证安装
goaccess --version

2.2.3 Arch Linux

sudo pacman -S goaccess

2.2.4 macOS (Homebrew)

brew install goaccess

# 验证安装
goaccess --version

2.2.5 FreeBSD

pkg install goaccess
# 或通过 Ports
cd /usr/ports/www/goaccess && make install clean

版本检查速查表

平台	命令	预期输出示例
所有平台	`goaccess --version`	`GoAccess - 1.9.2`
所有平台	`goaccess --help`	显示帮助信息
源码编译	`goaccess --with-geoip`	显示 GeoIP 支持状态

2.3 源码编译安装

当包管理器中的版本较旧，或需要启用特定编译选项时，建议从源码编译。

2.3.1 安装编译依赖

# Ubuntu / Debian
sudo apt install -y build-essential libncursesw5-dev libgeoip-dev \
  libssl-dev autopoint gettext autoconf autoconf-archive

# CentOS / RHEL / Fedora
sudo yum install -y gcc make ncurses-devel geoip-devel openssl-devel \
  gettext-devel autoconf automake

# Arch Linux
sudo pacman -S base-devel ncurses geoip openssl gettext autoconf

# macOS (Homebrew)
brew install ncurses geoip openssl gettext autoconf autoconf-archive

2.3.2 下载与编译

# 方法一：从 GitHub 克隆（推荐，可获取最新代码）
git clone https://github.com/allinurl/goaccess.git
cd goaccess

# 方法二：下载发行版压缩包
# 前往 https://github.com/allinurl/goaccess/releases 获取最新版本
wget https://tar.goaccess.io/goaccess-1.9.2.tar.gz
tar -xzvf goaccess-1.9.2.tar.gz
cd goaccess-1.9.2

# 生成配置脚本（从 Git 克隆时需要）
autoreconf -fi

# 配置编译选项（见下文详述）
./configure \
  --enable-utf8 \
  --enable-geoip=mmdb \
  --with-openssl \
  --with-getline

# 编译
make -j$(nproc)

# 安装
sudo make install

# 验证
goaccess --version

2.3.3 关键编译选项详解

编译选项	说明	默认值
`--enable-utf8`	启用 UTF-8 宽字符支持	关闭
`--enable-geoip=mmdb`	启用 GeoIP2 (MaxMind DB) 支持	关闭
`--enable-geoip=legacy`	启用 GeoIP Legacy 支持	关闭
`--with-openssl`	启用 OpenSSL 支持（WebSocket 安全连接）	关闭
`--with-getline`	使用动态行缓冲（处理超长行）	关闭
`--with-gettimeofday`	使用微秒级时间戳	关闭
`--prefix=/usr/local`	安装路径前缀	`/usr/local`

推荐编译配置（生产环境）：

./configure \
  --enable-utf8 \
  --enable-geoip=mmdb \
  --with-openssl \
  --with-getline \
  --prefix=/usr/local

2.4 GeoIP 配置

GeoIP 功能允许 GoAccess 根据访客 IP 地址分析其地理位置（国家、城市、ISP 等）。

2.4.1 GeoIP 版本选择

版本	数据库格式	说明	推荐度
GeoIP2 (mmdb)	`.mmdb`	MaxMind 新格式，推荐使用	⭐⭐⭐
GeoIP Legacy	`.dat`	旧格式，已停止更新	⚠️ 不推荐

2.4.2 获取 MaxMind 数据库

注册 MaxMind 账号
获取 License Key
下载 GeoLite2-City 和 GeoLite2-ASN 数据库

# 安装 geoipupdate 工具
sudo apt install -y geoipupdate  # Ubuntu/Debian
# 或
sudo yum install -y geoipupdate  # CentOS/RHEL

# 配置 License Key
sudo vi /etc/GeoIP.conf

/etc/GeoIP.conf 配置内容：

AccountID YOUR_ACCOUNT_ID
LicenseKey YOUR_LICENSE_KEY
EditionIDs GeoLite2-City GeoLite2-ASN

# 下载/更新数据库
sudo geoipupdate

# 数据库默认位置
ls /usr/share/GeoIP/
# GeoLite2-City.mmdb  GeoLite2-ASN.mmdb

2.4.3 配置 GoAccess 使用 GeoIP

在 goaccess.conf 中配置数据库路径：

# 编辑配置文件
sudo vi /etc/goaccess/goaccess.conf
# 或
vi ~/.goaccessrc

# GeoIP2 数据库路径
geoip-database /usr/share/GeoIP/GeoLite2-City.mmdb

或者通过命令行参数指定：

goaccess /var/log/nginx/access.log \
  --geoip-database=/usr/share/GeoIP/GeoLite2-City.mmdb \
  --log-format=COMBINED

2.4.4 自动更新 GeoIP 数据库

使用 Cron 定期更新：

# 编辑 crontab
sudo crontab -e

# 添加以下行：每周一凌晨 3 点更新
0 3 * * 1 /usr/bin/geoipupdate > /var/log/geoipupdate.log 2>&1

2.5 UTF-8 支持配置

对于中文网站日志分析，UTF-8 支持至关重要（例如分析中文 URL 路径、来源页关键词等）。

2.5.1 编译时启用

# 源码编译时必须包含此选项
./configure --enable-utf8

2.5.2 运行时环境

确保终端环境变量正确设置：

# 检查当前 locale
locale

# 设置 UTF-8 locale（如果尚未设置）
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# 或中文 locale
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

# 持久化配置
echo 'export LANG=zh_CN.UTF-8' >> ~/.bashrc
echo 'export LC_ALL=zh_CN.UTF-8' >> ~/.bashrc
source ~/.bashrc

2.5.3 终端要求

确保终端模拟器支持 UTF-8 和宽字符：

终端	UTF-8 支持	宽字符支持
GNOME Terminal	✅	✅
iTerm2 (macOS)	✅	✅
Windows Terminal	✅	✅
PuTTY	需配置	需配置
xterm	需 `-u8` 参数	✅

# 验证 GoAccess 是否支持 UTF-8
goaccess --version | grep -i utf
# 输出应包含: --enable-utf8

2.6 配置文件

GoAccess 支持通过配置文件持久化常用选项，避免每次运行时输入大量参数。

2.6.1 配置文件位置

GoAccess 按以下优先级查找配置文件：

命令行指定：--config-file=/path/to/goaccess.conf
用户级：~/.goaccessrc
系统级：/etc/goaccess/goaccess.conf

2.6.2 生成默认配置文件

# 查看默认配置文件位置
goaccess --dcf
# 输出示例: /usr/local/etc/goaccess/goaccess.conf

# 复制默认配置到用户目录
cp $(goaccess --dcf) ~/.goaccessrc

2.6.3 推荐的基础配置

以下是适合 Nginx 环境的推荐配置 ~/.goaccessrc：

# ============ 日志格式 ============
# Nginx combined 格式
log-format %h - %^ [%d:%t %^] "%r" %s %b "%R" "%u"

# ============ 时间格式 ============
time-format %H:%M:%S
date-format %d/%b/%Y

# ============ 面板配置 ============
# 启用所有面板
enable-panel UNIQUE_VISITORS
enable-panel REQUESTED_FILES
enable-panel REQUESTED_STATIC_FILES
enable-panel NOT_FOUND
enable-panel HOSTS
enable-panel OS_TOOLS
enable-panel BROWSERS
enable-panel REFERRING_SITES
enable-panel REFERRING_URLS
enable-panel STATUS_CODES
enable-panel GEO_LOCATION

# ============ GeoIP ============
geoip-database /usr/share/GeoIP/GeoLite2-City.mmdb

# ============ HTML 报告配置 ============
html-prefs {"theme":"bright","perPage":20}

# ============ 实时 HTML ============
ws-url wss://your-domain.com:7890

# ============ 排除规则 ============
# 排除静态资源的爬虫请求
# ignore-panel REFERRING_SITES
# exclude-ip 127.0.0.1
# exclude-ip ::1

# ============ 性能配置 ============
# 每 200 条记录刷新一次屏幕
# (终端模式下)

2.7 卸载 GoAccess

包管理器卸载

# Ubuntu / Debian
sudo apt remove --purge goaccess

# CentOS / RHEL
sudo yum remove goaccess

# macOS
brew uninstall goaccess

源码编译卸载

# 进入编译源码目录
cd goaccess-1.9.2
sudo make uninstall

2.8 安装验证清单

完成安装后，使用以下清单逐一验证：

# 1. 版本检查
goaccess --version
# 预期输出: GoAccess - 1.9.x

# 2. UTF-8 支持
goaccess --version | grep -c "ENABLE-UTF8"
# 预期输出: 1 (表示已启用)

# 3. GeoIP 支持
goaccess --version | grep -c "GEOIP"
# 预期输出: 1 (表示已启用)

# 4. 快速测试
echo '192.168.1.1 - - [10/May/2026:13:55:36 +0800] "GET / HTTP/1.1" 200 612 "-" "Mozilla/5.0"' | \
  goaccess --log-format=COMBINED -
# 预期: 显示终端面板

# 5. 配置文件检查
test -f ~/.goaccessrc && echo "配置文件存在" || echo "配置文件不存在"

2.9 常见安装问题

问题一：编译报错 `ncurses not found`

# 解决方案：安装 ncurses 开发库
sudo apt install libncursesw5-dev   # Ubuntu/Debian
sudo yum install ncurses-devel      # CentOS/RHEL

问题二：GeoIP 数据库找不到

goaccess: GeoIP database not found

# 检查数据库是否存在
ls /usr/share/GeoIP/GeoLite2-City.mmdb

# 如不存在，安装 geoipupdate 并下载
sudo apt install geoipupdate
sudo geoipupdate

问题三：中文显示乱码

# 1. 确认编译时启用了 UTF-8
goaccess --version | grep UTF8

# 2. 确认终端 locale
locale | grep LANG

# 3. 如果未启用 UTF-8，重新编译
./configure --enable-utf8 && make && sudo make install

问题四：版本过旧，缺少功能

# 查看当前版本
goaccess --version

# 如果低于 1.7，建议源码编译安装最新版

2.10 小结

项目	要点
最快安装	`sudo apt install goaccess` 或 `brew install goaccess`
推荐安装	源码编译，启用 `--enable-utf8` 和 `--enable-geoip=mmdb`
GeoIP	需注册 MaxMind 获取免费数据库
配置文件	`~/.goaccessrc` 持久化常用选项
验证	`goaccess --version` 检查编译选项

安装完成后，下一章将介绍 GoAccess 的基本使用方法，包括终端面板操作、HTML 报告生成和多种输出格式。

→ 03 - 基本使用

强曰为道

02 - 安装与配置

02 - 安装与配置

2.1 安装方式概览

2.2 包管理器安装

2.2.1 Ubuntu / Debian

2.2.2 CentOS / RHEL / Fedora

2.2.3 Arch Linux

2.2.4 macOS (Homebrew)

2.2.5 FreeBSD

版本检查速查表

2.3 源码编译安装

2.3.1 安装编译依赖

2.3.2 下载与编译

2.3.3 关键编译选项详解

2.4 GeoIP 配置

2.4.1 GeoIP 版本选择

2.4.2 获取 MaxMind 数据库

2.4.3 配置 GoAccess 使用 GeoIP

2.4.4 自动更新 GeoIP 数据库

2.5 UTF-8 支持配置

2.5.1 编译时启用

2.5.2 运行时环境

2.5.3 终端要求

2.6 配置文件

2.6.1 配置文件位置

2.6.2 生成默认配置文件

2.6.3 推荐的基础配置

2.7 卸载 GoAccess

包管理器卸载

源码编译卸载

2.8 安装验证清单

2.9 常见安装问题

问题一：编译报错 `ncurses not found`

问题二：GeoIP 数据库找不到

问题三：中文显示乱码

问题四：版本过旧，缺少功能

2.10 小结

下一章

扩展阅读

强曰为道

02 - 安装与配置

02 - 安装与配置

2.1 安装方式概览

2.2 包管理器安装

2.2.1 Ubuntu / Debian

2.2.2 CentOS / RHEL / Fedora

2.2.3 Arch Linux

2.2.4 macOS (Homebrew)

2.2.5 FreeBSD

版本检查速查表

2.3 源码编译安装

2.3.1 安装编译依赖

2.3.2 下载与编译

2.3.3 关键编译选项详解

2.4 GeoIP 配置

2.4.1 GeoIP 版本选择

2.4.2 获取 MaxMind 数据库

2.4.3 配置 GoAccess 使用 GeoIP

2.4.4 自动更新 GeoIP 数据库

2.5 UTF-8 支持配置

2.5.1 编译时启用

2.5.2 运行时环境

2.5.3 终端要求

2.6 配置文件

2.6.1 配置文件位置

2.6.2 生成默认配置文件

2.6.3 推荐的基础配置

2.7 卸载 GoAccess

包管理器卸载

源码编译卸载

2.8 安装验证清单

2.9 常见安装问题

问题一：编译报错 ncurses not found

问题二：GeoIP 数据库找不到

问题三：中文显示乱码

问题四：版本过旧，缺少功能

2.10 小结

下一章

扩展阅读

问题一：编译报错 `ncurses not found`