OpenGrok 安装配置说明

================================================================================

OpenGrok 安装配置说明

文档生成时间: 2026-06-28

安装路径: /opt/opengrok

服务端口: 8090

================================================================================

一、系统环境

操作系统: Ubuntu 20.04.6 LTS (Focal Fossa)

架构: x86_64

CPU 核心: 8

磁盘空间: 1.8T 总量, 1.3T 可用 (/opt 分区)

Java: OpenJDK 21.0.7 (2025-04-15)

================================================================================

二、已安装组件

组件版本路径

───────────────── ──────────────────────── ──────────────────────────────

OpenGrok 1.14.15 /opt/opengrok/opengrok-1.14.15/

Tomcat 10.1.40 /opt/opengrok/apache-tomcat-10.1.40/

Universal Ctags 0.0.0 (2019-01-06 编译) /opt/opengrok/ctags

Java OpenJDK 21.0.7 系统默认

================================================================================

三、目录结构

/opt/opengrok/

├── src/ # 源代码根目录

│ └── android17/ # → Android 17 源码 (软链接)

├── data/ # 索引数据目录

│ ├── index/ # → Lucene 索引文件

│ └── xref/ # → 交叉引用 HTML 文件

├── etc/ # 配置文件目录

│ └── configuration.xml # → OpenGrok 配置 (索引完成后生成)

├── ctags # Universal Ctags 二进制文件

├── apache-tomcat-10.1.40/ # Tomcat 10 服务

├── opengrok-1.14.15/ # OpenGrok 发行版

│ ├── lib/

│ │ ├── opengrok.jar # 索引器

│ │ └── source.war # Web 应用

│ ├── tools/ # 额外工具

│ └── doc/ # 文档

├── apache-tomcat-9.0.119/ # Tomcat 9 (已弃用, 与 Jakarta EE 不兼容)

├── opengrok.tar.gz # OpenGrok 下载缓存

├── tomcat10.tar.gz # Tomcat 10 下载缓存

└── tomcat.tar.gz # Tomcat 9 下载缓存 (可删除)

================================================================================

四、安装步骤回顾

安装 Java 运行环境

(系统已预装 OpenJDK 21, 无需额外操作)
安装 Universal Ctags

由于无 sudo 权限, 从 Ubuntu Focal 软件源下载 deb 包并手动提取:

curl -L -o /tmp/uctags_focal.deb

"http://archive.ubuntu.com/ubuntu/pool/universe/u/universal-ctags/universal-ctags_0+git20181215-2_amd64.deb"

dpkg -x /tmp/uctags_focal.deb /tmp/uctags_focal/

cp /tmp/uctags_focal/usr/bin/ctags-universal /opt/opengrok/ctags

chmod +x /opt/opengrok/ctags
安装 Tomcat 10 (必须用 Tomcat 10+, OpenGrok 1.14.15 依赖 Jakarta EE)

curl -L -o tomcat10.tar.gz

"https://archive.apache.org/dist/tomcat/tomcat-10/v10.1.40/bin/apache-tomcat-10.1.40.tar.gz"

tar xzf tomcat10.tar.gz
配置 Tomcat 端口为 8090

编辑 apache-tomcat-10.1.40/conf/server.xml

将所有 port="8080" 改为 port="8090"
创建 Tomcat 环境变量

文件: apache-tomcat-10.1.40/bin/setenv.sh

内容:

#!/bin/sh

export JAVA_OPTS="$JAVA_OPTS -Xmx2048m -Dopengrok.configuration=/opt/opengrok/etc/configuration.xml"
下载 OpenGrok 1.14.15

curl -L -o opengrok.tar.gz

"https://github.com/oracle/opengrok/releases/download/1.14.15/opengrok-1.14.15.tar.gz"

tar xzf opengrok.tar.gz
部署 OpenGrok Web 应用

cp opengrok-1.14.15/lib/source.war apache-tomcat-10.1.40/webapps/source.war
启动 Tomcat

./apache-tomcat-10.1.40/bin/startup.sh
运行索引 (首次)

java -Xmx8g -jar /opt/opengrok/opengrok-1.14.15/lib/opengrok.jar

-s /opt/opengrok/src

-d /opt/opengrok/data

-c /opt/opengrok/ctags

-W /opt/opengrok/etc/configuration.xml

-v

⚠️ 大型代码库务必加 -Xmx8g (或更大) 指定堆内存，默认 ~4G 可能在

解析大型 JAR 等文件时触发 OutOfMemoryError。

本次索引 Android 17 (144GB/164万文件) 首次运行 12 小时后在 98.8%

处 OOM 崩溃，加 -Xmx8g 重启后跳过已完成文件，几分钟即完成。
修补 web.xml 配置文件路径

OpenGrok WAR 包默认读取 /var/opengrok/etc/configuration.xml。

mkdir -p /tmp/war_fix && cd /tmp/war_fix

cp /opt/opengrok/opengrok-1.14.15/lib/source.war .

unzip -q source.war WEB-INF/web.xml

sed -i 's|/var/opengrok/etc/configuration.xml|/opt/opengrok/etc/configuration.xml|g' WEB-INF/web.xml

zip -q source.war WEB-INF/web.xml

cp source.war /opt/opengrok/opengrok-1.14.15/lib/source.war

如果不修补，Web 应用将无法找到配置，返回 HTTP 500。

================================================================================

五、日常使用命令

◆ 启动 Tomcat:

/opt/opengrok/apache-tomcat-10.1.40/bin/startup.sh

◆ 停止 Tomcat:

/opt/opengrok/apache-tomcat-10.1.40/bin/shutdown.sh

◆ 查看 Tomcat 日志:

tail -f /opt/opengrok/apache-tomcat-10.1.40/logs/catalina.out

◆ 访问 OpenGrok Web 界面:

http://<服务器IP>:8090/source/

◆ 完整重新索引:

java -Xmx8g -jar /opt/opengrok/opengrok-1.14.15/lib/opengrok.jar

-s /opt/opengrok/src

-d /opt/opengrok/data

-c /opt/opengrok/ctags

-W /opt/opengrok/etc/configuration.xml

-v

◆ 增量索引 (使用已有配置, 只索引变更文件):

java -jar /opt/opengrok/opengrok-1.14.15/lib/opengrok.jar

-R /opt/opengrok/etc/configuration.xml

-v

◆ 发送配置到运行中的 Web 应用 (无需重启 Tomcat):

java -jar /opt/opengrok/opengrok-1.14.15/lib/opengrok.jar

-R /opt/opengrok/etc/configuration.xml

-U http://localhost:8090/source

◆ 添加新的源代码目录:

ln -sf /path/to/your/source/code /opt/opengrok/src/your-project

然后重新运行索引

◆ 查看索引数据大小:

du -sh /opt/opengrok/data/

================================================================================

六、访问 OpenGrok

Web 地址: http://<服务器IP>:8090/source/

首次打开后可以:

全文搜索: 在搜索框输入关键字, 支持正则表达式
代码导航: 点击搜索结果中的文件名, 查看带语法高亮的源码
交叉引用: 点击代码中的函数名/类名/变量名, 跳转到定义处
文件历史: 如果开启了版本控制历史, 可查看文件修改记录

搜索语法示例:

full:setupWizard 全文搜索 "setupWizard"

def:onCreate 搜索名为 "onCreate" 的定义

ref:MyClass 搜索对 "MyClass" 的引用

path:MainActivity.java 按文件路径搜索

hist:some_function 搜索历史记录

================================================================================

七、注意事项

Tomcat 版本

必须使用 Tomcat 10 以上版本。OpenGrok 1.14.15 使用 Jakarta Servlet API

(jakarta.servlet.), 而 Tomcat 9 使用旧版 javax.servlet., 两者不兼容。
Ctags 版本

当前使用 Universal Ctags 2019 年版, 部分新语言 (Terraform, CobolFree

等) 的词法分析器不可用, 但不影响 C/C++/Java/Python 等主流语言。

如需完整支持, 建议编译安装最新版 universal-ctags:

https://github.com/universal-ctags/ctags
内存配置

Tomcat JVM 堆内存: 2GB (setenv.sh 中的 -Xmx2048m)

索引器堆内存: 必须显式指定 -Xmx8g (默认仅 ~4G, 大型 JAR 解析会 OOM)

本机 16GB 内存, 当前 Tomcat 2G + 索引 8G 共存有余量。
索引耗时

当前 Android 17 源码约 144GB，完整索引可能需要数小时。

后续增量索引会快很多。
磁盘空间

索引数据大小通常约为源代码的 10%-20%。

================================================================================

八、故障排除

◆ Web 页面返回 500 错误:

检查 configuration.xml 是否存在: ls /opt/opengrok/etc/configuration.xml
如果不存在, 说明索引尚未完成或未运行, 请执行索引命令
检查 Tomcat 日志: tail -f apache-tomcat-10.1.40/logs/catalina.out

◆ 搜索结果为空:

确认索引是否已完成
检查 data/index/ 目录是否有内容

◆ Tomcat 无法启动:

检查端口 8090 是否被占用: ss -tlnp | grep 8090
检查 JAVA_HOME 是否正确: echo $JAVA_HOME
查看启动日志: cat apache-tomcat-10.1.40/logs/catalina.out

◆ Ctags 报错 "Unknown language":

这是旧版 ctags 的已知警告, 不影响主流语言的索引
升级 universal-ctags 到最新版可消除此警告

◆ 索引时 OutOfMemoryError (Java heap space):

大型 JAR/二进制文件的解析可能耗尽默认 ~4G 堆内存
加 -Xmx8g (或更大) 重新运行索引命令
已索引的文件会被自动跳过, 无需从头开始
当前实例: Android 17 源码首次运行 12h 后在 98.8% 处 OOM

◆ Web 页面返回 500 且日志提示 /var/opengrok/etc/configuration.xml:

web.xml 中配置路径未修改, 指向默认位置 /var/opengrok/...
解决方法: 按步骤四第 10 步修补 source.war 中的 web.xml
或创建软链接: ln -s /opt/opengrok/etc /var/opengrok/etc (需 sudo)
修补后重启 Tomcat 即可

================================================================================

九、索引进度监控脚本 (/opt/opengrok_progress.sh)

脚本位于 /opt/opengrok_progress.sh, 用于监控索引进度，展示运行时间、

xref 文件数、数据大小、处理速度及预计完成时间。

⚠️ 注意事项:

大规模索引时 find 遍历百万级文件极度缓慢(>30秒), 脚本采用缓存机制:

首次运行 find 获取基础 xref 值, 后续 3 分钟内复用缓存, 避免每次等待

使用前需更新脚本内的 PID 变量为当前索引进程 ID
SRC_TOTAL 需改为实际源码文件总数 (find /path/src -type f | wc -l)

◆ 使用方法:

复制代码

  chmod +x /opt/opengrok_progress.sh
  /opt/opengrok_progress.sh
  watch -n 60 /opt/opengrok_progress.sh   # 每分钟刷新

◆ 当前实例参数:

源码文件总数: 1,644,456 (Android 17)

首次索引耗时: ~12h (含 OOM 崩溃后重启)

最终索引数据: 52GB

访问地址: http://localhost:8090/source/

================================================================================