服务管理

server 命令组管理本机 North Coder daemon。桌面端和 CLI 使用同一套服务发现和生命周期机制，默认复用 127.0.0.1:8848 上的健康后端。

CLI 管理的 daemon metadata 写入 ~/.north-coder/server.json。开发模式使用独立 scope，不会误用用户已安装正式版的 metadata。

server start

启动一个后台 daemon 进程。

ncoder server start [OPTIONS]

选项

选项	默认值	说明
`--host`, `-h`	`127.0.0.1`	绑定地址。
`--port`, `-p`	自动选择	监听端口；未指定时优先使用 `8848`。
`--startup-timeout`	`30`	等待 health check 成功的秒数。
`--enable-remote-shutdown`	`false`	非 loopback 绑定时启用远程 admin shutdown endpoint。
`--require-version`	—	只复用指定版本的本地服务。

行为

检查同一 runtime scope 下是否已有 CLI daemon metadata。
如果 metadata 对应的进程健康且版本满足要求，直接返回 already_running。
默认 scope 下如果没有 metadata，会探测 127.0.0.1:8848 上是否已有健康的 North Coder 后端；可复用时返回 already_running。
未指定端口时优先使用 8848；如果被占用但不是可复用的 North Coder 后端，则让 OS 分配一个可用端口。
启动后台进程并等待 /api/health 返回有效 instance_id。
成功后写入 ~/.north-coder/server.json。
在终端输出可直接打开的访问 URL；--json 输出包含 token 和 access_urls。
启动失败或超时时清理子进程，不写入 metadata。

安全策略

绑定到 127.0.0.1、localhost、::1 时，自动启用 admin shutdown endpoint。
绑定到其他地址时，admin shutdown 默认禁用。如需启用，必须显式传入 --enable-remote-shutdown。
Token 通过环境变量传递给子进程，不出现在命令行参数中。
server start 会生成本次 daemon 的访问 token，并在启动结果中输出一次。daemon 日志不会记录明文 token。
日志目录和文件在 Unix 上使用受限权限（目录 0700，文件 0600）。

示例

# 基本启动
ncoder server start

# 指定端口
ncoder server start --port 19000

# 桌面端启动时要求复用同版本服务
ncoder server start --require-version 0.0.72-alpha.3

# 绑定到局域网
ncoder server start --host 0.0.0.0 --enable-remote-shutdown

JSON 输出

{
  "status": "started",
  "instance_id": "abc123",
  "pid": 12345,
  "host": "127.0.0.1",
  "port": 8848,
  "runtime_scope": "default",
  "log_path": "/Users/you/.north-coder/logs/server-startup_123.log",
  "access_urls": [
    "http://127.0.0.1:8848?token=abc123"
  ],
  "token": "abc123"
}

status 可能的值：

状态	说明
`started`	成功启动。
`already_running`	已有健康服务可复用。
`stale`	存在旧 metadata 但进程状态异常，需要手动处理。
`version_mismatch`	已有服务版本与 `--require-version` 不一致。
`port_occupied`	显式指定端口已被其他 North Coder 实例占用。
`spawn_failed`	子进程启动失败。
`timeout`	启动超时，子进程已被清理。

桌面端调用 server start --require-version 时，如果 default scope 的 CLI-managed daemon 版本不匹配，会先通过 server stop --force 停止旧 daemon，再重试启动当前桌面端打包的后端版本。关闭窗口只有在会停止本次桌面端创建/替换的 daemon 时才弹二次确认；auto-update 安装退出前会停止 default scope 的 CLI-managed daemon，确保重启后使用新版本后端。

server stop

停止 CLI 管理的 daemon 进程。

ncoder server stop [OPTIONS]

选项

选项	默认值	说明
`--force`, `-f`	`false`	跳过 health 验证，直接终止 metadata 指向的进程。

行为

读取 ~/.north-coder/server.json 获取 daemon 信息。
如果没有 metadata 或进程已退出，清理并报告。
执行 health check 确认 instance_id 匹配。
如果匹配，通过 admin shutdown API 优雅停止。
API 停止失败时，fallback 到进程终止。
确认进程退出后清理 metadata。

server stop 只管理 CLI-owned daemon。探测到的旧桌面 sidecar 或手动前台服务不会被误杀。

示例

# 优雅停止
ncoder server stop

# 强制停止（进程无响应时）
ncoder server stop --force

server status

查看本机服务状态。

ncoder server status [OPTIONS]

选项

选项	默认值	说明
`--verbose`, `-v`	`false`	显示日志路径等详细信息。

行为

优先读取 metadata 并执行 health check。
没有 metadata 时，探测 127.0.0.1:8848 上的健康 North Coder 后端。
验证 instance_id 匹配，避免把 stale metadata 当成有效服务。

JSON 输出

{
  "status": "running",
  "instance_id": "abc123",
  "pid": 12345,
  "host": "127.0.0.1",
  "port": 8848,
  "mode": "cli-daemon",
  "runtime_scope": "default",
  "uptime": "1h 23m 45s",
  "version": "0.0.72-alpha.3"
}

status 可能的值：

状态	说明
`running`	服务正常运行中。
`not_running`	没有可用本机服务。
`stale`	metadata 过期或实例不匹配。
`unhealthy`	进程存在但 health check 失败。

直接运行服务（serve）

serve 是底层命令，直接在前台启动 North Coder 后端，不创建 daemon metadata。日常使用推荐通过 server start 管理 daemon 生命周期，serve 适合调试、容器化部署或 systemd 托管。

ncoder serve [OPTIONS]

选项

选项	默认值	说明
`--host`	`0.0.0.0`	绑定地址。
`--port`	`8848`	监听端口。
`--token`	—	访问令牌（远程访问时必填）。环境变量：`NC_AUTH_TOKEN`。
`--serve-frontend` / `--no-serve-frontend`	打包时 `true`	是否服务前端静态资源。
`--frontend-dir`	—	自定义前端资源目录。
`--skip-update`	`false`	跳过自动更新检查。

典型用法

# 开发模式前台运行
ncoder serve --host 127.0.0.1 --port 8848

# 远程服务模式
ncoder serve --host 0.0.0.0 --port 8848 --token "$NORTH_CODER_TOKEN"

本页内容