softinstigate/restheart

RESTHeart - 零代码构建即时后端 API

https://img.shields.io/docker/pulls/softinstigate/restheart.svg?maxAge=2592000](https://hub.docker.com/r/softinstigate/restheart/) https://img.shields.io/github/stars/SoftInstigate/restheart?label=GitHub%20Stars](https://github.com/SoftInstigate/restheart)

开源 Java 服务器，无需编写代码即可从 MongoDB 集合自动生成 REST、GraphQL 和 WebSocket API。

完美适配容器化环境 — 无状态架构专为 Docker、Kubernetes、AWS ECS、App Runner 及任何容器编排平台设计。

为何在容器中使用 RESTHeart？

✅ 无状态设计 — 无本地状态，轻松实现水平扩展
✅ 快速启动 — 秒级就绪，适合自动扩缩容场景
✅ 轻量级 — 资源占用高效（原生镜像约 80MB）
✅ Java 25 虚拟线程 — 高效处理 10K+ 并发连接
✅ 优化 JVM — G1GC 调优，适用于堆内存 ≤2GB 的高吞吐量 REST API
✅ 基于环境的配置 — 通过 RHO 环境变量进行配置
✅ 健康检查端点 — 内置 /ping 和 /metrics 供编排平台使用
✅ 12-Factor 应用 — 遵循云原生最佳实践

快速开始

Docker Compose（开发环境）

bash
curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/docker-compose.yml \
  --output docker-compose.yml && docker compose up

通过 http://localhost:8080 访问 RESTHeart

Docker Run（独立运行）

bash
docker run -d \
  --name restheart \
  -p 8080:8080 \
  -e RHO="/mclient/connection-string->'mongodb://mongodb:27017'" \
  docker.xuanyuan.run/softinstigate/restheart:latest

与 MongoDB 一起运行

bash
# 启动 MongoDB
docker run -d --name mongodb -p 27017:27017 docker.xuanyuan.run/mongo:7

# 启动 RESTHeart
docker run -d \
  --name restheart \
  --link mongodb \
  -p 8080:8080 \
  -e RHO="/mclient/connection-string->'mongodb://mongodb:27017'" \
  docker.xuanyuan.run/softinstigate/restheart:latest

测试 API：

bash
curl http://localhost:8080/ping

容器编排

免责声明：以下示例仅供参考，您需要根据具体需求、安全策略和基础设施设置进行调整。

Kubernetes

部署示例：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: restheart
spec:
  replicas: 3
  selector:
    matchLabels:
      app: restheart
  template:
    metadata:
      labels:
        app: restheart
    spec:
      containers:
      - name: restheart
        image: docker.xuanyuan.run/softinstigate/restheart:latest  # 使用 :native 以实现更快的自动扩缩容
        ports:
        - containerPort: 8080
        env:
        - name: RHO
          value: "/mclient/connection-string->'mongodb://mongodb-service:27017'"
        livenessProbe:
          httpGet:
            path: /ping
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ping
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
  name: restheart-service
spec:
  selector:
    app: restheart
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

K8s 核心特性：

• 无状态 Pod 支持无缝水平扩展
• 内置健康检查端点用于存活/就绪探针
• 支持 ConfigMaps 进行配置管理
• 支持 Secrets 存储敏感数据（MongoDB 凭证、JWT 密钥）

AWS ECS

任务定义：

json
{
  "family": "restheart",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "containerDefinitions": [
    {
      "name": "restheart",
      "image": "softinstigate/restheart:latest",
      "portMappings": [
        {
          "containerPort": 8080,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {
          "name": "RHO",
          "value": "/mclient/connection-string->'mongodb+srv://user:pass@cluster.mongodb.net'"
        }
      ],
      "healthCheck": {
        "command": ["CMD-SHELL", "curl -f http://localhost:8080/ping || exit 1"],
        "interval": 30,
        "timeout": 5,
        "retries": 3
      },
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/restheart",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

ECS 优势：

• 原生 AWS 集成，支持 DocumentDB
• 基于 CloudWatch 指标的自动扩缩容
• 应用负载均衡器集成
• 任务级 IAM 角色支持，增强安全性

AWS App Runner

最简单的 AWS 部署：

bash
aws apprunner create-service \
  --service-name restheart-api \
  --source-configuration '{
    "ImageRepository": {
      "ImageIdentifier": "softinstigate/restheart:latest",
      "ImageRepositoryType": "ECR_PUBLIC",
      "ImageConfiguration": {
        "Port": "8080",
        "RuntimeEnvironmentVariables": {
          "RHO": "/mclient/connection-string->\"mongodb+srv://user:pass@cluster.mongodb.net\""
        }
      }
    },
    "AutoDeploymentsEnabled": false
  }' \
  --instance-configuration '{
    "Cpu": "1 vCPU",
    "Memory": "2 GB"
  }'

App Runner 优势：

• 完全托管，无需配置基础设施
• 自动 HTTPS 和自定义域名支持
• 按使用量付费（可缩容至零）
• 适合 MVP 和低维护成本部署

Docker Swarm

bash
docker service create \
  --name restheart \
  --replicas 3 \
  --publish 8080:8080 \
  --env RHO="/mclient/connection-string->'mongodb://mongodb:27017'" \
  --health-cmd "curl -f http://localhost:8080/ping || exit 1" \
  --health-interval 30s \
  --health-retries 3 \
  softinstigate/restheart:latest

配置

环境变量配置

RHO 环境变量用于覆盖 YAML 配置：

bash
docker run -e RHO="/http-listener/host->'0.0.0.0';/http-listener/port->8080" \
  docker.xuanyuan.run/softinstigate/restheart:latest

基于卷的配置

bash
docker run -v ./restheart.yml:/opt/restheart/etc/restheart.yml \
  docker.xuanyuan.run/softinstigate/restheart:latest

示例 restheart.yml：

yaml
mongo-uri: mongodb://mongodb:27017

http-listener:
  host: 0.0.0.0
  port: 8080

auth:
  mechanism: jwtAuthentication
  jwt:
    key: your-secret-key

cors:
  enabled: true
  allow-origin: "*"

密钥管理

Kubernetes Secrets：

yaml
apiVersion: v1
kind: Secret
metadata:
  name: restheart-secrets
type: Opaque
stringData:
  mongo-uri: "mongodb+srv://user:password@cluster.mongodb.net"
  jwt-key: "your-jwt-secret-key"
---
env:
- name: MONGO_URI
  valueFrom:
    secretKeyRef:
      name: restheart-secrets
      key: mongo-uri
- name: RHO
  value: "/mclient/connection-string->env('MONGO_URI')"

AWS Secrets Manager (ECS)：

json
{
  "secrets": [
    {
      "name": "MONGO_URI",
      "valueFrom": "arn:aws:secretsmanager:region:account:secret:mongo-uri"
    }
  ]
}

可用镜像

标签

• latest — 最新稳定版（Eclipse Temurin JRE 25，推荐生产环境使用）
• distroless — 最小化安全加固镜像（Chainguard distroless JRE）
• graalvm — GraalVM JDK，支持多语言插件（JavaScript、Python、TypeScript）
• native — GraalVM 原生编译二进制文件（启动最快，体积最小）
• X.Y.Z — 特定版本标签（如 8.1.0、8.2.0）
• X.Y.Z-distroless、X.Y.Z-graalvm、X.Y.Z-native — 特定版本的变体

镜像变体对比

选择合适的镜像

latest — 适用于大多数生产部署

• 完整 Java 25 JRE，支持虚拟线程
• 优化的 G1GC，适用于高吞吐量 REST API
• 功能与性能的最佳平衡

distroless — 适用于安全关键环境

• 基于 Chainguard 的最小化镜像（无 shell，无包管理器）
• 减少***面和 CVE 暴露
• 适合合规要求严格的组织

graalvm — 当需要多语言插件时使用

• 运行 JavaScript、TypeScript 或 Python 插件
• GraalVM JIT 编译器优化动态语言
• 非 Java 语言自定义业务逻辑的必要选择

native — 适用于资源受限或无服务器部署

• GraalVM 原生镜像（AOT 编译）
• 亚秒级启动时间
• 更低的内存占用（运行时 ~50-100MB）
• 无 JVM 开销
• ⚠️ 插件兼容性有限（仅支持 Java 插件）

使用示例

标准部署：

bash
docker run -p 8080:8080 \
  -e RHO="/mclient/connection-string->'mongodb://mongodb:27017'" \
  docker.xuanyuan.run/softinstigate/restheart:latest

安全加固部署：

bash
docker run -p 8080:8080 \
  -e RHO="/mclient/connection-string->'mongodb://mongodb:27017'" \
  docker.xuanyuan.run/softinstigate/restheart:distroless

带 JavaScript 插件：

bash
docker run -p 8080:8080 \
  -v ./plugins:/opt/restheart/plugins \
  -e RHO="/mclient/connection-string->'mongodb://mongodb:27017'" \
  docker.xuanyuan.run/softinstigate/restheart:graalvm

无服务器/边缘部署：

bash
docker run -p 8080:8080 \
  -e RHO="/mclient/connection-string->'mongodb://mongodb:27017'" \
  docker.xuanyuan.run/softinstigate/restheart:native

各变体的最佳适用场景

native 镜像特别适合：

• AWS Lambda / Google Cloud Run
• 边缘计算和 IoT 网关
• 具有激进自动扩缩容策略的 Kubernetes
• 成本敏感型部署（更低的资源使用）
• 快速冷启动要求（<1 秒）

生产部署清单

安全

• ✅ 生产环境使用特定版本标签，而非 latest
• ✅ 将 MongoDB 凭证存储在密钥管理系统中
• ✅ 启用身份验证（JWT、OAuth2 或 LDAP）
• ✅ 为您的域名适当配置 CORS
• ✅ 使用 TLS/HTTPS（在负载均衡器处终止）
• ✅ 设置基于角色的访问控制（RBAC）

监控

• ✅ 配置健康检查端点（/ping、/metrics）
• ✅ 设置 Prometheus 指标收集
• ✅ 启用结构化日志
• ✅ 监控容器资源使用情况
• ✅ 为 API 错误和延迟设置告警

扩展

• ✅ 配置水平 Pod/任务自动扩缩容
• ✅ 设置适当的资源请求和限制
• ✅ 为 MongoDB 使用连接池
• ✅ 部署多个副本以实现高可用性
• ✅ 测试自动扩缩容触发器和阈值

数据库

• ✅ 使用 MongoDB Atlas 或托管数据库服务
• ✅ 配置副本集以实现高可用性
• ✅ 设置数据库备份
• ✅ 为读密集型工作负载使用只读副本
• ✅ 监控数据库连接池指标

用例

🚀 MongoDB API 网关 — 无需编写后端代码，即时获得 REST/GraphQL API

📱 移动/Web 后端 — 自动生成端点，加速开发

⚡ 微服务 — 轻量级、无状态服务，适合容器编排

🔄 实时应用 — WebSocket 支持，实现实时更新和通知

🏢 MongoDB Data API 替代方案 — 自托管替代已弃用的 Atlas Data API

🌐 多区域部署 — 无状态设计，完美支持全球负载均衡

🧪 原型设计与 MVP — 几分钟内搭建功能完备的后端

功能特性

• REST API — 完整的 CRUD、过滤、排序、分页、聚合功能
• GraphQL API — 自动生成的模式，支持查询、变更和订阅
• WebSocket API — 来自 MongoDB 的实时变更流
• 身份验证 — JWT、OAuth2、LDAP、MongoDB 用户支持
• 授权 — 基于角色的访问控制（RBAC）
• 插件系统 — 支持 Java、JavaScript、Python、TypeScript 扩展（需使用 graalvm 镜像）
• 可观测性 — Prometheus 指标、健康检查、结构化日志

无需编写代码即可实现标准数据库操作。仅在需要自定义业务逻辑时编写插件。

注意： JavaScript、TypeScript 和 Python 插件需要 graalvm 镜像变体。Java 插件适用于所有镜像变体。

示例 API 使用

REST API

bash
# 创建文档
curl -X POST http://localhost:8080/db/collection \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "age": 30}'

# 使用过滤器查询
curl "http://localhost:8080/db/collection?filter={\"age\":{\"\$gt\":25}}"

# 聚合管道
curl -X POST http://localhost:8080/db/collection/_aggrs/pipeline \
  -H "Content-Type: application/json" \
  -d '[{"$group": {"_id": "$status", "count": {"$sum": 1}}}]'

GraphQL API

graphql
query {
  collection(filter: "{'age': {'$gt': 25}}", limit: