Ubuntu 22.04 安装 REI3 3.13.1 指南

目标：在 Ubuntu 22.04 服务器上从零安装 REI3 3.13.1 低代码业务应用平台，主推官方推荐的裸机部署方案（PostgreSQL 16 + 官方 tar.gz 二进制 + systemd 托管，即官方 Dedicated 模式），并给出官方 Docker Compose 备选方案。已完成安装、服务注册、故障修复与 HTTPS 访问的全流程实测。

一、环境信息

本指南所述命令与回显均在以下环境实测通过：

操作系统：Ubuntu 22.04.5 LTS（x86_64，PRETTY_NAME="Ubuntu 22.04.5 LTS"）
REI3 版本：3.13.1（官方包 REI3_3.13.1_x64_linux.tar.gz，实测二进制自报版本 v3.13.1.7204）
数据库：PostgreSQL 16.15（pgdg 官方 APT 源）
安装目录：/opt/rei3/
Web 端口：443（HTTPS，首次启动自动生成自签名证书）
数据库实例：实例名 app、角色 app、密码 q1w2e3r4（本文演示值，生产请替换为强密码）
管理演示账号：root / q1w2e3r4（通过 r3 -newadmin 创建）
可选依赖：ImageMagick 6.9.11（缩略图）、Ghostscript 9.55（PDF 缩略图）、postgresql-client（集成备份）

二、前置条件

开始安装前，请确认目标服务器满足以下条件（硬件要求来源：官方 Admin 文档 Technical requirements，查询日期 2026-10-24）：

操作系统：Linux（官方在 Debian、NixOS、Ubuntu Server 上验证过）、x64 或 ARM64 架构。
硬件：内存 4GB 起步；磁盘 REI3 本体约 500MB，数据库与上传文件建议预留 20GB 以上并随业务增长扩容。
数据库：PostgreSQL 15.0 或更新版本，UTF8 编码，REI3 数据库账号对库有完整权限（方案 A 中直接安装 16）。
网络：默认监听 443 端口，防火墙需放行；仅内网使用时按需放行对应网段。
可选软件：
- ImageMagick：生成图片缩略图（sudo apt install imagemagick）；
- Ghostscript：生成 PDF 缩略图（许可原因官方不随包分发）；
- postgresql-client：启用平台内建备份功能。

三、版本选型说明

REI3 官方下载页（https://rei3.de/en/downloads ，查询日期 2026-10-24）提供的 Linux 安装形态是预编译 tar.gz 包，下载 URL 遵循固定模式：

https://rei3.de/downloads/REI3_<版本>_<架构>_linux.tar.gz

2026-10-24 实查可用的 Linux 版本与对应包名：

版本	发布时间	x64 包名	arm64 包名
3.13.1（最新）	2026-10-20	REI3_3.13.1_x64_linux.tar.gz	REI3_3.13.1_arm64_linux.tar.gz
3.13	2026-10-13	REI3_3.13_x64_linux.tar.gz	REI3_3.13_arm64_linux.tar.gz
3.12.8	2026-08-19	REI3_3.12.8_x64_linux.tar.gz	REI3_3.12.8_arm64_linux.tar.gz
3.11.10	—	REI3_3.11.10_x64_linux.tar.gz	REI3_3.11.10_arm64_linux.tar.gz

💡 技术拓展：自托管软件的版本选型常见三种策略——

策略做法取舍
追最新稳定每次大版本发布后短观察期即升级功能最全，但需紧跟升级
锁补丁线锁定大版本只跟 x.y.z 补丁稳定与修复兼顾，本文采用
跨版本保守严重落后几个大版本升级链长，数据库迁移风险累积

REI3 数据库结构随版本演进且不可自动降级，建议采用「锁补丁线」：装 3.13.1 后跟进 3.13.x 补丁，跨大版本前完整备份演练。

策略	做法	取舍
追最新稳定	每次大版本发布后短观察期即升级	功能最全，但需紧跟升级
锁补丁线	锁定大版本只跟 x.y.z 补丁	稳定与修复兼顾，本文采用
跨版本保守	严重落后几个大版本	升级链长，数据库迁移风险累积

本文实测所用 3.13.1 x64 包的 SHA-256 校验值（实测）：

7bd3cb53f374bc67aa6a8cff763e7188b472e25212033c1d379f280492748661  REI3_3.13.1_x64_linux.tar.gz

⚠️ 注意：REI3 升级后数据库无法自动降级（官方文档明确说明），每次升级前务必完成完整备份。

四、方案 A：官方 tar.gz 安装（Dedicated 模式，生产推荐）

本方案即官方推荐的 Dedicated 部署模型：REI3 程序安装在应用服务器本地，数据存放在独立的 PostgreSQL 数据库中。全流程实测通过，步骤如下。

4.1 安装 PostgreSQL 16

REI3 要求 PostgreSQL 15+，Ubuntu 22.04 官方源自带的 PostgreSQL 版本较旧，这里添加 PostgreSQL 官方 APT 源（pgdg）后安装 16：

sudo apt update
sudo apt install -y curl ca-certificates gnupg lsb-release
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt jammy-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt update
sudo apt install -y postgresql-16 imagemagick ghostscript postgresql-client

同时安装的三个可选包：imagemagick（图片缩略图）、ghostscript（PDF 缩略图）、postgresql-client（平台内建备份依赖）。

安装完成后确认集群状态（实测回显）：

pg_lsclusters

Ver Cluster Port Status Owner    Data directory              Log file
16  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

⚠️ 排障实录：若 pg_lsclusters 输出为空（表头都没有集群行），通常是安装过程中 dpkg 配置阶段被中断所致。处理方式：sudo dpkg --configure -a 补完配置，postgres 用户与 16/main 集群会随之建立，随后 sudo systemctl start postgresql 启动。实测中执行 dpkg --configure -a 后回显出现 performing post-bootstrap initialization ... ok，pg_lsclusters 即可看到 online 状态。

4.2 初始化 REI3 数据库

REI3 需要一个 UTF8 编码、且账号对其拥有完整权限的数据库（官方 Admin 文档 "Preparing a new PostgreSQL database" 一节给出的 SQL 模式，本文将演示口令落地）。先创建专用角色：

sudo su - postgres -c "psql -c \"CREATE ROLE app WITH LOGIN PASSWORD 'q1w2e3r4';\""

CREATE ROLE

再创建 UTF8 编码的数据库并指定属主：

sudo su - postgres -c "psql -c \"CREATE DATABASE app WITH OWNER = app TEMPLATE = template0 ENCODING = 'UTF8';\""

CREATE DATABASE

核对编码与属主（实测回显）：

sudo su - postgres -c "psql -c '\l app'"

                                           List of databases
 Name | Owner | Encoding | Locale Provider | Collate | Ctype  | Locale | ICU Rules | Access privileges
------+-------+----------+-----------------+---------+--------+--------+-----------+-------------------
 app  | app   | UTF8     | libc            | C.UTF-8 | C.UTF-8 |        |           |
(1 row)

💡 说明：TEMPLATE = template0 保证新库编码可显式指定为 UTF8，避免继承系统 locale 导致的编码不符；REI3 对数据库的唯一硬性要求就是 UTF8 与全权限。

4.3 下载并部署 REI3 程序

下载官方包并校验（校验值为本文实测值）：

cd /tmp
wget https://rei3.de/downloads/REI3_3.13.1_x64_linux.tar.gz
sha256sum REI3_3.13.1_x64_linux.tar.gz

7bd3cb53f374bc67aa6a8cff763e7188b472e25212033c1d379f280492748661  REI3_3.13.1_x64_linux.tar.gz

解压到安装目录 /opt/rei3/ 并赋予执行权限（实测回显）：

sudo mkdir -p /opt/rei3
sudo tar -xzf REI3_3.13.1_x64_linux.tar.gz -C /opt/rei3
cd /opt/rei3
sudo chmod u+x r3
ls -la /opt/rei3

total 168556
drwxr-xr-x 3 root root      4096 Oct 24 04:10 .
drwxr-xr-x 4 root root      4096 Oct 24 04:10 ..
-rw-rw-rw- 1 root root     10347 Oct 20 11:28 LICENSE.Apache-2.0
-rw-rw-rw- 1 root root      1287 Oct 20 11:28 LICENSE.BSD-2
-rw-rw-rw- 1 root root     32193 Oct 20 11:28 LICENSE.GPL-3.0
-rw-rw-rw- 1 root root       698 Oct 20 11:28 LICENSE.ISC
-rw-rw-rw- 1 root root      1026 Oct 20 11:28 LICENSE.MIT
-rw-rw-rw- 1 root root      4415 Oct 20 11:28 LICENSE.md
-rw-rw-rw- 1 root root      3670 Oct 20 11:28 README.txt
-rw-r--r-- 1 root root       675 Oct 24 04:10 config.json
-rw-rw-rw- 1 root root       675 Oct 20 11:28 config_template.json
drwxr-xr-x 6 root root      4096 Oct 24 04:10 data
-rwxrw-rw- 1 root root 172507296 Oct 20 11:29 r3

包内容：单文件二进制 r3（约 165MB）、配置模板 config_template.json、四个数据子目录（data/certificates、data/files、data/temp、data/transfer）以及多份开源许可证文件。

4.4 配置 config.json

从模板复制正式配置文件，并把数据库口令改为 4.2 中创建的值：

cd /opt/rei3
sudo cp config_template.json config.json
sudo sed -i 's/"pass": "app"/"pass": "q1w2e3r4"/' config.json
cat config.json

实测配置全文：

{
        "cluster": {
                "nodeId": ""
        },
        "db": {
                "embedded": false,
                "host": "localhost",
                "port": 5432,
                "name": "app",
                "user": "app",
                "pass": "q1w2e3r4",
                "ssl": false,
                "sslSkipVerify": false,
                "connsMax": 0,
                "connsMin": 0
        },
        "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.pass 改为实际口令。其余键保持默认即可跑通——db.host=localhost、db.port=5432、db.name=app、db.user=app 正好对应 4.2 创建的数据库；web.port=443 是默认 HTTPS 端口。全部参数的逐项解释见本专栏《REI3 3.13.1 配置参数详解》。

4.5 注册 systemd 服务

用官方参数注册系统服务（实测回显）：

cd /opt/rei3
sudo ./r3 -install

I: 04:10:41 service was successfully installed

确认服务单元已生成并随机启动（实测回显）：

systemctl list-unit-files | grep -i rei3

rei3.service                           enabled         enabled

⚠️ 排障实录（重要）：r3 -install 生成的服务单元 ExecStart=/opt/rei3/r3 不带 -run 参数，而 r3 不带参数只会打印参数表后立即退出（退出码 0），表现为 systemctl start rei3 后服务长期停留在 activating (auto-restart)，systemctl status rei3 显示 Process: ... ExecStart=/opt/rei3/r3 (code=exited, status=0/SUCCESS)，journal 中出现 rei3.service: Deactivated successfully.。定位方法：直接手动执行 /opt/rei3/r3，可见其输出 "Available parameters" 参数表与版本横幅（This is the executable of REI3, the open low-code platform, v3.13.1.7204）后等待回车退出。修复方法——把 ExecStart 补上 -run 并重载：

sudo sed -i 's|ExecStart=/opt/rei3/r3$|ExecStart=/opt/rei3/r3 -run|' /etc/systemd/system/rei3.service
sudo systemctl daemon-reload

修复后的单元关键内容（实测）：

[Unit]
Description=Provides the REI3 platform components
ConditionFileIsExecutable=/opt/rei3/r3

[Service]
StartLimitInterval=5
StartLimitBurst=10
ExecStart=/opt/rei3/r3 -run
Restart=always
RestartSec=120
EnvironmentFile=-/etc/sysconfig/rei3

[Install]
WantedBy=multi-user.target

⚠️ 注意两点：其一，每次执行 r3 -uninstall 后再 -install 会重新生成不带 -run 的单元，需重新执行上述修复；其二，单元内 RestartSec=120 表示异常退出后 2 分钟才重启，排障时不要误以为服务"还没反应"。

4.6 启动服务并验证

启动并确认状态（实测回显）：

sudo systemctl start rei3
systemctl is-active rei3

active

验证 HTTPS 服务与首次访问（自签名证书用 -k 忽略校验，实测回显）：

curl -sk -I https://localhost/

HTTP/2 200
accept-ranges: bytes
content-security-policy: default-src 'self'; connect-src 'self' *; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors *; frame-src *
content-type: text/html; charset=utf-8
referrer-policy: strict-origin-when-cross-origin
x-content-type-options: nosniff

确认首次启动自动生成了自签名证书（实测回显）：

ls -la /opt/rei3/data/certificates/

total 16
drwxr-xr-x 2 root root 4096 Oct 24 04:12 .
drwxr-xr-x 5 root root 4096 Oct 24 04:10 ..
-rw-r--r-- 1 root root  631 Oct 24 04:12 cert.crt
-rw------- 1 root root  227 Oct 24 04:12 cert.key

浏览器访问 https://<服务器IP>/，默认账号与密码均为 admin，登录后应立即在右上角用户设置中修改密码（本文演示环境将管理口令设为 q1w2e3r4）。

4.7 创建备用管理员（防丢失访问）

官方 README 提供命令行创建管理员的方式：先停服务，再以 -newadmin 用户名:口令 运行一次（实测回显）：

sudo systemctl stop rei3
cd /opt/rei3
sudo ./r3 -newadmin root:q1w2e3r4

I: 04:17:02 successfully created new admin user
Shutting down...

重新启动服务后即可用 root / q1w2e3r4 登录：

sudo systemctl start rei3
systemctl is-active rei3

active

⚠️ 注意：-newadmin 创建的用户名不能与已有用户重复，且口令不能包含空格或冒号（来自官方参数表 -newadmin 说明）。

4.8 开机自启

r3 -install 已把单元放入 multi-user.target.wants（list-unit-files 显示 enabled），无需额外操作。可用如下命令复核（实测回显）：

systemctl is-enabled rei3

enabled

五、方案 B：Docker Compose 部署（开发/测试定位）

本章面向已使用容器化基础设施的环境。官方明确声明其 Docker 发布「为开发与测试目的设计，请勿直接用于生产运行 REI3」（来源：官方 Docker 仓库 r3-team/r3_docker README，查询日期 2026-10-24）；生产环境请优先采用方案 A，或基于官方文件自行改造后使用。

官方提供现成的 Compose 文件（x64/arm64 两种架构，从 https://rei3.de/docker_x64 直接下载），包含两个服务：postgres:16 数据库服务与现场构建的 r3:<版本> 应用服务。以下为本文实测使用的改造版（与官方文件的差异：显式 Compose 项目名、固定容器名、端口映射改为宿主 8133、显式网络子网避免网段冲突）：

name: rei3-3.13.1-stack

services:
    r3_db:
        container_name: rei3-3.13.1-db
        environment:
            POSTGRES_DB: ${R3_DB_NAME:-app}
            POSTGRES_USER: ${R3_DB_USER:-app}
            POSTGRES_PASSWORD: ${R3_DB_PASS:-app}
        image: postgres:16
        restart: always
        volumes:
            - data_db:/var/lib/postgresql/data
        networks:
            - rei3-net
    r3:
        build:
            context: https://github.com/r3-team/r3_docker.git#main
            args:
                r3_version: ${R3_VERSION:-3.13.1}
                r3_db_host: r3_db
                r3_db_name: ${R3_DB_NAME:-app}
                r3_db_user: ${R3_DB_USER:-app}
                r3_db_pass: ${R3_DB_PASS:-app}
                r3_os_arch: x64
                im_policy: /etc/ImageMagick-6/policy.xml
        container_name: rei3-3.13.1-app
        image: r3:${R3_VERSION:-3.13.1}
        depends_on:
            - r3_db
        ports:
            - "8133:80"
        pull_policy: never
        restart: always
        volumes:
            - data_app:/opt/r3/data
        networks:
            - rei3-net
networks:
    rei3-net:
        driver: bridge
        ipam:
            config:
                - subnet: 10.89.61.0/24
volumes:
    data_db:
    data_app:

要点解读：

应用服务以官方 Dockerfile 现场 build（context 直接指向官方 GitHub 仓库），构建过程基于 Ubuntu 25.04 基础镜像安装 ImageMagick、Ghostscript、postgresql-client，并把 config 模板中的数据库主机/库名/账号改写为环境变量传入的值，Web 端口由 443 改为 80（容器内明文 HTTP，由外部决定是否加 TLS）；
im_policy 指向 ImageMagick 策略文件，构建时自动把 PDF 从禁用改为读写，从而启用 PDF 缩略图；
数据持久化通过命名卷 data_db（数据库）与 data_app（REI3 文件与配置目录）实现，升级重建服务不丢数据；
版本切换/升级：导出 R3_VERSION=<目标版本> 后重新 docker compose up -d 即可，官方不支持跨版本降级。

部署命令（在保存上述文件的目录执行）：

docker compose up -d --build

构建完成后查看服务状态（实测回显）：

docker compose ps

NAME               IMAGE         COMMAND                  SERVICE   CREATED              STATUS              PORTS
rei3-3.13.1-app    r3:3.13.1     "/opt/r3/r3 -run -ht…"   r3        About a minute ago   Up About a minute   0.0.0.0:8133->80/tcp, [::]:8133->80/tcp
rei3-3.13.1-db     postgres:16   "docker-entrypoint.s…"   r3_db     About a minute ago   Up About a minute   5432/tcp

观察应用日志出现 Starting web server 即就绪（实测回显）：

docker logs rei3-3.13.1-app 2>&1 | tail -2

Starting web server for '0.0.0.0:80'...

浏览器访问 http://<宿主机IP>:8133/，默认账号密码均为 admin（实测 HTTP 探活返回 200）。

官方 Compose 支持的环境变量（来源：官方 r3_docker README，查询日期 2026-10-24）：

变量	默认值	作用
R3_VERSION	3.13.1	指定运行的 REI3 版本（用于升级或部署旧版）
R3_DB_NAME	app	PostgreSQL 库名
R3_DB_USER	app	PostgreSQL 角色
R3_DB_PASS	app	PostgreSQL 口令

六、方案对比与选择建议

维度	方案 A：tar.gz + systemd	方案 B：Docker Compose
官方定位	生产推荐（Dedicated 模型）	开发/测试（官方明确不建议生产直接用）
依赖	PostgreSQL 15+（本机或远端）、可选 ImageMagick/Ghostscript	Docker 与 Compose 插件
需要联网	安装时下载官方包	构建时拉基础镜像与官方包
服务管理	systemd（开机自启、日志进 journal）	Compose 托管
TLS	内建 HTTPS 443 + 自签/正式证书	容器内 HTTP，需外部反代加 TLS
升级	停服覆盖二进制后重启	改 R3_VERSION 重新 up
适合谁	单机生产、内网稳定运行业务	已有容器平台、快速搭建测试实例

选择建议：生产环境用方案 A；仅做功能评估、应用开发测试或已有统一容器管理平台时用方案 B。

七、配置说明

配置文件位置：/opt/rei3/config.json（与 r3 二进制同目录）；修改后需 systemctl restart rei3 生效（官方文档明确"改动在服务重启后应用"）。
证书替换：把正式证书与私钥放到 data/certificates/ 目录（默认文件名 cert.crt/cert.key，可在 web.cert/web.key 改名），REI3 会自动检测并加载更新的证书文件，支持 Let's Encrypt 等短期自动续期证书；证书域名需与客户端访问主机名一致，否则服务可能无法启动并写 syslog。
PDF 缩略图：Ubuntu 22.04 的 ImageMagick 默认在 /etc/ImageMagick-6/policy.xml 第 97 行禁用 PDF（实测存在 <policy domain="coder" rights="none" pattern="PDF" />），需按官方 Dockerfile 的做法把该行改为 rights="read|write" 并重启服务；Ghostscript 本体已装即可。
多节点集群：在另一台服务器重复方案 A 安装，config.json 指向同一数据库、paths 指向同一存储（官方建议网络共享），cluster.nodeId 留空，节点连上即自动注册（详见《REI3 3.13.1 配置参数详解》集群参数一节）。

八、常见问题（FAQ）

Q1：systemctl start rei3 后状态一直是 activating (auto-restart)，服务起不来？ 官方 -install 生成的单元 ExecStart 缺少 -run 参数所致，完整排障与修复见 4.5 节；卸载重装后问题会复现，需重新修复。

Q2：安装 PostgreSQL 后 pg_lsclusters 没有任何集群？ dpkg 配置阶段被中断所致，执行 sudo dpkg --configure -a 补完配置即可，详见 4.1 节排障实录。

Q3：忘记管理员密码怎么办？ 停服务后用 sudo ./r3 -newadmin 新用户名:新口令 创建一个新管理员（用户名不能与现有用户重复），再正常启动并用新账号登录，详见 4.7 节。

Q4：替换正式证书后服务无法启动？ 按官方文档排查三点：证书域名是否与客户端访问的主机名一致；证书文件链是否完整（内网部署时 *.crt 需包含到受信根的完整链）；加载失败的详细原因写入了 syslog（journalctl -u rei3 或 /var/log/syslog）。

Q5：经过 Nginx/负载均衡反代后频繁掉线？ REI3 客户端与服务器通过 WebSocket 长连接交换数据，反代的请求超时/会话上限会强制断开连接导致客户端丢失未保存改动；官方要求对 WebSocket 禁用超时或设置为数小时以上，集群场景下 WebSocket 会话需粘滞在所属节点。

九、卸载与清理

停服务并卸载服务单元（实测回显）：

cd /opt/rei3
sudo ./r3 -uninstall

I: 04:17:12 service was successfully uninstalled

确认单元已移除（实测回显）：

systemctl list-unit-files | grep -i rei3

（无输出，表示已无 rei3 相关单元）

删除程序与数据目录：

sudo rm -rf /opt/rei3

如需一并清掉数据库（谨慎操作，数据不可恢复）：

sudo su - postgres -c "psql -c 'DROP DATABASE IF EXISTS app;'"
sudo su - postgres -c "psql -c 'DROP ROLE IF EXISTS app;'"

DROP DATABASE
DROP ROLE

可选清理：不再使用 PostgreSQL 时执行 sudo apt purge postgresql-16 && sudo apt autoremove。

十、参考链接

官方 Admin 文档（安装章节）：https://rei3.de/en/docs/admin
官方下载页：https://rei3.de/en/downloads
官方 Docker 辅助仓库：https://github.com/r3-team/r3_docker
PostgreSQL 官方 APT 源说明：https://www.postgresql.org/download/linux/ubuntu/
本专栏系列：《REI3 3.13.1 介绍与选型指南》、《REI3 3.13.1 配置参数详解》、《REI3 3.13.1 常用 CLI 命令与工具详解》