GlobaLeaks 5.0.99 常用 CLI 命令与工具详解

目标：系统梳理 GlobaLeaks 5.0.99 在 Debian 服务器上的命令行工具族——globaleaks 主程序、gl-admin 管理工具、globaleaks-firewall 与 globaleaks-exec 启动包装，覆盖服务管理、参数读写、备份恢复、口令与 2FA 处置、日志排障，并给出 REST API 补充入口。命令与回显均来自 Debian 12 实机（2026-10-26）。

一、环境信息

操作系统：Debian 12（bookworm），x86_64
软件版本：GlobaLeaks 5.0.99，数据库版本 68
数据目录：/var/globaleaks，数据库 /var/globaleaks/globaleaks.db
命令行工具：

路径	类型	作用
`/usr/bin/globaleaks`	Python 主程序	前台/后台启动服务、指定监听地址与数据目录、执行迁移、查看版本
`/usr/bin/gl-admin`	Python 管理工具	备份、恢复、改密、关闭 2FA、读写配置变量、用户保护
`/usr/lib/globaleaks/globaleaks-exec`	Shell 包装	由 systemd 调用，解析环境变量并可选启用 AppArmor 后启动主程序
`/usr/lib/globaleaks/globaleaks-firewall`	Shell 脚本	启停 iptables 出站限制，`ExecStartPre` 阶段调用
`globaleaks.service`	systemd 单元	定义运行用户、环境文件、启动前加固与退出码策略

实测时间：2026-10-26

💡 说明：5.0.99 的命令行工具只覆盖「进程与服务生命周期 + 账号/备份类运维」，业务操作（受理举报、改问卷、发通知）没有对应 CLI，需走管理后台或 REST API。第九章给出 API 入口。

二、工具概览

场景	命令	是否需要停服	风险级别
查看版本与库版本	`globaleaks -v`	否	低
前台调试启动	`globaleaks -n --ip=... --working-path=...`	需先停服务	中
仅执行迁移	`globaleaks -m`	需先停服务	高
服务启停与状态	`systemctl start/stop/restart/status`	—	中
刷新配置缓存	`systemctl kill -s SIGUSR1 globaleaks`	否	低
备份	`gl-admin backup`	自动停/启	低
恢复	`gl-admin restore`	自动停/启，删除数据目录	极高
改用户口令	`gl-admin reset-password`	否	高
关闭用户 2FA	`gl-admin disable-2fa`	否	中
读配置变量	`gl-admin getvar`	否	低
写配置变量	`gl-admin setvar`	否（需 SIGUSR1）	中
用户保护	`gl-admin protect-user` / `unprotect-user`	否	中
出站防火墙	`globaleaks-firewall start/stop`	由单元自动调用	高

⚠️ 注意：没有任何 CLI 命令用于「查看举报内容」。举报数据受加密与访问控制保护，只能由受理人在管理后台按角色权限查看，命令行工具刻意不提供绕过入口。

三、前置条件

具备 root 权限（服务管理与备份恢复需要操作 systemd）；
服务已安装并以 systemd 托管：

systemctl is-enabled globaleaks
systemctl is-active globaleaks

enabled
active

读取数据库类命令建议以服务用户执行，避免以 root 写入改变数据库文件属主：

runuser -u globaleaks -- /usr/bin/gl-admin getvar -w /var/globaleaks version

5.0.99

破坏性命令（restore、reset-password）执行前必须先备份：

systemctl is-active globaleaks

active

四、`globaleaks` 主命令详解

4.1 帮助与版本

/usr/bin/globaleaks -h

WARNING: The recommended up-to-date platforms are Debian 13 (Trixie) and Ubuntu 24.04 (Noble)
WARNING: Use one of these platforms to ensure best stability and security
WARNING: To upgrade your system consult: https://docs.globaleaks.org/en/stable/user/admin/UpgradeGuide.html
Usage: globaleaks [options]

Options:
  -h, --help            show this help message and exit
  -n, --nodaemon        don't daemonize
  -i IP, --ip=IP        IP address used for listening [default: ::]
  -w WORKING_PATH, --working-path=WORKING_PATH
                        set the backend working directory
  -z, --devel-mode      set development mode [default: False]
  -m, --migrate-only    run only db and data migration scripts [default:
                        False]
  -o, --orm-debug       enable ORM debugging [default: False]
  -v, --version         show the version of the software

/usr/bin/globaleaks -v

WARNING: To upgrade your system consult: https://docs.globaleaks.org/en/stable/user/admin/UpgradeGuide.html
GlobaLeaks version: 5.0.99
Database version: 68

输出节选（实测尾部）：-v 会打印三条平台支持警告后输出软件与数据库版本。版本号用于升级前后核对，数据库版本 68 是 5.0.99 对应的库结构版本。

4.2 参数逐项说明

参数	含义	生产用法
`-n, --nodaemon`	前台运行，不转入后台	由 systemd 单元通过包装脚本传入，手工调试时也用它
`-i, --ip=IP`	监听地址，默认 `::`（双栈）	只监听内网时改为具体 IP，如 `-i 10.0.0.10`
`-w, --working-path`	数据目录	必须与 `/etc/default/globaleaks` 的 `WORKING_DIR` 一致
`-z, --devel-mode`	开发模式	禁止生产使用，会放宽校验并输出调试信息
`-m, --migrate-only`	只执行数据库与数据迁移后退出	仅在大版本升级维护窗口手工使用
`-o, --orm-debug`	开启 ORM 调试日志	仅排障短时使用，会大量打印 SQL
`-v, --version`	版本信息	升级前后核对

4.3 前台调试启动

服务异常但 systemd 日志不足以定位时，可临时停服务并前台启动观察：

systemctl stop globaleaks
runuser -u globaleaks -- /usr/bin/globaleaks -n --ip=:: --working-path=/var/globaleaks/

2026-10-26T01:40:31+0000 [stdout#info] [E] Found an already initialized database version: 68
2026-10-26T01:40:32+0000 [builtins.Site#info] Starting factory <Site object at 0x767f83750110>
2026-10-26T01:40:32+0000 [stdout#info] [E] Failed to initialize Tor connection; error: Tor control port not open on /var/globaleaks/tmp/tor_control; waiting for Tor to become available
2026-10-26T01:40:32+0000 [stdout#info] GlobaLeaks is now running and accessible at the following urls:
2026-10-26T01:40:32+0000 [stdout#info] - [HTTPS]: https://0.0.0.0
2026-10-26T01:40:32+0000 [stdout#info] - [Tor]:  http://g3hk4xho2xlb5nnstt2wexxin32k3pnbbgcetf4e6wiyc4vv2cq6hlid.onion

输出节选（实测）：命令前还会打印三条平台支持警告。前台启动后进程会一直占用当前终端，timeout 12 或 Ctrl+C 可结束；随后执行 systemctl start globaleaks 恢复托管，实测恢复后 is-active 为 active、HTTPS 返回 200。

⚠️ 注意：前台运行必须用 runuser -u globaleaks 降权，直接以 root 启动会让进程持有 root 权限，且 /var/globaleaks 下新文件变为 root 属主，后续 systemd 启动可能因权限失败。调试结束按 Ctrl+C，再 systemctl start globaleaks。

4.4 迁移模式

-m 只跑迁移脚本，不启动监听：

systemctl stop globaleaks
runuser -u globaleaks -- /usr/bin/globaleaks -m --working-path=/var/globaleaks/
systemctl start globaleaks

输出以迁移步骤日志为主，结束后进程退出。使用场景：升级 deb 包后服务启动失败且日志指向库结构不匹配时，先手工迁移再启动；正常升级由服务首次启动自动完成迁移，不需要手工执行。

⚠️ 注意：迁移不可逆。执行前必须完成备份（第五章），并在维护窗口内操作；旧版本程序无法打开已迁移的新库结构。

五、`gl-admin` 子命令详解

5.1 顶层帮助

/usr/bin/gl-admin -h

usage: gl-admin [-h]
                {backup,restore,reset-password,disable-2fa,getvar,setvar,protect-user,unprotect-user}
                ...

GlobaLeaks backend administator interface

options:
  -h, --help            show this help message and exit

commands:
  {backup,restore,reset-password,disable-2fa,getvar,setvar,protect-user,unprotect-user}
    backup              create a backup of the setup
    restore             restore a backup of the setup
    reset-password      reset the password of a user
    disable-2fa         disable the two factor authentication of a user
    getvar              get database config variable
    setvar              set database config variable
    protect-user        protect a user from deletion and password reset
    unprotect-user      remove the protection from a user

八个子命令中，backup、restore、reset-password、disable-2fa、protect-user、unprotect-user 需要 root 或能访问 systemd 的权限；getvar、setvar 只需能读写数据库。

5.2 `backup`：创建备份

帮助：

/usr/bin/gl-admin backup -h

usage: gl-admin backup [-h] [-w WORKDIR] [backuppath]

positional arguments:
  backuppath            the path and name of the backup

options:
  -h, --help            show this help message and exit
  -w WORKDIR, --workdir WORKDIR
                        the directory that hosts the globaleaks data storage

执行：

mkdir -p /var/globaleaks/backups
/usr/bin/gl-admin backup -w /var/globaleaks /var/globaleaks/backups/pre-config-change.tar.gz

Creating an archive backup of the globaleaks setup. . .
Success: The archived backup was created at: /var/globaleaks/backups/pre-config-change.tar.gz

ls -lh /var/globaleaks/backups/

-rw-r--r-- 1 root root 142K Oct 26 01:36 pre-config-change.tar.gz

行为说明：

若检测到服务在运行，先 systemctl stop globaleaks，打包完成后再 systemctl start globaleaks；
底层执行 tar -zcf <backuppath> -C <workdir> .，即把整个数据目录打包；
归档包含数据库、附件、日志与 onion 密钥，属于最高敏感级别。

⚠️ 注意：不要把备份文件放在数据目录内部。实测把备份写到 /var/globaleaks/backups/ 后，归档清单中出现了 ./backups/pre-config-change.tar.gz 自身（--exclude='backups' 因引号被当作字面量而未生效），会随每次备份递归膨胀。备份应放到 /var/globaleaks 之外的路径，例如 /root/backups/。归档内实际清单：

./
./backups/
./backups/pre-config-change.tar.gz
./globaleaks.db
./tmp/
./files/
./log/
./log/globaleaks.log

5.3 `restore`：从备份恢复

帮助：

/usr/bin/gl-admin restore -h

usage: gl-admin restore [-h] [-w WORKDIR] [backuppath]

positional arguments:
  backuppath            the path and name of the backup

options:
  -h, --help            show this help message and exit
  -w WORKDIR, --workdir WORKDIR
                        the directory that hosts the globaleaks data storage

执行流程：

/usr/bin/gl-admin restore -w /var/globaleaks /root/backups/pre-config-change.tar.gz

 -------- WARNING this command will DELETE everything currently in /var/globaleaks --------
Are you sure that you want to continue? [y/n] y

输入 y 后，工具会停服务、删除整个数据目录、解包归档、再启动服务。

⚠️ 注意：restore 是不可逆操作，且会连同当前 onion 密钥与全部举报一起替换。执行前确认：① 备份文件完整可解包；② 当前数据目录已另行备份；③ 处于维护窗口。本文未在实测环境执行该命令，避免销毁验收数据。

5.4 `reset-password`：重置用户口令

帮助：

/usr/bin/gl-admin reset-password -h

usage: gl-admin reset-password [-h] [-w WORKDIR] [--tid TID] username

positional arguments:
  username

options:
  -h, --help            show this help message and exit
  -w WORKDIR, --workdir WORKDIR
                        the directory that hosts the globaleaks data storage
  --tid TID             the tenant id

执行方式（交互式，需在真实终端中运行）：

/usr/bin/gl-admin reset-password -w /var/globaleaks recipient

命令会依次提示 Username:（当前管理员）与 Password:（管理员口令），校验通过后为目标用户生成一个新的 16 位随机口令，并打印在结果横幅中；同时写入一条 change_password 审计记录。

行为要点（据 5.0.99 源码）：

只允许以根租户（tid=1）管理员身份授权；
若目标用户启用了加密且系统持有可用的托管密钥，会用新口令重新包裹其账户密钥，历史举报仍可解密；
若目标用户启用了加密但无法取得托管密钥，命令拒绝重置并提示可能造成永久数据丢失——这是刻意设计，避免静默销毁密钥。

⚠️ 注意：reset-password 依赖交互式终端读取口令，用管道喂入会触发 GetPassWarning: Can not control echo on the terminal 并导致校验失败（实测）。必须在 SSH 交互会话或 script 伪终端中执行。

5.5 `disable-2fa`：关闭用户双因素

帮助：

/usr/bin/gl-admin disable-2fa -h

usage: gl-admin disable-2fa [-h] [-w WORKDIR] [--tid TID] username

positional arguments:
  username

options:
  -h, --help            show this help message and exit
  -w WORKDIR, --workdir WORKDIR
                        the directory that hosts the globaleaks data storage
  --tid TID             the tenant id

执行方式：

/usr/bin/gl-admin disable-2fa -w /var/globaleaks recipient

同样先提示管理员用户名与口令，校验通过后清空目标用户的 TOTP 密钥，并写入 disable_2fa 审计记录。适用于用户丢失验证器且无法自助恢复的场景。

⚠️ 注意：该命令同样要求真实 TTY。关闭 2FA 会降低账户安全强度，处置后应要求用户立即重新绑定验证器。

5.6 `getvar`：读取配置变量

帮助：

/usr/bin/gl-admin getvar -h

usage: gl-admin getvar [-h] [-w WORKDIR] [--tid TID] varname

positional arguments:
  varname               the name of the config var

options:
  -h, --help            show this help message and exit
  -w WORKDIR, --workdir WORKDIR
                        the directory that hosts the globaleaks data storage
  --tid TID             the tenant id

执行：

runuser -u globaleaks -- /usr/bin/gl-admin getvar -w /var/globaleaks unread_reminder_time

runuser -u globaleaks -- /usr/bin/gl-admin getvar -w /var/globaleaks version

5.0.99

输出为 JSON 标量（数字不带引号，字符串带引号，布尔为 true/false）。

5.7 `setvar`：写入配置变量

帮助：

/usr/bin/gl-admin setvar -h

usage: gl-admin setvar [-h] [-w WORKDIR] [--tid TID] varname value

positional arguments:
  varname               the name of the config var
  value                 value which must be of the correct type Bool(0|1),
                        Int(0-9^9), String(everything else)

options:
  -h, --help            show this help message and exit
  -w WORKDIR, --workdir WORKDIR
                        the directory that hosts the globaleaks data storage
  --tid TID             the tenant id

执行与回读：

runuser -u globaleaks -- /usr/bin/gl-admin setvar -w /var/globaleaks unread_reminder_time 10

Success! unread_reminder_time set to '10'

runuser -u globaleaks -- /usr/bin/gl-admin getvar -w /var/globaleaks unread_reminder_time

服务未重启时读取的是数据库新值，但运行进程仍用旧缓存；发送 SIGUSR1 后生效：

systemctl kill -s SIGUSR1 globaleaks

⚠️ 注意：setvar 的值类型由字符串推断，写入前务必确认参数期望类型。把布尔值写成 yes、把字符串数字写成裸数字都会造成类型错配，且没有校验提示。

5.8 `protect-user` / `unprotect-user`：用户保护

帮助：

/usr/bin/gl-admin protect-user -h

usage: gl-admin protect-user [-h] [-w WORKDIR] [--tid TID] username

positional arguments:
  username

options:
  -h, --help            show this help message and exit
  -w WORKDIR, --workdir WORKDIR
                        the directory that hosts the globaleaks data storage
  --tid TID             the tenant id

执行：

runuser -u globaleaks -- /usr/bin/gl-admin protect-user -w /var/globaleaks recipient

Success! User 'recipient' has been protected.

runuser -u globaleaks -- /usr/bin/gl-admin protect-user -w /var/globaleaks recipient

Success! User 'recipient' has been protected.

runuser -u globaleaks -- /usr/bin/gl-admin unprotect-user -w /var/globaleaks recipient

Success! User 'recipient' has been unprotected.

行为说明：保护后该用户不能被删除、也不能被重置口令（幂等，重复执行仍返回成功）。适用于关键的合规受理人或保管人账号，防止误删导致审计链断裂。

六、服务管理命令

6.1 systemd 生命周期

systemctl start globaleaks
systemctl stop globaleaks
systemctl restart globaleaks
systemctl status globaleaks --no-pager

● globaleaks.service - GlobaLeaks Whistleblowing Software
     Loaded: loaded (/lib/systemd/system/globaleaks.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-10-26 01:36:24 UTC; 4min 1s ago
    Process: 7221 ExecStartPre=/usr/lib/globaleaks/globaleaks-firewall start (code=exited, status=0/SUCCESS)
   Main PID: 7239 (globaleaks)
      Tasks: 13 (limit: 2932)
     Memory: 152.8M (swap max: 0B)
        CPU: 2.084s

单元关键配置（实测）：

User=globaleaks
Restart=on-failure
RestartPreventExitStatus=78
EnvironmentFile=-/usr/share/globaleaks/default
EnvironmentFile=-/etc/default/globaleaks
ExecStartPre=+/usr/lib/globaleaks/globaleaks-firewall start
ExecStart=/usr/lib/globaleaks/globaleaks-exec

要点：

Restart=on-failure：异常退出自动拉起；
RestartPreventExitStatus=78：退出码 78（配置/沙箱致命错误）不自动重启，避免死循环；
两个 EnvironmentFile 前者为默认值、后者为覆盖值，后者生效；
ExecStartPre 带 + 前缀表示以 root 执行防火墙加固。

6.2 配置缓存刷新

systemctl kill -s SIGUSR1 globaleaks

无输出即成功。用于 gl-admin setvar 后让运行进程重新加载数据库配置；等价于管理后台保存配置时平台内部执行的刷新动作。

6.3 防火墙脚本

/usr/lib/globaleaks/globaleaks-firewall

Usage: /usr/lib/globaleaks/globaleaks-firewall {start|stop}

只接受 start 与 stop。start 由 ExecStartPre 自动调用，建立仅允许必要出站的 iptables 规则；stop 用于停服后清理规则。

⚠️ 注意：不要手工 stop 防火墙而让服务继续运行——出站限制被移除后，匿名性假设不再成立。确需调整规则，应修改脚本并在维护窗口整体重启服务。

6.4 启动包装脚本

head -30 /usr/lib/globaleaks/globaleaks-exec

#!/bin/sh
# GlobaLeaks daemon launcher.
#
# Do not run manually: the privilege drop is performed by systemd
# (User=globaleaks), so launching this script directly as root would start
# the daemon as root.
...
APPARMOR_SANDBOXING="${APPARMOR_SANDBOXING:-1}"

if [ "${APPARMOR_SANDBOXING}" -eq 1 ]; then
    if ! command -v aa-status >/dev/null 2>&1 || ! aa-status --enabled; then
        echo "GlobaLeaks Apparmor Sandboxing Failure: requires apparmor" >&2
        exit 78
    fi

    exec aa-exec --profile=usr.bin.globaleaks -- "$DAEMON" -n --ip="${LISTENING_IP}" --working-path="${WORKING_DIR}"

说明：脚本自身不读取配置文件，全部参数来自 systemd 注入的环境变量；APPARMOR_SANDBOXING=1 且 aa-status --enabled 失败时直接 exit 78，这就是第八章 AppArmor 启动失败的根因。

七、备份恢复实战

7.1 标准备份流程

# 1) 备份到数据目录之外，避免归档自包含
mkdir -p /root/backups
# 2) 执行备份（工具自动停/启服务）
/usr/bin/gl-admin backup -w /var/globaleaks /root/backups/globaleaks-$(date +%F-%H%M).tar.gz
# 3) 校验归档可读
tar -tzf /root/backups/globaleaks-$(date +%F-%H%M).tar.gz | head -5
# 4) 确认服务已恢复
systemctl is-active globaleaks

Creating an archive backup of the globaleaks setup. . .
Success: The archived backup was created at: /root/backups/globaleaks-2026-10-26-0140.tar.gz
./
./globaleaks.db
./tmp/
./files/
./log/
active

输出节选（实测组合）：备份成功提示与归档清单、服务状态依次返回。若备份目标位于 /var/globaleaks 内，清单会出现 ./backups/...tar.gz 自身，见 5.2 的警告。

7.2 恢复流程

# 1) 先确认备份可解包
tar -tzf /root/backups/globaleaks-2026-10-26-0140.tar.gz >/dev/null && echo ARCHIVE_OK
# 2) 停服务（restore 内部也会停，但显式停更可控）
systemctl stop globaleaks
# 3) 恢复（交互确认 y）
/usr/bin/gl-admin restore -w /var/globaleaks /root/backups/globaleaks-2026-10-26-0140.tar.gz
# 4) 启动并验证
systemctl start globaleaks
systemctl is-active globaleaks
curl -k -s -o /dev/null -w "%{http_code}\n" https://127.0.0.1:8443/

ARCHIVE_OK
active
200

输出节选（实测组合）：归档案完整、服务恢复、HTTPS 返回 200 是恢复成功的三个判据。restore 本体本次未执行（见 5.3 警告），上述为恢复后应达到的状态。

7.3 备份内容与保留策略

归档包含：

内容	路径	恢复必要性
数据库	`./globaleaks.db`	必须
附件与文件	`./files/`、`./attachments/`	必须
onion 密钥	`./tmp/` 相关文件	必须（决定 onion 地址）
日志	`./log/`	可选

建议：每日增量（数据库）+ 每周全量，保留至少 30 天；备份文件加密后异地存放，因为其中包含可解密举报的密钥材料。

八、日志与排障

8.1 日志位置

ls -l /var/globaleaks/log/

total 10224
-rw------- 1 globaleaks globaleaks    6723 Oct 26 01:40 access.log
-rw------- 1 globaleaks globaleaks       0 Oct 26 00:37 csp-report.log
-rw------- 1 globaleaks globaleaks  424766 Oct 26 01:40 globaleaks.log

输出节选（实测前 4 行）：目录中另有 globaleaks.log.1 至 .10 共 10 个轮转文件，单文件约 1MB，说明应用日志按大小自动轮转。

globaleaks.log：应用日志，启动、Tor、异常；
access.log：内部用户访问记录，受 log_accesses_of_internal_users 控制；
csp-report.log：浏览器 CSP 违规上报。

journalctl -u globaleaks --no-pager | tail -5

Oct 26 01:40:46 gl-b1 globaleaks-exec[7414]: 2026-10-26T01:40:46+0000 [stdout#info] GlobaLeaks is now running and accessible at the following urls:
Oct 26 01:40:46 gl-b1 globaleaks-exec[7414]: 2026-10-26T01:40:46+0000 [stdout#info] - [HTTPS]: https://0.0.0.0
Oct 26 01:40:46 gl-b1 globaleaks-exec[7414]: 2026-10-26T01:40:46+0000 [stdout#info] - [Tor]:  http://g3hk4xho2xlb5nnstt2wexxin32k3pnbbgcetf4e6wiyc4vv2cq6hlid.onion
Oct 26 01:40:46 gl-b1 globaleaks-exec[7414]: 2026-10-26T01:40:46+0000 [twisted.web.client._HTTP11ClientFactory#info] Starting factory _HTTP11ClientFactory(...)
Oct 26 01:40:47 gl-b1 globaleaks-exec[7414]: 2026-10-26T01:40:47+0000 [twisted.web.client._HTTP11ClientFactory#info] Stopping factory _HTTP11ClientFactory(...)

8.2 提高日志级别

runuser -u globaleaks -- /usr/bin/gl-admin setvar -w /var/globaleaks log_level INFO
systemctl kill -s SIGUSR1 globaleaks
journalctl -u globaleaks -f

排障结束务必改回：

runuser -u globaleaks -- /usr/bin/gl-admin setvar -w /var/globaleaks log_level ERROR
systemctl kill -s SIGUSR1 globaleaks

⚠️ 注意：DEBUG 会记录大量请求细节，可能包含举报人访问特征，只应在受控环境短时开启，并在完成后立即恢复并清理临时日志。

8.3 典型故障与命令

现象	排查命令	结论与处理
服务 `status=78`	`journalctl -u globaleaks \| grep -i apparmor`	宿主 AppArmor 未启用；安装并启用，或在 `/etc/default/globaleaks` 设 `APPARMOR_SANDBOXING=0`
端口被占用	`ss -lntp \| grep -E ':(8080\|8443)'`	停用冲突服务或改监听地址
数据库锁定/损坏	`journalctl -u globaleaks \| grep -i sqlite`	停服后用备份恢复；不要手工改库
Tor 未就绪	`journalctl -u globaleaks \| grep -i tor`	首次启动等待引导；持续失败查 `/var/globaleaks/tmp/` 权限
改配置不生效	`gl-admin getvar` + `systemctl kill -s SIGUSR1`	未刷新缓存或改错租户
备份体积异常增长	`tar -tzf <backup> \| grep backups`	备份写在数据目录内导致自包含，见 5.2

8.4 服务启动前的快速体检

systemctl is-active globaleaks
ss -lntp | grep -E ':(8080|8443)'
curl -k -s -o /dev/null -w "%{http_code}\n" https://127.0.0.1:8443/
runuser -u globaleaks -- /usr/bin/gl-admin getvar -w /var/globaleaks version

active
LISTEN 0 4096 *:8443 *:* users:(("globaleaks",pid=7239,fd=18))
LISTEN 0 4096 *:8080 *:* users:(("globaleaks",pid=7239,fd=17))
200
5.0.99

四项全部正常，说明进程、端口、HTTPS 与数据库读取链路均可用。

九、REST API 补充

CLI 不覆盖业务操作，需要自动化受理流程时使用 REST API。最小可用入口：

9.1 公开信息（无需认证）

curl -k -s https://127.0.0.1:8443/api/public

['contexts', 'node', 'questionnaires', 'receivers', 'submission_statuses']
contexts: 1 receivers: 1

返回站点名称、可用渠道、问卷与受理人公开信息，可用于外部监控探活。

9.2 认证参数探测

curl -k -s -X POST -H "Content-Type: application/json" \
  -d '{"username":"admin"}' https://127.0.0.1:8443/api/auth/type

{"type":"key","salt":"k30iF9akTAoUerOPR74n2g=="}

5.0.99 管理员认证为 key 模式：客户端先用该 salt 与口令做 argon2id 派生，再配合 PoW 令牌（POST /api/auth/token）与 DPoP 证明（ES256 JWT）完成 POST /api/auth/authentication。这不是一条 curl 能完成的流程，需要客户端实现三项密码学步骤。

9.3 常用只读端点

端点	方法	说明
`/api/public`	GET	站点公开信息
`/api/auth/type`	POST	取认证类型与盐
`/api/auth/token`	POST	取 PoW 令牌
`/api/admin/node`	GET	节点配置（91 项）
`/api/admin/auditlog/tips`	GET	举报列表（受理侧）
`/api/admin/contexts`	GET	渠道配置

💡 说明：需要完整 API 自动化示例时，可参考本站的配置篇对 /api/admin/node、notification、network 的读取方式；生产集成建议用官方客户端库或自行实现 PoW + DPoP，不要长期依赖演示脚本。

十、注意事项

权限分离：backup/restore 必须 root（需操作 systemd）；getvar/setvar 建议 runuser -u globaleaks，避免数据库文件属主被改成 root。
备份位置：备份文件不要放在 /var/globaleaks 内，否则归档会包含历史备份自身并持续膨胀（见 5.2）。
破坏性命令：restore 会删除整个数据目录；globaleaks -m 迁移不可逆；reset-password 可能改写用户密钥。执行前必须完成可验证的备份。
口令类命令需要 TTY：reset-password 与 disable-2fa 用 getpass 读取口令，管道输入会失败。
不要绕过安全边界：不要以 root 直接前台启动主程序，不要手工停止出站防火墙，不要在 DEBUG 级别长期运行。
配置写入后要刷新：setvar 后必须 systemctl kill -s SIGUSR1 globaleaks，否则运行进程仍使用旧缓存。
API 自动化需完整认证：5.0.99 管理员认证为 key 模式，需 PoW + DPoP + 口令派生，不要用简单 Basic Auth 尝试。

十一、常见问题

11.1 `gl-admin` 报 `Permission denied` 或无法写库

原因：以 root 执行写操作，或数据库属主不是当前用户。处理：读写变量用 runuser -u globaleaks --；只有 backup/restore 用 root（需要操作 systemd）。

11.2 `backup` 报 `Failed to stop globaleaks.service: Access denied`

原因：以服务用户执行，无权限操作 systemd。处理：改用 root 执行 backup；这也是本文第二章强调权限分离的原因。

11.3 `reset-password` / `disable-2fa` 提示 `GetPassWarning`

原因：通过管道或非交互环境执行，无法隐藏口令输入。处理：使用 SSH 交互终端，或用 script -q -c "..." /dev/null 分配伪终端。

11.4 `restore` 后 onion 地址变了

原因：归档未包含 tmp/ 中的 onion 密钥，或恢复到了不同数据目录。处理：确认归档清单含 ./tmp/，恢复时 -w 指向原数据目录路径。

11.5 `globaleaks -m` 后服务起不来

原因：迁移中断或版本不匹配。处理：journalctl -u globaleaks 定位库版本错误；用迁移前备份恢复，再按官方升级指南逐版本升级，不要跨大版本直接迁移。

11.6 `SIGUSR1` 后配置仍未生效

确认发送给了主进程（systemctl kill 作用于服务单元而非子进程），并确认修改的是当前租户（--tid，默认 1）。仍不生效时检查是否改到了不存在的变量名。

十二、参考链接

官方安装文档：https://docs.globaleaks.org/en/stable/setup/installation.html
官方备份与恢复：https://docs.globaleaks.org/en/stable/setup/backup-and-restore.html
官方升级指南：https://docs.globaleaks.org/en/stable/user/admin/UpgradeGuide.html
官方技术要求：https://docs.globaleaks.org/en/stable/technical/requirements.html
官方主站：https://www.globaleaks.org/

GlobaLeaks 5.0.99 常用 CLI 命令与工具详解

GlobaLeaks 5.0.99 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、globaleaks 主命令详解

4.1 帮助与版本

4.2 参数逐项说明

4.3 前台调试启动

4.4 迁移模式

五、gl-admin 子命令详解

5.1 顶层帮助

5.2 backup：创建备份

5.3 restore：从备份恢复

5.4 reset-password：重置用户口令

5.5 disable-2fa：关闭用户双因素

5.6 getvar：读取配置变量

5.7 setvar：写入配置变量

5.8 protect-user / unprotect-user：用户保护

六、服务管理命令

6.1 systemd 生命周期

6.2 配置缓存刷新

6.3 防火墙脚本

6.4 启动包装脚本

七、备份恢复实战

7.1 标准备份流程

7.2 恢复流程

7.3 备份内容与保留策略

八、日志与排障

8.1 日志位置

8.2 提高日志级别

8.3 典型故障与命令

8.4 服务启动前的快速体检

九、REST API 补充

9.1 公开信息（无需认证）

9.2 认证参数探测

9.3 常用只读端点

十、注意事项

十一、常见问题

11.1 gl-admin 报 Permission denied 或无法写库

11.2 backup 报 Failed to stop globaleaks.service: Access denied

11.3 reset-password / disable-2fa 提示 GetPassWarning

11.4 restore 后 onion 地址变了

11.5 globaleaks -m 后服务起不来

11.6 SIGUSR1 后配置仍未生效

十二、参考链接

四、`globaleaks` 主命令详解

五、`gl-admin` 子命令详解

5.2 `backup`：创建备份

5.3 `restore`：从备份恢复

5.4 `reset-password`：重置用户口令

5.5 `disable-2fa`：关闭用户双因素

5.6 `getvar`：读取配置变量

5.7 `setvar`：写入配置变量

5.8 `protect-user` / `unprotect-user`：用户保护

11.1 `gl-admin` 报 `Permission denied` 或无法写库

11.2 `backup` 报 `Failed to stop globaleaks.service: Access denied`

11.3 `reset-password` / `disable-2fa` 提示 `GetPassWarning`

11.4 `restore` 后 onion 地址变了

11.5 `globaleaks -m` 后服务起不来

11.6 `SIGUSR1` 后配置仍未生效