================================================================================
          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 下载缓存 (可删除)

================================================================================
四、安装步骤回顾
================================================================================

  1. 安装 Java 运行环境
     (系统已预装 OpenJDK 21, 无需额外操作)

  2. 安装 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

  3. 安装 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

  4. 配置 Tomcat 端口为 8090

       编辑 apache-tomcat-10.1.40/conf/server.xml
       将所有 port="8080" 改为 port="8090"

  5. 创建 Tomcat 环境变量

       文件: apache-tomcat-10.1.40/bin/setenv.sh
       内容:
         #!/bin/sh
         export OPENGROK_CONFIGURATION=/opt/opengrok/etc/configuration.xml
         export JAVA_OPTS="$JAVA_OPTS -Xmx2048m"

  6. 下载 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

  7. 部署 OpenGrok Web 应用

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

  8. 启动 Tomcat

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

  9. 运行索引 (首次)

       java -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

================================================================================
五、日常使用命令
================================================================================

  ◆ 启动 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 -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                   搜索历史记录

================================================================================
七、注意事项
================================================================================

  1. Tomcat 版本
     必须使用 Tomcat 10 以上版本。OpenGrok 1.14.15 使用 Jakarta Servlet API
     (jakarta.servlet.*), 而 Tomcat 9 使用旧版 javax.servlet.*, 两者不兼容。

  2. Ctags 版本
     当前使用 Universal Ctags 2019 年版, 部分新语言 (Terraform, CobolFree
     等) 的词法分析器不可用, 但不影响 C/C++/Java/Python 等主流语言。
     如需完整支持, 建议编译安装最新版 universal-ctags:
       https://github.com/universal-ctags/ctags

  3. 内存配置
     Tomcat JVM 堆内存当前设为 2GB (setenv.sh 中的 -Xmx2048m)。
     Java 自动索引时最多使用约 4GB。如果服务器内存充足可适当增大。

  4. 索引耗时
     大型代码库 (如 Android 源码 100+ GB) 完整索引可能需要数小时。
     后续增量索引会快很多。

  5. 磁盘空间
     索引数据大小通常约为源代码的 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 到最新版可消除此警告

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

  脚本位于 /opt/opengrok_progress.sh, 用于监控索引进度，展示运行时间、
  xref 文件数、数据大小、处理速度及预计完成时间。

  ◆ 脚本内容:

#!/bin/bash
# OpenGrok 索引进度监控脚本

PID=564679
DATA_DIR=/opt/opengrok/data
SRC_TOTAL=1644456  # 总文件数

# 获取运行时间
etime=$(ps -o etime= -p $PID 2>/dev/null | tr -d ' ')
if [ -z "$etime" ]; then
    echo "进程 $PID 已结束"
    exit 0
fi

# 运行时间转分钟
min=$(echo "$etime" | awk -F: '{
    if(NF==3) mins=$1*60+$2+$3/60;
    else if(NF==2) mins=$1+$2/60;
    else mins=$1/60;
    printf "%.0f", mins
}')

# 当前数据
xref=$(find $DATA_DIR/xref -type f 2>/dev/null | wc -l)
data=$(du -sh $DATA_DIR 2>/dev/null | cut -f1)

# 速度（文件/分钟）
if [ "$min" -gt 0 ]; then
    speed=$((xref / min))
else
    speed=0
fi

# 估算剩余（假设50%文件需索引）
need=$((SRC_TOTAL / 2))
remain=$((need - xref))

# 计算预计完成时间
if [ "$speed" -gt 0 ] && [ "$remain" -gt 0 ]; then
    # xref阶段剩余分钟
    eta_xref_min=$((remain / speed))
    # 加上Lucene索引构建(45分钟)
    eta_total_min=$((eta_xref_min + 45))
    now_ts=$(date +%s)
    done_ts=$((now_ts + eta_total_min * 60))
    done_time=$(date -d @$done_ts '+%H:%M')
    eta_h=$((eta_total_min / 60))
    eta_m=$((eta_total_min % 60))
elif [ "$remain" -le 0 ]; then
    done_time="即将完成"
    eta_total_min=0
else
    done_time="计算中..."
fi

echo
echo "  📊 索引进度（运行 ${etime}）"
echo
printf "  ┌──────────────┬───────────────────────────┐\n"
printf "  │ %-12s │ %-25s │\n" "指标" "数值"
printf "  ├──────────────┼───────────────────────────┤\n"
printf "  │ %-12s │ %-25s │\n" "已运行" "${etime}"
printf "  ├──────────────┼───────────────────────────┤\n"
printf "  │ %-12s │ %-25s │\n" "Xref 文件" "$(printf "%'d" $xref)"
printf "  ├──────────────┼───────────────────────────┤\n"
printf "  │ %-12s │ %-25s │\n" "数据大小" "$data"
printf "  ├──────────────┼───────────────────────────┤\n"
printf "  │ %-12s │ ~%d 文件/分钟 %-8s │\n" "速度" $speed ""
printf "  └──────────────┴───────────────────────────┘\n"
echo
if [ "$speed" -gt 0 ] && [ "$remain" -gt 0 ]; then
    printf "  ⏱️  预计还需 %dh%dm  →  完成时间: %s\n" $eta_h $eta_m "$done_time"
    printf "      (含 xref + Lucene索引构建 ~45min)\n"
elif [ "$remain" -le 0 ]; then
    echo "  ⏱️  xref 阶段接近完成，进入 Lucene 索引构建"
    echo "      预计完成时间: $(date -d @$(( $(date +%s) + 2700 )) '+%H:%M')"
fi
echo

  ◆ 使用方法:

      chmod +x /opt/opengrok_progress.sh
      /opt/opengrok_progress.sh

      # 或持续监控 (每 60 秒刷新)
      watch -n 60 /opt/opengrok_progress.sh

  ◆ 说明:
      - 脚本依赖 ps、find、du、date 等基础命令
      - PID 变量需根据实际索引进程 ID 修改
      - SRC_TOTAL 是源码文件总数，需根据实际源码量调整
      - 估算逻辑: 假设约 50% 的文件需要建立交叉引用

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

Ubuntu 24.04 部署 Opengrok | 汪广鑫の小pò站

ubantu opengrok_ubuntu opengrok-CSDN博客