# IT 部署指南（IT rollout）

使用一个注册令牌（enrollment token）在多台 Windows、macOS 和 Linux 计算机上安装 OpenChatly Capture。每台计算机独立注册并录制，无需登录 OpenChatly，您可以在需要时将其关联到具体人员。

Canonical page: https://openchatly.com/docs/zh/capture/rollout

IT 人员只需执行一条命令，即可在每台 Windows、macOS 或 Linux 计算机上安装 OpenChatly Capture（独立的录制应用）。安装程序会添加一个系统服务。每次登录时，该服务会自动注册计算机并开始录制。无需任何人手动登录 OpenChatly，也无需拥有 OpenChatly 账户。如果录制程序停止，该服务会在数秒内将其重启。

本页面专为 IT 团队和 OpenChatly 账户管理员编写。如果是个人在自己的计算机上安装，请参阅 [Capture → 安装 OpenChatly Capture](/docs/zh/capture#安装-openchatly-capture)。

## 工作原理

1. 账户管理员在 OpenChatly 中创建一个**注册令牌（enrollment token）**。
2. IT 人员在每台计算机上安装 `KortixCapture-x64.msi`，并传入 OpenChatly URL 和令牌。安装程序会将这两项信息写入注册表，并启动 **OpenChatly Capture** Windows 服务。
3. 每次 Windows 登录时，该服务会读取用户的 Windows 登录名（即用户主体名称，例如 `jane@corp.example`），并使用令牌注册该计算机。
4. 计算机获取一个设备令牌并开始录制，归属于该账户。如果使用个人令牌，则会将其关联到对应人员。其他任何计算机均会**不关联任何人**进行录制，这是一种正常状态：管理员可在需要时将其关联到具体人员。
5. 通知区域中的 OpenChatly Capture 图标会显示其正在录制。除此之外不会打扰用户。当策略中设置了通知时，用户会看到一次该通知。

该服务以 `LocalSystem` 身份运行。它会在每个已登录的会话中以该用户的身份启动录制程序，并在其停止后数秒内重新启动。注册令牌仅保留在服务中：存储该令牌的注册表项仅 SYSTEM 和管理员可读，用户的进程永远无法看到该令牌。

## 开始之前

- 为账户开启 Capture 并设置策略：包括录制内容、帧率、排除项、保留期限以及**用户看到的通知**。请参阅 [Capture → 策略](/docs/zh/capture#策略the-policy)。
- 用户无需拥有 OpenChatly 账户。无论计算机是否关联到个人，均可为账户进行录制。若要在计算机注册时将其关联到成员，请开启 **Approve each computer**（审批每台计算机）：OpenChatly 会根据计算机的登录邮箱建议对应的成员，您只需确认即可。
- 您需要具备 `capture.manage` 权限。账户所有者和管理员默认拥有此权限。

## 1. 创建注册令牌（Enrollment token）

在 OpenChatly 中，打开 **OpenChatly Capture** → **Devices**（设备），然后选择 **Company install**（企业安装）。创建一个令牌并填写以下信息：

| 字段 | 作用 |
|---|---|
| **Name**（名称） | 令牌的名称，例如计算机组名称。 |
| **For**（适用对象） | **Anyone at the company**（公司内任何人）：一个令牌用于多台计算机。这些计算机会在不关联任何人的情况下注册；您可以手动关联它们，或通过 **Approve each computer**（审批每台计算机）确认建议的成员。**A member**（指定成员）：个人令牌。无论谁登录，使用该令牌安装的每台计算机都会关联到该人员。当该人员离开账户时，令牌将失效。 |
| **Email domains**（邮箱域） | 仅限“任何人”令牌。只有使用这些域名登录计算机的人员才能完成注册。留空表示不限制。 |
| **Computer limit**（计算机数量上限） | 防止令牌泄露的安全上限。个人令牌默认为 1。留空表示无限制。 |
| **Valid for**（有效期） | 7 天、30 天或 90 天，或选择 **Never**（永不过期）。在过期前完成注册的计算机将继续录制。 |
| **Approve each computer**（审批每台计算机） | 每台新计算机均需等待管理员审批，即使其对应的人员已是账户成员。 |

OpenChatly 仅显示一次令牌（`kortix_enr_…`）。请复制该令牌及其旁边的安装命令。任何持有该令牌的人都可以在您撤销它之前将计算机注册到账户中，因此请像对待密码一样妥善保管。

通过 API 创建：向 `POST /v1/accounts/<account_id>/capture/enrollment-tokens` 发送 `{"name": "Pilot laptops", "email_domains": ["corp.example"], "max_devices": 20}`。
若要创建个人令牌，请添加 `"user_id": "<member>"`：该成员必须属于该账户，否则 API 将返回 `400 capture_enrollment_invalid` 错误。

## 2. 在每台 Windows 计算机上安装

在一台计算机上，以**管理员身份打开命令提示符（Command Prompt as administrator）**，然后粘贴 **Devices**（设备）→ **Company install**（企业安装）对话框（**Install on company computers**）中的命令。该命令会下载安装程序、静默安装、等待安装完成、检查 OpenChatly Capture 服务是否存在，并输出安装是否成功：

```bat
curl.exe -fsSL -o "%TEMP%\KortixCapture-x64.msi" https://github.com/kortix-ai/CompanyOS/releases/latest/download/KortixCapture-x64.msi && start /wait msiexec /i "%TEMP%\KortixCapture-x64.msi" /qn /l*v "%TEMP%\KortixCapture-install.log" KORTIX_URL=https://api.kortix.com ENROLLMENT_TOKEN=kortix_enr_... && sc query KortixCapture >nul 2>&1 && echo Kortix Capture installed. It records from the next Windows sign-in. || echo Install failed. Log: "%TEMP%\KortixCapture-install.log"
```

msiexec 单独运行时会立即返回并在后台进行安装，且使用 /qn 参数时不会显示任何错误（即使 MSI 文件路径错误也是如此）。配合 start /wait 和日志记录可以使安装结果变得可见。当 MSI 文件与命令放在同一位置时（例如在 Intune 或脚本中），简写形式如下

```bat
msiexec /i KortixCapture-x64.msi /qn KORTIX_URL=https://api.kortix.com ENROLLMENT_TOKEN=kortix_enr_...
```

`KORTIX_URL` 是您的 OpenChatly API 地址，不包含 `/v1`。自托管的 OpenChatly 会使用其自身的 API 地址。安装程序会将 `ENROLLMENT_TOKEN` 标记为隐藏，因此它不会出现在安装日志中。

若使用 Microsoft Intune，请将该 MSI 添加为业务线应用（line-of-business）或 Win32 应用，并使用上述命令行。若使用组策略（Group Policy）或其他工具，请在不传递属性的情况下安装 MSI，然后手动写入以下两个注册表值：

| 注册表项 (Key) | 值名称 (Value) | 类型 (Type) |
|---|---|---|
| `HKLM\SOFTWARE\Policies\Kortix\Capture` | `Url` | `REG_SZ` |
| `HKLM\SOFTWARE\Policies\Kortix\Capture` | `EnrollmentToken` | `REG_SZ` |

执行升级操作时（即使用较新的 MSI 运行 `msiexec /i`），如果不传递任何属性，原有的注册表值将被保留。

即使服务未能启动，安装程序也绝不会回滚：它会在条件允许时启动服务，而 Windows 会在每次开机约一分钟后自动启动该服务。如果 Windows 10 计算机上未安装 Microsoft Edge WebView2 运行时，MSI 会自动进行安装，因为 OpenChatly Capture 窗口需要依赖该运行时。如果用户直接双击 MSI 且未提供属性，安装结束后应用会自动打开，用户可从中进行登录。

## 3. 检查部署情况

**Devices**（设备）列表会显示每台已注册的计算机，并带有 **IT rollout**（IT 部署）徽章。这些计算机可能已关联到具体人员，也可能显示为 **Linked to no one**（未关联任何人），并展示其实时状态：录制中（recording）、已暂停（paused）或离线（offline）。计算机在首次 Windows 登录后的一分钟内会上报状态。

若要将计算机关联到个人，请在该计算机上选择 **Link to a person…**（关联到个人…）。此前未关联任何人时录制的内容将转移至该人员名下。请参阅 [Capture → 将计算机关联到个人](/docs/zh/capture#将计算机关联到个人)。

**Waiting for approval**（等待审批）列表会显示等待管理员处理的计算机：可能是令牌配置为需逐台审批，也可能是管理员撤销了该计算机。对于列表中的每台计算机，请选择 **Approve**（批准）（如果需要，还可以选择其录制归属人员）或 **Deny**（拒绝）。被批准的计算机将在一分钟内开始录制。

在计算机端：

```powershell
sc query KortixCapture
Get-Process kortix-capture | Select-Object Id, SessionId
```

服务状态为 `RUNNING`（运行中），并且在每个已登录的会话中都会运行一个 `kortix-capture` 进程。

## 移除计算机或停止部署

| 目标 | 操作 |
|---|---|
| 阻止新计算机注册 | 在 **Company install**（企业安装）中撤销令牌。已注册的计算机将继续录制。 |
| 停止单台计算机 | 在 **Devices**（设备）中撤销该设备，或在 **Waiting for approval**（等待审批）中拒绝它。其设备令牌将立即失效。在管理员批准之前，该计算机不会再次注册。 |
| 卸载 OpenChatly Capture | 运行 `msiexec /x KortixCapture-x64.msi /qn`（使用相同的 MSI 文件），或通过 **Settings → Apps → OpenChatly Capture → Uninstall** 进行卸载。服务和程序文件将被移除。计算机上的录制内容将保留在各自用户的配置文件中，直到达到保留期限被删除。 |

## 注册令牌的能力与限制

- 它会在其指定的域名、数量上限和有效期内，将计算机注册到一个账户中。它无法读取任何数据。
- 每台已注册的计算机都会获得一个设备令牌（device token），用于上传该计算机的录制内容并读取账户的策略。它无法读取录制内容本身。
- 计算机上报的登录名并不能证明是谁在使用它：该计算机的管理员可以修改此名称。因此，该名称本身永远不会自动关联计算机。它仅作为一个建议，供您在 **Approve each computer**（审批每台计算机）下进行确认。
- 已注册的计算机在再次注册时，会使用当前的设备令牌来证明自己的身份。如果仅复制了其机器密钥（machine key），则只有在管理员批准后（例如重新安装后）才能获得新令牌。
- 每次注册、令牌变更和审批决定都会记录在账户的审计日志中：`capture.device.enroll`、`capture.enrollment_token.create`、`capture.enrollment_token.revoke`、`capture.enrollment.approve`、`capture.enrollment.deny`、`capture.device.link`。

## enroll（注册）的响应状态

服务会将以下响应写入其日志（`%ProgramData%\Kortix\Capture\logs`）并自动重新请求。

| 响应 | 含义 | 计算机行为 |
|---|---|---|
| `enrolled` | 令牌有效。`member` 会指明关联的人员；若计算机未关联任何人，则为 `null`。 | 进行录制 |
| `pending` `approval_required` | 令牌要求逐台审批、管理员撤销了该计算机，或者它在没有当前令牌的情况下请求了新令牌。 | 等待；每分钟重新请求一次 |
| `401` `enrollment_token_invalid` | 令牌未知、已被撤销或已过期。 | 每小时重新请求一次 |
| `403` `enrollment_domain_not_allowed` | 登录域名不在令牌的允许域名列表中。 | 每 6 小时重新请求一次 |
| `403` `enrollment_limit_reached` | 令牌已达到计算机数量上限。 | 每小时重新请求一次 |
| `403` `enrollment_denied` | 管理员拒绝了该计算机。 | 每 6 小时重新请求一次 |
| `403` `capture_disabled` | 该账户的 Capture 功能已关闭。 | 每小时重新请求一次 |

## macOS 部署

IT 人员会将 OpenChatly URL 和令牌写入一个仅限 root 访问的文件，然后安装该软件包。该软件包会安装 `Kortix Capture.app`（具有开发者 ID 签名并经过公证）、一个用于保存令牌并为每个登录用户进行注册的机器服务（LaunchDaemon），以及一个在每个会话中进行录制的代理程序（agent）。

```bash
sudo mkdir -p "/Library/Application Support/Kortix/Capture"
echo '{"url":"https://api.kortix.com","enrollment_token":"kortix_enr_..."}' | sudo tee "/Library/Application Support/Kortix/Capture/config.json" >/dev/null
sudo chmod 600 "/Library/Application Support/Kortix/Capture/config.json"
curl -fsSL -o /tmp/KortixCapture-universal.pkg https://github.com/kortix-ai/CompanyOS/releases/latest/download/KortixCapture-universal.pkg && sudo installer -pkg /tmp/KortixCapture-universal.pkg -target / && echo "Kortix Capture installed."
```

若使用 MDM（移动设备管理），请部署该软件包以及一个针对域 `ai.kortix.capture` 的配置描述文件（configuration profile），其中包含 `Url` 和 `EnrollmentToken` 两个键。配置描述文件可被计算机上的所有用户读取；当令牌必须保持机密时，请改用仅限 root 访问的文件。

macOS 会请求用户允许一次“屏幕录制”（Screen Recording）。隐私偏好策略控制（PPPC，Privacy Preferences Policy Control）描述文件可以为 `ai.kortix.capture` 预先批准“辅助功能”（Accessibility）和“输入监控”（Input Monitoring）权限；但对于“屏幕录制”，它只能让标准用户自行批准。若要卸载 OpenChatly Capture，请运行：`sudo "/Applications/Kortix Capture.app/Contents/Resources/uninstall.sh"`。

## Linux

```bash
sudo install -d -m 755 /etc/kortix
echo '{"url":"https://api.kortix.com","enrollment_token":"kortix_enr_..."}' | sudo tee /etc/kortix/capture.json >/dev/null
sudo chmod 600 /etc/kortix/capture.json
curl -fsSL -o /tmp/kortix-capture_amd64.deb https://github.com/kortix-ai/CompanyOS/releases/latest/download/kortix-capture_amd64.deb && sudo apt-get install -y /tmp/kortix-capture_amd64.deb && echo "Kortix Capture installed."
```

该软件包会安装一个机器服务（`kortix-capture-machine`），用于保存令牌并为每个登录到图形会话的用户进行注册；同时还会安装一个用户服务，用于在每个会话中进行录制。OpenChatly Capture 支持录制 X11 会话；对于 Wayland 会话，目前可以完成注册，但尚无法进行录制。若要卸载，请运行：`sudo apt purge kortix-capture`。

如果在 macOS 或 Linux 上没有配置文件，每位用户需点击 OpenChatly Capture 图标，然后选择 **Sign in with OpenChatly…**（使用 OpenChatly 登录…）（请参阅 [Capture → 安装 OpenChatly Capture](/docs/zh/capture#安装-openchatly-capture)）。
