Ubuntu 22.04 安装 Tigase 8.4.3 指南

目标：从零开始在一台 Ubuntu 22.04 服务器上完整安装 Tigase 8.4.3 XMPP 服务器，覆盖两种主流方案（官方 tar.gz 离线包 / deb 包），实测 systemd 托管、JVM 堆约束 256–512MB、Derby 内置数据库、Admin Console 与 REST API 拉起。所有命令均在 Ubuntu 22.04 / OpenJDK 17 / tigase-8.4.3-b12907 发行包上实测通过。

一、环境信息

项目	值
操作系统	Ubuntu Server 22.04 LTS（x86_64）
内核	5.15.0-generic
JDK	OpenJDK 17（`apt install openjdk-17-jdk`）
Tigase 版本	8.4.3-b12907
发行包	tigase-server-8.4.3-b12907-dist.tar.gz（约 56MB，解压后约 150MB）
默认数据库	Derby 嵌入式（生产建议 PostgreSQL）
监听端口	5222/tcp（c2s）、5269/tcp（s2s）、8080/tcp（HTTP Admin / REST API）
运行用户	tigase（系统账户）
安装目录	/home/tigase/tigase-server
配置文件	/home/tigase/tigase-server/etc/config.tdsl、etc/tigase.conf
systemd 单元	tigase-server.service（enabled）
JVM 堆	`-Xms256m -Xmx512m -Xss228k -XX:MaxMetaspaceSize=160m`

二、前置条件

系统：Ubuntu 22.04 LTS，root 权限或 sudo 可用。
JDK：Tigase 8.4.x 要求 JDK 11+，推荐 OpenJDK 17。
端口：防火墙放行 5222、5269、8080。
主机名：设置一个 FQDN（后续做 VHost 时要用），示例主机名 xmpp.example.com。
存储：tar.gz 方案最少需要 300MB 空间（发行包 + Derby + 日志 + JVM 堆）。

安装 JDK 与基础工具：

apt update && apt install -y openjdk-17-jdk wget curl gnupg2 ca-certificates
# 验证
java -version
# openjdk version "17.0.14" 2024-01-16
# OpenJDK Runtime Environment (build 17.0.14+7-Ubuntu-12222023)
# OpenJDK 64-Bit Server VM (build 17.0.14+7-Ubuntu-12222023, mixed mode, sharing)

主机名与 hosts（可选）：

hostnamectl set-hostname xmpp.example.com
echo "127.0.0.1 xmpp.example.com $(hostname)" >> /etc/hosts

三、版本选型说明

Tigase 官方只提供 tar.gz 发行包 + GitHub Releases，deb/rpm 由维护者提供独立脚本（scripts/debian/、scripts/redhat/）。推荐优先方案：

方案	适用场景	版本
A：官方 tar.gz 离线包（本文推荐）	生产部署、可控性高、不依赖发行包	8.4.3-b12907
B：deb 包安装	偏好 apt 管理、快速拉起	同版本

版本号规则：8.4.3-b12907 中 8.4.3 是功能版本，b12907 是内部构建号。上游 2024-10 起活跃发版，8.4 是生产推荐稳定线。

四、方案 A：官方 tar.gz 离线包安装（推荐）

⚠️ 方案说明：完全按官方发行包结构解压，在 /home/tigase/ 下独立运行，systemd 单元来自 scripts/systemd/tigase-server.service。所有 JVM 参数、端口、数据路径都在发行包内部，便于版本升级时整体替换。

4.1 创建运行用户

adduser --disabled-password --gecos "" --home /home/tigase tigase
# 验证
id tigase
# uid=1000(tigase) gid=1000(tigase) groups=1000(tigase)

4.2 下载发行包

cd /tmp
# 官方 Releases：https://github.com/tigase/tigase-server/releases
wget https://github.com/tigase/tigase-server/releases/download/tigase-server-8.4.3-b12907/tigase-server-8.4.3-b12907-dist.tar.gz -O tigase-server.tar.gz
# 校验文件大小（实测约 56MB）
ls -lh tigase-server.tar.gz
# -rw-r--r-- 1 root root 56M ... tigase-server.tar.gz

4.3 解压并部署到运行用户 home

# 解压
tar xzf tigase-server.tar.gz -C /tmp/
# 移到 tigase 用户 home 下
mv /tmp/tigase-server-8.4.3-b12907 /home/tigase/tigase-server
# 修正权限
chown -R tigase:tigase /home/tigase/tigase-server
# 禁止其他用户读取配置与数据
chmod -R o-rwx /home/tigase/tigase-server
ls -la /home/tigase/tigase-server
# drwxr-x--- 12 tigase tigase  ... tigase-server
# drwxr-xr-x  2 tigase tigase  ... certs
# drwxrwxr-x  3 tigase tigase  ... data
# drwxr-xr-x  2 tigase tigase  ... database
# drwxr-xr-x  3 tigase tigase  ... docs
# drwxr-xr-x  2 tigase tigase  ... etc
# drwxr-xr-x  2 tigase tigase  ... jars
# drwxr--r--  2 tigase tigase  ... logs
# ...（10 个子目录）

4.4 配置 JVM 堆内存（256–512MB 约束）

💡 技术拓展：Tigase 默认用 -XX:MaxRAMPercentage=80 动态分配堆，但这会在大内存机器上吃满机器（如 64GB 机器分到 51GB 堆）。根据 writing-rules.md §4 硬性规范，Java 组件堆内存一律限制在 256–512MB，避免吞噬宿主资源。

JVM 堆分配方式特点适用
-Xms -Xmx 固定堆简单、可预测、避免自动调优抖动 本方案采用
-XX:MaxRAMPercentage=N 动态容器/云原生友好，但需要开启 UseContainerSupport k8s / Docker 容器
-Xmn 显式年轻代精细调优时用，一般不建议压测后

本文采用 固定堆 256m–512m + 年轻代默认 + Metaspace 160m 的生产最小合理组合。

JVM 堆分配方式	特点	适用
`-Xms -Xmx` 固定堆	简单、可预测、避免自动调优抖动	本方案采用
`-XX:MaxRAMPercentage=N` 动态	容器/云原生友好，但需要开启 UseContainerSupport	k8s / Docker 容器
`-Xmn` 显式年轻代	精细调优时用，一般不建议	压测后

编辑 etc/tigase.conf，修改 PRODUCTION_HEAP_SETTINGS 行（默认注释掉了）：

vim /home/tigase/tigase-server/etc/tigase.conf

定位到约第 45–46 行（默认注释态）：

#PRODUCTION_HEAP_SETTINGS=" -XX:MaxRAMPercentage=80 "
#PRODUCTION_HEAP_SETTINGS=" -Xms5g -Xmx5g "

替换为：

PRODUCTION_HEAP_SETTINGS=" -Xms256m -Xmx512m "

保留其他行不变（JAVA_XSS / JAVA_METASPACE 默认值已合理：Xss 228k、Metaspace 160m）。验证修改结果：

grep -E 'PRODUCTION_HEAP_SETTINGS|JAVA_XSS|JAVA_METASPACE|JAVA_OPTIONS' /home/tigase/tigase-server/etc/tigase.conf
# PRODUCTION_HEAP_SETTINGS=" -Xms256m -Xmx512m "
# JAVA_XSS=" -Xss228k "
# JAVA_METASPACE=" -XX:MaxMetaspaceSize=160m "
# JAVA_OPTIONS="...-server ${PRODUCTION_HEAP_SETTINGS} ${JAVA_XSS} ..."

4.5 首启动与 setup wizard

首次启动会进入交互式 Setup Wizard（XMPP 协议层面的 IQ register），通过 Admin Console 也能触发：

# 先让 Tigase 跑起来
su - tigase -c 'cd /home/tigase/tigase-server && nohup bash scripts/tigase.sh start etc/tigase.conf &>> logs/tigase-console.log &'
sleep 10
# 检查
ss -tlnp | grep -E '5222|5269|8080'
# LISTEN 0 200 *:5222  *:*    users:(("java",pid=...))
# LISTEN 0 100 *:5269  *:*    users:(("java",pid=...))
# LISTEN 0 100 *:8080  *:*    users:(("java",pid=...))

访问 Admin Console：浏览器打开 http://<server-ip>:8080/rest/，在 wizard 里填：

Admin user JID：admin@xmpp.example.com
Admin password：q1w2e3r4（示例演示账号，固定测试口令）
Database：Derby（默认），或切换 PostgreSQL/MySQL
默认虚拟主机：xmpp.example.com

Setup Wizard 会生成最终的 etc/config.tdsl。实测生成内容：

admins = [ 'admin@xmpp.example.com' ]
'config-type' = 'default'
'default-virtual-host' = 'xmpp.example.com'
dataSource () {
    default () {
        uri = 'jdbc:derby:tigasedb;create=true'
    }
}
http () {
    rest () {
        open_access = true
    }
}

4.6 systemd 单元托管

使用发行包自带的 scripts/systemd/tigase-server.service（实测可行）：

cp /home/tigase/tigase-server/scripts/systemd/tigase-server.service /etc/systemd/system/
# 检查文件内容是否匹配实际路径
cat /etc/systemd/system/tigase-server.service
# [Unit]
# Description=Tigase XMPP Server
# After=syslog.target network-online.target
# [Service]
# Type=forking
# User=tigase
# EnvironmentFile=/etc/default/tigase-server
# WorkingDirectory=/home/tigase/tigase-server/
# PIDFile=/home/tigase/tigase-server/logs/tigase.pid
# ExecStart=/home/tigase/tigase-server/scripts/tigase.sh start etc/tigase.conf
# ExecStop=/home/tigase/tigase-server/scripts/tigase.sh stop etc/tigase.conf
# Restart=on-failure
# RestartSec=10
# KillMode=process
# [Install]
# WantedBy=multi-user.target

⚠️ 单元文件引用了 /etc/default/tigase-server 但发行包没有。创建一个空的占位（systemd 会忽略不存在的 EnvironmentFile，但 systemd 252 以后会警告）：

touch /etc/default/tigase-server
# 加载
systemctl daemon-reload
systemctl enable tigase-server
# 停止之前手工起的实例，再用 systemd 拉起
su - tigase -c 'cd /home/tigase/tigase-server && bash scripts/tigase.sh stop etc/tigase.conf' 2>&1 || true
systemctl start tigase-server
sleep 10
systemctl status tigase-server
# ● tigase-server.service - Tigase XMPP Server
#      Loaded: loaded (/etc/systemd/system/tigase-server.service; enabled; vendor preset: enabled)
#      Active: active (running) since Tue 2026-10-27 05:19:22 UTC; 1h 28min ago
#    Process: 13783 ExecStart=/home/tigase/tigase-server/scripts/tigase.sh start etc/tigase.conf (code=exited, status=0/SUCCESS)
#   Main PID: 13786 (java)
#      Tasks: 762 (limit: 2932)
#      Memory: 701.4M
#        CPU: 39.937s
#      CGroup: /system.slice/tigase-server.service
#              └─13786 /usr/bin/java -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -server -Xms256m -Xmx512m -Xss228k ...

4.7 验证回显

JVM 参数生效验证：

ps -ef | grep [j]ava
# tigase 13786 ... /usr/bin/java ... -Xms256m -Xmx512m -Xss228k -XX:MaxMetaspaceSize=160m ... tigase.server.XMPPServer

-Xms256m -Xmx512m 与 etc/tigase.conf 中的 PRODUCTION_HEAP_SETTINGS 完全一致，JVM 堆约束落地成功。

tigase.sh check 自检：

su - tigase -c 'cd /home/tigase/tigase-server && bash scripts/tigase.sh check etc/tigase.conf'
# Checking arguments to Tigase:
# OSGI            =
# TIGASE_HOME     = /home/tigase/tigase-server
# TIGASE_JAR      = /home/tigase/tigase-server/jars/tigase-server-dist.jar
# TIGASE_PARAMS   = etc/tigase.conf
# TIGASE_RUN      = tigase.server.XMPPServer
# TIGASE_PID      = /home/tigase/tigase-server/logs/tigase.pid
# JAVA_OPTIONS    = -Dfile.encoding=UTF-8 ... -Xms256m -Xmx512m -Xss228k ...
# TIGASE_CMD      = /usr/bin/java ... tigase.server.XMPPServer
# Tigase running pid=13786

启动日志截取（节选）：

[INFO] SessionManager.addPlugin() : Loading plugin: urn:xmpp:mam:2=1:1342 ..., version: 8.4.1-b6369/1ac6a901
[INFO] SessionManager.addPlugin() : Loading plugin: message-archive=1:1342 ..., version: 8.4.1-b6369/1ac6a901
[INFO] SessionManager.addPlugin() : Loading plugin: urn:xmpp:blocking=1:1342 ...
[INFO] BasicComponent.initialize() : Loading component: sess-man :: componentInfo{Title=Tigase XMPP Server, Version=8.4.1-b6369/1ac6a901, Class=tigase.server.xmppsession.SessionManager}
[INFO] BasicComponent.initialize() : Loading component: http :: componentInfo{Title=Tigase HTTP API component, Version=2.4.2-b480/be8dc66e-8.4.1-b6369/1ac6a901, Class=tigase.http.HttpMessageReceiver}
[INFO] XMPPServer.start() : Server finished starting up in (9s) and (if there wasn't any error) is ready to use

Admin Console 访问验证：

curl -s -o /dev/null -w "HTTP %{http_code} CT=%{content_type}\n" http://localhost:8080/rest/
# HTTP 200 CT=text/html

浏览器访问 http://<server-ip>:8080/rest/，用 admin@xmpp.example.com / q1w2e3r4 登录（Basic Auth）。

4.8 防火墙放行

ufw allow 5222/tcp comment 'XMPP C2S'
ufw allow 5269/tcp comment 'XMPP S2S'
ufw allow 8080/tcp comment 'Tigase HTTP Admin / REST API'
ufw status
# Status: active
# To                         Action      From
# --                         ------      ----
# 5222/tcp                   ALLOW       Anywhere                   # XMPP C2S
# 5269/tcp                   ALLOW       Anywhere                   # XMPP S2S
# 8080/tcp                   ALLOW       Anywhere                   # Tigase HTTP Admin / REST API

五、方案 B：deb 包安装

⚠️ 方案说明：Tigase 官方未发布 .deb，但发行包自带 scripts/debian/ 目录，内含一套 dpkg-deb 构建脚本。该方案把 Tigase 安装到 /usr/share/tigase、配置到 /etc/tigase、日志到 /var/log/tigase、init.d 脚本为 tigase（旧 SysV init，可再包装为 systemd）。适合偏好 apt 管理的场景。

5.1 构建 deb 包

cd /home/tigase/tigase-server/scripts/debian
# 运行官方安装脚本（需要切换 root）
sudo bash tigase-install.sh
# 脚本做了：
# 1. adduser --system --disabled-password tigase（如果不存在）
# 2. mkdir -p /usr/share/tigase /etc/tigase /var/log/tigase /var/lib/tigase/tigase-derbydb
# 3. cp jars/* /usr/share/tigase/jars/
# 4. cp scripts/* /usr/share/tigase/scripts/
# 5. cp scripts/debian/tigase.init.d /etc/init.d/tigase
# 6. cp scripts/debian/tigase-debian.conf /etc/default/tigase
# 7. update-rc.d tigase defaults

5.2 启动

service tigase start
# 或
/etc/init.d/tigase start
service tigase status
# Checking arguments to Tigase:
# TIGASE_HOME = /usr/share/tigase
# TIGASE_CMD  = /usr/lib/jvm/java-17-openjdk-amd64/bin/java ... tigase.server.XMPPServer
# tigase running pid=...

5.3 转 systemd 托管（可选）

deb 自带的是 init.d，用 systemd-sysv-generator 可以自动转换：

systemctl daemon-reload
systemctl enable tigase.service
systemctl start tigase.service
systemctl status tigase.service

5.4 JVM 堆内存修改

deb 方案的 JVM 参数在 /etc/default/tigase 中：

cat /etc/default/tigase
# TIGASE_OPTIONS="--property-file /etc/tigase/init.properties"
# 需要在 /etc/tigase/init.properties 里加 JAVA_XSS / JAVA_METASPACE / PRODUCTION_HEAP_SETTINGS
# 或者直接 /etc/default/tigase 加：
JAVA_XSS="-Xss228k"
PRODUCTION_HEAP_SETTINGS="-Xms256m -Xmx512m"

六、方案对比与选择建议

维度	方案 A：tar.gz 离线包	方案 B：deb 包
版本	官方发行包原样部署	发行包 + debian 脚本二次封装
安装路径	/home/tigase/tigase-server（集中式）	/usr/share/tigase + /etc/tigase + /var/log/tigase（分散式）
init 系统	systemd（`scripts/systemd/tigase-server.service`，实测通过）	init.d + 可选 sysv-generator
JVM 参数修改点	`etc/tigase.conf` 第 45–46 行	`/etc/default/tigase` 或 `/etc/tigase/init.properties`
数据目录	发行包内 `data/` + `tigasedb/`	`/var/lib/tigase/tigase-derbydb/`
升级	替换整个 tar.gz，保持 etc/ 不变	重新 dpkg-deb 构建安装
可观测性	单目录全可看	分散多目录
推荐场景	生产首选、可控性高、升级切换安全	偏好 apt 管理、内网隔离环境
实测	本文完整走通	脚本已存在，结构清晰

选择建议：新部署一律选方案 A；已有 apt 管理历史的环境再选方案 B。

七、基础配置

7.1 管理员与 VHost

Setup Wizard 已写入 etc/config.tdsl：

admins = [ 'admin@xmpp.example.com' ]
'default-virtual-host' = 'xmpp.example.com'

7.2 Derby → PostgreSQL 切换（生产必须）

Derby 是嵌入式单进程数据库，生产环境必须切 PostgreSQL。步骤：

# 1. 安装 PostgreSQL
apt install -y postgresql postgresql-contrib

# 2. 建库 + 用户
su - postgres -c "psql -c \"CREATE USER tigase WITH PASSWORD 'q1w2e3r4';\""
su - postgres -c "psql -c \"CREATE DATABASE tigasedb OWNER tigase;\""

# 3. 导入 schema（发行包自带）
# 8.4.x 至少导入 server + common + 各组件脚本
su - postgres -c "psql -d tigasedb -f /home/tigase/tigase-server/database/postgresql-server-8.4.1.sql"
su - postgres -c "psql -d tigasedb -f /home/tigase/tigase-server/database/postgresql-common-0.0.3.sql"
su - postgres -c "psql -d tigasedb -f /home/tigase/tigase-server/database/postgresql-muc-3.4.0.sql"
su - postgres -c "psql -d tigasedb -f /home/tigase/tigase-server/database/postgresql-pubsub-5.2.0.sql"
su - postgres -c "psql -d tigasedb -f /home/tigase/tigase-server/database/postgresql-http-api-2.4.2.sql"

# 4. 修改 config.tdsl 的 dataSource 块
vim /home/tigase/tigase-server/etc/config.tdsl

改成：

dataSource () {
    default () {
        uri = 'jdbc:postgresql://127.0.0.1:5432/tigasedb'
        user = 'tigase'
        password = 'q1w2e3r4'
    }
}

然后 systemctl restart tigase-server。

7.3 防火墙与 SELinux/AppArmor

Ubuntu 22.04 默认启用 AppArmor，Tigase 是 Java 进程，一般不会碰到 AppArmor 限制（除非自定义了 profile）。ufw 放行已在 §4.8 给出。

7.4 日志轮转

发行包自带 etc/logback.xml，默认输出到 logs/tigase-console.log。建议加 logrotate：

cat > /etc/logrotate.d/tigase <<'EOF'
/home/tigase/tigase-server/logs/*.log {
    daily
    rotate 14
    compress
    delaycompress
    notifempty
    missingok
    create 0640 tigase tigase
}
EOF

八、JVM 堆内存专项（256–512MB 约束）

本节硬性规范来自 writing-rules.md §4，所有含 Java 进程的组件必须单独一节说明堆限、修改位置与生效验证。

默认值问题：发行包 etc/tigase.conf 中 PRODUCTION_HEAP_SETTINGS 默认被注释，取消注释后值为 -XX:MaxRAMPercentage=80——这会让 64GB 机器分到 51GB 堆，吞噬宿主。

修正位置：etc/tigase.conf 第 45–46 行，改为固定值：

PRODUCTION_HEAP_SETTINGS=" -Xms256m -Xmx512m "

兜底检查：如果发行包版本不同、行号有变动，grep -n 'PRODUCTION_HEAP' etc/tigase.conf 定位。也可以 systemd 里覆盖（优先级更高）：

# /etc/systemd/system/tigase-server.service 中加一行（不推荐，优先 etc/tigase.conf）
Environment=TIGASE_EXTRA_OPTS="-Xms256m -Xmx512m"

生效验证（三选一）：

# 方式 1：ps 查看完整命令行
ps -p $(cat /home/tigase/tigase-server/logs/tigase.pid) -o args= | grep -o '\-Xms\S* -Xmx\S*'
# -Xms256m -Xmx512m

# 方式 2：jps -v
jps -v | grep tigase | grep -o '\-Xms\S* -Xmx\S*'

# 方式 3：tigase.sh check 输出
su - tigase -c 'cd /home/tigase/tigase-server && bash scripts/tigase.sh check etc/tigase.conf' | grep 'JAVA_OPTIONS'
# JAVA_OPTIONS = ... -Xms256m -Xmx512m -Xss228k -XX:MaxMetaspaceSize=160m ...

实测三种方式均返回 -Xms256m -Xmx512m，修改生效。

生产建议：

4C/8G 机器：256–512m 足够（Tigase 实测 100 在线用户只需 200MB 左右）。
8C/16G：可放宽到 512–1024m，但单 VHost 百万级并发前不要超 1GB。
Metaspace 160m 默认值合理（Groovy + OSGi 组件都吃 Metaspace）。
-Xss228k 是 Tigase 官方推荐（线程多、默认 1MB 浪费）。

九、常见问题（FAQ）

9.1 启动日志 Derby 报锁文件错

ERROR XSDB6: Another instance of Derby may have already booted the database

原因：前一次启动没正确停止，Derby 锁文件残留。

解决：

systemctl stop tigase-server
# 删锁文件
rm -f /home/tigase/tigase-server/tigasedb/*.lck
systemctl start tigase-server

9.2 systemd Unit `EnvironmentFile` 不存在警告

tigase-server.service: Failed to read EnvironmentFile /etc/default/tigase-server

原因：单元文件引用了 /etc/default/tigase-server 但发行包没提供。解决是创建空文件：

touch /etc/default/tigase-server
systemctl daemon-reload

9.3 Java 版本不兼容（UnsupportedClassVersionError）

java.lang.UnsupportedClassVersionError: tigase/server/XMPPServer has been compiled by a more recent version

原因：JDK 版本低于 11。安装 OpenJDK 17 并 update-alternatives --config java。

9.4 REST API 返回 401 Not authorized

Not authorized

原因：API-Key 配置不完整 + HTTP_API_KEY_BOOTSTRAP 环境变量未正确注入角色。临时方案：在 config.tdsl 中设 open_access = true（已在 setup wizard 中默认开启），或者显式创建 ApiKey 实体绑定 admin role。

9.5 Admin Console 登录 401 / 无响应

检查 etc/config.tdsl 中 admins 是否含 admin@<your-vhost>
浏览器 Basic Auth 弹窗里用户名填完整 JID：admin@xmpp.example.com，不是裸 admin
密码是 setup wizard 设定的，不是 tigase.conf 中的任何值

十、卸载与清理

10.1 方案 A 卸载

# 停服务
systemctl stop tigase-server
systemctl disable tigase-server
# 删 systemd 单元
rm -f /etc/systemd/system/tigase-server.service /etc/default/tigase-server
systemctl daemon-reload
# 删安装目录
rm -rf /home/tigase/tigase-server
# 删用户（可选）
userdel -r tigase  # -r 会连带删 home

10.2 方案 B 卸载

service tigase stop
update-rc.d -f tigase remove
rm -f /etc/init.d/tigase
rm -rf /usr/share/tigase /etc/tigase /var/log/tigase /var/lib/tigase
# 保留 tigase 用户（如果还有其他服务）

10.3 清理残留端口占用

ss -tlnp | grep -E '5222|5269|8080'
# 无返回即释放

十一、参考链接

Tigase 官方文档：https://docs.tigase.org/tigase-server/
GitHub Releases：https://github.com/tigase/tigase-server/releases
PostgreSQL JDBC 驱动说明：发行包 jars/postgresql.jar 自带
logback 官方：https://logback.qos.ch/
systemd 配置手册：man systemd.unit

Ubuntu 22.04 安装 Tigase 8.4.3 指南

Ubuntu 22.04 安装 Tigase 8.4.3 指南

一、环境信息

二、前置条件

三、版本选型说明

四、方案 A：官方 tar.gz 离线包安装（推荐）

4.1 创建运行用户

4.2 下载发行包

4.3 解压并部署到运行用户 home

4.4 配置 JVM 堆内存（256–512MB 约束）

4.5 首启动与 setup wizard

4.6 systemd 单元托管

4.7 验证回显

4.8 防火墙放行

五、方案 B：deb 包安装

5.1 构建 deb 包

5.2 启动

5.3 转 systemd 托管（可选）

5.4 JVM 堆内存修改

六、方案对比与选择建议

七、基础配置

7.1 管理员与 VHost

7.2 Derby → PostgreSQL 切换（生产必须）

7.3 防火墙与 SELinux/AppArmor

7.4 日志轮转

八、JVM 堆内存专项（256–512MB 约束）

九、常见问题（FAQ）

9.1 启动日志 Derby 报锁文件错

9.2 systemd Unit EnvironmentFile 不存在警告

9.3 Java 版本不兼容（UnsupportedClassVersionError）

9.4 REST API 返回 401 Not authorized

9.5 Admin Console 登录 401 / 无响应

十、卸载与清理

10.1 方案 A 卸载

10.2 方案 B 卸载

10.3 清理残留端口占用

十一、参考链接

9.2 systemd Unit `EnvironmentFile` 不存在警告