Para 1.57.0 配置参数详解

Para 1.57.0 配置参数体系：application.conf/环境变量/系统属性三级优先级实测，17 组 192 参数分类详解，存储/检索/缓存/安全/分页核心参数，JVM 堆限制与 systemd 托管排障实录。

ParaJavaBaaS全文检索自托管2026/10/24

Para 1.57.0 配置参数详解

目标：讲清 Para 1.57.0 的配置加载机制（application.conf / 环境变量 / 系统属性三级来源与优先级），逐类详解核心参数，并给出可直接复用的场景化配置与排障记录。本文所有优先级与参数行为均在一台 Ubuntu 24.04 服务器上实测验证。

一、环境信息

项目值
操作系统Ubuntu 24.04.3 LTS（真实服务器视角，systemd 托管）
JavaOpenJDK 21.0.12.1（apt 安装 openjdk-21-jdk-headless，Para 1.57.0 基于 Spring Boot 4.1.1，编译目标 Java 21）
Para1.57.0（官方 Releases 发行 JAR，sha256 前缀 af68e52f，发布于 2026-10-09）
部署目录/opt/para
实测日期2026-10-24
默认配置文件application.conf（首次启动后同目录自动生成 para-application.conf 根应用凭据文件）

版本与发布日期核实自官方 releases.atom（查询日期 2026-10-24）。

二、配置体系概览

2.1 三种配置来源与优先级（实测）

Para 基于 Typesafe Config 体系，同一参数可从三个来源设置，优先级从高到低：

  1. JVM 系统属性（java -Dpara.port=8083）；
  2. 环境变量（para_port=8082，命名规则为配置键的 . 换成 _）；
  3. 配置文件 application.conf（用 -Dconfig.file=/opt/para/application.conf 显式指定）。

实测过程（在 /opt/para 下，application.conf 中写 para.port = 8081）：

# 第三级：仅配置文件，监听 8081
java -Dconfig.file=/opt/para/application.conf -jar para-1.57.0.jar
# 第二级：环境变量覆盖配置文件，监听 8082
para_port=8082 java -Dconfig.file=/opt/para/application.conf -jar para-1.57.0.jar
# 第一级：系统属性覆盖一切，监听 8083
para_port=8082 java -Dpara.port=8083 -Dconfig.file=/opt/para/application.conf -jar para-1.57.0.jar

每次启动后用 ls /opt/para/ 观察 pid 文件名验证实际端口：三级实验分别生成 para_8081.pid、para_8082.pid、para_8083.pid，且健康检查 curl http://localhost:<端口>/v1/_health 仅在被监听端口返回 {"message":"healthy"}，其余端口连接拒绝。优先级链实证成立：系统属性 > 环境变量 > 配置文件。

2.2 默认值与首次启动行为

  • 不传任何配置直接 java -jar para-1.57.0.jar 即可启动：内置默认 DAO=H2DAO（内嵌 H2）、Search=LuceneSearch、Cache=CaffeineCache；
  • 1.57.0 默认运行模式为 production：首次启动日志可见 The following 1 profile is active: production（注意：早期官方文档曾写默认 embedded，以实测为准）；
  • 首次启动在 JAR 同目录自动生成 para-application.conf，内容为根应用凭据与豁免端点（其中 para.root_secret_key 为随机生成，务必妥善保管，勿提交到代码库）：
# security.ignored - ignore authentication for these URIs
security.ignored = "/v1/_config/options"

# root app credentials - the 'super' app
para.env = "production"
para.dao = "H2DAO"
para.search = "LuceneSearch"
para.root_access_key = "app:para"
para.root_secret_key = "<首次启动随机生成的密钥>"

2.3 参数总览的两种权威渠道

  • 运行时端点：GET /v1/_config/options（默认豁免鉴权），返回全部 17 组、192 个参数的注册表 JSON，是现场核对参数名的最快方式：
curl -s http://localhost:8080/v1/_config/options | jq 'keys'

返回分组包括：Core、Basic Authentication、Security、River & Queue、Metrics、LDAP Authentication、File Storage、Para Client、Elasticsearch Search、Lucene Search、MongoDB DAO、SQL DAO、Cassandra DAO、AWS DynamoDB DAO、Caffeine Cache、Hazelcast Cache、Miscellaneous。

  • 官方配置参考：https://paraio.org/docs 配置一节含每个参数的默认值与说明（查询日期 2026-10-24）。

三、核心参数详解

3.1 服务器与运行模式

参数默认值说明
para.envproduction运行模式：embedded/development/production，影响各后端默认组合
para.port8080HTTP 端口，改端口实测见 5.1
para.context_path/应用上下文路径，反代统一前缀时使用
para.app_namepara应用 id（appid）与根应用名（根应用为 app:para）
para.worker_id1实例编号，取值 1~128，多节点集群必须各不相同（用于 ID 生成）
para.cluster_namepara集群名
para.print_logotrue启动时打印 ASCII Logo，生产环境可关（实测置 false 后日志直接以 "Starting ParaServer" 开始）
para.print_versiontrue启动时打印版本号
para.pidfile_enabledtrue生成 para_<端口>.pid（实测文件名随端口变化），便于守护脚本
para.api_enabledtrue是否开启 REST API；纯嵌入模式可关
para.executor_threads64线程池大小
para.max_entity_size_bytes1048576单请求 JSON 载荷上限（1MB）

3.2 存储后端（DAO）

参数默认值说明
para.daoH2DAODAO 实现：H2DAO（默认，内嵌 H2，已打包在 JAR 内）/ SqlDAO / DynamoDB / MongoDB / Cassandra（后四者需插件 JAR 放入 lib/）
para.db.dir./dataH2 数据文件目录（实测默认生成 ./data，内含 para.mv.db）
para.sql.urljdbc:h2:file:./data/paraSqlDAO 的 JDBC 连接串，换 MySQL/PostgreSQL 时改这里
para.sql.driverorg.h2.DriverJDBC 驱动类，MySQL 为 com.mysql.cj.jdbc.Driver 等
para.sql.user / para.sql.passwordsa / 空数据库凭据（密码建议用环境变量 para_sql_password 注入）
para.shared_table_namepara多租户共享表名

换存储后端的完整迁移路径（SqlDAO + MySQL 示例配置）：

para.dao = "SqlDAO"
para.sql.url = "jdbc:mysql://localhost:3306/para?useUnicode=true&characterEncoding=utf8"
para.sql.driver = "com.mysql.cj.jdbc.Driver"
para.sql.user = "para"
para.sql.password = "强密码"

切换后首次启动会自动建表；历史数据迁移需配合 para-cli export/import（见本专栏 CLI 篇）。

3.3 检索后端（Search）

参数默认值说明
para.searchLuceneSearch检索实现；多节点集群必须换 ElasticSearch（同时兼容 OpenSearch）
para.lucene.dir./data/luceneLucene 索引目录
para.search_enabledtrue关闭后纯 DAO 模式（无全文检索）
para.sync_index_with_dbtrue启动时以数据库为基准同步索引
para.read_from_indexfalse顶 true 可从索引读数据（库损坏时的应急手段，官方文档标注慎用）
para.reindex_batch_size500_reindex 重建索引的批大小

ES 插件场景（para.search = "ElasticSearch"）常用：para.es.host、para.es.port、para.es.cluster_name、para.es.shards、para.es.replicas、para.es.fail_on_indexing_errors（true 时索引失败向客户端抛异常，可配合回滚重试）。

3.4 缓存（Cache）

参数默认值说明
para.cache_enabledfalse对象缓存开关（production 模式下运行时默认启用）
para.cacheCaffeineCache缓存实现，集群换 HazelcastCache
para.caffeine.evict_after_minutes1440本地缓存过期时间（分钟）
para.caffeine.cache_size10000缓存对象上限

3.5 队列与索引同步（River & Queue）

参数默认值说明
para.qLocalQueue队列实现，可换 SQS 插件
para.default_queue_namepara_default默认队列名
para.webhooks_enabledtrueWebhook 投递开关（依赖队列）
para.max_failed_webhook_attempts5Webhook 失败重试上限
para.river.max_indexing_retries3索引同步失败重试次数
para.indexing_sync_interval_sec60索引同步轮询间隔（秒）

3.6 安全与认证

参数默认值说明
para.root_secret_override空启动时强制覆盖根应用密钥（重置凭据用）
para.request_expires_after900签名请求有效期（秒），防重放
para.jwt_expires_after3600JWT 令牌有效期（秒）
para.jwt_refresh_interval600JWT 刷新窗口（秒）
para.id_token_expires_after60短时效 ID Token（秒）
para.session_timeout3600会话超时（秒）
para.security.csrf_protectiontrueCSRF 防护
para.cors_enabledfalseCORS 支持
para.min_password_length8密码最小长度

3.7 分页与检索行为

参数默认值说明
para.max_items_per_page30默认页长上限（省略 limit 参数时生效）
para.max_page_limit256显式 limit 参数的上限
para.max_pages1000分页页数上限
para.max_datatypes_per_app1024每应用自定义类型上限

⚠️ 实测澄清一个语义：max_items_per_page 只管省略 limit 时的默认页长，不截断显式 limit。实测步骤：先造 62 个 post 对象，再带 para.max_items_per_page = 50 配置启动：

  • GET /v1/posts?q=*（不带 limit）→ 返回 50 条（受配置控制）；
  • GET /v1/posts?q=*&limit=100 → 返回 62 条（未被 50 截断，受 max_page_limit=256 管辖）。

3.8 健康检查与监控

参数默认值说明
para.health_check_enabledtrue开启 /v1/_health 端点与周期自检
para.health.check_interval60自检间隔（秒）
para.metrics_enabledtrueDropwizard 指标采集
para.metrics.jmx_enabledfalseJMX 暴露开关
para.metrics.logging_ratePT15M指标日志输出频率
para.access_log_enabledfalse访问日志开关

四、多应用与文件存储参数

  • para.localstorage.folder：本地文件存储目录（LocalFileStore）；
  • para.localstorage.max_filesize_mb：单文件上限（默认 1MB，需大文件上传时调大并配合反向代理 body 限制）；
  • para.fs：文件存储实现选择（LocalFileStore 默认，S3 需插件 + para.s3.bucket 等参数）；
  • 多应用场景：每个业务 App 的密钥与设置存在根应用的数据里（可通过 CLI app-settings 查看），application.conf 只承载根应用与服务器级配置。

五、场景化配置实操（实测）

5.1 修改端口

三种改法按优先级排列，最小侵入的是配置文件方式：

# 方式一：application.conf
echo 'para.port = 8081' >> /opt/para/application.conf
# 方式二：环境变量
para_port=8081 java -jar para-1.57.0.jar
# 方式三：系统属性
java -Dpara.port=8081 -jar para-1.57.0.jar

验证：curl http://localhost:8081/v1/_health 返回 {"message":"healthy"}，且目录中出现 para_8081.pid。

5.2 JVM 堆内存限制（systemd 托管）

修改位置在 systemd unit 的 Environment= 行，jps -v 验证生效：

# /etc/systemd/system/para.service
[Service]
Environment="JAVA_OPTS=-Xms256m -Xmx512m"
ExecStart=/usr/bin/java $JAVA_OPTS -Dconfig.file=/opt/para/application.conf -jar /opt/para/para-1.57.0.jar

生效证据（实测 jps -v 输出）：

1593 para-1.57.0.jar -Xms256m -Xmx512m -Dconfig.file=/opt/para/application.conf

写法上有两个必踩的坑，见第六章排障实录。

5.3 数据与索引目录外移

mkdir -p /data/para
cat >> /opt/para/application.conf << 'EOF'
para.db.dir = "/data/para/h2"
para.lucene.dir = "/data/para/lucene"
EOF
systemctl restart para

重启后 /data/para/h2/ 下生成 para.mv.db，/data/para/lucene/ 下生成索引段文件。

六、排障实录（均为实测踩坑，含真实报错）

  1. systemd Environment= 值含空格未加引号 → journalctl 告警 Invalid environment assignment, ignoring: -Xmx512m，一半参数被静默丢弃（jps -v 只见 -Xms256m）。修复：Environment="JAVA_OPTS=-Xms256m -Xmx512m"；
  2. systemd ExecStart 用 ${JAVA_OPTS} 花括号引用 → 变量整体作为单个参数传给 java，JVM 报 Invalid initial heap size: -Xms256m -Xmx512m，服务无法启动。修复：改用 $JAVA_OPTS（无花括号，systemd 会按空格分词）；
  3. 启动后约 1 分钟内 /v1/_health 返回 500 {"code":500,"message":"unhealthy"} → 属正常现象：首个健康检查周期（默认 60 秒）尚未完成，等待后自动转为 {"message":"healthy"}，无需重启；
  4. pkill -f para-1.57.0.jar 把自己的 shell 一并杀掉 → pkill -f 匹配的是完整命令行，当前 shell 的命令串里含该字符串。修复：按 pid 文件精确停止 kill $(cat /opt/para/para_8080.pid)；
  5. 显式 limit 不被 max_items_per_page 截断 → 语义见 3.7，想限制最大返回量应调 para.max_page_limit；
  6. 修改 application.conf 不生效 → 检查是否漏传 -Dconfig.file（不传时 Para 读 JAR 同目录的 application.conf；若该文件不存在则全部走默认值），以及环境变量/系统属性是否有更高优先级的同名覆盖。

七、参考链接

  1. Para 官方配置参考：https://paraio.org/docs （配置一节，查询日期 2026-10-24）
  2. GitHub 仓库：https://github.com/Erudika/para
  3. Releases：https://github.com/Erudika/para/releases （1.57.0，2026-10-09）
  4. 站内本组件系列：《Para 1.57.0 介绍与选型指南》、《Ubuntu 24.04 安装 Para 1.57.0 指南》、《Para 1.57.0 常用 CLI 命令与 API 实测详解》

站内相关：《DreamFactory 7.7.1 介绍与选型指南》。