Apache OpenMeetings 9.1.0 常用 CLI 命令与工具详解

目标：梳理 Apache OpenMeetings 9.1.0 的命令行管理与运维工具，逐条给出实测命令与真实回显。环境：Ubuntu 22.04.5 LTS，JDK 21.0.12.1，OpenMeetings 9.1.0（安装路径 /opt/apache-openmeetings-9.1.0，下称 $OM_HOME，内嵌 Tomcat 11.0.23）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
安装路径：$OM_HOME=/opt/apache-openmeetings-9.1.0
管理工具：$OM_HOME/admin.sh（org.apache.openmeetings.cli.Admin）
Tomcat 脚本：$OM_HOME/bin/（startup.sh、shutdown.sh、catalina.sh、version.sh、configtest.sh、digest.sh、ciphers.sh）
网络测试脚本：$OM_HOME/network_test.sh
systemd 单元：/etc/systemd/system/openmeetings.service（服务名 openmeetings）
管理账号：admin（示例口令 Q1w2e3r4!）

二、工具概览

工具	路径	用途
admin.sh -i	$OM_HOME/admin.sh	初始化数据库与默认管理员
admin.sh -b	$OM_HOME/admin.sh	备份（数据+文件 → zip）
admin.sh -r	$OM_HOME/admin.sh	从备份恢复
admin.sh -l	$OM_HOME/admin.sh	从 LDAP 导入用户
admin.sh -f	$OM_HOME/admin.sh	文件统计/清理
startup.sh / shutdown.sh	$OM_HOME/bin/	启动/停止服务
catalina.sh run/start/stop	$OM_HOME/bin/	前台/后台启停（catalina 全子命令）
version.sh	$OM_HOME/bin/	打印版本与 JVM 信息
configtest.sh	$OM_HOME/bin/	配置校验
digest.sh	$OM_HOME/bin/	生成 Tomcat 口令摘要
network_test.sh	$OM_HOME/	双端带宽/抖动测试（需 iperf）
systemctl	系统	openmeetings 服务托管

三、前置条件

JDK 21（java -version 确认；admin.sh 会打印 Picked up JDK_JAVA_OPTIONS 提示，属正常输出）。
管理命令（-i/-b/-r/-l/-f）访问内嵌 H2 数据库，必须在服务停止状态执行，否则报数据库文件被锁（见 5.2 节排障）。
systemd 管理命令需 root。

四、工具详解

4.1 admin.sh 帮助与通用选项

查看帮助：

cd /opt/apache-openmeetings-9.1.0
./admin.sh -h

回显（完整 55 行帮助，核心部分）：

 usage:  admin [-h|-b|-r|-l|-i|-f] [options]

 Please specify one of the required parameters.

               Option                                                       Description
 -v,--verbose                      verbose error messages
 ----------------------------------------------------------------------------------------------------
 -h,--help                         prints this message
 ----------------------------------------------------------------------------------------------------
 -b,--backup                       Backups OM
    -file <arg>                    (optional) file used for backup/restore/install
       --exclude-files             (optional) should backup exclude files [default: include]
 ----------------------------------------------------------------------------------------------------
 -r,--restore                      Restores OM
    -file <arg>                    file used for backup/restore/install
 ----------------------------------------------------------------------------------------------------
 -l,--ldap                         Import LDAP users into DB
    -d,--domain-id <arg>           LDAP domain Id
       --print-only                (optional) Print users found instead of importing
 ----------------------------------------------------------------------------------------------------
 -i,--install                      Fill DB table, and make OM usable
    -file <arg>                    file used for backup/restore/install
    -user <arg>                    Login name of the default user, minimum 4 characters (mutually exclusive with 'file')
    -email <arg>                   Email of the default user (mutually exclusive with 'file')
    -group <arg>                   The name of the default user group (mutually exclusive with 'file')
    -tz <arg>                      Default server time zone, and time zone for the selected user (mutually exclusive with 'file')
       --password <arg>            (optional) Password of the default user, minimum 8 characters (will be prompted if not set)
       --system-email-address <arg>(optional) System e-mail address [default: noreply@openmeetings.apache.org]
       --smtp-server <arg>         (optional) SMTP server for outgoing e-mails [default: localhost]
       --smtp-port <arg>           (optional) SMTP server for outgoing e-mails [default: 25]
       --email-auth-user <arg>     (optional) Email auth username (anonymous connection will be used if not set)
       --email-auth-pass <arg>     (optional) Email auth password (anonymous connection will be used if not set)
       --email-use-tls             (optional) Is secure e-mail connection [default: no]
       --skip-default-objects      (optional) Do not create default rooms and OAuth servers [created by default]
       --disable-frontend-register (optional) Do not allow front end register [allowed by default]
       --default-language <arg>    (optional) Default system language as int [1 by default]
       --db-type <arg>             (optional) The type of the DB to be used
       --db-host <arg>             (optional) DNS name or IP address of database
       --db-port <arg>             (optional) Database port
       --db-name <arg>             (optional) The name of Openmeetings database
       --db-user <arg>             (optional) User with write access to the DB specified
       --db-pass <arg>             (optional) Password of the user with write access to the DB specified
       --drop                      (optional) Drop database before installation
       --force                     (optional) Install without checking the existence of old data in the database.
 ----------------------------------------------------------------------------------------------------
 -f,--files                        File operations - statictics/cleanup
       --cleanup                   (optional) Should intermediate files be clean up
 ----------------------------------------------------------------------------------------------------

 Examples:
    ./admin.sh -b
    ./admin.sh -i -v -file backup_31_07_2012_12_07_51.zip --drop
    ./admin.sh -i -v -user admin -email someemail@gmail.com -tz "Asia/Tehran" -group "yourgroup"
    --db-type mysql --db-host localhost

💡 说明：-v,--verbose 用于打印完整错误堆栈，排障时建议带上（如 ./admin.sh -i -v ...）。

4.2 admin.sh -i 安装初始化

初始化数据库、创建默认管理员、默认房间与 OAuth 服务器（服务停止状态执行）：

cd /opt/apache-openmeetings-9.1.0
./admin.sh -i -user admin -email admin@example.com -tz "Asia/Shanghai" -group "admin" --password "Q1w2e3r4!"

回显关键行（命令 exit=0）：

20:xx:xx INFO org.apache.openmeetings.util.OmFileHelper -- Using file locations - omHome: /opt/apache-openmeetings-9.1.0/webapps/openmeetings DATA_DIR: /opt/apache-openmeetings-9.1.0/webapps/openmeetings/data
20:xx:xx INFO org.springframework.orm.jpa.LocalEntityManagerFactoryBean -- Initialized JPA EntityManagerFactory for persistence unit 'openmeetings'
20:xx:xx INFO org.quartz.core.QuartzScheduler -- Scheduler org.springframework.scheduling.quartz.SchedulerFactoryBean#0_$_NON_CLUSTERED started.
INFO: Loading 'hazelcast.xml' from the classpath.
... Done

常用变体：

# 从备份包初始化（迁移场景，等价于恢复安装）
./admin.sh -i -file backup_2026_10_11_19_46_34.zip --drop

# 指定外部数据库初始化
./admin.sh -i -user admin -email admin@example.com -tz "Asia/Shanghai" -group "admin" --password "Q1w2e3r4!" \
  --db-type mysql --db-host 192.168.1.100 --db-port 3306 --db-name openmeetings \
  --db-user om --db-pass 'Om@2026#db'

# 不创建默认房间与 OAuth 服务器
./admin.sh -i -user admin -email admin@example.com -tz "Asia/Shanghai" -group "admin" --password "Q1w2e3r4!" --skip-default-objects

--password 须满足强度校验（大写+小写+数字+特殊符号，≥8 位），否则阻塞提示 Please enter password for the user 'admin': 等待交互输入。
-user 最少 4 字符，与 -file 互斥。

4.3 admin.sh -b 备份

cd /opt/apache-openmeetings-9.1.0
./admin.sh -b

回显：

20:xx:xx INFO org.apache.openmeetings.cli.Admin -- File name was not specified, 'backup_2026_10_11_19_46_34.zip' will be used
... Done

产物：$OM_HOME/backup_2026_10_11_19_46_34.zip（实测 14,429 字节），包含数据库快照与数据文件。

指定文件名 / 排除文件：

./admin.sh -b -file openmeetings-20261011.zip
./admin.sh -b --exclude-files

4.4 admin.sh -r 恢复

cd /opt/apache-openmeetings-9.1.0
./admin.sh -r -file backup_2026_10_11_19_46_34.zip

执行完成 exit=0（恢复后启动服务并验证登录）：

systemctl start openmeetings
curl -s -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'user=admin&pass=Q1w2e3r4%21' \
  http://127.0.0.1:5080/openmeetings/services/user/login

回显（恢复后原账号直接可用）：

{"serviceResult":{"message":"41c93036-1582-408f-ab5f-a25c8e7490f9","type":"SUCCESS"}}

4.5 admin.sh -l LDAP 导入

从已配置的 LDAP 域导入用户（-d 为域 ID，--print-only 只打印不导入）：

cd /opt/apache-openmeetings-9.1.0
./admin.sh -l --print-only -d 1

未配置 LDAP 域时的真实回显（exit=1，提示域不存在）：

org.apache.openmeetings.util.OmException: java.lang.NullPointerException: Cannot invoke "org.apache.openmeetings.db.entity.server.LdapConfig.getConfigFileName()" because "this.ldapCfg" is null
        at org.apache.openmeetings.core.ldap.LdapLoginManager.importUsers(LdapLoginManager.java:318)
        at org.apache.openmeetings.cli.Admin.processLdap(Admin.java:387)

⚠️ 前置说明：执行前需先在管理员后台配置 LDAP 域（OAuth/LDAP 设置，生成 om_ldap.cfg），否则报上述空指针错误。

4.6 admin.sh -f 文件操作

统计（不带参数，服务停止状态）：

cd /opt/apache-openmeetings-9.1.0
./admin.sh -f

统计 + 清理（--cleanup 删除中间文件）：

./admin.sh -f --cleanup

回显（实测，--cleanup 尾部）：

Upload totally allocates: 0
                profiles: 0
                        invalid: 0
                        deleted: 0
                        missing count: 0
                import: 0
                backup: 0
                files: 0
                        invalid: 0
                        deleted: 0
                        missing count: 0
                rest: 0
Recordings allocates: 0
                final: 0
                        invalid: 0
                        deleted: 0
                        missing count: 0
                rest: 0
... Done

💡 说明：invalid/deleted/missing count 统计损坏、待清理与缺失的文件数，日常巡检可用来核对上传与录制文件完整性。

4.7 Tomcat 启停脚本

启动 / 停止：

cd /opt/apache-openmeetings-9.1.0
./bin/startup.sh

回显：

Tomcat started.

./bin/shutdown.sh

回显：

Tomcat stopped.

前台运行（排障时直接看日志输出，Ctrl+C 停止）：

./bin/catalina.sh run

catalina.sh 全部子命令：

./bin/catalina.sh

回显（Usage 部分）：

Usage:  catalina.sh ( commands ... )
  commands:
    debug             Start Catalina in a debugger
    jpda start        Start Catalina under JPDA debugger
    run               Start Catalina in the current window
    start             Start Catalina in a separate window
    stop              Stop Catalina, waiting up to 5 seconds for the process to end
    stop n            Stop Catalina, waiting up to n seconds for the process to end
    stop -force       Stop Catalina, wait up to 5 seconds and then use kill -KILL if still running
    configtest        Check a configuration file for syntax errors
    version           What version of tomcat and JVM are running

版本信息：

cd /opt/apache-openmeetings-9.1.0
./bin/version.sh

回显：

Server version: Apache Tomcat/11.0.23
Server number:  11.0.23.0
OS Name:        Linux
OS Version:     6.8.0-138-generic
Architecture:   amd64
JVM Version:    21.0.12.1+1-1-22.04.4-Ubuntu

配置校验：

./bin/configtest.sh

回显：

INFO: Server initialization in [749] milliseconds

4.8 digest.sh 口令摘要

生成 Tomcat 标准口令摘要（user:password 与盐，用于 Tomcat 自身 user database）：

cd /opt/apache-openmeetings-9.1.0
./bin/digest.sh -a sha-256 q1w2e3r4

回显：

q1w2e3r4:447d9eeeaf567db9cc65271c58f51e807e17cdcc90830722e7e2ffb0103bf616$1$a8ceaf7266f0c709505b131eac50b8356a05c5bc11a29f777a456ca67ced9e40

💡 说明：OpenMeetings 用户口令由应用自行管理（scrypt），该摘要工具用于 Tomcat realm 场景，一般无需使用。

4.9 network_test.sh 网络测试

双端带宽/抖动测试（会议音视频网络质量评估，⚠️ 前置：双端安装 iperf 并配置 SSH 免密）：

cd /opt/apache-openmeetings-9.1.0
./network_test.sh LOCAL_HOST_IP REMOTE_SSH_LOGIN REMOTE_HOST_IP

脚本用法回显：

Usage: ./network_test.sh LOCAL_HOST_IP REMOTE_SSH_LOGIN REMOTE_HOST_IP
Script requare installed 'iperf' on both local and remote hosts.
Also need setting up ssh login without requiring a password. Use for this purpose ssl certificates.

4.10 systemd 管理

服务名 openmeetings（单元文件 /etc/systemd/system/openmeetings.service）：

systemctl daemon-reload
systemctl enable openmeetings
systemctl start openmeetings
systemctl is-active openmeetings
systemctl status openmeetings --no-pager -l
systemctl restart openmeetings
systemctl stop openmeetings
systemctl disable openmeetings

状态回显：

active

● openmeetings.service - Apache OpenMeetings server
     Loaded: loaded (/etc/systemd/system/openmeetings.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-11 19:47:47 UTC; 40s ago
    Process: 8014 ExecStart=/opt/apache-openmeetings-9.1.0/bin/startup.sh (code=exited, status=0/SUCCESS)
   Main PID: 8021 (java)
      Tasks: 119 (limit: 5753)
     Memory: 558.2M

五、注意事项

admin.sh 的 -i/-b/-r/-l/-f 全部要求服务停止状态执行（内嵌 H2 单进程锁）。
管理命令执行时间可能较长（初始化/恢复含数据导入），期间勿中断，以 ... Done 或 exit=0 判定成功。
密码强度：--password 需大写+小写+数字+特殊符号且≥8位（admin/Q1w2e3r4! 为本文统一示例）。
改配置后重启：systemctl restart openmeetings。
备份文件默认生成在 $OM_HOME 下，重要备份请移出该目录妥善保存。

六、常见问题

6.1 执行 admin.sh 报 Database may be already in use / The file is locked

原因：服务正在运行，内嵌 H2 文件被占用。

处理：先停止服务再执行管理命令：

systemctl stop openmeetings
cd /opt/apache-openmeetings-9.1.0
./admin.sh -b
systemctl start openmeetings

6.2 UnsupportedClassVersionError

原因：使用了 Java 21 以下版本。

处理：安装 JDK 21（apt-get install -y openjdk-21-jdk-headless），确认 java -version。

6.3 -l 导入 LDAP 报 LdapConfig 为 null

原因：未配置 LDAP 域。

处理：先在管理员后台配置 LDAP 域生成 om_ldap.cfg，再执行 ./admin.sh -l -d <域ID>。

6.4 startup.sh 提示但 5080 端口未监听

原因：webapp 部署需 25–40 秒，或端口被占用。

处理：查看日志 tail -f $OM_HOME/logs/catalina.out 等待 Server startup；端口占用用 netstat -tlnp | grep 5080 排查。

6.5 如何确认 JVM 堆生效

ps -ef | grep [j]ava

回显中出现 -Xms256m -Xmx512m 即生效（见回显 4.7 节版本行附近）。

七、参考链接

官方命令行管理说明：https://openmeetings.apache.org/CommandLineAdmin.html
官方安装文档：https://openmeetings.apache.org/installation.html
Apache Tomcat 11 运行说明（RUNNING.txt 随发行包提供）：https://tomcat.apache.org/tomcat-11.0-doc/