Ubuntu 22.04 安装 Apache Grails 指南

Apache Grails 是基于 Groovy 的全栈 Web 框架，构建在 Spring Boot 之上，通过 grails CLI 完成工程脚手架、运行与打包。本文在 Ubuntu 22.04 服务器上完成 JDK 与 Grails 的安装，并创建一个最小应用进行真实验证。示例登录账号统一为 root / q1w2e3r4。

一、环境与前置条件

1.1 系统要求

项目	要求
操作系统	Ubuntu 22.04 LTS（x86_64）
JDK	JDK 11 或 JDK 17（Grails 6.x 官方支持）
内存	建议 ≥ 2GB（运行应用时 JVM 堆 256–512MB）
磁盘	建议 ≥ 5GB（含 Gradle 与依赖缓存）
网络	可访问 Maven 中央仓库与 Gradle 发行包地址

本文实测环境为 Ubuntu 22.04.5 LTS，最终安装 Grails 6.2.3 + OpenJDK 17.0.20.1。

1.2 前置工具

sudo apt-get update -qq
sudo apt-get install -y curl unzip zip git ca-certificates

1.3 网络受限说明

部分环境无法直连 github.com（实测连接超时），而 Grails 官方二进制包托管在 GitHub Release。此时可改用可达的加速镜像拉取，下载地址与校验方式保持一致。若服务器可直连 GitHub，则可直接使用官方原始地址。

二、安装 JDK

2.1 安装 OpenJDK 17

sudo apt-get install -y openjdk-17-jdk

2.2 验证 Java

java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

如系统安装多版本 JDK，可通过 update-alternatives 切换：

sudo update-alternatives --config java

三、安装 Apache Grails

Grails 提供两种主流安装方式：SDKMAN 版本管理器与官方二进制包。两者结果一致，任选其一。

3.1 方式一：二进制包安装（推荐，网络受限时首选）

# 1) 创建安装目录
sudo mkdir -p /opt/grails-dl

# 2) 下载 Grails 6.2.3 二进制包（GitHub 不可达时使用加速镜像前缀）
curl -L -m 300 --retry 2 -o /opt/grails-dl/grails-6.2.3.zip \
  "https://gh-proxy.com/https://github.com/apache/grails-core/releases/download/v6.2.3/grails-6.2.3.zip"

# 3) 解压到 /opt
cd /opt && sudo unzip -q /opt/grails-dl/grails-6.2.3.zip -d /opt/

实测下载包大小约 172MB，解压后目录为 /opt/grails-6.2.3。

3.2 配置环境变量

sudo tee /etc/profile.d/grails.sh >/dev/null <<'EOF'
export GRAILS_HOME=/opt/grails-6.2.3
export PATH=$GRAILS_HOME/bin:$PATH
EOF

source /etc/profile.d/grails.sh

验证环境变量：

echo $GRAILS_HOME
# /opt/grails-6.2.3

3.3 方式二：SDKMAN 安装

服务器可直连 github.com 时，可用 SDKMAN 安装并管理多版本：

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install grails 6.2.3

实测说明：SDKMAN 安装脚本本身可下载，但其下载 broker 会重定向至 github.com，在 GitHub 不可达环境中会报 curl: (7) Failed to connect to github.com port 443，此时请改用 3.1 的二进制包方式。

四、验证安装

grails --version

实测回显：

| Grails Version: 6.2.3
| JVM Version: 17.0.20.1

同时可确认 CLI 可用：

grails help

将打印 Usage、示例命令与全部可用命令列表（create-app、run-app、generate-all、assemble 等）。

五、创建并运行最小应用

5.1 创建应用

mkdir -p /root/grails-lab && cd /root/grails-lab
grails create-app demoapp

实测回显：

| Application created at /root/grails-lab/demoapp

生成的工程目录包含：

demoapp/
├── build.gradle          # Gradle 构建脚本
├── gradle.properties
├── gradlew / gradlew.bat # Gradle Wrapper
├── grailsw / grails-wrapper.jar
├── grails-app/
│   ├── conf/application.yml   # 主配置（profile=web，H2 数据源）
│   ├── controllers/           # 控制器
│   ├── domain/                # GORM 域类
│   ├── views/                 # GSP 视图
│   └── init/
└── src/                       # Groovy/Java 源码与测试

5.2 启动应用

cd /root/grails-lab/demoapp
export JAVA_OPTS="-Xmx512m"     # JVM 堆限制在 256–512MB 规范内
grails run-app

首次运行会下载 Gradle 发行包与依赖（实测约 8 分钟），随后启动内嵌 Tomcat：

Grails application running at http://localhost:8080 in environment: development

5.3 访问验证

另开终端采集真实 HTTP 响应：

curl -i http://localhost:8080/

实测回显（节选）：

HTTP/1.1 200
Content-Type: text/html;charset=UTF-8

<title>Welcome to Grails</title>

5.4 创建控制器并验证路由

grails create-controller Hello

编辑 grails-app/controllers/demoapp/HelloController.groovy：

package demoapp

import grails.converters.JSON

class HelloController {
    def index() {
        render([status: "ok", framework: "Apache Grails", version: "6.2.3"] as JSON)
    }
}

访问 http://localhost:8080/hello（开发模式下自动热重载）：

curl -i http://localhost:8080/hello

实测回显：

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{"status":"ok","framework":"Apache Grails","version":"6.2.3"}

5.5 停止应用

grails stop-app

实测回显：

| Shutting down application...
| {"message":"Shutting down, bye..."}
| Application shutdown.

停止后 curl http://localhost:8080/ 返回 Connection refused，端口已释放。

六、卸载

6.1 二进制包方式卸载

rm -rf /opt/grails-6.2.3
sudo rm -f /etc/profile.d/grails.sh
unalias grails 2>/dev/null; hash -r

清理 Gradle 缓存（可选，释放磁盘）：

rm -rf ~/.gradle

6.2 SDKMAN 方式卸载

sdk uninstall grails 6.2.3
rm -rf ~/.sdkman

6.3 卸载 JDK（可选）

sudo apt-get remove -y --purge openjdk-17-jdk
sudo apt-get autoremove -y

6.4 验证卸载

command -v grails   # 应无输出
ls -d /opt/grails-6.2.3   # 应提示 No such file or directory

七、常见问题

Q1：grails --version 报找不到 java？ 确认 java -version 正常，且 JAVA_HOME（如设置）指向有效 JDK；必要时执行 sudo update-alternatives --config java 指定 JDK 17。

Q2：create-app 或 run-app 卡在下载？ 首次运行需从 Maven 中央仓库与 Gradle 发行地址拉取依赖，网络受限时可配置镜像仓库或在可达网络中预热 ~/.gradle 缓存。

Q3：8080 端口被占用？ 在 grails-app/conf/application.yml 中修改 server.port，或启动前设置 SERVER_PORT 环境变量。

Q4：生产部署用哪个命令打包？ Grails 6.x 没有 war 命令，使用 grails assemble 生成 JAR/WAR 归档。