企业官网建设流程全解析

Claude Code Router CLI 如何用 ccr serve 与进程管理器在服务器上长期运行

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router

在 SSH 服务器或无桌面环境下，Claude Code Router（CCR）需要以 npm CLI 方式部署，而不是桌面应用。要让管理服务和模型网关在服务器上长期运行，官方文档给出的路径是：用前台命令ccr serve拉起服务，再由外部进程管理器负责进程退出后的重启与日志收集。本文覆盖从安装 CLI、固定启动参数，到交给进程管理器托管、验证网关可用性的完整操作路径。

前提：选择 npm CLI 并安装

CCR 有ccr（npm 包@musistudio/claude-code-router）和ccr-app（桌面应用生成的启动器）两个命令，二者会读取同一套本机配置目录，但不要混用。需要托盘、桌面通知、自动更新时用桌面版；需要无桌面部署或由进程管理器托管时，使用 npm CLI。

CLI 要求 Node.js 22 或更高版本：

node --version npm install -g @musistudio/claude-code-router ccr --help

如果安装成功但找不到ccr命令，执行npm prefix -g，确认 npm 全局可执行目录已加入PATH，然后打开一个新终端。

为什么用ccr serve而不是ccr start

CCR 的服务命令分两类（完整参考见 CLI 安装与命令参考）：

长期运行场景下选择ccr serve的原因，文档中有三点直接依据：

1. 错误直接输出到当前终端。排查启动错误时优先使用它，日志会进入进程管理器统一收集的 stdout。
2. 信号处理干净。serve留在前台，收到SIGINT或SIGTERM后会关闭管理服务和已配置服务——这正是进程管理器做优雅重启所依赖的行为。
3. ccr stop管不到它。ccr stop只管理start/ui创建的后台服务；前台serve应通过对应终端或外部进程管理器停止。

文档还明确要求：不要同时运行由ccr start创建的后台服务，否则可能出现两个管理端口、或两个进程竞争同一套配置。如果机器上之前跑过ccr start或ccr ui，先执行ccr stop停掉旧后台服务。

固定启动参数

文档对生产启动的要求是：使用ccr serve --no-open，并且启动命令至少应固定工作用户、HOME、监听地址和CCR_WEB_AUTH_TOKEN。这些值既可以通过serve的选项传入，也可以通过公开的环境变量提供（省略选项时生效）：

serve的完整选项与start、ui相同：

ccr serve [--host <host>] [--port <port>] [--open|--no-open] [--gateway|--no-gateway]

• --no-open：不打开浏览器，无桌面服务器上必须带上。
• --gateway是默认行为（启动模型网关）；--no-gateway只启动管理服务。
• --port必须是1到65535的整数，默认3458。

把上述要求落成进程管理器实际执行的命令（CCR_WEB_AUTH_TOKEN需替换为一个长的随机值，这是管理 UI / RPC 的固定凭据）：

CCR_WEB_HOST=127.0.0.1 \ CCR_WEB_PORT=3458 \ CCR_WEB_AUTH_TOKEN=replace-with-a-long-random-value \ ccr serve --no-open

除环境变量外，进程管理器还要保证进程以固定的工作用户运行，且HOME稳定——配置目录在 macOS / Linux 上位于~/.claude-code-router，HOME变化会改变 CCR 实际读取的配置与数据位置。

交给进程管理器托管

文档没有指定具体的进程管理器，给出的约束是：让外部管理器负责重启和日志。任何满足以下条件的管理器（systemd、PM2 等）都符合这一要求：

• 按上一条的命令启动前台ccr serve进程；
• 进程退出（非零或崩溃）后自动拉起，重启时复用同一套固定参数；
• 收集进程的 stdout/stderr，便于排查启动错误。

由于serve收到SIGTERM会干净地关闭管理服务和已配置服务，管理器的重启动作不会残留半停状态。停止服务时回到进程管理器操作即可，不要用ccr stop——它对该进程无效。

验证部署是否可用

服务启动只是第一步。完成供应商与凭据配置后，按 安装并启动 CCR 的验证流程逐项确认：

1. 在服务页面确认网关状态为运行中。管理界面默认使用http://127.0.0.1:3458，模型网关默认使用http://127.0.0.1:3456。
2. 请求当前部署的/health；成功时应返回200和运行状态。
3. 用 CCR 客户端 Key 向兼容路径发送一个最小模型请求。
4. 在日志页面确认请求模型、最终供应商 / 模型、状态码和耗时。

注意两点边界：管理界面能打开并不代表模型网关已经可用；没有配置供应商 / 模型时，/health返回502属于预期行为。另外，管理 URL 的完整链接包含ccr_web_token查询参数，应把完整 URL 当作密码，不要粘贴到日志、工单或公开截图里。管理 Token 与 CCR 客户端 Key 是两种独立凭据：前者保护 UI / RPC，后者验证模型请求，不要混用。

常见问题与限制

以下现象和处理方式均来自 CLI 文档的常见问题章节：

• 管理端口发生偏移：首选端口3458被占用时，CCR 会继续尝试后续端口并打印实际 URL，以命令打印的 URL 为准；需要固定端口时先停止占用端口的进程。
• UI 能打开，但/health或模型请求失败：管理服务可以在没有可用模型网关时运行。添加供应商和模型、创建 CCR 客户端 Key，然后从服务页面启动或重启网关；启动错误用前台ccr serve的终端输出查看。
• 升级 CLI：执行npm install -g @musistudio/claude-code-router@latest，之后通过进程管理器重启进程使新版本生效。卸载 npm 包不会删除本地配置和数据库。

数据与安全的两条硬性限制：

• 不要在 CCR 运行时直接编辑或复制活跃的 SQLite 文件（当前配置在config.sqlite）。优先使用Settings → Export data；文件级备份前先停止 CLI。
• 上游供应商凭据保存在本地数据目录（app-data/下有 API Key、请求日志、证书等），目录及其备份都应按敏感数据保护。

监听地址默认127.0.0.1。监听到0.0.0.0会让管理界面进入局域网或外部网络，文档要求只在确实需要时这样配置，并同时使用固定强 Token、主机防火墙或私网、可信反向代理提供的 TLS；不要在未创建 CCR 客户端 Key 的情况下暴露网关。

如果后续希望改为容器化常驻部署（镜像内置 PM2 与 Nginx 单入口），可参考仓库中的 Docker 部署文档，它与 CLI 部署互斥，不是同一操作链的延伸步骤。

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router