ClipCascade 配置参数详解

ClipCascade 服务端没有传统意义的配置文件，全部行为由 CC_ 前缀的环境变量驱动，共 37 个，均提供合理的内置默认值。本文逐项讲解每个变量的作用、默认值与影响面，关键参数均附带真实服务器的实测回显。部署前置步骤见 《ClipCascade 安装部署指南》，命令行运维见 《ClipCascade 常用 CLI 命令详解》。

一、配置机制与生效方式

加载路径：systemd 部署时推荐用 EnvironmentFile 指向独立 env 文件（本文环境为 /etc/clipcascade/clipcascade.env，建议属主 root:clipcascade、权限 640——数据库加密口令会出现在这里）：

# /etc/systemd/system/clipcascade.service 节选
[Service]
EnvironmentFile=/etc/clipcascade/clipcascade.env

生效时机：环境变量在进程启动时读取一次，修改后必须重启服务。实测：将 CC_PORT 从 8080 改为 8081 并 systemctl restart clipcascade：

CC_PORT=8081
=== 监听验证 ===
LISTEN 0      100                *:8081             *:*          
=== 8081 健康检查 ===
OK
8080 -> 000

新端口立即监听、旧端口不再监听。改回 8080 重启后恢复：

=== 改回 CC_PORT=8080 ===
OK

运行时可见的参数：部分参数可通过认证端点实时核对，适合变更后快速验证——

/server-mode -> 200 {"mode":"P2S"}
/server-version -> 200 {"version":"3.3.0"}
/max-size -> 200 {"maxsize":1048576}
/max-message-size -> 200 {"maxmessagesize":1.0}
/stun-url -> 200 {"url":""}

/max-size 返回字节值（1 MiB = 1048576）对应 CC_MAX_MESSAGE_SIZE_IN_MiB=1；/stun-url 为空说明 P2P 模式未开启。

二、服务与注册参数

CC_PORT

反代场景下保持默认即可，反代把 443 流量转到这里（见部署篇 nginx 配置）。直连场景按需修改。实测见上文第一节。

CC_SIGNUP_ENABLED

公共部署若开放注册，建议同步设置 CC_MAX_USER_ACCOUNTS 限制账号总量。实测关闭状态下的行为——访问 /signup 返回 302 并跳回首页：

=== CC_SIGNUP_ENABLED=false 时 GET /signup ===
302
signup redirect -> http://127.0.0.1:8080/

配套的 /captcha 端点在关闭状态下仍返回 200（供管理面板使用），但注册表单不再可达。

CC_ALLOWED_ORIGINS

* 允许任意来源连 WebSocket。有固定域名时改为 https://clipcascade.example.com；多域名用逗号分隔。安全敏感部署务必收紧，否则任意网页都能向你的服务端发起剪贴板连接尝试（受账号体系保护，风险主要是骚扰性连接）。

CC_MAX_USER_ACCOUNTS

注册与管理员建号都受此限制。超出后注册失败。小团队建议显式设为成员数，防止口令泄露后被批量建号。

CC_ACCOUNT_PURGE_TIMEOUT_SECONDS

示例值 63115200（2 年）。临时人员流动性大的部署可开启，注意删除是硬删除，账号的加密密钥随用户名+口令派生，重建同名账号也拿不回旧密钥。

三、消息与同步参数

CC_MAX_MESSAGE_SIZE_IN_MiB

仅 P2S 模式生效（CC_P2P_ENABLED=true 时忽略）。官方提示 Android 客户端文本剪贴板上限约 1 MiB，桌面端三类内容都可更大；客户端侧还有独立的本地限额设置兜底。实测默认配置下：

/max-message-size -> 200 {"maxmessagesize":1.0}

调大后（如 3）客户端可传 3 MiB 以内的图片/文件，同时记得把反代 client_max_body_size 同步放大。

CC_MAX_MESSAGE_SIZE_IN_BYTES

需要精确非 2^n 限额时使用，例如 917504（896 KiB）适配某些 Android 机型的文本剪贴板上限。

CC_P2P_ENABLED

开启后：消息大小限制全部失效（WebRTC 数据通道无服务端中转）、服务端负载降低；客户端登录页会看到 P2P 模式提示，桌面端首次运行会请求局域网访问权限。服务端此时只负责认证与 WebRTC 信令（/p2psignaling）。

CC_P2P_STUN_URL

CC_P2P_ENABLED=true 时必读：默认指向 Google 公共 STUN，内网/离线环境需自建（如 coturn）或改为可达地址。实测 P2P 关闭时该值对客户端为空：

/stun-url -> 200 {"url":""}

CC_MAX_WS_GLOBAL_CONNECTIONS / CC_MAX_WS_CONNECTIONS_PER_USER

仅 P2P 模式生效。P2S 场景每设备一条连接，天然受账号数约束。

CC_P2P_SIGNALING_RATE_LIMIT_PER_SEC

短突发允许到上限值，超出丢弃。0 或负值关闭限流。公网暴露的 P2P 服务端建议设个 10~50 的值防信令洪泛。

四、会话与防暴力破解参数

CC_SESSION_TIMEOUT

实测环境即默认值（env 文件中显式写了 CC_SESSION_TIMEOUT=525960m）。会话默认存内存，重启即失效，除非开启持久化（下条）。

CC_SESSION_PERSISTENCE_ENABLED

开启后未过期的会话跨重启保留（存在 H2/PostgreSQL 里，要求 /database 数据目录持久化）；WebSocket 无论如何都要重连。关闭持久化会清除已存会话。生产环境建议开启，避免每次重启全员重新登录。

CC_MAX_UNIQUE_IP_ATTEMPTS

防"分布式撞库"：同一账号被多个 IP 各试错几次即触发。

CC_MAX_ATTEMPTS_PER_IP

实测验证 BFA 追踪器：对 user1 连续 4 次提交错误口令（每次都 302 到 /login?error），管理员查看快照：

attempt 1 -> 302 http://localhost:8080/login?error
attempt 2 -> 302 http://localhost:8080/login?error
attempt 3 -> 302 http://localhost:8080/login?error
attempt 4 -> 302 http://localhost:8080/login?error
bfa-snapshot: {"user1":{"ipAccessDetails":{"0:0:0:0:0:0:0:1":{"attempts":4,"lockCount":0,"lockTimeout":0}},"uniqueIpSet":["0:0:0:0:0:0:0:1"],"lockTimeout":0},"admin":{"ipAccessDetails":{},"uniqueIpSet":[],"lockTimeout":0}}

attempts: 4 实时累计、lockCount/lockTimeout 归零表明尚未触发锁定。按默认参数，该 IP 累计到 30 次即锁。

CC_LOCK_TIMEOUT_SECONDS / CC_LOCK_TIMEOUT_SCALING_FACTOR

官方示例：系数 1 → 60,120,180…；系数 2 → 120,240,360…。激进暴露面（公网直接 8080）建议首锁 300 秒、系数 2。

CC_BFA_CACHE_ENABLED（及配套三参数）

配套参数（仅在开启时生效）：CC_BFA_TRACKER_CACHE_MAX_JVM_ENTRIES（JVM 内缓存条目上限，默认 50）、CC_BFA_TRACKER_CACHE_RAM_PERCENTAGE（堆外 RAM 占比，默认 0）、CC_BFA_TRACKER_CACHE_DISK_PERCENTAGE（磁盘占比，默认 40）。大流量公网实例才需要开启，避免每个失败请求都落库。

CC_CAPTCHA_DIFFICULTY_PERCENT

登录页与注册页的验证码强度。人机矛盾突出时可降到 50~70，降低视觉干扰但保留基本校验。

CC_LOG_BRUTE_FORCE_TRACKER_ENABLED

排查"账号为何被锁"时临时开启，配合 journalctl -u clipcascade -f 观察命中过程。

五、数据库参数（默认 H2，可切 PostgreSQL）

默认使用内置 H2 文件库，位于工作目录 ./database/clipcascade，AES 加密：

实测部署的数据库文件：

/var/lib/clipcascade/database/:
-rw-r--r-- 1 clipcascade clipcascade 36864 Oct 28 03:39 clipcascade.mv.db

H2 口令安全要点（官方文档原意）：默认口令是公开的，任何拿到数据库文件的人可解密。首启之前就应改成随机值；开启 CC_SESSION_PERSISTENCE_ENABLED 后会话也入库，更必须改。改口令只在首次启动前有效——已建的库不随变量变更自动改密，跨重启/升级/迁移保持一致即可。

切换 PostgreSQL（多实例或需要外置备份时）：

CC_SERVER_DB_URL=jdbc:postgresql://localhost:5432/clipcascade
CC_SERVER_DB_DRIVER=org.postgresql.Driver
CC_SERVER_DB_HIBERNATE_DIALECT=org.hibernate.dialect.PostgreSQLDialect
CC_SERVER_DB_USERNAME=clipcascade
CC_SERVER_DB_PASSWORD=<强口令>

切换前用 pg_dump 思路迁移数据不可行（schema 自建），官方路径是干净初始化后让用户重新注册/建号。

六、日志参数

日志双轨：应用滚动日志在工作目录 logs/ 下；systemd 部署时 stdout/stderr 同时进 journald，journalctl -u clipcascade 直接可查。排障时临时把 CC_SERVER_LOGGING_LEVEL 调到 DEBUG 重启，观察 WebSocket 握手与 BFA 判定细节，查完调回。

七、外部消息代理参数（集群扩展）

单机部署用内置内存代理即可；多实例负载均衡时，开启外部 STOMP（如 ActiveMQ Artemis）让各实例共享剪贴板广播。

八、生产配置模板

整合以上参数的推荐基线（小团队、域名接入、PostgreSQL 外置）：

# --- 服务 ---
CC_PORT=8080
CC_ALLOWED_ORIGINS=https://clipcascade.example.com
CC_SIGNUP_ENABLED=false
CC_MAX_USER_ACCOUNTS=50
CC_ACCOUNT_PURGE_TIMEOUT_SECONDS=-1

# --- 消息 ---
CC_MAX_MESSAGE_SIZE_IN_MiB=3
CC_MAX_MESSAGE_SIZE_IN_BYTES=0
CC_P2P_ENABLED=false

# --- 会话与安全 ---
CC_SESSION_TIMEOUT=525960m
CC_SESSION_PERSISTENCE_ENABLED=true
CC_MAX_UNIQUE_IP_ATTEMPTS=10
CC_MAX_ATTEMPTS_PER_IP=20
CC_LOCK_TIMEOUT_SECONDS=300
CC_LOCK_TIMEOUT_SCALING_FACTOR=2
CC_BFA_CACHE_ENABLED=false
CC_CAPTCHA_DIFFICULTY_PERCENT=70
CC_LOG_BRUTE_FORCE_TRACKER_ENABLED=false

# --- 数据库（示例：PostgreSQL 外置）---
CC_SERVER_DB_URL=jdbc:postgresql://127.0.0.1:5432/clipcascade
CC_SERVER_DB_DRIVER=org.postgresql.Driver
CC_SERVER_DB_HIBERNATE_DIALECT=org.hibernate.dialect.PostgreSQLDialect
CC_SERVER_DB_USERNAME=clipcascade
CC_SERVER_DB_PASSWORD=<强口令>

# --- 日志 ---
CC_SERVER_LOGGING_LEVEL=INFO
CC_SERVER_LOG_HISTORY_MAX_DAYS=30
CC_SERVER_LOG_MAX_CAPACITY=1GB

每次修改后：systemctl restart clipcascade && systemctl status clipcascade --no-pager | head -5，再用 /health 与 /max-message-size 抽验。

九、配置相关排障实录

实录 1：改端口后"服务失联"。 修改 CC_PORT 后浏览器仍访问旧端口 8080 失败。诊断顺序：ss -ltn | grep java 确认新端口已监听（实测回显见第一节），curl -s http://127.0.0.1:<新端口>/health 应返回 OK。根因通常是忘了 restart，或反代 upstream 仍指向旧端口。

实录 2：/signup 打不开。 CC_SIGNUP_ENABLED=false 是默认值，/signup 302 跳首页是预期行为而非故障。建号走管理员面板或 API。

实录 3：登录失败次数没有出现在 user-details。 管理端 /admin/user-details 的 failedLoginAttempts 字段与 /admin/bfa-snapshot 的 attempts 计数更新时机不同（实测：连续 4 次失败后 snapshot 里 attempts:4，user-details 中仍为 0）。判断是否接近锁定以 bfa-snapshot 为准。

实录 4（客户端侧）：No module named 'Crypto'。 属于 Linux 客户端依赖命名空间问题，与上文服务端 37 个参数无关，完整复现与修复过程见 《ClipCascade 常用 CLI 命令详解》。

十、延伸阅读

• 服务端安装、systemd 与反代全流程：《ClipCascade 安装部署指南》
• 日常运维命令、API 调用与 Linux 客户端 CLI：《ClipCascade 常用 CLI 命令详解》
• 多机文件同步的另一个思路：《Syncthing 2.1.7 配置参数详解》