Programmatic API Key Management

本指南解释了如何利用 Unraid API CLI 通过编程方式创建、使用和删除 API 密钥，从而实现自动化工作流和脚本。

概述

unraid-api apikey 命令支持交互模式和非交互模式，适用于：

创建 API 密钥

跳转到 完整工作流示例 查看一切操作。

使用 --json 标志获取机器可读的输出：

unraid-api apikey --create --name "workflow key" --roles ADMIN --json

输出：

{
    "key": "your-generated-api-key-here",
    "name": "workflow key",
    "id": "generated-uuid"
}

使用 --json 标志获取机器可读的输出：

unraid-api apikey --create \
  --name "limited access key" \
  --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" \
  --description "Read-only access for monitoring" \
  --json

输出：

如果已有同名密钥，使用 --overwrite：

unraid-api apikey --create --name "existing key" --roles ADMIN --overwrite --json

警告

通过名称删除密钥，无提示：

删除 API 密钥

通过名称删除密钥，无提示：

通过名称删除密钥，无提示：

unraid-api apikey --delete --name "workflow key"

输出：

Successfully deleted 1 API key

通过名称删除密钥，无提示：

使用 --json 标志获取机器可读的删除确认：

unraid-api apikey --delete --name "workflow key" --json

成功输出：

{
    "deleted": 1,
    "keys": [
        {
            "id": "generated-uuid",
            "name": "workflow key"
        }
    ]
}

错误输出：

{
    "deleted": 0,
    "error": "No API key found with name: nonexistent key"
}

成功输出：

指定密钥不存在时：

unraid-api apikey --delete --name "nonexistent key"
# Output: No API keys found to delete

JSON 错误输出：

{
    "deleted": 0,
    "message": "No API keys found to delete"
}

完整工作流示例

JSON 错误输出：

#!/bin/bash
set -e

# 1. Create temporary API key
echo "Creating temporary API key..."
KEY_DATA=$(unraid-api apikey --create \
  --name "temp deployment key" \
  --roles ADMIN \
  --description "Temporary key for deployment $(date)" \
  --json)

# 2. Extract the API key
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')
echo "API key created successfully"

# 3. Use the key for operations
echo "Configuring services..."
curl -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "azure", "clientId": "your-client-id"}' \
  http://localhost:3001/graphql

# 4. Clean up (always runs, even on error)
trap 'echo "Cleaning up..."; unraid-api apikey --delete --name "temp deployment key"' EXIT

echo "Deployment completed successfully"

完整工作流示例

以下是一个临时访问权限供应的完整示例：

标志	描述	示例
--name <name>	密钥名称（必需）	--name "my key"
--roles <roles>	逗号分隔的角色	--roles ADMIN,VIEWER
--permissions <perms>	资源：操作对	--permissions "DOCKER:READ_ANY"
--description <desc>	密钥描述	--description "CI/CD key"
--overwrite	替换现有密钥	--overwrite
--json	机器可读输出	--json

可用角色： ADMIN（完整系统访问权限）、CONNECT（Unraid Connect 功能）、VIEWER（只读访问权限）、GUEST（有限访问权限）。

可用资源： ACTIVATION_CODE、API_KEY、ARRAY、CLOUD、CONFIG、CONNECT、CONNECT__REMOTE_ACCESS、CUSTOMIZATIONS、DASHBOARD、DISK、DISPLAY、DOCKER、FLASH、INFO、LOGS、ME、NETWORK、NOTIFICATIONS、ONLINE、OS、OWNER、PERMISSION、REGISTRATION、SERVERS、SERVICES、SHARE、VARS、VMS、WELCOME。

可用操作： CREATE_ANY、CREATE_OWN、READ_ANY、READ_OWN、UPDATE_ANY、UPDATE_OWN、DELETE_ANY、DELETE_OWN。

删除命令选项：

标志	描述	示例
--delete	启用删除模式	--delete
--name <name>	要删除的密钥（可选）	--name "my key"

如果省略 --name，命令将以交互式方式运行。

资源： ACTIVATION_CODE, API_KEY, ARRAY, CLOUD, CONFIG, CONNECT, CONNECT__REMOTE_ACCESS, CUSTOMIZATIONS, DASHBOARD, DISK, DISPLAY, DOCKER, FLASH, INFO, LOGS, ME, NETWORK, NOTIFICATIONS, ONLINE, OS, OWNER, PERMISSION, REGISTRATION, SERVERS, SERVICES, SHARE, VARS, VMS, WELCOME

操作： CREATE_ANY, CREATE_OWN, READ_ANY, READ_OWN, UPDATE_ANY, UPDATE_OWN, DELETE_ANY, DELETE_OWN

故障排除

常见错误消息:

• “API key 名称只能包含字母、数字和空格”：移除连字符、下划线或符号等特殊字符。
• “名称为 'x' 的 API key 已存在”：使用 --overwrite 标志或选择其他名称。
• “请至少为该 key 添加一个角色或权限”：指定 --roles 或 --permissions（或两者都指定）。

为故障排除，使用调试日志运行：

LOG_LEVEL=debug unraid-api apikey --create --name "debug key" --roles ADMIN