# Gerrit 个人使用完整安装与使用指南

## 📋 目录
- [环境准备](#环境准备)
- [手动安装步骤](#手动安装步骤)
- [一键自动化安装脚本](#一键自动化安装脚本)
- [使用指南](#使用指南)
- [常用技巧](#常用技巧)

---

## 环境准备

### 适合的系统
- **Ubuntu** 18.04+ / 20.04 / 22.04
- **Debian** 10+ / 11+
- **CentOS** 7+ / Rocky Linux 8+

### 云主机建议配置
- **CPU**: 1-2核
- **内存**: 2GB
- **磁盘**: 20GB+ (根据项目数量调整)
- **网络**: 公网IP（如需远程访问）

### 必备软件
- **Git**: 版本控制工具
- **JDK**: Java 11 或 Java 17（推荐 Java 17）
- **wget**: 下载工具

---

## 手动安装步骤

### 步骤 1: 系统更新

```bash
# Ubuntu/Debian 系统
sudo apt update && sudo apt upgrade -y

# CentOS/Rocky Linux 系统
sudo yum update -y
# 或者 (CentOS 8+)
sudo dnf update -y
```

### 步骤 2: 安装依赖软件

#### Ubuntu/Debian 系统

```bash
# 安装 Git 和 wget
sudo apt install -y git wget

# 安装 OpenJDK 17
sudo apt install -y openjdk-17-jdk

# 验证安装
java -version
git --version
```

#### CentOS/Rocky Linux 系统

```bash
# 安装 Git 和 wget
sudo yum install -y git wget
# 或者 (CentOS 8+)
sudo dnf install -y git wget

# 安装 OpenJDK 17
sudo yum install -y java-17-openjdk java-17-openjdk-devel
# 或者 (CentOS 8+)
sudo dnf install -y java-17-openjdk java-17-openjdk-devel

# 验证安装
java -version
git --version
```

### 步骤 3: 创建工作目录

```bash
# 创建 Gerrit 工作目录
sudo mkdir -p /opt/gerrit
sudo chown $USER:$USER /opt/gerrit
cd /opt/gerrit
```

### 步骤 4: 下载 Gerrit.war 文件

```bash
# 下载最新稳定版本（以 3.9.0 为例，可根据需要修改版本号）
GERRIT_VERSION=3.9.0
wget https://gerrit-releases.storage.googleapis.com/gerrit-${GERRIT_VERSION}.war

# 或者下载特定版本
# wget https://gerrit-releases.storage.googleapis.com/gerrit-3.8.0.war
```

### 步骤 5: 初始化 Gerrit（使用内置 H2 数据库）

```bash
# 初始化 Gerrit，使用 H2 数据库（适合个人使用）
java -jar gerrit-${GERRIT_VERSION}.war init -d review_site

# 初始化过程中会提示以下配置，建议选择：
# - 数据库类型: [2] H2 (默认，适合个人使用)
# - 认证方式: [1] DEVELOPMENT_BECOME_ANY_ACCOUNT (开发模式，方便测试)
#   或者 [2] HTTP (生产环境推荐)
# - Git 仓库位置: 直接回车使用默认值
# - 索引类型: [1] LUCENE (默认)
# - 监听地址: 直接回车使用默认 (0.0.0.0)
# - 监听端口: 直接回车使用默认 (29418) 或输入自定义端口
# - 是否作为守护进程运行: [Y] 是
# - 是否安装 Bouncy Castle: [Y] 是
```

**注意**: 如果希望非交互式初始化，可以使用以下命令：

```bash
java -jar gerrit-${GERRIT_VERSION}.war init \
  -d review_site \
  --batch \
  --no-auto-start \
  --install-plugin=download-commands \
  --install-plugin=replication \
  --install-plugin=reviewnotes
```

### 步骤 6: 启动 Gerrit 服务

```bash
# 进入 Gerrit 站点目录
cd /opt/gerrit/review_site

# 启动 Gerrit
bin/gerrit.sh start

# 查看状态
bin/gerrit.sh status

# 查看日志
tail -f logs/gerrit.log
```

### 步骤 7: 访问 Gerrit
101.43.95.130
http://101.43.95.130:8080
打开浏览器访问：
- **Web 界面**: `http://你的服务器IP:8080` 或 `http://localhost:8080`
- **SSH 端口**: `29418` (默认)

---

## 一键自动化安装脚本

以下脚本会自动判断系统类型、安装依赖、下载 Gerrit、初始化并启动服务。

### 创建安装脚本

```bash
cat > install_gerrit.sh << 'EOF'
#!/bin/bash

# Gerrit 一键安装脚本
# 支持 Ubuntu/Debian 和 CentOS/Rocky Linux

set -e

# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 配置变量
GERRIT_VERSION="${GERRIT_VERSION:-3.9.0}"
GERRIT_HOME="/opt/gerrit"
GERRIT_USER="${USER}"
GERRIT_PORT="${GERRIT_PORT:-8080}"
GERRIT_SSH_PORT="${GERRIT_SSH_PORT:-29418}"

echo -e "${GREEN}========================================${NC}"
echo -e "${GREEN}Gerrit 自动化安装脚本${NC}"
echo -e "${GREEN}版本: ${GERRIT_VERSION}${NC}"
echo -e "${GREEN}========================================${NC}"

# 检测系统类型
detect_os() {
    if [ -f /etc/os-release ]; then
        . /etc/os-release
        OS=$ID
        OS_VERSION=$VERSION_ID
    elif [ -f /etc/redhat-release ]; then
        OS="rhel"
        OS_VERSION=$(cat /etc/redhat-release | sed 's/.*release \([0-9]\+\).*/\1/')
    else
        echo -e "${RED}无法检测操作系统类型${NC}"
        exit 1
    fi
    echo -e "${YELLOW}检测到系统: ${OS} ${OS_VERSION}${NC}"
}

# 安装依赖
install_dependencies() {
    echo -e "${GREEN}开始安装依赖...${NC}"
    
    if [[ "$OS" == "ubuntu" ]] || [[ "$OS" == "debian" ]]; then
        sudo apt update
        sudo apt install -y git wget openjdk-17-jdk
    elif [[ "$OS" == "centos" ]] || [[ "$OS" == "rhel" ]] || [[ "$OS" == "rocky" ]]; then
        if command -v dnf &> /dev/null; then
            sudo dnf install -y git wget java-17-openjdk java-17-openjdk-devel
        else
            sudo yum install -y git wget java-17-openjdk java-17-openjdk-devel
        fi
    else
        echo -e "${RED}不支持的操作系统: ${OS}${NC}"
        exit 1
    fi
    
    # 验证 Java 安装
    if ! java -version 2>&1 | grep -q "version"; then
        echo -e "${RED}Java 安装失败${NC}"
        exit 1
    fi
    
    echo -e "${GREEN}依赖安装完成${NC}"
}

# 创建工作目录
create_directories() {
    echo -e "${GREEN}创建工作目录...${NC}"
    sudo mkdir -p ${GERRIT_HOME}
    sudo chown ${GERRIT_USER}:${GERRIT_USER} ${GERRIT_HOME}
    cd ${GERRIT_HOME}
}

# 下载 Gerrit
download_gerrit() {
    echo -e "${GREEN}下载 Gerrit ${GERRIT_VERSION}...${NC}"
    cd ${GERRIT_HOME}
    
    if [ ! -f "gerrit-${GERRIT_VERSION}.war" ]; then
        wget https://gerrit-releases.storage.googleapis.com/gerrit-${GERRIT_VERSION}.war
    else
        echo -e "${YELLOW}Gerrit war 文件已存在，跳过下载${NC}"
    fi
}

# 初始化 Gerrit
init_gerrit() {
    echo -e "${GREEN}初始化 Gerrit...${NC}"
    cd ${GERRIT_HOME}
    
    if [ -d "review_site" ]; then
        echo -e "${YELLOW}Gerrit 已初始化，跳过初始化步骤${NC}"
        return
    fi
    
    # 非交互式初始化
    java -jar gerrit-${GERRIT_VERSION}.war init \
        -d review_site \
        --batch \
        --no-auto-start \
        -D gerrit.canonicalWebUrl=http://$(hostname -I | awk '{print $1}'):${GERRIT_PORT}/ \
        --install-plugin=download-commands \
        --install-plugin=replication \
        --install-plugin=reviewnotes || true
    
    # 配置认证方式为开发模式（方便个人使用）
    cat > review_site/etc/gerrit.config << EOCONFIG
[gerrit]
    basePath = git
    canonicalWebUrl = http://$(hostname -I | awk '{print $1}'):${GERRIT_PORT}/
    serverId = $(uuidgen 2>/dev/null || echo $(date +%s))
[database]
    type = h2
    database = db/ReviewDB
[auth]
    type = DEVELOPMENT_BECOME_ANY_ACCOUNT
[sshd]
    listenAddress = *:${GERRIT_SSH_PORT}
[httpd]
    listenUrl = http://*:${GERRIT_PORT}/
[cache]
    directory = cache
[index]
    type = LUCENE
[receive]
    enableSignedPush = false
EOCONFIG

    echo -e "${GREEN}Gerrit 初始化完成${NC}"
}

# 启动 Gerrit
start_gerrit() {
    echo -e "${GREEN}启动 Gerrit 服务...${NC}"
    cd ${GERRIT_HOME}/review_site
    
    # 启动服务
    bin/gerrit.sh start
    
    # 等待服务启动
    sleep 5
    
    # 检查状态
    if bin/gerrit.sh status | grep -q "Running"; then
        echo -e "${GREEN}Gerrit 服务启动成功！${NC}"
    else
        echo -e "${RED}Gerrit 服务启动失败，请检查日志${NC}"
        echo -e "${YELLOW}查看日志: tail -f ${GERRIT_HOME}/review_site/logs/gerrit.log${NC}"
        exit 1
    fi
}

# 创建 systemd 服务（可选）
create_systemd_service() {
    echo -e "${GREEN}创建 systemd 服务...${NC}"
    
    sudo tee /etc/systemd/system/gerrit.service > /dev/null << EOSERVICE
[Unit]
Description=Gerrit Code Review
After=network.target

[Service]
Type=forking
User=${GERRIT_USER}
Group=${GERRIT_USER}
ExecStart=${GERRIT_HOME}/review_site/bin/gerrit.sh start
ExecStop=${GERRIT_HOME}/review_site/bin/gerrit.sh stop
ExecReload=${GERRIT_HOME}/review_site/bin/gerrit.sh restart
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOSERVICE

    sudo systemctl daemon-reload
    sudo systemctl enable gerrit
    
    echo -e "${GREEN}systemd 服务创建完成${NC}"
    echo -e "${YELLOW}使用以下命令管理服务:${NC}"
    echo -e "  启动: sudo systemctl start gerrit"
    echo -e "  停止: sudo systemctl stop gerrit"
    echo -e "  重启: sudo systemctl restart gerrit"
    echo -e "  状态: sudo systemctl status gerrit"
}

# 输出访问信息
print_info() {
    SERVER_IP=$(hostname -I | awk '{print $1}')
    
    echo -e "${GREEN}========================================${NC}"
    echo -e "${GREEN}安装完成！${NC}"
    echo -e "${GREEN}========================================${NC}"
    echo -e "${YELLOW}访问地址:${NC}"
    echo -e "  Web 界面: http://${SERVER_IP}:${GERRIT_PORT}"
    echo -e "  SSH 端口: ${GERRIT_SSH_PORT}"
    echo -e ""
    echo -e "${YELLOW}常用命令:${NC}"
    echo -e "  启动服务: ${GERRIT_HOME}/review_site/bin/gerrit.sh start"
    echo -e "  停止服务: ${GERRIT_HOME}/review_site/bin/gerrit.sh stop"
    echo -e "  重启服务: ${GERRIT_HOME}/review_site/bin/gerrit.sh restart"
    echo -e "  查看状态: ${GERRIT_HOME}/review_site/bin/gerrit.sh status"
    echo -e "  查看日志: tail -f ${GERRIT_HOME}/review_site/logs/gerrit.log"
    echo -e ""
    echo -e "${YELLOW}配置文件位置:${NC}"
    echo -e "  ${GERRIT_HOME}/review_site/etc/gerrit.config"
    echo -e ""
    echo -e "${YELLOW}首次访问:${NC}"
    echo -e "  1. 打开浏览器访问 http://${SERVER_IP}:${GERRIT_PORT}"
    echo -e "  2. 使用任意用户名登录（开发模式）"
    echo -e "  3. 第一个登录的用户将自动成为管理员"
    echo -e "${GREEN}========================================${NC}"
}

# 主函数
main() {
    detect_os
    install_dependencies
    create_directories
    download_gerrit
    init_gerrit
    start_gerrit
    
    # 询问是否创建 systemd 服务
    read -p "是否创建 systemd 服务以便开机自启? (y/n): " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        create_systemd_service
    fi
    
    print_info
}

# 执行主函数
main
EOF

chmod +x install_gerrit.sh
```

### 运行安装脚本

```bash
# 直接运行（使用默认配置）
./install_gerrit.sh

# 或者指定版本和端口
GERRIT_VERSION=3.8.0 GERRIT_PORT=8080 ./install_gerrit.sh
```

---

## 使用指南

### 1. 首页访问与管理员账户创建

#### 访问 Gerrit

1. 打开浏览器，访问 `http://你的服务器IP:8080`
2. 首次访问会看到 Gerrit 欢迎页面

#### 创建管理员账户

**方式一：开发模式（推荐个人使用）**

如果使用 `DEVELOPMENT_BECOME_ANY_ACCOUNT` 认证方式：

1. 点击右上角 "Sign In"
2. 输入任意用户名（例如：`admin`）
3. 点击 "Sign In"
4. **第一个登录的用户自动成为管理员**

**方式二：HTTP 认证**

1. 首次访问会提示创建账户
2. 输入用户名和邮箱
3. 设置密码
4. 第一个账户自动成为管理员

#### 验证管理员权限

登录后，点击右上角用户名 → "Settings" → 左侧菜单应显示 "Administration" 选项。

### 2. 创建项目仓库

#### 在 Web 界面创建项目

1. 登录 Gerrit
2. 点击顶部菜单 "Projects" → "Create Project"
3. 填写项目信息：
   - **Project Name**: `my-project`（例如）
   - **Parent**: `All-Projects`（默认）
   - **Description**: 项目描述（可选）
   - **Submit Type**: `Merge If Necessary`（推荐）
   - **Create initial empty commit**: 勾选（推荐）
4. 点击 "Create Project"

#### 通过命令行创建项目

```bash
# 使用 SSH 连接 Gerrit
ssh -p 29418 admin@你的服务器IP gerrit create-project my-project

# 或者使用 HTTP API（需要配置）
curl -X PUT \
  --user admin:密码 \
  http://你的服务器IP:8080/a/projects/my-project
```

### 3. 在本地 Git 配置与克隆仓库

#### 配置 Git 用户信息

```bash
# 设置全局用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 配置 Gerrit 服务器
git config --global review.你的服务器IP:29418.username admin
```

#### 克隆仓库

```bash
# 方式一：通过 SSH（推荐）
git clone ssh://admin@你的服务器IP:29418/my-project

# 方式二：通过 HTTP
git clone http://你的服务器IP:8080/my-project
```

#### 配置 Git 远程仓库

如果已经有一个本地 Git 仓库，可以添加 Gerrit 作为远程仓库：

```bash
cd your-existing-repo
git remote add gerrit ssh://admin@你的服务器IP:29418/my-project
# 或者
git remote add gerrit http://你的服务器IP:8080/my-project
```

### 4. 开发提交流程

#### 标准提交流程（代码评审）

```bash
# 1. 进入项目目录
cd my-project

# 2. 创建或切换到开发分支
git checkout -b feature/new-feature

# 3. 进行代码修改
echo "# My Project" > README.md
git add README.md

# 4. 提交更改
git commit -m "Add README file"

# 5. 推送到 Gerrit 进行评审
# 关键：推送到 refs/for/master 分支（不是直接推送到 master）
git push origin HEAD:refs/for/master

# 如果配置了 review 用户名，可以使用：
git push gerrit HEAD:refs/for/master
```

**重要说明**：
- `refs/for/master` 表示推送到 `master` 分支的评审队列
- 推送后会生成一个 Change（变更），需要经过评审才能合并
- 推送成功后，Gerrit 会返回 Change 的 URL

#### 推送示例输出

```
remote: Resolving deltas: 100% (1/1)
remote: Processing changes: refs: 1, new: 1
remote: 
remote: SUCCESS
remote: 
remote:   http://你的服务器IP:8080/c/my-project/+/1 [NEW]
remote: 
To ssh://你的服务器IP:29418/my-project
 * [new branch]      HEAD -> refs/for/master
```

### 5. 在网页界面进行代码评审并合并

#### 查看变更

1. 推送成功后，复制 Gerrit 返回的 URL
2. 在浏览器中打开该 URL，或登录 Gerrit 后点击 "Changes" 查看

#### 代码评审流程

1. **查看变更详情**
   - 点击 Change 进入详情页
   - 查看文件差异（Diff）
   - 查看提交信息

2. **添加评论**
   - 在代码行上点击，添加行内评论
   - 在页面底部添加整体评论

3. **评审投票**
   - **Code-Review**: 
     - `+2` = 批准合并
     - `+1` = 看起来不错，但需要其他人批准
     - `-1` = 需要修改
     - `-2` = 拒绝
   - **Verified**:
     - `+1` = 验证通过
     - `-1` = 验证失败

4. **提交者修改代码**（如果需要）

```bash
# 修改代码后，追加提交（会自动关联到同一个 Change）
git add .
git commit --amend  # 修改最后一次提交
git push origin HEAD:refs/for/master
```

5. **合并变更**

当满足以下条件时，变更可以自动合并：
- Code-Review: +2
- Verified: +1（如果启用了 Verified 标签）

或者管理员可以手动点击 "Submit" 按钮合并。

#### 合并后的操作

```bash
# 更新本地仓库
cd my-project
git checkout master
git pull origin master

# 删除已合并的特性分支
git branch -d feature/new-feature
```

### 6. 常用技巧

#### 跳过评审直接推送（个人使用）

如果只是个人使用，可以配置直接推送：

```bash
# 方法一：推送到 refs/heads/master（绕过评审）
git push origin HEAD:refs/heads/master

# 方法二：配置项目权限，允许直接推送
# 在 Gerrit Web 界面：
# Projects → my-project → Access → Edit
# 添加权限：
#   Reference: refs/heads/*
#   Push: 允许你的用户组
```

#### 修改端口

编辑配置文件：

```bash
sudo nano /opt/gerrit/review_site/etc/gerrit.config
```

修改以下部分：

```ini
[httpd]
    listenUrl = http://*:9090/  # 修改为 9090 端口

[sshd]
    listenAddress = *:29419     # 修改 SSH 端口为 29419
```

重启服务：

```bash
/opt/gerrit/review_site/bin/gerrit.sh restart
```

#### 备份数据

```bash
# 1. 停止 Gerrit 服务
/opt/gerrit/review_site/bin/gerrit.sh stop

# 2. 备份整个站点目录
tar -czf gerrit-backup-$(date +%Y%m%d).tar.gz /opt/gerrit/review_site

# 3. 或者只备份重要数据
# 备份 Git 仓库
tar -czf gerrit-git-$(date +%Y%m%d).tar.gz /opt/gerrit/review_site/git

# 备份数据库（H2）
cp -r /opt/gerrit/review_site/db /backup/gerrit-db-$(date +%Y%m%d)

# 备份配置
cp -r /opt/gerrit/review_site/etc /backup/gerrit-etc-$(date +%Y%m%d)

# 4. 启动服务
/opt/gerrit/review_site/bin/gerrit.sh start
```

#### 恢复数据

```bash
# 1. 停止服务
/opt/gerrit/review_site/bin/gerrit.sh stop

# 2. 恢复备份
tar -xzf gerrit-backup-20240101.tar.gz -C /

# 3. 启动服务
/opt/gerrit/review_site/bin/gerrit.sh start
```

#### 查看日志

```bash
# 实时查看日志
tail -f /opt/gerrit/review_site/logs/gerrit.log

# 查看错误日志
tail -f /opt/gerrit/review_site/logs/error_log

# 查看 SSH 日志
tail -f /opt/gerrit/review_site/logs/sshd_log
```

#### 修改管理员账户

```bash
# 通过 SSH 命令添加管理员
ssh -p 29418 admin@你的服务器IP gerrit set-members --add admin Administrators

# 查看管理员组
ssh -p 29418 admin@你的服务器IP gerrit gsql -c "SELECT account_id, full_name FROM accounts WHERE account_id IN (SELECT account_id FROM account_group_members WHERE group_id IN (SELECT group_id FROM account_groups WHERE name='Administrators'));"
```

#### 配置邮件通知（可选）

编辑配置文件：

```bash
sudo nano /opt/gerrit/review_site/etc/gerrit.config
```

添加邮件配置：

```ini
[sendemail]
    smtpServer = smtp.example.com
    smtpServerPort = 587
    smtpEncryption = tls
    smtpUser = your-email@example.com
    smtpPass = your-password
    from = Gerrit Code Review <noreply@example.com>
```

#### 性能优化

对于个人使用，可以调整以下配置：

```bash
sudo nano /opt/gerrit/review_site/etc/gerrit.config
```

```ini
[cache]
    directory = cache

[core]
    packedGitOpenFiles = 128
    packedGitLimit = 100m
    packedGitWindowSize = 8k
```

---

## 常用命令速查

### 服务管理

```bash
# 启动
/opt/gerrit/review_site/bin/gerrit.sh start

# 停止
/opt/gerrit/review_site/bin/gerrit.sh stop

# 重启
/opt/gerrit/review_site/bin/gerrit.sh restart

# 状态
/opt/gerrit/review_site/bin/gerrit.sh status

# 查看日志
tail -f /opt/gerrit/review_site/logs/gerrit.log
```

### Git 操作

```bash
# 推送代码评审
git push origin HEAD:refs/for/master

# 直接推送（跳过评审）
git push origin HEAD:refs/heads/master

# 修改提交后重新推送
git commit --amend
git push origin HEAD:refs/for/master

# 查看远程分支
git ls-remote origin
```

### Gerrit 命令行工具

```bash
# 创建项目
ssh -p 29418 admin@服务器 gerrit create-project my-project

# 查看项目列表
ssh -p 29418 admin@服务器 gerrit ls-projects

# 查看用户信息
ssh -p 29418 admin@服务器 gerrit query --format=JSON --current-patch-set change:1
```

---

## 故障排查

### 问题 1: 无法访问 Web 界面

**检查项**：
1. 服务是否运行：`/opt/gerrit/review_site/bin/gerrit.sh status`
2. 端口是否被占用：`netstat -tlnp | grep 8080`
3. 防火墙是否开放端口：
   ```bash
   # Ubuntu/Debian
   sudo ufw allow 8080/tcp
   
   # CentOS
   sudo firewall-cmd --permanent --add-port=8080/tcp
   sudo firewall-cmd --reload
   ```
4. 查看错误日志：`tail -f /opt/gerrit/review_site/logs/gerrit.log`

### 问题 2: SSH 连接失败

**检查项**：
1. SSH 服务是否运行：检查 Gerrit 日志
2. 端口是否正确：默认 29418
3. 用户权限：确保用户已注册

### 问题 3: 推送失败

**常见错误**：
- `Permission denied`: 检查项目权限配置
- `Branch refs/for/master not found`: 确保推送到 `refs/for/master` 而不是 `master`
- `Authentication failed`: 检查 SSH 密钥或 HTTP 认证配置

---

## 总结

恭喜！你已经完成了 Gerrit 的安装和基本配置。现在你可以：

1. ✅ 通过 Web 界面管理代码评审
2. ✅ 使用 Git 推送代码进行评审
3. ✅ 在网页上进行代码审查和合并
4. ✅ 管理项目仓库和用户权限

**下一步建议**：
- 配置邮件通知（如果需要）
- 设置项目权限规则
- 安装常用插件（如：download-commands, replication）
- 配置定期备份

祝你使用愉快！如有问题，请查看 Gerrit 官方文档：https://www.gerritcodereview.com/