安装部署

codingas.com 基于 Java 21 + Spring Boot 3.5，支持多种部署方式。开发期可用内嵌 H2 零依赖启动，生产环境推荐 PostgreSQL + Redis。

环境要求

组件	版本	说明
JDK	21+	推荐 Eclipse Temurin
Maven	3.9+	仓库自带 `mvnw`，可直接用 `./mvnw`
PostgreSQL	14+（生产）	开发可用内嵌 H2 替代
Redis	7.x（生产）	本地缓存模式可不依赖

一、源码运行（开发试用，最快）

仓库根目录执行：

./mvnw spring-boot:run -pl gateway-boot

默认 local profile：内嵌 H2 文件库 + 自动建表 + 示例数据，无需 PostgreSQL / Redis。服务监听 http://localhost:8080。

二、源码构建 + jar 运行

# 构建（跳过测试加速）
./mvnw clean install -DskipTests -pl gateway-boot

# 产物：gateway-boot/target/gateway-boot-1.0.0-SNAPSHOT.jar

# 运行（H2 开发模式）
java -jar gateway-boot/target/gateway-boot-1.0.0-SNAPSHOT.jar \
  --spring.profiles.active=local

# 运行（PostgreSQL 生产模式）
java -jar gateway-boot/target/gateway-boot-1.0.0-SNAPSHOT.jar \
  --spring.profiles.active=postgresql

三、PostgreSQL 生产部署

准备数据库：创建库 llm_gateway（PostgreSQL 不会自动建库）并安装扩展：

CREATE DATABASE llm_gateway;
\c llm_gateway
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

设置环境变量并启动：

export DB_URL="jdbc:postgresql://localhost:5432/llm_gateway"
export DB_USERNAME="llm_gateway"
export DB_PASSWORD="your_secure_password"
export ENCRYPTION_KEY="$(openssl rand -base64 32)"  # 必填
export SPRING_PROFILES_ACTIVE=postgresql

java -jar gateway-boot/target/gateway-boot-1.0.0-SNAPSHOT.jar

启动后 Flyway 自动执行表结构迁移（无需手动建表）。

加密密钥（必读）

API Key 使用 AES-256-GCM 加密存储。密钥获取顺序为：gateway.security.encryption-key 配置属性 → 环境变量 ENCRYPTION_KEY → 开发环境临时密钥：

# 生成 32 字节 Base64 密钥
openssl rand -base64 32

生产环境（postgresql / prod 等非 local/dev profile）必须配置，否则启动抛 ENCRYPTION_KEY_MISSING
环境变量名为 ENCRYPTION_KEY；GATEWAY_ENCRYPTION_KEY 仅在 local profile 的 yml 映射中生效，生产环境请直接使用 ENCRYPTION_KEY
local / dev profile 允许使用临时密钥，但重启后已加密数据无法解密
密钥丢失 = 所有已存储的上游 Key 失效，请妥善备份

Profile 对照

Profile	数据库	Redis	缓存	用途
`local`（默认）	H2 文件	关闭	-	本地开发，预置示例数据
`dev`	H2 文件	关闭	-	开发调试
`postgresql`	PostgreSQL	启用	-	生产推荐
`standalone`	同上	-	Caffeine	单机，本地限流
`prod`	同上	启用	simple	生产精简日志

关键环境变量

变量	默认值	说明
`SPRING_PROFILES_ACTIVE`	`local`	激活的 profile
`SERVER_PORT`	`8080`	服务端口
`DB_URL`	H2 文件	数据库 JDBC URL
`DB_USERNAME` / `DB_PASSWORD`	`sa` / 空	数据库账号
`REDIS_HOST` / `REDIS_PORT`	`localhost` / `6379`	Redis 地址
`ENCRYPTION_KEY`	空	API Key 加密密钥（生产必填，Base64 32 字节）
`OTEL_EXPORTER_OTLP_ENDPOINT`	空	OpenTelemetry Trace 上报地址

完整占位符清单见 gateway-boot/src/main/resources/application.yml 中 ${ENV:默认值} 定义，另见配置项参考。

健康检查

curl http://localhost:8080/actuator/health

可用端点：/actuator/health、/actuator/health/liveness、/actuator/health/readiness、/actuator/prometheus、/actuator/metrics、/actuator/traces、/actuator/info。详见可观测性。

四、Docker 部署

仓库提供 deployments/docker/Dockerfile 与 docker-compose.yml（含 PostgreSQL、Redis、Prometheus、Grafana、Jaeger、OTel Collector）：

cd deployments/docker
docker compose up -d

Dockerfile 采用多阶段构建（单模块 gateway-boot），运行阶段基于 eclipse-temurin:21-jre-alpine，健康检查端点为 /actuator/health，默认暴露 8080 端口。

五、系统安装包（deb / rpm / Windows zip）

deployments/package/ 提供基于 Gradle ospackage 的系统安装包（不内置 JRE，目标机需预装 Java 17/21/25）：

./deployments/package/build.sh
# 产物（deployments/package/dist/）：
#   llmgateway.deb          Linux deb（Ubuntu/Debian）
#   llmgateway.rpm          Linux rpm（RHEL/Rocky/CentOS）
#   llmgateway-win-*.zip    Windows zip

安装方式：

# Linux deb（自动拉取 openjdk-21-jre-headless 依赖），systemd 注册服务
sudo apt install ./llmgateway_*.deb

# Linux rpm（自动拉取 java-21-headless 依赖）
sudo dnf install ./llmgateway-*.rpm

Windows 解压 zip 后以管理员身份运行 bin\install.ps1（需 PATH 可执行 java）。安装时密钥自动生成，务必备份。

下一步

快速开始：跑通第一个请求
控制台快速上手：管理后台导览
配置项参考：完整配置说明