API Key 与认证

注意

不要在没有反向代理、TLS、显式管理员凭据和 secret key 配置的情况下，直接把 SkillFlaw 端口暴露到公网。 生产环境至少应显式设置 SKILLFLAW_SUPERUSER、SKILLFLAW_SUPERUSER_PASSWORD，并优先使用 SKILLFLAW_SECRET_KEY_FILE 管理密钥文件。 更多说明请参阅配置受保护的 SkillFlaw 服务。

认证凭据用于防止未授权访问你的 SkillFlaw 服务、流程，以及流程中通过组件连接的外部服务。

在 SkillFlaw 中，常见凭据分为三类：

• SkillFlaw API Key：用于调用 SkillFlaw API，以及授权服务端执行流程、上传文件等动作。
• 组件 API Key：用于 SkillFlaw 与外部服务之间的鉴权，例如模型服务商、数据库或第三方 API。
• 认证环境变量：用于控制 SkillFlaw 的用户认证、API Key 校验、Webhook 鉴权与 Cookie 行为。

SkillFlaw API Key

你可以使用 SkillFlaw API Key 以编程方式调用 SkillFlaw。

默认情况下，大多数 SkillFlaw API 端点（例如 /api/v1/run/$FLOW_ID）都需要 API Key 认证。

SkillFlaw 支持两种 API Key 校验来源：

• db：校验数据库中保存的 SkillFlaw API Key（默认）
• env：使用环境变量 SKILLFLAW_API_KEY 参与校验，适合通过部署配置统一注入 API Key 的场景

如果你希望 Webhook 端点也强制启用 API Key 校验，请使用 SKILLFLAW_WEBHOOK_AUTH_ENABLE。 如果你要为 SkillFlaw MCP 服务配置认证，请参阅将 SkillFlaw 用作 MCP 服务器。

SkillFlaw API Key 的权限边界

SkillFlaw API Key 继承创建该 Key 的用户权限。 也就是说，你创建的 API Key 拥有与你当前账号一致的访问范围，包括你有权访问的流程、组件和 SkillFlaw 数据。

在单用户环境中，你通常就是超级用户，因此你创建的 API Key 也具有超级用户权限。

在多用户环境中：

• 非超级用户不能通过自己的 API Key 访问他人资源
• 超级用户也不能直接绕过资源归属去运行其他用户拥有的流程
• 如果要安全地管理用户与多账户访问，必须先完成受保护部署配置

创建 SkillFlaw API Key

你可以在 SkillFlaw 的 Settings 中创建 API Key。

保留的 skillflaw api-key CLI 子命令已经不再负责创建 API Key，它只会提示“未认证的 CLI API Key 创建流程已不再支持”。

SkillFlaw Settings

1. 在 SkillFlaw 页头点击个人头像，然后选择 Settings。
2. 点击 SkillFlaw API Keys。
3. 点击 Add New。
4. 输入名称，然后点击 Create API Key。
5. 复制并妥善保存该 Key。

SkillFlaw CLI

skillflaw api-key 当前只保留迁移提示作用，不再从终端直接生成 API Key。

当前 CLI 行为请参阅 skillflaw api-key。

使用 SkillFlaw API Key

调用 SkillFlaw API 时，可以通过 x-api-key 请求头或查询参数传入 API Key。

HTTP header

_10

curl -X POST \

_10

"http://$SKILLFLAW_SERVER_ADDRESS/api/v1/run/$FLOW_ID?stream=false" \

_10

-H "Content-Type: application/json" \

_10

-H "x-api-key: $SKILLFLAW_API_KEY" \

_10

-d '{"inputs": {"text": ""}, "tweaks": {}}'

Query parameter

_10

curl -X POST \

_10

"http://$SKILLFLAW_SERVER_ADDRESS/api/v1/run/$FLOW_ID?x-api-key=$SKILLFLAW_API_KEY" \

_10

-H "Content-Type: application/json" \

_10

-d '{"inputs": {"text": ""}, "tweaks": {}}'

更多请求示例请参阅开始使用 SkillFlaw API与使用 SkillFlaw API 触发流程。

跟踪 API Key 使用情况

默认情况下，SkillFlaw 会在数据库中记录 API Key 的 total_uses 与 last_used_at 等使用痕迹。

如果你希望在高并发场景下降低这类写入带来的数据库竞争，可以在环境变量中设置：

_10

SKILLFLAW_DISABLE_TRACK_APIKEY_USAGE=True

撤销 API Key

如果要撤销并删除 API Key：

1. 在 SkillFlaw 页头点击个人头像，然后选择 Settings。
2. 点击 SkillFlaw API Keys。
3. 勾选你要删除的 Key。
4. 点击 Delete。

删除后，该 Key 会立即失效。

组件 API Key

组件 API Key 用于授权 SkillFlaw 访问外部服务，例如模型服务商、数据库、搜索 API 或其他第三方系统。 这类 Key 不是 SkillFlaw 平台自身的 API Key。

在 SkillFlaw 中，你通常会把组件 API Key 保存在 Settings 的全局变量中，或者从运行时环境导入。 更多说明请参阅全局变量。

组件 API Key 的真实创建、吊销与轮换，仍然发生在服务提供方自己的平台中。 SkillFlaw 只负责加密存储该值，或存储一个安全引用。

如果你希望减少流程数据落库时携带的敏感信息，可以设置：

_10

SKILLFLAW_REMOVE_API_KEYS=True

这样可以在流程保存到数据库前移除 API Key / Token 类型字段。 另外，在导入与导出流程时，也可以选择不导出 API Key。

认证环境变量

本节说明与认证直接相关的环境变量。

推荐模板请优先参考项目根目录的 .env.example。

AUTO_LOGIN 兼容变量

旧版本中与 AUTO_LOGIN 相关的兼容变量已经不再是 SkillFlaw 的主要认证方案。 应使用本页介绍的显式管理员凭据、API Key 校验来源、Webhook 鉴权和 Cookie 配置。

SKILLFLAW_ENABLE_SUPERUSER_CLI

该变量控制 skillflaw superuser 命令是否可用。

• 默认值：true
• 生产环境建议：false

_10

SKILLFLAW_ENABLE_SUPERUSER_CLI=False

更多说明请参阅 skillflaw superuser。

SKILLFLAW_SUPERUSER 与 SKILLFLAW_SUPERUSER_PASSWORD

这两个变量用于指定 SkillFlaw 的引导超级用户账号与密码。

_10

SKILLFLAW_SUPERUSER=administrator

_10

SKILLFLAW_SUPERUSER_PASSWORD=securepassword

如果未显式设置，系统会回退到默认值 skillflaw / skillflaw。 这些默认值只适合本地临时调试，绝不能直接用于真实环境。

SKILLFLAW_SECRET_KEY_FILE 与 SKILLFLAW_SECRET_KEY

这两个变量共同决定运行时用于加密敏感信息的 secret key 来源。

推荐方式是：

• 使用 SKILLFLAW_SECRET_KEY_FILE 指向一个仅本机可读的密钥文件
• 运行时读取文件内容本身作为 secret key

_10

SKILLFLAW_SECRET_KEY_FILE=~/.skillflaw/secret_key

运行时行为如下：

• 如果设置了 SKILLFLAW_SECRET_KEY_FILE，SkillFlaw 会优先使用该文件内容
• 如果同时显式提供 SKILLFLAW_SECRET_KEY，SkillFlaw 会把该值写入目标密钥文件
• 如果两者都未提供，但存在 CONFIG_DIR，SkillFlaw 会在 CONFIG_DIR/secret_key 自动生成并保存一个随机密钥

因此：

• 推荐：在部署中显式维护 SKILLFLAW_SECRET_KEY_FILE
• 兼容支持：可以直接提供 SKILLFLAW_SECRET_KEY
• 不建议：依赖隐式自动生成后再用于多实例生产环境

生成并写入密钥文件

在 macOS 或 Linux 上，你可以先生成高熵随机密钥，再写入本地文件：

_10

python3 - <<'PY'

_10

from pathlib import Path

_10

from secrets import token_urlsafe

_10

_10

path = Path.home() / '.skillflaw' / 'secret_key'

_10

path.parent.mkdir(parents=True, exist_ok=True)

_10

path.write_text(token_urlsafe(32), encoding='utf-8')

_10

print(path)

_10

PY

然后在 .env 中引用该文件：

_10

SKILLFLAW_SECRET_KEY_FILE=~/.skillflaw/secret_key

SKILLFLAW_NEW_USER_IS_ACTIVE

该变量控制超级用户新建账号时，是否自动激活。

• False（默认）：新建用户默认未激活，需要管理员显式激活
• True：新建用户自动激活

_10

SKILLFLAW_NEW_USER_IS_ACTIVE=False

只有超级用户才能管理用户账号。

SKILLFLAW_API_KEY_SOURCE

该变量控制 SkillFlaw 如何校验 x-api-key。

值	说明
db（默认）	校验数据库中保存的 SkillFlaw API Key
env	使用环境变量 SKILLFLAW_API_KEY 参与校验；适合通过部署配置统一注入 API Key 的场景

_10

SKILLFLAW_API_KEY_SOURCE=db

当 SKILLFLAW_API_KEY_SOURCE=env 时，部署中设置的 SKILLFLAW_API_KEY 可作为统一注入的运行时 API Key。 这类模式适合单租户部署、自动化环境或使用 Secret 注入 API Key 的场景。

启用示例：

_10

SKILLFLAW_API_KEY_SOURCE=env

_10

SKILLFLAW_API_KEY=your-secure-api-key

请求示例：

_10

curl -X POST \

_10

"http://SKILLFLAW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false" \

_10

-H "Content-Type: application/json" \

_10

-H "x-api-key: your-secure-api-key" \

_10

-d '{"inputs": {"text": ""}, "tweaks": {}}'

Kubernetes Secret 示例

_10

apiVersion: v1

_10

kind: Secret

_10

metadata:

_10

name: skillflaw-api-key

_10

type: Opaque

_10

stringData:

_10

api-key: "YOUR_API_KEY"

_10

env:

_10

- name: SKILLFLAW_API_KEY_SOURCE

_10

value: "env"

_10

- name: SKILLFLAW_API_KEY

_10

valueFrom:

_10

secretKeyRef:

_10

name: skillflaw-api-key

_10

key: api-key

SKILLFLAW_CORS_*

在前后端分离部署下，跨域请求中的 Cookie 与认证头行为由 SKILLFLAW_CORS_* 变量控制。

变量	类型	默认值	说明
SKILLFLAW_CORS_ALLOW_CREDENTIALS	Boolean	True	是否允许跨域请求携带 Cookie 与认证头
SKILLFLAW_CORS_ALLOW_HEADERS	List[String] / String	*	允许的请求头
SKILLFLAW_CORS_ALLOW_METHODS	List[String] / String	*	允许的 HTTP 方法
SKILLFLAW_CORS_ORIGINS	String	*	允许的来源

危险

默认的宽松跨域配置只适合本地或受控环境。 在生产环境中，应显式收敛 SKILLFLAW_CORS_ORIGINS，必要时同时收敛允许的方法与请求头。

SSRF 保护

以下变量用于控制 API Request 组件 的 SSRF 防护：

变量	类型	默认值	说明
SKILLFLAW_SSRF_PROTECTION_ENABLED	Boolean	False	是否开启 SSRF 防护
SKILLFLAW_SSRF_ALLOWED_HOSTS	List[String]	未设置	允许跳过 SSRF 检查的主机、IP 或 CIDR

SKILLFLAW_WEBHOOK_AUTH_ENABLE

该变量控制 Webhook 端点是否强制要求 API Key 认证。

变量	类型	默认值	说明
SKILLFLAW_WEBHOOK_AUTH_ENABLE	Boolean	False	为 True 时，Webhook 必须带 API Key；为 False 时，Webhook 默认按流程拥有者身份执行

_10

SKILLFLAW_WEBHOOK_AUTH_ENABLE=True

当开启后，请求必须通过请求头或查询参数提供 API Key。 如果缺少 API Key，请求会直接返回 403。

配置受保护的 SkillFlaw 服务

对于共享网络、多用户或公网可访问的 SkillFlaw 部署，建议至少完成以下配置。

1. 准备 .env

_10

SKILLFLAW_SUPERUSER=administrator

_10

SKILLFLAW_SUPERUSER_PASSWORD=securepassword

_10

SKILLFLAW_SECRET_KEY_FILE=~/.skillflaw/secret_key

_10

SKILLFLAW_NEW_USER_IS_ACTIVE=False

_10

SKILLFLAW_ENABLE_SUPERUSER_CLI=False

你也可以额外加入数据库、缓存、日志与前端路径等配置。

2. 启动 SkillFlaw

_10

uv run skillflaw run --env-file .env

默认地址通常为 http://localhost:7860。

3. 以管理员身份登录

1. 打开 http://localhost:7860/login
2. 使用 SKILLFLAW_SUPERUSER 与 SKILLFLAW_SUPERUSER_PASSWORD 登录
3. 进入管理员入口，管理用户、重置密码与分配权限

4. 为其他用户创建账号

1. 打开用户管理页
2. 点击 New User
3. 输入用户名与密码
4. 视需要决定是否立即激活账号
5. 视需要决定是否授予超级用户权限
6. 保存后把初始凭据安全地发送给用户

另请参阅

• SkillFlaw 环境变量
• 全局变量
• SkillFlaw CLI