cc-connect 注册为 Windows 服务实战指南

背景

cc-connect 是一个消息桥接层，能把 Claude Code 接入飞书、钉钉、Slack 等聊天工具。

通常它通过命令行启动，跑在终端里。但如果想让它在后台持续运行、开机自启、不占用终端窗口，就需要把它注册成 Windows 服务。

本机环境：

Windows 10 Pro
Node.js 24.16.0（通过 nvm 管理，位于 E:\software\nvm）
cc-connect v1.3.2（npm 全局安装）
配置文件在 C:\Users\[用户名]\.cc-connect\config.toml

一键安装脚本

先把路径变量设好，后面的代码直接复制粘贴就能跑。

# ============================================================
# 配置变量（根据你的环境修改）
# ============================================================
$CC_BIN   = "E:\software\nvm\v24.16.0\node_modules\cc-connect\bin\cc-connect.exe"
$CONFIG   = "$env:USERPROFILE\.cc-connect\config.toml"
$NSSM     = "C:\Program Files\nssm\nssm.exe"
$LOG_DIR  = "$env:USERPROFILE\.cc-connect"
$SVC_NAME = "cc-connect"
$SVC_DISP = "cc-connect AI Bridge"

方案对比

Windows 上注册后台服务有三种常见方式：

方式	命令	优点	缺点
`sc.exe`	`sc create`	系统自带，无需额外安装	对 stop 信号处理不好，进程可能停不掉
`New-Service`	PowerShell cmdlet	PowerShell 原生，写法简洁	本质同 sc.exe，同样有停服问题
nssm	`nssm install`	生命周期管理完善，start/stop 可靠	需要额外下载（但很小，500KB）

为什么推荐 nssm

Windows 服务管理器（SCM）发 stop 信号时，普通命令行程序未必能正确响应 SERVICE_CONTROL_STOP。nssm（Non-Sucking Service Manager）专门解决这个问题——它作为中间层，接管服务的 start/stop 信号，底层用 CreateProcess + GenerateConsoleCtrlEvent 管理子进程生命周期，保证能正常启停。

nssm 方案（推荐）

1. 安装 nssm

# 用 winget 一键安装（管理员权限）
winget install nssm

# 检查是否安装成功
Get-Command nssm -ErrorAction SilentlyContinue
# 或检查默认路径
Test-Path "C:\Program Files\nssm\nssm.exe"

默认安装到 C:\Program Files\nssm\nssm.exe。

如果 winget 不可用，去 https://nssm.cc/download 手动下载。

2. 安装服务

# ============================================================
# 使用变量（替换成你自己的路径）
# ============================================================
$CC_BIN   = "E:\software\nvm\v24.16.0\node_modules\cc-connect\bin\cc-connect.exe"
$CONFIG   = "$env:USERPROFILE\.cc-connect\config.toml"
$NSSM     = "C:\Program Files\nssm\nssm.exe"
$SVC_NAME = "cc-connect"

# ---------------------
# 方式 A：图形界面安装（推荐，不容易填错）
# ---------------------
& $NSSM install $SVC_NAME

# 在弹出的界面里填入：
#   Application:  $CC_BIN 的完整路径
#   Arguments:    --config $CONFIG --force
#   Startup directory: $env:USERPROFILE\.cc-connect

# ---------------------
# 方式 B：命令行一键安装
# ---------------------
& $NSSM install $SVC_NAME $CC_BIN "--config $CONFIG --force"

# ---------------------
# 设置工作目录
# ---------------------
& $NSSM set $SVC_NAME AppDirectory "$env:USERPROFILE\.cc-connect"

# ---------------------
# 设置日志输出路径
# ---------------------
& $NSSM set $SVC_NAME AppStdout "$env:USERPROFILE\.cc-connect\service-output.log"
& $NSSM set $SVC_NAME AppStderr "$env:USERPROFILE\.cc-connect\service-error.log"

# ---------------------
# 启动服务
# ---------------------
& $NSSM start $SVC_NAME

# 确认状态
& $NSSM status $SVC_NAME
# 或
Get-Service $SVC_NAME

3. 管理服务

# ============================================================
# 启停管理（管理员权限）
# ============================================================
$NSSM     = "C:\Program Files\nssm\nssm.exe"
$SVC_NAME = "cc-connect"

# ---- nssm 命令 ----
& $NSSM start   $SVC_NAME
& $NSSM stop    $SVC_NAME
& $NSSM restart $SVC_NAME
& $NSSM status  $SVC_NAME

# ---- PowerShell 原生命令（同样有效） ----
Start-Service   -Name $SVC_NAME
Stop-Service    -Name $SVC_NAME
Restart-Service -Name $SVC_NAME
Get-Service     -Name $SVC_NAME

# ---- sc.exe（同样有效） ----
sc.exe start   $SVC_NAME
sc.exe stop    $SVC_NAME
sc.exe restart $SVC_NAME
sc.exe query   $SVC_NAME

# ---- 图形界面 ----
services.msc
# 在列表里找到 "cc-connect AI Bridge"，右键操作

4. 查看日志

# ============================================================
# 查看服务日志
# ============================================================
$LOG_DIR = "$env:USERPROFILE\.cc-connect"

# 实时查看输出日志
Get-Content "$LOG_DIR\service-output.log" -Tail 50 -Wait

# 查看错误日志
Get-Content "$LOG_DIR\service-error.log" -Tail 50

# 一次性查看全部
Get-Content "$LOG_DIR\service-output.log"

nssm 会自动记录服务的标准输出和错误日志：

C:\Users\JA016620\.cc-connect\service-output.log
C:\Users\JA016620\.cc-connect\service-error.log

5. 服务参数微调

# ============================================================
# 高级配置
# ============================================================
$NSSM     = "C:\Program Files\nssm\nssm.exe"
$SVC_NAME = "cc-connect"

# 设置服务失败后自动重启（延迟 10 秒）
& $NSSM set $SVC_NAME AppRestartDelay 10000

# 设置日志文件最大 10MB，超出则轮转
& $NSSM set $SVC_NAME AppRotateBytes 10485760

# 查看当前所有配置（备用：可能显示有编码问题，但不影响功能）
& $NSSM dump $SVC_NAME

6. 卸载服务

# ============================================================
# 卸载（管理员权限）
# ============================================================
$NSSM     = "C:\Program Files\nssm\nssm.exe"
$SVC_NAME = "cc-connect"

# 先停止
& $NSSM stop $SVC_NAME

# 卸载（不需要确认）
& $NSSM remove $SVC_NAME confirm

sc.exe 方案（纯原生）

如果不想安装任何额外工具，Windows 自带的 sc.exe 也能注册服务。

等号后面必须有一个空格，这是语法要求。

# ============================================================
# 安装（管理员权限）
# ============================================================
$CC_BIN   = "E:\software\nvm\v24.16.0\node_modules\cc-connect\bin\cc-connect.exe"
$CONFIG   = "$env:USERPROFILE\.cc-connect\config.toml"
$SVC_NAME = "cc-connect"
$SVC_DISP = "cc-connect AI Bridge"

sc.exe create $SVC_NAME `
  binPath= "`"$CC_BIN`" --config `"$CONFIG`" --force" `
  start= auto `
  DisplayName= $SVC_DISP

# 验证安装
sc.exe query $SVC_NAME
Get-Service $SVC_NAME

# ---- 管理 ----
sc.exe start   $SVC_NAME
sc.exe stop    $SVC_NAME
sc.exe restart $SVC_NAME
sc.exe query   $SVC_NAME

# ---- 修改配置 ----
sc.exe config $SVC_NAME start= auto     # 改为自动启动
sc.exe config $SVC_NAME start= demand   # 改为手动启动

# ---- 卸载 ----
sc.exe stop   $SVC_NAME
sc.exe delete $SVC_NAME

完整管理脚本

把下面保存为 manage-cc-connect.ps1，以后双击或拖进终端就能用。

<#
.SYNOPSIS
  cc-connect 服务管理脚本
.DESCRIPTION
  启停、重启、查看状态和日志
.PARAMETER Action
  start|stop|restart|status|logs|uninstall
.EXAMPLE
  .\manage-cc-connect.ps1 status
  .\manage-cc-connect.ps1 logs
#>

param(
  [ValidateSet("start","stop","restart","status","logs","uninstall")]
  [string]$Action = "status"
)

$SVC_NAME = "cc-connect"
$LOG_DIR  = "$env:USERPROFILE\.cc-connect"

switch ($Action) {
  "start" {
    Write-Host "▶ 启动 cc-connect 服务..." -ForegroundColor Cyan
    Start-Service -Name $SVC_NAME -ErrorAction Stop
    Write-Host "✅ 已启动" -ForegroundColor Green
  }
  "stop" {
    Write-Host "⏹ 停止 cc-connect 服务..." -ForegroundColor Yellow
    Stop-Service -Name $SVC_NAME -ErrorAction Stop
    Write-Host "✅ 已停止" -ForegroundColor Green
  }
  "restart" {
    Write-Host "🔄 重启 cc-connect 服务..." -ForegroundColor Cyan
    Restart-Service -Name $SVC_NAME -ErrorAction Stop
    Write-Host "✅ 已重启" -ForegroundColor Green
  }
  "status" {
    $svc = Get-Service -Name $SVC_NAME -ErrorAction SilentlyContinue
    if (-not $svc) {
      Write-Host "❌ 服务 $SVC_NAME 未安装" -ForegroundColor Red
      return
    }
    Write-Host "📊 $SVC_NAME 状态: $($svc.Status)" -ForegroundColor Cyan
    Write-Host "   启动类型: $($svc.StartType)"
  }
  "logs" {
    $logFile = "$LOG_DIR\service-output.log"
    if (-not (Test-Path $logFile)) {
      Write-Host "❌ 日志文件不存在: $logFile" -ForegroundColor Red
      return
    }
    Write-Host "📝 查看日志 (Ctrl+C 退出)..." -ForegroundColor Cyan
    Get-Content $logFile -Tail 30 -Wait
  }
  "uninstall" {
    Write-Host "⚠ 正在卸载 cc-connect 服务..." -ForegroundColor Yellow
    Stop-Service -Name $SVC_NAME -ErrorAction SilentlyContinue
    Start-Sleep 2
    sc.exe delete $SVC_NAME
    Write-Host "✅ 已卸载" -ForegroundColor Green
  }
}

使用方式：

# 查看状态
.\manage-cc-connect.ps1 status

# 启停
.\manage-cc-connect.ps1 start
.\manage-cc-connect.ps1 stop
.\manage-cc-connect.ps1 restart

# 跟踪日志（Ctrl+C 退出）
.\manage-cc-connect.ps1 logs

踩坑记录

1. cc-connect 自带的 daemon 命令不支持 Windows

# ❌ 这在 Windows 上行不通
cc-connect daemon install

# ✅ 应该用 nssm 或 sc.exe 包装（见上文方案）

这个命令只支持 Linux（systemd）和 macOS（launchd），在 Windows 上会报错。

2. nssm 输出编码问题

# 查看 nssm 配置时显示带 NUL 字符的乱码
& "C:\Program Files\nssm\nssm.exe" get "cc-connect" Application
# 输出可能是: E : \ s o f t w a r e \ ...

这是 nssm 的老问题（宽字符输出），不影响功能，查看时忽略即可。

3. 配置文件的路径

cc-connect 查找配置的默认顺序：

当前目录下的 config.toml
~/.cc-connect/config.toml

服务运行时当前目录是 C:\Windows\System32，不是用户目录。必须用 --config 显式指定配置路径，否则 cc-connect 找不到配置。

启动参数加上 --force，确保杀掉可能遗留的旧进程实例。

总结

cc-connect 注册为 Windows 服务，核心就是三步：

安装 nssm（或直接用 sc.exe）
注册服务（指定二进制路径、启动参数、配置文件路径）
设置自动启动（start= auto）

之后重启电脑，cc-connect 就会自动在后台运行，通过飞书/钉钉就能直接跟 Claude Code 对话，不再需要手动开终端启动进程了。

如果你已经在用 Docker 运行 cc-connect，那保持 Docker Desktop 开机自启 + 容器 restart: unless-stopped 也能达到同样的效果。Windows 原生服务的优势在于资源更轻量，没有 Docker 的额外开销。

posted @ 2026-05-26 18:31 司野良阅读(19) 评论(0) 收藏举报

刷新页面返回顶部

司野良

业余程序员，如有错误请多多指教