# 快速部署

本节介绍如何使用 g2rain-deploy (opens new window) 在单机或内网环境快速拉起 G2rain 全栈：MySQL、Redis、Nacos、Nginx、IAM、网关、basis、infra 及可选业务容器。更完整的运维说明见 g2rain-deploy 模块文档。

# 适用场景

场景	说明
体验 / 演示	不想手工拼装各微服务，希望一条命令起全栈
内网 PoC	在自有服务器用 Docker 验证平台能力
业务扩展	通过 `business.d` 叠加 CMS、自定义网关等 Compose 片段
日常迭代	用 `update.sh` 拉代码、构建镜像并滚动更新

在线演示环境：https://demo.g2rain.com/ (opens new window)

# 环境要求

运行 Compose 栈：

Docker 20.10+
docker-compose（V1 独立命令）或 docker compose 插件（V2）
建议 4GB+ 内存、10GB+ 磁盘

首次 ./init-once.sh（克隆源码并构建本地镜像）还需：

Git、JDK、Maven（java、mvn 在 PATH）
可访问 Git 远端（默认 https://github.com/g2rain，可用 G2RAIN_GIT_BASE 调整）

# 三步上手

git clone https://github.com/g2rain/g2rain-deploy.git
cd g2rain-deploy

# 1. 一次性安装：.env、SQL 占位符、克隆 codes/、构建镜像
./init-once.sh --host <服务器IP或域名> --port <HTTPS端口> --ssl-ip <服务器IP或域名>

# 2. 启动栈
./start.sh

# 3. 日常更新
./update.sh

默认入口端口见 .env（env.example 常见为 HTTP 10080、HTTPS 10443）。init-once.sh 不执行 docker compose up，装完后须 ./start.sh。

# init-once：一次性安装

init-once.sh 负责「装环境、备数据、拉代码、建镜像」，成功后写入 .g2rain-deploy-install.done。

步骤	行为
依赖检查	Docker、Git、JDK、Maven、Compose CLI
`.env`	若无则从 `env.example` 复制；`--host` / `--port` 写入 `PLATFORM_HOST`、`PLATFORM_PORT` 等
MySQL 初始化 SQL	按 `.env` 替换 `config/mysql/g2rain-basis.sql` 中 `__PLATFORM_HOST__`、`__PLATFORM_PORT__`（仅空数据卷首次导入生效）
SSL（可选）	`--ssl-ip` 调用 `config/generate-ssl.sh` 生成 `ssl/server.crt` / `server.key`
克隆源码	按 `services.conf`（及 `service_config.d`）克隆到 `codes/`
构建镜像	默认在各仓库执行 `build.sh`（可用 `--skip-build` 跳过）

常用命令：

# 快捷：平台地址 + HTTPS 端口 + 证书
./init-once.sh --host 43.138.13.145 --port 443 --ssl-ip 43.138.13.145

# 仅克隆与配置，暂不构建（网络差时）
./init-once.sh --skip-build

# 忽略完成标记重装
./init-once.sh --force

# 构建失败重试
G2RAIN_BUILD_RETRIES=5 G2RAIN_BUILD_RETRY_SLEEP=30 ./init-once.sh

# 使用其他 Git 组织前缀
G2RAIN_GIT_BASE=https://github.com/your-org ./init-once.sh

完整参数：./init-once.sh --help

# start / stop：启动与停止

# start.sh

检查依赖与 SSL → 缺镜像时从 codes/ 构建 → docker compose up -d（具体 CLI 见下文 V1/V2）。

./start.sh
./start.sh --host <HOST> --port <PORT>
./start.sh --compose-v2
./start.sh --generate-ssl <IP或域名>   # 仅生成证书，不启动

未检测到 .g2rain-deploy-install.done 时会提示先执行 init-once.sh。缺少 ssl/server.crt 时 会阻止启动（入口 Nginx HTTPS 必需）。

# stop.sh

./stop.sh                    # stop：容器保留，可再次 start
./stop.sh --cleanup          # down：删除容器与默认网络，并 prune 镜像
./stop.sh --compose-v2 --cleanup

start、stop、update 应使用同一套 Compose CLI（均读 config/compose-cli.env 或相同的 --compose-v2 / --compose-v1），避免项目上下文不一致。

# update：日常更新

update.sh 按 services.conf 映射：git pull → build.sh → pull / up 滚动更新。

./update.sh                           # 更新全部
./update.sh g2rain-gateway            # 只更新指定 compose 服务名
./update.sh --compose-v2 g2rain-iam
./update.sh --force-pull              # 强制拉取远程镜像
./update.sh --cleanup-all             # 更新后清理未使用镜像

服务名与 services.conf 中第三段 compose_service 一致。完整选项：./update.sh --help

# 配置说明

# `.env`（环境变量）

从 env.example 复制；init-once.sh / start.sh 在首次也可代为创建。

变量	说明
`PLATFORM_HOST` / `PLATFORM_PORT`	平台对外地址，写入 SSO 等；`init-once` 用于替换 basis SQL 占位符
`NGINX_HTTP_PORT` / `NGINX_HTTPS_PORT`	入口 Nginx 端口（示例 `10080` / `10443`）
`MYSQL_` / `REDIS_`	数据库与缓存连接、映射端口
`GATEWAY_IMAGE`	可选，覆盖网关镜像（如 WebMVC）

完整列表以仓库 env.example 为准。

# `services.conf`（源码与构建映射）

Bash 片段，定义 SERVICES 数组，每项格式：

"repo|dir|compose_service|build_cmd"

字段	含义
`repo`	GitHub 仓库名（与 `G2RAIN_GIT_BASE` 拼接）
`dir`	检出到 `codes/` 下的目录名
`compose_service`	`docker-compose.yml` 中的服务名
`build_cmd`	构建命令，默认 `./build.sh`

init-once.sh、update.sh、start.sh（缺镜像时）均依赖此映射。

# `service_config.d/`（扩展服务映射）

在默认 services.conf 之外追加 SERVICES 条目，运行时内存合并，不改写 services.conf。

每个 *.conf 定义 SERVICES=( "repo|dir|compose_service|build_cmd" )
以 compose_service 为键去重，后加载的覆盖先加载的
默认加载目录下全部 .conf；可用 --service <名> 只加载指定片段

./init-once.sh --service custom-apps
./update.sh --service custom-apps g2rain-cms
./start.sh --service module-a --service module-b

详见仓库 service_config.d/README.md。

# `config/` 其他要点

路径	用途
`config/mysql/`	初始化 SQL（basis、infra、cms、department 等）
`config/nginx/conf.d/`	入口反向代理；`locations.inc` 须与子应用 `VITE_CONTEXT_PATH` 对齐
`config/compose-cli.env`	Compose V1/V2 偏好（见下节）
`config/generate-ssl.sh` / `generate_key.sh`	SSL 与前端 ES256 密钥

持久化目录：data/mysql、data/redis；日志：logs/。

# Docker Compose V1 与 V2

仓库维护两套等价主配置，脚本通过 compose-cli-preference.inc 统一选择 CLI：

模式	命令	主文件
V1（默认）	`docker-compose`	`docker-compose.yml`（含 `version` 键）
V2	`docker compose`	`compose-v2/compose.yaml`（Compose Specification，`name: g2rain-deploy`）

# 如何启用 V2

方式一：命令行（单次，优先级最高）

./start.sh --compose-v2
./stop.sh --compose-v2
./update.sh --compose-v2

方式二：持久化偏好

# 探测本机并写入 config/compose-cli.env
./scripts/write-compose-cli-preference.sh

# 或手动复制模板后设置
# G2RAIN_USE_COMPOSE_V2=1

init-once.sh 在依赖检测通过后会默认尝试写入该文件。未传 --compose-v2 / --compose-v1 时，脚本读取 config/compose-cli.env 中的 G2RAIN_USE_COMPOSE_V2。

方式三：手动执行 V2（须在仓库根目录）

docker compose -f compose-v2/compose.yaml --project-directory . up -d

修改 docker-compose.yml 后请同步 compose-v2/compose.yaml，避免两套配置漂移。

强制回退 V1：./start.sh --compose-v1

# business.d：快速扩展业务

business.d/ 存放与主 Compose 合并加载的业务片段（.yml）。start.sh、stop.sh、update.sh 会在主文件之后按 -f 链自动追加该目录下的片段（见 compose-merge.inc）。

# 默认行为

目录下所有 *.yml 均会合并（不排序，由 shell 展开顺序决定）
仓库默认提供 g2rain-cms.yml（g2rain-cms、g2rain-cms-app），已从主 compose 拆出
勿在多个片段中重复定义同一 service 名

# 只加载部分片段

./start.sh --business g2rain-cms
./start.sh --business g2rain-cms --business gateway-webmvc
./update.sh g2rain-manager-app --business tenant-a

指定 --business 后仅加载列出的文件，不再自动扫描目录其余 .yml。若仍需 CMS，须显式带上 g2rain-cms。

# 常见扩展示例

切换 WebMVC 网关：

cp docker-compose.fragment.gateway-webmvc.yml business.d/gateway-webmvc.yml
./start.sh

片段覆盖 g2rain-gateway 的 image（默认 g2rain/g2rain-gateway-webmvc:latest，可用 GATEWAY_IMAGE 环境变量覆盖）。

新增自定义业务栈：

在 business.d/ 新建 my-biz.yml，定义你的服务、网络与卷；与主栈共用 g2rain-network 与 MySQL/Redis 即可。若不经脚本、直接执行 compose，须手动带上所有 -f：

docker-compose -f docker-compose.yml -f business.d/g2rain-cms.yml --project-directory . up -d

# 辅助脚本一览 {#deploy-scripts}

除根目录生命周期脚本外，g2rain-deploy 在 config/、scripts/ 下提供证书与密钥工具。与认证与安全中的 JWT + DPoP 链路对应关系见下节。

脚本	路径	作用
生命周期	`init-once.sh`	一次性安装（`.env`、SQL、克隆、`build.sh`）
	`start.sh`	启动栈；`--generate-ssl` 委托证书脚本
	`stop.sh`	停止；`--cleanup` 执行 `down`
	`update.sh`	拉代码、构建、滚动更新
Compose CLI	`scripts/write-compose-cli-preference.sh`	探测 `docker compose` / `docker-compose`，写入 `config/compose-cli.env`
HTTPS	`config/generate-ssl.sh`	为入口 Nginx 生成自签名 TLS 证书
DPoP / 应用密钥	`config/generate_key.sh`	为前端子应用生成 ES256（P-256）公私钥对

init-once.sh 在依赖检测通过后会默认调用 write-compose-cli-preference.sh；start.sh --generate-ssl 与 init-once.sh --ssl-ip 均会调用 generate-ssl.sh。

# HTTPS 证书（`generate-ssl.sh`）{#deploy-ssl}

G2rain Compose 栈的 TLS 仅用于集群总入口 Nginx（ssl/server.crt、ssl/server.key）。网关、IAM、basis、infra 等业务容器走内网 HTTP，不挂载该证书。

# 生成方式

# 方式 1：独立脚本（推荐）
./config/generate-ssl.sh <服务器IP或域名>

# 方式 2：安装阶段一并生成
./init-once.sh --host demo.g2rain.com --port 443 --ssl-ip demo.g2rain.com

# 方式 3：仅生成证书，不启动栈
./start.sh --generate-ssl 192.168.1.100

# 行为说明

项	说明
参数	支持 IPv4 或域名（如 `demo.g2rain.com`）
输出	项目根目录 `ssl/server.crt`（644）、`ssl/server.key`（600）
SAN	IP 模式含指定 IP + `127.0.0.1` + `localhost`；域名模式含指定域名 + `localhost` + `127.0.0.1`
有效期	自签名，365 天；浏览器会提示不受信任，需手动信任或换用正式 CA 证书
覆盖	证书已存在时会交互询问是否覆盖
启动约束	`start.sh` 全栈启动前会检查证书；缺失则拒绝启动（`./start.sh kafka` 等仅中间件模式除外）

# 重新生成

rm -f ssl/server.crt ssl/server.key
./config/generate-ssl.sh <新IP或域名>
./start.sh

生产环境可将自有 CA 签发的 server.crt / server.key 直接放入 ssl/ 目录（保持 Nginx 挂载路径不变）。

# DPoP 与 JWT 密钥（`generate_key.sh`）{#dpop-jwt-keys}

G2rain 安全链路区分三类密钥材料（详见认证与安全）：

flowchart LR
  subgraph ingress [入口 TLS]
    SSL[ssl/server.crt<br/>generate-ssl.sh]
  end

  subgraph server [服务端 JWT 签发]
    Nacos[g2rain-token-keypair.yml<br/>Nacos / init-nacos.sql]
    IAM[g2rain-iam 签发 JWT]
  end

  subgraph client [客户端 DPoP]
    AppKey[应用 ES256 密钥对<br/>generate_key.sh]
    DPoP[DPoP 请求头签名]
  end

  subgraph verify [前端校验 IAM JWT]
    IAMPub[iam-public-key.pem<br/>iam-key-id.txt]
  end

  SSL --> Nginx
  Nacos --> IAM
  AppKey --> DPoP
  IAM --> IAMPub
  DPoP --> Gateway[网关 DPoP 校验]

# 1. 服务端 JWT 密钥（IAM / 网关）

配置名：Nacos 中 g2rain-token-keypair.yml（group=g2rain）
部署包：config/mysql/init-nacos.sql 已预置演示用 ES256 key-id 与公私钥，MySQL 首次初始化时写入 Nacos
用途：IAM 在 /auth/token 等端点签发 JWT；网关用同一套材料校验访问令牌
生产轮换：在 Nacos 更新 token.keys 后，须同步更新各前端 config/<应用>/keys/ 下的 iam-public-key.pem 与 iam-key-id.txt（须与 Nacos 中 key-id、公钥一致）

演示环境仓库已为主应用、子应用预置匹配的 IAM 公钥文件，例如：

config/g2rain-main-shell/keys/
├── private-key.pem      # 应用 DPoP 私钥
├── public-key.pem       # 应用 DPoP 公钥
├── iam-public-key.pem   # 校验 IAM 所发 JWT
└── iam-key-id.txt       # IAM 当前活跃 key-id

# 2. 客户端 DPoP / 应用密钥（`generate_key.sh`）

前端子应用（及主应用）用 ES256（P-256） 密钥对证明「持有私钥」，为 HTTP 请求构建 DPoP 头，并与 JWT 绑定以防重放。脚本同时输出 PEM 与 DER，私钥为 PKCS#8（兼容 OpenResty / lua-resty-openssl）。

# 默认文件名：private-key.pem / public-key.pem（及 .der）
./config/generate_key.sh config/g2rain-main-shell/keys

# 自定义前缀（生成 iam-private-key.pem 等）
./config/generate_key.sh config/g2rain-main-shell/keys iam

# 为新子应用生成
./config/generate_key.sh config/my-new-app/keys

输出文件：

文件	格式	用途
`private-key.pem`	PKCS#8 PEM	前端签名 DPoP（勿泄露、勿提交生产私钥到公开仓库）
`public-key.pem`	PEM	注册到 IAM/OAuth 客户端配置，供网关校验 DPoP
`private-key.der` / `public-key.der`	DER	部分运行时或 Lua 侧读取

依赖本机 OpenSSL（openssl ecparam、pkcs8 等）。

# 3. 新增子应用时的密钥清单

步骤	操作
1	`./config/generate_key.sh config/<compose服务名>/keys` 生成应用 DPoP 密钥对
2	从 Nacos `g2rain-token-keypair.yml` 或 IAM 管理端取得当前 JWT 公钥与 key-id，写入 `iam-public-key.pem`、`iam-key-id.txt`
3	确保 Compose / 镜像构建将 `config/<应用>/keys/` 挂载或打入前端静态资源路径（与仓库内现有子应用一致）
4	在 basis 注册应用时，应用的 clientPublicKey 与 `public-key.pem` 对应

密钥轮换后需同时更新 Nacos JWT 材料与各前端 iam-* 文件，并重新构建/发布受影响的前端镜像。

# 与子应用路径对齐

新增前端子应用时：

子应用 .env 中 VITE_CONTEXT_PATH 与 Nginx config/nginx/conf.d/locations.inc 中 location 路径一致
proxy_pass 目标与 docker-compose 服务名一致
按上节使用 generate_key.sh 生成 DPoP 密钥，并配置 IAM 公钥与 iam-key-id
修改 Nginx 后：docker-compose restart nginx（或 V2 等价命令）

# 运维速查

docker-compose ps                    # 或 docker compose … ps（与启动时 CLI 一致）
docker-compose logs -f g2rain-gateway
./stop.sh --cleanup && ./start.sh    # 清容器后重启（慎用，会 down）

# 相关文档

g2rain-deploy 模块说明
快速开始（子应用开发）
架构设计
仓库 README：github.com/g2rain/g2rain-deploy (opens new window)

← 快速开始技术栈概览 →