> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Token 配置

> AgentEye GitHub Token 配置文档。

GitHub 个人访问令牌（PAT）是解锁所有 AgentEye 资源的唯一凭证。使用一个令牌，您即可拉取 Docker 镜像、下载发布版二进制文件并安装 Python wheel 包，无需对各组件分别登录，也无需在团队内传递共享密钥。所有 AgentEye 资源均通过 `agenteye-enterprise` GitHub 组织分发；一旦您的组织获得访问权限，每位开发者或运维人员可自行生成并轮换各自的令牌，从而实现按人可审计、可撤销的访问控制。

在每台机器上，将令牌设置为环境变量并配置 Docker 凭证：

```bash theme={null}
export AGENTEYE_TOKEN=<your-github-pat>
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
```

> **用户名说明：** GHCR 会忽略 `docker login` 中的用户名，完全依赖令牌进行认证，因此任意非空值均可使用。本文档使用 `-u x` 以保持简洁；在创建 Kubernetes 镜像拉取密钥的部署清单中，可使用更具描述性的用户名，例如 `agenteye-enterprise`。两种写法均可接受。

***

## 方案 A：经典令牌（推荐）

经典令牌是 AgentEye 最可靠的选择，因为 GHCR 的 `docker login` 和镜像拉取流程对经典令牌的支持最为全面且稳定。两个权限范围即可覆盖所有需求（拉取镜像和下载发布资源），一次认证即可完成，无需排查注册表的各种异常。其中 `read:packages` 是真正意义上的只读权限；而 `repo` 是唯一能够访问私有发布资源的经典权限范围，其定义本身较为宽泛——GitHub 将其定义为对私有仓库的完全控制权（读写权限）。

### 1. 创建令牌

前往 **GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)**。

| 字段             | 值                                               |
| -------------- | ----------------------------------------------- |
| **Note**       | `agenteye-<机器名或团队名>`（例如 `agenteye-prod-server`） |
| **Expiration** | 根据您的安全策略设置有效期；90 天是合理的默认值                       |

> **标签说明：** GitHub 对经典令牌将此字段标记为 **Note**，对细粒度令牌标记为 **Token name**。两者用途相同：作为便于后续审计和撤销的可读标识符。

### 2. 选择权限范围

| 权限范围            | 用途说明                                                                                                                 |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `read:packages` | 从 `ghcr.io/agenteye-enterprise/` 拉取 Docker 镜像及下载包资源                                                                  |
| `repo`          | 读取 `agenteye-enterprise/releases` 中的私有仓库内容、原始文件及发布资源。这是 GitHub 宽泛的"完全控制私有仓库"范围（读写权限），并非只读范围——它只是唯一能授予私有发布资源访问权限的经典范围 |

无需其他权限范围。

### 3. 生成并复制令牌

点击 **Generate token** 并立即复制令牌值；该值仅显示一次。请将其存储至您的密钥管理器或环境变量中。

***

## 方案 B：细粒度令牌

细粒度令牌可将访问范围限定在特定仓库和权限上，是最严格的最小权限选项。当您的组织安全策略要求使用细粒度令牌时，请选择此方案。

> **注意：** GHCR 对细粒度令牌的支持不如经典令牌稳定。如果按照以下步骤操作后 `docker login` 或 `docker pull` 失败，请回退至经典令牌（方案 A）。

### 1. 创建令牌

前往 **GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token**。

| 字段                    | 值                                                             |
| --------------------- | ------------------------------------------------------------- |
| **Token name**        | `agenteye-<机器名或团队名>`（例如 `agenteye-prod-server`）               |
| **Expiration**        | 根据您的安全策略设置有效期；90 天是合理的默认值                                     |
| **Resource owner**    | `agenteye-enterprise`                                         |
| **Repository access** | **Only select repositories** → `agenteye-enterprise/releases` |

### 2. 设置仓库权限

在 **Permissions → Repository permissions** 下，进行如下设置：

| 权限           | 访问级别      |
| ------------ | --------- |
| **Contents** | Read-only |
| **Packages** | Read-only |

其他所有权限可保持 **No access**。

> **注意：** 如果容器镜像（`ghcr.io/agenteye-enterprise/...`）作为组织级包而非仓库关联包发布，仅使用仓库范围的权限可能导致 Docker 登录失败。在这种情况下，请添加组织级权限：**Permissions → Organization permissions → Packages: Read-only**。

### 3. 各权限说明

| 权限                  | 用途                                                                                |
| ------------------- | --------------------------------------------------------------------------------- |
| Contents: Read-only | 从 `agenteye-enterprise/releases` 下载 `docker-compose.yml`、发布版二进制文件及 Python wheel 包 |
| Packages: Read-only | 从 `ghcr.io/agenteye-enterprise/` 拉取 Docker 镜像                                     |

### 4. 生成并复制令牌

点击 **Generate token** 并立即复制令牌值；该值仅显示一次。请将其存储至您的密钥管理器或环境变量中。

***

## 轮换令牌

定期轮换令牌可保持访问的可审计性，并在凭证泄露时将影响范围降至最低。令牌也可能随时过期或被撤销，因此轮换是保持认证有效的常规方式。轮换步骤如下：

1. 按照上述步骤生成新令牌。
2. 在您的环境变量或密钥管理器中更新 `AGENTEYE_TOKEN`。
3. 重新进行 Docker 认证：`echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin`
4. 在 GitHub → Settings → Developer settings → Personal access tokens 中撤销旧令牌，打开与令牌类型对应的 **Tokens (classic)** 或 **Fine-grained tokens** 子页面，将其删除。

***

## 验证令牌

在将令牌接入部署流程之前，请先确认其可正常使用，以便认证问题在此阶段暴露，而非在发布过程中出现。以下每条命令分别验证上述其中一个权限范围：

```bash theme={null}
# Packages scope - authenticate Docker against GHCR
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

# Contents scope - fetch a raw release file
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o /tmp/agenteye-compose-check.yml
```

`docker login` 成功即表示包权限范围有效；文件下载成功即表示内容权限范围有效。

***

## 故障排查

| 现象                            | 可能原因                                                   | 解决方法                                        |
| ----------------------------- | ------------------------------------------------------ | ------------------------------------------- |
| `docker login` 返回 401         | 令牌缺少 `Packages: Read-only`（细粒度）或 `read:packages`（经典）权限 | 添加包权限范围并重新生成令牌                              |
| `curl` 请求原始 GitHub URL 返回 404 | 令牌缺少 `Contents: Read-only` 或 `repo` 权限范围               | 添加内容权限范围并重新生成令牌                             |
| `gh release download` 返回 403  | 令牌未获授权访问 `agenteye-enterprise/releases`                | 确认该仓库已包含在细粒度令牌的仓库访问范围内，或改用带有 `repo` 范围的经典令牌 |
| 令牌被接受但找不到镜像                   | 细粒度令牌缺少组织级包权限                                          | 添加组织级 `Packages: Read-only` 权限              |

如遇访问问题，请联系 `support@exosphere.host`。