Fluxer 2026.1025.41605 配置参数详解

目标：本文系统讲解 Fluxer 自托管实例的配置参数体系——三层配置结构（部署层 / rexctl config 实例行为层 / 内部环境变量层）、rexctl config 四个子命令的实测用法、172 项实例行为参数按 25 个参数域的全量清单与生效时机，以及实例改名、注册策略、SMTP、SSO、域名迁移五个常用调优场景的落地模板。全部命令与回显来自 2026-10-25 的真实实例实测（Ubuntu 22.04.5 LTS / rexctl 与 Fluxer 2026.1025.41605）。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（amd64）
• 组件版本：Fluxer 2026.1025.41605（rexctl 与实例同版本）
• 运维工具：rexctl 2026.1025.41605（官方运维 CLI，全部配置操作入口）
• 实例目录：/opt/fluxer（rexctl 托管形态；本文所有命令均带 --dir /opt/fluxer）
• 实例地址：https://fluxer.test（评测环境私有后缀域名，边缘以纯 HTTP 监听 8080）
• 演示账号：管理员 root / 密码 q1w2e3r4（演示口令，生产必须换强密码）
• 实例安装方式：rexctl 非交互安装，注册策略 invite，详见《Ubuntu 22.04 安装 Fluxer 2026.1025.41605 指南》

二、前置条件

动手改参数前，确认以下三件事：

1. 实例在运行：rexctl --dir /opt/fluxer status 输出 ok Fluxer is running.；停止状态下多数参数仍可改，但标注「Right away」的即时生效无从谈起；
2. 知道实例目录：rexctl 以 --dir 定位实例（默认 /opt/fluxer），一台机器多套实例时务必显式带 --dir，避免改错对象；
3. root 或等价权限：rexctl 需要访问运行引擎套接字与实例目录，实测全程以 root 执行。

验证配置通道可用（读一项参数）：

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

能出这张小卡片，说明实例数据库可连、配置通道正常。

三、参数查看与修改方式

3.1 三层配置体系：先搞清楚改哪一层

Fluxer 的配置分三层，修改通道与持久化位置各不相同：

要点：

• 日常运维只碰第②层（rexctl config）与少量第①层参数（它们也在 172 项清单里，如 domain、edge.*、voice.*）；
• 第③层用 rexctl config list --all 可见（实测 518 项，含全部 FLUXER_*），用于排障时核对渲染结果，不要试图用 config set 直接写它们——友好层参数会覆盖你的推导；
• 手工编排（非 rexctl 托管）形态下没有 rexctl，第①③层体现为 .env 文件，第②层仍在数据库里、启动后由管理面板或 API 调整，见《Fluxer 2026.1025.41605 Docker Compose 部署指南》。

3.2 rexctl config 四个子命令

rexctl --dir /opt/fluxer config --help

实测回显：

  Read and change Fluxer's settings

  Usage

    rexctl config [command] [--flags]

  Commands

    get <key> [--flags]                   Show one setting
    list [--flags]                        List every setting with its value and help
    set <key> <value> | <key>=<value>...  Change one or more settings
    unset <key>...                        Go back to the default for one or more settings

  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

四个子命令的职责：

• config list：全量列出参数（友好层 172 项；加 --all 连内部层共 518 项），列为 Setting / Value / Applies / Help 四栏；
• config get <键>：读单项，输出取值、可接受值（Takes）、生效时机（Applies）、说明（Help）；
• config set <键> <值> 或 config set <键>=<值> ...：改一项或一次改多项；
• config unset <键>...：恢复默认值——注意并非所有参数都能 unset，无默认可回退的会被拒（实测见「七、常见问题」Q1）。

改一项参数并回读的完整闭环（实例改名，品牌域参数）：

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

实测回显：

ok Set app_public.branding.product_name to Fluxer Lab.

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

3.3 生效时机（Applies）与敏感值显示

每项参数的 Applies 列标注了改动何时生效，实测分布（172 项）：

config set 之后 rexctl 会按该参数的标注自动完成相应重启，无需手工干预；标注「Right away」的改完即用。

敏感值显示规则：口令、密钥类参数在 config list/get 中不回显明文，已配置显示 set、未配置显示 not set（实测 storage.secret_key 显示 set，sso.client_secret、billing.stripe_secret_key 显示 not set）。排障时凭此判断「配没配」，想确认内容只能重设。

四、参数总览

友好层 172 项参数按前缀分为 25 个参数域，分布如下（按项数排序）：

排障提示：rexctl config list --all 会把内部 FLUXER_* 变量一并列出（实测全表 518 项），每项同样带 Applies 标注（如 FLUXER_API_MEMORY_LIMIT 2560mb、FLUXER_API_POSTGRES_MAX_CONNECTIONS 12）。这一层是 rexctl 按机器规格与友好层参数渲染的结果，核对渲染是否符合预期时有用，日常不要直接改。

五、核心参数分类详解

以下按域逐项列出 172 项参数。「默认值」列为本实测实例的当前值（多数即出厂默认；空表示未设置）；「生效」列为 Applies 标注。

5.1 站点域名与公告：domain / notice（2 项）

5.2 边缘接入：edge.*（6 项）

实测环境即 proxy + bind 0.0.0.0:8080 形态（装时 --behind-proxy --bind 0.0.0.0:8080），由前置代理终结 TLS；直接暴露公网则用自带 HTTPS 形态（edge.mode 默认 + 80/443 放行），证书自动签发。

5.3 语音视频：voice.*（3 项）

5.4 对象存储：storage.*（6 项）

5.5 出向网络：network.*（4 项）

服务器访问外网需代理时（如推送中继、外链 unfurl），在这里配，而不是改系统环境变量。

5.6 引擎、部署单元与内存：engine.host / images.* / memory.profile（10 项）

正常情况下 images.* 由 rexctl 随版本统一管理，只有「拉不动官方仓库要换镜像站」（images.registry）或「锁定/替换某个基础组件版本」时才需要动。

5.7 注册、登录与人机验证：registration.* / auth.* / captcha.*（9 项）

注册策略的日常切换建议用 rexctl registration set <open|approval|invite|closed>（语义化输出，且会联动 registration.admin_registration_urls_enabled），实测见 6.2 与《Fluxer 2026.1025.41605 常用 CLI 命令与工具详解》第六节。

5.8 账号生命周期：accounts.*（12 项）

这一域是合规与数据占用的关键：长期运营务必审视 inactivity_deletion（默认 730+30 天）与 unclaimed_account_cleanup（默认 90 天）是否符合你的保留策略。

5.9 外发邮件：integrations.email.*（9 项）

不配邮件的后果很实际：密码重置、闲置删除警告、新 IP 授权等邮件都发不出去。生产建议尽早配置，模板见 6.3。也可以用 rexctl email 命令组引导配置。

5.10 单点登录：sso.*（16 项）

标准 OIDC 参数集，对接 Keycloak/Authentik/Entra ID 等均可。模板见 6.4。

5.11 实例级策略：policy.*（12 项）

5.12 品牌与法务：app_public.*（19 项）

品牌 16 项（全部立即生效，值多为素材 URL）：

法务 3 项（均立即生效，空为未设置）：app_public.legal.terms_url（服务条款）、app_public.legal.privacy_url（隐私政策）、app_public.legal.guidelines_url（社区准则）。对外开放的实例务必补齐这三项。

品牌调整也可用 rexctl branding 命令组操作；本文 6.1 给出 config set 实测闭环。

5.13 域名迁移：domain_migration.*（10 项）

换域名不是改一下 domain 就完事——旧域名的客户端、外链、媒体地址需要灰度过渡，这一域就是干这个的（全部立即生效）：

典型顺序：新域名解析就绪 → 开 enabled 并小比例灰度 → 观察 → 拉满 10000 基点 → config set domain <新域名>（重启整机）→ 稳定后关迁移。

5.14 其余参数域速览

以下域面向灰度发布/内部架构/商业化，日常运维很少动，列表备查（均立即生效）：

• gateway_rollout.*（9 项）：网关内部架构 rollout。session_rollout_percentage/guild_rollout_percentage（灰度百分比，均 100）、session_rollout_mode（modulo）、max_concurrent_session_starts（512）/max_concurrent_guild_starts（256）、gateway_dispatch_relay_shards（32）/gateway_dispatch_relay_max_queue（50000）、rpc_request_timeout_ms（10000）、voice_e2ee_scope（guild_feature_only）。
• voice_p2p.*（9 项）：语音 P2P 直连灰度。enabled（false）、max_participants（2）、rollout_basis_points（0）、rollout_salt（voice-p2p-v1）、rollout_country_codes、included/excluded_user_ids、included_guild_ids、include_premium_users（false）。小圈子通话直连省语音服务器流量。
• guild_visits.*（5 项）：「不加入即可浏览社区」灰度。enabled（false，总开关/kill switch）、user_basis_points（0）、user_salt（guild-visits-user-v1）、included/excluded_user_ids。
• media.attachment_decay.*（9 项）：附件衰减清理。enabled、curve、min/max_size_mb、min/max_lifetime_days、max_eligible_size_mb、renew_threshold_days、renew_window_days（全空=未启用）。存储吃紧的实例可按「大而久未被访问的附件先清理」思路启用。
• billing.*（10 项）：商业化计费（Stripe）。enabled、prices、legacy_prices、default_currency、country_currencies、automatic_tax、tax_id_collection、terms_consent_required、stripe_secret_key（敏感）、stripe_webhook_secret（敏感）。自用实例保持空即可。
• integrations.bluesky.*（7 项）：Bluesky 集成（enabled、client_name 默认 Fluxer、client_uri、logo_uri、policy_uri、tos_uri、keys）。
• integrations.gif.klipy_api_key（1 项，敏感）：GIF 搜索（Klipy）API Key；integrations.youtube.api_key（1 项，敏感）：YouTube 嵌入解析 API Key。
• experiment_delivery.*（2 项）：实验配置下发轮询，poll_interval_seconds（300）、poll_jitter_percent（15）。
• push_relay.relay_consent_accepted（1 项）：是否已同意官方推送中继的服务条款（移动推送走官方中继时需要置 true）。

六、生产配置模板（常用调优场景实测）

6.1 实例改名与品牌

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

实测回显：

ok Set app_public.branding.product_name to Fluxer Lab.

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

立即生效，客户端刷新即见。Logo/favicon/主题色等同理（5.12），均「Right away」。

6.2 注册策略切换（开放↔审批↔邀请↔关闭）

语义化命令（推荐，输出人类可读的确认语）：

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

实测回显：

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

Nobody is waiting for approval.

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

等价地也可以 config set registration.mode approval，两者写同一处（registration.mode 的 Help 原文即「It works like rexctl registration set」）。审批模式下待审队列的 approve/deny 操作见《Fluxer 2026.1025.41605 常用 CLI 命令与工具详解》第六节。

6.3 SMTP 外发邮件（模板）

安装时 --skip-email 跳过的，事后补配（本实测未接真实 SMTP，以下为按 5.9 参数组织的模板；也可用 rexctl email 命令组引导）：

rexctl --dir /opt/fluxer config set \
  integrations.email.delivery=smtp \
  integrations.email.smtp.host=smtp.example.com \
  integrations.email.smtp.port=587 \
  integrations.email.smtp.tls_mode=starttls \
  integrations.email.smtp.username=fluxer@example.com \
  integrations.email.smtp.password='<SMTP密码>' \
  integrations.email.from_email=noreply@example.com \
  integrations.email.from_name="Fluxer Lab"

配完用一次密码重置链路验证（rexctl users reset-link <用户> 触发的邮件）确认可达。全部邮件参数「Right away」，改完即发。

6.4 对接 OIDC 单点登录（模板）

rexctl --dir /opt/fluxer config set \
  sso.enabled=true \
  sso.issuer=https://idp.example.com/realms/fluxer \
  sso.client_id=fluxer \
  sso.client_secret='<Client Secret>' \
  sso.display_name="Corporate SSO" \
  sso.button_label="用公司账号登录"

要点：sso.auto_provision 默认 true（首登自动建号）；只许 SSO 登录再加 sso.enforced=true；限制邮箱域名用 sso.allowed_domains。IdP 侧回调地址按 IdP 文档指向实例域名即可。

6.5 换域名（灰度迁移）

# 1) 新域名解析与证书就绪后，开启迁移并小比例灰度
rexctl --dir /opt/fluxer config set domain_migration.enabled=true domain_migration.rollout_basis_points=500
# 2) 观察无异常后拉满（10000 基点 = 100%）
rexctl --dir /opt/fluxer config set domain_migration.rollout_basis_points=10000
# 3) 切主域名（重启整机，有短暂中断）
rexctl --dir /opt/fluxer config set domain chat.example.com
# 4) 稳定运行一段时间后关闭迁移
rexctl --dir /opt/fluxer config set domain_migration.enabled=false

七、常见问题

Q1：config unset 报 x Fluxer can't clear ... 被拒？ 实测：

$ 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>.
[exit=3]

unset 的语义是「回到默认值」；没有默认可回退的参数（如产品名，卸载即无意义）会被拒，退出码 3。按提示用 config set 给一个新值即可。

Q2：为什么 config list 里密码类参数只显示 set / not set？ 敏感值不回显明文（3.3）。判断「配没配」看这两个字即可；内容忘了就只能重设，实例数据库里存的是密文。

Q3：改参数会把服务改挂吗？ 看 Applies 列：142/172 项「Right away」无感生效；标注「Restarts ...」的会触发对应服务滚动重启（整机级参数有秒级到分钟级中断），config set 后 rexctl 自动完成，无需手工 restart。中断敏感的改动放在低峰期。

Q4：rexctl config 和 /opt/fluxer 下的编排文件是什么关系？ 编排文件（docker-compose.yml 等）是 rexctl 依据①②层参数渲染的产物，手改会在下次 rexctl 操作时被打回。一切改动走 rexctl config set（或安装期参数），让 rexctl 负责渲染与重启。手工编排（bundle）形态对应物是 .env，见《Fluxer 2026.1025.41605 Docker Compose 部署指南》。

Q5：config list --all 里的 FLUXER_* 变量能直接 set 吗？ 不建议。那是内部渲染层（518 项全量表的一部分），友好层参数会覆盖你的推导值。例如想调 API 内存，正确入口是 memory.profile 这类友好层参数，而不是 FLUXER_API_MEMORY_LIMIT。

Q6：配置会随备份一起走吗？ 会。实例行为层（172 项）存在实例数据库里，rexctl backup 产物（/opt/fluxer/backups/*.tar.zst）包含数据库，restore 后配置随之回来。装机参数另存于 /opt/fluxer/.rexctl/ 状态目录，同机恢复无需重答。

八、参考链接

• Fluxer 官方文档：https://docs.fluxer.app
• Fluxer 官网：https://fluxer.app
• Fluxer 源码仓库（AGPL-3.0）：https://github.com/fluxerapp/fluxer
• 系列文档：《Fluxer 2026.1025.41605 介绍与选型指南》、《Ubuntu 22.04 安装 Fluxer 2026.1025.41605 指南》、《Fluxer 2026.1025.41605 Docker Compose 部署指南》、《Fluxer 2026.1025.41605 常用 CLI 命令与工具详解》