设备与注册码

这页写给管理员：员工的电脑在企业后端里是怎么登记的，怎么把它分进团队、怎么吊销，以及怎么给没有浏览器的机器发凭据。

企业后端管的单位是设备，不是人。策略、预算按设备所在的组织和团队求值，账本、事件按设备记录。人通过设备挂上去：一个人可以有多台设备，一台设备同时最多绑一个人。

员工端看到的登录、凭据、状态检查写在企业登录，这页不重复。

设备从哪来

来源	适用	绑人吗	落在哪
sid-code login（飞书）	员工自己的电脑，主路径	绑到登录的人	新设备进 CTL_LOGIN_ORG_ID 组织（默认 default），不在任何团队
注册码 sid-code auth enroll	CI、构建机、没有浏览器或飞书的机器	不绑人	签发时指定的组织（和团队）

设备 ID 是客户端第一次需要时生成的 UUID，存在员工机器的 ~/.sid-code/device-id。

设备凭据的生命周期

登录或注册成功后，员工机器拿到一份设备凭据（~/.sid-code/device-credential.json），之后访问企业后端都带着它。

环节	规则
有效期	90 天（CTL_CREDENTIAL_TTL_DAYS）
续期	滑动：每次成功访问控制面都把过期时间顺延到「现在 + 90 天」。连续 90 天不用才过期
客户端同步	启动时最多每 24 小时调一次 /ctl/whoami，把服务端的过期时间写回本地。本地记录只是参考，是否失效以服务端返回 401 为准
重新登录 / 重新注册	这台设备的旧凭据作废，换一份新的
失效	过期、被吊销、本人登出、此人被吊销，服务端一律返回 401

凭据失效时，员工端状态栏提示一次「企业登录已失效，执行 /login 重新登录」。

在管理台里操作

页面在左侧菜单「设备」。上方是「设备列表」，下方是「注册码」。

设备列表

列	含义
设备	设备 ID
组织 / 团队	当前归属；不在团队显示 —
用户	绑定的人；注册码设备为空
平台 / 版本	例如 darwin-arm64、sid-code 版本
最近活跃	最近一次访问控制面的时间
状态	「有效」或「已吊销」；正在被遥控时另有「遥控中」

「有效」不代表凭据没过期

状态列只区分「有没有被吊销」，不看过期时间。一台 90 天没用、凭据已经过期的设备仍显示「有效」。判断设备是否还在用，看「最近活跃」。

列表没有搜索框。要找某台设备，从「用户」页、「成本」页点进来，或者在地址栏加 ?device_id=<ID>。

每行「操作」：

按钮	作用
生效配置	只读抽屉：这台设备此刻命中哪份策略、哪份预算（含本周期用量）、下发中的 Flag、最近一次 policy_enforced 上报
调整归属	改组织和团队，见下
轨迹 / 审计 / 成本	跳到对应页面，已按这台设备过滤
变更记录	这台设备的调整归属和吊销记录：谁、什么时候、从哪到哪、理由
吊销	见下

「生效配置」显示的是服务端此刻的求值结果。客户端要等下一次拉取才会变，策略最迟约 33 分钟（见策略）。抽屉里「最近一次 policy_enforced」为空，说明这台设备还没上报过策略已应用，无法确认客户端真的在执行。

调整归属

1. 在设备那一行点「调整归属」。
2. 「组织」必选；「团队」可以留空，留空表示只挂在组织上。团队要先在「组织与团队」页建好。
3. 「理由」必填，进审计。
4. 确定，提示「已调整，设备下一次请求控制面即生效」。归属没变化时提示「归属没有变化」，不写审计。

联动：

你做了什么	sid-code 什么时候知道	员工看到什么
把设备从组织层移进团队 platform	凭据不重签。服务端每次请求都按数据库里的归属求值，所以下一次请求就按新团队命中策略和预算	策略：要等客户端下一次拉取（重启、/login 或约 30 分钟的轮询）；预算：下一次拉取（启动或账本上报后）

调整之后员工重新 sid-code login，仍然保留你设的归属，不会被拉回登录组织。

吊销设备

1. 在设备那一行点「吊销」。
2. 「理由」必填，例如「员工离职」「设备丢失」。
3. 确定，提示「已吊销该设备全部凭据」。

效果：这台设备的全部凭据立即失效，下一次访问控制面返回 401。审计里记录吊销了几份凭据。

吊销设备不是永久封禁：设备的主人可以在这台电脑上重新 sid-code login，拿到新凭据，状态重新变回「有效」。注册码设备则要用新的注册码重新注册。要让一个人彻底用不了，吊销用户，见用户与登录。

	吊销设备	吊销用户
影响范围	这一台	此人名下全部设备 + 管理台会话 + 飞书 token
本人能否重新登录	能	不能，直到被恢复
能否管住注册码设备	能	不能（注册码设备不绑人）
理由	必填	不要求

两者都不会终止员工正在跑的会话，只是让它下一次访问企业后端时失败。

注册码

给不能走飞书登录的机器发凭据：CI、构建机、共享的远程开发机。注册码换来的设备不绑人，成本页里显示为「未登录设备」。

前提：服务端开启 CTL_ENROLL_ENABLED=true（默认关闭）。关闭时「签发注册码」按钮置灰，鼠标悬停显示原因。

签发

1. 「设备」页，「设备列表」右上角点「签发注册码」。

2. 填写：

   字段	说明
   组织 ID	必填，例如 acme
   组织名称	可选，组织不存在时用作名称
   团队 ID	可选，例如 platform。填了的话，用这个码注册的设备直接进这个团队
   备注	必填，写清楚发给谁、哪台机器，进审计

3. 确定后弹出注册码明文。只显示这一次，库里只存哈希。复制后交给对方。

注册码一次有效，默认 24 小时内可用（CTL_ENROLL_CODE_TTL_HOURS）。管理台签发时一律用这个默认值。

签发会顺手建组织和团队

组织或团队不存在时，签发注册码会直接创建它们，不做「组织与团队」页那样的 ID 格式检查。打错一个字母就会多出一个组织。签发前先到「组织与团队」页确认 ID。

「注册码」区列出所有签发过的码：组织、团队、备注、创建和过期时间、是否「已使用」。「签发记录」按钮看签发审计。

在机器上兑换

在那台机器上（已配好 backend.url）：

sid-code auth enroll --code <注册码> --org acme
# 签发时没指定团队、想放进团队的，加 --team：
sid-code auth enroll --code <注册码> --org acme --team platform

成功输出：

✓ 注册成功：acme / platform
  凭据有效期至 2027-01-14T03:04:07+00:00

然后用 sid-code auth status --verify 确认各条通道。这条命令需要 v0.1.610 之后的 sid-code。

结果	状态码	员工端提示
服务端没开 CTL_ENROLL_ENABLED	403	服务端未开启注册端点（CTL_ENROLL_ENABLED=false），请联系管理员打开后重试。
码错、已用、已过期，或 --org / --team 和码不符	401	注册码无效、已被使用或已过期（一次性码，且 24 小时内有效）。请向管理员重新申请。
这台设备已经绑给某个人	409	提示先执行 sid-code auth logout 解绑
这台设备已经在另一个组织	409	提示联系管理员调整归属

401 的几种原因故意不区分，避免有人用它试探码是否存在。员工报 401 时，到「注册码」区看这个码是不是「已使用」或已过期，再核对 --org。

同一组织里一台不绑人的设备重新注册，旧凭据作废，换新的。

签发时不指定团队，--team 可以建团队

码没有绑团队时，兑换方传的 --team 如果在组织里不存在，会被自动创建。要控制设备进哪个团队，签发时就把团队填上。

能力边界（如实说）

1. 设备 ID 由客户端生成，可以复制。 把 ~/.sid-code/ 目录整个拷到另一台电脑，后端会把两台当成同一台设备。凭据也随目录一起被拷走。

2. 吊销设备挡不住设备主人重新登录。 见吊销设备。

3. 状态列不反映过期。 见设备列表下的警告。

4. 管理台不能设注册码有效期。 签发时一律用 CTL_ENROLL_CODE_TTL_HOURS 的值（默认 24 小时）；要改只能改服务端配置并重启。

5. 注册码设备不绑人。 它的用量在成本页「按人看」里归到「未登录设备」一行，审计里没有人名。按人追责的场景不要用注册码。

常见问题

飞书登录的设备没进团队，团队层策略不生效

预期行为。新设备默认只在登录组织里。在设备行点「调整归属」分进团队；想让新设备直接落到你的组织，把 CTL_LOGIN_ORG_ID 改成你的组织 ID。

员工说「刚才还能用，现在全是 401」

在设备页看这台设备的「状态」和「变更记录」：是否被吊销。再看「用户」页此人是否被吊销。都不是的话，让员工跑 sid-code auth status --verify，看「服务端核验」一行。

一个人有好几台「设备」，其实只有一台电脑

每次重装系统、换用户目录、删掉 ~/.sid-code/ 都会生成新的设备 ID。旧的那几条不再活跃，可以吊销，留着也不影响什么。

相关

• 企业登录 —— 员工端的登录、凭据位置、状态检查
• 组织与团队 —— 先建团队，再调整归属
• 用户与登录 —— 吊销用户
• 策略 —— 设备层策略和遮蔽规则