Para

面向云端的可扩展多租户后端。

Para 是一个可扩展的多租户后端服务器／框架，用于对象持久化和检索。 它可帮助你处理后端操作，从而更快速地构建应用并制作原型。 它可以作为基于 JVM 的应用程序的一部分，也可以部署为独立的多租户 API 服务，供多个应用程序和客户端连接。

“pára”在保加利亚语中意为“蒸汽”。正如蒸汽可以用来驱动各种设备，你也可以使用 Para 为移动或 Web 应用的后端提供动力。

了解 Para 与其他开源后端框架的比较。

本项目由 Erudika 全额资助并提供支持。这是一家独立的自举公司。

功能

• RESTful JSON API，使用 Amazon 的 Signature V4 算法进行保护
• 与数据库无关，专为可扩展的数据存储设计（DynamoDB、Cassandra、MongoDB 等）
• 全文搜索（Lucene、Elasticsearch）
• 分布式和本地对象缓存（Hazelcast、Caffeine）
• 多租户：每个应用都有自己的表、索引和缓存
• 带签名负载的 Webhook
• 基于 Spring Security 的灵活安全机制（LDAP、SAML、社交登录、CSRF 保护等）
• 使用 JSON Web Tokens（JWT）进行无状态客户端身份验证
• 简单而有效的资源权限，用于客户端访问控制
• 基于 JSR-303 和 Hibernate Validator 的可靠约束验证机制
• 对每个对象分别控制持久化、索引和缓存操作
• 支持乐观锁和事务（由各 DAO 原生实现）
• 高级序列化和反序列化功能（Jackson）
• 提供全面的指标，用于监控和诊断（Dropwizard）
• 由 Google Guice 驱动的模块化设计，并支持插件
• 用于翻译语言包和处理货币的 I18n 工具
• 内嵌 Jetty 的独立可执行 JAR
• HTML 表单处理，提供接受 multipart/form-data 请求的公共端点
• MCP 服务 — 允许 AI Agent 与你的后端交互
• Para Web Console — 管理员用户界面

架构

+----------------------------------------------------------+
|                  ____  ___ _ ____ ___ _                  |
|                 / __ \/ __` / ___/ __` /                 |
|                / /_/ / /_/ / /  / /_/ /                  |
|               / .___/\__,_/_/   \__,_/     +-------------+
|              /_/                           | Persistence |
+-------------------+  +-----------------+   +-------------+
|      REST API     |  |     Search      |---|    Cache    |
+---------+---------+--+--------+--------+---+------+------+
          |                     |                   |
+---------+---------+  +--------+--------+   +------+------+
|  Signed Requests  |  |  Search Index   |   |  Data Store |
|  and JWT Tokens   |  |      (Any)      |   |    (Any)    |
+----+---------^----+  +-----------------+   +-------------+
     |         |
+----v---------+-------------------------------------------+
| Clients: JavaScript, PHP, Java, C#, Android, iOS, et al. |
+----------------------------------------------------------+

文档

阅读文档

博客

在我们的博客上进一步了解 Para

托管

我们在 paraio.com 提供托管和高级支持，你可以通过免费开发者账户在线试用 Para。在 Web 控制台中，只需点击几下，即可浏览和管理用户与对象、备份数据并编辑权限。升级到高级账户后，你可以在几秒内扩展或缩减项目，并管理多个应用。

其他托管提供商

快速入门

1. 下载最新的可执行 JAR
2. 在 JAR 包所在的目录中创建一个配置文件 application.conf。
3. 使用 java -jar -Dconfig.file=./application.conf para-*.jar 启动 Para。
4. 使用 npm install -g para-cli 安装 Para CLI
5. 为你的项目创建一个专用应用，并保存访问密钥：

# run setup and set endpoint to either 'http://localhost:8080' or 'https://paraio.com'
# the keys for the root app are inside application.conf
$ para-cli setup
$ para-cli new-app "myapp" --name "My App"

或者，你可以使用 Para Web Console 管理数据， 也可以通过以下任一 API 客户端将 Para 直接集成到项目中。

Docker

Para 的带标签 Docker 镜像位于 Docker Hub 上的 erudikaltd/para。 强烈建议只拉取 :1.51.0 或 :latest_stable 等发行版镜像， 因为 :latest 标签对应的镜像可能有问题或不稳定。 首先，创建一个 application.conf 文件和一个 data 文件夹，然后启动 Para 容器：

$ touch application.conf && mkdir data
$ docker run -ti -p 8080:8080 --rm -v $(pwd)/data:/para/data \
  -v $(pwd)/application.conf:/para/application.conf \
  -e JAVA_OPTS="-Dconfig.file=/para/application.conf" erudikaltd/para:latest_stable

环境变量

JAVA_OPTS - Java 系统属性，默认为 -Dloader.path=lib

插件

你可以使用 docker compose 创建一个包含所需全部插件和 JDBC 驱动程序的自定义 Para 容器。 下面是一个使用 para-dao-sql、para-search-lucene 和 PostgreSQL 作为数据库来构建 Para 的示例。

1. 首先，创建一个新的 Dockerfile-plugins，并按如下方式进行多阶段构建：

• 查看 Dockerfile-plugins 的内容

  ARG PARA_VERSION="0.0.0"
  ARG SQL_DAO_VERSION="0.0.0"
  FROM erudikaltd/para:v${PARA_VERSION} AS base
  FROM erudikaltd/para-dao-sql:${SQL_DAO_VERSION} AS dao
  FROM erudikaltd/para-search-lucene:${SEARCH_VERSION} AS search
  FROM base AS final
  COPY --from=dao /para/lib/*.jar /para/lib
  COPY --from=search /para/lib/*.jar /para/lib
  
  # EXAMPLE: Add a PostgreSQL JDBC Driver
  ARG PG_JDBC_VERSION="0.0.0"
  ADD https://jdbc.postgresql.org/download/postgresql-${PG_JDBC_VERSION}.jar /para/lib/
  

2. 然后，创建一个 docker-compose.yml 文件：

• 查看 docker-compose.yml 的内容

  services:
     para:
       depends_on:
         - db
       build:
         context: .
         dockerfile: Dockerfile
         args:
           PARA_VERSION: "1.51.0"
           SQL_DAO_VERSION: "1.49.1"
           PG_JDBC_VERSION: "42.7.7"
       image: para-with-plugins
       pull_policy: never
       ports:
         - "8080:8080"
       volumes:
         - type: volume
           source: paraData
           target: /para/data
         - type: volume
           source: paraLib
           target: /para/lib
         - type: bind
           source: ./para-application.conf
           target: /para/application.conf
       restart: always
       environment:
         - JAVA_OPTS=-Dconfig.file=/para/application.conf -Dloader.path=/para/lib
  
     db:
       image: postgres:latest
       ports:
         - "5432:5432"
       volumes:
         - type: volume
           source: postgresData
           target: /var/lib/postgresql/data
       restart: always
       environment:
         - POSTGRES_PASSWORD=mysecretpassword
         - PGDATA=/var/lib/postgresql/data
  volumes:
    paraData:
    paraLib:
    postgresData:
  

3. 另外，创建 Para 配置文件 para-application.conf：

• 查看 para-application.conf 的内容

  para.env = "production"
  para.dao = "SqlDAO"
  para.sql.driver = "org.postgresql.Driver"
  para.sql.url = "postgresql://db:5432/para"
  para.sql.user = "postgres"
  para.sql.password = "mysecretpassword"
  

4. 最后，运行 docker compose build para && docker compose up

Kubernetes

helm/ 文件夹中包含一个 Helm chart。先编辑 helm/para/values.yaml，然后只需一条命令即可将 Para 部署到 Kubernetes：

cd helm; helm install para ./para

更多信息请查看 helm/README.md 中的快速入门指南。

构建 Para

Para 可以使用 JDK 8+ 编译：

编译需要 Maven。安装好之后，克隆并构建即可：

$ git clone https://github.com/erudika/para.git && cd para
$ mvn install -DskipTests=true

要生成可执行的“fat-jar”，运行 $ mvn package，生成的文件位于 ./para-server/target/para-x.y.z-SNAPSHOT.jar。 总共会生成两个 JAR 文件，其中 fat JAR 文件稍大一些。

要构建 Para 的原生镜像，请运行：

$ cd para-server && mvn -Pnative package

请注意，原生镜像依赖平台，因此在 x86-64 上构建的镜像无法在 aarch64 上运行，反之亦然。

要在本地运行 Para 实例以进行开发，请使用：

$ mvn -Dconfig.file=./application.conf spring-boot:run

独立服务端

下载可执行 JAR 文件并运行，或者克隆 Para 仓库后从头构建。 要构建“uber JAR”（fat JAR）文件，需要启用以下 Maven 配置文件：

mvn -Pfatjar,sql,lucene -DskipTests=true package

最后，运行 Para 服务端：

java -jar para-X.Y.Z.jar

然后，你可以通过 Para Web Console console.paraio.org 浏览对象。 只需将 API 端点更改为本地服务端，并连接访问密钥。 管理界面仅在客户端运行，你的密钥绝不会通过网络发送。相反， JWT 访问令牌会在本地生成，并在每次请求时发送到服务端。

下载 JAR

Maven 依赖

你也可以将 Para 添加为依赖项，以便在项目中集成 Para。Para 托管在 Maven Central 上。 以下是添加到 pom.xml 中的 Maven 片段：

<dependency>
  <groupId>com.erudika</groupId>
  <artifactId>para-server</artifactId>
  <version>{see_green_version_badge_above}</version>
</dependency>

如果要构建连接到 Para 的轻量级纯客户端应用程序，只需添加客户端模块：

<dependency>
  <groupId>com.erudika</groupId>
  <artifactId>para-client</artifactId>
  <version>{see_green_version_badge_above}</version>
</dependency>

命令行工具

• Para CLI：para-cli

$ npm install -g para-cli

API 客户端

使用这些客户端库，可以快速将 Para 集成到项目中：

• Java：para-client
• JavaScript / Node.js：para-client-js
• PHP：para-client-php
• Python：para-client-python
• C# / .NET：para-client-csharp
• Android：para-client-android
• Swift / iOS：para-client-ios

数据库集成

使用这些 DAO 实现连接不同的数据库：

• DynamoDB：para-dao-dynamodb
• MongoDB：para-dao-mongodb
• Cassandra：para-dao-cassandra
• SQL（H2/MySQL/SQL Server/PostgreSQL 等）：para-dao-sql H2DAO 是默认的 DAO，属于 SQL 插件的一部分（随 JAR 文件打包）

搜索引擎集成

以下实现了 Search 接口：

• Lucene：para-search-lucene
• Elasticsearch / OpenSearch：para-search-elasticsearch
• Elasticsearch v5.x：para-search-elasticsearch-v5 [DEPRECATED] 仅兼容 ES 5.x，且缺少 AWS Elasticsearch 支持等一些最新功能。

缓存集成

以下实现了 Cache 接口：

• Caffeine：对象缓存在本地（包含在 para-server 中）
• Hazelcast：para-cache-hazelcast（分布式）

队列实现

以下实现了 Queue 接口：

• Amazon SQS：para-queue-sqs，Amazon SQS 插件
• LocalQueue，用于单主机部署和本地开发

文件存储实现

以下实现了 FileStore 接口：

• Amazon S3：para-storage-s3，Amazon S3 插件
• LocalFileStore：用于将文件存储到本地文件系统。

邮件发送器实现

以下实现了 Emailer 接口：

• AWSEmailer：para-email-ses，Amazon SES 插件
• JavaMailEmailer - 用于处理事务邮件的默认 JavaMail 实现

使用 Para 的项目

• Scoold - 一个开源的 Stack Overflow 克隆项目
• ParaIO.com - 托管式 Para 服务
• Erudika.com - 我们网站上的搜索栏和联系表单使用 Para
• Angular 演示应用 - 一个 Angular 示例项目
• React 演示应用 - 一个 React 示例项目

愿望清单 / 路线图

• Para 2.0 - 仅支持 Java 25+，原生镜像
• 更完善的管理 UI

支持

你可以在此提交 issue 获取支持。也可以前往 Gitter 聊天室寻求帮助。 也提供付费 / 优先支持。

获取帮助

• 有问题？- 在 Gitter 上提问
• 发现了 Bug？- 在此提交 Bug 报告
• 在 Stack Overflow 上使用 para 标签提问
• 对 Scoold 有疑问，请在 Stack Overflow 上使用 para 标签

参与贡献

1. Fork 此仓库，并将 Fork 克隆到本地
2. 创建一个分支（git checkout -b my-new-feature）
3. 实现新功能或修复 Bug，并添加一些测试
4. 提交更改（git commit -am 'Added a new feature'）
5. 将分支推送到 GitHub 上的你的 Fork（git push origin my-new-feature）
6. 从你的 Fork 创建新的 Pull Request

请尽量遵循本项目的代码风格。要检查代码，请使用风格检查器运行：

mvn validate

更多信息请参阅 CONTRIBUTING.md

许可证

Apache 2.0