ClipCascade 常用 CLI 命令详解

ClipCascade 三层命令行实操：服务端 systemd/journalctl 运维、curl 三段式 API 调用、Python 端到端收发验证、Linux CLI 客户端启动参数与登录实测，含 Cryptodome 命名空间坑等排障实录。

ClipCascade剪贴板同步Java平台信息安全2026/10/28

ClipCascade 常用 CLI 命令详解

ClipCascade 的命令行分三层：服务端生命周期管理（systemd/journalctl）、服务端 API 调用（curl/Python）、Linux 客户端 CLI 程序（main.py）。本文所有命令与回显均在 Ubuntu 22.04 + ClipCascade v3.3.1 真实服务器实测，账号统一使用管理员 admin 与普通用户 user1（口令均为 q1w2e3r4）。部署与选型背景见 《ClipCascade 安装部署指南》 与 《ClipCascade 介绍与选型指南》。

一、命令总览

层命令用途
服务端systemctl status/start/stop/restart clipcascade服务生命周期
服务端journalctl -u clipcascade ...运行日志
服务端curl http://127.0.0.1:8080/health、/ping免认证探活
服务端curl（cookie + CSRF 三段式）登录、管理、改密等 API
服务端python3 cc_e2e.py 类脚本端到端收发验证
客户端python3 main.py [--gui] [--xmode] [--polling]Linux CLI 同步程序

二、服务端生命周期命令

systemctl status clipcascade --no-pager -l     # 状态与最近日志
systemctl start clipcascade                    # 启动
systemctl stop clipcascade                     # 停止
systemctl restart clipcascade                  # 重启（改配置后必做）
systemctl enable --now clipcascade             # 开机自启并立即启动

实测 status 回显（节选）：

● clipcascade.service - ClipCascade Clipboard Sync Server
     Active: active (running) since Wed 2026-10-28 03:35:28 UTC; 25min ago
   Main PID: 4006 (java)
     Memory: 398.2M
             └─4006 /usr/bin/java -Xms256m -Xmx512m -jar /opt/clipcascade/ClipCascade-Server-JRE_21.jar

重启后确认进程与探活：

systemctl restart clipcascade
sleep 5
systemctl is-active clipcascade
curl -s http://127.0.0.1:8080/health; echo

实测回显：

active
OK

冷启动约 4 秒，sleep 5 足够探活。

三、日志查看命令

journald 轨（stdout 重定向）：

journalctl -u clipcascade -n 5 --no-pager -o cat       # 最近 5 行
journalctl -u clipcascade -f                            # 跟踪滚动
journalctl -u clipcascade --since "10 min ago"          # 时间窗检索

实测 -n 5 -o cat 回显（节选）：

2026-10-28T04:05:22.313Z  INFO 4773 --- [           main] c.a.clipcascade.ClipCascadeApplication   : Started ClipCascadeApplication in 3.405 seconds (process running for 3.69)
2026-10-28T04:05:26.656Z  INFO 4773 --- [nio-8080-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring DispatcherServlet 'dispatcherServlet'

文件轨：应用滚动日志在工作目录 logs/ 下（本文为 /var/lib/clipcascade/logs/），保留天数与总容量由 CC_SERVER_LOG_HISTORY_MAX_DAYS（默认 30）与 CC_SERVER_LOG_MAX_CAPACITY（默认 1GB）控制，参数详解见 《ClipCascade 配置参数详解》。

四、curl 调用 API（登录三段式）

ClipCascade 无 API Key/Token，认证是"表单登录 + 会话 Cookie + CSRF 头"三段式。以下全流程实测。

第一段：取登录页 Cookie 与 CSRF 隐藏域：

JAR=/tmp/cc.cookies; rm -f $JAR
CSRF=$(curl -s -c $JAR http://127.0.0.1:8080/login | grep -oP 'name="_csrf" value="\K[^"]+')
echo "csrf token: ${CSRF:0:20}..."

实测回显：

csrf token: c2Fd1C3vm8KRmjZnlP9o...

第二段：提交登录表单（密码为原始口令的 SHA3-512 小写十六进制摘要——这是官方客户端约定，摘要本身等价于凭据，注意保管）：

DIGEST=$(python3 -c "import hashlib;print(hashlib.sha3_512('q1w2e3r4'.encode()).hexdigest())")
curl -s -b $JAR -c $JAR -o /dev/null -w "%{http_code} -> %{redirect_url}\n" -X POST http://127.0.0.1:8080/login \
  --data-urlencode "username=admin" --data-urlencode "password=$DIGEST" --data-urlencode "_csrf=$CSRF"

实测回显（302 到 / 即成功；302 到 /login?error 即失败）：

302 -> http://127.0.0.1:8080/

第三段：验明身份并取操作用 CSRF 头：

curl -s -b $JAR http://127.0.0.1:8080/whoami; echo
XHR=$(curl -s -b $JAR http://127.0.0.1:8080/csrf-token); echo $XHR
TOK=$(echo $XHR | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")

实测回显：

{"role":"ADMIN","username":"admin"}
{"token":"Q9wl4ZlUIb-ZY9n2QNCdUh1MIXhjyqHn7RQ1FZc4DBNSV5daIulHh6BsQ4e0BunGef2pYXl7DEFbr5jKj3BRIqUIaHI0ZKRr","parameterName":"_csrf","headerName":"X-CSRF-TOKEN"}

带 CSRF 头的管理调用（列出全部用户；GET 虽不强制 CSRF，带上保持一致）：

curl -s -b $JAR -H "X-CSRF-TOKEN: $TOK" http://127.0.0.1:8080/admin/all-users; echo

实测回显：

[{"username":"admin","password":null,"role":"ADMIN","enabled":true},{"username":"user1","password":null,"role":"USER","enabled":true}]

登出并验证会话吊销：

curl -s -b $JAR -o /dev/null -w "%{http_code}\n" -X POST -H "X-CSRF-TOKEN: $TOK" http://127.0.0.1:8080/logout
curl -s -b $JAR -o /dev/null -w "whoami after logout: %{http_code}\n" http://127.0.0.1:8080/whoami

实测回显：

302
whoami after logout: 302

登出后访问受保护端点统一 302 回登录页。

五、Python 客户端脚本（端到端收发验证）

排障"服务端到底能不能同步"时，最直接的办法是用官方 API 文档的最小示例跑一次 P2S 加密收发。脚本要点：登录 → 连 /clipsocket 的 STOMP 1.1 → 订阅 /user/queue/cliptext → 用 PBKDF2 派生密钥 AES-GCM 加密发送 → 收到回显后解密。核心片段（完整脚本见官方 ClipCascade_Server/API.md）：

def derive_key(username, original_password, extra_salt="", rounds=664937):
    return hashlib.pbkdf2_hmac("sha256", original_password.encode("utf-8"),
                               (username + original_password + extra_salt).encode("utf-8"),
                               rounds, dklen=32)

实测运行回显：

login ok: {"role":"USER","username":"user1"}
websocket url: ws://localhost:8080/clipsocket
STOMP CONNECTED: {'version': '1.1', 'heart-beat': '20000,0', 'user-name': 'user1'}
received envelope type: text
decrypted payload: Hello from an alternative client 👋

STOMP CONNECTED 中的 user-name 确认服务端识别了订阅者身份；同一账号的已订阅会话会收到自己发送的加密信封，解密成功即证明派生密钥、加密参数与服务端链路全部正常。注意依赖为 requests、websocket-client、pycryptodome（或 pycryptodomex，见下文排障实录二）。

六、Linux CLI 客户端

6.1 获取与依赖安装

从官方 Releases 下载 ClipCascade_Linux.zip（v3.3.1 实测约 82 KiB）解压：

curl -L -o ClipCascade_Linux.zip \
  https://github.com/Sathvik-Rao/ClipCascade/releases/download/v3.3.1/ClipCascade_Linux.zip
unzip ClipCascade_Linux.zip -d FcOHJtWcP0B0ent
cd FcOHJtWcP0B0ent/ClipCascade

目录结构实测（main.py 为入口）：

LICENSE   cli   clipboard   core   gui   help.txt   interfaces
main.py   p2p   packaging   pyproject.toml   requirements.txt   ...

系统依赖（官方 README Step 1/2/4，Debian/Ubuntu 系）：

apt update
apt install -y python3 python3-pip python3-gi xclip wl-clipboard dunst
apt install -y python3-gi-cairo gir1.2-gtk-3.0 gir1.2-gdk-3.0

Python 依赖优先走发行版包（externally-managed-environment 报错时的官方替代路径）：

apt install -y python3-xxhash python3-pyperclip python3-requests \
  python3-websocket python3-pycryptodome python3-tk python3-pystray \
  python3-pyfiglet python3-bs4 python3-plyer python3-aiortc

6.2 启动参数（Linux 专属）

参数取值作用
--guitrue/false强制托盘 GUI 或终端 CLI，覆盖自动判定
--xmodetrue/falsetrue 用 X11 风格（xclip/GTK 剪贴板），false 用 Wayland 风格（wl-clipboard）
--polling正数（秒）覆盖剪贴板轮询间隔

参数支持 --gui=false 与 --gui false 两种写法（源码 core/constants.py 实测确认）。不带参数时按会话环境自动判定：XDG_SESSION_TYPE/DISPLAY/WAYLAND_DISPLAY 决定 X11/XWayland/Hyprland/原生 Wayland 分类，X11 与未知环境默认 GUI + X11 剪贴板路径，原生 Wayland 与 Hyprland 默认 CLI + wl-clipboard 路径。

官方示例：

python3 main.py --gui true
python3 main.py --gui false --xmode false --polling 3
python3 main.py --polling 1.5

6.3 CLI 模式登录实测

无图形会话的终端服务器上直接跑：

python3 main.py --gui false

实测回显（完整交互表单）：

❌ An error occurred during application initialization: [Errno 2] No such file or directory: 'xclip'
  ____ _ _        ____                        _      
 / ___| (_)_ __  / ___|__ _ ___  ___ __ _  __| | ___ 
| |   | | |_) | |__| (_| \__ \ (_| | (_| | (_| | (_| |\___\__,_|\___|
          |_|                                        

*****************************************************
             Real-Time Clipboard Syncing             
      https://github.com/Sathvik-Rao/ClipCascade     
*****************************************************
══════════════
║ LOGIN FORM ║
══════════════
username []: 
password: 
server url [http://localhost:8080]: 
Enable encryption (recommended) [y]: 
Show connection status notifications [y]: 
Show advanced settings [n]:

登录表单共 6 项：用户名、密码（getpass 静默输入）、服务器地址（默认 http://localhost:8080）、加密开关（默认开）、连接状态通知（默认开）、高级设置（默认关）。输入 user1 / q1w2e3r4 全部回车确认默认值后，登录成功进入主菜单：

╔══════════════════════════════════╗
║            MAIN MENU             ║
╠══════════════════════════════════╣
║ 1 . Connected                   ║
║ 2 . ⛓️‍💥 Disconnect               ║
║ ──────────────────────────────── ║
║ 3 . 🗒️  Open Logs                 ║
║ 4 . 📂 Program Files             ║
║ ──────────────────────────────── ║
║ 5 . 🏠 Homepage                  ║
║ 6 . ❓ Help                      ║
║ 7 . 💟 Donate                    ║
║ 8 . 🌐 GitHub                    ║
║ ──────────────────────────────── ║
║ 9 . ℹ️  Version v3.3.0 (latest)   ║
║ ──────────────────────────────── ║
║ 10. 🔒 Logoff and Quit           ║
║ 11. ❌ Quit                      ║
╚══════════════════════════════════╝
Choice:

菜单第 1 项实时显示连接状态（Connected），第 9 项自报客户端版本。客户端日志落在程序目录 clipcascade_log.log，每次启动重置。无图形会话下剪贴板监控会自动降级，日志实录：

2026-10-28 04:19:40,729 - INFO - Max size: 1048576
2026-10-28 04:19:40,989 - INFO - XMODE: True
2026-10-28 04:19:40,992 - ERROR - Failed to start clipboard monitor: Error Namespace Gtk not available
Starting polling mode for Unknown server as fallback.
2026-10-28 04:19:40,994 - WARNING - x-clip is not owned by the current user. Switching to wl-clipboard.

即：GTK 事件式监控失败 → 回退轮询 → xclip 归属校验失败再切 wl-clipboard。有图形会话的桌面终端不会出现这条链。

6.4 后台运行与开机自启

官方 README 给出的后台与自启方式：

# 前台运行
cd /path/to/clipcascade/src/ && python3 main.py
# 后台运行
cd /path/to/clipcascade/src/ && nohup python3 main.py &> /dev/null &
# 写入桌面自启脚本
cd /path/to/clipcascade/src/ && nohup python3 main.py &> /dev/null &

更规范的做法是编写 systemd user 单元（~/.config/systemd/user/FcOHJtWcP0B0ent.service）后 systemctl --user enable --now FcOHJtWcP0B0ent，崩溃自动拉起，日志进 journalctl --user -u FcOHJtWcP0B0ent。

七、排障实录

实录一：apt 源没有 python3-xxhash

现象：按官方 Step 4.1 列表安装时报错。

E: Package 'python3-xxhash' has no installation candidate

原因：官方 README 的 apt 清单与发行版仓库实况存在出入（Ubuntu 22.04 的 universe 源中无此包名）。

处置：以 pip 补齐缺口包（pip3 install xxhash），其余仍用 apt 包。教训：依赖清单要以 python3 -c "import 模块名" 逐个验证，而不是照抄文档。

实录二：No module named 'Crypto'（Cryptodome 命名空间坑，官方必踩）

现象：客户端/自写脚本里 from Crypto.Cipher import AES 报错：

Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'Crypto'

原因：发行版仓库安装的是 python3-pycryptodomex（Debian/Ubuntu 打包策略），它提供的命名空间是 Cryptodome 而非 Crypto；而 ClipCascade 客户端代码与官方 API 示例均按 pycryptodome 的 Crypto 命名空间编写。实测确认两者同源同版本：

$ ls -la /usr/lib/python3/dist-packages/ | grep -iE "crypto"
lrwxrwxrwx  1 root root     41 Oct 28 03:39 Crypto -> /usr/lib/python3/dist-packages/Cryptodome
drwxr-xr-x 13 root root   4096 Oct 28 03:39 Cryptodome
drwxr-xr-x  2 root root   4096 Oct 28 03:39 pycryptodomex-3.11.0.egg-info
$ python3 -c "from Cryptodome.Cipher import AES; print('Cryptodome AES ok')"
Cryptodome AES ok

处置（官方 README Step 5.1 的软链方案）：让 Crypto 成为 Cryptodome 的别名即可，无需重复安装：

ln -s /usr/lib/python3/dist-packages/Cryptodome /usr/lib/python3/dist-packages/Crypto
python3 -c "from Crypto.Cipher import AES; print('Crypto AES ok:', AES)"

实测回显：

Crypto AES ok: <module 'Crypto.Cipher.AES' from '/usr/lib/python3/dist-packages/Crypto/Cipher/AES.py'>

若系统走 pip 而非发行版包，直接 pip3 install pycryptodome 一步到位，无需软链。

实录三：依赖缺失的渐进报错链

CLI 客户端依赖是惰性导入的，缺什么报什么，实测链条：

ModuleNotFoundError: No module named 'bs4'     → apt install python3-bs4
ModuleNotFoundError: No module named 'PIL'     → apt install python3-pil
[Errno 2] No such file or directory: 'xclip'   → apt install xclip

全部补齐后才能走到登录表单（见 6.3）。Pillow 在官方 requirements.txt 中按 Python 版本锁 10.4.0/12.0.0，apt 的 python3-pil 满足导入即可。

实录四：改了配置不生效

环境变量在进程启动时读取。任何 clipcascade.env 修改后必须 systemctl restart clipcascade，再用 curl -s http://127.0.0.1:<端口>/health 验证。实测改 CC_PORT=8081 重启后：ss -ltn 显示监听 *:8081、curl http://127.0.0.1:8080/health 返回 000（连接拒绝），改回 8080 重启恢复 OK。完整过程见配置篇。

实录五：登录一直失败

先分清两类失败：口令错误返回 302 -> /login?error；触发 BFA 锁定后同样表现为失败但带锁定时间。管理员视角核查：

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},...}

attempts 为该 IP 对该账号的失败累计，lockTimeout 大于 0 表示处于锁定期。等待解锁或重启服务（内存态追踪器随重启清空，缓存开启时除外）。

八、延伸阅读