ClearFlask 2.7.2 Docker Compose 部署指南

目标：在一台 Linux 服务器上，用 Docker Compose 把 ClearFlask 2.7.2 的 self-host 全栈（clearflask-server + clearflask-connect + MariaDB + LocalStack）拉起、验证并注册超级管理员，覆盖编排文件定稿、共享令牌生成、首次启动配置自动生成、可用性取证、升级回滚与端口/子网/证书排障。全文命令与回显均为 2026-11-01 本地实测照抄。

一、环境信息

项目	值
宿主 OS	Linux 7.0.0-38-generic（x86_64）
Docker	29.9.2
Docker Compose	v5.6.1（`docker compose` 子命令）
组件版本	ClearFlask 2.7.2（2026-10-31 发布，镜像 tag 固定 `2.7.2`）
部署目录	`/opt/clearflask`（本文示例，任意可写目录均可）
对外端口	`8130`（映射 connect 的 9080；官方默认 80/443，见第八节排障）
辅助工具	openssl（生成令牌）、curl（验证）
内存建议	可用 ≥ 2 GB（Java + Node + MariaDB + LocalStack 四件套）

💡 组件定位、与 Fider/Astuto 的选型对比见《ClearFlask 2.7.2 介绍与选型指南》。

二、部署架构与组件清单

ClearFlask self-host 由 2 个自有组件 + 2 个内置依赖组成（官方 docker-compose.self-host.yml 的 with-deps profile 即此四件套）：

服务	镜像	角色	内部端口	宿主发布
clearflask-server	`ghcr.io/clearflask/clearflask-server:2.7.2`	Java/Tomcat REST API 与业务核心	8080	❌ 不发布（仅 connect 内网可达）
clearflask-connect	`ghcr.io/clearflask/clearflask-connect:2.7.2`	Node.js SSR、静态文件、限流封禁、证书管理	9080 / 9443	✅ `8130:9080`
mysql-db	`mariadb:10.5`	搜索/过滤索引（`READWRITE_MYSQL` 引擎）	3306	❌
localstack	`localstack/localstack:0.14.3`	DynamoDB 兼容源数据 + S3 附件 + SES 邮件模拟	4566	❌

请求链路：浏览器 → connect（SSR/限流）→ server（API）→ localstack（源数据）/ mysql（索引）。两个自有组件用一份安装专属共享令牌 CLEARFLASK_CONNECT_TOKEN 互相鉴权，compose 缺它直接拒绝启动（${CLEARFLASK_CONNECT_TOKEN:?...} 语法强制）。

⚠️ 官方明确不建议把 server 的 8080 发布到宿主——绕过 connect 会失去限流与封禁能力。本文编排全程不发布 8080/3306/4566。

三、前置条件

Docker 与 Compose v2+ 就绪：

$ docker --version
Docker version 29.9.2, build 29.9.2
$ docker compose version
Docker Compose version v5.6.1

目标端口空闲（本文用 8130；若沿用官方 80/443 需 root 或 capability）：

$ ss -ltn | grep -E ':8130\b' || echo "8130 空闲"
8130 空闲

mkdir -p /opt/clearflask && cd /opt/clearflask

四、编排文件与共享令牌

4.1 生成 .env 令牌

官方 Quick start 第一步，令牌随机生成、写入编排文件同目录的 .env（compose 自动读取）：

echo "CLEARFLASK_CONNECT_TOKEN=$(openssl rand -hex 16)" > .env

本例生成值（下文配置篇与 API 篇均以此为例）：2b2677bb5b9b4c98866c3daacd90c746。

4.2 定稿编排文件

官方文件默认 latest 标签与 80/443 端口；生产建议固定版本号并把入口改到非特权端口。以下为本实测定稿（存为 /opt/clearflask/docker-compose.yml），与官方差异仅三处：镜像 tag 固定 2.7.2、端口 8130:9080、server 增加堆限制与遥测关闭两项：

name: clearflask-stack
services:
  clearflask-connect:
    image: ghcr.io/clearflask/clearflask-connect:2.7.2
    depends_on:
      - clearflask-server
    ports:
      - 8130:9080
    environment:
      - NODE_ENV=production
      - ENV=selfhost
      - CLEARFLASK_CREATE_CONNECT_CONFIG_IF_MISSING=1
      - CLEARFLASK_CONNECT_TOKEN=${CLEARFLASK_CONNECT_TOKEN:?set a generated shared token in .env}
      - CLEARFLASK_DISABLE_AUTO_FETCH_CERTIFICATE=true
      - CLEARFLASK_FORCE_REDIRECT_HTTPS=false
    volumes:
      - ./connect:/opt/clearflask/
  clearflask-server:
    image: ghcr.io/clearflask/clearflask-server:2.7.2
    environment:
      - CLEARFLASK_ENVIRONMENT=PRODUCTION_SELF_HOST
      - CLEARFLASK_CREATE_SERVER_CONFIG_IF_MISSING=1
      - CLEARFLASK_CONNECT_TOKEN=${CLEARFLASK_CONNECT_TOKEN:?set a generated shared token in .env}
      - CLEARFLASK_TELEMETRY_ENABLED=false
      - CATALINA_OPTS=-Xms256m -Xmx512m
    volumes:
      - ./server:/opt/clearflask/
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:8080/api/health" ]
      interval: 5s
      timeout: 15s
      retries: 2
  mysql-db:
    image: mariadb:10.5
    command:
      - 'mysqld'
      - '--port=3306'
      - '--sql-mode=IGNORE_SPACE'
      - '--explicit-defaults-for-timestamp'
      - '--secure-file-priv=/tmp'
    volumes:
      - ./data/mysql:/var/lib/mysql
      - ./mysql-db:/docker-entrypoint-initdb.d
    environment:
      - MYSQL_ROOT_PASSWORD=clearflask
  localstack:
    profiles:
      - with-deps
    image: localstack/localstack:0.14.3
    expose:
      - 4566
      - 4571
    environment:
      - DEFAULT_REGION=us-east-1
      - LOCALSTACK_HOSTNAME=localstack
      - HOSTNAME_EXTERNAL=localstack
      - SERVICES=dynamodb,ses,s3
      - LS_LOG=warn
      - START_WEB=0
      - USE_SSL=0
      - FORCE_NONINTERACTIVE=true
      - DATA_DIR=/tmp/localstack/data
      - LEGACY_PERSISTENCE=1
    volumes:
      - ./data/localstack:/tmp/localstack

要点说明：

localstack 挂在 with-deps profile 下：不加 --profile with-deps 则不起 LocalStack，适合已有真实 AWS/DynamoDB 兼容服务的场景；本地全栈必须带上。
mysql-db 无 profile，默认随栈启动；root 密码 clearflask 是官方内置的众所周知值，靠"不发布 3306 到宿主"保安全，切勿外暴。
CLEARFLASK_DISABLE_AUTO_FETCH_CERTIFICATE=true 与 CLEARFLASK_FORCE_REDIRECT_HTTPS=false：本机无域名无证书环境关闭 Let's Encrypt 自动签发与 HTTPS 强跳（connect 实际仅监听 9080，日志 App on 9080 (selfhost)）。
多机/CI 需要固定容器名或子网时，可另加 container_name 与自定义网络 ipam 段（见第八节排障）。

五、启动全栈

$ docker compose --profile with-deps up -d

拉起后 ps 实测回显（2026-11-01，运行约 1 小时后采集）：

$ docker compose ps
NAME                        IMAGE                                          STATUS
clearflask-2.7.2-server     ghcr.io/clearflask/clearflask-server:2.7.2     Up 55 minutes (healthy)
clearflask-2.7.2-connect    ghcr.io/clearflask/clearflask-connect:2.7.2    Up 2 hours
clearflask-2.7.2-mysql      mariadb:10.5                                   Up 2 hours
clearflask-2.7.2-localstack localstack/localstack:0.14.3                   Up About an hour

💡 server 的 (healthy) 来自编排内 healthcheck（容器内 curl -f http://localhost:8080/api/health），是判断 Java 侧就绪的最快信号。

启动顺序与等待：server 配置项 startupWaitUntilDeps=true（首次生成的 cfg 默认值）让 Java 进程轮询等待 DynamoDB/MySQL 可用后才初始化；实测冷启动 Tomcat 日志 Server startup in 13309 ms（首次含建表可达 20+ 秒，dev-notes 记录首启 23815 ms）。

5.1 首次启动自动生成的文件

CLEARFLASK_CREATE_*_CONFIG_IF_MISSING=1 使首次 up 在挂载目录生成两份配置：

/opt/clearflask/
├── docker-compose.yml
├── .env
├── server/config-selfhost.cfg      # Java 侧主配置（C1 专篇逐项详解）
├── connect/connect.config.json     # Node 侧配置
└── data/
    ├── mysql/                      # MariaDB 数据目录
    └── localstack/                 # DynamoDB/S3/SES 持久化

config-selfhost.cfg 首次生成时会自动写入安装专属密钥：VAPID 浏览器推送公私钥、搜索游标加密 key、JWT 签名私钥（tokenSigner）、SSO secret、GitLab/Jira webhook secret——这些不是占位符而是真随机值，备份该文件即备份了整套密钥，权限应 600。

六、验证服务可用性（实测回显链）

宿主监听端口——只应有 8130：

$ ss -ltn | grep -E '8130|8080|3306|4566'
LISTEN 0 4096 0.0.0.0:8130 0.0.0.0:*
LISTEN 0 4096 [::]:8130 [::]:*

入口 302 → 仪表盘 200：

$ curl -sI http://127.0.0.1:8130/ | head -3
HTTP/1.1 302 Found
Location: /dashboard
...
$ curl -s http://127.0.0.1:8130/dashboard | grep -o '<title>[^<]*</title>'
<title>ClearFlask</title>

API 健康：

$ docker exec clearflask-2.7.2-server curl -sf http://localhost:8080/api/health
ok

存储底座就绪（源数据在 DynamoDB 兼容层，MySQL 仅搜索索引）：

$ docker exec clearflask-2.7.2-localstack awslocal dynamodb list-tables
{
    "TableNames": [
        "clearflaskprimary"
    ]
}
$ docker exec clearflask-2.7.2-localstack awslocal s3 ls
2026-11-01 11:02:14 local-upload
$ docker exec clearflask-2.7.2-mysql mysql -uroot -pclearflask -e "use clearflask; show tables;"
Tables_in_clearflask
account
comment
comment_parent_id
idea
idea_funders
idea_tags
user

💡 注意 user 表 count(*)=0 但账号已能登录——源数据在 clearflaskprimary 单表，MySQL 表只是搜索镜像。排障时别在 MySQL 里找业务数据。

七、注册超级管理员与首个项目

浏览器打开 http://<服务器IP>:8130，跳转 /dashboard 后点注册。默认配置 superAdminEmailRegex=^admin@localhost$ 只放行 admin@localhost 这一个邮箱（本文实测账号：admin@localhost / q1w2e3r4）。
注册成功后立即把 cfg 的 signupEnabled=true 改为 false 并重启 server，关闭后续注册（改法见《ClearFlask 2.7.2 配置参数详解》）。重复注册同邮箱的实测回显：

HTTP 409 {"userFacingMessage":"Email already in use"}

登录后走仪表盘新建项目向导（名称任意、slug 设 demo）。项目门户按 slug 挂子域：本环境 parentDomain=localhost，门户即 http://demo.localhost:8130，connect 日志可见 SSR 成功：

Rendered http://demo.localhost/ in 2 pass(es)

⚠️ 无证书 HTTP 环境的已知坑：connect 对项目子域的 API 写操作（如门户提交反馈）会回 403 + Location: https://demo.localhost/... 强制跳 HTTPS，而本栈 9443 未监听。生产按官方 DNS/证书方案配好 TLS 即消除；本地功能验证可改走 server 内网 API（方法见《ClearFlask 2.7.2 常用 CLI 命令与 API 详解》）。

八、日常运维与升级回滚

# 停止（数据保留在 ./data 与 ./server ./connect）
docker compose --profile with-deps down
# 仅重启 Java 侧（改 cfg 后生效）
docker compose restart clearflask-server
# 跟踪日志排障
docker compose logs -f clearflask-server
docker compose logs -f clearflask-connect

升级：先备份（mysqldump + data/ 目录 + config-selfhost.cfg，命令实测见 D1 篇），再把两个 ghcr.io/clearflask/* 镜像 tag 改为新版本号，docker compose --profile with-deps up -d 滚动替换。ClearFlask 启动时自动做 schema 升级（ConfigSchemaUpgrader），无需手工迁移 SQL。回滚同理：tag 改回旧版本再 up——注意源数据 schema 若已被新版升级，旧版可能不识别，回滚前先整目录备份 data/localstack。

九、常见问题（本环境实测排障记录）

症状	根因	处置
`Bind for 0.0.0.0:8129 failed: port is already allocated`	前置验证时 8129 被其他组件占用	换 `8130:9080`；`ss -ltn` 先查占用
compose 启动即报 `ERROR: ... CLEARFLASK_CONNECT_TOKEN ... required`	缺 `.env` 或变量名拼错	按 4.1 生成 `.env`
server 反复重启、日志 `Connection refused: localstack:4566`	漏了 `--profile with-deps`，LocalStack 没起	补 profile 重新 up
登录/建项目报 401，直连 server 带 `x-cf-connect-token` 也 401	`.env` 令牌与 `server/config-selfhost.cfg` 的 `connectToken` 不一致	三处（.env / cfg / connect.config.json）以 `.env` 为准，改齐后 `restart`
门户子域 POST 返回 403 且 `Location: https://...`	无证书环境 connect 对门户域强制 HTTPS	配 TLS 或走内网 API 验证
注册页提示不允许注册 / 403	`superAdminEmailRegex` 不匹配或 `signupEnabled=false`	检查 cfg 两项（见 C1）
内存吃紧、server OOM kill	JVM 默认堆偏大或宿主内存 <2 GB	`CATALINA_OPTS=-Xms256m -Xmx512m`（本定稿已含）

十、相关文章

《ClearFlask 2.7.2 介绍与选型指南》——先读架构与选型再部署
《ClearFlask 2.7.2 配置参数详解》——config-selfhost.cfg 全量逐项
《ClearFlask 2.7.2 常用 CLI 命令与 API 详解》——备份、自带脚本与 REST API 实操

参考链接

官方仓库：https://github.com/clearflask/clearflask
官方编排文件：https://github.com/clearflask/clearflask/blob/master/clearflask-release/src/main/docker/compose/docker-compose.self-host.yml
镜像发布页：https://github.com/clearflask/clearflask/pkgs/container/clearflask-server
LocalStack 0.14 文档：https://docs.localstack.cloud/v0.14/