ClearFlask 2.7.2 配置参数详解

目标：把 ClearFlask 2.7.2 self-host 的配置体系讲透——全局配置文件 server/config-selfhost.cfg 的语法与每一项参数、Node 侧 connect.config.json、约 20 个 CLEARFLASK_* 环境变量的注入与优先级、首次启动自动生成的安装密钥，以及改完如何生效与验证。全文以 2026-11-01 本地实测环境为例证，关键值均来自真实配置文件与命令回显。

一、环境信息

⚠️ 宿主前置：本文的重启/进程核查命令按真机（systemd 或等价进程管理）形态书写。本系列实测环境的两套服务由编排文件拉起（见 《ClearFlask 2.7.2 Docker Compose 部署指南》），真机部署需自备对应 unit 或以你实际的进程管理方式等价执行。

二、配置体系总览

ClearFlask 的配置分三层：

本文聚焦前两层；项目层 Config 的完整读写实操见 《ClearFlask 2.7.2 常用 CLI 命令与 API 详解》。

2.1 cfg 文件语法

config-selfhost.cfg 是 Java 配置框架（kik ConfigSystem）的属性文件，每行一个参数，键为实现类全限定名 + $Config. + 属性名：

# 井号行为注释；键=值，也支持键:值写法
com.smotana.clearflask.web.Application$Config.domain=localhost
com.smotana.clearflask.web.Application$Config.defaultSearchEngine:READWRITE_MYSQL

被注释掉的行（行首 #）表示"采用代码内默认值"——官方模板把不常用项全部注释好放在文件里，取消注释即启用，这是阅读该文件最重要的心智模型。

三、域名与访问控制组

💡 环境变量等价项：CLEARFLASK_DOMAIN、CLEARFLASK_SUPER_ADMIN_EMAIL、CLEARFLASK_SIGNUP_ENABLED、CLEARFLASK_AUTH_COOKIE_SECURE、CLEARFLASK_TELEMETRY_ENABLED。另有 CLEARFLASK_TRUSTED_PROXY_COUNT（默认 1，即 Node 前端服务这一层；前面再加一层负载均衡则设 2）——限流按该位置取客户端 IP，设错会让限流打在代理 IP 上。

四、数据源与搜索引擎组

ClearFlask 的源数据在 DynamoDB 兼容存储，MySQL/ElasticSearch 只是可热切换的搜索索引（实测 MySQL 库 clearflask 仅 7 张索引表：account / comment / comment_parent_id / idea / idea_funders / idea_tags / user，账号等业务数据实际在 DynamoDB 单表 clearflaskprimary 中——排障时别在 MySQL 里找业务数据）。

defaultSearchEngine 取值（迁移中间态用于双写灰度）：

💡 官方默认值是 ElasticSearch——cfg 里找不到这一行时按 ES 运行。MySQL 与 ES 间在线迁移走 JMX 调用 ProjectResource.createIndexes / reindexProjects 配合双写四步切换，完整流程见官方 README "Migration between Elasticsearch/MySQL" 节；小项目用 MySQL（前缀匹配），大项目用 ES（词形归并，搜 "Johnny" 命中 "Jonathan"）。

五、对象存储组（附件/S3）

六、邮件组

SMTP 形态需填的 8 项（官方 Gmail 示例）：

EmailServiceImpl$Config.smtpStrategy=SMTP_TLS          # SMTP_TLS(587) / SMTPS(465) / SMTP(25)
EmailServiceImpl$Config.smtpHost=smtp.gmail.com
EmailServiceImpl$Config.smtpPort=587
EmailServiceImpl$Config.smtpUser=my.name@gmail.com
EmailServiceImpl$Config.smtpPassword=<应用专用密码>     # 开了 2FA 必须用 app password
EmailServiceImpl$Config.emailDisplayName=ClearFlask for MyCompany
EmailServiceImpl$Config.fromEmailLocalPart=my.name
EmailServiceImpl$Config.fromEmailDomainOverride=gmail.com

环境变量捷径：设 CLEARFLASK_SMTP_HOST 即自动把 useService 切到 SMTP，配合 CLEARFLASK_SMTP_PORT/USER/PASSWORD/STRATEGY 与 CLEARFLASK_EMAIL_DISPLAY_NAME/FROM_LOCAL_PART/FROM_DOMAIN。

七、安装密钥组（首启自动生成）

首次启动时以下 5 组密钥自动生成并写入 cfg（本实测值示意，部署时务必以你机器上的新值为准，切勿复用）：

⚠️ 官方 README 安全提示：此行为之前的老安装共享公开已知的默认密钥——启动日志出现 SECURITY: 警告必须按注释命令重新生成。cfg 文件含全部密钥，权限收紧（chmod 600），备份视同备份数据库。

八、Connect 协同与证书形态组

Java 与 Node 两套服务用共享令牌互信：

connect.config.json 实测关键字段：

{
  "connectToken": "7cb1e1c26f5d4705a213529257d081c6",
  "parentDomain": "localhost",
  "apiBasePath": "http://<java服务主机>:8080",
  "disableAutoFetchCertificate": true,
  "forceRedirectHttpToHttps": false
}

• parentDomain：项目门户按 <slug>.<parentDomain> 寻址（slug=demo → demo.localhost）。
• apiBasePath：Node 转发 API 请求的 Java 侧地址。
• 证书三开关组合（官方四形态）：

💡 实测优先级证据：本环境 connect.config.json 里的令牌是初始值 7cb1e1c2…，与 .env/cfg 的 2b2677bb… 不一致，但全链路 API 实测以 2b2677bb… 为准并成功——环境变量注入优先于文件值（README 原话 "always take precedence over values in the file"）。三处令牌以 CLEARFLASK_CONNECT_TOKEN 环境变量为唯一事实源最省心；不一致的典型症状是 Java 侧对 Node 转发的请求回 401。

九、可选集成组

十、环境变量注入全表（Java 服务侧）

官方支持约 20 个 CLEARFLASK_* 变量在启动时注入并强制覆盖 cfg 文件值（适配 Railway/PikaPods/Elestio 等无法编辑持久文件的平台）：

Node 服务侧支持：CLEARFLASK_CONNECT_TOKEN、CLEARFLASK_DOMAIN、CLEARFLASK_API_BASE_PATH、CLEARFLASK_LISTEN_PORT、CLEARFLASK_DISABLE_AUTO_FETCH_CERTIFICATE、CLEARFLASK_FORCE_REDIRECT_HTTPS（覆盖 connect.config.json）。另有 CLEARFLASK_CREATE_SERVER_CONFIG_IF_MISSING / CLEARFLASK_CREATE_CONNECT_CONFIG_IF_MISSING 控制首启是否自动生成配置文件。

十一、修改与生效流程（实测）

1. 改配置（示例：关闭注册）：

vi /opt/clearflask/server/config-selfhost.cfg
# signupEnabled=true → false

2. 重启 Java 服务进程使其生效（真机形态）：

systemctl restart clearflask-server

⚠️ 本系列实测环境以部署编排的等价重启操作执行；真机需自备 unit 文件（ExecStart 指向 Java 服务启动命令，Environment 注入 CLEARFLASK_*）。

3. 验证生效（服务器视角，实测回显）：

$ ps -ef | grep 'catalina.base' | grep -v grep | head -1
root  792229  792202 15 19:32 ? 00:05:32 /opt/java/openjdk/bin/java ... -Xms256m -Xmx512m ... org.apache.catalina.startup.Bootstrap start
$ curl -s http://127.0.0.1:8130/api/health
ok
$ ss -ltn | grep ':8130\b'
LISTEN 0 4096 0.0.0.0:8130 0.0.0.0:*

十二、实测排障记录

十三、相关文章与参考

• 《ClearFlask 2.7.2 介绍与选型指南》
• 《ClearFlask 2.7.2 Docker Compose 部署指南》
• 《ClearFlask 2.7.2 常用 CLI 命令与 API 详解》
• 官方 README（配置/环境变量/证书/迁移权威来源）：https://github.com/clearflask/clearflask
• Helm values 形态的配置对照（K8s 部署）：https://github.com/clearflask/clearflask/blob/master/clearflask-helm/README.md