REI3 3.13.1 配置参数详解

目标：完整梳理 REI3 3.13.1 平台核心配置文件 config.json 的全部参数——数据库、Web 服务器、路径、集群与顶层开关，逐项给出官方语义与实测验证，并提供生产配置模板。参数语义来源为官方 Admin 文档（查询日期 2026-10-24），端口修改、目录结构等关键行为已在 Ubuntu 22.04 实测环境验证。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• REI3 版本：3.13.1（实测二进制自报 v3.13.1.7204）
• 数据库：PostgreSQL 16.15（本机 5432）
• 配置文件：/opt/rei3/config.json（与 r3 二进制同目录）
• 服务管理：systemd 单元 rei3.service
• Web 端口：默认 443（HTTPS），本文实测改为 8443 后回改验证
• 参数语义来源：官方 Admin 文档 "Configuration file" 一节（https://rei3.de/en/docs/admin ，查询日期 2026-10-24）

二、前置条件

• 已按 《Ubuntu 22.04 安装 REI3 3.13.1 指南》 完成 REI3 安装并可正常访问；
• 具备服务器 root/sudo 权限，能编辑 /opt/rei3/config.json 并重启 rei3 服务；
• 本文每个示例均可独立执行；修改参数后统一用「重启 + 探活」验证。

三、参数查看与修改方式

REI3 的核心配置只有一个 JSON 文件，位于安装目录（本文为 /opt/rei3/config.json），与官方打包的模板 config_template.json 同目录同结构。查看当前配置：

cat /opt/rei3/config.json

修改规则与生效机制：

1. 直接编辑 JSON 文件，保存后必须重启服务才生效（官方文档：Changes are applied when the application service restarts）；
2. 重启命令：sudo systemctl restart rei3；
3. 验证方式：探活目标端口返回 200 即生效。

下面以最常用的「改 Web 端口」为例做完整闭环实测。先把 web.port 从 443 改为 8443：

cd /opt/rei3
sudo sed -i 's/"port": 443/"port": 8443/' config.json
grep -A3 '"listen"' config.json

                "listen": "0.0.0.0",
                "port": 8443,
                "tlsMinVersion": "1.2"
        }

重启服务并分别探测新旧端口：

sudo systemctl restart rei3
systemctl is-active rei3
curl -sk --noproxy '*' -o /dev/null -w 'port8443_code=%{http_code}\n' https://localhost:8443/
curl -sk --noproxy '*' -o /dev/null -w 'port443_code=%{http_code}\n' https://localhost:443/

active
port8443_code=200
port443_code=000

新端口 8443 返回 200、旧端口 443 已无监听（000），证明端口修改重启后生效。把端口改回 443 并复核：

sudo sed -i 's/"port": 8443/"port": 443/' config.json
sudo systemctl restart rei3
sleep 8
systemctl is-active rei3
curl -sk --noproxy '*' -o /dev/null -w 'port443_restored=%{http_code}\n' https://localhost/

active
port443_restored=200

💡 说明：web.port 设为 0 时，REI3 将由操作系统分配一个随机空闲端口（官方语义），适合一次性测试场景；生产固定端口便于防火墙与反代配置。

四、参数总览

config.json 顶层共 5 个配置块。各键总览（默认值取自官方 config_template.json，实测与之一致）：

顶层开关：

db 参数块（9 键）：

web 参数块（5 键）：

paths 参数块（8 键）：

关键差异解读：Dedicated 部署（外部数据库）只需关心 db、web、paths 中的 files/temp/transfer/certificates；embeddedDbBin/embeddedDbData 仅在 Windows 的 stand-alone 与 portable 模型下有意义，Linux 下保持默认即可。

五、核心参数分类详解

5.1 db：数据库连接参数

REI3 全部平台与应用数据存放于一个 PostgreSQL 数据库（要求 15.0+、UTF8 编码、账号对库全权限）。逐项说明：

• host / port：数据库地址与端口。Dedicated 模式下本机库用 localhost:5432；独立数据库服务器填其 IP 或主机名。官方 Docker 模板即通过把 host 改写为 r3_db 实现容器间寻址。
• name / user / pass：库名、账号与口令。账号需对目标库有完整权限（建表、改结构等），REI3 启动与升级时会自动管理平台所需的表结构。官方建议的建库 SQL 模式见安装指南 4.2 节。
• embedded：true 时 REI3 启动自带的内嵌 PostgreSQL（stand-alone 与 portable 模型的行为）；Dedicated 模式必须为 false。Linux 官方包没有内嵌库形态，保持 false。
• ssl：与数据库之间启用 SSL 加密传输，前提是 PostgreSQL 端配置了 SSL（默认 ssl=on 的 PG 实例即可）。内网同机部署通常保持 false。
• sslSkipVerify：ssl 开启时跳过对数据库证书的校验。官方语义明确"允许连接证书不可信的加密数据库，一般不推荐"——仅建议在自签证书的内网库上使用。
• connsMin / connsMax：连接池保持的最小/最大连接数，0 表示由平台自动决定。connsMax 的典型用途是 REI3 与其他系统共享同一数据库服务器时的连接数限流；官方同时提醒 REI3 自身至少需要 4 个连接。

💡 技术拓展：应用与 PostgreSQL 的连接管理常见三种取向——

取向	代表	特点
应用内连接池	REI3（connsMin/connsMax）	配置简单，池随应用生命周期
外置连接池中间件	PgBouncer	多应用共享池，支持更大并发
数据库侧限流	max_connections + 角色 连接限额	兜底保护，粒度粗

REI3 采用应用内连接池；只有当多个 REI3 节点或多个系统挤压数据库连接时，才需要考虑外置 PgBouncer。

5.2 web：Web 服务器参数

REI3 内嵌 Web 服务器，HTTPS 与 WebSocket 共用一个端口。逐项说明：

• cert / key：证书与私钥的文件名（相对于 paths.certificates 目录）。文件不存在时，HTTPS 模式启动会自动生成自签名证书（实测首次启动生成了 cert.crt/cert.key，见安装指南 4.6 节）。REI3 会自动检测并加载证书文件更新，支持 Let's Encrypt 等自动续期证书。
• listen：监听地址，0.0.0.0 表示对所有网卡地址提供服务（官方语义）；仅内网网卡服务时可改为对应 IP。
• port：监听端口，默认 443；设 0 由 OS 分配。修改实测见第三章（8443 生效、443 停止监听）。
• tlsMinVersion：客户端可接受的最低 TLS 版本，允许值 "1.1"、"1.2"、"1.3"。默认 1.2 兼顾老客户端；纯内网现代浏览器环境可收紧到 1.3。

💡 技术拓展：TLS 版本取舍一览——

版本	现状	建议
TLS 1.1 及以下	已被主流浏览器弃用	仅兼容极老内网系统时开启
TLS 1.2	当前兼容性基线	默认值，通用场景保持
TLS 1.3	更快握手、更强套件	全内网现代环境可收紧到此

REI3 默认 tlsMinVersion: "1.2"，本文实测未改动。

证书排障要点（官方 Admin 文档 "SSL certificates" 一节）：证书域名需与客户端访问主机名一致（端口无关）；内网部署时证书文件需含到受信根的完整链；证书无法加载时 REI3 将启动失败并写 syslog（Linux 为 journal/syslog）。

5.3 paths：数据路径参数

安装包自带的数据目录结构（实测 find /opt/rei3/data -maxdepth 2 回显）：

/opt/rei3/data
/opt/rei3/data/certificates
/opt/rei3/data/certificates/cert.crt
/opt/rei3/data/certificates/cert.key
/opt/rei3/data/files
/opt/rei3/data/temp
/opt/rei3/data/transfer

逐项说明：

• certificates：Web 证书目录，web.cert/web.key 指定的文件名在此目录下解析。
• files：应用「文件类型属性」上传文件的存储目录；官方说明其内容由平台定时任务清理（引用删除或保留期满足后）。
• fileExport / fileImport：REI3 应用做文件导入/导出时使用的服务器目录，默认空（不启用）；启用后平台只能在这两个目录做导入导出（官方安全设计：限制文件交换范围）。集群部署时这些目录需所有节点可见（通常挂网络共享）。
• temp：CSV 上传、应用导入等操作的临时文件目录，内容由定时任务定期清理。
• transfer：应用安装/更新包的上传暂存目录；保留安装包是为了支持后续导出依赖（官方语义）。
• embeddedDbBin / embeddedDbData：内嵌 PostgreSQL 的程序与数据目录，仅 stand-alone（Windows）与 portable 模型使用；Dedicated 模式保持默认即可。

⚠️ 注意：备份 REI3 实例时，除数据库外还需备份 config.json 与 certificates/files/transfer 三个目录（官方 Backup and recovery 一节给出的完整清单）。

5.4 cluster：集群参数

• nodeId：本节点在集群中的标识，不应手工填写。新节点把该值留空接入共享数据库后，平台自动注册节点并分配唯一 nodeId 存储。集群扩容流程：新服务器按安装指南完成部署 → config.json 指向同一数据库与同一文件存储路径 → 启动即自动入列；集群主角色与任务由平台自动分配（官方 Clustering 一节语义）。客户端 WebSocket 会话建立后需粘滞在所属节点，重连时可被任意节点接管。

5.5 顶层开关：mirror 与 portable

• mirror：镜像模式。true 时禁用所有写出型连接器（当前为邮件与 REST）以及内建备份。设计目的：用生产数据复制出的测试/开发实例不外发邮件、不调用外部 API、不产生备份干扰。本文实测环境保持 false。
• portable：便携模式，仅与 Windows 便携版相关：true 时以 HTTP 模式启动并自动打开浏览器跳转首页。服务器部署保持 false。

六、生产配置模板

以下模板适用于「16GB 内存、NVMe SSD、100 用户以内的部门级业务系统、独立 PostgreSQL 16 实例」场景；相对默认值的变化仅 3 处，均有依据（官方语义），其余保持官方默认：

{
        "cluster": {
                "nodeId": ""
        },
        "db": {
                "embedded": false,
                "host": "10.20.0.11",
                "port": 5432,
                "name": "app",
                "user": "app",
                "pass": "q1w2e3r4",
                "ssl": false,
                "sslSkipVerify": false,
                "connsMax": 20,
                "connsMin": 4
        },
        "mirror": false,
        "paths": {
                "certificates": "data/certificates/",
                "embeddedDbBin": "pgsql18/bin/",
                "embeddedDbData": "data/database/",
                "files": "data/files/",
                "fileExport": "",
                "fileImport": "",
                "temp": "data/temp/",
                "transfer": "data/transfer"
        },
        "portable": false,
        "web": {
                "cert": "cert.crt",
                "key": "cert.key",
                "listen": "0.0.0.0",
                "port": 443,
                "tlsMinVersion": "1.2"
        }
}

取值解读：

• db.host=10.20.0.11：数据库独立部署时的典型取值（示例内网 IP），本机库则回 localhost；
• db.connsMax=20、db.connsMin=4：官方说明平台自身至少需要 4 个连接，min 取下限 4 保证就绪；100 用户规模 20 个连接上限已足够，且为共享数据库服务器留出余量；
• web.tlsMinVersion="1.2"：保持官方默认的兼容基线；
• pass 请替换为生产强密码；证书文件替换为正式证书后无需改这里（文件名不变时）。

💡 说明：节点扩容（集群第二台服务器）时直接复用本模板——db 指向同一库、paths 指向同一共享存储、cluster.nodeId 留空即可，无需其他集群配置。

七、常见问题（FAQ）

Q1：改了 config.json 不生效？ 配置仅在服务重启后加载：sudo systemctl restart rei3 后再验证（见第三章实测闭环）。

Q2：数据库连接失败如何排查？ 按官方建库要求核对四点：库编码是否 UTF8、账号是否对库有全权限、db.host/port 是否可达、PostgreSQL 15+ 版本要求；可用 psql -h <host> -p <port> -U <user> -d <name> 手工验证连通性。

Q3：换成正式证书后服务起不来？ 见 5.2 节证书排障要点：域名匹配、证书链完整、journal/syslog 看具体加载错误；文件名与 web.cert/web.key 不一致时需同步修改。

Q4：测试实例会不会给真实用户发邮件、调外部接口？ 把测试实例的 mirror 设为 true，邮件与 REST 连接器及内建备份即被禁用（见 5.5 节）。

Q5：第二台服务器加入集群还需要改什么？ db 指向同一数据库、paths 各目录指向同一存储位置（网络共享）、cluster.nodeId 留空，启动后自动注册节点并分配任务（见 5.4 节）。

八、参考链接

• 官方 Admin 文档（Configuration / Configuration file 章节）：https://rei3.de/en/docs/admin
• 官方下载页与安装包：https://rei3.de/en/downloads
• 官方 Docker 仓库（Compose 模板中 config 改写示例）：https://github.com/r3-team/r3_docker
• 本专栏系列：《REI3 3.13.1 介绍与选型指南》、《Ubuntu 22.04 安装 REI3 3.13.1 指南》、《REI3 3.13.1 常用 CLI 命令与工具详解》