Fluxer 2026.1025.41605 常用 CLI 命令与工具详解

目标：把 Fluxer 自托管实例的全部日常操作收敛到官方运维工具 rexctl 上——命令树、实例生命周期、账号与管理员、邀请与注册策略、配置读写、品牌与邮件、备份恢复与升级交接、日志排障、Shell 补全，逐条给出可执行命令与实测回显。本文命令与回显均来自 2026-10-25 的真实实例实测（Ubuntu 22.04.5 LTS / rexctl 2026.1025.41605 / 实例目录 /opt/fluxer）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（amd64）
组件版本：Fluxer 2026.1025.41605（rexctl 与实例同版本；日历化版本号「年.月日.构建号」）
运维工具：rexctl 2026.1025.41605（commit 4abd1a3e，Go 1.27.3 构建）
实例目录：/opt/fluxer（编排文件、证书、备份、状态都在这里）
实例地址：https://fluxer.test（评测环境私有后缀域名，边缘以纯 HTTP 监听 8080）
演示账号：管理员 root / 密码 q1w2e3r4（演示口令，生产必须换强密码）
运行引擎版本：29.1.3（rexctl 要求 ≥ 24.0.0，版本门槛以 https://fluxer.dev/rexctl/release.json 的 min_docker 字段为准）

本文所有命令都显式带 --dir /opt/fluxer。一台机器只有一套实例时该参数可省略（rexctl 默认就是 /opt/fluxer），多套实例并存时它是防止改错对象的唯一手段。

二、rexctl 的安装位置与命令树

rexctl 是 Fluxer 唯一的官方运维入口：安装、升级、备份、回滚、账号、邀请、配置、日志全部通过它完成。本节先确认它装在哪里、能做什么。

2.1 二进制与实例目录的职责划分

安装完成后，rexctl 在机器上留下两个同版本二进制：

ls -l /usr/local/bin/rexctl /usr/local/libexec/rexctl/rexctl

实测回显：

-rwxr-xr-x 1 1001 1001 33898656 Oct 25 03:51 /usr/local/bin/rexctl
-rwxr-xr-x 1 root root 33898656 Oct 25 07:23 /usr/local/libexec/rexctl/rexctl

两者的分工：

/usr/local/bin/rexctl：日常敲的入口，安装脚本或手动 install -m 0755 放进去的副本；
/usr/local/libexec/rexctl/rexctl：实例自带的「锚定版本」副本，开机自启服务与 rexctl upgrade 都以它为准，避免入口被替换后版本漂移；
/opt/fluxer：实例目录，status 里的 Folder 就是它；backups/ 存备份，recovery-kit-root.txt 是管理员恢复包。

2.2 版本查询

rexctl --version
rexctl --dir /opt/fluxer version

实测回显：

rexctl version 2026.1025.41605 (4abd1a3)

rexctl 2026.1025.41605
Fluxer 2026.1025.41605

--version 只报 rexctl 自身；version 子命令同时报「工具版本 + 实例版本」，两者不一致就说明工具与实例升级不同步，应检查 rexctl doctor。

2.3 顶层命令树

rexctl --help

实测回显：


  Install and run your Fluxer instance.

  Exit codes:
    0     ok
    1     failed
    2     usage
    3     refused, or doctor found a problem
    130   interrupted

  Usage

    rexctl [command] [--flags]

  Install and run

    backup [command]           Back up your instance
    doctor [--flags]           Check your instance and this machine for problems
    eject                      Manage this instance yourself with docker compose
    install [--flags]          Install Fluxer on this machine, or take over an existing install
    logs [service] [--flags]   Show logs from your instance
    proxy [command]            Use your own reverse proxy in front of Fluxer
    restart                    Restart your instance
    restore <file> [--flags]   Restore your instance from a backup
    rollback [--flags]         Go back to the release you ran before the last upgrade
    setup [command] [--flags]  Create the admin account and finish setup in the terminal
    start [--flags]            Start your instance
    status [--flags]           Show whether your instance is running
    stop [--flags]             Stop your instance
    takeover [--flags]         Let rexctl manage an instance it doesn't manage yet
    uninstall [--flags]        Remove Fluxer from this machine
    upgrade [--flags]          Upgrade rexctl and Fluxer to the latest release

  Manage your instance

    admins [command]           Choose who can manage your instance
    branding [command]         Change your instance's name, colour and images
    config [command]           Read and change Fluxer's settings
    email [command]            Set up how your instance sends email
    invites [command]          Manage invite links for new accounts
    registration [command]     Choose who can create an account
    users [command]            Manage accounts on your instance

  Other commands

    completion [command]       Print a shell completion script
    help [command]             Show help for a command
    version [--flags]          Show the rexctl and Fluxer versions

  Flags

    --dir                      Folder with your instance
    -h --help                  Show help for a command
    -q --quiet                 Print only errors and results
    --verbose                  Print every step and command
    -v --version               Show the rexctl version
    -y --yes                   Answer yes to every question and never prompt

命令按用途分四组：Install and run（安装与实例生命周期）、Manage your instance（账号体系与实例行为）、Other commands（补全、帮助、版本），以及全局 Flags。扩展命令一律以「名词 + 动词」两段式组织（users ban、invites create、config set），与 kubectl 的 资源动作 风格一致。

五个退出码是写自动化脚本的关键：0 成功、1 失败、2 用法错误、3 被拒绝或 doctor 发现问题、130 被中断。下文各命令的回显后面都标注了实测退出码。

💡 技术拓展：自托管服务的运维入口常见三种形态——

形态代表特点适用
命令式 CLI rexctl、systemctl、wp-cli 一条命令一个动作，回显直给，易进脚本单机实例的日常运维
声明式 IaC Ansible、Terraform、Helm 状态描述在文件里，可版本化、可审计多机批量、CI 下发
Web 控制台管理面板、Portainer 图形化、零记忆成本低频操作、非技术人员

本文主线是命令式 CLI；Fluxer 同时提供管理面板（/admin）与 Helm Chart，分别覆盖图形化与集群化场景，三者操作的是同一份实例状态。

形态	代表	特点	适用
命令式 CLI	rexctl、systemctl、wp-cli	一条命令一个动作，回显直给，易进脚本	单机实例的日常运维
声明式 IaC	Ansible、Terraform、Helm	状态描述在文件里，可版本化、可审计	多机批量、CI 下发
Web 控制台	管理面板、Portainer	图形化、零记忆成本	低频操作、非技术人员

三、全局参数与输出约定

3.1 六个全局参数

参数	作用	实测要点
`--dir`	指定实例目录	默认 `/opt/fluxer`；多实例机器必须显式指定
`-h --help`	显示当前命令帮助	每一级命令都有；`rexctl users create --help` 列出该子命令全部参数
`-q --quiet`	只打印错误与结果	去掉 `ok ...` 前缀行，适合脚本取值
`--verbose`	打印每一步实际执行的动作	排障时看 rexctl 到底做了什么
`-y --yes`	所有提问自动答是，绝不交互	无人值守脚本必备，危险操作仍要配 `--confirm`
`-v --version`	打印 rexctl 版本	等价 `rexctl --version`

3.2 静默模式的实测差异

rexctl -q --dir /opt/fluxer status

实测回显：

Address   https://fluxer.test
Version   2026.1025.41605
Folder    /opt/fluxer

对比不加 -q 的输出，首行 ok Fluxer is running. 被去掉了——脚本里取地址/版本时用 -q 更省事。

3.3 用法错误的固定形态

rexctl --dir /opt/fluxer nosuchcmd

实测回显：

rexctl has no nosuchcmd command.
Run rexctl --help to see every command.

退出码 2。同样地，拼错子命令（如 rexctl admins list）会提示 rexctl admins has no list command. 并给出看帮助的指引——rexctl 不猜意图，命令名必须精确。

四、实例生命周期

生命周期命令负责「实例是开着还是停着」，是其余所有操作的前提。status 的退出码本身就是状态信号：运行中返回 0，已停止返回 3。

4.1 查看状态

rexctl --dir /opt/fluxer status

实测回显：

ok Fluxer is running.
Address   https://fluxer.test
Version   2026.1025.41605
Folder    /opt/fluxer

status 另支持 --json，输出含 running、healthy 与逐服务状态数组，便于监控系统取值；文本模式则是给人和 shell 判断用的精简四行。

4.2 停止与启动

rexctl --dir /opt/fluxer stop

实测回显：

ok Stopped Fluxer.
Run rexctl start to start it again.

停止后立即查状态，得到的是「失败态 + 指引」：

rexctl --dir /opt/fluxer status

实测回显：

x Fluxer is stopped.
  Run rexctl start.
Address   https://fluxer.test
Version   2026.1025.41605
Folder    /opt/fluxer

退出码 3（refused）。这正是脚本里判断「实例是否在跑」的正确方式：看退出码，而不是 grep 文本。

重新启动：

rexctl --dir /opt/fluxer start

实测回显（节选末行）：

ok Started Fluxer at https://fluxer.test.

启动过程会逐行打印「已起 N 个服务、还在等待哪些依赖」，直到全部健康才宣告完成。

4.3 重启

rexctl --dir /opt/fluxer restart

实测回显（输出节选，实测首尾）：

Restarting Fluxer: 20 of 20 services started, waiting for nats (0s)
Restarting Fluxer: 20 of 20 services started, waiting for nats and valkey (0s)
...
Restarting Fluxer: 20 of 21 services ready, waiting for seaweedfs-init (28s)
ok Restarted Fluxer.

整机重启实测约 28 秒。restart 会按依赖顺序滚动重启全部服务，期间实例不可用，生产应在低峰执行。

4.4 体检：doctor

doctor 是排障第一入口，它把「机器资源、实例文件、开机自启、域名解析、数据库口令、语音公网 IP、最近备份」一次性查完：

rexctl --dir /opt/fluxer doctor

实测回显：

ok Docker 29.1.3 is running.
ok This machine has 23 GB of memory.
ok This machine has 171 GB of free disk space.
ok rexctl keeps all of your instance's settings.
ok Fluxer's files are all in place.
ok Fluxer starts with this machine.
ok Your instance's address is https://fluxer.test everywhere.
ok Browser notifications are set up.
ok Fluxer is running.
ok Every Fluxer service runs the version on this machine.
ok Fluxer answers on this machine.
ok Apps are told to connect to fluxer.test.
ok The web app loads.
ok Fluxer can sign in to its database.
ok The database password works with this release.
ok Voice calls can find this machine's public IP address.
ok Your last backup is from 25 October.

17 项全部 ok，退出码 0。任何一项变 x 时退出码即为 3，可安全用作监控探针。--fix 会尝试自动修可安全修复的项（如重写自启服务），--json 输出逐项 id/status/message/fixable 结构供采集。

4.5 生命周期验证闭环

停→查→启→查，四步确认操作真的生效：

rexctl --dir /opt/fluxer stop
rexctl --dir /opt/fluxer status; echo "exit=$?"
rexctl --dir /opt/fluxer start
rexctl --dir /opt/fluxer status; echo "exit=$?"

实测回显（节选关键行）：

ok Stopped Fluxer.
x Fluxer is stopped.
  Run rexctl start.
exit=3
ok Started Fluxer at https://fluxer.test.
ok Fluxer is running.
exit=0

五、账号与管理员

users 管普通账号，admins 管管理员权限，两组命令的分工在帮助里写得很清楚。

5.1 列出账号

rexctl --dir /opt/fluxer users list

实测回显：

Username   Email   ID                    Joined        Status
root               1563815331372204032   25 Oct 2026   admin
alice              1563816061910908928   25 Oct 2026
bob                1563816061910908931   25 Oct 2026

--admins 只列管理员，--search 按文本过滤，--json 输出结构化数组（含 id、admin、banned、mfa、created_at）：

rexctl --dir /opt/fluxer users list --admins

实测回显：

Username   Email   ID                    Joined        Status
root               1563815331372204032   25 Oct 2026   admin

5.2 查看单个账号

rexctl --dir /opt/fluxer users show root

实测回显：

Account           root
ID                1563815331372204032
Email             none
Email confirmed   yes
Joined            25 Oct 2026
Last active       25 Oct 2026
Admin             yes
Permissions       *
Two-factor        no
Banned            no
Disabled          no
Sessions          1

这张卡片是账号排障的起点：Sessions 判断是否在线、Two-factor 判断 MFA 状态、Banned/Disabled 区分「封禁」与「停用」。

5.3 创建账号

rexctl --dir /opt/fluxer users create demo1

实测回显：

ok Created demo1.
Send them this link to set a password.
https://fluxer.test/reset#token=hNhzZq3DBgvR8wbjD01WC2hum4PgcoMydXz2hjtB7ZrHRhIMNJJhFIXPyvsG7sUa

创建即打印「设密码链接」，管理员把它发给本人即可，全程不需要知道对方密码。可选参数：--email（用户名登录模式下不挂邮箱，带该参数会报 Pass a username. 或邮箱相关错误）、--admin（直接设为管理员）。

5.4 重置密码、强制下线与关闭 MFA

rexctl --dir /opt/fluxer users reset-link alice

实测回显：

ok Made a link for alice to set a new password. It works until 08:59 on 25 October.
https://fluxer.test/reset#token=RzCkoxXKSz0WJzWIIkAQNpDJ6yXUqZZMwtDA160iu5ldXToasDCy1QJSwvlwjlkt

链接有时效（实测约 1 小时），过期重新生成即可。配套的两个账号安全操作：

rexctl --dir /opt/fluxer users sign-out alice
rexctl --dir /opt/fluxer users disable-mfa alice

实测回显：

ok alice wasn't signed in anywhere.

ok alice doesn't use two-factor authentication.

sign-out 让目标账号在所有设备下线（改密码后应执行）；disable-mfa 用于用户丢失 TOTP 设备时解锁。

5.5 封禁、解封与删除

封禁必须给理由，理由取值受枚举约束（spam、scam、harassment、hate、threats、raids、automation、ban-evasion、impersonation、malware、doxxing 等）：

rexctl --dir /opt/fluxer users ban alice --reason spam -y

实测回显：

ok Banned alice.

不带 --reason 会被直接拒绝（Pass --reason.，退出码 2）。封禁后 users show alice 的 Banned 变 yes、Disabled 同步变 yes：

rexctl --dir /opt/fluxer users show alice

实测回显（节选账号状态段）：

Banned            yes
Disabled          yes

解封：

rexctl --dir /opt/fluxer users unban alice

实测回显：

ok Lifted the ban on alice.

删除账号会连同其数据一起清除，需用域名确认：

rexctl --dir /opt/fluxer users delete demo1 --confirm fluxer.test -y

实测回显：

ok Deleted demo1.

5.6 管理员权限

admins 只有三个动作：加、减、发一次性登录链接。

rexctl --dir /opt/fluxer admins add carol
rexctl --dir /opt/fluxer admins sign-in-link carol
rexctl --dir /opt/fluxer admins remove carol

实测回显：

ok carol is an admin.

ok Made a link that signs carol in. It works once, until 08:15 on 25 October.
https://fluxer.test/login#sign_in_link=C6jk_CBSgWmtUKnziRO4_s1MgH2RiObmWmi1AbUoB_w

ok Removed admin access from carol.

sign-in-link 生成的链接一次性有效，适合管理员忘密码又来不及走重置流程时应急；用后立即失效。

5.7 账号操作验证

任何变更都用 users show 复核，而不是只看 ok：

rexctl --dir /opt/fluxer users show alice

实测回显（解封后）：

Account           alice
ID                1563816061910908928
Email             none
Email confirmed   yes
Joined            25 Oct 2026
Last active       25 Oct 2026
Admin             no
Permissions       none
Two-factor        no
Banned            no
Disabled          no
Sessions          0

六、邀请与注册

注册策略决定「谁能注册」，邀请链接是其中「邀请制」档位的凭证。两者配合才能控制住一个半公开社区。

6.1 邀请链接的创建、列出与作废

rexctl --dir /opt/fluxer invites create --label 演示邀请 --uses 3 --expires 12h

实测回显：

ok Created an invite for 3 people. It expires at 22:03 on 25 October.
https://fluxer.test/register?registration_url=a155e59f-168e-47bc-b947-499a8350e556

参数默认值（来自 invites create --help）：--uses 默认 1（传 0 表示不限次数）、--expires 默认 7d（可写 12h、7d、never）、--label 仅供人辨认。

列出全部邀请：

rexctl --dir /opt/fluxer invites list

实测回显：

ID                                     Label      Used     Expires               Link
a155e59f-168e-47bc-b947-499a8350e556   演示邀请   0 of 3   22:03 on 25 October   https://fluxer.test/register?registration_url=a155e59f-168e-47bc-b947-499a8350e556
aa28e624-3728-4e05-bff1-acd2c6cca133   团队邀请   0 of 5   1 November            https://fluxer.test/register?registration_url=aa28e624-3728-4e05-bff1-acd2c6cca133
951b175e-0357-4360-8caf-e531d34b3d9b              0 of 1   1 November            https://fluxer.test/register?registration_url=951b175e-0357-4360-8caf-e531d34b3d9b
4959afb8-0b77-486c-9a72-0c41c1fbfba6   内部测试   0 of 5   1 November            https://fluxer.test/register?registration_url=4959afb8-0b77-486c-9a72-0c41c1fbfba6

Used 列显示「已用/上限」，用满即自动失效。作废：

rexctl --dir /opt/fluxer invites revoke a155e59f-168e-47bc-b947-499a8350e556

实测回显：

ok The invite link a155e59f-168e-47bc-b947-499a8350e556 doesn't work anymore.

6.2 注册策略四档

rexctl --dir /opt/fluxer registration --help

实测回显：


  Choose who can create an account

  Usage

    rexctl registration [command] [--flags]

  Commands

    approve <id>                       Approve a person waiting for approval
    deny <id>                          Turn down a person waiting for approval
    pending [--flags]                  List people waiting for approval
    set <open|approval|invite|closed>  Set who can create an account

  Flags

    --dir                              Folder with your instance
    -h --help                          Show help for a command
    -q --quiet                         Print only errors and results
    --verbose                          Print every step and command
    -y --yes                           Answer yes to every question and never prompt

切换到审批制（任何人都能申请，管理员逐个人工通过）：

rexctl --dir /opt/fluxer registration set approval -y

实测回显：

ok Anyone can ask for an account, and an admin approves each one.

切回邀请制：

rexctl --dir /opt/fluxer registration set invite -y

实测回显：

ok Only people with an invite link can create an account.

审批制下查看待审队列：

rexctl --dir /opt/fluxer registration pending

实测回显：

Nobody is waiting for approval.

有申请时该命令会列出待审 ID，再用 registration approve <id> 或 registration deny <id> 处理。四档语义对照：

档位	含义	适用场景
`open`	任何人打开页面即可注册	公开社区、演示环境
`approval`	任何人可申请，管理员审批	半公开社区、需要人工把关
`invite`	仅持邀请链接者可注册	内部团队、封闭社区
`closed`	关闭注册，仅管理员建号	上线初期、只读公告站

6.3 注册策略验证

策略切换后必须回读，确认写进实例数据库而不是只改了内存：

rexctl --dir /opt/fluxer config get registration.mode

实测回显：

Setting   registration.mode
Value     invite
Takes     open, approval, invite or closed
Applies   Right away
Help      Who can create an account. It works like rexctl registration set

七、配置管理

config 是 rexctl 里最常用的命令组：读一项、改一项、批量改、恢复默认，四个动作覆盖全部实例行为参数（172 项友好参数；加 --all 可见含内部变量的 518 项）。

7.1 读一项

rexctl --dir /opt/fluxer config get app_public.branding.product_name

实测回显：

Setting   app_public.branding.product_name
Value     Fluxer Lab
Takes     text
Applies   Right away
Help      Branding product name

四行卡片的信息量：当前值（Value）、合法取值（Takes）、生效时机（Applies）、官方说明（Help）。Applies 为 Right away 表示改完即生效；显示 Restarts ... 则说明要滚动重启对应服务。

7.2 改一项与批量改

rexctl --dir /opt/fluxer config set app_public.branding.product_name "Fluxer Lab"

实测回显：

ok Set app_public.branding.product_name to Fluxer Lab.

批量写法用 键=值 形式一次提交多项（config set <key>=<value>...），适合把一组相关参数一次性落库。改完立刻 config get 回读确认。

7.3 恢复默认会被拒绝的情况

rexctl --dir /opt/fluxer config unset app_public.branding.product_name

实测回显：

x Fluxer can't clear app_public.branding.product_name.
  Set another value with rexctl config set app_public.branding.product_name <value>.

退出码 3（refused）。原因不是权限问题，而是该参数没有可回退的默认值——品牌名必须显式给一个值。排障时应换思路：用 config set 填入合理值，而不是反复 unset。

7.4 列出全部参数

rexctl --dir /opt/fluxer config list | head -12

实测回显：

Setting                                                  Value                            Applies             Help
domain                                                   fluxer.test                      Restarts Fluxer     The domain people use to reach Fluxer
edge.mode                                                proxy                            Restarts Fluxer     Whether Fluxer serves HTTPS itself, sits behind your reverse proxy or behind a tunnel
edge.bind                                                0.0.0.0:8080                     Restarts edge       The address your reverse proxy or tunnel connects to
edge.http_port                                           80                               Restarts edge       The port Fluxer listens on for HTTP
edge.https_port                                          443                              Restarts Fluxer     The port Fluxer listens on for HTTPS
edge.public_port                                         443                              Restarts Fluxer     The port people use in Fluxer's address, when it differs from the one Fluxer listens on
edge.trusted_proxies                                     private_ranges                   Restarts edge       Proxies whose client address headers Fluxer trusts
voice.tcp_port                                           7881                             Restarts voice      The TCP port for voice and video
voice.udp_port                                           7882                             Restarts voice      The UDP port for voice and video
voice.public_ip                                                                           Restarts voice      The public IP address voice and video use, when Fluxer can't find it by itself
storage.endpoint                                         http://seaweedfs:8333            Restarts Fluxer     An S3-compatible object store to use instead of the bundled one

规模实测：config list | wc -l 为 173（1 行表头 + 172 项），config list --all | wc -l 为 519（1 行表头 + 518 项）。逐项参数含义与调优模板见《Fluxer 2026.1025.41605 配置参数详解》。

7.5 结构化读取

脚本里取值用 --json，避免解析人类可读的四行卡片：

rexctl --dir /opt/fluxer config get --json domain

实测回显：

{
  "key": "domain",
  "kind": "deployment",
  "type": "hostname",
  "value": "fluxer.test",
  "secret": false,
  "restarts": [
    "admin",
    "api",
    "edge",
    "gateway",
    "gifs",
    "media-proxy",
    "messages",
    "push",
    "snowflakes",
    "unfurl",
    "users",
    "worker"
  ],
  "help": "The domain people use to reach Fluxer"
}

restarts 数组直接告诉你改这项会重启哪些服务——改域名会动 12 个服务，必须安排在维护窗口。

7.6 配置操作验证

rexctl --dir /opt/fluxer config get app_public.branding.product_name

实测回显：

Setting   app_public.branding.product_name
Value     Fluxer Lab
Takes     text
Applies   Right away
Help      Branding product name

值已变为 Fluxer Lab，说明 config set 落库成功。

八、品牌、邮件与反向代理

这三组命令改的是「对外观感」与「接入方式」，改动幅度比单个配置项大，rexctl 用语义化命令把相关参数打包处理。

8.1 实例改名、配色与图标

rexctl --dir /opt/fluxer branding set --name "Fluxer Lab"

实测回显：

ok Your instance is called Fluxer Lab.

branding set 支持四项：--name（实例名）、--colour（十六进制主色，如 #4641d9）、--logo（Logo 图片文件）、--icon（图标图片文件）。它比直接 config set app_public.branding.* 多做了缓存刷新与前端资源重建，官方推荐优先用它。

8.2 邮件外发

rexctl --dir /opt/fluxer email test root@fluxer.test

实测回显：

x Fluxer couldn't send email. Email is off while accounts sign in with usernames.
  Check the settings, then run rexctl email set.

这是典型的「用户名登录模式不挂邮箱」状态：实例初始化为 --sign-in username 后，邮件通道默认关闭，测试发信会被明确拒绝。要启用就配 SMTP：

rexctl --dir /opt/fluxer email set --host smtp.example.com --port 587 \
  --username no-reply@example.com --password-file /root/.smtp.pw \
  --from "Rex Lab <no-reply@example.com>" --tls starttls

参数默认值：--port 默认 587，--tls 未指定时按端口推断（starttls/implicit/opportunistic/none）。口令用文件传入（--password-file，- 表示从标准输入读），避免出现在 shell 历史里。配好后 email test <地址> 收信验收；email off 一键停用外发。

8.3 自带反向代理接入

rexctl --dir /opt/fluxer proxy --help

实测回显：


  Use your own reverse proxy in front of Fluxer

  Usage

    rexctl proxy [command] [--flags]

  Commands

    off           Serve HTTPS directly with a certificate from Let's Encrypt
    on [--flags]  Serve plain HTTP for your own proxy

  Flags

    --dir         Folder with your instance
    -h --help     Show help for a command
    -q --quiet    Print only errors and results
    --verbose     Print every step and command
    -y --yes      Answer yes to every question and never prompt

proxy on 把实例切成「纯 HTTP 对内、由你的 Nginx/Caddy 终结 TLS」；--bind 指定监听地址（首次默认 127.0.0.1:8080，之后保留上次值）。proxy off 切回 Fluxer 自管 HTTPS 证书（Let's Encrypt）。切换后 rexctl doctor 会重新校验域名与证书链路。

8.4 首次设置令牌

rexctl --dir /opt/fluxer setup token

实测回显：

x Setup is already finished.
  Sign in at https://fluxer.test.

setup token 只在「浏览器建管理员」模式下有意义：安装完成但管理员尚未创建时，它给出网页设置令牌；已完成后固定回此提示（退出码 3）。管理员已在终端建好（--setup terminal）时同样如此。

九、备份、恢复、升级与交接

这一组命令决定「数据能不能找回、版本能不能退」。所有操作前先看 backup list 确认手里有可用备份。

9.1 立即备份

rexctl --dir /opt/fluxer backup

实测回显（输出节选，实测首尾）：

Fluxer stops for about a minute while rexctl copies your uploads.
Starting Fluxer: 4 of 7 services started, waiting for nats (0s)
...
ok Backed up your instance (148.7 KB).
Starting Fluxer again: 20 of 21 services ready, waiting for app-proxy (0s)
ok Fluxer is running again.
/opt/fluxer/backups/fluxer-fluxer.test-20261025-080055.tar.zst

备份期间实例会短暂停机（上传文件需要一致性快照），完成后自动拉起并打印产物路径。产物为 tar.zst，命名含域名、时间戳与版本。

9.2 列出备份

rexctl --dir /opt/fluxer backup list

实测回显：

File                                         Made                           Version           Size
fluxer-fluxer.test-20261025-080055.tar.zst   25 October 2026 at 08:00 UTC   2026.1025.41605   148.7 KB
fluxer-fluxer.test-20261025-072732.tar.zst   25 October 2026 at 07:27 UTC   2026.1025.41605   109.6 KB

9.3 校验备份完整性

rexctl --dir /opt/fluxer backup verify /opt/fluxer/backups/fluxer-fluxer.test-20261025-080055.tar.zst

实测回显：

ok The backup is complete. It has fluxer.test on Fluxer 2026.1025.41605, made 25 October 2026 at 08:00 UTC.

异地备份落地后务必跑一次 verify，确认传输没有截断——这是恢复成功率的唯一前置保证。

9.4 保留数量与存放位置

rexctl --dir /opt/fluxer backup keep
rexctl --dir /opt/fluxer backup location

实测回显：

/opt/fluxer/backups

默认保留 3 份，超出后每次备份自动删最旧的（但会保留 rollback 需要的那份）；backup keep all 表示全部保留，backup keep 7 改保留 7 份。backup location /data/backups 可把新备份写到独立磁盘，已存在的备份不迁移。

9.5 恢复

rexctl --dir /opt/fluxer restore --help

实测回显：


  Restore your instance from a backup. This works on a new machine too. Copy the backup file there and run this command.

  Usage

    rexctl restore <file> [--flags]

  Flags

    --confirm   Your instance's domain, to confirm without a prompt
    --dir       Folder with your instance
    --engine    Move the instance to another engine while restoring (docker)
    -h --help   Show help for a command
    -q --quiet  Print only errors and results
    --verbose   Print every step and command
    -y --yes    Answer yes to every question and never prompt

恢复是破坏性操作，要求用域名二次确认（--confirm fluxer.test）。它也能在新机器上重建实例：拷入备份文件、装好同版本 rexctl、执行同一条命令即可。

9.6 升级检查与回滚

rexctl --dir /opt/fluxer upgrade --check

实测回显：

ok Fluxer 2026.1025.41605 is up to date.

upgrade 默认先自动备份再升级（--no-backup 可跳过，不建议）；--to <版本> 指定目标版本，--prefetch 先下载稍后升级，--dry-run 只演练。升级后不满意：

rexctl --dir /opt/fluxer rollback --dry-run

rollback 回到上一个发布；--restore-database 连数据库一起回滚（升级后产生的新数据会丢，慎用）。回滚前同样建议先手动 backup 一份现状。

9.7 交还与接管

rexctl eject 把全部设置写进实例目录、停止 rexctl 对实例的接管，实例继续运行，此后可用 compose 自行管理；rexctl takeover 反向操作，把「手工 compose 建的实例」或「被 eject 的实例」交回 rexctl 托管（--dry-run 先看会改什么）。这两条命令构成「官方托管 ↔ 自行编排」的双向通道，迁移运维体系时不必重装。

9.8 卸载

rexctl --dir /opt/fluxer uninstall --keep-data

卸载会移除实例目录、自启服务与编排产物；加 --keep-data 保留数据库与备份，之后可用 rexctl install --take-over 重新接管。彻底清理则不加该参数（仍要求域名确认）。

十、日志查看

rexctl logs 把 20 个服务的日志统一收口，按服务名过滤，无需逐个找日志文件。

10.1 服务名与参数

rexctl --dir /opt/fluxer logs --help

实测回显：


  Show logs from your instance.

  The services are web, api, worker, gateway, voice, media, edge, admin, push, database, search, storage, cache, queue
  and internal.
  Without a service, rexctl shows every service.

  Usage

    rexctl logs [service] [--flags]

  Flags

    --dir        Folder with your instance
    -f --follow  Keep printing new lines
    -h --help    Show help for a command
    -q --quiet   Print only errors and results
    --since      Show lines newer than this, like 10m or 2h
    --verbose    Print every step and command
    -y --yes     Answer yes to every question and never prompt

可用的服务别名是逻辑分组而非逐个微服务：web（前端）、api、worker、gateway、voice、media、edge、admin、push、database、search、storage、cache、queue、internal。不写服务名即输出全部，排障时先看全量、再按组收窄。

10.2 查看指定服务日志

rexctl --dir /opt/fluxer logs api

实测回显（节选启动段）：

api | {"level":"info","time":"2026-10-25T07:30:00.880Z","service":"fluxer-api","env":"production","msg":"JetStream worker service initialized"}
api | {"level":"info","time":"2026-10-25T07:30:00.882Z","service":"fluxer-api","env":"production","msg":"Activity events initialized"}
api | {"level":"info","time":"2026-10-25T07:30:00.882Z","service":"fluxer-api","env":"production","msg":"KV deletion queue state is healthy"}
api | {"level":"info","time":"2026-10-25T07:30:00.882Z","service":"fluxer-api","env":"production","msg":"Initializing search indexes..."}
api | {"level":"info","time":"2026-10-25T07:30:00.882Z","service":"fluxer-api","env":"production","url":"http://meilisearch:7700","msg":"Using Meilisearch for search"}
api | {"level":"info","time":"2026-10-25T07:30:00.946Z","service":"fluxer-api","env":"production","msg":"Search backend initialized successfully"}

（日志为逐行 JSON，每行首列是服务名，可直接喂给 jq 过滤。）

10.3 按时间窗口取日志

rexctl --dir /opt/fluxer logs --since 2m

实测回显（节选）：

app-proxy | 2026-10-25T10:02:37.831715Z  INFO fluxer_app_proxy: starting Fluxer app proxy addr=0.0.0.0:8080
app-proxy | 2026-10-25T10:03:48.208730Z  INFO fluxer_app_proxy::branding_images: instance branding updated origins=[] instance_origins=["https://fluxer.test", "wss://fluxer.test"] product_name="Fluxer Lab" custom_css_bytes=0
admin | 2026-10-25T10:02:36.055368Z  INFO fluxer_admin: starting Fluxer admin service addr=0.0.0.0:8080
push | {"timestamp":"2026-10-25T10:02:35.938852Z","level":"INFO","fields":{"message":"push sidecar listening","addr":"0.0.0.0:8126","vapid_subject":"admin@fluxer.test"},"target":"fluxer_push::server"}
push | {"timestamp":"2026-10-25T10:02:35.941736Z","level":"INFO","fields":{"message":"connected successfully","server":"4222","max_payload":"1048576"},"target":"async_nats::connector"}

--since 接受 10m、2h 这类相对时间；配合 -f --follow 可实时盯盘，等价于 tail -f。刚才的 branding set 也能在这里看到落地痕迹（product_name="Fluxer Lab"），是验证品牌改动的好办法。

10.4 参数拼错的提示

rexctl --dir /opt/fluxer logs api --tail 3

实测回显：

Unknown flag: --tail.
Run rexctl logs --help to see every flag.

rexctl 没有 --tail（限行用 shell 管道 | tail -n 3），未知参数会明确拒绝并指向帮助，退出码 2。

十一、Shell 补全

rexctl 自带补全脚本生成器，支持 bash/zsh/fish/powershell：

rexctl --dir /opt/fluxer completion bash | head -8

实测回显：

# bash completion V2 for rexctl                               -*- shell-script -*-

__rexctl_debug()
{
    if [[ -n ${BASH_COMP_DEBUG_FILE-} ]]; then
        echo "$*" >> "${BASH_COMP_DEBUG_FILE}"
    fi
}

永久启用（bash）：

rexctl completion bash > /etc/bash_completion.d/rexctl

新开终端后输入 rexctl us<Tab> 即可补出 users，rexctl users <Tab> 补出 ban/create/delete/disable-mfa/list/reset-link/show/sign-out/unban。zsh 用 rexctl completion zsh > "${fpath[1]}/_rexctl"，fish 用 rexctl completion fish > ~/.config/fish/completions/rexctl.fish。

十二、命令速查表

场景	命令	关键点
看实例是否在跑	`rexctl --dir /opt/fluxer status`	退出码 0=运行、3=停止
启停与重启	`rexctl start` / `stop` / `restart`	`restart` 实测约 28 秒不可用
全面体检	`rexctl doctor`	17 项检查，异常退出码 3；`--fix` 自动修可修项
查账号	`rexctl users list [--admins] [--search x]`	`--json` 供脚本消费
建号	`rexctl users create <用户名>`	输出一次性设密码链接
重置密码	`rexctl users reset-link <用户名>`	链接约 1 小时有效
强制下线	`rexctl users sign-out <用户名>`	改密码后执行
封禁/解封	`rexctl users ban <用户名> --reason spam` / `unban`	`--reason` 必填且受枚举约束
删号	`rexctl users delete <用户名> --confirm <域名>`	数据一并删除
加/减管理员	`rexctl admins add/remove <用户名>`	另有 `sign-in-link` 一次性登录
建邀请	`rexctl invites create --uses 5 --expires 7d --label x`	默认 1 人、7 天
作废邀请	`rexctl invites revoke <ID>`	ID 从 `invites list` 取
切注册策略	`rexctl registration set open/approval/invite/closed`	回读 `config get registration.mode`
审批队列	`rexctl registration pending` / `approve <id>` / `deny <id>`	仅审批制有队列
读参数	`rexctl config get <键> [--json] [--reveal]`	四行卡片含 Takes/Applies
改参数	`rexctl config set <键> <值>` 或 `键=值 ...`	回读确认
恢复默认	`rexctl config unset <键>`	无默认值者被拒（退出码 3）
列全部参数	`rexctl config list [--all]`	172 项 / 518 项
改名配色	`rexctl branding set --name x --colour '#4641d9'`	比裸改配置多刷新缓存
配 SMTP	`rexctl email set --host ... --password-file ...`	口令走文件，别进 shell 历史
测试发信	`rexctl email test <地址>`	用户名登录模式下默认拒绝
切反代模式	`rexctl proxy on [--bind 127.0.0.1:8080]` / `off`	on=纯 HTTP 交给自有反代
立即备份	`rexctl backup`	短暂停机，输出 tar.zst 路径
校验备份	`rexctl backup verify <文件>`	异地落地后必跑
保留策略	`rexctl backup keep [数量	all]`
恢复	`rexctl restore <文件> --confirm <域名>`	新机器同样适用
升级	`rexctl upgrade [--check] [--to 版本]`	默认先自动备份
回滚	`rexctl rollback [--restore-database]`	带库回滚会丢升级后数据
交还/接管	`rexctl eject` / `rexctl takeover --dry-run`	官方托管与自行编排互转
看日志	`rexctl logs <服务> [--since 10m] [-f]`	15 个逻辑服务别名
补全	`rexctl completion bash`	写入 bash_completion.d

十三、常见问题

Q1：执行任何命令都报 x Fluxer isn't installed in /opt/fluxer.？

--dir 指错了目录或多实例机器没带 --dir。先 ls /opt/fluxer 确认有编排文件与 .rexctl/，再用正确的 --dir 重试。实测一套实例的目录里同时有 backups/、certs/、recovery-kit-root.txt，可据此辨认。

Q2：users create --email ... 报错？

安装时选了 --sign-in username 的实例，账号不挂邮箱，创建用户不要带邮箱参数（实测报 Pass a username. 或邮箱相关提示）。要邮箱登录，须在安装期用 --sign-in email 初始化；已装好的实例不能靠建号参数绕过。

Q3：users ban 报 Pass --reason.？

封禁必须给理由，且取值受枚举约束（spam、scam、harassment、hate、threats、raids、automation、ban-evasion、impersonation、malware、doxxing、intimate-images、explicit-content、adult-content、violence、self-harm、illegal、deception、exploits、report-abuse）。补上 --reason spam 再执行。

Q4：config unset 被拒绝，退出码 3？

该参数没有默认值可回退，rexctl 不允许清空。用 config set 显式给一个合法值，或先用 config list 查 Takes 列的可接受取值。

Q5：改了 domain 之后实例卡住/接口超时？

config get --json domain 的 restarts 数组显示改域名会重启 12 个服务，整个过程是滚动重启，期间接口会短暂不可用。等 status 恢复 ok Fluxer is running. 后再验证；生产务必放在维护窗口。

Q6：backup 期间站点打不开？

备份需要一致性快照，实例会主动停约一分钟（回显首行原文即提醒），完成后自动拉起。要大文件量实例的备份安排在低峰；backup keep/location 先把保留份数与存放磁盘规划好，避免磁盘被历史备份占满。

Q7：email test 报 Email is off while accounts sign in with usernames.？

用户名登录模式默认关闭邮件通道（该模式不需要邮箱验证）。先 rexctl email set 配好 SMTP，再 email test 验收；不需要邮件就忽略此提示，注册与密码重置走邀请链接/重置链接即可。

Q8：脚本里怎么判断实例健康？

用退出码而不是文本匹配：status 返回 0 为运行、3 为停止；doctor 返回 0 为全部检查通过、3 为发现问题；用法错误统一 2。配合 -q 消除装饰性输出，取值用 --json。

十四、参考链接

官方自托管文档：https://docs.fluxer.app/operator/ （查询日期 2026-10-25）
rexctl 命令参考：https://docs.fluxer.app/operator/rexctl/ （查询日期 2026-10-25）
版本与下载接口：https://fluxer.dev/rexctl/release.json （查询日期 2026-10-25）
GitHub 仓库：https://github.com/fluxerapp/fluxer （查询日期 2026-10-25）
本专栏姊妹篇：