企业官网建设流程全解析

CrossWatch 是一款开源媒体数据同步工具，能让 Plex、Jellyfin 等媒体服务器与 Trakt、SIMKL 等追踪平台之间的电影、剧集观看列表、历史记录和评分保持同步。这篇文章围绕 CrossWatch 内置的终端命令cw展开：从首次配置、创建 API token，到建立同步对、一行触发同步、设置计划任务和备份恢复，全部在终端里用一行命令完成。读完这篇 CrossWatch CLI 速查手册，你就不用再点网页 UI，也能管好所有同步任务。

📦 cw 命令是什么

cw与网页版 UI 共享同一个服务：在终端发起的同步会出现在 Web 界面里，写入同一份日志，并遵守"已有同步正在运行"的保护逻辑。服务挂掉时，只读命令还会自动回退到本地安装数据。完整文档见 cli/README.md。

容器内cw已安装到 PATH，任意目录都能执行：

docker exec -it crosswatch cw status docker exec -it crosswatch cw sync run --follow docker exec -it crosswatch cw shell

容器外可以从安装根目录直接运行python cli/cw.py status，入口文件是 cli/cw.py。

🚀 三步完成首次配置

第一步：设置管理员密码

全新安装或配置被删后，先设置密码（默认同时生成并保存 CLI token）：

cw --local auth setup --username admin

第二步：创建 API token

之后所有命令都会自动认证，token 保存在容器内/config/.cw_cli/cli.json：

cw --local auth token create --name cli

脚本和 CI 场景可以只创建只读 token，并直接写入文件避免泄露：

cw auth token create --name monitor --access monitor --expires-days 365 --write-to /run/secrets/cw_token

token 校验相关实现位于 cli/commands/auth.py，URL 与 token 的解析逻辑见 cli/_settings.py。

第三步：确认服务状态

cw status # 一屏看全：版本、配对、同步、Watcher、计划任务 cw status --fresh # 强制重新探测各 provider 而非用缓存 cw version # 版本与全部 provider 模块版本 cw health # 服务是否在响应

🎛 全局选项：任何命令都能用

以下选项可放在命令行任意位置，参数定义在 cli/_app.py：

-o json是写脚本的最佳搭档：stdout 只输出 JSON，错误走 stderr。

🔑 一行登录 18 个 Provider

cw auth login会自动识别登录流程，不管是设备码还是账号密码：

cw auth providers # 列出全部 provider、流程类型和所需字段 cw auth list [--fresh] # 当前哪些已连接 cw auth login trakt # 打印设备码，等你在网页批准后自动轮询 cw auth login plex --no-wait # 同上但不阻塞终端 cw auth login jellyfin # 交互式询问服务器、用户名、密码 cw auth logout simkl

脚本化时可以直接传字段、跳过交互：

cw auth login jellyfin \ --field jellyfin.server=http://192.168.2.100:8096 \ --field jellyfin.username=pascal \ --field jellyfin.password="$JF_PASSWORD" \ --non-interactive

字段名以cw auth show <provider>的输出为准；多实例环境用--instance <id>指定实例。

🔄 同步对（Pair）管理

同步对就是"谁同步到谁、同步哪些功能"。完整命令清单见 cli/README.md：

cw pair create plex trakt --feature watchlist --feature ratings cw pair create simkl trakt --mode two-way cw pair create plex trakt --feature history --add-only cw pair list [--enabled] cw pair show <id> # 支持唯一前缀或路由名，如 "PLEX -> TRAKT" cw pair enable <id> cw pair disable <id> cw pair feature <id> <feature> on|off cw pair delete <id> [--yes]

cw pair set用来微调已存在功能里的单个选项：

cw pair set <id> history.add on|off cw pair set <id> history.rewatches on|off cw pair set <id> history.libraries PLEX=1,2 # 限定某个 provider 的媒体库

配对管理的源码在 cli/commands/pair.py。

▶️ 触发、跟踪与取消同步

这是日常使用频率最高的一组命令，对应实现见 cli/commands/sync.py：

cw sync list [--enabled] # 运行顺序、端点与启用的功能 cw sync run # 运行全部已启用配对 cw sync run 1 # 只跑 cw sync list 里的第 1 个 cw sync run pair_07c3 # 按 id 或唯一前缀指定 cw sync run --follow # 运行并实时流式输出日志 cw sync status # 当前/上一次运行及各项计数 cw sync follow # 挂到正在运行的一次同步上 cw sync cancel # 当前批次结束后停止 cw sync unresolved # 上次运行未能匹配的项目 cw sync once --dry-run --plan-out plan.json # 预演并导出计划变更

两个关键区别：

• cw sync run通过运行中的服务发起，适合常规操作；
• cw sync once在本地进程内执行并等待结束、以同步结果作为退出码，专为docker run --rm、cron、Kubernetes CronJob 等外部调度器设计。默认"未解析项"不算失败，加--fail-on-unresolved可以更严格。

⏰ 计划任务与实时 Watcher

定时同步不用系统 crontab，CrossWatch 自带调度器：

cw scheduler status cw scheduler next # 下一次触发时间 cw scheduler set daily 03:30 # 每天凌晨 3:30 cw scheduler set every 6h cw scheduler setup # 交互式引导配置 cw scheduler run-now # 立即触发一次

Watcher 负责把播放事件实时推送到各追踪器，命令与 cli/commands/watcher.py 对应：

cw watcher status cw watcher start / stop / restart cw watcher now # 现在谁在播什么 cw watcher logs [-n 200]

Webhook 与路由配置则通过cw scrobbler系列命令管理：

cw scrobbler overview cw scrobbler route add | set | delete cw scrobbler webhook urls cw scrobbler webhook regenerate

📊 数据管理：观看列表、进度与播放记录

cw watchlist list [--type movie] [--search dune] cw watchlist remove <key> [<key> ...] cw progress list [--provider PLEX] [--min 10] cw progress watched <key> cw progress set <key> 45 # 把进度设为 45% cw progress remove <key>

Editor 命令则面向逐条数据的手工编辑：

cw editor list --kind watchlist [--provider PLEX] cw editor sources cw editor send <key> --provider TRAKT cw editor export

🛟 快照、备份与维护

Capture 是回滚工具，同步前先拍一张快照最稳妥：

cw capture create [--provider PLEX] [--feature watchlist] cw capture diff <older> <newer> cw capture restore <path> [--dry-run] cw capture delete <path>

Backup 面向整体配置，支持定期自动备份：

cw backup create --note "before the big sync" cw backup validate <path> cw backup restore <path> cw backup schedule --enable --every-hours 24 cw backup retention 10

Maintenance 是一组维护操作，从缓存清理到工厂重置都有：

cw maintenance tools # 全部维护动作一览 cw maintenance cache <what> # all / metadata / provider-sync / state... cw maintenance provider-cleanup # 清空某 provider 的观看列表、评分等 cw maintenance reset-pair [id] # 用全新基线重置某个同步对 cw maintenance support [--scopes] cw maintenance factory-reset --confirm RESET

🧭 其余命令组一句话速查

config组是合并补丁语义，只动你点名的键：

cw config show [path] cw config get sync.anime.enabled cw config set some.list "[1,2,3]" --json cw config unset some.key cw config edit # 打开 $EDITOR

🐚 cw shell：交互式 REPL

嫌前缀打太累？cw shell提供可嵌套的命令组，?查看当前可用命令，Tab 自动补全：

cw> sync cw(sync)> status cw(sync)> run --follow cw(sync)> exit cw> exit

历史记录保存在~/.crosswatch/history，实现见 cli/commands/shell.py。

🔢 退出码与服务宕机时的行为

写脚本时值得记住这 7 个退出码（定义于 cli/_errors.py）：

服务宕机时，status、config、pair list/show、auth token等只读命令会直接读本地安装继续工作（stderr 会提示回退）；需要运行引擎的命令（发起同步、操作 Watcher、流式日志）则以退出码 3 失败，--local可强制这一行为。

小结

CrossWatch CLI 的价值在于：把"连接 provider → 建同步对 → 触发同步 → 定时运行 → 出问题回滚"这条完整链路压缩成一行行的cw命令，还能用-o json无缝接入你的自动化脚本。新手建议按"三步完成首次配置"跑通cw status，之后照着上面的速查表按需取用即可。