# 在 OAK Apps 和脚本中使用 Hub API 密钥

当您需要将 Luxonis Hub API 密钥 传递给本地脚本或未采用到 Luxonis Hub 的设备，且不希望将密钥暴露在源代码管理时，请参考本页。

有关创建和管理 API 密钥本身，请参阅 [Luxonis Hub 中的 API 密钥](https://docs.luxonis.com/cloud/api/api-keys.md)。本页重点介绍如何安全地将这些密钥用于 Luxonis 软件。

通过 Luxonis Hub 管理的已采用设备和 OAK Apps 不需要团队 API 密钥。Hub 使用比共享团队 API 密钥更合适的设备级权限为其处理身份验证。

> **Hub API 密钥拥有完整团队管理员权限**
> 将 Hub API 密钥视为高机密性密钥。它们目前对您团队的资源拥有完整的管理员权限。
> [查看更多](https://docs.luxonis.com/cloud/api/api-keys.md)
> .

手动 API 密钥处理主要适用于：

 * 未采用到 Luxonis Hub 且需要从 Models Registry 下载私有模型的设备
 * 本地脚本

不要将 API 密钥直接放置在 git 跟踪的文件中，例如 oakapp.toml、Python 源文件、JSON、YAML 或 shell 脚本。相反，使用仅运行时的注入模式，例如环境变量、.env 文件或 oakctl 登录流程。

## 一般建议

 * 切勿直接将 API 密钥提交 到仓库（例如 git 下的 .toml、.json、.yaml 或 .py 文件）。
 * 优先使用环境变量或 .env 文件（通过 .gitignore 排除在 git 之外）。
 * 除非有特定的非 Hub 需求，否则不要将团队 API 密钥添加到已采用设备或 Hub 管理的 OAK App 工作流中。
 * 当确实需要密钥时，优先使用**oakctl 管理的身份验证**或本地运行时注入。
 * 仅将 .env 文件保留在本地，并避免共享。

## 模式和安全设置选项

#### Standalone Mode

## 何时无需手动传递密钥

如果设备已采用到 Luxonis Hub，或者应用已通过 Hub 部署和管理，您通常无需手动管理团队 API 密钥。Hub 通过已采用设备流程和设备级权限处理身份验证。

## 本地和设备端设置

### 选项1 - 设备已采用

如果设备已在 Hub 中被您的团队采用，则无需手动提供团队 API 密钥。使用以下命令运行应用：

```bash
oakctl app run .
```

### 选项2 - 覆盖密钥

如果设备未采用到 Hub，请覆盖 DEPTHAI_HUB_API_KEY。

在这种情况下，从本地的 .env 文件中加载值：

```python
import os
from dotenv import load_dotenv

load_dotenv(override=True)

print(os.environ["DEPTHAI_HUB_API_KEY"])
```

然后将密钥存储在 main.py 旁边的 .env 文件中：

```bash
cd <INSERT_PATH_TO_PROJECT>
echo "DEPTHAI_HUB_API_KEY=<INSERT_YOUR_DEPTHAI_HUB_API_KEY>" > .env
echo ".env" >> .gitignore
```

然后运行：

```bash
oakctl app run .
```

oakctl 将 .env 文件复制到设备上的应用环境中。您的应用仍需要自己的逻辑在运行时读取该值，例如使用 dotenv.load_dotenv()。

#### Peripheral Mode

## oakctl 管理的身份验证

如果 oakctl 正在为未采用到 Hub 的设备驱动工作流，请使用其 Hub 登录流程，而不是手动硬编码原始密钥：

```bash
oakctl hub login
oakctl run-script python3 main.py
```

登录后，oakctl 向脚本提供 Hub 身份验证上下文。稍后您可以使用 oakctl hub logout 登出。

## 本地脚本设置

如果您直接运行脚本，请使用以下模式之一：

### 选项1 - 内联参数

从 CLI 参数读取值：

```python
_, args = initialize_argparser()

if args.api_key:
    print(args.api_key)
```

从命令行调用：

```bash
python3 <INSERT_PATH_TO_PROJECT>/main.py -api <INSERT_YOUR_DEPTHAI_HUB_API_KEY>
```

### 选项2 - .env 文件

从本地的 .env 文件加载密钥：

```python
import os
from dotenv import load_dotenv

load_dotenv(override=True)
print(os.environ["DEPTHAI_HUB_API_KEY"])
```

然后执行以下命令：

```bash
cd <INSERT_PATH_TO_PROJECT>
echo "DEPTHAI_HUB_API_KEY=<INSERT_YOUR_DEPTHAI_HUB_API_KEY>" > .env
echo ".env" >> .gitignore
python3 <INSERT_PATH_TO_PROJECT>/main.py
```

### 选项3 - 导出的环境变量

从进程环境读取密钥：

```python
import os
print(os.environ["DEPTHAI_HUB_API_KEY"])
```

然后执行：

```bash
cd <INSERT_PATH_TO_PROJECT>
export DEPTHAI_HUB_API_KEY=your_key_here
python3 main.py
```

## 示例

请参阅 [oak-examples 中的通用神经网络示例](https://github.com/luxonis/oak-examples/blob/dynamic_calib/neural-networks/generic-example/main.py)
以了解一个实用模式。