访问令牌
Linkr KVM 提供 访问令牌（Access Token） 功能，用于在无需 Web 登录会话的情况下，通过 API 以编程方式访问 KVM 的部分能力。适用于自动化脚本、监控集成、第三方工具调用等场景。
访问令牌等同于 API Key，创建后可用于调用设备的公开 API 接口。
功能概述
| 能力 | 说明 |
|---|---|
| Web 界面管理 | 在系统设置中创建、查看名称、删除访问令牌 |
| 密码验证 | 生成新令牌时需输入 KVM 登录密码，防止未授权创建 |
| 一次性展示 | 令牌明文仅在创建成功时显示一次，关闭弹窗后无法再次查看 |
| 持久保存 | 令牌保存在设备本地配置中，重启后仍然有效，直至手动删除 |
适用场景
- 远程截图：定时获取 KVM 当前画面快照，用于监控或巡检
- 远程控制：通过 API 发送控制指令（键盘、鼠标等）
- 自动化集成：将 KVM 接入 CI/CD、运维平台或自定义脚本
安全提示
访问令牌拥有与创建者相当的 API 访问权限。请妥善保管，切勿提交到公开代码仓库或分享给不可信方。若令牌泄露，请立即在管理界面删除并重新生成。
操作步骤
1. 进入系统设置
- 打开 KVM 管理 Web 界面并登录。
- 点击左侧边栏的 系统设置（设置图标）。
- 找到 访问令牌 折叠面板。
2. 生成新令牌
- 点击 + 生成 按钮，弹出「访问令牌」对话框。
- 填写 密钥名称（必填）：
- 仅允许英文字母
a-z、数字0-9和连字符- - 必须以字母或数字开头，不能以
-开头或结尾 - 最长 20 个字符
- 示例：
monitor-script、ci-deploy-01
- 仅允许英文字母
- 填写 用户密码（必填）：输入当前 KVM 管理账号的登录密码，用于身份验证。
- 点击绿色 生成 按钮。
3. 保存令牌
生成成功后，对话框会显示完整的访问令牌字符串（以 radxa_linkr_ 为前缀）。
- 点击令牌右侧的 复制 图标，将令牌保存到安全位置（密码管理器、密钥管理系统等）。
- 确认已妥善保存后，关闭对话框。
重要
令牌明文只会在创建时显示一次。关闭弹窗后，界面和 API 均无法再次获取完整令牌内容。若遗失令牌，只能删除旧条目并重新生成。
4. 管理已有令牌
在 访问令牌 面板中，已创建的令牌以 密钥名称 列表形式展示：
- 列表中不显示令牌明文，仅显示名称，便于识别用途。
- 点击条目右侧的 删除 图标，确认后即可吊销该令牌，吊销后立即失效。
使用访问令牌调用 API
认证方式
在 HTTP 请求头中携带访问令牌：
Authorization: token <你的访问令牌>
示例：
curl -H "Authorization: token radxa_linkr_xxxxxxxx" \
https://<kvm-ip>/api/public/snapshot \
--output snapshot.jpg
请将 <kvm-ip> 替换为 KVM 的实际 IP 地址或域名（本地局域网 IP、Tailscale IP 等均可）。
可用公开 API
当前支持通过访问令牌认证的公开接口如下：
| 接口 | 方法 | 说明 |
|---|---|---|
/api/public/snapshot | GET | 获取当前画面 JPEG 截图 |
/api/public/control | POST | 发送远程控制指令（请求体为控制协议数据） |
获取截图示例
curl -H "Authorization: token radxa_linkr_xxxxxxxx" \
"https://192.168.1.100/api/public/snapshot" \
-o snapshot.jpg
成功时返回 image/jpeg 格式的图片数据。
发送控制指令示例
curl -X POST \
-H "Authorization: token radxa_linkr_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '<控制数据>' \
"https://192.168.1.100/api/public/control"
控制数据的格式取决于 KVM 控制协议，具体字段请参考 API 文档或集成 SDK。
认证失败
若返回 403 No Permission，请检查：
Authorization头格式是否为token <令牌>（注意token与令牌之间有一个空格）- 令牌是否完整、未被截断
- 该令牌是否已被删除
- KVM 设备 IP 或网络是否可达
令牌格式说明
- 前缀：
radxa_linkr_ - 主体：Base64 URL 编码的随机字符串（约 86 字符）
- 示例：
radxa_linkr_-yDJ3JYDST0BygX5ltq1aFfOom0imn6hnfLTrl4-fDgHTkO8Uk0vdkf_Gxuia_T-fn07GJmZ_MDvhRLnLQ73WA
每个令牌的名称在设备上必须唯一，不可重复创建同名密钥。
安全建议
- 最小权限原则：为不同用途创建不同名称的令牌，便于单独吊销。
- 定期轮换：建议定期删除旧令牌并重新生成，尤其在人员变动或脚本迁移后。
- 安全存储：使用环境变量或密钥管理工具存放令牌，不要硬编码在源码中。
- HTTPS 访问：生产环境建议通过 HTTPS 访问 KVM API，避免令牌在传输中被窃听。
- 及时吊销：发现泄露或不再使用时，立即在系统设置中删除对应令牌。
常见问题
提示「名称格式错误」
密钥名称不符合规则。请确认：
- 只包含
a-z、0-9和- - 以字母或数字开头
- 不以
-结尾
提示密码错误
生成令牌时输入的用户密码与 KVM 登录密码不一致。请使用当前管理账号的正确密码。
提示名称已被占用
同一设备上不能创建两个相同名称的令牌。请更换密钥名称，或先删除同名旧令牌。
复制失败
若浏览器不支持剪贴板 API（如非 HTTPS 且非 localhost 环境），请手动选中令牌文本复制。
删除令牌后脚本仍报错 403
删除操作立即生效。请在脚本或环境中更新为新令牌，或重新生成并配置。